Integrate perlio:
[p5sagit/p5-mst-13.2.git] / pod / perlclib.pod
CommitLineData
f40a6c71 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
56d22bd2 14and who want to do things the Perl way; to tell them which functions
f40a6c71 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*>
56d22bd2 47types. Don't forget that with the new PerlIO layered I/O abstraction
f40a6c71 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:
56d22bd2 52
f40a6c71 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
702eb6d0 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 memset(dst, 0, n * sizeof(t)) Zero(dst, n, t)
109 memzero(dst, 0) Zero(dst, n, char)
110 free(p) Safefree(p)
f40a6c71 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
328bf373 132Note also the existence of C<sv_catpvf> and C<sv_vcatpvfn>, combining
f40a6c71 133concatenation with formatting.
134
135=head2 Character Class Tests
136
137There are two types of character class tests that Perl implements: one
138type deals in C<char>s and are thus B<not> Unicode aware (and hence
139deprecated unless you B<know> you should use them) and the other type
140deal in C<UV>s and know about Unicode properties. In the following
141table, C<c> is a C<char>, and C<u> is a Unicode codepoint.
142
143 Instead Of: Use: But better use:
144
145 isalnum(c) isALNUM(c) isALNUM_uni(u)
146 isalpha(c) isALPHA(c) isALPHA_uni(u)
147 iscntrl(c) isCNTRL(c) isCNTRL_uni(u)
148 isdigit(c) isDIGIT(c) isDIGIT_uni(u)
149 isgraph(c) isGRAPH(c) isGRAPH_uni(u)
150 islower(c) isLOWER(c) isLOWER_uni(u)
151 isprint(c) isPRINT(c) isPRINT_uni(u)
152 ispunct(c) isPUNCT(c) isPUNCT_uni(u)
153 isspace(c) isSPACE(c) isSPACE_uni(u)
154 isupper(c) isUPPER(c) isUPPER_uni(u)
155 isxdigit(c) isXDIGIT(c) isXDIGIT_uni(u)
156
157 tolower(c) toLOWER(c) toLOWER_uni(u)
158 toupper(c) toUPPER(c) toUPPER_uni(u)
159
160=head2 F<stdlib.h> functions
161
162 Instead Of: Use:
163
164 atof(s) Atof(s)
165 atol(s) Atol(s)
56d22bd2 166 strtod(s, *p) Nothing. Just don't use it.
f40a6c71 167 strtol(s, *p, n) Strtol(s, *p, n)
168 strtoul(s, *p, n) Strtoul(s, *p, n)
169
53305cf1 170Notice also the C<grok_bin>, C<grok_hex>, and C<grok_oct> functions in
2826e23d 171F<numeric.c> for converting strings representing numbers in the respective
f40a6c71 172bases into C<NV>s.
173
174In theory C<Strtol> and C<Strtoul> may not be defined if the machine perl is
175built on doesn't actually have strtol and strtoul. But as those 2
176functions are part of the 1989 ANSI C spec we suspect you'll find them
177everywhere by now.
178
179 int rand() double Drand01()
180 srand(n) { seedDrand01((Rand_seed_t)n);
181 PL_srand_called = TRUE; }
56d22bd2 182
f40a6c71 183 exit(n) my_exit(n)
184 system(s) Don't. Look at pp_system or use my_popen
185
186 getenv(s) PerlEnv_getenv(s)
187 setenv(s, val) my_putenv(s, val)
188
189=head2 Miscellaneous functions
190
191You should not even B<want> to use F<setjmp.h> functions, but if you
192think you do, use the C<JMPENV> stack in F<scope.h> instead.
193
194For C<signal>/C<sigaction>, use C<rsignal(signo, handler)>.
195
196=head1 SEE ALSO
197
198C<perlapi>, C<perlapio>, C<perlguts>
199