[Summary view] [Print] [Text view]

   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)                Newx(id, p, n, t)
 103      t* p = calloc(n, s)             Newxz(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      memset(dst, 0, n * sizeof(t))    Zero(dst, n, t)
 109      memzero(dst, 0)            Zero(dst, n, char)
 110      free(p)                         Safefree(p)
 111  
 112      strdup(p)                   savepv(p)
 113      strndup(p, n)               savepvn(p, n) (Hey, strndup doesn't exist!)
 114  
 115      strstr(big, little)         instr(big, little)
 116      strcmp(s1, s2)              strLE(s1, s2) / strEQ(s1, s2) / strGT(s1,s2)
 117      strncmp(s1, s2, n)          strnNE(s1, s2, n) / strnEQ(s1, s2, n)
 118  
 119  Notice the different order of arguments to C<Copy> and C<Move> than used
 120  in C<memcpy> and C<memmove>.
 121  
 122  Most of the time, though, you'll want to be dealing with SVs internally
 123  instead of raw C<char *> strings:
 124  
 125      strlen(s)                   sv_len(sv)
 126      strcpy(dt, src)             sv_setpv(sv, s)
 127      strncpy(dt, src, n)         sv_setpvn(sv, s, n)
 128      strcat(dt, src)             sv_catpv(sv, s)
 129      strncat(dt, src)            sv_catpvn(sv, s)
 130      sprintf(s, fmt, ...)        sv_setpvf(sv, fmt, ...)
 131  
 132  Note also the existence of C<sv_catpvf> and C<sv_vcatpvfn>, combining
 133  concatenation with formatting.
 134  
 135  Sometimes instead of zeroing the allocated heap by using Newxz() you
 136  should consider "poisoning" the data.  This means writing a bit
 137  pattern into it that should be illegal as pointers (and floating point
 138  numbers), and also hopefully surprising enough as integers, so that
 139  any code attempting to use the data without forethought will break
 140  sooner rather than later.  Poisoning can be done using the Poison()
 141  macros, which have similar arguments as Zero():
 142  
 143      PoisonWith(dst, n, t, b)    scribble memory with byte b
 144      PoisonNew(dst, n, t)        equal to PoisonWith(dst, n, t, 0xAB)
 145      PoisonFree(dst, n, t)       equal to PoisonWith(dst, n, t, 0xEF)
 146      Poison(dst, n, t)           equal to PoisonFree(dst, n, t)
 147  
 148  =head2 Character Class Tests
 149  
 150  There are two types of character class tests that Perl implements: one
 151  type deals in C<char>s and are thus B<not> Unicode aware (and hence
 152  deprecated unless you B<know> you should use them) and the other type
 153  deal in C<UV>s and know about Unicode properties. In the following
 154  table, C<c> is a C<char>, and C<u> is a Unicode codepoint.
 155  
 156      Instead Of:                 Use:            But better use:
 157  
 158      isalnum(c)                  isALNUM(c)      isALNUM_uni(u)
 159      isalpha(c)                  isALPHA(c)      isALPHA_uni(u)
 160      iscntrl(c)                  isCNTRL(c)      isCNTRL_uni(u)
 161      isdigit(c)                  isDIGIT(c)      isDIGIT_uni(u)
 162      isgraph(c)                  isGRAPH(c)      isGRAPH_uni(u)
 163      islower(c)                  isLOWER(c)      isLOWER_uni(u)
 164      isprint(c)                  isPRINT(c)      isPRINT_uni(u)
 165      ispunct(c)                  isPUNCT(c)      isPUNCT_uni(u)
 166      isspace(c)                  isSPACE(c)      isSPACE_uni(u)
 167      isupper(c)                  isUPPER(c)      isUPPER_uni(u)
 168      isxdigit(c)                 isXDIGIT(c)     isXDIGIT_uni(u)
 169  
 170      tolower(c)                  toLOWER(c)      toLOWER_uni(u)
 171      toupper(c)                  toUPPER(c)      toUPPER_uni(u)
 172  
 173  =head2 F<stdlib.h> functions
 174  
 175      Instead Of:                 Use: 
 176  
 177      atof(s)                     Atof(s)
 178      atol(s)                     Atol(s)
 179      strtod(s, *p)               Nothing.  Just don't use it.
 180      strtol(s, *p, n)            Strtol(s, *p, n)
 181      strtoul(s, *p, n)           Strtoul(s, *p, n)
 182  
 183  Notice also the C<grok_bin>, C<grok_hex>, and C<grok_oct> functions in
 184  F<numeric.c> for converting strings representing numbers in the respective
 185  bases into C<NV>s.
 186  
 187  In theory C<Strtol> and C<Strtoul> may not be defined if the machine perl is
 188  built on doesn't actually have strtol and strtoul. But as those 2
 189  functions are part of the 1989 ANSI C spec we suspect you'll find them
 190  everywhere by now.
 191  
 192      int rand()                  double Drand01()
 193      srand(n)                    { seedDrand01((Rand_seed_t)n); 
 194                                    PL_srand_called = TRUE; }
 195  
 196      exit(n)                     my_exit(n)
 197      system(s)                   Don't. Look at pp_system or use my_popen
 198  
 199      getenv(s)                   PerlEnv_getenv(s)
 200      setenv(s, val)              my_putenv(s, val)
 201  
 202  =head2 Miscellaneous functions
 203  
 204  You should not even B<want> to use F<setjmp.h> functions, but if you
 205  think you do, use the C<JMPENV> stack in F<scope.h> instead.
 206  
 207  For C<signal>/C<sigaction>, use C<rsignal(signo, handler)>.
 208  
 209  =head1 SEE ALSO
 210  
 211  C<perlapi>, C<perlapio>, C<perlguts>
 212