This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
[perl #114248] Newxz? doc wrong in perlclib.pod
[perl5.git] / pod / perlclib.pod
CommitLineData
f40a6c71
SC
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
SC
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
SC
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
SC
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
JH
100 Instead Of: Use:
101
bbe42f07
DM
102 t* p = malloc(n) Newx(p, n, t)
103 t* p = calloc(n, s) Newxz(p, n, t)
702eb6d0
JH
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)
4d567a56 107 memcpy(dst, src, sizeof(t)) StructCopy(src, dst, t)
702eb6d0
JH
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
SC
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
SC
133concatenation with formatting.
134
9f653bb5 135Sometimes instead of zeroing the allocated heap by using Newxz() you
9965345d
JH
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()
ea787f3b 141macros, which have similar arguments to Zero():
9965345d 142
7e337ee0
JH
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)
9965345d 147
f40a6c71
SC
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)
4d567a56
VP
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)
f40a6c71 182
53305cf1 183Notice also the C<grok_bin>, C<grok_hex>, and C<grok_oct> functions in
2826e23d 184F<numeric.c> for converting strings representing numbers in the respective
f40a6c71
SC
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; }
56d22bd2 195
f40a6c71
SC
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
d974f73b 211L<perlapi>, L<perlapio>, L<perlguts>
f40a6c71 212