extra code in pp_concat, Take 2
[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
9965345d 135Sometimes instead of zeroing the allocated heap by using Newz() 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()
141macro, which has similar arguments as Zero():
142
143 Poison(dst, n, t)
144
f40a6c71 145=head2 Character Class Tests
146
147There are two types of character class tests that Perl implements: one
148type deals in C<char>s and are thus B<not> Unicode aware (and hence
149deprecated unless you B<know> you should use them) and the other type
150deal in C<UV>s and know about Unicode properties. In the following
151table, C<c> is a C<char>, and C<u> is a Unicode codepoint.
152
153 Instead Of: Use: But better use:
154
155 isalnum(c) isALNUM(c) isALNUM_uni(u)
156 isalpha(c) isALPHA(c) isALPHA_uni(u)
157 iscntrl(c) isCNTRL(c) isCNTRL_uni(u)
158 isdigit(c) isDIGIT(c) isDIGIT_uni(u)
159 isgraph(c) isGRAPH(c) isGRAPH_uni(u)
160 islower(c) isLOWER(c) isLOWER_uni(u)
161 isprint(c) isPRINT(c) isPRINT_uni(u)
162 ispunct(c) isPUNCT(c) isPUNCT_uni(u)
163 isspace(c) isSPACE(c) isSPACE_uni(u)
164 isupper(c) isUPPER(c) isUPPER_uni(u)
165 isxdigit(c) isXDIGIT(c) isXDIGIT_uni(u)
166
167 tolower(c) toLOWER(c) toLOWER_uni(u)
168 toupper(c) toUPPER(c) toUPPER_uni(u)
169
170=head2 F<stdlib.h> functions
171
172 Instead Of: Use:
173
174 atof(s) Atof(s)
175 atol(s) Atol(s)
56d22bd2 176 strtod(s, *p) Nothing. Just don't use it.
f40a6c71 177 strtol(s, *p, n) Strtol(s, *p, n)
178 strtoul(s, *p, n) Strtoul(s, *p, n)
179
53305cf1 180Notice also the C<grok_bin>, C<grok_hex>, and C<grok_oct> functions in
2826e23d 181F<numeric.c> for converting strings representing numbers in the respective
f40a6c71 182bases into C<NV>s.
183
184In theory C<Strtol> and C<Strtoul> may not be defined if the machine perl is
185built on doesn't actually have strtol and strtoul. But as those 2
186functions are part of the 1989 ANSI C spec we suspect you'll find them
187everywhere by now.
188
189 int rand() double Drand01()
190 srand(n) { seedDrand01((Rand_seed_t)n);
191 PL_srand_called = TRUE; }
56d22bd2 192
f40a6c71 193 exit(n) my_exit(n)
194 system(s) Don't. Look at pp_system or use my_popen
195
196 getenv(s) PerlEnv_getenv(s)
197 setenv(s, val) my_putenv(s, val)
198
199=head2 Miscellaneous functions
200
201You should not even B<want> to use F<setjmp.h> functions, but if you
202think you do, use the C<JMPENV> stack in F<scope.h> instead.
203
204For C<signal>/C<sigaction>, use C<rsignal(signo, handler)>.
205
206=head1 SEE ALSO
207
208C<perlapi>, C<perlapio>, C<perlguts>
209