pod/perlclib.pod

   1 =head1 NAME
   2
   3 perlclib - Internal replacements for standard C library functions
   4
   5 =head1 DESCRIPTION
   6
   7 One thing Perl porters should note is that F<perl> doesn't tend to use that
   8 much of the C standard library internally; you'll see very little use of,
   9 for example, the F<ctype.h> functions in there. This is because Perl
  10 tends to reimplement or abstract standard library functions, so that we
  11 know exactly how they're going to operate.
  12
  13 This is a reference card for people who are familiar with the C library
  14 and who want to do things the Perl way; to tell them which functions
  15 they ought to use instead of the more normal C functions.
  16
  17 =head2 Conventions
  18
  19 In the following tables:
  20
  21 =over 3
  22
  23 =item C<t>
  24
  25 is a type.
  26
  27 =item C<p>
  28
  29 is a pointer.
  30
  31 =item C<n>
  32
  33 is a number.
  34
  35 =item C<s>
  36
  37 is a string.
  38
  39 =back
  40
  41 C<sv>, C<av>, C<hv>, etc. represent variables of their respective types.
  42
  43 =head2 File Operations
  44
  45 Instead of the F<stdio.h> functions, you should use the Perl abstraction
  46 layer. Instead of C<FILE*> types, you need to be handling C<PerlIO*>
  47 types.  Don't forget that with the new PerlIO layered I/O abstraction
  48 C<FILE*> types may not even be available. See also the C<perlapio>
  49 documentation for more information about the following functions:
  50
  51     Instead Of:                 Use:
  52
  53     stdin                       PerlIO_stdin()
  54     stdout                      PerlIO_stdout()
  55     stderr                      PerlIO_stderr()
  56
  57     fopen(fn, mode)             PerlIO_open(fn, mode)
  58     freopen(fn, mode, stream)   PerlIO_reopen(fn, mode, perlio) (Deprecated)
  59     fflush(stream)              PerlIO_flush(perlio)
  60     fclose(stream)              PerlIO_close(perlio)
  61
  62 =head2 File Input and Output
  63
  64     Instead Of:                 Use:
  65
  66     fprintf(stream, fmt, ...)   PerlIO_printf(perlio, fmt, ...)
  67
  68     [f]getc(stream)             PerlIO_getc(perlio)
  69     [f]putc(stream, n)          PerlIO_putc(perlio, n)
  70     ungetc(n, stream)           PerlIO_ungetc(perlio, n)
  71
  72 Note that the PerlIO equivalents of C<fread> and C<fwrite> are slightly
  73 different from their C library counterparts:
  74
  75     fread(p, size, n, stream)   PerlIO_read(perlio, buf, numbytes)
  76     fwrite(p, size, n, stream)  PerlIO_write(perlio, buf, numbytes)
  77
  78     fputs(s, stream)            PerlIO_puts(perlio, s)
  79
  80 There is no equivalent to C<fgets>; one should use C<sv_gets> instead:
  81
  82     fgets(s, n, stream)         sv_gets(sv, perlio, append)
  83
  84 =head2 File Positioning
  85
  86     Instead Of:                 Use:
  87
  88     feof(stream)                PerlIO_eof(perlio)
  89     fseek(stream, n, whence)    PerlIO_seek(perlio, n, whence)
  90     rewind(stream)              PerlIO_rewind(perlio)
  91
  92     fgetpos(stream, p)          PerlIO_getpos(perlio, sv)
  93     fsetpos(stream, p)          PerlIO_setpos(perlio, sv)
  94
  95     ferror(stream)              PerlIO_error(perlio)
  96     clearerr(stream)            PerlIO_clearerr(perlio)
  97
  98 =head2 Memory Management and String Handling
  99
 100     Instead Of:                 Use:
 101
 102     t* p = malloc(n)            New(id, p, n, t)
 103     t* p = calloc(n, s)         Newz(id, p, n, t)
 104     p = realloc(p, n)           Renew(p, n, t)
 105     memcpy(dst, src, n)         Copy(src, dst, n, t)
 106     memmove(dst, src, n)        Move(src, dst, n, t)
 107     memcpy/*(struct foo *)      StructCopy(src, dst, t)
 108     free(p)                     Safefree(p)
 109
 110     strdup(p)                   savepv(p)
 111     strndup(p, n)               savepvn(p, n) (Hey, strndup doesn't exist!)
 112
 113     strstr(big, little)         instr(big, little)
 114     strcmp(s1, s2)              strLE(s1, s2) / strEQ(s1, s2) / strGT(s1,s2)
 115     strncmp(s1, s2, n)          strnNE(s1, s2, n) / strnEQ(s1, s2, n)
 116
 117 Notice the different order of arguments to C<Copy> and C<Move> than used
 118 in C<memcpy> and C<memmove>.
 119
 120 Most of the time, though, you'll want to be dealing with SVs internally
 121 instead of raw C<char *> strings:
 122
 123     strlen(s)                   sv_len(sv)
 124     strcpy(dt, src)             sv_setpv(sv, s)
 125     strncpy(dt, src, n)         sv_setpvn(sv, s, n)
 126     strcat(dt, src)             sv_catpv(sv, s)
 127     strncat(dt, src)            sv_catpvn(sv, s)
 128     sprintf(s, fmt, ...)        sv_setpvf(sv, fmt, ...)
 129
 130 Note also the existence of C<sv_catpvf> and C<sv_catpvfn>, combining
 131 concatenation with formatting.
 132
 133 =head2 Character Class Tests
 134
 135 There are two types of character class tests that Perl implements: one
 136 type deals in C<char>s and are thus B<not> Unicode aware (and hence
 137 deprecated unless you B<know> you should use them) and the other type
 138 deal in C<UV>s and know about Unicode properties. In the following
 139 table, C<c> is a C<char>, and C<u> is a Unicode codepoint.
 140
 141     Instead Of:                 Use:            But better use:
 142
 143     isalnum(c)                  isALNUM(c)      isALNUM_uni(u)
 144     isalpha(c)                  isALPHA(c)      isALPHA_uni(u)
 145     iscntrl(c)                  isCNTRL(c)      isCNTRL_uni(u)
 146     isdigit(c)                  isDIGIT(c)      isDIGIT_uni(u)
 147     isgraph(c)                  isGRAPH(c)      isGRAPH_uni(u)
 148     islower(c)                  isLOWER(c)      isLOWER_uni(u)
 149     isprint(c)                  isPRINT(c)      isPRINT_uni(u)
 150     ispunct(c)                  isPUNCT(c)      isPUNCT_uni(u)
 151     isspace(c)                  isSPACE(c)      isSPACE_uni(u)
 152     isupper(c)                  isUPPER(c)      isUPPER_uni(u)
 153     isxdigit(c)                 isXDIGIT(c)     isXDIGIT_uni(u)
 154
 155     tolower(c)                  toLOWER(c)      toLOWER_uni(u)
 156     toupper(c)                  toUPPER(c)      toUPPER_uni(u)
 157
 158 =head2 F<stdlib.h> functions
 159
 160     Instead Of:                 Use:
 161
 162     atof(s)                     Atof(s)
 163     atol(s)                     Atol(s)
 164     strtod(s, *p)               Nothing.  Just don't use it.
 165     strtol(s, *p, n)            Strtol(s, *p, n)
 166     strtoul(s, *p, n)           Strtoul(s, *p, n)
 167
 168 Notice also the C<scan_bin>, C<scan_hex>, and C<scan_oct> functions in
 169 F<numeric.c> for converting strings representing numbers in the respective
 170 bases into C<NV>s.
 171
 172 In theory C<Strtol> and C<Strtoul> may not be defined if the machine perl is
 173 built on doesn't actually have strtol and strtoul. But as those 2
 174 functions are part of the 1989 ANSI C spec we suspect you'll find them
 175 everywhere by now.
 176
 177     int rand()                  double Drand01()
 178     srand(n)                    { seedDrand01((Rand_seed_t)n);
 179                                   PL_srand_called = TRUE; }
 180
 181     exit(n)                     my_exit(n)
 182     system(s)                   Don't. Look at pp_system or use my_popen
 183
 184     getenv(s)                   PerlEnv_getenv(s)
 185     setenv(s, val)              my_putenv(s, val)
 186
 187 =head2 Miscellaneous functions
 188
 189 You should not even B<want> to use F<setjmp.h> functions, but if you
 190 think you do, use the C<JMPENV> stack in F<scope.h> instead.
 191
 192 For C<signal>/C<sigaction>, use C<rsignal(signo, handler)>.
 193
 194 =head1 SEE ALSO
 195
 196 C<perlapi>, C<perlapio>, C<perlguts>
 197