Commit | Line | Data |
---|---|---|
a0d0e21e LW |
1 | =head1 NAME |
2 | ||
3 | perlfunc - Perl builtin functions | |
4 | ||
5 | =head1 DESCRIPTION | |
6 | ||
7 | The functions in this section can serve as terms in an expression. | |
8 | They fall into two major categories: list operators and named unary | |
9 | operators. These differ in their precedence relationship with a | |
10 | following comma. (See the precedence table in L<perlop>.) List | |
11 | operators take more than one argument, while unary operators can never | |
12 | take more than one argument. Thus, a comma terminates the argument of | |
13 | a unary operator, but merely separates the arguments of a list | |
14 | operator. A unary operator generally provides a scalar context to its | |
2b5ab1e7 | 15 | argument, while a list operator may provide either scalar or list |
a0d0e21e | 16 | contexts for its arguments. If it does both, the scalar arguments will |
5f05dabc | 17 | be first, and the list argument will follow. (Note that there can ever |
0f31cffe | 18 | be only one such list argument.) For instance, splice() has three scalar |
2b5ab1e7 TC |
19 | arguments followed by a list, whereas gethostbyname() has four scalar |
20 | arguments. | |
a0d0e21e LW |
21 | |
22 | In the syntax descriptions that follow, list operators that expect a | |
23 | list (and provide list context for the elements of the list) are shown | |
24 | with LIST as an argument. Such a list may consist of any combination | |
25 | of scalar arguments or list values; the list values will be included | |
26 | in the list as if each individual element were interpolated at that | |
27 | point in the list, forming a longer single-dimensional list value. | |
28 | Elements of the LIST should be separated by commas. | |
29 | ||
30 | Any function in the list below may be used either with or without | |
31 | parentheses around its arguments. (The syntax descriptions omit the | |
5f05dabc | 32 | parentheses.) If you use the parentheses, the simple (but occasionally |
19799a22 | 33 | surprising) rule is this: It I<looks> like a function, therefore it I<is> a |
a0d0e21e LW |
34 | function, and precedence doesn't matter. Otherwise it's a list |
35 | operator or unary operator, and precedence does matter. And whitespace | |
36 | between the function and left parenthesis doesn't count--so you need to | |
37 | be careful sometimes: | |
38 | ||
68dc0745 | 39 | print 1+2+4; # Prints 7. |
40 | print(1+2) + 4; # Prints 3. | |
41 | print (1+2)+4; # Also prints 3! | |
42 | print +(1+2)+4; # Prints 7. | |
43 | print ((1+2)+4); # Prints 7. | |
a0d0e21e LW |
44 | |
45 | If you run Perl with the B<-w> switch it can warn you about this. For | |
46 | example, the third line above produces: | |
47 | ||
48 | print (...) interpreted as function at - line 1. | |
49 | Useless use of integer addition in void context at - line 1. | |
50 | ||
2b5ab1e7 TC |
51 | A few functions take no arguments at all, and therefore work as neither |
52 | unary nor list operators. These include such functions as C<time> | |
53 | and C<endpwent>. For example, C<time+86_400> always means | |
54 | C<time() + 86_400>. | |
55 | ||
a0d0e21e | 56 | For functions that can be used in either a scalar or list context, |
54310121 | 57 | nonabortive failure is generally indicated in a scalar context by |
a0d0e21e LW |
58 | returning the undefined value, and in a list context by returning the |
59 | null list. | |
60 | ||
5a964f20 TC |
61 | Remember the following important rule: There is B<no rule> that relates |
62 | the behavior of an expression in list context to its behavior in scalar | |
63 | context, or vice versa. It might do two totally different things. | |
a0d0e21e | 64 | Each operator and function decides which sort of value it would be most |
2b5ab1e7 | 65 | appropriate to return in scalar context. Some operators return the |
5a964f20 | 66 | length of the list that would have been returned in list context. Some |
a0d0e21e LW |
67 | operators return the first value in the list. Some operators return the |
68 | last value in the list. Some operators return a count of successful | |
69 | operations. In general, they do what you want, unless you want | |
70 | consistency. | |
71 | ||
d1be9408 | 72 | A named array in scalar context is quite different from what would at |
5a964f20 TC |
73 | first glance appear to be a list in scalar context. You can't get a list |
74 | like C<(1,2,3)> into being in scalar context, because the compiler knows | |
75 | the context at compile time. It would generate the scalar comma operator | |
76 | there, not the list construction version of the comma. That means it | |
77 | was never a list to start with. | |
78 | ||
79 | In general, functions in Perl that serve as wrappers for system calls | |
f86cebdf | 80 | of the same name (like chown(2), fork(2), closedir(2), etc.) all return |
5a964f20 TC |
81 | true when they succeed and C<undef> otherwise, as is usually mentioned |
82 | in the descriptions below. This is different from the C interfaces, | |
19799a22 GS |
83 | which return C<-1> on failure. Exceptions to this rule are C<wait>, |
84 | C<waitpid>, and C<syscall>. System calls also set the special C<$!> | |
5a964f20 TC |
85 | variable on failure. Other functions do not, except accidentally. |
86 | ||
cb1a09d0 AD |
87 | =head2 Perl Functions by Category |
88 | ||
89 | Here are Perl's functions (including things that look like | |
5a964f20 | 90 | functions, like some keywords and named operators) |
cb1a09d0 AD |
91 | arranged by category. Some functions appear in more |
92 | than one place. | |
93 | ||
13a2d996 | 94 | =over 4 |
cb1a09d0 AD |
95 | |
96 | =item Functions for SCALARs or strings | |
97 | ||
22fae026 | 98 | C<chomp>, C<chop>, C<chr>, C<crypt>, C<hex>, C<index>, C<lc>, C<lcfirst>, |
945c54fd JH |
99 | C<length>, C<oct>, C<ord>, C<pack>, C<q/STRING/>, C<qq/STRING/>, C<reverse>, |
100 | C<rindex>, C<sprintf>, C<substr>, C<tr///>, C<uc>, C<ucfirst>, C<y///> | |
cb1a09d0 AD |
101 | |
102 | =item Regular expressions and pattern matching | |
103 | ||
ab4f32c2 | 104 | C<m//>, C<pos>, C<quotemeta>, C<s///>, C<split>, C<study>, C<qr//> |
cb1a09d0 AD |
105 | |
106 | =item Numeric functions | |
107 | ||
22fae026 TM |
108 | C<abs>, C<atan2>, C<cos>, C<exp>, C<hex>, C<int>, C<log>, C<oct>, C<rand>, |
109 | C<sin>, C<sqrt>, C<srand> | |
cb1a09d0 AD |
110 | |
111 | =item Functions for real @ARRAYs | |
112 | ||
22fae026 | 113 | C<pop>, C<push>, C<shift>, C<splice>, C<unshift> |
cb1a09d0 AD |
114 | |
115 | =item Functions for list data | |
116 | ||
ab4f32c2 | 117 | C<grep>, C<join>, C<map>, C<qw/STRING/>, C<reverse>, C<sort>, C<unpack> |
cb1a09d0 AD |
118 | |
119 | =item Functions for real %HASHes | |
120 | ||
22fae026 | 121 | C<delete>, C<each>, C<exists>, C<keys>, C<values> |
cb1a09d0 AD |
122 | |
123 | =item Input and output functions | |
124 | ||
22fae026 TM |
125 | C<binmode>, C<close>, C<closedir>, C<dbmclose>, C<dbmopen>, C<die>, C<eof>, |
126 | C<fileno>, C<flock>, C<format>, C<getc>, C<print>, C<printf>, C<read>, | |
127 | C<readdir>, C<rewinddir>, C<seek>, C<seekdir>, C<select>, C<syscall>, | |
128 | C<sysread>, C<sysseek>, C<syswrite>, C<tell>, C<telldir>, C<truncate>, | |
129 | C<warn>, C<write> | |
cb1a09d0 AD |
130 | |
131 | =item Functions for fixed length data or records | |
132 | ||
22fae026 | 133 | C<pack>, C<read>, C<syscall>, C<sysread>, C<syswrite>, C<unpack>, C<vec> |
cb1a09d0 AD |
134 | |
135 | =item Functions for filehandles, files, or directories | |
136 | ||
22fae026 | 137 | C<-I<X>>, C<chdir>, C<chmod>, C<chown>, C<chroot>, C<fcntl>, C<glob>, |
5ff3f7a4 | 138 | C<ioctl>, C<link>, C<lstat>, C<mkdir>, C<open>, C<opendir>, |
1e278fd9 JH |
139 | C<readlink>, C<rename>, C<rmdir>, C<stat>, C<symlink>, C<sysopen>, |
140 | C<umask>, C<unlink>, C<utime> | |
cb1a09d0 AD |
141 | |
142 | =item Keywords related to the control flow of your perl program | |
143 | ||
98293880 JH |
144 | C<caller>, C<continue>, C<die>, C<do>, C<dump>, C<eval>, C<exit>, |
145 | C<goto>, C<last>, C<next>, C<redo>, C<return>, C<sub>, C<wantarray> | |
cb1a09d0 | 146 | |
54310121 | 147 | =item Keywords related to scoping |
cb1a09d0 | 148 | |
4375e838 | 149 | C<caller>, C<import>, C<local>, C<my>, C<our>, C<package>, C<use> |
cb1a09d0 AD |
150 | |
151 | =item Miscellaneous functions | |
152 | ||
4375e838 | 153 | C<defined>, C<dump>, C<eval>, C<formline>, C<local>, C<my>, C<our>, C<reset>, |
22fae026 | 154 | C<scalar>, C<undef>, C<wantarray> |
cb1a09d0 AD |
155 | |
156 | =item Functions for processes and process groups | |
157 | ||
22fae026 | 158 | C<alarm>, C<exec>, C<fork>, C<getpgrp>, C<getppid>, C<getpriority>, C<kill>, |
ab4f32c2 | 159 | C<pipe>, C<qx/STRING/>, C<setpgrp>, C<setpriority>, C<sleep>, C<system>, |
22fae026 | 160 | C<times>, C<wait>, C<waitpid> |
cb1a09d0 AD |
161 | |
162 | =item Keywords related to perl modules | |
163 | ||
22fae026 | 164 | C<do>, C<import>, C<no>, C<package>, C<require>, C<use> |
cb1a09d0 AD |
165 | |
166 | =item Keywords related to classes and object-orientedness | |
167 | ||
22fae026 TM |
168 | C<bless>, C<dbmclose>, C<dbmopen>, C<package>, C<ref>, C<tie>, C<tied>, |
169 | C<untie>, C<use> | |
cb1a09d0 AD |
170 | |
171 | =item Low-level socket functions | |
172 | ||
22fae026 TM |
173 | C<accept>, C<bind>, C<connect>, C<getpeername>, C<getsockname>, |
174 | C<getsockopt>, C<listen>, C<recv>, C<send>, C<setsockopt>, C<shutdown>, | |
737dd4b4 | 175 | C<socket>, C<socketpair> |
cb1a09d0 AD |
176 | |
177 | =item System V interprocess communication functions | |
178 | ||
22fae026 TM |
179 | C<msgctl>, C<msgget>, C<msgrcv>, C<msgsnd>, C<semctl>, C<semget>, C<semop>, |
180 | C<shmctl>, C<shmget>, C<shmread>, C<shmwrite> | |
cb1a09d0 AD |
181 | |
182 | =item Fetching user and group info | |
183 | ||
22fae026 TM |
184 | C<endgrent>, C<endhostent>, C<endnetent>, C<endpwent>, C<getgrent>, |
185 | C<getgrgid>, C<getgrnam>, C<getlogin>, C<getpwent>, C<getpwnam>, | |
186 | C<getpwuid>, C<setgrent>, C<setpwent> | |
cb1a09d0 AD |
187 | |
188 | =item Fetching network info | |
189 | ||
22fae026 TM |
190 | C<endprotoent>, C<endservent>, C<gethostbyaddr>, C<gethostbyname>, |
191 | C<gethostent>, C<getnetbyaddr>, C<getnetbyname>, C<getnetent>, | |
192 | C<getprotobyname>, C<getprotobynumber>, C<getprotoent>, | |
193 | C<getservbyname>, C<getservbyport>, C<getservent>, C<sethostent>, | |
194 | C<setnetent>, C<setprotoent>, C<setservent> | |
cb1a09d0 AD |
195 | |
196 | =item Time-related functions | |
197 | ||
22fae026 | 198 | C<gmtime>, C<localtime>, C<time>, C<times> |
cb1a09d0 | 199 | |
37798a01 | 200 | =item Functions new in perl5 |
201 | ||
22fae026 | 202 | C<abs>, C<bless>, C<chomp>, C<chr>, C<exists>, C<formline>, C<glob>, |
b76cc8ba | 203 | C<import>, C<lc>, C<lcfirst>, C<map>, C<my>, C<no>, C<our>, C<prototype>, |
4375e838 | 204 | C<qx>, C<qw>, C<readline>, C<readpipe>, C<ref>, C<sub*>, C<sysopen>, C<tie>, |
22fae026 | 205 | C<tied>, C<uc>, C<ucfirst>, C<untie>, C<use> |
37798a01 | 206 | |
207 | * - C<sub> was a keyword in perl4, but in perl5 it is an | |
5a964f20 | 208 | operator, which can be used in expressions. |
37798a01 | 209 | |
210 | =item Functions obsoleted in perl5 | |
211 | ||
22fae026 | 212 | C<dbmclose>, C<dbmopen> |
37798a01 | 213 | |
cb1a09d0 AD |
214 | =back |
215 | ||
60f9f73c JH |
216 | =head2 Portability |
217 | ||
2b5ab1e7 TC |
218 | Perl was born in Unix and can therefore access all common Unix |
219 | system calls. In non-Unix environments, the functionality of some | |
220 | Unix system calls may not be available, or details of the available | |
221 | functionality may differ slightly. The Perl functions affected | |
60f9f73c JH |
222 | by this are: |
223 | ||
224 | C<-X>, C<binmode>, C<chmod>, C<chown>, C<chroot>, C<crypt>, | |
225 | C<dbmclose>, C<dbmopen>, C<dump>, C<endgrent>, C<endhostent>, | |
226 | C<endnetent>, C<endprotoent>, C<endpwent>, C<endservent>, C<exec>, | |
227 | C<fcntl>, C<flock>, C<fork>, C<getgrent>, C<getgrgid>, C<gethostent>, | |
228 | C<getlogin>, C<getnetbyaddr>, C<getnetbyname>, C<getnetent>, | |
229 | C<getppid>, C<getprgp>, C<getpriority>, C<getprotobynumber>, | |
230 | C<getprotoent>, C<getpwent>, C<getpwnam>, C<getpwuid>, | |
231 | C<getservbyport>, C<getservent>, C<getsockopt>, C<glob>, C<ioctl>, | |
232 | C<kill>, C<link>, C<lstat>, C<msgctl>, C<msgget>, C<msgrcv>, | |
2b5ab1e7 | 233 | C<msgsnd>, C<open>, C<pipe>, C<readlink>, C<rename>, C<select>, C<semctl>, |
60f9f73c JH |
234 | C<semget>, C<semop>, C<setgrent>, C<sethostent>, C<setnetent>, |
235 | C<setpgrp>, C<setpriority>, C<setprotoent>, C<setpwent>, | |
236 | C<setservent>, C<setsockopt>, C<shmctl>, C<shmget>, C<shmread>, | |
737dd4b4 | 237 | C<shmwrite>, C<socket>, C<socketpair>, |
80cbd5ad JH |
238 | C<stat>, C<symlink>, C<syscall>, C<sysopen>, C<system>, |
239 | C<times>, C<truncate>, C<umask>, C<unlink>, | |
2b5ab1e7 | 240 | C<utime>, C<wait>, C<waitpid> |
60f9f73c JH |
241 | |
242 | For more information about the portability of these functions, see | |
243 | L<perlport> and other available platform-specific documentation. | |
244 | ||
cb1a09d0 AD |
245 | =head2 Alphabetical Listing of Perl Functions |
246 | ||
a0d0e21e LW |
247 | =over 8 |
248 | ||
22fae026 | 249 | =item I<-X> FILEHANDLE |
a0d0e21e | 250 | |
22fae026 | 251 | =item I<-X> EXPR |
a0d0e21e | 252 | |
22fae026 | 253 | =item I<-X> |
a0d0e21e LW |
254 | |
255 | A file test, where X is one of the letters listed below. This unary | |
256 | operator takes one argument, either a filename or a filehandle, and | |
257 | tests the associated file to see if something is true about it. If the | |
7660c0ab | 258 | argument is omitted, tests C<$_>, except for C<-t>, which tests STDIN. |
19799a22 | 259 | Unless otherwise documented, it returns C<1> for true and C<''> for false, or |
a0d0e21e LW |
260 | the undefined value if the file doesn't exist. Despite the funny |
261 | names, precedence is the same as any other named unary operator, and | |
262 | the argument may be parenthesized like any other unary operator. The | |
263 | operator may be any of: | |
7e778d91 IZ |
264 | X<-r>X<-w>X<-x>X<-o>X<-R>X<-W>X<-X>X<-O>X<-e>X<-z>X<-s>X<-f>X<-d>X<-l>X<-p> |
265 | X<-S>X<-b>X<-c>X<-t>X<-u>X<-g>X<-k>X<-T>X<-B>X<-M>X<-A>X<-C> | |
a0d0e21e LW |
266 | |
267 | -r File is readable by effective uid/gid. | |
268 | -w File is writable by effective uid/gid. | |
269 | -x File is executable by effective uid/gid. | |
270 | -o File is owned by effective uid. | |
271 | ||
272 | -R File is readable by real uid/gid. | |
273 | -W File is writable by real uid/gid. | |
274 | -X File is executable by real uid/gid. | |
275 | -O File is owned by real uid. | |
276 | ||
277 | -e File exists. | |
8e7e0aa8 MJD |
278 | -z File has zero size (is empty). |
279 | -s File has nonzero size (returns size in bytes). | |
a0d0e21e LW |
280 | |
281 | -f File is a plain file. | |
282 | -d File is a directory. | |
283 | -l File is a symbolic link. | |
9c4d0f16 | 284 | -p File is a named pipe (FIFO), or Filehandle is a pipe. |
a0d0e21e LW |
285 | -S File is a socket. |
286 | -b File is a block special file. | |
287 | -c File is a character special file. | |
288 | -t Filehandle is opened to a tty. | |
289 | ||
290 | -u File has setuid bit set. | |
291 | -g File has setgid bit set. | |
292 | -k File has sticky bit set. | |
293 | ||
121910a4 | 294 | -T File is an ASCII text file (heuristic guess). |
2cdbc966 | 295 | -B File is a "binary" file (opposite of -T). |
a0d0e21e | 296 | |
95a3fe12 | 297 | -M Script start time minus file modification time, in days. |
a0d0e21e | 298 | -A Same for access time. |
95a3fe12 | 299 | -C Same for inode change time (Unix, may differ for other platforms) |
a0d0e21e | 300 | |
a0d0e21e LW |
301 | Example: |
302 | ||
303 | while (<>) { | |
5b3eff12 | 304 | chomp; |
a0d0e21e | 305 | next unless -f $_; # ignore specials |
5a964f20 | 306 | #... |
a0d0e21e LW |
307 | } |
308 | ||
5ff3f7a4 GS |
309 | The interpretation of the file permission operators C<-r>, C<-R>, |
310 | C<-w>, C<-W>, C<-x>, and C<-X> is by default based solely on the mode | |
311 | of the file and the uids and gids of the user. There may be other | |
312 | reasons you can't actually read, write, or execute the file. Such | |
313 | reasons may be for example network filesystem access controls, ACLs | |
314 | (access control lists), read-only filesystems, and unrecognized | |
315 | executable formats. | |
316 | ||
2b5ab1e7 TC |
317 | Also note that, for the superuser on the local filesystems, the C<-r>, |
318 | C<-R>, C<-w>, and C<-W> tests always return 1, and C<-x> and C<-X> return 1 | |
5ff3f7a4 GS |
319 | if any execute bit is set in the mode. Scripts run by the superuser |
320 | may thus need to do a stat() to determine the actual mode of the file, | |
2b5ab1e7 | 321 | or temporarily set their effective uid to something else. |
5ff3f7a4 GS |
322 | |
323 | If you are using ACLs, there is a pragma called C<filetest> that may | |
324 | produce more accurate results than the bare stat() mode bits. | |
5ff3f7a4 GS |
325 | When under the C<use filetest 'access'> the above-mentioned filetests |
326 | will test whether the permission can (not) be granted using the | |
468541a8 | 327 | access() family of system calls. Also note that the C<-x> and C<-X> may |
5ff3f7a4 GS |
328 | under this pragma return true even if there are no execute permission |
329 | bits set (nor any extra execute permission ACLs). This strangeness is | |
330 | due to the underlying system calls' definitions. Read the | |
331 | documentation for the C<filetest> pragma for more information. | |
332 | ||
a0d0e21e LW |
333 | Note that C<-s/a/b/> does not do a negated substitution. Saying |
334 | C<-exp($foo)> still works as expected, however--only single letters | |
335 | following a minus are interpreted as file tests. | |
336 | ||
337 | The C<-T> and C<-B> switches work as follows. The first block or so of the | |
338 | file is examined for odd characters such as strange control codes or | |
61eff3bc | 339 | characters with the high bit set. If too many strange characters (>30%) |
a0d0e21e LW |
340 | are found, it's a C<-B> file, otherwise it's a C<-T> file. Also, any file |
341 | containing null in the first block is considered a binary file. If C<-T> | |
9124316e | 342 | or C<-B> is used on a filehandle, the current IO buffer is examined |
19799a22 | 343 | rather than the first block. Both C<-T> and C<-B> return true on a null |
54310121 | 344 | file, or a file at EOF when testing a filehandle. Because you have to |
4633a7c4 LW |
345 | read a file to do the C<-T> test, on most occasions you want to use a C<-f> |
346 | against the file first, as in C<next unless -f $file && -T $file>. | |
a0d0e21e | 347 | |
19799a22 | 348 | If any of the file tests (or either the C<stat> or C<lstat> operators) are given |
28757baa | 349 | the special filehandle consisting of a solitary underline, then the stat |
a0d0e21e LW |
350 | structure of the previous file test (or stat operator) is used, saving |
351 | a system call. (This doesn't work with C<-t>, and you need to remember | |
352 | that lstat() and C<-l> will leave values in the stat structure for the | |
5c9aa243 RGS |
353 | symbolic link, not the real file.) (Also, if the stat buffer was filled by |
354 | a C<lstat> call, C<-T> and C<-B> will reset it with the results of C<stat _>). | |
355 | Example: | |
a0d0e21e LW |
356 | |
357 | print "Can do.\n" if -r $a || -w _ || -x _; | |
358 | ||
359 | stat($filename); | |
360 | print "Readable\n" if -r _; | |
361 | print "Writable\n" if -w _; | |
362 | print "Executable\n" if -x _; | |
363 | print "Setuid\n" if -u _; | |
364 | print "Setgid\n" if -g _; | |
365 | print "Sticky\n" if -k _; | |
366 | print "Text\n" if -T _; | |
367 | print "Binary\n" if -B _; | |
368 | ||
369 | =item abs VALUE | |
370 | ||
54310121 | 371 | =item abs |
bbce6d69 | 372 | |
a0d0e21e | 373 | Returns the absolute value of its argument. |
7660c0ab | 374 | If VALUE is omitted, uses C<$_>. |
a0d0e21e LW |
375 | |
376 | =item accept NEWSOCKET,GENERICSOCKET | |
377 | ||
f86cebdf | 378 | Accepts an incoming socket connect, just as the accept(2) system call |
19799a22 | 379 | does. Returns the packed address if it succeeded, false otherwise. |
2b5ab1e7 | 380 | See the example in L<perlipc/"Sockets: Client/Server Communication">. |
a0d0e21e | 381 | |
8d2a6795 GS |
382 | On systems that support a close-on-exec flag on files, the flag will |
383 | be set for the newly opened file descriptor, as determined by the | |
384 | value of $^F. See L<perlvar/$^F>. | |
385 | ||
a0d0e21e LW |
386 | =item alarm SECONDS |
387 | ||
54310121 | 388 | =item alarm |
bbce6d69 | 389 | |
a0d0e21e | 390 | Arranges to have a SIGALRM delivered to this process after the |
d400eac8 JH |
391 | specified number of wallclock seconds have elapsed. If SECONDS is not |
392 | specified, the value stored in C<$_> is used. (On some machines, | |
393 | unfortunately, the elapsed time may be up to one second less or more | |
394 | than you specified because of how seconds are counted, and process | |
395 | scheduling may delay the delivery of the signal even further.) | |
396 | ||
397 | Only one timer may be counting at once. Each call disables the | |
398 | previous timer, and an argument of C<0> may be supplied to cancel the | |
399 | previous timer without starting a new one. The returned value is the | |
400 | amount of time remaining on the previous timer. | |
a0d0e21e | 401 | |
4633a7c4 | 402 | For delays of finer granularity than one second, you may use Perl's |
19799a22 GS |
403 | four-argument version of select() leaving the first three arguments |
404 | undefined, or you might be able to use the C<syscall> interface to | |
83df6a1d JH |
405 | access setitimer(2) if your system supports it. The Time::HiRes |
406 | module (from CPAN, and starting from Perl 5.8 part of the standard | |
407 | distribution) may also prove useful. | |
2b5ab1e7 | 408 | |
68f8bed4 JH |
409 | It is usually a mistake to intermix C<alarm> and C<sleep> calls. |
410 | (C<sleep> may be internally implemented in your system with C<alarm>) | |
a0d0e21e | 411 | |
19799a22 GS |
412 | If you want to use C<alarm> to time out a system call you need to use an |
413 | C<eval>/C<die> pair. You can't rely on the alarm causing the system call to | |
f86cebdf | 414 | fail with C<$!> set to C<EINTR> because Perl sets up signal handlers to |
19799a22 | 415 | restart system calls on some systems. Using C<eval>/C<die> always works, |
5a964f20 | 416 | modulo the caveats given in L<perlipc/"Signals">. |
ff68c719 | 417 | |
418 | eval { | |
f86cebdf | 419 | local $SIG{ALRM} = sub { die "alarm\n" }; # NB: \n required |
36477c24 | 420 | alarm $timeout; |
ff68c719 | 421 | $nread = sysread SOCKET, $buffer, $size; |
36477c24 | 422 | alarm 0; |
ff68c719 | 423 | }; |
ff68c719 | 424 | if ($@) { |
f86cebdf | 425 | die unless $@ eq "alarm\n"; # propagate unexpected errors |
ff68c719 | 426 | # timed out |
427 | } | |
428 | else { | |
429 | # didn't | |
430 | } | |
431 | ||
a0d0e21e LW |
432 | =item atan2 Y,X |
433 | ||
434 | Returns the arctangent of Y/X in the range -PI to PI. | |
435 | ||
ca6e1c26 | 436 | For the tangent operation, you may use the C<Math::Trig::tan> |
28757baa | 437 | function, or use the familiar relation: |
438 | ||
439 | sub tan { sin($_[0]) / cos($_[0]) } | |
440 | ||
a0d0e21e LW |
441 | =item bind SOCKET,NAME |
442 | ||
443 | Binds a network address to a socket, just as the bind system call | |
19799a22 | 444 | does. Returns true if it succeeded, false otherwise. NAME should be a |
4633a7c4 LW |
445 | packed address of the appropriate type for the socket. See the examples in |
446 | L<perlipc/"Sockets: Client/Server Communication">. | |
a0d0e21e | 447 | |
1c1fc3ea GS |
448 | =item binmode FILEHANDLE, DISCIPLINE |
449 | ||
a0d0e21e LW |
450 | =item binmode FILEHANDLE |
451 | ||
16fe6d59 GS |
452 | Arranges for FILEHANDLE to be read or written in "binary" or "text" mode |
453 | on systems where the run-time libraries distinguish between binary and | |
30168b04 | 454 | text files. If FILEHANDLE is an expression, the value is taken as the |
16537909 JH |
455 | name of the filehandle. |
456 | ||
457 | DISCIPLINE can be either of C<:raw> for binary mode or C<:crlf> for | |
458 | "text" mode. If the DISCIPLINE is omitted, it defaults to C<:raw>. | |
459 | Returns true on success, C<undef> on failure. To mark FILEHANDLE as | |
460 | UTF-8, use C<:utf8>, and to mark the as bytes, use C<:bytes>. | |
461 | ||
462 | The C<:raw> are C<:clrf>, and any other directives of the form | |
463 | C<:...>, are called I/O I<disciplines>. The C<open> pragma can be | |
464 | used to establish default I/O disciplines. See L<open>. | |
ed53a2bb JH |
465 | |
466 | In general, binmode() should be called after open() but before any I/O | |
467 | is done on the filehandle. Calling binmode() will flush any possibly | |
468 | pending buffered input or output data on the handle. The only | |
469 | exception to this is the C<:encoding> discipline that changes | |
470 | the default character encoding of the handle, see L<open>. | |
471 | The C<:encoding> discipline sometimes needs to be called in | |
472 | mid-stream, and it doesn't flush the stream. | |
16fe6d59 | 473 | |
16fe6d59 GS |
474 | On some systems binmode() is necessary when you're not working with a |
475 | text file. For the sake of portability it is a good idea to always use | |
476 | it when appropriate, and to never use it when it isn't appropriate. | |
30168b04 GS |
477 | |
478 | In other words: Regardless of platform, use binmode() on binary | |
479 | files, and do not use binmode() on text files. | |
19799a22 GS |
480 | |
481 | The operating system, device drivers, C libraries, and Perl run-time | |
30168b04 GS |
482 | system all work together to let the programmer treat a single |
483 | character (C<\n>) as the line terminator, irrespective of the external | |
484 | representation. On many operating systems, the native text file | |
485 | representation matches the internal representation, but on some | |
486 | platforms the external representation of C<\n> is made up of more than | |
487 | one character. | |
488 | ||
68bd7414 NIS |
489 | Mac OS, all variants of Unix, and Stream_LF files on VMS use a single |
490 | character to end each line in the external representation of text (even | |
5e12dbfa | 491 | though that single character is CARRIAGE RETURN on Mac OS and LINE FEED |
68bd7414 NIS |
492 | on Unix and most VMS files). Consequently binmode() has no effect on |
493 | these operating systems. In other systems like OS/2, DOS and the various | |
494 | flavors of MS-Windows your program sees a C<\n> as a simple C<\cJ>, but | |
495 | what's stored in text files are the two characters C<\cM\cJ>. That means | |
496 | that, if you don't use binmode() on these systems, C<\cM\cJ> sequences on | |
497 | disk will be converted to C<\n> on input, and any C<\n> in your program | |
5e12dbfa PP |
498 | will be converted back to C<\cM\cJ> on output. This is what you want for |
499 | text files, but it can be disastrous for binary files. | |
30168b04 GS |
500 | |
501 | Another consequence of using binmode() (on some systems) is that | |
502 | special end-of-file markers will be seen as part of the data stream. | |
503 | For systems from the Microsoft family this means that if your binary | |
4375e838 | 504 | data contains C<\cZ>, the I/O subsystem will regard it as the end of |
30168b04 GS |
505 | the file, unless you use binmode(). |
506 | ||
507 | binmode() is not only important for readline() and print() operations, | |
508 | but also when using read(), seek(), sysread(), syswrite() and tell() | |
509 | (see L<perlport> for more details). See the C<$/> and C<$\> variables | |
510 | in L<perlvar> for how to manually set your input and output | |
511 | line-termination sequences. | |
a0d0e21e | 512 | |
4633a7c4 | 513 | =item bless REF,CLASSNAME |
a0d0e21e LW |
514 | |
515 | =item bless REF | |
516 | ||
2b5ab1e7 TC |
517 | This function tells the thingy referenced by REF that it is now an object |
518 | in the CLASSNAME package. If CLASSNAME is omitted, the current package | |
19799a22 | 519 | is used. Because a C<bless> is often the last thing in a constructor, |
2b5ab1e7 TC |
520 | it returns the reference for convenience. Always use the two-argument |
521 | version if the function doing the blessing might be inherited by a | |
522 | derived class. See L<perltoot> and L<perlobj> for more about the blessing | |
523 | (and blessings) of objects. | |
a0d0e21e | 524 | |
57668c4d | 525 | Consider always blessing objects in CLASSNAMEs that are mixed case. |
2b5ab1e7 TC |
526 | Namespaces with all lowercase names are considered reserved for |
527 | Perl pragmata. Builtin types have all uppercase names, so to prevent | |
528 | confusion, you may wish to avoid such package names as well. Make sure | |
529 | that CLASSNAME is a true value. | |
60ad88b8 GS |
530 | |
531 | See L<perlmod/"Perl Modules">. | |
532 | ||
a0d0e21e LW |
533 | =item caller EXPR |
534 | ||
535 | =item caller | |
536 | ||
5a964f20 | 537 | Returns the context of the current subroutine call. In scalar context, |
28757baa | 538 | returns the caller's package name if there is a caller, that is, if |
19799a22 | 539 | we're in a subroutine or C<eval> or C<require>, and the undefined value |
5a964f20 | 540 | otherwise. In list context, returns |
a0d0e21e | 541 | |
748a9306 | 542 | ($package, $filename, $line) = caller; |
a0d0e21e LW |
543 | |
544 | With EXPR, it returns some extra information that the debugger uses to | |
545 | print a stack trace. The value of EXPR indicates how many call frames | |
546 | to go back before the current one. | |
547 | ||
f3aa04c2 | 548 | ($package, $filename, $line, $subroutine, $hasargs, |
e476b1b5 | 549 | $wantarray, $evaltext, $is_require, $hints, $bitmask) = caller($i); |
e7ea3e70 | 550 | |
951ba7fe | 551 | Here $subroutine may be C<(eval)> if the frame is not a subroutine |
19799a22 | 552 | call, but an C<eval>. In such a case additional elements $evaltext and |
7660c0ab | 553 | C<$is_require> are set: C<$is_require> is true if the frame is created by a |
19799a22 | 554 | C<require> or C<use> statement, $evaltext contains the text of the |
277ddfaf | 555 | C<eval EXPR> statement. In particular, for an C<eval BLOCK> statement, |
951ba7fe | 556 | $filename is C<(eval)>, but $evaltext is undefined. (Note also that |
dc848c6f | 557 | each C<use> statement creates a C<require> frame inside an C<eval EXPR>) |
277ddfaf | 558 | frame. C<$hasargs> is true if a new instance of C<@_> was set up for the |
e476b1b5 GS |
559 | frame. C<$hints> and C<$bitmask> contain pragmatic hints that the caller |
560 | was compiled with. The C<$hints> and C<$bitmask> values are subject to | |
561 | change between versions of Perl, and are not meant for external use. | |
748a9306 LW |
562 | |
563 | Furthermore, when called from within the DB package, caller returns more | |
7660c0ab | 564 | detailed information: it sets the list variable C<@DB::args> to be the |
54310121 | 565 | arguments with which the subroutine was invoked. |
748a9306 | 566 | |
7660c0ab | 567 | Be aware that the optimizer might have optimized call frames away before |
19799a22 | 568 | C<caller> had a chance to get the information. That means that C<caller(N)> |
7660c0ab | 569 | might not return information about the call frame you expect it do, for |
b76cc8ba | 570 | C<< N > 1 >>. In particular, C<@DB::args> might have information from the |
19799a22 | 571 | previous time C<caller> was called. |
7660c0ab | 572 | |
a0d0e21e LW |
573 | =item chdir EXPR |
574 | ||
ffce7b87 | 575 | Changes the working directory to EXPR, if possible. If EXPR is omitted, |
0bfc1ec4 | 576 | changes to the directory specified by C<$ENV{HOME}>, if set; if not, |
ffce7b87 | 577 | changes to the directory specified by C<$ENV{LOGDIR}>. (Under VMS, the |
b4ad75f0 AMS |
578 | variable C<$ENV{SYS$LOGIN}> is also checked, and used if it is set.) If |
579 | neither is set, C<chdir> does nothing. It returns true upon success, | |
580 | false otherwise. See the example under C<die>. | |
a0d0e21e LW |
581 | |
582 | =item chmod LIST | |
583 | ||
584 | Changes the permissions of a list of files. The first element of the | |
4633a7c4 | 585 | list must be the numerical mode, which should probably be an octal |
2f9daede TP |
586 | number, and which definitely should I<not> a string of octal digits: |
587 | C<0644> is okay, C<'0644'> is not. Returns the number of files | |
dc848c6f | 588 | successfully changed. See also L</oct>, if all you have is a string. |
a0d0e21e LW |
589 | |
590 | $cnt = chmod 0755, 'foo', 'bar'; | |
591 | chmod 0755, @executables; | |
f86cebdf GS |
592 | $mode = '0644'; chmod $mode, 'foo'; # !!! sets mode to |
593 | # --w----r-T | |
2f9daede TP |
594 | $mode = '0644'; chmod oct($mode), 'foo'; # this is better |
595 | $mode = 0644; chmod $mode, 'foo'; # this is best | |
a0d0e21e | 596 | |
ca6e1c26 JH |
597 | You can also import the symbolic C<S_I*> constants from the Fcntl |
598 | module: | |
599 | ||
600 | use Fcntl ':mode'; | |
601 | ||
602 | chmod S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH|S_IXOTH, @executables; | |
603 | # This is identical to the chmod 0755 of the above example. | |
604 | ||
a0d0e21e LW |
605 | =item chomp VARIABLE |
606 | ||
313c9f5c | 607 | =item chomp( LIST ) |
a0d0e21e LW |
608 | |
609 | =item chomp | |
610 | ||
2b5ab1e7 TC |
611 | This safer version of L</chop> removes any trailing string |
612 | that corresponds to the current value of C<$/> (also known as | |
28757baa | 613 | $INPUT_RECORD_SEPARATOR in the C<English> module). It returns the total |
614 | number of characters removed from all its arguments. It's often used to | |
615 | remove the newline from the end of an input record when you're worried | |
2b5ab1e7 TC |
616 | that the final record may be missing its newline. When in paragraph |
617 | mode (C<$/ = "">), it removes all trailing newlines from the string. | |
4c5a6083 GS |
618 | When in slurp mode (C<$/ = undef>) or fixed-length record mode (C<$/> is |
619 | a reference to an integer or the like, see L<perlvar>) chomp() won't | |
b76cc8ba | 620 | remove anything. |
19799a22 | 621 | If VARIABLE is omitted, it chomps C<$_>. Example: |
a0d0e21e LW |
622 | |
623 | while (<>) { | |
624 | chomp; # avoid \n on last field | |
625 | @array = split(/:/); | |
5a964f20 | 626 | # ... |
a0d0e21e LW |
627 | } |
628 | ||
4bf21a6d RD |
629 | If VARIABLE is a hash, it chomps the hash's values, but not its keys. |
630 | ||
a0d0e21e LW |
631 | You can actually chomp anything that's an lvalue, including an assignment: |
632 | ||
633 | chomp($cwd = `pwd`); | |
634 | chomp($answer = <STDIN>); | |
635 | ||
636 | If you chomp a list, each element is chomped, and the total number of | |
637 | characters removed is returned. | |
638 | ||
639 | =item chop VARIABLE | |
640 | ||
313c9f5c | 641 | =item chop( LIST ) |
a0d0e21e LW |
642 | |
643 | =item chop | |
644 | ||
645 | Chops off the last character of a string and returns the character | |
5b3eff12 | 646 | chopped. It is much more efficient than C<s/.$//s> because it neither |
7660c0ab | 647 | scans nor copies the string. If VARIABLE is omitted, chops C<$_>. |
4bf21a6d RD |
648 | If VARIABLE is a hash, it chops the hash's values, but not its keys. |
649 | ||
5b3eff12 | 650 | You can actually chop anything that's an lvalue, including an assignment. |
a0d0e21e LW |
651 | |
652 | If you chop a list, each element is chopped. Only the value of the | |
19799a22 | 653 | last C<chop> is returned. |
a0d0e21e | 654 | |
19799a22 | 655 | Note that C<chop> returns the last character. To return all but the last |
748a9306 LW |
656 | character, use C<substr($string, 0, -1)>. |
657 | ||
a0d0e21e LW |
658 | =item chown LIST |
659 | ||
660 | Changes the owner (and group) of a list of files. The first two | |
19799a22 GS |
661 | elements of the list must be the I<numeric> uid and gid, in that |
662 | order. A value of -1 in either position is interpreted by most | |
663 | systems to leave that value unchanged. Returns the number of files | |
664 | successfully changed. | |
a0d0e21e LW |
665 | |
666 | $cnt = chown $uid, $gid, 'foo', 'bar'; | |
667 | chown $uid, $gid, @filenames; | |
668 | ||
54310121 | 669 | Here's an example that looks up nonnumeric uids in the passwd file: |
a0d0e21e LW |
670 | |
671 | print "User: "; | |
19799a22 | 672 | chomp($user = <STDIN>); |
5a964f20 | 673 | print "Files: "; |
19799a22 | 674 | chomp($pattern = <STDIN>); |
a0d0e21e LW |
675 | |
676 | ($login,$pass,$uid,$gid) = getpwnam($user) | |
677 | or die "$user not in passwd file"; | |
678 | ||
5a964f20 | 679 | @ary = glob($pattern); # expand filenames |
a0d0e21e LW |
680 | chown $uid, $gid, @ary; |
681 | ||
54310121 | 682 | On most systems, you are not allowed to change the ownership of the |
4633a7c4 LW |
683 | file unless you're the superuser, although you should be able to change |
684 | the group to any of your secondary groups. On insecure systems, these | |
685 | restrictions may be relaxed, but this is not a portable assumption. | |
19799a22 GS |
686 | On POSIX systems, you can detect this condition this way: |
687 | ||
688 | use POSIX qw(sysconf _PC_CHOWN_RESTRICTED); | |
689 | $can_chown_giveaway = not sysconf(_PC_CHOWN_RESTRICTED); | |
4633a7c4 | 690 | |
a0d0e21e LW |
691 | =item chr NUMBER |
692 | ||
54310121 | 693 | =item chr |
bbce6d69 | 694 | |
a0d0e21e | 695 | Returns the character represented by that NUMBER in the character set. |
a0ed51b3 | 696 | For example, C<chr(65)> is C<"A"> in either ASCII or Unicode, and |
121910a4 JH |
697 | chr(0x263a) is a Unicode smiley face. Note that characters from 127 |
698 | to 255 (inclusive) are by default not encoded in Unicode for backward | |
699 | compatibility reasons (but see L<encoding>). | |
aaa68c4a | 700 | |
b76cc8ba | 701 | For the reverse, use L</ord>. |
121910a4 | 702 | See L<perlunicode> and L<encoding> for more about Unicode. |
a0d0e21e | 703 | |
7660c0ab | 704 | If NUMBER is omitted, uses C<$_>. |
bbce6d69 | 705 | |
a0d0e21e LW |
706 | =item chroot FILENAME |
707 | ||
54310121 | 708 | =item chroot |
bbce6d69 | 709 | |
5a964f20 | 710 | This function works like the system call by the same name: it makes the |
4633a7c4 | 711 | named directory the new root directory for all further pathnames that |
951ba7fe | 712 | begin with a C</> by your process and all its children. (It doesn't |
28757baa | 713 | change your current working directory, which is unaffected.) For security |
4633a7c4 | 714 | reasons, this call is restricted to the superuser. If FILENAME is |
19799a22 | 715 | omitted, does a C<chroot> to C<$_>. |
a0d0e21e LW |
716 | |
717 | =item close FILEHANDLE | |
718 | ||
6a518fbc TP |
719 | =item close |
720 | ||
9124316e JH |
721 | Closes the file or pipe associated with the file handle, returning |
722 | true only if IO buffers are successfully flushed and closes the system | |
723 | file descriptor. Closes the currently selected filehandle if the | |
724 | argument is omitted. | |
fb73857a | 725 | |
726 | You don't have to close FILEHANDLE if you are immediately going to do | |
19799a22 GS |
727 | another C<open> on it, because C<open> will close it for you. (See |
728 | C<open>.) However, an explicit C<close> on an input file resets the line | |
729 | counter (C<$.>), while the implicit close done by C<open> does not. | |
fb73857a | 730 | |
19799a22 GS |
731 | If the file handle came from a piped open C<close> will additionally |
732 | return false if one of the other system calls involved fails or if the | |
fb73857a | 733 | program exits with non-zero status. (If the only problem was that the |
b76cc8ba | 734 | program exited non-zero C<$!> will be set to C<0>.) Closing a pipe |
2b5ab1e7 | 735 | also waits for the process executing on the pipe to complete, in case you |
b76cc8ba | 736 | want to look at the output of the pipe afterwards, and |
2b5ab1e7 | 737 | implicitly puts the exit status value of that command into C<$?>. |
5a964f20 | 738 | |
73689b13 GS |
739 | Prematurely closing the read end of a pipe (i.e. before the process |
740 | writing to it at the other end has closed it) will result in a | |
741 | SIGPIPE being delivered to the writer. If the other end can't | |
742 | handle that, be sure to read all the data before closing the pipe. | |
743 | ||
fb73857a | 744 | Example: |
a0d0e21e | 745 | |
fb73857a | 746 | open(OUTPUT, '|sort >foo') # pipe to sort |
747 | or die "Can't start sort: $!"; | |
5a964f20 | 748 | #... # print stuff to output |
fb73857a | 749 | close OUTPUT # wait for sort to finish |
750 | or warn $! ? "Error closing sort pipe: $!" | |
751 | : "Exit status $? from sort"; | |
752 | open(INPUT, 'foo') # get sort's results | |
753 | or die "Can't open 'foo' for input: $!"; | |
a0d0e21e | 754 | |
5a964f20 TC |
755 | FILEHANDLE may be an expression whose value can be used as an indirect |
756 | filehandle, usually the real filehandle name. | |
a0d0e21e LW |
757 | |
758 | =item closedir DIRHANDLE | |
759 | ||
19799a22 | 760 | Closes a directory opened by C<opendir> and returns the success of that |
5a964f20 TC |
761 | system call. |
762 | ||
763 | DIRHANDLE may be an expression whose value can be used as an indirect | |
764 | dirhandle, usually the real dirhandle name. | |
a0d0e21e LW |
765 | |
766 | =item connect SOCKET,NAME | |
767 | ||
768 | Attempts to connect to a remote socket, just as the connect system call | |
19799a22 | 769 | does. Returns true if it succeeded, false otherwise. NAME should be a |
4633a7c4 LW |
770 | packed address of the appropriate type for the socket. See the examples in |
771 | L<perlipc/"Sockets: Client/Server Communication">. | |
a0d0e21e | 772 | |
cb1a09d0 AD |
773 | =item continue BLOCK |
774 | ||
775 | Actually a flow control statement rather than a function. If there is a | |
98293880 JH |
776 | C<continue> BLOCK attached to a BLOCK (typically in a C<while> or |
777 | C<foreach>), it is always executed just before the conditional is about to | |
778 | be evaluated again, just like the third part of a C<for> loop in C. Thus | |
cb1a09d0 AD |
779 | it can be used to increment a loop variable, even when the loop has been |
780 | continued via the C<next> statement (which is similar to the C C<continue> | |
781 | statement). | |
782 | ||
98293880 | 783 | C<last>, C<next>, or C<redo> may appear within a C<continue> |
19799a22 GS |
784 | block. C<last> and C<redo> will behave as if they had been executed within |
785 | the main block. So will C<next>, but since it will execute a C<continue> | |
1d2dff63 GS |
786 | block, it may be more entertaining. |
787 | ||
788 | while (EXPR) { | |
789 | ### redo always comes here | |
790 | do_something; | |
791 | } continue { | |
792 | ### next always comes here | |
793 | do_something_else; | |
794 | # then back the top to re-check EXPR | |
795 | } | |
796 | ### last always comes here | |
797 | ||
798 | Omitting the C<continue> section is semantically equivalent to using an | |
19799a22 | 799 | empty one, logically enough. In that case, C<next> goes directly back |
1d2dff63 GS |
800 | to check the condition at the top of the loop. |
801 | ||
a0d0e21e LW |
802 | =item cos EXPR |
803 | ||
d6217f1e GS |
804 | =item cos |
805 | ||
5a964f20 | 806 | Returns the cosine of EXPR (expressed in radians). If EXPR is omitted, |
7660c0ab | 807 | takes cosine of C<$_>. |
a0d0e21e | 808 | |
ca6e1c26 | 809 | For the inverse cosine operation, you may use the C<Math::Trig::acos()> |
28757baa | 810 | function, or use this relation: |
811 | ||
812 | sub acos { atan2( sqrt(1 - $_[0] * $_[0]), $_[0] ) } | |
813 | ||
a0d0e21e LW |
814 | =item crypt PLAINTEXT,SALT |
815 | ||
f86cebdf | 816 | Encrypts a string exactly like the crypt(3) function in the C library |
4633a7c4 LW |
817 | (assuming that you actually have a version there that has not been |
818 | extirpated as a potential munition). This can prove useful for checking | |
819 | the password file for lousy passwords, amongst other things. Only the | |
820 | guys wearing white hats should do this. | |
a0d0e21e | 821 | |
85c16d83 JH |
822 | Note that C<crypt> is intended to be a one-way function, much like |
823 | breaking eggs to make an omelette. There is no (known) corresponding | |
824 | decrypt function (in other words, the crypt() is a one-way hash | |
825 | function). As a result, this function isn't all that useful for | |
11155c91 | 826 | cryptography. (For that, see your nearby CPAN mirror.) |
2f9daede | 827 | |
85c16d83 JH |
828 | When verifying an existing encrypted string you should use the |
829 | encrypted text as the salt (like C<crypt($plain, $crypted) eq | |
830 | $crypted>). This allows your code to work with the standard C<crypt> | |
831 | and with more exotic implementations. In other words, do not assume | |
832 | anything about the returned string itself, or how many bytes in | |
833 | the encrypted string matter. | |
834 | ||
835 | Traditionally the result is a string of 13 bytes: two first bytes of | |
836 | the salt, followed by 11 bytes from the set C<[./0-9A-Za-z]>, and only | |
837 | the first eight bytes of the encrypted string mattered, but | |
838 | alternative hashing schemes (like MD5), higher level security schemes | |
839 | (like C2), and implementations on non-UNIX platforms may produce | |
840 | different strings. | |
841 | ||
842 | When choosing a new salt create a random two character string whose | |
843 | characters come from the set C<[./0-9A-Za-z]> (like C<join '', ('.', | |
844 | '/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]>). | |
e71965be | 845 | |
a0d0e21e LW |
846 | Here's an example that makes sure that whoever runs this program knows |
847 | their own password: | |
848 | ||
849 | $pwd = (getpwuid($<))[1]; | |
a0d0e21e LW |
850 | |
851 | system "stty -echo"; | |
852 | print "Password: "; | |
e71965be | 853 | chomp($word = <STDIN>); |
a0d0e21e LW |
854 | print "\n"; |
855 | system "stty echo"; | |
856 | ||
e71965be | 857 | if (crypt($word, $pwd) ne $pwd) { |
a0d0e21e LW |
858 | die "Sorry...\n"; |
859 | } else { | |
860 | print "ok\n"; | |
54310121 | 861 | } |
a0d0e21e | 862 | |
9f8f0c9d | 863 | Of course, typing in your own password to whoever asks you |
748a9306 | 864 | for it is unwise. |
a0d0e21e | 865 | |
19799a22 GS |
866 | The L<crypt> function is unsuitable for encrypting large quantities |
867 | of data, not least of all because you can't get the information | |
868 | back. Look at the F<by-module/Crypt> and F<by-module/PGP> directories | |
869 | on your favorite CPAN mirror for a slew of potentially useful | |
870 | modules. | |
871 | ||
f2791508 JH |
872 | If using crypt() on a Unicode string (which I<potentially> has |
873 | characters with codepoints above 255), Perl tries to make sense | |
874 | of the situation by trying to downgrade (a copy of the string) | |
875 | the string back to an eight-bit byte string before calling crypt() | |
876 | (on that copy). If that works, good. If not, crypt() dies with | |
877 | C<Wide character in crypt>. | |
85c16d83 | 878 | |
aa689395 | 879 | =item dbmclose HASH |
a0d0e21e | 880 | |
19799a22 | 881 | [This function has been largely superseded by the C<untie> function.] |
a0d0e21e | 882 | |
aa689395 | 883 | Breaks the binding between a DBM file and a hash. |
a0d0e21e | 884 | |
19799a22 | 885 | =item dbmopen HASH,DBNAME,MASK |
a0d0e21e | 886 | |
19799a22 | 887 | [This function has been largely superseded by the C<tie> function.] |
a0d0e21e | 888 | |
7b8d334a | 889 | This binds a dbm(3), ndbm(3), sdbm(3), gdbm(3), or Berkeley DB file to a |
19799a22 GS |
890 | hash. HASH is the name of the hash. (Unlike normal C<open>, the first |
891 | argument is I<not> a filehandle, even though it looks like one). DBNAME | |
aa689395 | 892 | is the name of the database (without the F<.dir> or F<.pag> extension if |
893 | any). If the database does not exist, it is created with protection | |
19799a22 GS |
894 | specified by MASK (as modified by the C<umask>). If your system supports |
895 | only the older DBM functions, you may perform only one C<dbmopen> in your | |
aa689395 | 896 | program. In older versions of Perl, if your system had neither DBM nor |
19799a22 | 897 | ndbm, calling C<dbmopen> produced a fatal error; it now falls back to |
aa689395 | 898 | sdbm(3). |
899 | ||
900 | If you don't have write access to the DBM file, you can only read hash | |
901 | variables, not set them. If you want to test whether you can write, | |
19799a22 | 902 | either use file tests or try setting a dummy hash entry inside an C<eval>, |
aa689395 | 903 | which will trap the error. |
a0d0e21e | 904 | |
19799a22 GS |
905 | Note that functions such as C<keys> and C<values> may return huge lists |
906 | when used on large DBM files. You may prefer to use the C<each> | |
a0d0e21e LW |
907 | function to iterate over large DBM files. Example: |
908 | ||
909 | # print out history file offsets | |
910 | dbmopen(%HIST,'/usr/lib/news/history',0666); | |
911 | while (($key,$val) = each %HIST) { | |
912 | print $key, ' = ', unpack('L',$val), "\n"; | |
913 | } | |
914 | dbmclose(%HIST); | |
915 | ||
cb1a09d0 | 916 | See also L<AnyDBM_File> for a more general description of the pros and |
184e9718 | 917 | cons of the various dbm approaches, as well as L<DB_File> for a particularly |
cb1a09d0 | 918 | rich implementation. |
4633a7c4 | 919 | |
2b5ab1e7 TC |
920 | You can control which DBM library you use by loading that library |
921 | before you call dbmopen(): | |
922 | ||
923 | use DB_File; | |
924 | dbmopen(%NS_Hist, "$ENV{HOME}/.netscape/history.db") | |
925 | or die "Can't open netscape history file: $!"; | |
926 | ||
a0d0e21e LW |
927 | =item defined EXPR |
928 | ||
54310121 | 929 | =item defined |
bbce6d69 | 930 | |
2f9daede TP |
931 | Returns a Boolean value telling whether EXPR has a value other than |
932 | the undefined value C<undef>. If EXPR is not present, C<$_> will be | |
933 | checked. | |
934 | ||
935 | Many operations return C<undef> to indicate failure, end of file, | |
936 | system error, uninitialized variable, and other exceptional | |
937 | conditions. This function allows you to distinguish C<undef> from | |
938 | other values. (A simple Boolean test will not distinguish among | |
7660c0ab | 939 | C<undef>, zero, the empty string, and C<"0">, which are all equally |
2f9daede | 940 | false.) Note that since C<undef> is a valid scalar, its presence |
19799a22 | 941 | doesn't I<necessarily> indicate an exceptional condition: C<pop> |
2f9daede TP |
942 | returns C<undef> when its argument is an empty array, I<or> when the |
943 | element to return happens to be C<undef>. | |
944 | ||
f10b0346 GS |
945 | You may also use C<defined(&func)> to check whether subroutine C<&func> |
946 | has ever been defined. The return value is unaffected by any forward | |
847c7ebe DD |
947 | declarations of C<&foo>. Note that a subroutine which is not defined |
948 | may still be callable: its package may have an C<AUTOLOAD> method that | |
949 | makes it spring into existence the first time that it is called -- see | |
950 | L<perlsub>. | |
f10b0346 GS |
951 | |
952 | Use of C<defined> on aggregates (hashes and arrays) is deprecated. It | |
953 | used to report whether memory for that aggregate has ever been | |
954 | allocated. This behavior may disappear in future versions of Perl. | |
955 | You should instead use a simple test for size: | |
956 | ||
957 | if (@an_array) { print "has array elements\n" } | |
958 | if (%a_hash) { print "has hash members\n" } | |
2f9daede TP |
959 | |
960 | When used on a hash element, it tells you whether the value is defined, | |
dc848c6f | 961 | not whether the key exists in the hash. Use L</exists> for the latter |
2f9daede | 962 | purpose. |
a0d0e21e LW |
963 | |
964 | Examples: | |
965 | ||
966 | print if defined $switch{'D'}; | |
967 | print "$val\n" while defined($val = pop(@ary)); | |
968 | die "Can't readlink $sym: $!" | |
969 | unless defined($value = readlink $sym); | |
a0d0e21e | 970 | sub foo { defined &$bar ? &$bar(@_) : die "No bar"; } |
2f9daede | 971 | $debugging = 0 unless defined $debugging; |
a0d0e21e | 972 | |
19799a22 | 973 | Note: Many folks tend to overuse C<defined>, and then are surprised to |
7660c0ab | 974 | discover that the number C<0> and C<""> (the zero-length string) are, in fact, |
2f9daede | 975 | defined values. For example, if you say |
a5f75d66 AD |
976 | |
977 | "ab" =~ /a(.*)b/; | |
978 | ||
7660c0ab | 979 | The pattern match succeeds, and C<$1> is defined, despite the fact that it |
a5f75d66 | 980 | matched "nothing". But it didn't really match nothing--rather, it |
2b5ab1e7 | 981 | matched something that happened to be zero characters long. This is all |
a5f75d66 | 982 | very above-board and honest. When a function returns an undefined value, |
2f9daede | 983 | it's an admission that it couldn't give you an honest answer. So you |
19799a22 | 984 | should use C<defined> only when you're questioning the integrity of what |
7660c0ab | 985 | you're trying to do. At other times, a simple comparison to C<0> or C<""> is |
2f9daede TP |
986 | what you want. |
987 | ||
dc848c6f | 988 | See also L</undef>, L</exists>, L</ref>. |
2f9daede | 989 | |
a0d0e21e LW |
990 | =item delete EXPR |
991 | ||
01020589 GS |
992 | Given an expression that specifies a hash element, array element, hash slice, |
993 | or array slice, deletes the specified element(s) from the hash or array. | |
8216c1fd | 994 | In the case of an array, if the array elements happen to be at the end, |
b76cc8ba | 995 | the size of the array will shrink to the highest element that tests |
8216c1fd | 996 | true for exists() (or 0 if no such element exists). |
a0d0e21e | 997 | |
01020589 GS |
998 | Returns each element so deleted or the undefined value if there was no such |
999 | element. Deleting from C<$ENV{}> modifies the environment. Deleting from | |
1000 | a hash tied to a DBM file deletes the entry from the DBM file. Deleting | |
1001 | from a C<tie>d hash or array may not necessarily return anything. | |
1002 | ||
8ea97a1e GS |
1003 | Deleting an array element effectively returns that position of the array |
1004 | to its initial, uninitialized state. Subsequently testing for the same | |
8216c1fd GS |
1005 | element with exists() will return false. Note that deleting array |
1006 | elements in the middle of an array will not shift the index of the ones | |
1007 | after them down--use splice() for that. See L</exists>. | |
8ea97a1e | 1008 | |
01020589 | 1009 | The following (inefficiently) deletes all the values of %HASH and @ARRAY: |
a0d0e21e | 1010 | |
5f05dabc | 1011 | foreach $key (keys %HASH) { |
1012 | delete $HASH{$key}; | |
a0d0e21e LW |
1013 | } |
1014 | ||
01020589 GS |
1015 | foreach $index (0 .. $#ARRAY) { |
1016 | delete $ARRAY[$index]; | |
1017 | } | |
1018 | ||
1019 | And so do these: | |
5f05dabc | 1020 | |
01020589 GS |
1021 | delete @HASH{keys %HASH}; |
1022 | ||
9740c838 | 1023 | delete @ARRAY[0 .. $#ARRAY]; |
5f05dabc | 1024 | |
2b5ab1e7 | 1025 | But both of these are slower than just assigning the empty list |
01020589 GS |
1026 | or undefining %HASH or @ARRAY: |
1027 | ||
1028 | %HASH = (); # completely empty %HASH | |
1029 | undef %HASH; # forget %HASH ever existed | |
2b5ab1e7 | 1030 | |
01020589 GS |
1031 | @ARRAY = (); # completely empty @ARRAY |
1032 | undef @ARRAY; # forget @ARRAY ever existed | |
2b5ab1e7 TC |
1033 | |
1034 | Note that the EXPR can be arbitrarily complicated as long as the final | |
01020589 GS |
1035 | operation is a hash element, array element, hash slice, or array slice |
1036 | lookup: | |
a0d0e21e LW |
1037 | |
1038 | delete $ref->[$x][$y]{$key}; | |
5f05dabc | 1039 | delete @{$ref->[$x][$y]}{$key1, $key2, @morekeys}; |
a0d0e21e | 1040 | |
01020589 GS |
1041 | delete $ref->[$x][$y][$index]; |
1042 | delete @{$ref->[$x][$y]}[$index1, $index2, @moreindices]; | |
1043 | ||
a0d0e21e LW |
1044 | =item die LIST |
1045 | ||
19799a22 GS |
1046 | Outside an C<eval>, prints the value of LIST to C<STDERR> and |
1047 | exits with the current value of C<$!> (errno). If C<$!> is C<0>, | |
61eff3bc JH |
1048 | exits with the value of C<<< ($? >> 8) >>> (backtick `command` |
1049 | status). If C<<< ($? >> 8) >>> is C<0>, exits with C<255>. Inside | |
19799a22 GS |
1050 | an C<eval(),> the error message is stuffed into C<$@> and the |
1051 | C<eval> is terminated with the undefined value. This makes | |
1052 | C<die> the way to raise an exception. | |
a0d0e21e LW |
1053 | |
1054 | Equivalent examples: | |
1055 | ||
1056 | die "Can't cd to spool: $!\n" unless chdir '/usr/spool/news'; | |
54310121 | 1057 | chdir '/usr/spool/news' or die "Can't cd to spool: $!\n" |
a0d0e21e | 1058 | |
ccac6780 | 1059 | If the last element of LIST does not end in a newline, the current |
df37ec69 WW |
1060 | script line number and input line number (if any) are also printed, |
1061 | and a newline is supplied. Note that the "input line number" (also | |
1062 | known as "chunk") is subject to whatever notion of "line" happens to | |
1063 | be currently in effect, and is also available as the special variable | |
1064 | C<$.>. See L<perlvar/"$/"> and L<perlvar/"$.">. | |
1065 | ||
1066 | Hint: sometimes appending C<", stopped"> to your message will cause it | |
1067 | to make better sense when the string C<"at foo line 123"> is appended. | |
1068 | Suppose you are running script "canasta". | |
a0d0e21e LW |
1069 | |
1070 | die "/etc/games is no good"; | |
1071 | die "/etc/games is no good, stopped"; | |
1072 | ||
1073 | produce, respectively | |
1074 | ||
1075 | /etc/games is no good at canasta line 123. | |
1076 | /etc/games is no good, stopped at canasta line 123. | |
1077 | ||
2b5ab1e7 | 1078 | See also exit(), warn(), and the Carp module. |
a0d0e21e | 1079 | |
7660c0ab A |
1080 | If LIST is empty and C<$@> already contains a value (typically from a |
1081 | previous eval) that value is reused after appending C<"\t...propagated">. | |
fb73857a | 1082 | This is useful for propagating exceptions: |
1083 | ||
1084 | eval { ... }; | |
1085 | die unless $@ =~ /Expected exception/; | |
1086 | ||
ad216e65 JH |
1087 | If LIST is empty and C<$@> contains an object reference that has a |
1088 | C<PROPAGATE> method, that method will be called with additional file | |
1089 | and line number parameters. The return value replaces the value in | |
1090 | C<$@>. ie. as if C<<$@ = eval { $@->PROPAGATE(__FILE__, __LINE__) };>> | |
1091 | were called. | |
1092 | ||
7660c0ab | 1093 | If C<$@> is empty then the string C<"Died"> is used. |
fb73857a | 1094 | |
52531d10 GS |
1095 | die() can also be called with a reference argument. If this happens to be |
1096 | trapped within an eval(), $@ contains the reference. This behavior permits | |
1097 | a more elaborate exception handling implementation using objects that | |
4375e838 | 1098 | maintain arbitrary state about the nature of the exception. Such a scheme |
52531d10 GS |
1099 | is sometimes preferable to matching particular string values of $@ using |
1100 | regular expressions. Here's an example: | |
1101 | ||
1102 | eval { ... ; die Some::Module::Exception->new( FOO => "bar" ) }; | |
1103 | if ($@) { | |
1104 | if (ref($@) && UNIVERSAL::isa($@,"Some::Module::Exception")) { | |
1105 | # handle Some::Module::Exception | |
1106 | } | |
1107 | else { | |
1108 | # handle all other possible exceptions | |
1109 | } | |
1110 | } | |
1111 | ||
19799a22 | 1112 | Because perl will stringify uncaught exception messages before displaying |
52531d10 GS |
1113 | them, you may want to overload stringification operations on such custom |
1114 | exception objects. See L<overload> for details about that. | |
1115 | ||
19799a22 GS |
1116 | You can arrange for a callback to be run just before the C<die> |
1117 | does its deed, by setting the C<$SIG{__DIE__}> hook. The associated | |
1118 | handler will be called with the error text and can change the error | |
1119 | message, if it sees fit, by calling C<die> again. See | |
1120 | L<perlvar/$SIG{expr}> for details on setting C<%SIG> entries, and | |
1121 | L<"eval BLOCK"> for some examples. Although this feature was meant | |
1122 | to be run only right before your program was to exit, this is not | |
1123 | currently the case--the C<$SIG{__DIE__}> hook is currently called | |
1124 | even inside eval()ed blocks/strings! If one wants the hook to do | |
1125 | nothing in such situations, put | |
fb73857a | 1126 | |
1127 | die @_ if $^S; | |
1128 | ||
19799a22 GS |
1129 | as the first line of the handler (see L<perlvar/$^S>). Because |
1130 | this promotes strange action at a distance, this counterintuitive | |
b76cc8ba | 1131 | behavior may be fixed in a future release. |
774d564b | 1132 | |
a0d0e21e LW |
1133 | =item do BLOCK |
1134 | ||
1135 | Not really a function. Returns the value of the last command in the | |
1136 | sequence of commands indicated by BLOCK. When modified by a loop | |
98293880 JH |
1137 | modifier, executes the BLOCK once before testing the loop condition. |
1138 | (On other statements the loop modifiers test the conditional first.) | |
a0d0e21e | 1139 | |
4968c1e4 | 1140 | C<do BLOCK> does I<not> count as a loop, so the loop control statements |
2b5ab1e7 TC |
1141 | C<next>, C<last>, or C<redo> cannot be used to leave or restart the block. |
1142 | See L<perlsyn> for alternative strategies. | |
4968c1e4 | 1143 | |
a0d0e21e LW |
1144 | =item do SUBROUTINE(LIST) |
1145 | ||
1146 | A deprecated form of subroutine call. See L<perlsub>. | |
1147 | ||
1148 | =item do EXPR | |
1149 | ||
1150 | Uses the value of EXPR as a filename and executes the contents of the | |
1151 | file as a Perl script. Its primary use is to include subroutines | |
1152 | from a Perl subroutine library. | |
1153 | ||
1154 | do 'stat.pl'; | |
1155 | ||
1156 | is just like | |
1157 | ||
986b19de | 1158 | eval `cat stat.pl`; |
a0d0e21e | 1159 | |
2b5ab1e7 TC |
1160 | except that it's more efficient and concise, keeps track of the current |
1161 | filename for error messages, searches the @INC libraries, and updates | |
1162 | C<%INC> if the file is found. See L<perlvar/Predefined Names> for these | |
1163 | variables. It also differs in that code evaluated with C<do FILENAME> | |
1164 | cannot see lexicals in the enclosing scope; C<eval STRING> does. It's the | |
1165 | same, however, in that it does reparse the file every time you call it, | |
1166 | so you probably don't want to do this inside a loop. | |
a0d0e21e | 1167 | |
8e30cc93 | 1168 | If C<do> cannot read the file, it returns undef and sets C<$!> to the |
2b5ab1e7 | 1169 | error. If C<do> can read the file but cannot compile it, it |
8e30cc93 MG |
1170 | returns undef and sets an error message in C<$@>. If the file is |
1171 | successfully compiled, C<do> returns the value of the last expression | |
1172 | evaluated. | |
1173 | ||
a0d0e21e | 1174 | Note that inclusion of library modules is better done with the |
19799a22 | 1175 | C<use> and C<require> operators, which also do automatic error checking |
4633a7c4 | 1176 | and raise an exception if there's a problem. |
a0d0e21e | 1177 | |
5a964f20 TC |
1178 | You might like to use C<do> to read in a program configuration |
1179 | file. Manual error checking can be done this way: | |
1180 | ||
b76cc8ba | 1181 | # read in config files: system first, then user |
f86cebdf | 1182 | for $file ("/share/prog/defaults.rc", |
b76cc8ba | 1183 | "$ENV{HOME}/.someprogrc") |
2b5ab1e7 | 1184 | { |
5a964f20 | 1185 | unless ($return = do $file) { |
f86cebdf GS |
1186 | warn "couldn't parse $file: $@" if $@; |
1187 | warn "couldn't do $file: $!" unless defined $return; | |
1188 | warn "couldn't run $file" unless $return; | |
5a964f20 TC |
1189 | } |
1190 | } | |
1191 | ||
a0d0e21e LW |
1192 | =item dump LABEL |
1193 | ||
1614b0e3 JD |
1194 | =item dump |
1195 | ||
19799a22 GS |
1196 | This function causes an immediate core dump. See also the B<-u> |
1197 | command-line switch in L<perlrun>, which does the same thing. | |
1198 | Primarily this is so that you can use the B<undump> program (not | |
1199 | supplied) to turn your core dump into an executable binary after | |
1200 | having initialized all your variables at the beginning of the | |
1201 | program. When the new binary is executed it will begin by executing | |
1202 | a C<goto LABEL> (with all the restrictions that C<goto> suffers). | |
1203 | Think of it as a goto with an intervening core dump and reincarnation. | |
1204 | If C<LABEL> is omitted, restarts the program from the top. | |
1205 | ||
1206 | B<WARNING>: Any files opened at the time of the dump will I<not> | |
1207 | be open any more when the program is reincarnated, with possible | |
b76cc8ba | 1208 | resulting confusion on the part of Perl. |
19799a22 GS |
1209 | |
1210 | This function is now largely obsolete, partly because it's very | |
1211 | hard to convert a core file into an executable, and because the | |
1212 | real compiler backends for generating portable bytecode and compilable | |
ac206dc8 RGS |
1213 | C code have superseded it. That's why you should now invoke it as |
1214 | C<CORE::dump()>, if you don't want to be warned against a possible | |
1215 | typo. | |
19799a22 GS |
1216 | |
1217 | If you're looking to use L<dump> to speed up your program, consider | |
1218 | generating bytecode or native C code as described in L<perlcc>. If | |
1219 | you're just trying to accelerate a CGI script, consider using the | |
210b36aa | 1220 | C<mod_perl> extension to B<Apache>, or the CPAN module, CGI::Fast. |
19799a22 | 1221 | You might also consider autoloading or selfloading, which at least |
b76cc8ba | 1222 | make your program I<appear> to run faster. |
5a964f20 | 1223 | |
aa689395 | 1224 | =item each HASH |
1225 | ||
5a964f20 | 1226 | When called in list context, returns a 2-element list consisting of the |
aa689395 | 1227 | key and value for the next element of a hash, so that you can iterate over |
74fc8b5f | 1228 | it. When called in scalar context, returns only the key for the next |
e902a979 | 1229 | element in the hash. |
2f9daede | 1230 | |
ab192400 GS |
1231 | Entries are returned in an apparently random order. The actual random |
1232 | order is subject to change in future versions of perl, but it is guaranteed | |
19799a22 | 1233 | to be in the same order as either the C<keys> or C<values> function |
ab192400 GS |
1234 | would produce on the same (unmodified) hash. |
1235 | ||
1236 | When the hash is entirely read, a null array is returned in list context | |
19799a22 GS |
1237 | (which when assigned produces a false (C<0>) value), and C<undef> in |
1238 | scalar context. The next call to C<each> after that will start iterating | |
1239 | again. There is a single iterator for each hash, shared by all C<each>, | |
1240 | C<keys>, and C<values> function calls in the program; it can be reset by | |
2f9daede TP |
1241 | reading all the elements from the hash, or by evaluating C<keys HASH> or |
1242 | C<values HASH>. If you add or delete elements of a hash while you're | |
74fc8b5f MJD |
1243 | iterating over it, you may get entries skipped or duplicated, so |
1244 | don't. Exception: It is always safe to delete the item most recently | |
1245 | returned by C<each()>, which means that the following code will work: | |
1246 | ||
1247 | while (($key, $value) = each %hash) { | |
1248 | print $key, "\n"; | |
1249 | delete $hash{$key}; # This is safe | |
1250 | } | |
aa689395 | 1251 | |
f86cebdf | 1252 | The following prints out your environment like the printenv(1) program, |
aa689395 | 1253 | only in a different order: |
a0d0e21e LW |
1254 | |
1255 | while (($key,$value) = each %ENV) { | |
1256 | print "$key=$value\n"; | |
1257 | } | |
1258 | ||
19799a22 | 1259 | See also C<keys>, C<values> and C<sort>. |
a0d0e21e LW |
1260 | |
1261 | =item eof FILEHANDLE | |
1262 | ||
4633a7c4 LW |
1263 | =item eof () |
1264 | ||
a0d0e21e LW |
1265 | =item eof |
1266 | ||
1267 | Returns 1 if the next read on FILEHANDLE will return end of file, or if | |
1268 | FILEHANDLE is not open. FILEHANDLE may be an expression whose value | |
5a964f20 | 1269 | gives the real filehandle. (Note that this function actually |
19799a22 | 1270 | reads a character and then C<ungetc>s it, so isn't very useful in an |
748a9306 | 1271 | interactive context.) Do not read from a terminal file (or call |
19799a22 | 1272 | C<eof(FILEHANDLE)> on it) after end-of-file is reached. File types such |
748a9306 LW |
1273 | as terminals may lose the end-of-file condition if you do. |
1274 | ||
820475bd GS |
1275 | An C<eof> without an argument uses the last file read. Using C<eof()> |
1276 | with empty parentheses is very different. It refers to the pseudo file | |
1277 | formed from the files listed on the command line and accessed via the | |
61eff3bc JH |
1278 | C<< <> >> operator. Since C<< <> >> isn't explicitly opened, |
1279 | as a normal filehandle is, an C<eof()> before C<< <> >> has been | |
820475bd | 1280 | used will cause C<@ARGV> to be examined to determine if input is |
efdd0218 RB |
1281 | available. Similarly, an C<eof()> after C<< <> >> has returned |
1282 | end-of-file will assume you are processing another C<@ARGV> list, | |
1283 | and if you haven't set C<@ARGV>, will read input from C<STDIN>; | |
1284 | see L<perlop/"I/O Operators">. | |
820475bd | 1285 | |
61eff3bc | 1286 | In a C<< while (<>) >> loop, C<eof> or C<eof(ARGV)> can be used to |
820475bd GS |
1287 | detect the end of each file, C<eof()> will only detect the end of the |
1288 | last file. Examples: | |
a0d0e21e | 1289 | |
748a9306 LW |
1290 | # reset line numbering on each input file |
1291 | while (<>) { | |
b76cc8ba | 1292 | next if /^\s*#/; # skip comments |
748a9306 | 1293 | print "$.\t$_"; |
5a964f20 TC |
1294 | } continue { |
1295 | close ARGV if eof; # Not eof()! | |
748a9306 LW |
1296 | } |
1297 | ||
a0d0e21e LW |
1298 | # insert dashes just before last line of last file |
1299 | while (<>) { | |
5a964f20 | 1300 | if (eof()) { # check for end of current file |
a0d0e21e | 1301 | print "--------------\n"; |
2b5ab1e7 | 1302 | close(ARGV); # close or last; is needed if we |
748a9306 | 1303 | # are reading from the terminal |
a0d0e21e LW |
1304 | } |
1305 | print; | |
1306 | } | |
1307 | ||
a0d0e21e | 1308 | Practical hint: you almost never need to use C<eof> in Perl, because the |
3ce0d271 GS |
1309 | input operators typically return C<undef> when they run out of data, or if |
1310 | there was an error. | |
a0d0e21e LW |
1311 | |
1312 | =item eval EXPR | |
1313 | ||
1314 | =item eval BLOCK | |
1315 | ||
c7cc6f1c GS |
1316 | In the first form, the return value of EXPR is parsed and executed as if it |
1317 | were a little Perl program. The value of the expression (which is itself | |
5a964f20 | 1318 | determined within scalar context) is first parsed, and if there weren't any |
be3174d2 GS |
1319 | errors, executed in the lexical context of the current Perl program, so |
1320 | that any variable settings or subroutine and format definitions remain | |
1321 | afterwards. Note that the value is parsed every time the eval executes. | |
1322 | If EXPR is omitted, evaluates C<$_>. This form is typically used to | |
1323 | delay parsing and subsequent execution of the text of EXPR until run time. | |
c7cc6f1c GS |
1324 | |
1325 | In the second form, the code within the BLOCK is parsed only once--at the | |
1326 | same time the code surrounding the eval itself was parsed--and executed | |
1327 | within the context of the current Perl program. This form is typically | |
1328 | used to trap exceptions more efficiently than the first (see below), while | |
1329 | also providing the benefit of checking the code within BLOCK at compile | |
1330 | time. | |
1331 | ||
1332 | The final semicolon, if any, may be omitted from the value of EXPR or within | |
1333 | the BLOCK. | |
1334 | ||
1335 | In both forms, the value returned is the value of the last expression | |
5a964f20 | 1336 | evaluated inside the mini-program; a return statement may be also used, just |
c7cc6f1c | 1337 | as with subroutines. The expression providing the return value is evaluated |
5a964f20 | 1338 | in void, scalar, or list context, depending on the context of the eval itself. |
c7cc6f1c | 1339 | See L</wantarray> for more on how the evaluation context can be determined. |
a0d0e21e | 1340 | |
19799a22 GS |
1341 | If there is a syntax error or runtime error, or a C<die> statement is |
1342 | executed, an undefined value is returned by C<eval>, and C<$@> is set to the | |
a0d0e21e | 1343 | error message. If there was no error, C<$@> is guaranteed to be a null |
19799a22 | 1344 | string. Beware that using C<eval> neither silences perl from printing |
c7cc6f1c | 1345 | warnings to STDERR, nor does it stuff the text of warning messages into C<$@>. |
d9984052 A |
1346 | To do either of those, you have to use the C<$SIG{__WARN__}> facility, or |
1347 | turn off warnings inside the BLOCK or EXPR using S<C<no warnings 'all'>>. | |
1348 | See L</warn>, L<perlvar>, L<warnings> and L<perllexwarn>. | |
a0d0e21e | 1349 | |
19799a22 GS |
1350 | Note that, because C<eval> traps otherwise-fatal errors, it is useful for |
1351 | determining whether a particular feature (such as C<socket> or C<symlink>) | |
a0d0e21e LW |
1352 | is implemented. It is also Perl's exception trapping mechanism, where |
1353 | the die operator is used to raise exceptions. | |
1354 | ||
1355 | If the code to be executed doesn't vary, you may use the eval-BLOCK | |
1356 | form to trap run-time errors without incurring the penalty of | |
1357 | recompiling each time. The error, if any, is still returned in C<$@>. | |
1358 | Examples: | |
1359 | ||
54310121 | 1360 | # make divide-by-zero nonfatal |
a0d0e21e LW |
1361 | eval { $answer = $a / $b; }; warn $@ if $@; |
1362 | ||
1363 | # same thing, but less efficient | |
1364 | eval '$answer = $a / $b'; warn $@ if $@; | |
1365 | ||
1366 | # a compile-time error | |
5a964f20 | 1367 | eval { $answer = }; # WRONG |
a0d0e21e LW |
1368 | |
1369 | # a run-time error | |
1370 | eval '$answer ='; # sets $@ | |
1371 | ||
2b5ab1e7 TC |
1372 | Due to the current arguably broken state of C<__DIE__> hooks, when using |
1373 | the C<eval{}> form as an exception trap in libraries, you may wish not | |
1374 | to trigger any C<__DIE__> hooks that user code may have installed. | |
1375 | You can use the C<local $SIG{__DIE__}> construct for this purpose, | |
1376 | as shown in this example: | |
774d564b | 1377 | |
1378 | # a very private exception trap for divide-by-zero | |
f86cebdf GS |
1379 | eval { local $SIG{'__DIE__'}; $answer = $a / $b; }; |
1380 | warn $@ if $@; | |
774d564b | 1381 | |
1382 | This is especially significant, given that C<__DIE__> hooks can call | |
19799a22 | 1383 | C<die> again, which has the effect of changing their error messages: |
774d564b | 1384 | |
1385 | # __DIE__ hooks may modify error messages | |
1386 | { | |
f86cebdf GS |
1387 | local $SIG{'__DIE__'} = |
1388 | sub { (my $x = $_[0]) =~ s/foo/bar/g; die $x }; | |
c7cc6f1c GS |
1389 | eval { die "foo lives here" }; |
1390 | print $@ if $@; # prints "bar lives here" | |
774d564b | 1391 | } |
1392 | ||
19799a22 | 1393 | Because this promotes action at a distance, this counterintuitive behavior |
2b5ab1e7 TC |
1394 | may be fixed in a future release. |
1395 | ||
19799a22 | 1396 | With an C<eval>, you should be especially careful to remember what's |
a0d0e21e LW |
1397 | being looked at when: |
1398 | ||
1399 | eval $x; # CASE 1 | |
1400 | eval "$x"; # CASE 2 | |
1401 | ||
1402 | eval '$x'; # CASE 3 | |
1403 | eval { $x }; # CASE 4 | |
1404 | ||
5a964f20 | 1405 | eval "\$$x++"; # CASE 5 |
a0d0e21e LW |
1406 | $$x++; # CASE 6 |
1407 | ||
2f9daede | 1408 | Cases 1 and 2 above behave identically: they run the code contained in |
19799a22 | 1409 | the variable $x. (Although case 2 has misleading double quotes making |
2f9daede | 1410 | the reader wonder what else might be happening (nothing is).) Cases 3 |
7660c0ab | 1411 | and 4 likewise behave in the same way: they run the code C<'$x'>, which |
19799a22 | 1412 | does nothing but return the value of $x. (Case 4 is preferred for |
2f9daede TP |
1413 | purely visual reasons, but it also has the advantage of compiling at |
1414 | compile-time instead of at run-time.) Case 5 is a place where | |
19799a22 | 1415 | normally you I<would> like to use double quotes, except that in this |
2f9daede TP |
1416 | particular situation, you can just use symbolic references instead, as |
1417 | in case 6. | |
a0d0e21e | 1418 | |
4968c1e4 | 1419 | C<eval BLOCK> does I<not> count as a loop, so the loop control statements |
2b5ab1e7 | 1420 | C<next>, C<last>, or C<redo> cannot be used to leave or restart the block. |
4968c1e4 | 1421 | |
a0d0e21e LW |
1422 | =item exec LIST |
1423 | ||
8bf3b016 GS |
1424 | =item exec PROGRAM LIST |
1425 | ||
19799a22 GS |
1426 | The C<exec> function executes a system command I<and never returns>-- |
1427 | use C<system> instead of C<exec> if you want it to return. It fails and | |
1428 | returns false only if the command does not exist I<and> it is executed | |
fb73857a | 1429 | directly instead of via your system's command shell (see below). |
a0d0e21e | 1430 | |
19799a22 GS |
1431 | Since it's a common mistake to use C<exec> instead of C<system>, Perl |
1432 | warns you if there is a following statement which isn't C<die>, C<warn>, | |
1433 | or C<exit> (if C<-w> is set - but you always do that). If you | |
1434 | I<really> want to follow an C<exec> with some other statement, you | |
55d729e4 GS |
1435 | can use one of these styles to avoid the warning: |
1436 | ||
5a964f20 TC |
1437 | exec ('foo') or print STDERR "couldn't exec foo: $!"; |
1438 | { exec ('foo') }; print STDERR "couldn't exec foo: $!"; | |
55d729e4 | 1439 | |
5a964f20 | 1440 | If there is more than one argument in LIST, or if LIST is an array |
f86cebdf | 1441 | with more than one value, calls execvp(3) with the arguments in LIST. |
5a964f20 TC |
1442 | If there is only one scalar argument or an array with one element in it, |
1443 | the argument is checked for shell metacharacters, and if there are any, | |
1444 | the entire argument is passed to the system's command shell for parsing | |
1445 | (this is C</bin/sh -c> on Unix platforms, but varies on other platforms). | |
1446 | If there are no shell metacharacters in the argument, it is split into | |
b76cc8ba | 1447 | words and passed directly to C<execvp>, which is more efficient. |
19799a22 | 1448 | Examples: |
a0d0e21e | 1449 | |
19799a22 GS |
1450 | exec '/bin/echo', 'Your arguments are: ', @ARGV; |
1451 | exec "sort $outfile | uniq"; | |
a0d0e21e LW |
1452 | |
1453 | If you don't really want to execute the first argument, but want to lie | |
1454 | to the program you are executing about its own name, you can specify | |
1455 | the program you actually want to run as an "indirect object" (without a | |
1456 | comma) in front of the LIST. (This always forces interpretation of the | |
54310121 | 1457 | LIST as a multivalued list, even if there is only a single scalar in |
a0d0e21e LW |
1458 | the list.) Example: |
1459 | ||
1460 | $shell = '/bin/csh'; | |
1461 | exec $shell '-sh'; # pretend it's a login shell | |
1462 | ||
1463 | or, more directly, | |
1464 | ||
1465 | exec {'/bin/csh'} '-sh'; # pretend it's a login shell | |
1466 | ||
bb32b41a GS |
1467 | When the arguments get executed via the system shell, results will |
1468 | be subject to its quirks and capabilities. See L<perlop/"`STRING`"> | |
1469 | for details. | |
1470 | ||
19799a22 GS |
1471 | Using an indirect object with C<exec> or C<system> is also more |
1472 | secure. This usage (which also works fine with system()) forces | |
1473 | interpretation of the arguments as a multivalued list, even if the | |
1474 | list had just one argument. That way you're safe from the shell | |
1475 | expanding wildcards or splitting up words with whitespace in them. | |
5a964f20 TC |
1476 | |
1477 | @args = ( "echo surprise" ); | |
1478 | ||
2b5ab1e7 | 1479 | exec @args; # subject to shell escapes |
f86cebdf | 1480 | # if @args == 1 |
2b5ab1e7 | 1481 | exec { $args[0] } @args; # safe even with one-arg list |
5a964f20 TC |
1482 | |
1483 | The first version, the one without the indirect object, ran the I<echo> | |
1484 | program, passing it C<"surprise"> an argument. The second version | |
1485 | didn't--it tried to run a program literally called I<"echo surprise">, | |
1486 | didn't find it, and set C<$?> to a non-zero value indicating failure. | |
1487 | ||
0f897271 GS |
1488 | Beginning with v5.6.0, Perl will attempt to flush all files opened for |
1489 | output before the exec, but this may not be supported on some platforms | |
1490 | (see L<perlport>). To be safe, you may need to set C<$|> ($AUTOFLUSH | |
1491 | in English) or call the C<autoflush()> method of C<IO::Handle> on any | |
1492 | open handles in order to avoid lost output. | |
1493 | ||
19799a22 | 1494 | Note that C<exec> will not call your C<END> blocks, nor will it call |
7660c0ab A |
1495 | any C<DESTROY> methods in your objects. |
1496 | ||
a0d0e21e LW |
1497 | =item exists EXPR |
1498 | ||
01020589 | 1499 | Given an expression that specifies a hash element or array element, |
8ea97a1e GS |
1500 | returns true if the specified element in the hash or array has ever |
1501 | been initialized, even if the corresponding value is undefined. The | |
1502 | element is not autovivified if it doesn't exist. | |
a0d0e21e | 1503 | |
01020589 GS |
1504 | print "Exists\n" if exists $hash{$key}; |
1505 | print "Defined\n" if defined $hash{$key}; | |
1506 | print "True\n" if $hash{$key}; | |
1507 | ||
1508 | print "Exists\n" if exists $array[$index]; | |
1509 | print "Defined\n" if defined $array[$index]; | |
1510 | print "True\n" if $array[$index]; | |
a0d0e21e | 1511 | |
8ea97a1e | 1512 | A hash or array element can be true only if it's defined, and defined if |
a0d0e21e LW |
1513 | it exists, but the reverse doesn't necessarily hold true. |
1514 | ||
afebc493 GS |
1515 | Given an expression that specifies the name of a subroutine, |
1516 | returns true if the specified subroutine has ever been declared, even | |
1517 | if it is undefined. Mentioning a subroutine name for exists or defined | |
847c7ebe DD |
1518 | does not count as declaring it. Note that a subroutine which does not |
1519 | exist may still be callable: its package may have an C<AUTOLOAD> | |
1520 | method that makes it spring into existence the first time that it is | |
1521 | called -- see L<perlsub>. | |
afebc493 GS |
1522 | |
1523 | print "Exists\n" if exists &subroutine; | |
1524 | print "Defined\n" if defined &subroutine; | |
1525 | ||
a0d0e21e | 1526 | Note that the EXPR can be arbitrarily complicated as long as the final |
afebc493 | 1527 | operation is a hash or array key lookup or subroutine name: |
a0d0e21e | 1528 | |
2b5ab1e7 TC |
1529 | if (exists $ref->{A}->{B}->{$key}) { } |
1530 | if (exists $hash{A}{B}{$key}) { } | |
1531 | ||
01020589 GS |
1532 | if (exists $ref->{A}->{B}->[$ix]) { } |
1533 | if (exists $hash{A}{B}[$ix]) { } | |
1534 | ||
afebc493 GS |
1535 | if (exists &{$ref->{A}{B}{$key}}) { } |
1536 | ||
01020589 GS |
1537 | Although the deepest nested array or hash will not spring into existence |
1538 | just because its existence was tested, any intervening ones will. | |
61eff3bc | 1539 | Thus C<< $ref->{"A"} >> and C<< $ref->{"A"}->{"B"} >> will spring |
01020589 GS |
1540 | into existence due to the existence test for the $key element above. |
1541 | This happens anywhere the arrow operator is used, including even: | |
5a964f20 | 1542 | |
2b5ab1e7 TC |
1543 | undef $ref; |
1544 | if (exists $ref->{"Some key"}) { } | |
1545 | print $ref; # prints HASH(0x80d3d5c) | |
1546 | ||
1547 | This surprising autovivification in what does not at first--or even | |
1548 | second--glance appear to be an lvalue context may be fixed in a future | |
5a964f20 | 1549 | release. |
a0d0e21e | 1550 | |
479ba383 GS |
1551 | See L<perlref/"Pseudo-hashes: Using an array as a hash"> for specifics |
1552 | on how exists() acts when used on a pseudo-hash. | |
e0478e5a | 1553 | |
afebc493 GS |
1554 | Use of a subroutine call, rather than a subroutine name, as an argument |
1555 | to exists() is an error. | |
1556 | ||
1557 | exists ⊂ # OK | |
1558 | exists &sub(); # Error | |
1559 | ||
a0d0e21e LW |
1560 | =item exit EXPR |
1561 | ||
2b5ab1e7 | 1562 | Evaluates EXPR and exits immediately with that value. Example: |
a0d0e21e LW |
1563 | |
1564 | $ans = <STDIN>; | |
1565 | exit 0 if $ans =~ /^[Xx]/; | |
1566 | ||
19799a22 | 1567 | See also C<die>. If EXPR is omitted, exits with C<0> status. The only |
2b5ab1e7 TC |
1568 | universally recognized values for EXPR are C<0> for success and C<1> |
1569 | for error; other values are subject to interpretation depending on the | |
1570 | environment in which the Perl program is running. For example, exiting | |
1571 | 69 (EX_UNAVAILABLE) from a I<sendmail> incoming-mail filter will cause | |
1572 | the mailer to return the item undelivered, but that's not true everywhere. | |
a0d0e21e | 1573 | |
19799a22 GS |
1574 | Don't use C<exit> to abort a subroutine if there's any chance that |
1575 | someone might want to trap whatever error happened. Use C<die> instead, | |
1576 | which can be trapped by an C<eval>. | |
28757baa | 1577 | |
19799a22 | 1578 | The exit() function does not always exit immediately. It calls any |
2b5ab1e7 | 1579 | defined C<END> routines first, but these C<END> routines may not |
19799a22 | 1580 | themselves abort the exit. Likewise any object destructors that need to |
2b5ab1e7 TC |
1581 | be called are called before the real exit. If this is a problem, you |
1582 | can call C<POSIX:_exit($status)> to avoid END and destructor processing. | |
87275199 | 1583 | See L<perlmod> for details. |
5a964f20 | 1584 | |
a0d0e21e LW |
1585 | =item exp EXPR |
1586 | ||
54310121 | 1587 | =item exp |
bbce6d69 | 1588 | |
b76cc8ba | 1589 | Returns I<e> (the natural logarithm base) to the power of EXPR. |
a0d0e21e LW |
1590 | If EXPR is omitted, gives C<exp($_)>. |
1591 | ||
1592 | =item fcntl FILEHANDLE,FUNCTION,SCALAR | |
1593 | ||
f86cebdf | 1594 | Implements the fcntl(2) function. You'll probably have to say |
a0d0e21e LW |
1595 | |
1596 | use Fcntl; | |
1597 | ||
0ade1984 | 1598 | first to get the correct constant definitions. Argument processing and |
b76cc8ba | 1599 | value return works just like C<ioctl> below. |
a0d0e21e LW |
1600 | For example: |
1601 | ||
1602 | use Fcntl; | |
5a964f20 TC |
1603 | fcntl($filehandle, F_GETFL, $packed_return_buffer) |
1604 | or die "can't fcntl F_GETFL: $!"; | |
1605 | ||
19799a22 | 1606 | You don't have to check for C<defined> on the return from C<fnctl>. |
951ba7fe GS |
1607 | Like C<ioctl>, it maps a C<0> return from the system call into |
1608 | C<"0 but true"> in Perl. This string is true in boolean context and C<0> | |
2b5ab1e7 TC |
1609 | in numeric context. It is also exempt from the normal B<-w> warnings |
1610 | on improper numeric conversions. | |
5a964f20 | 1611 | |
19799a22 | 1612 | Note that C<fcntl> will produce a fatal error if used on a machine that |
2b5ab1e7 TC |
1613 | doesn't implement fcntl(2). See the Fcntl module or your fcntl(2) |
1614 | manpage to learn what functions are available on your system. | |
a0d0e21e LW |
1615 | |
1616 | =item fileno FILEHANDLE | |
1617 | ||
2b5ab1e7 TC |
1618 | Returns the file descriptor for a filehandle, or undefined if the |
1619 | filehandle is not open. This is mainly useful for constructing | |
19799a22 | 1620 | bitmaps for C<select> and low-level POSIX tty-handling operations. |
2b5ab1e7 TC |
1621 | If FILEHANDLE is an expression, the value is taken as an indirect |
1622 | filehandle, generally its name. | |
5a964f20 | 1623 | |
b76cc8ba | 1624 | You can use this to find out whether two handles refer to the |
5a964f20 TC |
1625 | same underlying descriptor: |
1626 | ||
1627 | if (fileno(THIS) == fileno(THAT)) { | |
1628 | print "THIS and THAT are dups\n"; | |
b76cc8ba NIS |
1629 | } |
1630 | ||
1631 | (Filehandles connected to memory objects via new features of C<open> may | |
1632 | return undefined even though they are open.) | |
1633 | ||
a0d0e21e LW |
1634 | |
1635 | =item flock FILEHANDLE,OPERATION | |
1636 | ||
19799a22 GS |
1637 | Calls flock(2), or an emulation of it, on FILEHANDLE. Returns true |
1638 | for success, false on failure. Produces a fatal error if used on a | |
2b5ab1e7 | 1639 | machine that doesn't implement flock(2), fcntl(2) locking, or lockf(3). |
19799a22 | 1640 | C<flock> is Perl's portable file locking interface, although it locks |
2b5ab1e7 TC |
1641 | only entire files, not records. |
1642 | ||
1643 | Two potentially non-obvious but traditional C<flock> semantics are | |
1644 | that it waits indefinitely until the lock is granted, and that its locks | |
1645 | B<merely advisory>. Such discretionary locks are more flexible, but offer | |
19799a22 GS |
1646 | fewer guarantees. This means that files locked with C<flock> may be |
1647 | modified by programs that do not also use C<flock>. See L<perlport>, | |
2b5ab1e7 TC |
1648 | your port's specific documentation, or your system-specific local manpages |
1649 | for details. It's best to assume traditional behavior if you're writing | |
1650 | portable programs. (But if you're not, you should as always feel perfectly | |
1651 | free to write for your own system's idiosyncrasies (sometimes called | |
1652 | "features"). Slavish adherence to portability concerns shouldn't get | |
1653 | in the way of your getting your job done.) | |
a3cb178b | 1654 | |
8ebc5c01 | 1655 | OPERATION is one of LOCK_SH, LOCK_EX, or LOCK_UN, possibly combined with |
1656 | LOCK_NB. These constants are traditionally valued 1, 2, 8 and 4, but | |
ea3105be | 1657 | you can use the symbolic names if you import them from the Fcntl module, |
68dc0745 | 1658 | either individually, or as a group using the ':flock' tag. LOCK_SH |
1659 | requests a shared lock, LOCK_EX requests an exclusive lock, and LOCK_UN | |
ea3105be GS |
1660 | releases a previously requested lock. If LOCK_NB is bitwise-or'ed with |
1661 | LOCK_SH or LOCK_EX then C<flock> will return immediately rather than blocking | |
68dc0745 | 1662 | waiting for the lock (check the return status to see if you got it). |
1663 | ||
2b5ab1e7 TC |
1664 | To avoid the possibility of miscoordination, Perl now flushes FILEHANDLE |
1665 | before locking or unlocking it. | |
8ebc5c01 | 1666 | |
f86cebdf | 1667 | Note that the emulation built with lockf(3) doesn't provide shared |
8ebc5c01 | 1668 | locks, and it requires that FILEHANDLE be open with write intent. These |
2b5ab1e7 | 1669 | are the semantics that lockf(3) implements. Most if not all systems |
f86cebdf | 1670 | implement lockf(3) in terms of fcntl(2) locking, though, so the |
8ebc5c01 | 1671 | differing semantics shouldn't bite too many people. |
1672 | ||
becacb53 TM |
1673 | Note that the fcntl(2) emulation of flock(3) requires that FILEHANDLE |
1674 | be open with read intent to use LOCK_SH and requires that it be open | |
1675 | with write intent to use LOCK_EX. | |
1676 | ||
19799a22 GS |
1677 | Note also that some versions of C<flock> cannot lock things over the |
1678 | network; you would need to use the more system-specific C<fcntl> for | |
f86cebdf GS |
1679 | that. If you like you can force Perl to ignore your system's flock(2) |
1680 | function, and so provide its own fcntl(2)-based emulation, by passing | |
8ebc5c01 | 1681 | the switch C<-Ud_flock> to the F<Configure> program when you configure |
1682 | perl. | |
4633a7c4 LW |
1683 | |
1684 | Here's a mailbox appender for BSD systems. | |
a0d0e21e | 1685 | |
7e1af8bc | 1686 | use Fcntl ':flock'; # import LOCK_* constants |
a0d0e21e LW |
1687 | |
1688 | sub lock { | |
7e1af8bc | 1689 | flock(MBOX,LOCK_EX); |
a0d0e21e LW |
1690 | # and, in case someone appended |
1691 | # while we were waiting... | |
1692 | seek(MBOX, 0, 2); | |
1693 | } | |
1694 | ||
1695 | sub unlock { | |
7e1af8bc | 1696 | flock(MBOX,LOCK_UN); |
a0d0e21e LW |
1697 | } |
1698 | ||
1699 | open(MBOX, ">>/usr/spool/mail/$ENV{'USER'}") | |
1700 | or die "Can't open mailbox: $!"; | |
1701 | ||
1702 | lock(); | |
1703 | print MBOX $msg,"\n\n"; | |
1704 | unlock(); | |
1705 | ||
2b5ab1e7 TC |
1706 | On systems that support a real flock(), locks are inherited across fork() |
1707 | calls, whereas those that must resort to the more capricious fcntl() | |
1708 | function lose the locks, making it harder to write servers. | |
1709 | ||
cb1a09d0 | 1710 | See also L<DB_File> for other flock() examples. |
a0d0e21e LW |
1711 | |
1712 | =item fork | |
1713 | ||
2b5ab1e7 TC |
1714 | Does a fork(2) system call to create a new process running the |
1715 | same program at the same point. It returns the child pid to the | |
1716 | parent process, C<0> to the child process, or C<undef> if the fork is | |
1717 | unsuccessful. File descriptors (and sometimes locks on those descriptors) | |
1718 | are shared, while everything else is copied. On most systems supporting | |
1719 | fork(), great care has gone into making it extremely efficient (for | |
1720 | example, using copy-on-write technology on data pages), making it the | |
1721 | dominant paradigm for multitasking over the last few decades. | |
5a964f20 | 1722 | |
0f897271 GS |
1723 | Beginning with v5.6.0, Perl will attempt to flush all files opened for |
1724 | output before forking the child process, but this may not be supported | |
1725 | on some platforms (see L<perlport>). To be safe, you may need to set | |
1726 | C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method of | |
1727 | C<IO::Handle> on any open handles in order to avoid duplicate output. | |
a0d0e21e | 1728 | |
19799a22 | 1729 | If you C<fork> without ever waiting on your children, you will |
2b5ab1e7 TC |
1730 | accumulate zombies. On some systems, you can avoid this by setting |
1731 | C<$SIG{CHLD}> to C<"IGNORE">. See also L<perlipc> for more examples of | |
1732 | forking and reaping moribund children. | |
cb1a09d0 | 1733 | |
28757baa | 1734 | Note that if your forked child inherits system file descriptors like |
1735 | STDIN and STDOUT that are actually connected by a pipe or socket, even | |
2b5ab1e7 | 1736 | if you exit, then the remote server (such as, say, a CGI script or a |
19799a22 | 1737 | backgrounded job launched from a remote shell) won't think you're done. |
2b5ab1e7 | 1738 | You should reopen those to F</dev/null> if it's any issue. |
28757baa | 1739 | |
cb1a09d0 AD |
1740 | =item format |
1741 | ||
19799a22 | 1742 | Declare a picture format for use by the C<write> function. For |
cb1a09d0 AD |
1743 | example: |
1744 | ||
54310121 | 1745 | format Something = |
cb1a09d0 AD |
1746 | Test: @<<<<<<<< @||||| @>>>>> |
1747 | $str, $%, '$' . int($num) | |
1748 | . | |
1749 | ||
1750 | $str = "widget"; | |
184e9718 | 1751 | $num = $cost/$quantity; |
cb1a09d0 AD |
1752 | $~ = 'Something'; |
1753 | write; | |
1754 | ||
1755 | See L<perlform> for many details and examples. | |
1756 | ||
8903cb82 | 1757 | =item formline PICTURE,LIST |
a0d0e21e | 1758 | |
5a964f20 | 1759 | This is an internal function used by C<format>s, though you may call it, |
a0d0e21e LW |
1760 | too. It formats (see L<perlform>) a list of values according to the |
1761 | contents of PICTURE, placing the output into the format output | |
7660c0ab | 1762 | accumulator, C<$^A> (or C<$ACCUMULATOR> in English). |
19799a22 | 1763 | Eventually, when a C<write> is done, the contents of |
a0d0e21e | 1764 | C<$^A> are written to some filehandle, but you could also read C<$^A> |
7660c0ab | 1765 | yourself and then set C<$^A> back to C<"">. Note that a format typically |
19799a22 | 1766 | does one C<formline> per line of form, but the C<formline> function itself |
748a9306 | 1767 | doesn't care how many newlines are embedded in the PICTURE. This means |
4633a7c4 | 1768 | that the C<~> and C<~~> tokens will treat the entire PICTURE as a single line. |
748a9306 LW |
1769 | You may therefore need to use multiple formlines to implement a single |
1770 | record format, just like the format compiler. | |
1771 | ||
19799a22 | 1772 | Be careful if you put double quotes around the picture, because an C<@> |
748a9306 | 1773 | character may be taken to mean the beginning of an array name. |
19799a22 | 1774 | C<formline> always returns true. See L<perlform> for other examples. |
a0d0e21e LW |
1775 | |
1776 | =item getc FILEHANDLE | |
1777 | ||
1778 | =item getc | |
1779 | ||
1780 | Returns the next character from the input file attached to FILEHANDLE, | |
2b5ab1e7 TC |
1781 | or the undefined value at end of file, or if there was an error. |
1782 | If FILEHANDLE is omitted, reads from STDIN. This is not particularly | |
1783 | efficient. However, it cannot be used by itself to fetch single | |
1784 | characters without waiting for the user to hit enter. For that, try | |
1785 | something more like: | |
4633a7c4 LW |
1786 | |
1787 | if ($BSD_STYLE) { | |
1788 | system "stty cbreak </dev/tty >/dev/tty 2>&1"; | |
1789 | } | |
1790 | else { | |
54310121 | 1791 | system "stty", '-icanon', 'eol', "\001"; |
4633a7c4 LW |
1792 | } |
1793 | ||
1794 | $key = getc(STDIN); | |
1795 | ||
1796 | if ($BSD_STYLE) { | |
1797 | system "stty -cbreak </dev/tty >/dev/tty 2>&1"; | |
1798 | } | |
1799 | else { | |
5f05dabc | 1800 | system "stty", 'icanon', 'eol', '^@'; # ASCII null |
4633a7c4 LW |
1801 | } |
1802 | print "\n"; | |
1803 | ||
54310121 | 1804 | Determination of whether $BSD_STYLE should be set |
1805 | is left as an exercise to the reader. | |
cb1a09d0 | 1806 | |
19799a22 | 1807 | The C<POSIX::getattr> function can do this more portably on |
2b5ab1e7 TC |
1808 | systems purporting POSIX compliance. See also the C<Term::ReadKey> |
1809 | module from your nearest CPAN site; details on CPAN can be found on | |
1810 | L<perlmodlib/CPAN>. | |
a0d0e21e LW |
1811 | |
1812 | =item getlogin | |
1813 | ||
5a964f20 TC |
1814 | Implements the C library function of the same name, which on most |
1815 | systems returns the current login from F</etc/utmp>, if any. If null, | |
19799a22 | 1816 | use C<getpwuid>. |
a0d0e21e | 1817 | |
f86702cc | 1818 | $login = getlogin || getpwuid($<) || "Kilroy"; |
a0d0e21e | 1819 | |
19799a22 GS |
1820 | Do not consider C<getlogin> for authentication: it is not as |
1821 | secure as C<getpwuid>. | |
4633a7c4 | 1822 | |
a0d0e21e LW |
1823 | =item getpeername SOCKET |
1824 | ||
1825 | Returns the packed sockaddr address of other end of the SOCKET connection. | |
1826 | ||
4633a7c4 LW |
1827 | use Socket; |
1828 | $hersockaddr = getpeername(SOCK); | |
19799a22 | 1829 | ($port, $iaddr) = sockaddr_in($hersockaddr); |
4633a7c4 LW |
1830 | $herhostname = gethostbyaddr($iaddr, AF_INET); |
1831 | $herstraddr = inet_ntoa($iaddr); | |
a0d0e21e LW |
1832 | |
1833 | =item getpgrp PID | |
1834 | ||
47e29363 | 1835 | Returns the current process group for the specified PID. Use |
7660c0ab | 1836 | a PID of C<0> to get the current process group for the |
4633a7c4 | 1837 | current process. Will raise an exception if used on a machine that |
f86cebdf | 1838 | doesn't implement getpgrp(2). If PID is omitted, returns process |
19799a22 | 1839 | group of current process. Note that the POSIX version of C<getpgrp> |
7660c0ab | 1840 | does not accept a PID argument, so only C<PID==0> is truly portable. |
a0d0e21e LW |
1841 | |
1842 | =item getppid | |
1843 | ||
1844 | Returns the process id of the parent process. | |
1845 | ||
1846 | =item getpriority WHICH,WHO | |
1847 | ||
4633a7c4 LW |
1848 | Returns the current priority for a process, a process group, or a user. |
1849 | (See L<getpriority(2)>.) Will raise a fatal exception if used on a | |
f86cebdf | 1850 | machine that doesn't implement getpriority(2). |
a0d0e21e LW |
1851 | |
1852 | =item getpwnam NAME | |
1853 | ||
1854 | =item getgrnam NAME | |
1855 | ||
1856 | =item gethostbyname NAME | |
1857 | ||
1858 | =item getnetbyname NAME | |
1859 | ||
1860 | =item getprotobyname NAME | |
1861 | ||
1862 | =item getpwuid UID | |
1863 | ||
1864 | =item getgrgid GID | |
1865 | ||
1866 | =item getservbyname NAME,PROTO | |
1867 | ||
1868 | =item gethostbyaddr ADDR,ADDRTYPE | |
1869 | ||
1870 | =item getnetbyaddr ADDR,ADDRTYPE | |
1871 | ||
1872 | =item getprotobynumber NUMBER | |
1873 | ||
1874 | =item getservbyport PORT,PROTO | |
1875 | ||
1876 | =item getpwent | |
1877 | ||
1878 | =item getgrent | |
1879 | ||
1880 | =item gethostent | |
1881 | ||
1882 | =item getnetent | |
1883 | ||
1884 | =item getprotoent | |
1885 | ||
1886 | =item getservent | |
1887 | ||
1888 | =item setpwent | |
1889 | ||
1890 | =item setgrent | |
1891 | ||
1892 | =item sethostent STAYOPEN | |
1893 | ||
1894 | =item setnetent STAYOPEN | |
1895 | ||
1896 | =item setprotoent STAYOPEN | |
1897 | ||
1898 | =item setservent STAYOPEN | |
1899 | ||
1900 | =item endpwent | |
1901 | ||
1902 | =item endgrent | |
1903 | ||
1904 | =item endhostent | |
1905 | ||
1906 | =item endnetent | |
1907 | ||
1908 | =item endprotoent | |
1909 | ||
1910 | =item endservent | |
1911 | ||
1912 | These routines perform the same functions as their counterparts in the | |
5a964f20 | 1913 | system library. In list context, the return values from the |
a0d0e21e LW |
1914 | various get routines are as follows: |
1915 | ||
1916 | ($name,$passwd,$uid,$gid, | |
6ee623d5 | 1917 | $quota,$comment,$gcos,$dir,$shell,$expire) = getpw* |
a0d0e21e LW |
1918 | ($name,$passwd,$gid,$members) = getgr* |
1919 | ($name,$aliases,$addrtype,$length,@addrs) = gethost* | |
1920 | ($name,$aliases,$addrtype,$net) = getnet* | |
1921 | ($name,$aliases,$proto) = getproto* | |
1922 | ($name,$aliases,$port,$proto) = getserv* | |
1923 | ||
1924 | (If the entry doesn't exist you get a null list.) | |
1925 | ||
4602f195 JH |
1926 | The exact meaning of the $gcos field varies but it usually contains |
1927 | the real name of the user (as opposed to the login name) and other | |
1928 | information pertaining to the user. Beware, however, that in many | |
1929 | system users are able to change this information and therefore it | |
106325ad | 1930 | cannot be trusted and therefore the $gcos is tainted (see |
2959b6e3 JH |
1931 | L<perlsec>). The $passwd and $shell, user's encrypted password and |
1932 | login shell, are also tainted, because of the same reason. | |
4602f195 | 1933 | |
5a964f20 | 1934 | In scalar context, you get the name, unless the function was a |
a0d0e21e LW |
1935 | lookup by name, in which case you get the other thing, whatever it is. |
1936 | (If the entry doesn't exist you get the undefined value.) For example: | |
1937 | ||
5a964f20 TC |
1938 | $uid = getpwnam($name); |
1939 | $name = getpwuid($num); | |
1940 | $name = getpwent(); | |
1941 | $gid = getgrnam($name); | |
1942 | $name = getgrgid($num; | |
1943 | $name = getgrent(); | |
1944 | #etc. | |
a0d0e21e | 1945 | |
4602f195 JH |
1946 | In I<getpw*()> the fields $quota, $comment, and $expire are special |
1947 | cases in the sense that in many systems they are unsupported. If the | |
1948 | $quota is unsupported, it is an empty scalar. If it is supported, it | |
1949 | usually encodes the disk quota. If the $comment field is unsupported, | |
1950 | it is an empty scalar. If it is supported it usually encodes some | |
1951 | administrative comment about the user. In some systems the $quota | |
1952 | field may be $change or $age, fields that have to do with password | |
1953 | aging. In some systems the $comment field may be $class. The $expire | |
1954 | field, if present, encodes the expiration period of the account or the | |
1955 | password. For the availability and the exact meaning of these fields | |
1956 | in your system, please consult your getpwnam(3) documentation and your | |
1957 | F<pwd.h> file. You can also find out from within Perl what your | |
1958 | $quota and $comment fields mean and whether you have the $expire field | |
1959 | by using the C<Config> module and the values C<d_pwquota>, C<d_pwage>, | |
1960 | C<d_pwchange>, C<d_pwcomment>, and C<d_pwexpire>. Shadow password | |
1961 | files are only supported if your vendor has implemented them in the | |
1962 | intuitive fashion that calling the regular C library routines gets the | |
5d3a0a3b GS |
1963 | shadow versions if you're running under privilege or if there exists |
1964 | the shadow(3) functions as found in System V ( this includes Solaris | |
1965 | and Linux.) Those systems which implement a proprietary shadow password | |
1966 | facility are unlikely to be supported. | |
6ee623d5 | 1967 | |
19799a22 | 1968 | The $members value returned by I<getgr*()> is a space separated list of |
a0d0e21e LW |
1969 | the login names of the members of the group. |
1970 | ||
1971 | For the I<gethost*()> functions, if the C<h_errno> variable is supported in | |
1972 | C, it will be returned to you via C<$?> if the function call fails. The | |
7660c0ab | 1973 | C<@addrs> value returned by a successful call is a list of the raw |
a0d0e21e LW |
1974 | addresses returned by the corresponding system library call. In the |
1975 | Internet domain, each address is four bytes long and you can unpack it | |
1976 | by saying something like: | |
1977 | ||
1978 | ($a,$b,$c,$d) = unpack('C4',$addr[0]); | |
1979 | ||
2b5ab1e7 TC |
1980 | The Socket library makes this slightly easier: |
1981 | ||
1982 | use Socket; | |
1983 | $iaddr = inet_aton("127.1"); # or whatever address | |
1984 | $name = gethostbyaddr($iaddr, AF_INET); | |
1985 | ||
1986 | # or going the other way | |
19799a22 | 1987 | $straddr = inet_ntoa($iaddr); |
2b5ab1e7 | 1988 | |
19799a22 GS |
1989 | If you get tired of remembering which element of the return list |
1990 | contains which return value, by-name interfaces are provided | |
1991 | in standard modules: C<File::stat>, C<Net::hostent>, C<Net::netent>, | |
1992 | C<Net::protoent>, C<Net::servent>, C<Time::gmtime>, C<Time::localtime>, | |
1993 | and C<User::grent>. These override the normal built-ins, supplying | |
1994 | versions that return objects with the appropriate names | |
1995 | for each field. For example: | |
5a964f20 TC |
1996 | |
1997 | use File::stat; | |
1998 | use User::pwent; | |
1999 | $is_his = (stat($filename)->uid == pwent($whoever)->uid); | |
2000 | ||
b76cc8ba NIS |
2001 | Even though it looks like they're the same method calls (uid), |
2002 | they aren't, because a C<File::stat> object is different from | |
19799a22 | 2003 | a C<User::pwent> object. |
5a964f20 | 2004 | |
a0d0e21e LW |
2005 | =item getsockname SOCKET |
2006 | ||
19799a22 GS |
2007 | Returns the packed sockaddr address of this end of the SOCKET connection, |
2008 | in case you don't know the address because you have several different | |
2009 | IPs that the connection might have come in on. | |
a0d0e21e | 2010 | |
4633a7c4 LW |
2011 | use Socket; |
2012 | $mysockaddr = getsockname(SOCK); | |
19799a22 | 2013 | ($port, $myaddr) = sockaddr_in($mysockaddr); |
b76cc8ba | 2014 | printf "Connect to %s [%s]\n", |
19799a22 GS |
2015 | scalar gethostbyaddr($myaddr, AF_INET), |
2016 | inet_ntoa($myaddr); | |
a0d0e21e LW |
2017 | |
2018 | =item getsockopt SOCKET,LEVEL,OPTNAME | |
2019 | ||
5a964f20 | 2020 | Returns the socket option requested, or undef if there is an error. |
a0d0e21e LW |
2021 | |
2022 | =item glob EXPR | |
2023 | ||
0a753a76 | 2024 | =item glob |
2025 | ||
2b5ab1e7 TC |
2026 | Returns the value of EXPR with filename expansions such as the |
2027 | standard Unix shell F</bin/csh> would do. This is the internal function | |
61eff3bc JH |
2028 | implementing the C<< <*.c> >> operator, but you can use it directly. |
2029 | If EXPR is omitted, C<$_> is used. The C<< <*.c> >> operator is | |
2b5ab1e7 | 2030 | discussed in more detail in L<perlop/"I/O Operators">. |
a0d0e21e | 2031 | |
3a4b19e4 GS |
2032 | Beginning with v5.6.0, this operator is implemented using the standard |
2033 | C<File::Glob> extension. See L<File::Glob> for details. | |
2034 | ||
a0d0e21e LW |
2035 | =item gmtime EXPR |
2036 | ||
d1be9408 | 2037 | Converts a time as returned by the time function to an 8-element list |
54310121 | 2038 | with the time localized for the standard Greenwich time zone. |
4633a7c4 | 2039 | Typically used as follows: |
a0d0e21e | 2040 | |
b76cc8ba | 2041 | # 0 1 2 3 4 5 6 7 |
48a26b3a | 2042 | ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday) = |
a0d0e21e LW |
2043 | gmtime(time); |
2044 | ||
48a26b3a GS |
2045 | All list elements are numeric, and come straight out of the C `struct |
2046 | tm'. $sec, $min, and $hour are the seconds, minutes, and hours of the | |
2047 | specified time. $mday is the day of the month, and $mon is the month | |
2048 | itself, in the range C<0..11> with 0 indicating January and 11 | |
2049 | indicating December. $year is the number of years since 1900. That | |
2050 | is, $year is C<123> in year 2023. $wday is the day of the week, with | |
2051 | 0 indicating Sunday and 3 indicating Wednesday. $yday is the day of | |
b76cc8ba | 2052 | the year, in the range C<0..364> (or C<0..365> in leap years.) |
48a26b3a GS |
2053 | |
2054 | Note that the $year element is I<not> simply the last two digits of | |
2055 | the year. If you assume it is, then you create non-Y2K-compliant | |
2056 | programs--and you wouldn't want to do that, would you? | |
2f9daede | 2057 | |
abd75f24 GS |
2058 | The proper way to get a complete 4-digit year is simply: |
2059 | ||
2060 | $year += 1900; | |
2061 | ||
2062 | And to get the last two digits of the year (e.g., '01' in 2001) do: | |
2063 | ||
2064 | $year = sprintf("%02d", $year % 100); | |
2065 | ||
48a26b3a | 2066 | If EXPR is omitted, C<gmtime()> uses the current time (C<gmtime(time)>). |
a0d0e21e | 2067 | |
48a26b3a | 2068 | In scalar context, C<gmtime()> returns the ctime(3) value: |
0a753a76 | 2069 | |
2070 | $now_string = gmtime; # e.g., "Thu Oct 13 04:54:34 1994" | |
2071 | ||
19799a22 | 2072 | Also see the C<timegm> function provided by the C<Time::Local> module, |
f86cebdf | 2073 | and the strftime(3) function available via the POSIX module. |
7660c0ab | 2074 | |
2b5ab1e7 TC |
2075 | This scalar value is B<not> locale dependent (see L<perllocale>), but |
2076 | is instead a Perl builtin. Also see the C<Time::Local> module, and the | |
2077 | strftime(3) and mktime(3) functions available via the POSIX module. To | |
7660c0ab A |
2078 | get somewhat similar but locale dependent date strings, set up your |
2079 | locale environment variables appropriately (please see L<perllocale>) | |
2080 | and try for example: | |
2081 | ||
2082 | use POSIX qw(strftime); | |
2b5ab1e7 | 2083 | $now_string = strftime "%a %b %e %H:%M:%S %Y", gmtime; |
7660c0ab | 2084 | |
2b5ab1e7 TC |
2085 | Note that the C<%a> and C<%b> escapes, which represent the short forms |
2086 | of the day of the week and the month of the year, may not necessarily | |
2087 | be three characters wide in all locales. | |
0a753a76 | 2088 | |
a0d0e21e LW |
2089 | =item goto LABEL |
2090 | ||
748a9306 LW |
2091 | =item goto EXPR |
2092 | ||
a0d0e21e LW |
2093 | =item goto &NAME |
2094 | ||
7660c0ab | 2095 | The C<goto-LABEL> form finds the statement labeled with LABEL and resumes |
a0d0e21e | 2096 | execution there. It may not be used to go into any construct that |
7660c0ab | 2097 | requires initialization, such as a subroutine or a C<foreach> loop. It |
0a753a76 | 2098 | also can't be used to go into a construct that is optimized away, |
19799a22 | 2099 | or to get out of a block or subroutine given to C<sort>. |
0a753a76 | 2100 | It can be used to go almost anywhere else within the dynamic scope, |
a0d0e21e | 2101 | including out of subroutines, but it's usually better to use some other |
19799a22 | 2102 | construct such as C<last> or C<die>. The author of Perl has never felt the |
7660c0ab | 2103 | need to use this form of C<goto> (in Perl, that is--C is another matter). |
1b6921cb BT |
2104 | (The difference being that C does not offer named loops combined with |
2105 | loop control. Perl does, and this replaces most structured uses of C<goto> | |
2106 | in other languages.) | |
a0d0e21e | 2107 | |
7660c0ab A |
2108 | The C<goto-EXPR> form expects a label name, whose scope will be resolved |
2109 | dynamically. This allows for computed C<goto>s per FORTRAN, but isn't | |
748a9306 LW |
2110 | necessarily recommended if you're optimizing for maintainability: |
2111 | ||
2112 | goto ("FOO", "BAR", "GLARCH")[$i]; | |
2113 | ||
1b6921cb BT |
2114 | The C<goto-&NAME> form is quite different from the other forms of |
2115 | C<goto>. In fact, it isn't a goto in the normal sense at all, and | |
2116 | doesn't have the stigma associated with other gotos. Instead, it | |
2117 | exits the current subroutine (losing any changes set by local()) and | |
2118 | immediately calls in its place the named subroutine using the current | |
2119 | value of @_. This is used by C<AUTOLOAD> subroutines that wish to | |
2120 | load another subroutine and then pretend that the other subroutine had | |
2121 | been called in the first place (except that any modifications to C<@_> | |
6cb9131c GS |
2122 | in the current subroutine are propagated to the other subroutine.) |
2123 | After the C<goto>, not even C<caller> will be able to tell that this | |
2124 | routine was called first. | |
2125 | ||
2126 | NAME needn't be the name of a subroutine; it can be a scalar variable | |
2127 | containing a code reference, or a block which evaluates to a code | |
2128 | reference. | |
a0d0e21e LW |
2129 | |
2130 | =item grep BLOCK LIST | |
2131 | ||
2132 | =item grep EXPR,LIST | |
2133 | ||
2b5ab1e7 TC |
2134 | This is similar in spirit to, but not the same as, grep(1) and its |
2135 | relatives. In particular, it is not limited to using regular expressions. | |
2f9daede | 2136 | |
a0d0e21e | 2137 | Evaluates the BLOCK or EXPR for each element of LIST (locally setting |
7660c0ab | 2138 | C<$_> to each element) and returns the list value consisting of those |
19799a22 GS |
2139 | elements for which the expression evaluated to true. In scalar |
2140 | context, returns the number of times the expression was true. | |
a0d0e21e LW |
2141 | |
2142 | @foo = grep(!/^#/, @bar); # weed out comments | |
2143 | ||
2144 | or equivalently, | |
2145 | ||
2146 | @foo = grep {!/^#/} @bar; # weed out comments | |
2147 | ||
be3174d2 GS |
2148 | Note that C<$_> is an alias to the list value, so it can be used to |
2149 | modify the elements of the LIST. While this is useful and supported, | |
2150 | it can cause bizarre results if the elements of LIST are not variables. | |
2b5ab1e7 TC |
2151 | Similarly, grep returns aliases into the original list, much as a for |
2152 | loop's index variable aliases the list elements. That is, modifying an | |
19799a22 GS |
2153 | element of a list returned by grep (for example, in a C<foreach>, C<map> |
2154 | or another C<grep>) actually modifies the element in the original list. | |
2b5ab1e7 | 2155 | This is usually something to be avoided when writing clear code. |
a0d0e21e | 2156 | |
19799a22 | 2157 | See also L</map> for a list composed of the results of the BLOCK or EXPR. |
38325410 | 2158 | |
a0d0e21e LW |
2159 | =item hex EXPR |
2160 | ||
54310121 | 2161 | =item hex |
bbce6d69 | 2162 | |
2b5ab1e7 TC |
2163 | Interprets EXPR as a hex string and returns the corresponding value. |
2164 | (To convert strings that might start with either 0, 0x, or 0b, see | |
2165 | L</oct>.) If EXPR is omitted, uses C<$_>. | |
2f9daede TP |
2166 | |
2167 | print hex '0xAf'; # prints '175' | |
2168 | print hex 'aF'; # same | |
a0d0e21e | 2169 | |
19799a22 | 2170 | Hex strings may only represent integers. Strings that would cause |
53305cf1 NC |
2171 | integer overflow trigger a warning. Leading whitespace is not stripped, |
2172 | unlike oct(). | |
19799a22 | 2173 | |
a0d0e21e LW |
2174 | =item import |
2175 | ||
19799a22 | 2176 | There is no builtin C<import> function. It is just an ordinary |
4633a7c4 | 2177 | method (subroutine) defined (or inherited) by modules that wish to export |
19799a22 | 2178 | names to another module. The C<use> function calls the C<import> method |
cea6626f | 2179 | for the package used. See also L</use>, L<perlmod>, and L<Exporter>. |
a0d0e21e LW |
2180 | |
2181 | =item index STR,SUBSTR,POSITION | |
2182 | ||
2183 | =item index STR,SUBSTR | |
2184 | ||
2b5ab1e7 TC |
2185 | The index function searches for one string within another, but without |
2186 | the wildcard-like behavior of a full regular-expression pattern match. | |
2187 | It returns the position of the first occurrence of SUBSTR in STR at | |
2188 | or after POSITION. If POSITION is omitted, starts searching from the | |
2189 | beginning of the string. The return value is based at C<0> (or whatever | |
2190 | you've set the C<$[> variable to--but don't do that). If the substring | |
2191 | is not found, returns one less than the base, ordinarily C<-1>. | |
a0d0e21e LW |
2192 | |
2193 | =item int EXPR | |
2194 | ||
54310121 | 2195 | =item int |
bbce6d69 | 2196 | |
7660c0ab | 2197 | Returns the integer portion of EXPR. If EXPR is omitted, uses C<$_>. |
2b5ab1e7 TC |
2198 | You should not use this function for rounding: one because it truncates |
2199 | towards C<0>, and two because machine representations of floating point | |
2200 | numbers can sometimes produce counterintuitive results. For example, | |
2201 | C<int(-6.725/0.025)> produces -268 rather than the correct -269; that's | |
2202 | because it's really more like -268.99999999999994315658 instead. Usually, | |
19799a22 | 2203 | the C<sprintf>, C<printf>, or the C<POSIX::floor> and C<POSIX::ceil> |
2b5ab1e7 | 2204 | functions will serve you better than will int(). |
a0d0e21e LW |
2205 | |
2206 | =item ioctl FILEHANDLE,FUNCTION,SCALAR | |
2207 | ||
2b5ab1e7 | 2208 | Implements the ioctl(2) function. You'll probably first have to say |
a0d0e21e | 2209 | |
4633a7c4 | 2210 | require "ioctl.ph"; # probably in /usr/local/lib/perl/ioctl.ph |
a0d0e21e | 2211 | |
2b5ab1e7 | 2212 | to get the correct function definitions. If F<ioctl.ph> doesn't |
a0d0e21e | 2213 | exist or doesn't have the correct definitions you'll have to roll your |
61eff3bc | 2214 | own, based on your C header files such as F<< <sys/ioctl.h> >>. |
5a964f20 | 2215 | (There is a Perl script called B<h2ph> that comes with the Perl kit that |
54310121 | 2216 | may help you in this, but it's nontrivial.) SCALAR will be read and/or |
4633a7c4 | 2217 | written depending on the FUNCTION--a pointer to the string value of SCALAR |
19799a22 | 2218 | will be passed as the third argument of the actual C<ioctl> call. (If SCALAR |
4633a7c4 LW |
2219 | has no string value but does have a numeric value, that value will be |
2220 | passed rather than a pointer to the string value. To guarantee this to be | |
19799a22 GS |
2221 | true, add a C<0> to the scalar before using it.) The C<pack> and C<unpack> |
2222 | functions may be needed to manipulate the values of structures used by | |
b76cc8ba | 2223 | C<ioctl>. |
a0d0e21e | 2224 | |
19799a22 | 2225 | The return value of C<ioctl> (and C<fcntl>) is as follows: |
a0d0e21e LW |
2226 | |
2227 | if OS returns: then Perl returns: | |
2228 | -1 undefined value | |
2229 | 0 string "0 but true" | |
2230 | anything else that number | |
2231 | ||
19799a22 | 2232 | Thus Perl returns true on success and false on failure, yet you can |
a0d0e21e LW |
2233 | still easily determine the actual value returned by the operating |
2234 | system: | |
2235 | ||
2b5ab1e7 | 2236 | $retval = ioctl(...) || -1; |
a0d0e21e LW |
2237 | printf "System returned %d\n", $retval; |
2238 | ||
c2611fb3 | 2239 | The special string "C<0> but true" is exempt from B<-w> complaints |
5a964f20 TC |
2240 | about improper numeric conversions. |
2241 | ||
19799a22 GS |
2242 | Here's an example of setting a filehandle named C<REMOTE> to be |
2243 | non-blocking at the system level. You'll have to negotiate C<$|> | |
2244 | on your own, though. | |
2245 | ||
2246 | use Fcntl qw(F_GETFL F_SETFL O_NONBLOCK); | |
2247 | ||
2248 | $flags = fcntl(REMOTE, F_GETFL, 0) | |
2249 | or die "Can't get flags for the socket: $!\n"; | |
2250 | ||
2251 | $flags = fcntl(REMOTE, F_SETFL, $flags | O_NONBLOCK) | |
2252 | or die "Can't set flags for the socket: $!\n"; | |
2253 | ||
a0d0e21e LW |
2254 | =item join EXPR,LIST |
2255 | ||
2b5ab1e7 TC |
2256 | Joins the separate strings of LIST into a single string with fields |
2257 | separated by the value of EXPR, and returns that new string. Example: | |
a0d0e21e | 2258 | |
2b5ab1e7 | 2259 | $rec = join(':', $login,$passwd,$uid,$gid,$gcos,$home,$shell); |
a0d0e21e | 2260 | |
eb6e2d6f GS |
2261 | Beware that unlike C<split>, C<join> doesn't take a pattern as its |
2262 | first argument. Compare L</split>. | |
a0d0e21e | 2263 | |
aa689395 | 2264 | =item keys HASH |
2265 | ||
19799a22 | 2266 | Returns a list consisting of all the keys of the named hash. (In |
1d2dff63 | 2267 | scalar context, returns the number of keys.) The keys are returned in |
ab192400 GS |
2268 | an apparently random order. The actual random order is subject to |
2269 | change in future versions of perl, but it is guaranteed to be the same | |
19799a22 | 2270 | order as either the C<values> or C<each> function produces (given |
ab192400 GS |
2271 | that the hash has not been modified). As a side effect, it resets |
2272 | HASH's iterator. | |
a0d0e21e | 2273 | |
aa689395 | 2274 | Here is yet another way to print your environment: |
a0d0e21e LW |
2275 | |
2276 | @keys = keys %ENV; | |
2277 | @values = values %ENV; | |
b76cc8ba | 2278 | while (@keys) { |
a0d0e21e LW |
2279 | print pop(@keys), '=', pop(@values), "\n"; |
2280 | } | |
2281 | ||
2282 | or how about sorted by key: | |
2283 | ||
2284 | foreach $key (sort(keys %ENV)) { | |
2285 | print $key, '=', $ENV{$key}, "\n"; | |
2286 | } | |
2287 | ||
8ea1e5d4 GS |
2288 | The returned values are copies of the original keys in the hash, so |
2289 | modifying them will not affect the original hash. Compare L</values>. | |
2290 | ||
19799a22 | 2291 | To sort a hash by value, you'll need to use a C<sort> function. |
aa689395 | 2292 | Here's a descending numeric sort of a hash by its values: |
4633a7c4 | 2293 | |
5a964f20 | 2294 | foreach $key (sort { $hash{$b} <=> $hash{$a} } keys %hash) { |
4633a7c4 LW |
2295 | printf "%4d %s\n", $hash{$key}, $key; |
2296 | } | |
2297 | ||
19799a22 | 2298 | As an lvalue C<keys> allows you to increase the number of hash buckets |
aa689395 | 2299 | allocated for the given hash. This can gain you a measure of efficiency if |
2300 | you know the hash is going to get big. (This is similar to pre-extending | |
2301 | an array by assigning a larger number to $#array.) If you say | |
55497cff | 2302 | |
2303 | keys %hash = 200; | |
2304 | ||
ab192400 GS |
2305 | then C<%hash> will have at least 200 buckets allocated for it--256 of them, |
2306 | in fact, since it rounds up to the next power of two. These | |
55497cff | 2307 | buckets will be retained even if you do C<%hash = ()>, use C<undef |
2308 | %hash> if you want to free the storage while C<%hash> is still in scope. | |
2309 | You can't shrink the number of buckets allocated for the hash using | |
19799a22 | 2310 | C<keys> in this way (but you needn't worry about doing this by accident, |
55497cff | 2311 | as trying has no effect). |
2312 | ||
19799a22 | 2313 | See also C<each>, C<values> and C<sort>. |
ab192400 | 2314 | |
b350dd2f | 2315 | =item kill SIGNAL, LIST |
a0d0e21e | 2316 | |
b350dd2f | 2317 | Sends a signal to a list of processes. Returns the number of |
517db077 GS |
2318 | processes successfully signaled (which is not necessarily the |
2319 | same as the number actually killed). | |
a0d0e21e LW |
2320 | |
2321 | $cnt = kill 1, $child1, $child2; | |
2322 | kill 9, @goners; | |
2323 | ||
b350dd2f GS |
2324 | If SIGNAL is zero, no signal is sent to the process. This is a |
2325 | useful way to check that the process is alive and hasn't changed | |
2326 | its UID. See L<perlport> for notes on the portability of this | |
2327 | construct. | |
2328 | ||
2329 | Unlike in the shell, if SIGNAL is negative, it kills | |
4633a7c4 LW |
2330 | process groups instead of processes. (On System V, a negative I<PROCESS> |
2331 | number will also kill process groups, but that's not portable.) That | |
2332 | means you usually want to use positive not negative signals. You may also | |
da0045b7 | 2333 | use a signal name in quotes. See L<perlipc/"Signals"> for details. |
a0d0e21e LW |
2334 | |
2335 | =item last LABEL | |
2336 | ||
2337 | =item last | |
2338 | ||
2339 | The C<last> command is like the C<break> statement in C (as used in | |
2340 | loops); it immediately exits the loop in question. If the LABEL is | |
2341 | omitted, the command refers to the innermost enclosing loop. The | |
2342 | C<continue> block, if any, is not executed: | |
2343 | ||
4633a7c4 LW |
2344 | LINE: while (<STDIN>) { |
2345 | last LINE if /^$/; # exit when done with header | |
5a964f20 | 2346 | #... |
a0d0e21e LW |
2347 | } |
2348 | ||
4968c1e4 | 2349 | C<last> cannot be used to exit a block which returns a value such as |
2b5ab1e7 TC |
2350 | C<eval {}>, C<sub {}> or C<do {}>, and should not be used to exit |
2351 | a grep() or map() operation. | |
4968c1e4 | 2352 | |
6c1372ed GS |
2353 | Note that a block by itself is semantically identical to a loop |
2354 | that executes once. Thus C<last> can be used to effect an early | |
2355 | exit out of such a block. | |
2356 | ||
98293880 JH |
2357 | See also L</continue> for an illustration of how C<last>, C<next>, and |
2358 | C<redo> work. | |
1d2dff63 | 2359 | |
a0d0e21e LW |
2360 | =item lc EXPR |
2361 | ||
54310121 | 2362 | =item lc |
bbce6d69 | 2363 | |
d1be9408 | 2364 | Returns a lowercased version of EXPR. This is the internal function |
ad0029c4 JH |
2365 | implementing the C<\L> escape in double-quoted strings. Respects |
2366 | current LC_CTYPE locale if C<use locale> in force. See L<perllocale> | |
983ffd37 | 2367 | and L<perlunicode> for more details about locale and Unicode support. |
a0d0e21e | 2368 | |
7660c0ab | 2369 | If EXPR is omitted, uses C<$_>. |
bbce6d69 | 2370 | |
a0d0e21e LW |
2371 | =item lcfirst EXPR |
2372 | ||
54310121 | 2373 | =item lcfirst |
bbce6d69 | 2374 | |
ad0029c4 JH |
2375 | Returns the value of EXPR with the first character lowercased. This |
2376 | is the internal function implementing the C<\l> escape in | |
2377 | double-quoted strings. Respects current LC_CTYPE locale if C<use | |
983ffd37 JH |
2378 | locale> in force. See L<perllocale> and L<perlunicode> for more |
2379 | details about locale and Unicode support. | |
a0d0e21e | 2380 | |
7660c0ab | 2381 | If EXPR is omitted, uses C<$_>. |
bbce6d69 | 2382 | |
a0d0e21e LW |
2383 | =item length EXPR |
2384 | ||
54310121 | 2385 | =item length |
bbce6d69 | 2386 | |
a0ed51b3 | 2387 | Returns the length in characters of the value of EXPR. If EXPR is |
b76cc8ba | 2388 | omitted, returns length of C<$_>. Note that this cannot be used on |
2b5ab1e7 TC |
2389 | an entire array or hash to find out how many elements these have. |
2390 | For that, use C<scalar @array> and C<scalar keys %hash> respectively. | |
a0d0e21e LW |
2391 | |
2392 | =item link OLDFILE,NEWFILE | |
2393 | ||
19799a22 | 2394 | Creates a new filename linked to the old filename. Returns true for |
b76cc8ba | 2395 | success, false otherwise. |
a0d0e21e LW |
2396 | |
2397 | =item listen SOCKET,QUEUESIZE | |
2398 | ||
19799a22 | 2399 | Does the same thing that the listen system call does. Returns true if |
b76cc8ba | 2400 | it succeeded, false otherwise. See the example in |
cea6626f | 2401 | L<perlipc/"Sockets: Client/Server Communication">. |
a0d0e21e LW |
2402 | |
2403 | =item local EXPR | |
2404 | ||
19799a22 | 2405 | You really probably want to be using C<my> instead, because C<local> isn't |
b76cc8ba | 2406 | what most people think of as "local". See |
13a2d996 | 2407 | L<perlsub/"Private Variables via my()"> for details. |
2b5ab1e7 | 2408 | |
5a964f20 TC |
2409 | A local modifies the listed variables to be local to the enclosing |
2410 | block, file, or eval. If more than one value is listed, the list must | |
2411 | be placed in parentheses. See L<perlsub/"Temporary Values via local()"> | |
2412 | for details, including issues with tied arrays and hashes. | |
a0d0e21e | 2413 | |
a0d0e21e LW |
2414 | =item localtime EXPR |
2415 | ||
19799a22 | 2416 | Converts a time as returned by the time function to a 9-element list |
5f05dabc | 2417 | with the time analyzed for the local time zone. Typically used as |
a0d0e21e LW |
2418 | follows: |
2419 | ||
54310121 | 2420 | # 0 1 2 3 4 5 6 7 8 |
a0d0e21e LW |
2421 | ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = |
2422 | localtime(time); | |
2423 | ||
48a26b3a GS |
2424 | All list elements are numeric, and come straight out of the C `struct |
2425 | tm'. $sec, $min, and $hour are the seconds, minutes, and hours of the | |
2426 | specified time. $mday is the day of the month, and $mon is the month | |
2427 | itself, in the range C<0..11> with 0 indicating January and 11 | |
2428 | indicating December. $year is the number of years since 1900. That | |
2429 | is, $year is C<123> in year 2023. $wday is the day of the week, with | |
2430 | 0 indicating Sunday and 3 indicating Wednesday. $yday is the day of | |
874b1813 | 2431 | the year, in the range C<0..364> (or C<0..365> in leap years.) $isdst |
48a26b3a GS |
2432 | is true if the specified time occurs during daylight savings time, |
2433 | false otherwise. | |
2434 | ||
2435 | Note that the $year element is I<not> simply the last two digits of | |
2436 | the year. If you assume it is, then you create non-Y2K-compliant | |
2437 | programs--and you wouldn't want to do that, would you? | |
54310121 | 2438 | |
abd75f24 GS |
2439 | The proper way to get a complete 4-digit year is simply: |
2440 | ||
2441 | $year += 1900; | |
2442 | ||
2443 | And to get the last two digits of the year (e.g., '01' in 2001) do: | |
2444 | ||
2445 | $year = sprintf("%02d", $year % 100); | |
2446 | ||
48a26b3a | 2447 | If EXPR is omitted, C<localtime()> uses the current time (C<localtime(time)>). |
a0d0e21e | 2448 | |
48a26b3a | 2449 | In scalar context, C<localtime()> returns the ctime(3) value: |
a0d0e21e | 2450 | |
5f05dabc | 2451 | $now_string = localtime; # e.g., "Thu Oct 13 04:54:34 1994" |
a0d0e21e | 2452 | |
a3cb178b | 2453 | This scalar value is B<not> locale dependent, see L<perllocale>, but |
68f8bed4 JH |
2454 | instead a Perl builtin. Also see the C<Time::Local> module |
2455 | (to convert the second, minutes, hours, ... back to seconds since the | |
2456 | stroke of midnight the 1st of January 1970, the value returned by | |
ca6e1c26 | 2457 | time()), and the strftime(3) and mktime(3) functions available via the |
68f8bed4 JH |
2458 | POSIX module. To get somewhat similar but locale dependent date |
2459 | strings, set up your locale environment variables appropriately | |
2460 | (please see L<perllocale>) and try for example: | |
a3cb178b | 2461 | |
5a964f20 | 2462 | use POSIX qw(strftime); |
2b5ab1e7 | 2463 | $now_string = strftime "%a %b %e %H:%M:%S %Y", localtime; |
a3cb178b GS |
2464 | |
2465 | Note that the C<%a> and C<%b>, the short forms of the day of the week | |
2466 | and the month of the year, may not necessarily be three characters wide. | |
a0d0e21e | 2467 | |
07698885 | 2468 | =item lock THING |
19799a22 GS |
2469 | |
2470 | This function places an advisory lock on a variable, subroutine, | |
2471 | or referenced object contained in I<THING> until the lock goes out | |
2472 | of scope. This is a built-in function only if your version of Perl | |
43d3ddbe JH |
2473 | was built with threading enabled, and if you've said C<use Thread>. |
2474 | Otherwise a user-defined function by this name will be called. | |
2475 | See L<Thread>. | |
19799a22 | 2476 | |
a0d0e21e LW |
2477 | =item log EXPR |
2478 | ||
54310121 | 2479 | =item log |
bbce6d69 | 2480 | |
2b5ab1e7 TC |
2481 | Returns the natural logarithm (base I<e>) of EXPR. If EXPR is omitted, |
2482 | returns log of C<$_>. To get the log of another base, use basic algebra: | |
19799a22 | 2483 | The base-N log of a number is equal to the natural log of that number |
2b5ab1e7 TC |
2484 | divided by the natural log of N. For example: |
2485 | ||
2486 | sub log10 { | |
2487 | my $n = shift; | |
2488 | return log($n)/log(10); | |
b76cc8ba | 2489 | } |
2b5ab1e7 TC |
2490 | |
2491 | See also L</exp> for the inverse operation. | |
a0d0e21e | 2492 | |
a0d0e21e LW |
2493 | =item lstat EXPR |
2494 | ||
54310121 | 2495 | =item lstat |
bbce6d69 | 2496 | |
19799a22 | 2497 | Does the same thing as the C<stat> function (including setting the |
5a964f20 TC |
2498 | special C<_> filehandle) but stats a symbolic link instead of the file |
2499 | the symbolic link points to. If symbolic links are unimplemented on | |
19799a22 | 2500 | your system, a normal C<stat> is done. |
a0d0e21e | 2501 | |
7660c0ab | 2502 | If EXPR is omitted, stats C<$_>. |
bbce6d69 | 2503 | |
a0d0e21e LW |
2504 | =item m// |
2505 | ||
2506 | The match operator. See L<perlop>. | |
2507 | ||
2508 | =item map BLOCK LIST | |
2509 | ||
2510 | =item map EXPR,LIST | |
2511 | ||
19799a22 GS |
2512 | Evaluates the BLOCK or EXPR for each element of LIST (locally setting |
2513 | C<$_> to each element) and returns the list value composed of the | |
2514 | results of each such evaluation. In scalar context, returns the | |
2515 | total number of elements so generated. Evaluates BLOCK or EXPR in | |
2516 | list context, so each element of LIST may produce zero, one, or | |
2517 | more elements in the returned value. | |
dd99ebda | 2518 | |
a0d0e21e LW |
2519 | @chars = map(chr, @nums); |
2520 | ||
2521 | translates a list of numbers to the corresponding characters. And | |
2522 | ||
4633a7c4 | 2523 | %hash = map { getkey($_) => $_ } @array; |
a0d0e21e LW |
2524 | |
2525 | is just a funny way to write | |
2526 | ||
2527 | %hash = (); | |
2528 | foreach $_ (@array) { | |
4633a7c4 | 2529 | $hash{getkey($_)} = $_; |
a0d0e21e LW |
2530 | } |
2531 | ||
be3174d2 GS |
2532 | Note that C<$_> is an alias to the list value, so it can be used to |
2533 | modify the elements of the LIST. While this is useful and supported, | |
2534 | it can cause bizarre results if the elements of LIST are not variables. | |
2b5ab1e7 TC |
2535 | Using a regular C<foreach> loop for this purpose would be clearer in |
2536 | most cases. See also L</grep> for an array composed of those items of | |
2537 | the original list for which the BLOCK or EXPR evaluates to true. | |
fb73857a | 2538 | |
205fdb4d NC |
2539 | C<{> starts both hash references and blocks, so C<map { ...> could be either |
2540 | the start of map BLOCK LIST or map EXPR, LIST. Because perl doesn't look | |
2541 | ahead for the closing C<}> it has to take a guess at which its dealing with | |
2542 | based what it finds just after the C<{>. Usually it gets it right, but if it | |
2543 | doesn't it won't realize something is wrong until it gets to the C<}> and | |
2544 | encounters the missing (or unexpected) comma. The syntax error will be | |
2545 | reported close to the C<}> but you'll need to change something near the C<{> | |
2546 | such as using a unary C<+> to give perl some help: | |
2547 | ||
2548 | %hash = map { "\L$_", 1 } @array # perl guesses EXPR. wrong | |
2549 | %hash = map { +"\L$_", 1 } @array # perl guesses BLOCK. right | |
2550 | %hash = map { ("\L$_", 1) } @array # this also works | |
2551 | %hash = map { lc($_), 1 } @array # as does this. | |
2552 | %hash = map +( lc($_), 1 ), @array # this is EXPR and works! | |
cea6626f | 2553 | |
205fdb4d NC |
2554 | %hash = map ( lc($_), 1 ), @array # evaluates to (1, @array) |
2555 | ||
2556 | or to force an anon hash constructor use C<+{> | |
2557 | ||
2558 | @hashes = map +{ lc($_), 1 }, @array # EXPR, so needs , at end | |
2559 | ||
2560 | and you get list of anonymous hashes each with only 1 entry. | |
2561 | ||
19799a22 | 2562 | =item mkdir FILENAME,MASK |
a0d0e21e | 2563 | |
5a211162 GS |
2564 | =item mkdir FILENAME |
2565 | ||
0591cd52 | 2566 | Creates the directory specified by FILENAME, with permissions |
19799a22 GS |
2567 | specified by MASK (as modified by C<umask>). If it succeeds it |
2568 | returns true, otherwise it returns false and sets C<$!> (errno). | |
5a211162 | 2569 | If omitted, MASK defaults to 0777. |
0591cd52 | 2570 | |
19799a22 | 2571 | In general, it is better to create directories with permissive MASK, |
0591cd52 | 2572 | and let the user modify that with their C<umask>, than it is to supply |
19799a22 | 2573 | a restrictive MASK and give the user no way to be more permissive. |
0591cd52 NT |
2574 | The exceptions to this rule are when the file or directory should be |
2575 | kept private (mail files, for instance). The perlfunc(1) entry on | |
19799a22 | 2576 | C<umask> discusses the choice of MASK in more detail. |
a0d0e21e | 2577 | |
cc1852e8 JH |
2578 | Note that according to the POSIX 1003.1-1996 the FILENAME may have any |
2579 | number of trailing slashes. Some operating and filesystems do not get | |
2580 | this right, so Perl automatically removes all trailing slashes to keep | |
2581 | everyone happy. | |
2582 | ||
a0d0e21e LW |
2583 | =item msgctl ID,CMD,ARG |
2584 | ||
f86cebdf | 2585 | Calls the System V IPC function msgctl(2). You'll probably have to say |
0ade1984 JH |
2586 | |
2587 | use IPC::SysV; | |
2588 | ||
7660c0ab A |
2589 | first to get the correct constant definitions. If CMD is C<IPC_STAT>, |
2590 | then ARG must be a variable which will hold the returned C<msqid_ds> | |
951ba7fe GS |
2591 | structure. Returns like C<ioctl>: the undefined value for error, |
2592 | C<"0 but true"> for zero, or the actual return value otherwise. See also | |
4755096e | 2593 | L<perlipc/"SysV IPC">, C<IPC::SysV>, and C<IPC::Semaphore> documentation. |
a0d0e21e LW |
2594 | |
2595 | =item msgget KEY,FLAGS | |
2596 | ||
f86cebdf | 2597 | Calls the System V IPC function msgget(2). Returns the message queue |
4755096e GS |
2598 | id, or the undefined value if there is an error. See also |
2599 | L<perlipc/"SysV IPC"> and C<IPC::SysV> and C<IPC::Msg> documentation. | |
a0d0e21e | 2600 | |
a0d0e21e LW |
2601 | =item msgrcv ID,VAR,SIZE,TYPE,FLAGS |
2602 | ||
2603 | Calls the System V IPC function msgrcv to receive a message from | |
2604 | message queue ID into variable VAR with a maximum message size of | |
41d6edb2 JH |
2605 | SIZE. Note that when a message is received, the message type as a |
2606 | native long integer will be the first thing in VAR, followed by the | |
2607 | actual message. This packing may be opened with C<unpack("l! a*")>. | |
2608 | Taints the variable. Returns true if successful, or false if there is | |
4755096e GS |
2609 | an error. See also L<perlipc/"SysV IPC">, C<IPC::SysV>, and |
2610 | C<IPC::SysV::Msg> documentation. | |
41d6edb2 JH |
2611 | |
2612 | =item msgsnd ID,MSG,FLAGS | |
2613 | ||
2614 | Calls the System V IPC function msgsnd to send the message MSG to the | |
2615 | message queue ID. MSG must begin with the native long integer message | |
2616 | type, and be followed by the length of the actual message, and finally | |
2617 | the message itself. This kind of packing can be achieved with | |
2618 | C<pack("l! a*", $type, $message)>. Returns true if successful, | |
2619 | or false if there is an error. See also C<IPC::SysV> | |
2620 | and C<IPC::SysV::Msg> documentation. | |
a0d0e21e LW |
2621 | |
2622 | =item my EXPR | |
2623 | ||
09bef843 SB |
2624 | =item my EXPR : ATTRIBUTES |
2625 | ||
19799a22 GS |
2626 | A C<my> declares the listed variables to be local (lexically) to the |
2627 | enclosing block, file, or C<eval>. If | |
5f05dabc | 2628 | more than one value is listed, the list must be placed in parentheses. See |
cb1a09d0 | 2629 | L<perlsub/"Private Variables via my()"> for details. |
4633a7c4 | 2630 | |
a0d0e21e LW |
2631 | =item next LABEL |
2632 | ||
2633 | =item next | |
2634 | ||
2635 | The C<next> command is like the C<continue> statement in C; it starts | |
2636 | the next iteration of the loop: | |
2637 | ||
4633a7c4 LW |
2638 | LINE: while (<STDIN>) { |
2639 | next LINE if /^#/; # discard comments | |
5a964f20 | 2640 | #... |
a0d0e21e LW |
2641 | } |
2642 | ||
2643 | Note that if there were a C<continue> block on the above, it would get | |
2644 | executed even on discarded lines. If the LABEL is omitted, the command | |
2645 | refers to the innermost enclosing loop. | |
2646 | ||
4968c1e4 | 2647 | C<next> cannot be used to exit a block which returns a value such as |
2b5ab1e7 TC |
2648 | C<eval {}>, C<sub {}> or C<do {}>, and should not be used to exit |
2649 | a grep() or map() operation. | |
4968c1e4 | 2650 | |
6c1372ed GS |
2651 | Note that a block by itself is semantically identical to a loop |
2652 | that executes once. Thus C<next> will exit such a block early. | |
2653 | ||
98293880 JH |
2654 | See also L</continue> for an illustration of how C<last>, C<next>, and |
2655 | C<redo> work. | |
1d2dff63 | 2656 | |
4a66ea5a RGS |
2657 | =item no Module VERSION LIST |
2658 | ||
2659 | =item no Module VERSION | |
2660 | ||
a0d0e21e LW |
2661 | =item no Module LIST |
2662 | ||
4a66ea5a RGS |
2663 | =item no Module |
2664 | ||
7660c0ab | 2665 | See the L</use> function, which C<no> is the opposite of. |
a0d0e21e LW |
2666 | |
2667 | =item oct EXPR | |
2668 | ||
54310121 | 2669 | =item oct |
bbce6d69 | 2670 | |
4633a7c4 | 2671 | Interprets EXPR as an octal string and returns the corresponding |
4f19785b WSI |
2672 | value. (If EXPR happens to start off with C<0x>, interprets it as a |
2673 | hex string. If EXPR starts off with C<0b>, it is interpreted as a | |
53305cf1 NC |
2674 | binary string. Leading whitespace is ignored in all three cases.) |
2675 | The following will handle decimal, binary, octal, and hex in the standard | |
2676 | Perl or C notation: | |
a0d0e21e LW |
2677 | |
2678 | $val = oct($val) if $val =~ /^0/; | |
2679 | ||
19799a22 GS |
2680 | If EXPR is omitted, uses C<$_>. To go the other way (produce a number |
2681 | in octal), use sprintf() or printf(): | |
2682 | ||
2683 | $perms = (stat("filename"))[2] & 07777; | |
2684 | $oct_perms = sprintf "%lo", $perms; | |
2685 | ||
2686 | The oct() function is commonly used when a string such as C<644> needs | |
2687 | to be converted into a file mode, for example. (Although perl will | |
2688 | automatically convert strings into numbers as needed, this automatic | |
2689 | conversion assumes base 10.) | |
a0d0e21e LW |
2690 | |
2691 | =item open FILEHANDLE,EXPR | |
2692 | ||
68bd7414 NIS |
2693 | =item open FILEHANDLE,MODE,EXPR |
2694 | ||
2695 | =item open FILEHANDLE,MODE,EXPR,LIST | |
2696 | ||
ba964c95 T |
2697 | =item open FILEHANDLE,MODE,REFERENCE |
2698 | ||
a0d0e21e LW |
2699 | =item open FILEHANDLE |
2700 | ||
2701 | Opens the file whose filename is given by EXPR, and associates it with | |
ed53a2bb JH |
2702 | FILEHANDLE. |
2703 | ||
2704 | (The following is a comprehensive reference to open(): for a gentler | |
2705 | introduction you may consider L<perlopentut>.) | |
2706 | ||
2707 | If FILEHANDLE is an undefined lexical (C<my>) variable the variable is | |
2708 | assigned a reference to a new anonymous filehandle, otherwise if | |
2709 | FILEHANDLE is an expression, its value is used as the name of the real | |
2710 | filehandle wanted. (This is considered a symbolic reference, so C<use | |
2711 | strict 'refs'> should I<not> be in effect.) | |
2712 | ||
2713 | If EXPR is omitted, the scalar variable of the same name as the | |
2714 | FILEHANDLE contains the filename. (Note that lexical variables--those | |
2715 | declared with C<my>--will not work for this purpose; so if you're | |
2716 | using C<my>, specify EXPR in your call to open.) | |
2717 | ||
2718 | If three or more arguments are specified then the mode of opening and | |
2719 | the file name are separate. If MODE is C<< '<' >> or nothing, the file | |
2720 | is opened for input. If MODE is C<< '>' >>, the file is truncated and | |
2721 | opened for output, being created if necessary. If MODE is C<<< '>>' >>>, | |
b76cc8ba | 2722 | the file is opened for appending, again being created if necessary. |
5a964f20 | 2723 | |
ed53a2bb JH |
2724 | You can put a C<'+'> in front of the C<< '>' >> or C<< '<' >> to |
2725 | indicate that you want both read and write access to the file; thus | |
2726 | C<< '+<' >> is almost always preferred for read/write updates--the C<< | |
2727 | '+>' >> mode would clobber the file first. You can't usually use | |
2728 | either read-write mode for updating textfiles, since they have | |
2729 | variable length records. See the B<-i> switch in L<perlrun> for a | |
2730 | better approach. The file is created with permissions of C<0666> | |
2731 | modified by the process' C<umask> value. | |
2732 | ||
2733 | These various prefixes correspond to the fopen(3) modes of C<'r'>, | |
2734 | C<'r+'>, C<'w'>, C<'w+'>, C<'a'>, and C<'a+'>. | |
5f05dabc | 2735 | |
6170680b IZ |
2736 | In the 2-arguments (and 1-argument) form of the call the mode and |
2737 | filename should be concatenated (in this order), possibly separated by | |
68bd7414 NIS |
2738 | spaces. It is possible to omit the mode in these forms if the mode is |
2739 | C<< '<' >>. | |
6170680b | 2740 | |
7660c0ab | 2741 | If the filename begins with C<'|'>, the filename is interpreted as a |
5a964f20 | 2742 | command to which output is to be piped, and if the filename ends with a |
f244e06d GS |
2743 | C<'|'>, the filename is interpreted as a command which pipes output to |
2744 | us. See L<perlipc/"Using open() for IPC"> | |
19799a22 | 2745 | for more examples of this. (You are not allowed to C<open> to a command |
5a964f20 | 2746 | that pipes both in I<and> out, but see L<IPC::Open2>, L<IPC::Open3>, |
4a4eefd0 GS |
2747 | and L<perlipc/"Bidirectional Communication with Another Process"> |
2748 | for alternatives.) | |
cb1a09d0 | 2749 | |
ed53a2bb JH |
2750 | For three or more arguments if MODE is C<'|-'>, the filename is |
2751 | interpreted as a command to which output is to be piped, and if MODE | |
2752 | is C<'-|'>, the filename is interpreted as a command which pipes | |
2753 | output to us. In the 2-arguments (and 1-argument) form one should | |
2754 | replace dash (C<'-'>) with the command. | |
2755 | See L<perlipc/"Using open() for IPC"> for more examples of this. | |
2756 | (You are not allowed to C<open> to a command that pipes both in I<and> | |
2757 | out, but see L<IPC::Open2>, L<IPC::Open3>, and | |
2758 | L<perlipc/"Bidirectional Communication"> for alternatives.) | |
2759 | ||
2760 | In the three-or-more argument form of pipe opens, if LIST is specified | |
2761 | (extra arguments after the command name) then LIST becomes arguments | |
2762 | to the command invoked if the platform supports it. The meaning of | |
2763 | C<open> with more than three arguments for non-pipe modes is not yet | |
2764 | specified. Experimental "layers" may give extra LIST arguments | |
2765 | meaning. | |
6170680b IZ |
2766 | |
2767 | In the 2-arguments (and 1-argument) form opening C<'-'> opens STDIN | |
b76cc8ba | 2768 | and opening C<< '>-' >> opens STDOUT. |
6170680b | 2769 | |
ed53a2bb JH |
2770 | You may use the three-argument form of open to specify |
2771 | I<I/O disciplines> that affect how the input and output | |
9124316e | 2772 | are processed: see L</binmode> and L<open>. For example |
7207e29d | 2773 | |
9124316e JH |
2774 | open(FH, "<:utf8", "file") |
2775 | ||
2776 | will open the UTF-8 encoded file containing Unicode characters, | |
2777 | see L<perluniintro>. | |
ed53a2bb JH |
2778 | |
2779 | Open returns nonzero upon success, the undefined value otherwise. If | |
2780 | the C<open> involved a pipe, the return value happens to be the pid of | |
2781 | the subprocess. | |
cb1a09d0 | 2782 | |
ed53a2bb JH |
2783 | If you're running Perl on a system that distinguishes between text |
2784 | files and binary files, then you should check out L</binmode> for tips | |
2785 | for dealing with this. The key distinction between systems that need | |
2786 | C<binmode> and those that don't is their text file formats. Systems | |
2787 | like Unix, MacOS, and Plan9, which delimit lines with a single | |
2788 | character, and which encode that character in C as C<"\n">, do not | |
2789 | need C<binmode>. The rest need it. | |
cb1a09d0 | 2790 | |
ed53a2bb JH |
2791 | In the three argument form MODE may also contain a list of IO "layers" |
2792 | (see L<open> and L<PerlIO> for more details) to be applied to the | |
2793 | handle. This can be used to achieve the effect of C<binmode> as well | |
2794 | as more complex behaviours. | |
68bd7414 | 2795 | |
fb73857a | 2796 | When opening a file, it's usually a bad idea to continue normal execution |
19799a22 GS |
2797 | if the request failed, so C<open> is frequently used in connection with |
2798 | C<die>. Even if C<die> won't do what you want (say, in a CGI script, | |
fb73857a | 2799 | where you want to make a nicely formatted error message (but there are |
5a964f20 | 2800 | modules that can help with that problem)) you should always check |
19799a22 | 2801 | the return value from opening a file. The infrequent exception is when |
fb73857a | 2802 | working with an unopened filehandle is actually what you want to do. |
2803 | ||
ed53a2bb JH |
2804 | As a special case the 3 arg form with a read/write mode and the third |
2805 | argument being C<undef>: | |
b76cc8ba NIS |
2806 | |
2807 | open(TMP, "+>", undef) or die ... | |
2808 | ||
2809 | opens a filehandle to an anonymous temporary file. | |
2810 | ||
ba964c95 T |
2811 | File handles can be opened to "in memory" files held in Perl scalars via: |
2812 | ||
b996200f SB |
2813 | open($fh, '>', \$variable) || .. |
2814 | ||
2815 | Though if you try to re-open C<STDOUT> or C<STDERR> as an "in memory" | |
2816 | file, you have to close it first: | |
2817 | ||
2818 | close STDOUT; | |
2819 | open STDOUT, '>', \$variable or die "Can't open STDOUT: $!"; | |
ba964c95 | 2820 | |
cb1a09d0 | 2821 | Examples: |
a0d0e21e LW |
2822 | |
2823 | $ARTICLE = 100; | |
2824 | open ARTICLE or die "Can't find article $ARTICLE: $!\n"; | |
2825 | while (<ARTICLE>) {... | |
2826 | ||
6170680b | 2827 | open(LOG, '>>/usr/spool/news/twitlog'); # (log is reserved) |
fb73857a | 2828 | # if the open fails, output is discarded |
a0d0e21e | 2829 | |
6170680b | 2830 | open(DBASE, '+<', 'dbase.mine') # open for update |
fb73857a | 2831 | or die "Can't open 'dbase.mine' for update: $!"; |
cb1a09d0 | 2832 | |
6170680b IZ |
2833 | open(DBASE, '+<dbase.mine') # ditto |
2834 | or die "Can't open 'dbase.mine' for update: $!"; | |
2835 | ||
2836 | open(ARTICLE, '-|', "caesar <$article") # decrypt article | |
fb73857a | 2837 | or die "Can't start caesar: $!"; |
a0d0e21e | 2838 | |
6170680b IZ |
2839 | open(ARTICLE, "caesar <$article |") # ditto |
2840 | or die "Can't start caesar: $!"; | |
2841 | ||
2842 | open(EXTRACT, "|sort >/tmp/Tmp$$") # $$ is our process id | |
fb73857a | 2843 | or die "Can't start sort: $!"; |
a0d0e21e | 2844 | |
ba964c95 T |
2845 | # in memory files |
2846 | open(MEMORY,'>', \$var) | |
2847 | or die "Can't open memory file: $!"; | |
2848 | print MEMORY "foo!\n"; # output will end up in $var | |
2849 | ||
a0d0e21e LW |
2850 | # process argument list of files along with any includes |
2851 | ||
2852 | foreach $file (@ARGV) { | |
2853 | process($file, 'fh00'); | |
2854 | } | |
2855 | ||
2856 | sub process { | |
5a964f20 | 2857 | my($filename, $input) = @_; |
a0d0e21e LW |
2858 | $input++; # this is a string increment |
2859 | unless (open($input, $filename)) { | |
2860 | print STDERR "Can't open $filename: $!\n"; | |
2861 | return; | |
2862 | } | |
2863 | ||
5a964f20 | 2864 | local $_; |
a0d0e21e LW |
2865 | while (<$input>) { # note use of indirection |
2866 | if (/^#include "(.*)"/) { | |
2867 | process($1, $input); | |
2868 | next; | |
2869 | } | |
5a964f20 | 2870 | #... # whatever |
a0d0e21e LW |
2871 | } |
2872 | } | |
2873 | ||
2874 | You may also, in the Bourne shell tradition, specify an EXPR beginning | |
61eff3bc | 2875 | with C<< '>&' >>, in which case the rest of the string is interpreted as the |
5a964f20 | 2876 | name of a filehandle (or file descriptor, if numeric) to be |
61eff3bc JH |
2877 | duped and opened. You may use C<&> after C<< > >>, C<<< >> >>>, |
2878 | C<< < >>, C<< +> >>, C<<< +>> >>>, and C<< +< >>. The | |
a0d0e21e | 2879 | mode you specify should match the mode of the original filehandle. |
184e9718 | 2880 | (Duping a filehandle does not take into account any existing contents of |
9124316e | 2881 | IO buffers.) If you use the 3 arg form then you can pass either a number, |
b76cc8ba | 2882 | the name of a filehandle or the normal "reference to a glob". |
6170680b | 2883 | |
eae1b76b SB |
2884 | Here is a script that saves, redirects, and restores C<STDOUT> and |
2885 | C<STDERR> using various methods: | |
a0d0e21e LW |
2886 | |
2887 | #!/usr/bin/perl | |
eae1b76b SB |
2888 | open my $oldout, ">&STDOUT" or die "Can't dup STDOUT: $!"; |
2889 | open OLDERR, ">&", \*STDERR or die "Can't dup STDERR: $!"; | |
2890 | ||
2891 | open STDOUT, '>', "foo.out" or die "Can't redirect STDOUT: $!"; | |
2892 | open STDERR, ">&STDOUT" or die "Can't dup STDOUT: $!"; | |
a0d0e21e | 2893 | |
eae1b76b SB |
2894 | select STDERR; $| = 1; # make unbuffered |
2895 | select STDOUT; $| = 1; # make unbuffered | |
a0d0e21e LW |
2896 | |
2897 | print STDOUT "stdout 1\n"; # this works for | |
2898 | print STDERR "stderr 1\n"; # subprocesses too | |
2899 | ||
eae1b76b SB |
2900 | close STDOUT; |
2901 | close STDERR; | |
a0d0e21e | 2902 | |
eae1b76b SB |
2903 | open STDOUT, ">&", $oldout or die "Can't dup \$oldout: $!"; |
2904 | open STDERR, ">&OLDERR" or die "Can't dup OLDERR: $!"; | |
a0d0e21e LW |
2905 | |
2906 | print STDOUT "stdout 2\n"; | |
2907 | print STDERR "stderr 2\n"; | |
2908 | ||
df632fdf JH |
2909 | If you specify C<< '<&=N' >>, where C<N> is a number, then Perl will |
2910 | do an equivalent of C's C<fdopen> of that file descriptor; this is | |
2911 | more parsimonious of file descriptors. For example: | |
a0d0e21e LW |
2912 | |
2913 | open(FILEHANDLE, "<&=$fd") | |
df632fdf | 2914 | |
b76cc8ba | 2915 | or |
df632fdf | 2916 | |
b76cc8ba | 2917 | open(FILEHANDLE, "<&=", $fd) |
a0d0e21e | 2918 | |
df632fdf JH |
2919 | Note that if Perl is using the standard C libraries' fdopen() then on |
2920 | many UNIX systems, fdopen() is known to fail when file descriptors | |
4af147f6 | 2921 | exceed a certain value, typically 255. If you need more file |
b76cc8ba | 2922 | descriptors than that, consider rebuilding Perl to use the C<PerlIO>. |
4af147f6 | 2923 | |
df632fdf JH |
2924 | You can see whether Perl has been compiled with PerlIO or not by |
2925 | running C<perl -V> and looking for C<useperlio=> line. If C<useperlio> | |
2926 | is C<define>, you have PerlIO, otherwise you don't. | |
2927 | ||
6170680b IZ |
2928 | If you open a pipe on the command C<'-'>, i.e., either C<'|-'> or C<'-|'> |
2929 | with 2-arguments (or 1-argument) form of open(), then | |
a0d0e21e | 2930 | there is an implicit fork done, and the return value of open is the pid |
7660c0ab | 2931 | of the child within the parent process, and C<0> within the child |
184e9718 | 2932 | process. (Use C<defined($pid)> to determine whether the open was successful.) |
a0d0e21e LW |
2933 | The filehandle behaves normally for the parent, but i/o to that |
2934 | filehandle is piped from/to the STDOUT/STDIN of the child process. | |
2935 | In the child process the filehandle isn't opened--i/o happens from/to | |
2936 | the new STDOUT or STDIN. Typically this is used like the normal | |
2937 | piped open when you want to exercise more control over just how the | |
2938 | pipe command gets executed, such as when you are running setuid, and | |
54310121 | 2939 | don't want to have to scan shell commands for metacharacters. |
6170680b | 2940 | The following triples are more or less equivalent: |
a0d0e21e LW |
2941 | |
2942 | open(FOO, "|tr '[a-z]' '[A-Z]'"); | |
6170680b IZ |
2943 | open(FOO, '|-', "tr '[a-z]' '[A-Z]'"); |
2944 | open(FOO, '|-') || exec 'tr', '[a-z]', '[A-Z]'; | |
b76cc8ba | 2945 | open(FOO, '|-', "tr", '[a-z]', '[A-Z]'); |
a0d0e21e LW |
2946 | |
2947 | open(FOO, "cat -n '$file'|"); | |
6170680b IZ |
2948 | open(FOO, '-|', "cat -n '$file'"); |
2949 | open(FOO, '-|') || exec 'cat', '-n', $file; | |
b76cc8ba NIS |
2950 | open(FOO, '-|', "cat", '-n', $file); |
2951 | ||
2952 | The last example in each block shows the pipe as "list form", which is | |
2953 | not yet supported on all platforms. | |
a0d0e21e | 2954 | |
4633a7c4 LW |
2955 | See L<perlipc/"Safe Pipe Opens"> for more examples of this. |
2956 | ||
0f897271 GS |
2957 | Beginning with v5.6.0, Perl will attempt to flush all files opened for |
2958 | output before any operation that may do a fork, but this may not be | |
2959 | supported on some platforms (see L<perlport>). To be safe, you may need | |
2960 | to set C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method | |
2961 | of C<IO::Handle> on any open handles. | |
2962 | ||
ed53a2bb JH |
2963 | On systems that support a close-on-exec flag on files, the flag will |
2964 | be set for the newly opened file descriptor as determined by the value | |
2965 | of $^F. See L<perlvar/$^F>. | |
a0d0e21e | 2966 | |
0dccf244 CS |
2967 | Closing any piped filehandle causes the parent process to wait for the |
2968 | child to finish, and returns the status value in C<$?>. | |
2969 | ||
ed53a2bb JH |
2970 | The filename passed to 2-argument (or 1-argument) form of open() will |
2971 | have leading and trailing whitespace deleted, and the normal | |
2972 | redirection characters honored. This property, known as "magic open", | |
5a964f20 | 2973 | can often be used to good effect. A user could specify a filename of |
7660c0ab | 2974 | F<"rsh cat file |">, or you could change certain filenames as needed: |
5a964f20 TC |
2975 | |
2976 | $filename =~ s/(.*\.gz)\s*$/gzip -dc < $1|/; | |
2977 | open(FH, $filename) or die "Can't open $filename: $!"; | |
2978 | ||
6170680b IZ |
2979 | Use 3-argument form to open a file with arbitrary weird characters in it, |
2980 | ||
2981 | open(FOO, '<', $file); | |
2982 | ||
2983 | otherwise it's necessary to protect any leading and trailing whitespace: | |
5a964f20 TC |
2984 | |
2985 | $file =~ s#^(\s)#./$1#; | |
2986 | open(FOO, "< $file\0"); | |
2987 | ||
a31a806a | 2988 | (this may not work on some bizarre filesystems). One should |
106325ad | 2989 | conscientiously choose between the I<magic> and 3-arguments form |
6170680b IZ |
2990 | of open(): |
2991 | ||
2992 | open IN, $ARGV[0]; | |
2993 | ||
2994 | will allow the user to specify an argument of the form C<"rsh cat file |">, | |
2995 | but will not work on a filename which happens to have a trailing space, while | |
2996 | ||
2997 | open IN, '<', $ARGV[0]; | |
2998 | ||
2999 | will have exactly the opposite restrictions. | |
3000 | ||
19799a22 | 3001 | If you want a "real" C C<open> (see L<open(2)> on your system), then you |
6170680b IZ |
3002 | should use the C<sysopen> function, which involves no such magic (but |
3003 | may use subtly different filemodes than Perl open(), which is mapped | |
3004 | to C fopen()). This is | |
5a964f20 TC |
3005 | another way to protect your filenames from interpretation. For example: |
3006 | ||
3007 | use IO::Handle; | |
3008 | sysopen(HANDLE, $path, O_RDWR|O_CREAT|O_EXCL) | |
3009 | or die "sysopen $path: $!"; | |
3010 | $oldfh = select(HANDLE); $| = 1; select($oldfh); | |
38762f02 | 3011 | print HANDLE "stuff $$\n"; |
5a964f20 TC |
3012 | seek(HANDLE, 0, 0); |
3013 | print "File contains: ", <HANDLE>; | |
3014 | ||
7660c0ab A |
3015 | Using the constructor from the C<IO::Handle> package (or one of its |
3016 | subclasses, such as C<IO::File> or C<IO::Socket>), you can generate anonymous | |
5a964f20 TC |
3017 | filehandles that have the scope of whatever variables hold references to |
3018 | them, and automatically close whenever and however you leave that scope: | |
c07a80fd | 3019 | |
5f05dabc | 3020 | use IO::File; |
5a964f20 | 3021 | #... |
c07a80fd | 3022 | sub read_myfile_munged { |
3023 | my $ALL = shift; | |
5f05dabc | 3024 | my $handle = new IO::File; |
c07a80fd | 3025 | open($handle, "myfile") or die "myfile: $!"; |
3026 | $first = <$handle> | |
3027 | or return (); # Automatically closed here. | |
3028 | mung $first or die "mung failed"; # Or here. | |
3029 | return $first, <$handle> if $ALL; # Or here. | |
3030 | $first; # Or here. | |
3031 | } | |
3032 | ||
b687b08b | 3033 | See L</seek> for some details about mixing reading and writing. |
a0d0e21e LW |
3034 | |
3035 | =item opendir DIRHANDLE,EXPR | |
3036 | ||
19799a22 GS |
3037 | Opens a directory named EXPR for processing by C<readdir>, C<telldir>, |
3038 | C<seekdir>, C<rewinddir>, and C<closedir>. Returns true if successful. | |
a0d0e21e LW |
3039 | DIRHANDLEs have their own namespace separate from FILEHANDLEs. |
3040 | ||
3041 | =item ord EXPR | |
3042 | ||
54310121 | 3043 | =item ord |
bbce6d69 | 3044 | |
121910a4 JH |
3045 | Returns the numeric (the native 8-bit encoding, like ASCII or EBCDIC, |
3046 | or Unicode) value of the first character of EXPR. If EXPR is omitted, | |
3047 | uses C<$_>. | |
3048 | ||
3049 | For the reverse, see L</chr>. | |
3050 | See L<perlunicode> and L<encoding> for more about Unicode. | |
a0d0e21e | 3051 | |
77ca0c92 LW |
3052 | =item our EXPR |
3053 | ||
9969eac4 BS |
3054 | =item our EXPR : ATTRIBUTES |
3055 | ||
77ca0c92 LW |
3056 | An C<our> declares the listed variables to be valid globals within |
3057 | the enclosing block, file, or C<eval>. That is, it has the same | |
3058 | scoping rules as a "my" declaration, but does not create a local | |
3059 | variable. If more than one value is listed, the list must be placed | |
3060 | in parentheses. The C<our> declaration has no semantic effect unless | |
3061 | "use strict vars" is in effect, in which case it lets you use the | |
3062 | declared global variable without qualifying it with a package name. | |
3063 | (But only within the lexical scope of the C<our> declaration. In this | |
3064 | it differs from "use vars", which is package scoped.) | |
3065 | ||
f472eb5c GS |
3066 | An C<our> declaration declares a global variable that will be visible |
3067 | across its entire lexical scope, even across package boundaries. The | |
3068 | package in which the variable is entered is determined at the point | |
3069 | of the declaration, not at the point of use. This means the following | |
3070 | behavior holds: | |
3071 | ||
3072 | package Foo; | |
3073 | our $bar; # declares $Foo::bar for rest of lexical scope | |
3074 | $bar = 20; | |
3075 | ||
3076 | package Bar; | |
3077 | print $bar; # prints 20 | |
3078 | ||
3079 | Multiple C<our> declarations in the same lexical scope are allowed | |
3080 | if they are in different packages. If they happened to be in the same | |
3081 | package, Perl will emit warnings if you have asked for them. | |
3082 | ||
3083 | use warnings; | |
3084 | package Foo; | |
3085 | our $bar; # declares $Foo::bar for rest of lexical scope | |
3086 | $bar = 20; | |
3087 | ||
3088 | package Bar; | |
3089 | our $bar = 30; # declares $Bar::bar for rest of lexical scope | |
3090 | print $bar; # prints 30 | |
3091 | ||
3092 | our $bar; # emits warning | |
3093 | ||
9969eac4 BS |
3094 | An C<our> declaration may also have a list of attributes associated |
3095 | with it. B<WARNING>: This is an experimental feature that may be | |
3096 | changed or removed in future releases of Perl. It should not be | |
3097 | relied upon. | |
3098 | ||
51d2bbcc | 3099 | The only currently recognized attribute is C<unique> which indicates |
9969eac4 BS |
3100 | that a single copy of the global is to be used by all interpreters |
3101 | should the program happen to be running in a multi-interpreter | |
3102 | environment. (The default behaviour would be for each interpreter to | |
3103 | have its own copy of the global.) In such an environment, this | |
3104 | attribute also has the effect of making the global readonly. | |
3105 | Examples: | |
3106 | ||
51d2bbcc JH |
3107 | our @EXPORT : unique = qw(foo); |
3108 | our %EXPORT_TAGS : unique = (bar => [qw(aa bb cc)]); | |
3109 | our $VERSION : unique = "1.00"; | |
9969eac4 BS |
3110 | |
3111 | Multi-interpreter environments can come to being either through the | |
3112 | fork() emulation on Windows platforms, or by embedding perl in a | |
51d2bbcc | 3113 | multi-threaded application. The C<unique> attribute does nothing in |
9969eac4 BS |
3114 | all other environments. |
3115 | ||
a0d0e21e LW |
3116 | =item pack TEMPLATE,LIST |
3117 | ||
2b6c5635 GS |
3118 | Takes a LIST of values and converts it into a string using the rules |
3119 | given by the TEMPLATE. The resulting string is the concatenation of | |
3120 | the converted values. Typically, each converted value looks | |
3121 | like its machine-level representation. For example, on 32-bit machines | |
3122 | a converted integer may be represented by a sequence of 4 bytes. | |
3123 | ||
18529408 IZ |
3124 | The TEMPLATE is a sequence of characters that give the order and type |
3125 | of values, as follows: | |
a0d0e21e | 3126 | |
5a929a98 | 3127 | a A string with arbitrary binary data, will be null padded. |
121910a4 JH |
3128 | A A text (ASCII) string, will be space padded. |
3129 | Z A null terminated (ASCIZ) string, will be null padded. | |
5a929a98 | 3130 | |
2b6c5635 GS |
3131 | b A bit string (ascending bit order inside each byte, like vec()). |
3132 | B A bit string (descending bit order inside each byte). | |
a0d0e21e LW |
3133 | h A hex string (low nybble first). |
3134 | H A hex string (high nybble first). | |
3135 | ||
3136 | c A signed char value. | |
a0ed51b3 | 3137 | C An unsigned char value. Only does bytes. See U for Unicode. |
96e4d5b1 | 3138 | |
a0d0e21e LW |
3139 | s A signed short value. |
3140 | S An unsigned short value. | |
96e4d5b1 | 3141 | (This 'short' is _exactly_ 16 bits, which may differ from |
851646ae JH |
3142 | what a local C compiler calls 'short'. If you want |
3143 | native-length shorts, use the '!' suffix.) | |
96e4d5b1 | 3144 | |
a0d0e21e LW |
3145 | i A signed integer value. |
3146 | I An unsigned integer value. | |
19799a22 | 3147 | (This 'integer' is _at_least_ 32 bits wide. Its exact |
f86cebdf GS |
3148 | size depends on what a local C compiler calls 'int', |
3149 | and may even be larger than the 'long' described in | |
3150 | the next item.) | |
96e4d5b1 | 3151 | |
a0d0e21e LW |
3152 | l A signed long value. |
3153 | L An unsigned long value. | |
96e4d5b1 | 3154 | (This 'long' is _exactly_ 32 bits, which may differ from |
851646ae JH |
3155 | what a local C compiler calls 'long'. If you want |
3156 | native-length longs, use the '!' suffix.) | |
a0d0e21e | 3157 | |
5d11dd56 MG |
3158 | n An unsigned short in "network" (big-endian) order. |
3159 | N An unsigned long in "network" (big-endian) order. | |
3160 | v An unsigned short in "VAX" (little-endian) order. | |
3161 | V An unsigned long in "VAX" (little-endian) order. | |
96e4d5b1 | 3162 | (These 'shorts' and 'longs' are _exactly_ 16 bits and |
3163 | _exactly_ 32 bits, respectively.) | |
a0d0e21e | 3164 | |
dae0da7a JH |
3165 | q A signed quad (64-bit) value. |
3166 | Q An unsigned quad value. | |
851646ae JH |
3167 | (Quads are available only if your system supports 64-bit |
3168 | integer values _and_ if Perl has been compiled to support those. | |
dae0da7a JH |
3169 | Causes a fatal error otherwise.) |
3170 | ||
92d41999 JH |
3171 | j A signed integer value (a Perl internal integer, IV). |
3172 | J An unsigned integer value (a Perl internal unsigned integer, UV). | |
3173 | ||
a0d0e21e LW |
3174 | f A single-precision float in the native format. |
3175 | d A double-precision float in the native format. | |
3176 | ||
92d41999 JH |
3177 | F A floating point value in the native native format |
3178 | (a Perl internal floating point value, NV). | |
3179 | D A long double-precision float in the native format. | |
3180 | (Long doubles are available only if your system supports long | |
3181 | double values _and_ if Perl has been compiled to support those. | |
3182 | Causes a fatal error otherwise.) | |
3183 | ||
a0d0e21e LW |
3184 | p A pointer to a null-terminated string. |
3185 | P A pointer to a structure (fixed-length string). | |
3186 | ||
3187 | u A uuencoded string. | |
ad0029c4 JH |
3188 | U A Unicode character number. Encodes to UTF-8 internally |
3189 | (or UTF-EBCDIC in EBCDIC platforms). | |
a0d0e21e | 3190 | |
96e4d5b1 | 3191 | w A BER compressed integer. Its bytes represent an unsigned |
f86cebdf GS |
3192 | integer in base 128, most significant digit first, with as |
3193 | few digits as possible. Bit eight (the high bit) is set | |
3194 | on each byte except the last. | |
def98dd4 | 3195 | |
a0d0e21e LW |
3196 | x A null byte. |
3197 | X Back up a byte. | |
3198 | @ Null fill to absolute position. | |
206947d2 | 3199 | ( Start of a ()-group. |
a0d0e21e | 3200 | |
5a929a98 VU |
3201 | The following rules apply: |
3202 | ||
3203 | =over 8 | |
3204 | ||
3205 | =item * | |
3206 | ||
5a964f20 | 3207 | Each letter may optionally be followed by a number giving a repeat |
951ba7fe | 3208 | count. With all types except C<a>, C<A>, C<Z>, C<b>, C<B>, C<h>, |
206947d2 IZ |
3209 | C<H>, C<@>, C<x>, C<X> and C<P> the pack function will gobble up that |
3210 | many values from the LIST. A C<*> for the repeat count means to use | |
3211 | however many items are left, except for C<@>, C<x>, C<X>, where it is | |
3212 | equivalent to C<0>, and C<u>, where it is equivalent to 1 (or 45, what | |
3213 | is the same). A numeric repeat count may optionally be enclosed in | |
3214 | brackets, as in C<pack 'C[80]', @arr>. | |
3215 | ||
3216 | One can replace the numeric repeat count by a template enclosed in brackets; | |
3217 | then the packed length of this template in bytes is used as a count. | |
62f95557 IZ |
3218 | For example, C<x[L]> skips a long (it skips the number of bytes in a long); |
3219 | the template C<$t X[$t] $t> unpack()s twice what $t unpacks. | |
3220 | If the template in brackets contains alignment commands (such as C<x![d]>), | |
3221 | its packed length is calculated as if the start of the template has the maximal | |
3222 | possible alignment. | |
2b6c5635 | 3223 | |
951ba7fe | 3224 | When used with C<Z>, C<*> results in the addition of a trailing null |
2b6c5635 GS |
3225 | byte (so the packed result will be one longer than the byte C<length> |
3226 | of the item). | |
3227 | ||
951ba7fe | 3228 | The repeat count for C<u> is interpreted as the maximal number of bytes |
2b6c5635 | 3229 | to encode per line of output, with 0 and 1 replaced by 45. |
5a929a98 VU |
3230 | |
3231 | =item * | |
3232 | ||
951ba7fe | 3233 | The C<a>, C<A>, and C<Z> types gobble just one value, but pack it as a |
5a929a98 | 3234 | string of length count, padding with nulls or spaces as necessary. When |
951ba7fe GS |
3235 | unpacking, C<A> strips trailing spaces and nulls, C<Z> strips everything |
3236 | after the first null, and C<a> returns data verbatim. When packing, | |
3237 | C<a>, and C<Z> are equivalent. | |
2b6c5635 GS |
3238 | |
3239 | If the value-to-pack is too long, it is truncated. If too long and an | |
951ba7fe GS |
3240 | explicit count is provided, C<Z> packs only C<$count-1> bytes, followed |
3241 | by a null byte. Thus C<Z> always packs a trailing null byte under | |
2b6c5635 | 3242 | all circumstances. |
5a929a98 VU |
3243 | |
3244 | =item * | |
3245 | ||
951ba7fe | 3246 | Likewise, the C<b> and C<B> fields pack a string that many bits long. |
c73032f5 IZ |
3247 | Each byte of the input field of pack() generates 1 bit of the result. |
3248 | Each result bit is based on the least-significant bit of the corresponding | |
3249 | input byte, i.e., on C<ord($byte)%2>. In particular, bytes C<"0"> and | |
3250 | C<"1"> generate bits 0 and 1, as do bytes C<"\0"> and C<"\1">. | |
3251 | ||
3252 | Starting from the beginning of the input string of pack(), each 8-tuple | |
951ba7fe | 3253 | of bytes is converted to 1 byte of output. With format C<b> |
c73032f5 | 3254 | the first byte of the 8-tuple determines the least-significant bit of a |
951ba7fe | 3255 | byte, and with format C<B> it determines the most-significant bit of |
c73032f5 IZ |
3256 | a byte. |
3257 | ||
3258 | If the length of the input string is not exactly divisible by 8, the | |
3259 | remainder is packed as if the input string were padded by null bytes | |
3260 | at the end. Similarly, during unpack()ing the "extra" bits are ignored. | |
3261 | ||
3262 | If the input string of pack() is longer than needed, extra bytes are ignored. | |
2b6c5635 GS |
3263 | A C<*> for the repeat count of pack() means to use all the bytes of |
3264 | the input field. On unpack()ing the bits are converted to a string | |
3265 | of C<"0">s and C<"1">s. | |
5a929a98 VU |
3266 | |
3267 | =item * | |
3268 | ||
951ba7fe | 3269 | The C<h> and C<H> fields pack a string that many nybbles (4-bit groups, |
851646ae | 3270 | representable as hexadecimal digits, 0-9a-f) long. |
5a929a98 | 3271 | |
c73032f5 IZ |
3272 | Each byte of the input field of pack() generates 4 bits of the result. |
3273 | For non-alphabetical bytes the result is based on the 4 least-significant | |
3274 | bits of the input byte, i.e., on C<ord($byte)%16>. In particular, | |
3275 | bytes C<"0"> and C<"1"> generate nybbles 0 and 1, as do bytes | |
3276 | C<"\0"> and C<"\1">. For bytes C<"a".."f"> and C<"A".."F"> the result | |
3277 | is compatible with the usual hexadecimal digits, so that C<"a"> and | |
3278 | C<"A"> both generate the nybble C<0xa==10>. The result for bytes | |
3279 | C&l |