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