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) 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 117Notice the different order of arguments to C<Copy> and C<Move> than used 118in C<memcpy> and C<memmove>. 119 120Most of the time, though, you'll want to be dealing with SVs internally 121instead 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 130Note also the existence of C<sv_catpvf> and C<sv_catpvfn>, combining 131concatenation with formatting. 132 133=head2 Character Class Tests 134 135There are two types of character class tests that Perl implements: one 136type deals in C<char>s and are thus B<not> Unicode aware (and hence 137deprecated unless you B<know> you should use them) and the other type 138deal in C<UV>s and know about Unicode properties. In the following 139table, 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 168Notice also the C<scan_bin>, C<scan_hex>, and C<scan_oct> functions in 169F<util.c> for converting strings representing numbers in the respective 170bases into C<NV>s. 171 172In theory C<Strtol> and C<Strtoul> may not be defined if the machine perl is 173built on doesn't actually have strtol and strtoul. But as those 2 174functions are part of the 1989 ANSI C spec we suspect you'll find them 175everywhere 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 189You should not even B<want> to use F<setjmp.h> functions, but if you 190think you do, use the C<JMPENV> stack in F<scope.h> instead. 191 192For C<signal>/C<sigaction>, use C<rsignal(signo, handler)>. 193 194=head1 SEE ALSO 195 196C<perlapi>, C<perlapio>, C<perlguts> 197 198