1=head1 NAME 2 3perlclib - Internal replacements for standard C library functions 4 5=head1 DESCRIPTION 6 7One thing Perl porters should note is that F<perl> doesn't tend to use that 8much of the C standard library internally; you'll see very little use of, 9for example, the F<ctype.h> functions in there. This is because Perl 10tends to reimplement or abstract standard library functions, so that we 11know exactly how they're going to operate. 12 13This is a reference card for people who are familiar with the C library 14and who want to do things the Perl way; to tell them which functions 15they ought to use instead of the more normal C functions. 16 17=head2 Conventions 18 19In the following tables: 20 21=over 3 22 23=item C<t> 24 25is a type. 26 27=item C<p> 28 29is a pointer. 30 31=item C<n> 32 33is a number. 34 35=item C<s> 36 37is a string. 38 39=back 40 41C<sv>, C<av>, C<hv>, etc. represent variables of their respective types. 42 43=head2 File Operations 44 45Instead of the F<stdio.h> functions, you should use the Perl abstraction 46layer. Instead of C<FILE*> types, you need to be handling C<PerlIO*> 47types. Don't forget that with the new PerlIO layered I/O abstraction 48C<FILE*> types may not even be available. See also the C<perlapio> 49documentation 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 72Note that the PerlIO equivalents of C<fread> and C<fwrite> are slightly 73different 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 80There 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 119Notice the different order of arguments to C<Copy> and C<Move> than used 120in C<memcpy> and C<memmove>. 121 122Most of the time, though, you'll want to be dealing with SVs internally 123instead 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 132Note also the existence of C<sv_catpvf> and C<sv_vcatpvfn>, combining 133concatenation with formatting. 134 135Sometimes instead of zeroing the allocated heap by using Newxz() you 136should consider "poisoning" the data. This means writing a bit 137pattern into it that should be illegal as pointers (and floating point 138numbers), and also hopefully surprising enough as integers, so that 139any code attempting to use the data without forethought will break 140sooner rather than later. Poisoning can be done using the Poison() 141macros, 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 150There are two types of character class tests that Perl implements: one 151type deals in C<char>s and are thus B<not> Unicode aware (and hence 152deprecated unless you B<know> you should use them) and the other type 153deal in C<UV>s and know about Unicode properties. In the following 154table, 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 183Notice also the C<grok_bin>, C<grok_hex>, and C<grok_oct> functions in 184F<numeric.c> for converting strings representing numbers in the respective 185bases into C<NV>s. 186 187In theory C<Strtol> and C<Strtoul> may not be defined if the machine perl is 188built on doesn't actually have strtol and strtoul. But as those 2 189functions are part of the 1989 ANSI C spec we suspect you'll find them 190everywhere 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 204You should not even B<want> to use F<setjmp.h> functions, but if you 205think you do, use the C<JMPENV> stack in F<scope.h> instead. 206 207For C<signal>/C<sigaction>, use C<rsignal(signo, handler)>. 208 209=head1 SEE ALSO 210 211C<perlapi>, C<perlapio>, C<perlguts> 212 213