perlclib.pod

MSYS在windows下模拟了一个类unix的终端

=head1 NAME

perlclib - Internal replacements for standard C library functions

=head1 DESCRIPTION

One thing Perl porters should note is that F<perl> doesn't tend to use that
much of the C standard library internally; you'll see very little use of, 
for example, the F<ctype.h> functions in there. This is because Perl
tends to reimplement or abstract standard library functions, so that we
know exactly how they're going to operate.

This is a reference card for people who are familiar with the C library
and who want to do things the Perl way; to tell them which functions
they ought to use instead of the more normal C functions. 

=head2 Conventions

In the following tables:

=over 3

=item C<t>

is a type.

=item C<p>

is a pointer.

=item C<n>

is a number.

=item C<s>

is a string.

=back

C<sv>, C<av>, C<hv>, etc. represent variables of their respective types.

=head2 File Operations

Instead of the F<stdio.h> functions, you should use the Perl abstraction
layer. Instead of C<FILE*> types, you need to be handling C<PerlIO*>
types.  Don't forget that with the new PerlIO layered I/O abstraction 
C<FILE*> types may not even be available. See also the C<perlapio>
documentation for more information about the following functions:

    Instead Of:                 Use:

    stdin                       PerlIO_stdin()
    stdout                      PerlIO_stdout()
    stderr                      PerlIO_stderr()

    fopen(fn, mode)             PerlIO_open(fn, mode)
    freopen(fn, mode, stream)   PerlIO_reopen(fn, mode, perlio) (Deprecated)
    fflush(stream)              PerlIO_flush(perlio)
    fclose(stream)              PerlIO_close(perlio)

=head2 File Input and Output

    Instead Of:                 Use:

    fprintf(stream, fmt, ...)   PerlIO_printf(perlio, fmt, ...)

    [f]getc(stream)             PerlIO_getc(perlio)
    [f]putc(stream, n)          PerlIO_putc(perlio, n)
    ungetc(n, stream)           PerlIO_ungetc(perlio, n)

Note that the PerlIO equivalents of C<fread> and C<fwrite> are slightly
different from their C library counterparts:

    fread(p, size, n, stream)   PerlIO_read(perlio, buf, numbytes)
    fwrite(p, size, n, stream)  PerlIO_write(perlio, buf, numbytes)

    fputs(s, stream)            PerlIO_puts(perlio, s)

There is no equivalent to C<fgets>; one should use C<sv_gets> instead:

    fgets(s, n, stream)         sv_gets(sv, perlio, append)

=head2 File Positioning

    Instead Of:                 Use:

    feof(stream)                PerlIO_eof(perlio)
    fseek(stream, n, whence)    PerlIO_seek(perlio, n, whence)
    rewind(stream)              PerlIO_rewind(perlio)

    fgetpos(stream, p)          PerlIO_getpos(perlio, sv)
    fsetpos(stream, p)          PerlIO_setpos(perlio, sv)

    ferror(stream)              PerlIO_error(perlio)
    clearerr(stream)            PerlIO_clearerr(perlio)

=head2 Memory Management and String Handling

    Instead Of:                 Use:

    t* p = malloc(n)            New(id, p, n, t)
    t* p = calloc(n, s)         Newz(id, p, n, t)
    p = realloc(p, n)           Renew(p, n, t)
    memcpy(dst, src, n)         Copy(src, dst, n, t)
    memmove(dst, src, n)        Move(src, dst, n, t)
    memcpy/*(struct foo *)      StructCopy(src, dst, t)
    free(p)                     Safefree(p)

    strdup(p)                   savepv(p)
    strndup(p, n)               savepvn(p, n) (Hey, strndup doesn't exist!)

    strstr(big, little)         instr(big, little)
    strcmp(s1, s2)              strLE(s1, s2) / strEQ(s1, s2) / strGT(s1,s2)
    strncmp(s1, s2, n)          strnNE(s1, s2, n) / strnEQ(s1, s2, n)

Notice the different order of arguments to C<Copy> and C<Move> than used
in C<memcpy> and C<memmove>.

Most of the time, though, you'll want to be dealing with SVs internally
instead of raw C<char *> strings:

    strlen(s)                   sv_len(sv)
    strcpy(dt, src)             sv_setpv(sv, s)
    strncpy(dt, src, n)         sv_setpvn(sv, s, n)
    strcat(dt, src)             sv_catpv(sv, s)
    strncat(dt, src)            sv_catpvn(sv, s)
    sprintf(s, fmt, ...)        sv_setpvf(sv, fmt, ...)

Note also the existence of C<sv_catpvf> and C<sv_catpvfn>, combining
concatenation with formatting.

=head2 Character Class Tests

There are two types of character class tests that Perl implements: one
type deals in C<char>s and are thus B<not> Unicode aware (and hence
deprecated unless you B<know> you should use them) and the other type
deal in C<UV>s and know about Unicode properties. In the following
table, C<c> is a C<char>, and C<u> is a Unicode codepoint.

    Instead Of:                 Use:            But better use:

    isalnum(c)                  isALNUM(c)      isALNUM_uni(u)
    isalpha(c)                  isALPHA(c)      isALPHA_uni(u)
    iscntrl(c)                  isCNTRL(c)      isCNTRL_uni(u)
    isdigit(c)                  isDIGIT(c)      isDIGIT_uni(u)
    isgraph(c)                  isGRAPH(c)      isGRAPH_uni(u)
    islower(c)                  isLOWER(c)      isLOWER_uni(u)
    isprint(c)                  isPRINT(c)      isPRINT_uni(u)
    ispunct(c)                  isPUNCT(c)      isPUNCT_uni(u)
    isspace(c)                  isSPACE(c)      isSPACE_uni(u)
    isupper(c)                  isUPPER(c)      isUPPER_uni(u)
    isxdigit(c)                 isXDIGIT(c)     isXDIGIT_uni(u)

    tolower(c)                  toLOWER(c)      toLOWER_uni(u)
    toupper(c)                  toUPPER(c)      toUPPER_uni(u)

=head2 F<stdlib.h> functions

    Instead Of:                 Use: 

    atof(s)                     Atof(s)
    atol(s)                     Atol(s)
    strtod(s, *p)               Nothing.  Just don't use it.
    strtol(s, *p, n)            Strtol(s, *p, n)
    strtoul(s, *p, n)           Strtoul(s, *p, n)

Notice also the C<scan_bin>, C<scan_hex>, and C<scan_oct> functions in
F<util.c> for converting strings representing numbers in the respective
bases into C<NV>s.

In theory C<Strtol> and C<Strtoul> may not be defined if the machine perl is
built on doesn't actually have strtol and strtoul. But as those 2
functions are part of the 1989 ANSI C spec we suspect you'll find them
everywhere by now.

    int rand()                  double Drand01()
    srand(n)                    { seedDrand01((Rand_seed_t)n); 
                                  PL_srand_called = TRUE; }

    exit(n)                     my_exit(n)
    system(s)                   Don't. Look at pp_system or use my_popen

    getenv(s)                   PerlEnv_getenv(s)
    setenv(s, val)              my_putenv(s, val)

=head2 Miscellaneous functions

You should not even B<want> to use F<setjmp.h> functions, but if you
think you do, use the C<JMPENV> stack in F<scope.h> instead.

For C<signal>/C<sigaction>, use C<rsignal(signo, handler)>.

=head1 SEE ALSO

C<perlapi>, C<perlapio>, C<perlguts>