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