4 perlfunc - Perl builtin functions
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 scalar context to its
16 argument, while a list operator may provide either scalar or list
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,
20 L<C<splice>|/splice ARRAY,OFFSET,LENGTH,LIST> has three scalar arguments
21 followed by a list, whereas L<C<gethostbyname>|/gethostbyname NAME> has
22 four scalar arguments.
24 In the syntax descriptions that follow, list operators that expect a
25 list (and provide list context for elements of the list) are shown
26 with LIST as an argument. Such a list may consist of any combination
27 of scalar arguments or list values; the list values will be included
28 in the list as if each individual element were interpolated at that
29 point in the list, forming a longer single-dimensional list value.
30 Commas should separate literal elements of the LIST.
32 Any function in the list below may be used either with or without
33 parentheses around its arguments. (The syntax descriptions omit the
34 parentheses.) If you use parentheses, the simple but occasionally
35 surprising rule is this: It I<looks> like a function, therefore it I<is> a
36 function, and precedence doesn't matter. Otherwise it's a list
37 operator or unary operator, and precedence does matter. Whitespace
38 between the function and left parenthesis doesn't count, so sometimes
39 you need to be careful:
41 print 1+2+4; # Prints 7.
42 print(1+2) + 4; # Prints 3.
43 print (1+2)+4; # Also prints 3!
44 print +(1+2)+4; # Prints 7.
45 print ((1+2)+4); # Prints 7.
47 If you run Perl with the L<C<use warnings>|warnings> pragma, it can warn
48 you about this. For example, the third line above produces:
50 print (...) interpreted as function at - line 1.
51 Useless use of integer addition in void context at - line 1.
53 A few functions take no arguments at all, and therefore work as neither
54 unary nor list operators. These include such functions as
55 L<C<time>|/time> and L<C<endpwent>|/endpwent>. For example,
56 C<time+86_400> always means C<time() + 86_400>.
58 For functions that can be used in either a scalar or list context,
59 nonabortive failure is generally indicated in scalar context by
60 returning the undefined value, and in list context by returning the
63 Remember the following important rule: There is B<no rule> that relates
64 the behavior of an expression in list context to its behavior in scalar
65 context, or vice versa. It might do two totally different things.
66 Each operator and function decides which sort of value would be most
67 appropriate to return in scalar context. Some operators return the
68 length of the list that would have been returned in list context. Some
69 operators return the first value in the list. Some operators return the
70 last value in the list. Some operators return a count of successful
71 operations. In general, they do what you want, unless you want
75 A named array in scalar context is quite different from what would at
76 first glance appear to be a list in scalar context. You can't get a list
77 like C<(1,2,3)> into being in scalar context, because the compiler knows
78 the context at compile time. It would generate the scalar comma operator
79 there, not the list concatenation version of the comma. That means it
80 was never a list to start with.
82 In general, functions in Perl that serve as wrappers for system calls
83 ("syscalls") of the same name (like L<chown(2)>, L<fork(2)>,
84 L<closedir(2)>, etc.) return true when they succeed and
85 L<C<undef>|/undef EXPR> otherwise, as is usually mentioned in the
86 descriptions below. This is different from the C interfaces, which
87 return C<-1> on failure. Exceptions to this rule include
88 L<C<wait>|/wait>, L<C<waitpid>|/waitpid PID,FLAGS>, and
89 L<C<syscall>|/syscall NUMBER, LIST>. System calls also set the special
90 L<C<$!>|perlvar/$!> variable on failure. Other functions do not, except
93 Extension modules can also hook into the Perl parser to define new
94 kinds of keyword-headed expression. These may look like functions, but
95 may also look completely different. The syntax following the keyword
96 is defined entirely by the extension. If you are an implementor, see
97 L<perlapi/PL_keyword_plugin> for the mechanism. If you are using such
98 a module, see the module's documentation for details of the syntax that
101 =head2 Perl Functions by Category
104 Here are Perl's functions (including things that look like
105 functions, like some keywords and named operators)
106 arranged by category. Some functions appear in more
107 than one place. Any warnings, including those produced by
108 keywords, are described in L<perldiag> and L<warnings>.
112 =item Functions for SCALARs or strings
113 X<scalar> X<string> X<character>
115 =for Pod::Functions =String
117 L<C<chomp>|/chomp VARIABLE>, L<C<chop>|/chop VARIABLE>,
118 L<C<chr>|/chr NUMBER>, L<C<crypt>|/crypt PLAINTEXT,SALT>,
119 L<C<fc>|/fc EXPR>, L<C<hex>|/hex EXPR>,
120 L<C<index>|/index STR,SUBSTR,POSITION>, L<C<lc>|/lc EXPR>,
121 L<C<lcfirst>|/lcfirst EXPR>, L<C<length>|/length EXPR>,
122 L<C<oct>|/oct EXPR>, L<C<ord>|/ord EXPR>,
123 L<C<pack>|/pack TEMPLATE,LIST>,
124 L<C<qE<sol>E<sol>>|/qE<sol>STRINGE<sol>>,
125 L<C<qqE<sol>E<sol>>|/qqE<sol>STRINGE<sol>>, L<C<reverse>|/reverse LIST>,
126 L<C<rindex>|/rindex STR,SUBSTR,POSITION>,
127 L<C<sprintf>|/sprintf FORMAT, LIST>,
128 L<C<substr>|/substr EXPR,OFFSET,LENGTH,REPLACEMENT>,
129 L<C<trE<sol>E<sol>E<sol>>|/trE<sol>E<sol>E<sol>>, L<C<uc>|/uc EXPR>,
130 L<C<ucfirst>|/ucfirst EXPR>,
131 L<C<yE<sol>E<sol>E<sol>>|/yE<sol>E<sol>E<sol>>
133 L<C<fc>|/fc EXPR> is available only if the
134 L<C<"fc"> feature|feature/The 'fc' feature> is enabled or if it is
135 prefixed with C<CORE::>. The
136 L<C<"fc"> feature|feature/The 'fc' feature> is enabled automatically
137 with a C<use v5.16> (or higher) declaration in the current scope.
139 =item Regular expressions and pattern matching
140 X<regular expression> X<regex> X<regexp>
142 =for Pod::Functions =Regexp
144 L<C<mE<sol>E<sol>>|/mE<sol>E<sol>>, L<C<pos>|/pos SCALAR>,
145 L<C<qrE<sol>E<sol>>|/qrE<sol>STRINGE<sol>>,
146 L<C<quotemeta>|/quotemeta EXPR>,
147 L<C<sE<sol>E<sol>E<sol>>|/sE<sol>E<sol>E<sol>>,
148 L<C<split>|/split E<sol>PATTERNE<sol>,EXPR,LIMIT>,
149 L<C<study>|/study SCALAR>
151 =item Numeric functions
152 X<numeric> X<number> X<trigonometric> X<trigonometry>
154 =for Pod::Functions =Math
156 L<C<abs>|/abs VALUE>, L<C<atan2>|/atan2 Y,X>, L<C<cos>|/cos EXPR>,
157 L<C<exp>|/exp EXPR>, L<C<hex>|/hex EXPR>, L<C<int>|/int EXPR>,
158 L<C<log>|/log EXPR>, L<C<oct>|/oct EXPR>, L<C<rand>|/rand EXPR>,
159 L<C<sin>|/sin EXPR>, L<C<sqrt>|/sqrt EXPR>, L<C<srand>|/srand EXPR>
161 =item Functions for real @ARRAYs
164 =for Pod::Functions =ARRAY
166 L<C<each>|/each HASH>, L<C<keys>|/keys HASH>, L<C<pop>|/pop ARRAY>,
167 L<C<push>|/push ARRAY,LIST>, L<C<shift>|/shift ARRAY>,
168 L<C<splice>|/splice ARRAY,OFFSET,LENGTH,LIST>,
169 L<C<unshift>|/unshift ARRAY,LIST>, L<C<values>|/values HASH>
171 =item Functions for list data
174 =for Pod::Functions =LIST
176 L<C<grep>|/grep BLOCK LIST>, L<C<join>|/join EXPR,LIST>,
177 L<C<map>|/map BLOCK LIST>, L<C<qwE<sol>E<sol>>|/qwE<sol>STRINGE<sol>>,
178 L<C<reverse>|/reverse LIST>, L<C<sort>|/sort SUBNAME LIST>,
179 L<C<unpack>|/unpack TEMPLATE,EXPR>
181 =item Functions for real %HASHes
184 =for Pod::Functions =HASH
186 L<C<delete>|/delete EXPR>, L<C<each>|/each HASH>,
187 L<C<exists>|/exists EXPR>, L<C<keys>|/keys HASH>,
188 L<C<values>|/values HASH>
190 =item Input and output functions
191 X<I/O> X<input> X<output> X<dbm>
193 =for Pod::Functions =I/O
195 L<C<binmode>|/binmode FILEHANDLE, LAYER>, L<C<close>|/close FILEHANDLE>,
196 L<C<closedir>|/closedir DIRHANDLE>, L<C<dbmclose>|/dbmclose HASH>,
197 L<C<dbmopen>|/dbmopen HASH,DBNAME,MASK>, L<C<die>|/die LIST>,
198 L<C<eof>|/eof FILEHANDLE>, L<C<fileno>|/fileno FILEHANDLE>,
199 L<C<flock>|/flock FILEHANDLE,OPERATION>, L<C<format>|/format>,
200 L<C<getc>|/getc FILEHANDLE>, L<C<print>|/print FILEHANDLE LIST>,
201 L<C<printf>|/printf FILEHANDLE FORMAT, LIST>,
202 L<C<read>|/read FILEHANDLE,SCALAR,LENGTH,OFFSET>,
203 L<C<readdir>|/readdir DIRHANDLE>, L<C<readline>|/readline EXPR>,
204 L<C<rewinddir>|/rewinddir DIRHANDLE>, L<C<say>|/say FILEHANDLE LIST>,
205 L<C<seek>|/seek FILEHANDLE,POSITION,WHENCE>,
206 L<C<seekdir>|/seekdir DIRHANDLE,POS>,
207 L<C<select>|/select RBITS,WBITS,EBITS,TIMEOUT>,
208 L<C<syscall>|/syscall NUMBER, LIST>,
209 L<C<sysread>|/sysread FILEHANDLE,SCALAR,LENGTH,OFFSET>,
210 L<C<sysseek>|/sysseek FILEHANDLE,POSITION,WHENCE>,
211 L<C<syswrite>|/syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET>,
212 L<C<tell>|/tell FILEHANDLE>, L<C<telldir>|/telldir DIRHANDLE>,
213 L<C<truncate>|/truncate FILEHANDLE,LENGTH>, L<C<warn>|/warn LIST>,
214 L<C<write>|/write FILEHANDLE>
216 L<C<say>|/say FILEHANDLE LIST> is available only if the
217 L<C<"say"> feature|feature/The 'say' feature> is enabled or if it is
218 prefixed with C<CORE::>. The
219 L<C<"say"> feature|feature/The 'say' feature> is enabled automatically
220 with a C<use v5.10> (or higher) declaration in the current scope.
222 =item Functions for fixed-length data or records
224 =for Pod::Functions =Binary
226 L<C<pack>|/pack TEMPLATE,LIST>,
227 L<C<read>|/read FILEHANDLE,SCALAR,LENGTH,OFFSET>,
228 L<C<syscall>|/syscall NUMBER, LIST>,
229 L<C<sysread>|/sysread FILEHANDLE,SCALAR,LENGTH,OFFSET>,
230 L<C<sysseek>|/sysseek FILEHANDLE,POSITION,WHENCE>,
231 L<C<syswrite>|/syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET>,
232 L<C<unpack>|/unpack TEMPLATE,EXPR>, L<C<vec>|/vec EXPR,OFFSET,BITS>
234 =item Functions for filehandles, files, or directories
235 X<file> X<filehandle> X<directory> X<pipe> X<link> X<symlink>
237 =for Pod::Functions =File
239 L<C<-I<X>>|/-X FILEHANDLE>, L<C<chdir>|/chdir EXPR>,
240 L<C<chmod>|/chmod LIST>, L<C<chown>|/chown LIST>,
241 L<C<chroot>|/chroot FILENAME>,
242 L<C<fcntl>|/fcntl FILEHANDLE,FUNCTION,SCALAR>, L<C<glob>|/glob EXPR>,
243 L<C<ioctl>|/ioctl FILEHANDLE,FUNCTION,SCALAR>,
244 L<C<link>|/link OLDFILE,NEWFILE>, L<C<lstat>|/lstat FILEHANDLE>,
245 L<C<mkdir>|/mkdir FILENAME,MODE>, L<C<open>|/open FILEHANDLE,EXPR>,
246 L<C<opendir>|/opendir DIRHANDLE,EXPR>, L<C<readlink>|/readlink EXPR>,
247 L<C<rename>|/rename OLDNAME,NEWNAME>, L<C<rmdir>|/rmdir FILENAME>,
248 L<C<select>|/select FILEHANDLE>, L<C<stat>|/stat FILEHANDLE>,
249 L<C<symlink>|/symlink OLDFILE,NEWFILE>,
250 L<C<sysopen>|/sysopen FILEHANDLE,FILENAME,MODE>,
251 L<C<umask>|/umask EXPR>, L<C<unlink>|/unlink LIST>,
252 L<C<utime>|/utime LIST>
254 =item Keywords related to the control flow of your Perl program
257 =for Pod::Functions =Flow
259 L<C<break>|/break>, L<C<caller>|/caller EXPR>,
260 L<C<continue>|/continue BLOCK>, L<C<die>|/die LIST>, L<C<do>|/do BLOCK>,
261 L<C<dump>|/dump LABEL>, L<C<eval>|/eval EXPR>,
262 L<C<evalbytes>|/evalbytes EXPR>, L<C<exit>|/exit EXPR>,
263 L<C<__FILE__>|/__FILE__>, L<C<goto>|/goto LABEL>,
264 L<C<last>|/last LABEL>, L<C<__LINE__>|/__LINE__>,
265 L<C<next>|/next LABEL>, L<C<__PACKAGE__>|/__PACKAGE__>,
266 L<C<redo>|/redo LABEL>, L<C<return>|/return EXPR>,
267 L<C<sub>|/sub NAME BLOCK>, L<C<__SUB__>|/__SUB__>,
268 L<C<wantarray>|/wantarray>
270 L<C<break>|/break> is available only if you enable the experimental
271 L<C<"switch"> feature|feature/The 'switch' feature> or use the C<CORE::>
272 prefix. The L<C<"switch"> feature|feature/The 'switch' feature> also
273 enables the C<default>, C<given> and C<when> statements, which are
274 documented in L<perlsyn/"Switch Statements">.
275 The L<C<"switch"> feature|feature/The 'switch' feature> is enabled
276 automatically with a C<use v5.10> (or higher) declaration in the current
277 scope. In Perl v5.14 and earlier, L<C<continue>|/continue BLOCK>
278 required the L<C<"switch"> feature|feature/The 'switch' feature>, like
281 L<C<evalbytes>|/evalbytes EXPR> is only available with the
282 L<C<"evalbytes"> feature|feature/The 'unicode_eval' and 'evalbytes' features>
283 (see L<feature>) or if prefixed with C<CORE::>. L<C<__SUB__>|/__SUB__>
284 is only available with the
285 L<C<"current_sub"> feature|feature/The 'current_sub' feature> or if
286 prefixed with C<CORE::>. Both the
287 L<C<"evalbytes">|feature/The 'unicode_eval' and 'evalbytes' features>
288 and L<C<"current_sub">|feature/The 'current_sub' feature> features are
289 enabled automatically with a C<use v5.16> (or higher) declaration in the
292 =item Keywords related to scoping
294 =for Pod::Functions =Namespace
296 L<C<caller>|/caller EXPR>, L<C<import>|/import LIST>,
297 L<C<local>|/local EXPR>, L<C<my>|/my VARLIST>, L<C<our>|/our VARLIST>,
298 L<C<package>|/package NAMESPACE>, L<C<state>|/state VARLIST>,
299 L<C<use>|/use Module VERSION LIST>
301 L<C<state>|/state VARLIST> is available only if the
302 L<C<"state"> feature|feature/The 'state' feature> is enabled or if it is
303 prefixed with C<CORE::>. The
304 L<C<"state"> feature|feature/The 'state' feature> is enabled
305 automatically with a C<use v5.10> (or higher) declaration in the current
308 =item Miscellaneous functions
310 =for Pod::Functions =Misc
312 L<C<defined>|/defined EXPR>, L<C<formline>|/formline PICTURE,LIST>,
313 L<C<lock>|/lock THING>, L<C<prototype>|/prototype FUNCTION>,
314 L<C<reset>|/reset EXPR>, L<C<scalar>|/scalar EXPR>,
315 L<C<undef>|/undef EXPR>
317 =item Functions for processes and process groups
318 X<process> X<pid> X<process id>
320 =for Pod::Functions =Process
322 L<C<alarm>|/alarm SECONDS>, L<C<exec>|/exec LIST>, L<C<fork>|/fork>,
323 L<C<getpgrp>|/getpgrp PID>, L<C<getppid>|/getppid>,
324 L<C<getpriority>|/getpriority WHICH,WHO>, L<C<kill>|/kill SIGNAL, LIST>,
325 L<C<pipe>|/pipe READHANDLE,WRITEHANDLE>,
326 L<C<qxE<sol>E<sol>>|/qxE<sol>STRINGE<sol>>,
327 L<C<readpipe>|/readpipe EXPR>, L<C<setpgrp>|/setpgrp PID,PGRP>,
328 L<C<setpriority>|/setpriority WHICH,WHO,PRIORITY>,
329 L<C<sleep>|/sleep EXPR>, L<C<system>|/system LIST>, L<C<times>|/times>,
330 L<C<wait>|/wait>, L<C<waitpid>|/waitpid PID,FLAGS>
332 =item Keywords related to Perl modules
335 =for Pod::Functions =Modules
337 L<C<do>|/do EXPR>, L<C<import>|/import LIST>,
338 L<C<no>|/no MODULE VERSION LIST>, L<C<package>|/package NAMESPACE>,
339 L<C<require>|/require VERSION>, L<C<use>|/use Module VERSION LIST>
341 =item Keywords related to classes and object-orientation
342 X<object> X<class> X<package>
344 =for Pod::Functions =Objects
346 L<C<bless>|/bless REF,CLASSNAME>, L<C<dbmclose>|/dbmclose HASH>,
347 L<C<dbmopen>|/dbmopen HASH,DBNAME,MASK>,
348 L<C<package>|/package NAMESPACE>, L<C<ref>|/ref EXPR>,
349 L<C<tie>|/tie VARIABLE,CLASSNAME,LIST>, L<C<tied>|/tied VARIABLE>,
350 L<C<untie>|/untie VARIABLE>, L<C<use>|/use Module VERSION LIST>
352 =item Low-level socket functions
355 =for Pod::Functions =Socket
357 L<C<accept>|/accept NEWSOCKET,GENERICSOCKET>,
358 L<C<bind>|/bind SOCKET,NAME>, L<C<connect>|/connect SOCKET,NAME>,
359 L<C<getpeername>|/getpeername SOCKET>,
360 L<C<getsockname>|/getsockname SOCKET>,
361 L<C<getsockopt>|/getsockopt SOCKET,LEVEL,OPTNAME>,
362 L<C<listen>|/listen SOCKET,QUEUESIZE>,
363 L<C<recv>|/recv SOCKET,SCALAR,LENGTH,FLAGS>,
364 L<C<send>|/send SOCKET,MSG,FLAGS,TO>,
365 L<C<setsockopt>|/setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL>,
366 L<C<shutdown>|/shutdown SOCKET,HOW>,
367 L<C<socket>|/socket SOCKET,DOMAIN,TYPE,PROTOCOL>,
368 L<C<socketpair>|/socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL>
370 =item System V interprocess communication functions
371 X<IPC> X<System V> X<semaphore> X<shared memory> X<memory> X<message>
373 =for Pod::Functions =SysV
375 L<C<msgctl>|/msgctl ID,CMD,ARG>, L<C<msgget>|/msgget KEY,FLAGS>,
376 L<C<msgrcv>|/msgrcv ID,VAR,SIZE,TYPE,FLAGS>,
377 L<C<msgsnd>|/msgsnd ID,MSG,FLAGS>,
378 L<C<semctl>|/semctl ID,SEMNUM,CMD,ARG>,
379 L<C<semget>|/semget KEY,NSEMS,FLAGS>, L<C<semop>|/semop KEY,OPSTRING>,
380 L<C<shmctl>|/shmctl ID,CMD,ARG>, L<C<shmget>|/shmget KEY,SIZE,FLAGS>,
381 L<C<shmread>|/shmread ID,VAR,POS,SIZE>,
382 L<C<shmwrite>|/shmwrite ID,STRING,POS,SIZE>
384 =item Fetching user and group info
385 X<user> X<group> X<password> X<uid> X<gid> X<passwd> X</etc/passwd>
387 =for Pod::Functions =User
389 L<C<endgrent>|/endgrent>, L<C<endhostent>|/endhostent>,
390 L<C<endnetent>|/endnetent>, L<C<endpwent>|/endpwent>,
391 L<C<getgrent>|/getgrent>, L<C<getgrgid>|/getgrgid GID>,
392 L<C<getgrnam>|/getgrnam NAME>, L<C<getlogin>|/getlogin>,
393 L<C<getpwent>|/getpwent>, L<C<getpwnam>|/getpwnam NAME>,
394 L<C<getpwuid>|/getpwuid UID>, L<C<setgrent>|/setgrent>,
395 L<C<setpwent>|/setpwent>
397 =item Fetching network info
398 X<network> X<protocol> X<host> X<hostname> X<IP> X<address> X<service>
400 =for Pod::Functions =Network
402 L<C<endprotoent>|/endprotoent>, L<C<endservent>|/endservent>,
403 L<C<gethostbyaddr>|/gethostbyaddr ADDR,ADDRTYPE>,
404 L<C<gethostbyname>|/gethostbyname NAME>, L<C<gethostent>|/gethostent>,
405 L<C<getnetbyaddr>|/getnetbyaddr ADDR,ADDRTYPE>,
406 L<C<getnetbyname>|/getnetbyname NAME>, L<C<getnetent>|/getnetent>,
407 L<C<getprotobyname>|/getprotobyname NAME>,
408 L<C<getprotobynumber>|/getprotobynumber NUMBER>,
409 L<C<getprotoent>|/getprotoent>,
410 L<C<getservbyname>|/getservbyname NAME,PROTO>,
411 L<C<getservbyport>|/getservbyport PORT,PROTO>,
412 L<C<getservent>|/getservent>, L<C<sethostent>|/sethostent STAYOPEN>,
413 L<C<setnetent>|/setnetent STAYOPEN>,
414 L<C<setprotoent>|/setprotoent STAYOPEN>,
415 L<C<setservent>|/setservent STAYOPEN>
417 =item Time-related functions
420 =for Pod::Functions =Time
422 L<C<gmtime>|/gmtime EXPR>, L<C<localtime>|/localtime EXPR>,
423 L<C<time>|/time>, L<C<times>|/times>
425 =item Non-function keywords
427 =for Pod::Functions =!Non-functions
429 C<and>, C<AUTOLOAD>, C<BEGIN>, C<CHECK>, C<cmp>, C<CORE>, C<__DATA__>,
430 C<default>, C<DESTROY>, C<else>, C<elseif>, C<elsif>, C<END>, C<__END__>,
431 C<eq>, C<for>, C<foreach>, C<ge>, C<given>, C<gt>, C<if>, C<INIT>, C<le>,
432 C<lt>, C<ne>, C<not>, C<or>, C<UNITCHECK>, C<unless>, C<until>, C<when>,
433 C<while>, C<x>, C<xor>
438 X<portability> X<Unix> X<portable>
440 Perl was born in Unix and can therefore access all common Unix
441 system calls. In non-Unix environments, the functionality of some
442 Unix system calls may not be available or details of the available
443 functionality may differ slightly. The Perl functions affected
446 L<C<-I<X>>|/-X FILEHANDLE>, L<C<binmode>|/binmode FILEHANDLE, LAYER>,
447 L<C<chmod>|/chmod LIST>, L<C<chown>|/chown LIST>,
448 L<C<chroot>|/chroot FILENAME>, L<C<crypt>|/crypt PLAINTEXT,SALT>,
449 L<C<dbmclose>|/dbmclose HASH>, L<C<dbmopen>|/dbmopen HASH,DBNAME,MASK>,
450 L<C<dump>|/dump LABEL>, L<C<endgrent>|/endgrent>,
451 L<C<endhostent>|/endhostent>, L<C<endnetent>|/endnetent>,
452 L<C<endprotoent>|/endprotoent>, L<C<endpwent>|/endpwent>,
453 L<C<endservent>|/endservent>, L<C<exec>|/exec LIST>,
454 L<C<fcntl>|/fcntl FILEHANDLE,FUNCTION,SCALAR>,
455 L<C<flock>|/flock FILEHANDLE,OPERATION>, L<C<fork>|/fork>,
456 L<C<getgrent>|/getgrent>, L<C<getgrgid>|/getgrgid GID>,
457 L<C<gethostbyname>|/gethostbyname NAME>, L<C<gethostent>|/gethostent>,
458 L<C<getlogin>|/getlogin>,
459 L<C<getnetbyaddr>|/getnetbyaddr ADDR,ADDRTYPE>,
460 L<C<getnetbyname>|/getnetbyname NAME>, L<C<getnetent>|/getnetent>,
461 L<C<getppid>|/getppid>, L<C<getpgrp>|/getpgrp PID>,
462 L<C<getpriority>|/getpriority WHICH,WHO>,
463 L<C<getprotobynumber>|/getprotobynumber NUMBER>,
464 L<C<getprotoent>|/getprotoent>, L<C<getpwent>|/getpwent>,
465 L<C<getpwnam>|/getpwnam NAME>, L<C<getpwuid>|/getpwuid UID>,
466 L<C<getservbyport>|/getservbyport PORT,PROTO>,
467 L<C<getservent>|/getservent>,
468 L<C<getsockopt>|/getsockopt SOCKET,LEVEL,OPTNAME>,
469 L<C<glob>|/glob EXPR>, L<C<ioctl>|/ioctl FILEHANDLE,FUNCTION,SCALAR>,
470 L<C<kill>|/kill SIGNAL, LIST>, L<C<link>|/link OLDFILE,NEWFILE>,
471 L<C<lstat>|/lstat FILEHANDLE>, L<C<msgctl>|/msgctl ID,CMD,ARG>,
472 L<C<msgget>|/msgget KEY,FLAGS>,
473 L<C<msgrcv>|/msgrcv ID,VAR,SIZE,TYPE,FLAGS>,
474 L<C<msgsnd>|/msgsnd ID,MSG,FLAGS>, L<C<open>|/open FILEHANDLE,EXPR>,
475 L<C<pipe>|/pipe READHANDLE,WRITEHANDLE>, L<C<readlink>|/readlink EXPR>,
476 L<C<rename>|/rename OLDNAME,NEWNAME>,
477 L<C<select>|/select RBITS,WBITS,EBITS,TIMEOUT>,
478 L<C<semctl>|/semctl ID,SEMNUM,CMD,ARG>,
479 L<C<semget>|/semget KEY,NSEMS,FLAGS>, L<C<semop>|/semop KEY,OPSTRING>,
480 L<C<setgrent>|/setgrent>, L<C<sethostent>|/sethostent STAYOPEN>,
481 L<C<setnetent>|/setnetent STAYOPEN>, L<C<setpgrp>|/setpgrp PID,PGRP>,
482 L<C<setpriority>|/setpriority WHICH,WHO,PRIORITY>,
483 L<C<setprotoent>|/setprotoent STAYOPEN>, L<C<setpwent>|/setpwent>,
484 L<C<setservent>|/setservent STAYOPEN>,
485 L<C<setsockopt>|/setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL>,
486 L<C<shmctl>|/shmctl ID,CMD,ARG>, L<C<shmget>|/shmget KEY,SIZE,FLAGS>,
487 L<C<shmread>|/shmread ID,VAR,POS,SIZE>,
488 L<C<shmwrite>|/shmwrite ID,STRING,POS,SIZE>,
489 L<C<socket>|/socket SOCKET,DOMAIN,TYPE,PROTOCOL>,
490 L<C<socketpair>|/socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL>,
491 L<C<stat>|/stat FILEHANDLE>, L<C<symlink>|/symlink OLDFILE,NEWFILE>,
492 L<C<syscall>|/syscall NUMBER, LIST>,
493 L<C<sysopen>|/sysopen FILEHANDLE,FILENAME,MODE>,
494 L<C<system>|/system LIST>, L<C<times>|/times>,
495 L<C<truncate>|/truncate FILEHANDLE,LENGTH>, L<C<umask>|/umask EXPR>,
496 L<C<unlink>|/unlink LIST>, L<C<utime>|/utime LIST>, L<C<wait>|/wait>,
497 L<C<waitpid>|/waitpid PID,FLAGS>
499 For more information about the portability of these functions, see
500 L<perlport> and other available platform-specific documentation.
502 =head2 Alphabetical Listing of Perl Functions
507 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>
508 X<-S>X<-b>X<-c>X<-t>X<-u>X<-g>X<-k>X<-T>X<-B>X<-M>X<-A>X<-C>
516 =for Pod::Functions a file test (-r, -x, etc)
518 A file test, where X is one of the letters listed below. This unary
519 operator takes one argument, either a filename, a filehandle, or a dirhandle,
520 and tests the associated file to see if something is true about it. If the
521 argument is omitted, tests L<C<$_>|perlvar/$_>, except for C<-t>, which
522 tests STDIN. Unless otherwise documented, it returns C<1> for true and
523 C<''> for false. If the file doesn't exist or can't be examined, it
524 returns L<C<undef>|/undef EXPR> and sets L<C<$!>|perlvar/$!> (errno).
525 Despite the funny names, precedence is the same as any other named unary
526 operator. The operator may be any of:
528 -r File is readable by effective uid/gid.
529 -w File is writable by effective uid/gid.
530 -x File is executable by effective uid/gid.
531 -o File is owned by effective uid.
533 -R File is readable by real uid/gid.
534 -W File is writable by real uid/gid.
535 -X File is executable by real uid/gid.
536 -O File is owned by real uid.
539 -z File has zero size (is empty).
540 -s File has nonzero size (returns size in bytes).
542 -f File is a plain file.
543 -d File is a directory.
544 -l File is a symbolic link (false if symlinks aren't
545 supported by the file system).
546 -p File is a named pipe (FIFO), or Filehandle is a pipe.
548 -b File is a block special file.
549 -c File is a character special file.
550 -t Filehandle is opened to a tty.
552 -u File has setuid bit set.
553 -g File has setgid bit set.
554 -k File has sticky bit set.
556 -T File is an ASCII or UTF-8 text file (heuristic guess).
557 -B File is a "binary" file (opposite of -T).
559 -M Script start time minus file modification time, in days.
560 -A Same for access time.
561 -C Same for inode change time (Unix, may differ for other
568 next unless -f $_; # ignore specials
572 Note that C<-s/a/b/> does not do a negated substitution. Saying
573 C<-exp($foo)> still works as expected, however: only single letters
574 following a minus are interpreted as file tests.
576 These operators are exempt from the "looks like a function rule" described
577 above. That is, an opening parenthesis after the operator does not affect
578 how much of the following code constitutes the argument. Put the opening
579 parentheses before the operator to separate it from code that follows (this
580 applies only to operators with higher precedence than unary operators, of
583 -s($file) + 1024 # probably wrong; same as -s($file + 1024)
584 (-s $file) + 1024 # correct
586 The interpretation of the file permission operators C<-r>, C<-R>,
587 C<-w>, C<-W>, C<-x>, and C<-X> is by default based solely on the mode
588 of the file and the uids and gids of the user. There may be other
589 reasons you can't actually read, write, or execute the file: for
590 example network filesystem access controls, ACLs (access control lists),
591 read-only filesystems, and unrecognized executable formats. Note
592 that the use of these six specific operators to verify if some operation
593 is possible is usually a mistake, because it may be open to race
596 Also note that, for the superuser on the local filesystems, the C<-r>,
597 C<-R>, C<-w>, and C<-W> tests always return 1, and C<-x> and C<-X> return 1
598 if any execute bit is set in the mode. Scripts run by the superuser
599 may thus need to do a L<C<stat>|/stat FILEHANDLE> to determine the
600 actual mode of the file, or temporarily set their effective uid to
603 If you are using ACLs, there is a pragma called L<C<filetest>|filetest>
604 that may produce more accurate results than the bare
605 L<C<stat>|/stat FILEHANDLE> mode bits.
606 When under C<use filetest 'access'>, the above-mentioned filetests
607 test whether the permission can(not) be granted using the L<access(2)>
608 family of system calls. Also note that the C<-x> and C<-X> tests may
609 under this pragma return true even if there are no execute permission
610 bits set (nor any extra execute permission ACLs). This strangeness is
611 due to the underlying system calls' definitions. Note also that, due to
612 the implementation of C<use filetest 'access'>, the C<_> special
613 filehandle won't cache the results of the file tests when this pragma is
614 in effect. Read the documentation for the L<C<filetest>|filetest>
615 pragma for more information.
617 The C<-T> and C<-B> tests work as follows. The first block or so of
618 the file is examined to see if it is valid UTF-8 that includes non-ASCII
619 characters. If so, it's a C<-T> file. Otherwise, that same portion of
620 the file is examined for odd characters such as strange control codes or
621 characters with the high bit set. If more than a third of the
622 characters are strange, it's a C<-B> file; otherwise it's a C<-T> file.
623 Also, any file containing a zero byte in the examined portion is
624 considered a binary file. (If executed within the scope of a L<S<use
625 locale>|perllocale> which includes C<LC_CTYPE>, odd characters are
626 anything that isn't a printable nor space in the current locale.) If
627 C<-T> or C<-B> is used on a filehandle, the current IO buffer is
629 rather than the first block. Both C<-T> and C<-B> return true on an empty
630 file, or a file at EOF when testing a filehandle. Because you have to
631 read a file to do the C<-T> test, on most occasions you want to use a C<-f>
632 against the file first, as in C<next unless -f $file && -T $file>.
634 If any of the file tests (or either the L<C<stat>|/stat FILEHANDLE> or
635 L<C<lstat>|/lstat FILEHANDLE> operator) is given the special filehandle
636 consisting of a solitary underline, then the stat structure of the
637 previous file test (or L<C<stat>|/stat FILEHANDLE> operator) is used,
638 saving a system call. (This doesn't work with C<-t>, and you need to
639 remember that L<C<lstat>|/lstat FILEHANDLE> and C<-l> leave values in
640 the stat structure for the symbolic link, not the real file.) (Also, if
641 the stat buffer was filled by an L<C<lstat>|/lstat FILEHANDLE> call,
642 C<-T> and C<-B> will reset it with the results of C<stat _>).
645 print "Can do.\n" if -r $a || -w _ || -x _;
648 print "Readable\n" if -r _;
649 print "Writable\n" if -w _;
650 print "Executable\n" if -x _;
651 print "Setuid\n" if -u _;
652 print "Setgid\n" if -g _;
653 print "Sticky\n" if -k _;
654 print "Text\n" if -T _;
655 print "Binary\n" if -B _;
657 As of Perl 5.10.0, as a form of purely syntactic sugar, you can stack file
658 test operators, in a way that C<-f -w -x $file> is equivalent to
659 C<-x $file && -w _ && -f _>. (This is only fancy syntax: if you use
660 the return value of C<-f $file> as an argument to another filetest
661 operator, no special magic will happen.)
663 Portability issues: L<perlport/-X>.
665 To avoid confusing would-be users of your code with mysterious
666 syntax errors, put something like this at the top of your script:
668 use 5.010; # so filetest ops can stack
675 =for Pod::Functions absolute value function
677 Returns the absolute value of its argument.
678 If VALUE is omitted, uses L<C<$_>|perlvar/$_>.
680 =item accept NEWSOCKET,GENERICSOCKET
683 =for Pod::Functions accept an incoming socket connect
685 Accepts an incoming socket connect, just as L<accept(2)>
686 does. Returns the packed address if it succeeded, false otherwise.
687 See the example in L<perlipc/"Sockets: Client/Server Communication">.
689 On systems that support a close-on-exec flag on files, the flag will
690 be set for the newly opened file descriptor, as determined by the
691 value of L<C<$^F>|perlvar/$^F>. See L<perlvar/$^F>.
700 =for Pod::Functions schedule a SIGALRM
702 Arranges to have a SIGALRM delivered to this process after the
703 specified number of wallclock seconds has elapsed. If SECONDS is not
704 specified, the value stored in L<C<$_>|perlvar/$_> is used. (On some
705 machines, unfortunately, the elapsed time may be up to one second less
706 or more than you specified because of how seconds are counted, and
707 process scheduling may delay the delivery of the signal even further.)
709 Only one timer may be counting at once. Each call disables the
710 previous timer, and an argument of C<0> may be supplied to cancel the
711 previous timer without starting a new one. The returned value is the
712 amount of time remaining on the previous timer.
714 For delays of finer granularity than one second, the L<Time::HiRes> module
715 (from CPAN, and starting from Perl 5.8 part of the standard
716 distribution) provides
717 L<C<ualarm>|Time::HiRes/ualarm ( $useconds [, $interval_useconds ] )>.
718 You may also use Perl's four-argument version of
719 L<C<select>|/select RBITS,WBITS,EBITS,TIMEOUT> leaving the first three
720 arguments undefined, or you might be able to use the
721 L<C<syscall>|/syscall NUMBER, LIST> interface to access L<setitimer(2)>
722 if your system supports it. See L<perlfaq8> for details.
724 It is usually a mistake to intermix L<C<alarm>|/alarm SECONDS> and
725 L<C<sleep>|/sleep EXPR> calls, because L<C<sleep>|/sleep EXPR> may be
726 internally implemented on your system with L<C<alarm>|/alarm SECONDS>.
728 If you want to use L<C<alarm>|/alarm SECONDS> to time out a system call
729 you need to use an L<C<eval>|/eval EXPR>/L<C<die>|/die LIST> pair. You
730 can't rely on the alarm causing the system call to fail with
731 L<C<$!>|perlvar/$!> set to C<EINTR> because Perl sets up signal handlers
732 to restart system calls on some systems. Using
733 L<C<eval>|/eval EXPR>/L<C<die>|/die LIST> always works, modulo the
734 caveats given in L<perlipc/"Signals">.
737 local $SIG{ALRM} = sub { die "alarm\n" }; # NB: \n required
739 my $nread = sysread $socket, $buffer, $size;
743 die unless $@ eq "alarm\n"; # propagate unexpected errors
750 For more information see L<perlipc>.
752 Portability issues: L<perlport/alarm>.
755 X<atan2> X<arctangent> X<tan> X<tangent>
757 =for Pod::Functions arctangent of Y/X in the range -PI to PI
759 Returns the arctangent of Y/X in the range -PI to PI.
761 For the tangent operation, you may use the
762 L<C<Math::Trig::tan>|Math::Trig/B<tan>> function, or use the familiar
765 sub tan { sin($_[0]) / cos($_[0]) }
767 The return value for C<atan2(0,0)> is implementation-defined; consult
768 your L<atan2(3)> manpage for more information.
770 Portability issues: L<perlport/atan2>.
772 =item bind SOCKET,NAME
775 =for Pod::Functions binds an address to a socket
777 Binds a network address to a socket, just as L<bind(2)>
778 does. Returns true if it succeeded, false otherwise. NAME should be a
779 packed address of the appropriate type for the socket. See the examples in
780 L<perlipc/"Sockets: Client/Server Communication">.
782 =item binmode FILEHANDLE, LAYER
783 X<binmode> X<binary> X<text> X<DOS> X<Windows>
785 =item binmode FILEHANDLE
787 =for Pod::Functions prepare binary files for I/O
789 Arranges for FILEHANDLE to be read or written in "binary" or "text"
790 mode on systems where the run-time libraries distinguish between
791 binary and text files. If FILEHANDLE is an expression, the value is
792 taken as the name of the filehandle. Returns true on success,
793 otherwise it returns L<C<undef>|/undef EXPR> and sets
794 L<C<$!>|perlvar/$!> (errno).
796 On some systems (in general, DOS- and Windows-based systems)
797 L<C<binmode>|/binmode FILEHANDLE, LAYER> is necessary when you're not
798 working with a text file. For the sake of portability it is a good idea
799 always to use it when appropriate, and never to use it when it isn't
800 appropriate. Also, people can set their I/O to be by default
801 UTF8-encoded Unicode, not bytes.
803 In other words: regardless of platform, use
804 L<C<binmode>|/binmode FILEHANDLE, LAYER> on binary data, like images,
807 If LAYER is present it is a single string, but may contain multiple
808 directives. The directives alter the behaviour of the filehandle.
809 When LAYER is present, using binmode on a text file makes sense.
811 If LAYER is omitted or specified as C<:raw> the filehandle is made
812 suitable for passing binary data. This includes turning off possible CRLF
813 translation and marking it as bytes (as opposed to Unicode characters).
814 Note that, despite what may be implied in I<"Programming Perl"> (the
815 Camel, 3rd edition) or elsewhere, C<:raw> is I<not> simply the inverse of C<:crlf>.
816 Other layers that would affect the binary nature of the stream are
817 I<also> disabled. See L<PerlIO>, L<perlrun>, and the discussion about the
818 PERLIO environment variable.
820 The C<:bytes>, C<:crlf>, C<:utf8>, and any other directives of the
821 form C<:...>, are called I/O I<layers>. The L<open> pragma can be used to
822 establish default I/O layers.
824 I<The LAYER parameter of the L<C<binmode>|/binmode FILEHANDLE, LAYER>
825 function is described as "DISCIPLINE" in "Programming Perl, 3rd
826 Edition". However, since the publishing of this book, by many known as
827 "Camel III", the consensus of the naming of this functionality has moved
828 from "discipline" to "layer". All documentation of this version of Perl
829 therefore refers to "layers" rather than to "disciplines". Now back to
830 the regularly scheduled documentation...>
832 To mark FILEHANDLE as UTF-8, use C<:utf8> or C<:encoding(UTF-8)>.
833 C<:utf8> just marks the data as UTF-8 without further checking,
834 while C<:encoding(UTF-8)> checks the data for actually being valid
835 UTF-8. More details can be found in L<PerlIO::encoding>.
837 In general, L<C<binmode>|/binmode FILEHANDLE, LAYER> should be called
838 after L<C<open>|/open FILEHANDLE,EXPR> but before any I/O is done on the
839 filehandle. Calling L<C<binmode>|/binmode FILEHANDLE, LAYER> normally
840 flushes any pending buffered output data (and perhaps pending input
841 data) on the handle. An exception to this is the C<:encoding> layer
842 that changes the default character encoding of the handle.
843 The C<:encoding> layer sometimes needs to be called in
844 mid-stream, and it doesn't flush the stream. C<:encoding>
845 also implicitly pushes on top of itself the C<:utf8> layer because
846 internally Perl operates on UTF8-encoded Unicode characters.
848 The operating system, device drivers, C libraries, and Perl run-time
849 system all conspire to let the programmer treat a single
850 character (C<\n>) as the line terminator, irrespective of external
851 representation. On many operating systems, the native text file
852 representation matches the internal representation, but on some
853 platforms the external representation of C<\n> is made up of more than
856 All variants of Unix, Mac OS (old and new), and Stream_LF files on VMS use
857 a single character to end each line in the external representation of text
858 (even though that single character is CARRIAGE RETURN on old, pre-Darwin
859 flavors of Mac OS, and is LINE FEED on Unix and most VMS files). In other
860 systems like OS/2, DOS, and the various flavors of MS-Windows, your program
861 sees a C<\n> as a simple C<\cJ>, but what's stored in text files are the
862 two characters C<\cM\cJ>. That means that if you don't use
863 L<C<binmode>|/binmode FILEHANDLE, LAYER> on these systems, C<\cM\cJ>
864 sequences on disk will be converted to C<\n> on input, and any C<\n> in
865 your program will be converted back to C<\cM\cJ> on output. This is
866 what you want for text files, but it can be disastrous for binary files.
868 Another consequence of using L<C<binmode>|/binmode FILEHANDLE, LAYER>
869 (on some systems) is that special end-of-file markers will be seen as
870 part of the data stream. For systems from the Microsoft family this
871 means that, if your binary data contain C<\cZ>, the I/O subsystem will
872 regard it as the end of the file, unless you use
873 L<C<binmode>|/binmode FILEHANDLE, LAYER>.
875 L<C<binmode>|/binmode FILEHANDLE, LAYER> is important not only for
876 L<C<readline>|/readline EXPR> and L<C<print>|/print FILEHANDLE LIST>
877 operations, but also when using
878 L<C<read>|/read FILEHANDLE,SCALAR,LENGTH,OFFSET>,
879 L<C<seek>|/seek FILEHANDLE,POSITION,WHENCE>,
880 L<C<sysread>|/sysread FILEHANDLE,SCALAR,LENGTH,OFFSET>,
881 L<C<syswrite>|/syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET> and
882 L<C<tell>|/tell FILEHANDLE> (see L<perlport> for more details). See the
883 L<C<$E<sol>>|perlvar/$E<sol>> and L<C<$\>|perlvar/$\> variables in
884 L<perlvar> for how to manually set your input and output
885 line-termination sequences.
887 Portability issues: L<perlport/binmode>.
889 =item bless REF,CLASSNAME
894 =for Pod::Functions create an object
896 This function tells the thingy referenced by REF that it is now an object
897 in the CLASSNAME package. If CLASSNAME is an empty string, it is
898 interpreted as referring to the C<main> package.
899 If CLASSNAME is omitted, the current package
900 is used. Because a L<C<bless>|/bless REF,CLASSNAME> is often the last
901 thing in a constructor, it returns the reference for convenience.
902 Always use the two-argument version if a derived class might inherit the
903 method doing the blessing. See L<perlobj> for more about the blessing
904 (and blessings) of objects.
906 Consider always blessing objects in CLASSNAMEs that are mixed case.
907 Namespaces with all lowercase names are considered reserved for
908 Perl pragmas. Builtin types have all uppercase names. To prevent
909 confusion, you may wish to avoid such package names as well.
910 It is advised to avoid the class name C<0>, because much code erroneously
911 uses the result of L<C<ref>|/ref EXPR> as a truth value.
913 See L<perlmod/"Perl Modules">.
917 =for Pod::Functions +switch break out of a C<given> block
919 Break out of a C<given> block.
921 L<C<break>|/break> is available only if the
922 L<C<"switch"> feature|feature/The 'switch' feature> is enabled or if it
923 is prefixed with C<CORE::>. The
924 L<C<"switch"> feature|feature/The 'switch' feature> is enabled
925 automatically with a C<use v5.10> (or higher) declaration in the current
929 X<caller> X<call stack> X<stack> X<stack trace>
933 =for Pod::Functions get context of the current subroutine call
935 Returns the context of the current pure perl subroutine call. In scalar
936 context, returns the caller's package name if there I<is> a caller (that is, if
937 we're in a subroutine or L<C<eval>|/eval EXPR> or
938 L<C<require>|/require VERSION>) and the undefined value otherwise.
939 caller never returns XS subs and they are skipped. The next pure perl
940 sub will appear instead of the XS sub in caller's return values. In
941 list context, caller returns
944 my ($package, $filename, $line) = caller;
946 With EXPR, it returns some extra information that the debugger uses to
947 print a stack trace. The value of EXPR indicates how many call frames
948 to go back before the current one.
951 my ($package, $filename, $line, $subroutine, $hasargs,
954 $wantarray, $evaltext, $is_require, $hints, $bitmask, $hinthash)
957 Here, $subroutine is the function that the caller called (rather than the
958 function containing the caller). Note that $subroutine may be C<(eval)> if
959 the frame is not a subroutine call, but an L<C<eval>|/eval EXPR>. In
960 such a case additional elements $evaltext and C<$is_require> are set:
961 C<$is_require> is true if the frame is created by a
962 L<C<require>|/require VERSION> or L<C<use>|/use Module VERSION LIST>
963 statement, $evaltext contains the text of the C<eval EXPR> statement.
964 In particular, for an C<eval BLOCK> statement, $subroutine is C<(eval)>,
965 but $evaltext is undefined. (Note also that each
966 L<C<use>|/use Module VERSION LIST> statement creates a
967 L<C<require>|/require VERSION> frame inside an C<eval EXPR> frame.)
968 $subroutine may also be C<(unknown)> if this particular subroutine
969 happens to have been deleted from the symbol table. C<$hasargs> is true
970 if a new instance of L<C<@_>|perlvar/@_> was set up for the frame.
971 C<$hints> and C<$bitmask> contain pragmatic hints that the caller was
972 compiled with. C<$hints> corresponds to L<C<$^H>|perlvar/$^H>, and
973 C<$bitmask> corresponds to
974 L<C<${^WARNING_BITS}>|perlvar/${^WARNING_BITS}>. The C<$hints> and
975 C<$bitmask> values are subject to change between versions of Perl, and
976 are not meant for external use.
978 C<$hinthash> is a reference to a hash containing the value of
979 L<C<%^H>|perlvar/%^H> when the caller was compiled, or
980 L<C<undef>|/undef EXPR> if L<C<%^H>|perlvar/%^H> was empty. Do not
981 modify the values of this hash, as they are the actual values stored in
984 Furthermore, when called from within the DB package in
985 list context, and with an argument, caller returns more
986 detailed information: it sets the list variable C<@DB::args> to be the
987 arguments with which the subroutine was invoked.
989 Be aware that the optimizer might have optimized call frames away before
990 L<C<caller>|/caller EXPR> had a chance to get the information. That
991 means that C<caller(N)> might not return information about the call
992 frame you expect it to, for C<< N > 1 >>. In particular, C<@DB::args>
993 might have information from the previous time L<C<caller>|/caller EXPR>
996 Be aware that setting C<@DB::args> is I<best effort>, intended for
997 debugging or generating backtraces, and should not be relied upon. In
998 particular, as L<C<@_>|perlvar/@_> contains aliases to the caller's
999 arguments, Perl does not take a copy of L<C<@_>|perlvar/@_>, so
1000 C<@DB::args> will contain modifications the subroutine makes to
1001 L<C<@_>|perlvar/@_> or its contents, not the original values at call
1002 time. C<@DB::args>, like L<C<@_>|perlvar/@_>, does not hold explicit
1003 references to its elements, so under certain cases its elements may have
1004 become freed and reallocated for other variables or temporary values.
1005 Finally, a side effect of the current implementation is that the effects
1006 of C<shift @_> can I<normally> be undone (but not C<pop @_> or other
1007 splicing, I<and> not if a reference to L<C<@_>|perlvar/@_> has been
1008 taken, I<and> subject to the caveat about reallocated elements), so
1009 C<@DB::args> is actually a hybrid of the current state and initial state
1010 of L<C<@_>|perlvar/@_>. Buyer beware.
1015 X<directory, change>
1017 =item chdir FILEHANDLE
1019 =item chdir DIRHANDLE
1023 =for Pod::Functions change your current working directory
1025 Changes the working directory to EXPR, if possible. If EXPR is omitted,
1026 changes to the directory specified by C<$ENV{HOME}>, if set; if not,
1027 changes to the directory specified by C<$ENV{LOGDIR}>. (Under VMS, the
1028 variable C<$ENV{'SYS$LOGIN'}> is also checked, and used if it is set.) If
1029 neither is set, L<C<chdir>|/chdir EXPR> does nothing and fails. It
1030 returns true on success, false otherwise. See the example under
1031 L<C<die>|/die LIST>.
1033 On systems that support L<fchdir(2)>, you may pass a filehandle or
1034 directory handle as the argument. On systems that don't support L<fchdir(2)>,
1035 passing handles raises an exception.
1038 X<chmod> X<permission> X<mode>
1040 =for Pod::Functions changes the permissions on a list of files
1042 Changes the permissions of a list of files. The first element of the
1043 list must be the numeric mode, which should probably be an octal
1044 number, and which definitely should I<not> be a string of octal digits:
1045 C<0644> is okay, but C<"0644"> is not. Returns the number of files
1046 successfully changed. See also L<C<oct>|/oct EXPR> if all you have is a
1049 my $cnt = chmod 0755, "foo", "bar";
1050 chmod 0755, @executables;
1051 my $mode = "0644"; chmod $mode, "foo"; # !!! sets mode to
1053 my $mode = "0644"; chmod oct($mode), "foo"; # this is better
1054 my $mode = 0644; chmod $mode, "foo"; # this is best
1056 On systems that support L<fchmod(2)>, you may pass filehandles among the
1057 files. On systems that don't support L<fchmod(2)>, passing filehandles raises
1058 an exception. Filehandles must be passed as globs or glob references to be
1059 recognized; barewords are considered filenames.
1061 open(my $fh, "<", "foo");
1062 my $perm = (stat $fh)[2] & 07777;
1063 chmod($perm | 0600, $fh);
1065 You can also import the symbolic C<S_I*> constants from the
1066 L<C<Fcntl>|Fcntl> module:
1068 use Fcntl qw( :mode );
1069 chmod S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH|S_IXOTH, @executables;
1070 # Identical to the chmod 0755 of the example above.
1072 Portability issues: L<perlport/chmod>.
1074 =item chomp VARIABLE
1075 X<chomp> X<INPUT_RECORD_SEPARATOR> X<$/> X<newline> X<eol>
1081 =for Pod::Functions remove a trailing record separator from a string
1083 This safer version of L<C<chop>|/chop VARIABLE> removes any trailing
1084 string that corresponds to the current value of
1085 L<C<$E<sol>>|perlvar/$E<sol>> (also known as C<$INPUT_RECORD_SEPARATOR>
1086 in the L<C<English>|English> module). It returns the total
1087 number of characters removed from all its arguments. It's often used to
1088 remove the newline from the end of an input record when you're worried
1089 that the final record may be missing its newline. When in paragraph
1090 mode (C<$/ = ''>), it removes all trailing newlines from the string.
1091 When in slurp mode (C<$/ = undef>) or fixed-length record mode
1092 (L<C<$E<sol>>|perlvar/$E<sol>> is a reference to an integer or the like;
1093 see L<perlvar>), L<C<chomp>|/chomp VARIABLE> won't remove anything.
1094 If VARIABLE is omitted, it chomps L<C<$_>|perlvar/$_>. Example:
1097 chomp; # avoid \n on last field
1098 my @array = split(/:/);
1102 If VARIABLE is a hash, it chomps the hash's values, but not its keys,
1103 resetting the L<C<each>|/each HASH> iterator in the process.
1105 You can actually chomp anything that's an lvalue, including an assignment:
1107 chomp(my $cwd = `pwd`);
1108 chomp(my $answer = <STDIN>);
1110 If you chomp a list, each element is chomped, and the total number of
1111 characters removed is returned.
1113 Note that parentheses are necessary when you're chomping anything
1114 that is not a simple variable. This is because C<chomp $cwd = `pwd`;>
1115 is interpreted as C<(chomp $cwd) = `pwd`;>, rather than as
1116 C<chomp( $cwd = `pwd` )> which you might expect. Similarly,
1117 C<chomp $a, $b> is interpreted as C<chomp($a), $b> rather than
1118 as C<chomp($a, $b)>.
1127 =for Pod::Functions remove the last character from a string
1129 Chops off the last character of a string and returns the character
1130 chopped. It is much more efficient than C<s/.$//s> because it neither
1131 scans nor copies the string. If VARIABLE is omitted, chops
1132 L<C<$_>|perlvar/$_>.
1133 If VARIABLE is a hash, it chops the hash's values, but not its keys,
1134 resetting the L<C<each>|/each HASH> iterator in the process.
1136 You can actually chop anything that's an lvalue, including an assignment.
1138 If you chop a list, each element is chopped. Only the value of the
1139 last L<C<chop>|/chop VARIABLE> is returned.
1141 Note that L<C<chop>|/chop VARIABLE> returns the last character. To
1142 return all but the last character, use C<substr($string, 0, -1)>.
1144 See also L<C<chomp>|/chomp VARIABLE>.
1147 X<chown> X<owner> X<user> X<group>
1149 =for Pod::Functions change the ownership on a list of files
1151 Changes the owner (and group) of a list of files. The first two
1152 elements of the list must be the I<numeric> uid and gid, in that
1153 order. A value of -1 in either position is interpreted by most
1154 systems to leave that value unchanged. Returns the number of files
1155 successfully changed.
1157 my $cnt = chown $uid, $gid, 'foo', 'bar';
1158 chown $uid, $gid, @filenames;
1160 On systems that support L<fchown(2)>, you may pass filehandles among the
1161 files. On systems that don't support L<fchown(2)>, passing filehandles raises
1162 an exception. Filehandles must be passed as globs or glob references to be
1163 recognized; barewords are considered filenames.
1165 Here's an example that looks up nonnumeric uids in the passwd file:
1168 chomp(my $user = <STDIN>);
1170 chomp(my $pattern = <STDIN>);
1172 my ($login,$pass,$uid,$gid) = getpwnam($user)
1173 or die "$user not in passwd file";
1175 my @ary = glob($pattern); # expand filenames
1176 chown $uid, $gid, @ary;
1178 On most systems, you are not allowed to change the ownership of the
1179 file unless you're the superuser, although you should be able to change
1180 the group to any of your secondary groups. On insecure systems, these
1181 restrictions may be relaxed, but this is not a portable assumption.
1182 On POSIX systems, you can detect this condition this way:
1184 use POSIX qw(sysconf _PC_CHOWN_RESTRICTED);
1185 my $can_chown_giveaway = ! sysconf(_PC_CHOWN_RESTRICTED);
1187 Portability issues: L<perlport/chown>.
1190 X<chr> X<character> X<ASCII> X<Unicode>
1194 =for Pod::Functions get character this number represents
1196 Returns the character represented by that NUMBER in the character set.
1197 For example, C<chr(65)> is C<"A"> in either ASCII or Unicode, and
1198 chr(0x263a) is a Unicode smiley face.
1200 Negative values give the Unicode replacement character (chr(0xfffd)),
1201 except under the L<bytes> pragma, where the low eight bits of the value
1202 (truncated to an integer) are used.
1204 If NUMBER is omitted, uses L<C<$_>|perlvar/$_>.
1206 For the reverse, use L<C<ord>|/ord EXPR>.
1208 Note that characters from 128 to 255 (inclusive) are by default
1209 internally not encoded as UTF-8 for backward compatibility reasons.
1211 See L<perlunicode> for more about Unicode.
1213 =item chroot FILENAME
1218 =for Pod::Functions make directory new root for path lookups
1220 This function works like the system call by the same name: it makes the
1221 named directory the new root directory for all further pathnames that
1222 begin with a C</> by your process and all its children. (It doesn't
1223 change your current working directory, which is unaffected.) For security
1224 reasons, this call is restricted to the superuser. If FILENAME is
1225 omitted, does a L<C<chroot>|/chroot FILENAME> to L<C<$_>|perlvar/$_>.
1227 B<NOTE:> It is good security practice to do C<chdir("/")>
1228 (L<C<chdir>|/chdir EXPR> to the root directory) immediately after a
1229 L<C<chroot>|/chroot FILENAME>.
1231 Portability issues: L<perlport/chroot>.
1233 =item close FILEHANDLE
1238 =for Pod::Functions close file (or pipe or socket) handle
1240 Closes the file or pipe associated with the filehandle, flushes the IO
1241 buffers, and closes the system file descriptor. Returns true if those
1242 operations succeed and if no error was reported by any PerlIO
1243 layer. Closes the currently selected filehandle if the argument is
1246 You don't have to close FILEHANDLE if you are immediately going to do
1247 another L<C<open>|/open FILEHANDLE,EXPR> on it, because
1248 L<C<open>|/open FILEHANDLE,EXPR> closes it for you. (See
1249 L<C<open>|/open FILEHANDLE,EXPR>.) However, an explicit
1250 L<C<close>|/close FILEHANDLE> on an input file resets the line counter
1251 (L<C<$.>|perlvar/$.>), while the implicit close done by
1252 L<C<open>|/open FILEHANDLE,EXPR> does not.
1254 If the filehandle came from a piped open, L<C<close>|/close FILEHANDLE>
1255 returns false if one of the other syscalls involved fails or if its
1256 program exits with non-zero status. If the only problem was that the
1257 program exited non-zero, L<C<$!>|perlvar/$!> will be set to C<0>.
1258 Closing a pipe also waits for the process executing on the pipe to
1259 exit--in case you wish to look at the output of the pipe afterwards--and
1260 implicitly puts the exit status value of that command into
1261 L<C<$?>|perlvar/$?> and
1262 L<C<${^CHILD_ERROR_NATIVE}>|perlvar/${^CHILD_ERROR_NATIVE}>.
1264 If there are multiple threads running, L<C<close>|/close FILEHANDLE> on
1265 a filehandle from a piped open returns true without waiting for the
1266 child process to terminate, if the filehandle is still open in another
1269 Closing the read end of a pipe before the process writing to it at the
1270 other end is done writing results in the writer receiving a SIGPIPE. If
1271 the other end can't handle that, be sure to read all the data before
1276 open(OUTPUT, '|sort >foo') # pipe to sort
1277 or die "Can't start sort: $!";
1278 #... # print stuff to output
1279 close OUTPUT # wait for sort to finish
1280 or warn $! ? "Error closing sort pipe: $!"
1281 : "Exit status $? from sort";
1282 open(INPUT, 'foo') # get sort's results
1283 or die "Can't open 'foo' for input: $!";
1285 FILEHANDLE may be an expression whose value can be used as an indirect
1286 filehandle, usually the real filehandle name or an autovivified handle.
1288 =item closedir DIRHANDLE
1291 =for Pod::Functions close directory handle
1293 Closes a directory opened by L<C<opendir>|/opendir DIRHANDLE,EXPR> and
1294 returns the success of that system call.
1296 =item connect SOCKET,NAME
1299 =for Pod::Functions connect to a remote socket
1301 Attempts to connect to a remote socket, just like L<connect(2)>.
1302 Returns true if it succeeded, false otherwise. NAME should be a
1303 packed address of the appropriate type for the socket. See the examples in
1304 L<perlipc/"Sockets: Client/Server Communication">.
1306 =item continue BLOCK
1311 =for Pod::Functions optional trailing block in a while or foreach
1313 When followed by a BLOCK, L<C<continue>|/continue BLOCK> is actually a
1314 flow control statement rather than a function. If there is a
1315 L<C<continue>|/continue BLOCK> BLOCK attached to a BLOCK (typically in a
1316 C<while> or C<foreach>), it is always executed just before the
1317 conditional is about to be evaluated again, just like the third part of
1318 a C<for> loop in C. Thus it can be used to increment a loop variable,
1319 even when the loop has been continued via the L<C<next>|/next LABEL>
1320 statement (which is similar to the C L<C<continue>|/continue BLOCK>
1323 L<C<last>|/last LABEL>, L<C<next>|/next LABEL>, or
1324 L<C<redo>|/redo LABEL> may appear within a
1325 L<C<continue>|/continue BLOCK> block; L<C<last>|/last LABEL> and
1326 L<C<redo>|/redo LABEL> behave as if they had been executed within the
1327 main block. So will L<C<next>|/next LABEL>, but since it will execute a
1328 L<C<continue>|/continue BLOCK> block, it may be more entertaining.
1331 ### redo always comes here
1334 ### next always comes here
1336 # then back the top to re-check EXPR
1338 ### last always comes here
1340 Omitting the L<C<continue>|/continue BLOCK> section is equivalent to
1341 using an empty one, logically enough, so L<C<next>|/next LABEL> goes
1342 directly back to check the condition at the top of the loop.
1344 When there is no BLOCK, L<C<continue>|/continue BLOCK> is a function
1345 that falls through the current C<when> or C<default> block instead of
1346 iterating a dynamically enclosing C<foreach> or exiting a lexically
1347 enclosing C<given>. In Perl 5.14 and earlier, this form of
1348 L<C<continue>|/continue BLOCK> was only available when the
1349 L<C<"switch"> feature|feature/The 'switch' feature> was enabled. See
1350 L<feature> and L<perlsyn/"Switch Statements"> for more information.
1353 X<cos> X<cosine> X<acos> X<arccosine>
1357 =for Pod::Functions cosine function
1359 Returns the cosine of EXPR (expressed in radians). If EXPR is omitted,
1360 takes the cosine of L<C<$_>|perlvar/$_>.
1362 For the inverse cosine operation, you may use the
1363 L<C<Math::Trig::acos>|Math::Trig> function, or use this relation:
1365 sub acos { atan2( sqrt(1 - $_[0] * $_[0]), $_[0] ) }
1367 =item crypt PLAINTEXT,SALT
1368 X<crypt> X<digest> X<hash> X<salt> X<plaintext> X<password>
1369 X<decrypt> X<cryptography> X<passwd> X<encrypt>
1371 =for Pod::Functions one-way passwd-style encryption
1373 Creates a digest string exactly like the L<crypt(3)> function in the C
1374 library (assuming that you actually have a version there that has not
1375 been extirpated as a potential munition).
1377 L<C<crypt>|/crypt PLAINTEXT,SALT> is a one-way hash function. The
1378 PLAINTEXT and SALT are turned
1379 into a short string, called a digest, which is returned. The same
1380 PLAINTEXT and SALT will always return the same string, but there is no
1381 (known) way to get the original PLAINTEXT from the hash. Small
1382 changes in the PLAINTEXT or SALT will result in large changes in the
1385 There is no decrypt function. This function isn't all that useful for
1386 cryptography (for that, look for F<Crypt> modules on your nearby CPAN
1387 mirror) and the name "crypt" is a bit of a misnomer. Instead it is
1388 primarily used to check if two pieces of text are the same without
1389 having to transmit or store the text itself. An example is checking
1390 if a correct password is given. The digest of the password is stored,
1391 not the password itself. The user types in a password that is
1392 L<C<crypt>|/crypt PLAINTEXT,SALT>'d with the same salt as the stored
1393 digest. If the two digests match, the password is correct.
1395 When verifying an existing digest string you should use the digest as
1396 the salt (like C<crypt($plain, $digest) eq $digest>). The SALT used
1397 to create the digest is visible as part of the digest. This ensures
1398 L<C<crypt>|/crypt PLAINTEXT,SALT> will hash the new string with the same
1399 salt as the digest. This allows your code to work with the standard
1400 L<C<crypt>|/crypt PLAINTEXT,SALT> and with more exotic implementations.
1401 In other words, assume nothing about the returned string itself nor
1402 about how many bytes of SALT may matter.
1404 Traditionally the result is a string of 13 bytes: two first bytes of
1405 the salt, followed by 11 bytes from the set C<[./0-9A-Za-z]>, and only
1406 the first eight bytes of PLAINTEXT mattered. But alternative
1407 hashing schemes (like MD5), higher level security schemes (like C2),
1408 and implementations on non-Unix platforms may produce different
1411 When choosing a new salt create a random two character string whose
1412 characters come from the set C<[./0-9A-Za-z]> (like C<join '', ('.',
1413 '/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]>). This set of
1414 characters is just a recommendation; the characters allowed in
1415 the salt depend solely on your system's crypt library, and Perl can't
1416 restrict what salts L<C<crypt>|/crypt PLAINTEXT,SALT> accepts.
1418 Here's an example that makes sure that whoever runs this program knows
1421 my $pwd = (getpwuid($<))[1];
1423 system "stty -echo";
1425 chomp(my $word = <STDIN>);
1429 if (crypt($word, $pwd) ne $pwd) {
1435 Of course, typing in your own password to whoever asks you
1438 The L<C<crypt>|/crypt PLAINTEXT,SALT> function is unsuitable for hashing
1439 large quantities of data, not least of all because you can't get the
1440 information back. Look at the L<Digest> module for more robust
1443 If using L<C<crypt>|/crypt PLAINTEXT,SALT> on a Unicode string (which
1444 I<potentially> has characters with codepoints above 255), Perl tries to
1445 make sense of the situation by trying to downgrade (a copy of) the
1446 string back to an eight-bit byte string before calling
1447 L<C<crypt>|/crypt PLAINTEXT,SALT> (on that copy). If that works, good.
1448 If not, L<C<crypt>|/crypt PLAINTEXT,SALT> dies with
1449 L<C<Wide character in crypt>|perldiag/Wide character in %s>.
1451 Portability issues: L<perlport/crypt>.
1456 =for Pod::Functions breaks binding on a tied dbm file
1458 [This function has been largely superseded by the
1459 L<C<untie>|/untie VARIABLE> function.]
1461 Breaks the binding between a DBM file and a hash.
1463 Portability issues: L<perlport/dbmclose>.
1465 =item dbmopen HASH,DBNAME,MASK
1466 X<dbmopen> X<dbm> X<ndbm> X<sdbm> X<gdbm>
1468 =for Pod::Functions create binding on a tied dbm file
1470 [This function has been largely superseded by the
1471 L<C<tie>|/tie VARIABLE,CLASSNAME,LIST> function.]
1473 This binds a L<dbm(3)>, L<ndbm(3)>, L<sdbm(3)>, L<gdbm(3)>, or Berkeley
1474 DB file to a hash. HASH is the name of the hash. (Unlike normal
1475 L<C<open>|/open FILEHANDLE,EXPR>, the first argument is I<not> a
1476 filehandle, even though it looks like one). DBNAME is the name of the
1477 database (without the F<.dir> or F<.pag> extension if any). If the
1478 database does not exist, it is created with protection specified by MASK
1479 (as modified by the L<C<umask>|/umask EXPR>). To prevent creation of
1480 the database if it doesn't exist, you may specify a MODE of 0, and the
1481 function will return a false value if it can't find an existing
1482 database. If your system supports only the older DBM functions, you may
1483 make only one L<C<dbmopen>|/dbmopen HASH,DBNAME,MASK> call in your
1484 program. In older versions of Perl, if your system had neither DBM nor
1485 ndbm, calling L<C<dbmopen>|/dbmopen HASH,DBNAME,MASK> produced a fatal
1486 error; it now falls back to L<sdbm(3)>.
1488 If you don't have write access to the DBM file, you can only read hash
1489 variables, not set them. If you want to test whether you can write,
1490 either use file tests or try setting a dummy hash entry inside an
1491 L<C<eval>|/eval EXPR> to trap the error.
1493 Note that functions such as L<C<keys>|/keys HASH> and
1494 L<C<values>|/values HASH> may return huge lists when used on large DBM
1495 files. You may prefer to use the L<C<each>|/each HASH> function to
1496 iterate over large DBM files. Example:
1498 # print out history file offsets
1499 dbmopen(%HIST,'/usr/lib/news/history',0666);
1500 while (($key,$val) = each %HIST) {
1501 print $key, ' = ', unpack('L',$val), "\n";
1505 See also L<AnyDBM_File> for a more general description of the pros and
1506 cons of the various dbm approaches, as well as L<DB_File> for a particularly
1507 rich implementation.
1509 You can control which DBM library you use by loading that library
1510 before you call L<C<dbmopen>|/dbmopen HASH,DBNAME,MASK>:
1513 dbmopen(%NS_Hist, "$ENV{HOME}/.netscape/history.db")
1514 or die "Can't open netscape history file: $!";
1516 Portability issues: L<perlport/dbmopen>.
1519 X<defined> X<undef> X<undefined>
1523 =for Pod::Functions test whether a value, variable, or function is defined
1525 Returns a Boolean value telling whether EXPR has a value other than the
1526 undefined value L<C<undef>|/undef EXPR>. If EXPR is not present,
1527 L<C<$_>|perlvar/$_> is checked.
1529 Many operations return L<C<undef>|/undef EXPR> to indicate failure, end
1530 of file, system error, uninitialized variable, and other exceptional
1531 conditions. This function allows you to distinguish
1532 L<C<undef>|/undef EXPR> from other values. (A simple Boolean test will
1533 not distinguish among L<C<undef>|/undef EXPR>, zero, the empty string,
1534 and C<"0">, which are all equally false.) Note that since
1535 L<C<undef>|/undef EXPR> is a valid scalar, its presence doesn't
1536 I<necessarily> indicate an exceptional condition: L<C<pop>|/pop ARRAY>
1537 returns L<C<undef>|/undef EXPR> when its argument is an empty array,
1538 I<or> when the element to return happens to be L<C<undef>|/undef EXPR>.
1540 You may also use C<defined(&func)> to check whether subroutine C<func>
1541 has ever been defined. The return value is unaffected by any forward
1542 declarations of C<func>. A subroutine that is not defined
1543 may still be callable: its package may have an C<AUTOLOAD> method that
1544 makes it spring into existence the first time that it is called; see
1547 Use of L<C<defined>|/defined EXPR> on aggregates (hashes and arrays) is
1548 no longer supported. It used to report whether memory for that
1549 aggregate had ever been allocated. You should instead use a simple
1552 if (@an_array) { print "has array elements\n" }
1553 if (%a_hash) { print "has hash members\n" }
1555 When used on a hash element, it tells you whether the value is defined,
1556 not whether the key exists in the hash. Use L<C<exists>|/exists EXPR>
1557 for the latter purpose.
1561 print if defined $switch{D};
1562 print "$val\n" while defined($val = pop(@ary));
1563 die "Can't readlink $sym: $!"
1564 unless defined($value = readlink $sym);
1565 sub foo { defined &$bar ? $bar->(@_) : die "No bar"; }
1566 $debugging = 0 unless defined $debugging;
1568 Note: Many folks tend to overuse L<C<defined>|/defined EXPR> and are
1569 then surprised to discover that the number C<0> and C<""> (the
1570 zero-length string) are, in fact, defined values. For example, if you
1575 The pattern match succeeds and C<$1> is defined, although it
1576 matched "nothing". It didn't really fail to match anything. Rather, it
1577 matched something that happened to be zero characters long. This is all
1578 very above-board and honest. When a function returns an undefined value,
1579 it's an admission that it couldn't give you an honest answer. So you
1580 should use L<C<defined>|/defined EXPR> only when questioning the
1581 integrity of what you're trying to do. At other times, a simple
1582 comparison to C<0> or C<""> is what you want.
1584 See also L<C<undef>|/undef EXPR>, L<C<exists>|/exists EXPR>,
1585 L<C<ref>|/ref EXPR>.
1590 =for Pod::Functions deletes a value from a hash
1592 Given an expression that specifies an element or slice of a hash,
1593 L<C<delete>|/delete EXPR> deletes the specified elements from that hash
1594 so that L<C<exists>|/exists EXPR> on that element no longer returns
1595 true. Setting a hash element to the undefined value does not remove its
1596 key, but deleting it does; see L<C<exists>|/exists EXPR>.
1598 In list context, usually returns the value or values deleted, or the last such
1599 element in scalar context. The return list's length corresponds to that of
1600 the argument list: deleting non-existent elements returns the undefined value
1601 in their corresponding positions. When a
1602 L<keyE<sol>value hash slice|perldata/KeyE<sol>Value Hash Slices> is passed to
1603 C<delete>, the return value is a list of key/value pairs (two elements for each
1604 item deleted from the hash).
1606 L<C<delete>|/delete EXPR> may also be used on arrays and array slices,
1607 but its behavior is less straightforward. Although
1608 L<C<exists>|/exists EXPR> will return false for deleted entries,
1609 deleting array elements never changes indices of existing values; use
1610 L<C<shift>|/shift ARRAY> or L<C<splice>|/splice
1611 ARRAY,OFFSET,LENGTH,LIST> for that. However, if any deleted elements
1612 fall at the end of an array, the array's size shrinks to the position of
1613 the highest element that still tests true for L<C<exists>|/exists EXPR>,
1614 or to 0 if none do. In other words, an array won't have trailing
1615 nonexistent elements after a delete.
1617 B<WARNING:> Calling L<C<delete>|/delete EXPR> on array values is
1618 strongly discouraged. The
1619 notion of deleting or checking the existence of Perl array elements is not
1620 conceptually coherent, and can lead to surprising behavior.
1622 Deleting from L<C<%ENV>|perlvar/%ENV> modifies the environment.
1623 Deleting from a hash tied to a DBM file deletes the entry from the DBM
1624 file. Deleting from a L<C<tied>|/tied VARIABLE> hash or array may not
1625 necessarily return anything; it depends on the implementation of the
1626 L<C<tied>|/tied VARIABLE> package's DELETE method, which may do whatever
1629 The C<delete local EXPR> construct localizes the deletion to the current
1630 block at run time. Until the block exits, elements locally deleted
1631 temporarily no longer exist. See L<perlsub/"Localized deletion of elements
1632 of composite types">.
1634 my %hash = (foo => 11, bar => 22, baz => 33);
1635 my $scalar = delete $hash{foo}; # $scalar is 11
1636 $scalar = delete @hash{qw(foo bar)}; # $scalar is 22
1637 my @array = delete @hash{qw(foo baz)}; # @array is (undef,33)
1639 The following (inefficiently) deletes all the values of %HASH and @ARRAY:
1641 foreach my $key (keys %HASH) {
1645 foreach my $index (0 .. $#ARRAY) {
1646 delete $ARRAY[$index];
1651 delete @HASH{keys %HASH};
1653 delete @ARRAY[0 .. $#ARRAY];
1655 But both are slower than assigning the empty list
1656 or undefining %HASH or @ARRAY, which is the customary
1657 way to empty out an aggregate:
1659 %HASH = (); # completely empty %HASH
1660 undef %HASH; # forget %HASH ever existed
1662 @ARRAY = (); # completely empty @ARRAY
1663 undef @ARRAY; # forget @ARRAY ever existed
1665 The EXPR can be arbitrarily complicated provided its
1666 final operation is an element or slice of an aggregate:
1668 delete $ref->[$x][$y]{$key};
1669 delete @{$ref->[$x][$y]}{$key1, $key2, @morekeys};
1671 delete $ref->[$x][$y][$index];
1672 delete @{$ref->[$x][$y]}[$index1, $index2, @moreindices];
1675 X<die> X<throw> X<exception> X<raise> X<$@> X<abort>
1677 =for Pod::Functions raise an exception or bail out
1679 L<C<die>|/die LIST> raises an exception. Inside an L<C<eval>|/eval EXPR>
1680 the exception is stuffed into L<C<$@>|perlvar/$@> and the L<C<eval>|/eval
1681 EXPR> is terminated with the undefined value. If the exception is
1682 outside of all enclosing L<C<eval>|/eval EXPR>s, then the uncaught
1683 exception is printed to C<STDERR> and perl exits with an exit code
1684 indicating failure. If you need to exit the process with a specific
1685 exit code, see L<C<exit>|/exit EXPR>.
1687 Equivalent examples:
1689 die "Can't cd to spool: $!\n" unless chdir '/usr/spool/news';
1690 chdir '/usr/spool/news' or die "Can't cd to spool: $!\n"
1692 Most of the time, C<die> is called with a string to use as the exception.
1693 You may either give a single non-reference operand to serve as the
1694 exception, or a list of two or more items, which will be stringified
1695 and concatenated to make the exception.
1697 If the string exception does not end in a newline, the current
1698 script line number and input line number (if any) and a newline
1699 are appended to it. Note that the "input line number" (also
1700 known as "chunk") is subject to whatever notion of "line" happens to
1701 be currently in effect, and is also available as the special variable
1702 L<C<$.>|perlvar/$.>. See L<perlvar/"$/"> and L<perlvar/"$.">.
1704 Hint: sometimes appending C<", stopped"> to your message will cause it
1705 to make better sense when the string C<"at foo line 123"> is appended.
1706 Suppose you are running script "canasta".
1708 die "/etc/games is no good";
1709 die "/etc/games is no good, stopped";
1711 produce, respectively
1713 /etc/games is no good at canasta line 123.
1714 /etc/games is no good, stopped at canasta line 123.
1716 If LIST was empty or made an empty string, and L<C<$@>|perlvar/$@>
1717 already contains an exception value (typically from a previous
1718 L<C<eval>|/eval EXPR>), then that value is reused after
1719 appending C<"\t...propagated">. This is useful for propagating exceptions:
1722 die unless $@ =~ /Expected exception/;
1724 If LIST was empty or made an empty string,
1725 and L<C<$@>|perlvar/$@> contains an object
1726 reference that has a C<PROPAGATE> method, that method will be called
1727 with additional file and line number parameters. The return value
1728 replaces the value in L<C<$@>|perlvar/$@>; i.e., as if
1729 C<< $@ = eval { $@->PROPAGATE(__FILE__, __LINE__) }; >> were called.
1731 If LIST was empty or made an empty string, and L<C<$@>|perlvar/$@>
1732 is also empty, then the string C<"Died"> is used.
1734 You can also call L<C<die>|/die LIST> with a reference argument, and if
1735 this is trapped within an L<C<eval>|/eval EXPR>, L<C<$@>|perlvar/$@>
1736 contains that reference. This permits more elaborate exception handling
1737 using objects that maintain arbitrary state about the exception. Such a
1738 scheme is sometimes preferable to matching particular string values of
1739 L<C<$@>|perlvar/$@> with regular expressions.
1741 Because Perl stringifies uncaught exception messages before display,
1742 you'll probably want to overload stringification operations on
1743 exception objects. See L<overload> for details about that.
1744 The stringified message should be non-empty, and should end in a newline,
1745 in order to fit in with the treatment of string exceptions.
1746 Also, because an exception object reference cannot be stringified
1747 without destroying it, Perl doesn't attempt to append location or other
1748 information to a reference exception. If you want location information
1749 with a complex exception object, you'll have to arrange to put the
1750 location information into the object yourself.
1752 Because L<C<$@>|perlvar/$@> is a global variable, be careful that
1753 analyzing an exception caught by C<eval> doesn't replace the reference
1754 in the global variable. It's
1755 easiest to make a local copy of the reference before any manipulations.
1758 use Scalar::Util "blessed";
1760 eval { ... ; die Some::Module::Exception->new( FOO => "bar" ) };
1761 if (my $ev_err = $@) {
1762 if (blessed($ev_err)
1763 && $ev_err->isa("Some::Module::Exception")) {
1764 # handle Some::Module::Exception
1767 # handle all other possible exceptions
1771 If an uncaught exception results in interpreter exit, the exit code is
1772 determined from the values of L<C<$!>|perlvar/$!> and
1773 L<C<$?>|perlvar/$?> with this pseudocode:
1775 exit $! if $!; # errno
1776 exit $? >> 8 if $? >> 8; # child exit status
1777 exit 255; # last resort
1779 As with L<C<exit>|/exit EXPR>, L<C<$?>|perlvar/$?> is set prior to
1780 unwinding the call stack; any C<DESTROY> or C<END> handlers can then
1781 alter this value, and thus Perl's exit code.
1783 The intent is to squeeze as much possible information about the likely cause
1784 into the limited space of the system exit code. However, as
1785 L<C<$!>|perlvar/$!> is the value of C's C<errno>, which can be set by
1786 any system call, this means that the value of the exit code used by
1787 L<C<die>|/die LIST> can be non-predictable, so should not be relied
1788 upon, other than to be non-zero.
1790 You can arrange for a callback to be run just before the
1791 L<C<die>|/die LIST> does its deed, by setting the
1792 L<C<$SIG{__DIE__}>|perlvar/%SIG> hook. The associated handler is called
1793 with the exception as an argument, and can change the exception,
1795 calling L<C<die>|/die LIST> again. See L<perlvar/%SIG> for details on
1796 setting L<C<%SIG>|perlvar/%SIG> entries, and L<C<eval>|/eval EXPR> for some
1797 examples. Although this feature was to be run only right before your
1798 program was to exit, this is not currently so: the
1799 L<C<$SIG{__DIE__}>|perlvar/%SIG> hook is currently called even inside
1800 L<C<eval>|/eval EXPR>ed blocks/strings! If one wants the hook to do
1801 nothing in such situations, put
1805 as the first line of the handler (see L<perlvar/$^S>). Because
1806 this promotes strange action at a distance, this counterintuitive
1807 behavior may be fixed in a future release.
1809 See also L<C<exit>|/exit EXPR>, L<C<warn>|/warn LIST>, and the L<Carp>
1815 =for Pod::Functions turn a BLOCK into a TERM
1817 Not really a function. Returns the value of the last command in the
1818 sequence of commands indicated by BLOCK. When modified by the C<while> or
1819 C<until> loop modifier, executes the BLOCK once before testing the loop
1820 condition. (On other statements the loop modifiers test the conditional
1823 C<do BLOCK> does I<not> count as a loop, so the loop control statements
1824 L<C<next>|/next LABEL>, L<C<last>|/last LABEL>, or
1825 L<C<redo>|/redo LABEL> cannot be used to leave or restart the block.
1826 See L<perlsyn> for alternative strategies.
1831 Uses the value of EXPR as a filename and executes the contents of the
1832 file as a Perl script:
1834 # load the exact specified file (./ and ../ special-cased)
1837 do '../foo/stat.pl';
1839 # search for the named file within @INC
1843 C<do './stat.pl'> is largely like
1847 except that it's more concise, runs no external processes, and keeps
1848 track of the current filename for error messages. It also differs in that
1849 code evaluated with C<do FILE> cannot see lexicals in the enclosing
1850 scope; C<eval STRING> does. It's the same, however, in that it does
1851 reparse the file every time you call it, so you probably don't want
1852 to do this inside a loop.
1854 Using C<do> with a relative path (except for F<./> and F<../>), like
1858 will search the L<C<@INC>|perlvar/@INC> directories, and update
1859 L<C<%INC>|perlvar/%INC> if the file is found. See L<perlvar/@INC>
1860 and L<perlvar/%INC> for these variables. In particular, note that
1861 whilst historically L<C<@INC>|perlvar/@INC> contained '.' (the
1862 current directory) making these two cases equivalent, that is no
1863 longer necessarily the case, as '.' is not included in C<@INC> by default
1864 in perl versions 5.26.0 onwards. Instead, perl will now warn:
1866 do "stat.pl" failed, '.' is no longer in @INC;
1867 did you mean do "./stat.pl"?
1869 If L<C<do>|/do EXPR> can read the file but cannot compile it, it
1870 returns L<C<undef>|/undef EXPR> and sets an error message in
1871 L<C<$@>|perlvar/$@>. If L<C<do>|/do EXPR> cannot read the file, it
1872 returns undef and sets L<C<$!>|perlvar/$!> to the error. Always check
1873 L<C<$@>|perlvar/$@> first, as compilation could fail in a way that also
1874 sets L<C<$!>|perlvar/$!>. If the file is successfully compiled,
1875 L<C<do>|/do EXPR> returns the value of the last expression evaluated.
1877 Inclusion of library modules is better done with the
1878 L<C<use>|/use Module VERSION LIST> and L<C<require>|/require VERSION>
1879 operators, which also do automatic error checking and raise an exception
1880 if there's a problem.
1882 You might like to use L<C<do>|/do EXPR> to read in a program
1883 configuration file. Manual error checking can be done this way:
1885 # Read in config files: system first, then user.
1886 # Beware of using relative pathnames here.
1887 for $file ("/share/prog/defaults.rc",
1888 "$ENV{HOME}/.someprogrc")
1890 unless ($return = do $file) {
1891 warn "couldn't parse $file: $@" if $@;
1892 warn "couldn't do $file: $!" unless defined $return;
1893 warn "couldn't run $file" unless $return;
1898 X<dump> X<core> X<undump>
1904 =for Pod::Functions create an immediate core dump
1906 This function causes an immediate core dump. See also the B<-u>
1907 command-line switch in L<perlrun>, which does the same thing.
1908 Primarily this is so that you can use the B<undump> program (not
1909 supplied) to turn your core dump into an executable binary after
1910 having initialized all your variables at the beginning of the
1911 program. When the new binary is executed it will begin by executing
1912 a C<goto LABEL> (with all the restrictions that L<C<goto>|/goto LABEL>
1914 Think of it as a goto with an intervening core dump and reincarnation.
1915 If C<LABEL> is omitted, restarts the program from the top. The
1916 C<dump EXPR> form, available starting in Perl 5.18.0, allows a name to be
1917 computed at run time, being otherwise identical to C<dump LABEL>.
1919 B<WARNING>: Any files opened at the time of the dump will I<not>
1920 be open any more when the program is reincarnated, with possible
1921 resulting confusion by Perl.
1923 This function is now largely obsolete, mostly because it's very hard to
1924 convert a core file into an executable. That's why you should now invoke
1925 it as C<CORE::dump()> if you don't want to be warned against a possible
1928 Unlike most named operators, this has the same precedence as assignment.
1929 It is also exempt from the looks-like-a-function rule, so
1930 C<dump ("foo")."bar"> will cause "bar" to be part of the argument to
1931 L<C<dump>|/dump LABEL>.
1933 Portability issues: L<perlport/dump>.
1936 X<each> X<hash, iterator>
1941 =for Pod::Functions retrieve the next key/value pair from a hash
1943 When called on a hash in list context, returns a 2-element list
1944 consisting of the key and value for the next element of a hash. In Perl
1945 5.12 and later only, it will also return the index and value for the next
1946 element of an array so that you can iterate over it; older Perls consider
1947 this a syntax error. When called in scalar context, returns only the key
1948 (not the value) in a hash, or the index in an array.
1950 Hash entries are returned in an apparently random order. The actual random
1951 order is specific to a given hash; the exact same series of operations
1952 on two hashes may result in a different order for each hash. Any insertion
1953 into the hash may change the order, as will any deletion, with the exception
1954 that the most recent key returned by L<C<each>|/each HASH> or
1955 L<C<keys>|/keys HASH> may be deleted without changing the order. So
1956 long as a given hash is unmodified you may rely on
1957 L<C<keys>|/keys HASH>, L<C<values>|/values HASH> and
1958 L<C<each>|/each HASH> to repeatedly return the same order
1959 as each other. See L<perlsec/"Algorithmic Complexity Attacks"> for
1960 details on why hash order is randomized. Aside from the guarantees
1961 provided here the exact details of Perl's hash algorithm and the hash
1962 traversal order are subject to change in any release of Perl.
1964 After L<C<each>|/each HASH> has returned all entries from the hash or
1965 array, the next call to L<C<each>|/each HASH> returns the empty list in
1966 list context and L<C<undef>|/undef EXPR> in scalar context; the next
1967 call following I<that> one restarts iteration. Each hash or array has
1968 its own internal iterator, accessed by L<C<each>|/each HASH>,
1969 L<C<keys>|/keys HASH>, and L<C<values>|/values HASH>. The iterator is
1970 implicitly reset when L<C<each>|/each HASH> has reached the end as just
1971 described; it can be explicitly reset by calling L<C<keys>|/keys HASH>
1972 or L<C<values>|/values HASH> on the hash or array, or by referencing
1973 the hash (but not array) in list context. If you add or delete
1974 a hash's elements while iterating over it, the effect on the iterator is
1975 unspecified; for example, entries may be skipped or duplicated--so don't
1976 do that. Exception: It is always safe to delete the item most recently
1977 returned by L<C<each>|/each HASH>, so the following code works properly:
1979 while (my ($key, $value) = each %hash) {
1981 delete $hash{$key}; # This is safe
1984 Tied hashes may have a different ordering behaviour to perl's hash
1987 The iterator used by C<each> is attached to the hash or array, and is
1988 shared between all iteration operations applied to the same hash or array.
1989 Thus all uses of C<each> on a single hash or array advance the same
1990 iterator location. All uses of C<each> are also subject to having the
1991 iterator reset by any use of C<keys> or C<values> on the same hash or
1992 array, or by the hash (but not array) being referenced in list context.
1993 This makes C<each>-based loops quite fragile: it is easy to arrive at
1994 such a loop with the iterator already part way through the object, or to
1995 accidentally clobber the iterator state during execution of the loop body.
1996 It's easy enough to explicitly reset the iterator before starting a loop,
1997 but there is no way to insulate the iterator state used by a loop from
1998 the iterator state used by anything else that might execute during the
1999 loop body. To avoid these problems, use a C<foreach> loop rather than
2002 This prints out your environment like the L<printenv(1)> program,
2003 but in a different order:
2005 while (my ($key,$value) = each %ENV) {
2006 print "$key=$value\n";
2009 Starting with Perl 5.14, an experimental feature allowed
2010 L<C<each>|/each HASH> to take a scalar expression. This experiment has
2011 been deemed unsuccessful, and was removed as of Perl 5.24.
2013 As of Perl 5.18 you can use a bare L<C<each>|/each HASH> in a C<while>
2014 loop, which will set L<C<$_>|perlvar/$_> on every iteration.
2015 If either an C<each> expression or an explicit assignment of an C<each>
2016 expression to a scalar is used as a C<while>/C<for> condition, then
2017 the condition actually tests for definedness of the expression's value,
2018 not for its regular truth value.
2021 print "$_=$ENV{$_}\n";
2024 To avoid confusing would-be users of your code who are running earlier
2025 versions of Perl with mysterious syntax errors, put this sort of thing at
2026 the top of your file to signal that your code will work I<only> on Perls of
2029 use 5.012; # so keys/values/each work on arrays
2030 use 5.018; # so each assigns to $_ in a lone while test
2032 See also L<C<keys>|/keys HASH>, L<C<values>|/values HASH>, and
2033 L<C<sort>|/sort SUBNAME LIST>.
2035 =item eof FILEHANDLE
2044 =for Pod::Functions test a filehandle for its end
2046 Returns 1 if the next read on FILEHANDLE will return end of file I<or> if
2047 FILEHANDLE is not open. FILEHANDLE may be an expression whose value
2048 gives the real filehandle. (Note that this function actually
2049 reads a character and then C<ungetc>s it, so isn't useful in an
2050 interactive context.) Do not read from a terminal file (or call
2051 C<eof(FILEHANDLE)> on it) after end-of-file is reached. File types such
2052 as terminals may lose the end-of-file condition if you do.
2054 An L<C<eof>|/eof FILEHANDLE> without an argument uses the last file
2055 read. Using L<C<eof()>|/eof FILEHANDLE> with empty parentheses is
2056 different. It refers to the pseudo file formed from the files listed on
2057 the command line and accessed via the C<< <> >> operator. Since
2058 C<< <> >> isn't explicitly opened, as a normal filehandle is, an
2059 L<C<eof()>|/eof FILEHANDLE> before C<< <> >> has been used will cause
2060 L<C<@ARGV>|perlvar/@ARGV> to be examined to determine if input is
2061 available. Similarly, an L<C<eof()>|/eof FILEHANDLE> after C<< <> >>
2062 has returned end-of-file will assume you are processing another
2063 L<C<@ARGV>|perlvar/@ARGV> list, and if you haven't set
2064 L<C<@ARGV>|perlvar/@ARGV>, will read input from C<STDIN>; see
2065 L<perlop/"I/O Operators">.
2067 In a C<< while (<>) >> loop, L<C<eof>|/eof FILEHANDLE> or C<eof(ARGV)>
2068 can be used to detect the end of each file, whereas
2069 L<C<eof()>|/eof FILEHANDLE> will detect the end of the very last file
2072 # reset line numbering on each input file
2074 next if /^\s*#/; # skip comments
2077 close ARGV if eof; # Not eof()!
2080 # insert dashes just before last line of last file
2082 if (eof()) { # check for end of last file
2083 print "--------------\n";
2086 last if eof(); # needed if we're reading from a terminal
2089 Practical hint: you almost never need to use L<C<eof>|/eof FILEHANDLE>
2090 in Perl, because the input operators typically return L<C<undef>|/undef
2091 EXPR> when they run out of data or encounter an error.
2094 X<eval> X<try> X<catch> X<evaluate> X<parse> X<execute>
2095 X<error, handling> X<exception, handling>
2101 =for Pod::Functions catch exceptions or compile and run code
2103 C<eval> in all its forms is used to execute a little Perl program,
2104 trapping any errors encountered so they don't crash the calling program.
2106 Plain C<eval> with no argument is just C<eval EXPR>, where the
2107 expression is understood to be contained in L<C<$_>|perlvar/$_>. Thus
2108 there are only two real C<eval> forms; the one with an EXPR is often
2109 called "string eval". In a string eval, the value of the expression
2110 (which is itself determined within scalar context) is first parsed, and
2111 if there were no errors, executed as a block within the lexical context
2112 of the current Perl program. This form is typically used to delay
2113 parsing and subsequent execution of the text of EXPR until run time.
2114 Note that the value is parsed every time the C<eval> executes.
2116 The other form is called "block eval". It is less general than string
2117 eval, but the code within the BLOCK is parsed only once (at the same
2118 time the code surrounding the C<eval> itself was parsed) and executed
2119 within the context of the current Perl program. This form is typically
2120 used to trap exceptions more efficiently than the first, while also
2121 providing the benefit of checking the code within BLOCK at compile time.
2122 BLOCK is parsed and compiled just once. Since errors are trapped, it
2123 often is used to check if a given feature is available.
2125 In both forms, the value returned is the value of the last expression
2126 evaluated inside the mini-program; a return statement may also be used, just
2127 as with subroutines. The expression providing the return value is evaluated
2128 in void, scalar, or list context, depending on the context of the
2129 C<eval> itself. See L<C<wantarray>|/wantarray> for more
2130 on how the evaluation context can be determined.
2132 If there is a syntax error or runtime error, or a L<C<die>|/die LIST>
2133 statement is executed, C<eval> returns
2134 L<C<undef>|/undef EXPR> in scalar context, or an empty list in list
2135 context, and L<C<$@>|perlvar/$@> is set to the error message. (Prior to
2136 5.16, a bug caused L<C<undef>|/undef EXPR> to be returned in list
2137 context for syntax errors, but not for runtime errors.) If there was no
2138 error, L<C<$@>|perlvar/$@> is set to the empty string. A control flow
2139 operator like L<C<last>|/last LABEL> or L<C<goto>|/goto LABEL> can
2140 bypass the setting of L<C<$@>|perlvar/$@>. Beware that using
2141 C<eval> neither silences Perl from printing warnings to
2142 STDERR, nor does it stuff the text of warning messages into
2143 L<C<$@>|perlvar/$@>. To do either of those, you have to use the
2144 L<C<$SIG{__WARN__}>|perlvar/%SIG> facility, or turn off warnings inside
2145 the BLOCK or EXPR using S<C<no warnings 'all'>>. See
2146 L<C<warn>|/warn LIST>, L<perlvar>, and L<warnings>.
2148 Note that, because C<eval> traps otherwise-fatal errors,
2149 it is useful for determining whether a particular feature (such as
2150 L<C<socket>|/socket SOCKET,DOMAIN,TYPE,PROTOCOL> or
2151 L<C<symlink>|/symlink OLDFILE,NEWFILE>) is implemented. It is also
2152 Perl's exception-trapping mechanism, where the L<C<die>|/die LIST>
2153 operator is used to raise exceptions.
2155 Before Perl 5.14, the assignment to L<C<$@>|perlvar/$@> occurred before
2157 of localized variables, which means that for your code to run on older
2158 versions, a temporary is required if you want to mask some, but not all
2161 # alter $@ on nefarious repugnancy only
2165 local $@; # protect existing $@
2166 eval { test_repugnancy() };
2167 # $@ =~ /nefarious/ and die $@; # Perl 5.14 and higher only
2168 $@ =~ /nefarious/ and $e = $@;
2170 die $e if defined $e
2173 There are some different considerations for each form:
2179 Since the return value of EXPR is executed as a block within the lexical
2180 context of the current Perl program, any outer lexical variables are
2181 visible to it, and any package variable settings or subroutine and
2182 format definitions remain afterwards.
2186 =item Under the L<C<"unicode_eval"> feature|feature/The 'unicode_eval' and 'evalbytes' features>
2188 If this feature is enabled (which is the default under a C<use 5.16> or
2189 higher declaration), EXPR is considered to be
2190 in the same encoding as the surrounding program. Thus if
2191 S<L<C<use utf8>|utf8>> is in effect, the string will be treated as being
2192 UTF-8 encoded. Otherwise, the string is considered to be a sequence of
2193 independent bytes. Bytes that correspond to ASCII-range code points
2194 will have their normal meanings for operators in the string. The
2195 treatment of the other bytes depends on if the
2196 L<C<'unicode_strings"> feature|feature/The 'unicode_strings' feature> is
2199 In a plain C<eval> without an EXPR argument, being in S<C<use utf8>> or
2200 not is irrelevant; the UTF-8ness of C<$_> itself determines the
2203 Any S<C<use utf8>> or S<C<no utf8>> declarations within the string have
2204 no effect, and source filters are forbidden. (C<unicode_strings>,
2205 however, can appear within the string.) See also the
2206 L<C<evalbytes>|/evalbytes EXPR> operator, which works properly with
2209 Variables defined outside the C<eval> and used inside it retain their
2210 original UTF-8ness. Everything inside the string follows the normal
2211 rules for a Perl program with the given state of S<C<use utf8>>.
2213 =item Outside the C<"unicode_eval"> feature
2215 In this case, the behavior is problematic and is not so easily
2216 described. Here are two bugs that cannot easily be fixed without
2217 breaking existing programs:
2223 It can lose track of whether something should be encoded as UTF-8 or
2228 Source filters activated within C<eval> leak out into whichever file
2229 scope is currently being compiled. To give an example with the CPAN module
2230 L<Semi::Semicolons>:
2232 BEGIN { eval "use Semi::Semicolons; # not filtered" }
2235 L<C<evalbytes>|/evalbytes EXPR> fixes that to work the way one would
2238 use feature "evalbytes";
2239 BEGIN { evalbytes "use Semi::Semicolons; # filtered" }
2246 Problems can arise if the string expands a scalar containing a floating
2247 point number. That scalar can expand to letters, such as C<"NaN"> or
2248 C<"Infinity">; or, within the scope of a L<C<use locale>|locale>, the
2249 decimal point character may be something other than a dot (such as a
2250 comma). None of these are likely to parse as you are likely expecting.
2252 You should be especially careful to remember what's being looked at
2259 eval { $x }; # CASE 4
2261 eval "\$$x++"; # CASE 5
2264 Cases 1 and 2 above behave identically: they run the code contained in
2265 the variable $x. (Although case 2 has misleading double quotes making
2266 the reader wonder what else might be happening (nothing is).) Cases 3
2267 and 4 likewise behave in the same way: they run the code C<'$x'>, which
2268 does nothing but return the value of $x. (Case 4 is preferred for
2269 purely visual reasons, but it also has the advantage of compiling at
2270 compile-time instead of at run-time.) Case 5 is a place where
2271 normally you I<would> like to use double quotes, except that in this
2272 particular situation, you can just use symbolic references instead, as
2275 An C<eval ''> executed within a subroutine defined
2276 in the C<DB> package doesn't see the usual
2277 surrounding lexical scope, but rather the scope of the first non-DB piece
2278 of code that called it. You don't normally need to worry about this unless
2279 you are writing a Perl debugger.
2281 The final semicolon, if any, may be omitted from the value of EXPR.
2285 If the code to be executed doesn't vary, you may use the eval-BLOCK
2286 form to trap run-time errors without incurring the penalty of
2287 recompiling each time. The error, if any, is still returned in
2288 L<C<$@>|perlvar/$@>.
2291 # make divide-by-zero nonfatal
2292 eval { $answer = $a / $b; }; warn $@ if $@;
2294 # same thing, but less efficient
2295 eval '$answer = $a / $b'; warn $@ if $@;
2297 # a compile-time error
2298 eval { $answer = }; # WRONG
2301 eval '$answer ='; # sets $@
2303 If you want to trap errors when loading an XS module, some problems with
2304 the binary interface (such as Perl version skew) may be fatal even with
2305 C<eval> unless C<$ENV{PERL_DL_NONLAZY}> is set. See
2308 Using the C<eval {}> form as an exception trap in libraries does have some
2309 issues. Due to the current arguably broken state of C<__DIE__> hooks, you
2310 may wish not to trigger any C<__DIE__> hooks that user code may have installed.
2311 You can use the C<local $SIG{__DIE__}> construct for this purpose,
2312 as this example shows:
2314 # a private exception trap for divide-by-zero
2315 eval { local $SIG{'__DIE__'}; $answer = $a / $b; };
2318 This is especially significant, given that C<__DIE__> hooks can call
2319 L<C<die>|/die LIST> again, which has the effect of changing their error
2322 # __DIE__ hooks may modify error messages
2324 local $SIG{'__DIE__'} =
2325 sub { (my $x = $_[0]) =~ s/foo/bar/g; die $x };
2326 eval { die "foo lives here" };
2327 print $@ if $@; # prints "bar lives here"
2330 Because this promotes action at a distance, this counterintuitive behavior
2331 may be fixed in a future release.
2333 C<eval BLOCK> does I<not> count as a loop, so the loop control statements
2334 L<C<next>|/next LABEL>, L<C<last>|/last LABEL>, or
2335 L<C<redo>|/redo LABEL> cannot be used to leave or restart the block.
2337 The final semicolon, if any, may be omitted from within the BLOCK.
2341 =item evalbytes EXPR
2346 =for Pod::Functions +evalbytes similar to string eval, but intend to parse a bytestream
2348 This function is similar to a L<string eval|/eval EXPR>, except it
2349 always parses its argument (or L<C<$_>|perlvar/$_> if EXPR is omitted)
2350 as a string of independent bytes.
2352 If called when S<C<use utf8>> is in effect, the string will be assumed
2353 to be encoded in UTF-8, and C<evalbytes> will make a temporary copy to
2354 work from, downgraded to non-UTF-8. If this is not possible
2355 (because one or more characters in it require UTF-8), the C<evalbytes>
2356 will fail with the error stored in C<$@>.
2358 Bytes that correspond to ASCII-range code points will have their normal
2359 meanings for operators in the string. The treatment of the other bytes
2360 depends on if the L<C<'unicode_strings"> feature|feature/The
2361 'unicode_strings' feature> is in effect.
2363 Of course, variables that are UTF-8 and are referred to in the string
2367 evalbytes 'print ord $a, "\n"';
2375 Source filters activated within the evaluated code apply to the code
2378 L<C<evalbytes>|/evalbytes EXPR> is available starting in Perl v5.16. To
2379 access it, you must say C<CORE::evalbytes>, but you can omit the
2381 L<C<"evalbytes"> feature|feature/The 'unicode_eval' and 'evalbytes' features>
2382 is enabled. This is enabled automatically with a C<use v5.16> (or
2383 higher) declaration in the current scope.
2388 =item exec PROGRAM LIST
2390 =for Pod::Functions abandon this program to run another
2392 The L<C<exec>|/exec LIST> function executes a system command I<and never
2393 returns>; use L<C<system>|/system LIST> instead of L<C<exec>|/exec LIST>
2394 if you want it to return. It fails and
2395 returns false only if the command does not exist I<and> it is executed
2396 directly instead of via your system's command shell (see below).
2398 Since it's a common mistake to use L<C<exec>|/exec LIST> instead of
2399 L<C<system>|/system LIST>, Perl warns you if L<C<exec>|/exec LIST> is
2400 called in void context and if there is a following statement that isn't
2401 L<C<die>|/die LIST>, L<C<warn>|/warn LIST>, or L<C<exit>|/exit EXPR> (if
2402 L<warnings> are enabled--but you always do that, right?). If you
2403 I<really> want to follow an L<C<exec>|/exec LIST> with some other
2404 statement, you can use one of these styles to avoid the warning:
2406 exec ('foo') or print STDERR "couldn't exec foo: $!";
2407 { exec ('foo') }; print STDERR "couldn't exec foo: $!";
2409 If there is more than one argument in LIST, this calls L<execvp(3)> with the
2410 arguments in LIST. If there is only one element in LIST, the argument is
2411 checked for shell metacharacters, and if there are any, the entire
2412 argument is passed to the system's command shell for parsing (this is
2413 C</bin/sh -c> on Unix platforms, but varies on other platforms). If
2414 there are no shell metacharacters in the argument, it is split into words
2415 and passed directly to C<execvp>, which is more efficient. Examples:
2417 exec '/bin/echo', 'Your arguments are: ', @ARGV;
2418 exec "sort $outfile | uniq";
2420 If you don't really want to execute the first argument, but want to lie
2421 to the program you are executing about its own name, you can specify
2422 the program you actually want to run as an "indirect object" (without a
2423 comma) in front of the LIST, as in C<exec PROGRAM LIST>. (This always
2424 forces interpretation of the LIST as a multivalued list, even if there
2425 is only a single scalar in the list.) Example:
2427 my $shell = '/bin/csh';
2428 exec $shell '-sh'; # pretend it's a login shell
2432 exec {'/bin/csh'} '-sh'; # pretend it's a login shell
2434 When the arguments get executed via the system shell, results are
2435 subject to its quirks and capabilities. See L<perlop/"`STRING`">
2438 Using an indirect object with L<C<exec>|/exec LIST> or
2439 L<C<system>|/system LIST> is also more secure. This usage (which also
2440 works fine with L<C<system>|/system LIST>) forces
2441 interpretation of the arguments as a multivalued list, even if the
2442 list had just one argument. That way you're safe from the shell
2443 expanding wildcards or splitting up words with whitespace in them.
2445 my @args = ( "echo surprise" );
2447 exec @args; # subject to shell escapes
2449 exec { $args[0] } @args; # safe even with one-arg list
2451 The first version, the one without the indirect object, ran the I<echo>
2452 program, passing it C<"surprise"> an argument. The second version didn't;
2453 it tried to run a program named I<"echo surprise">, didn't find it, and set
2454 L<C<$?>|perlvar/$?> to a non-zero value indicating failure.
2456 On Windows, only the C<exec PROGRAM LIST> indirect object syntax will
2457 reliably avoid using the shell; C<exec LIST>, even with more than one
2458 element, will fall back to the shell if the first spawn fails.
2460 Perl attempts to flush all files opened for output before the exec,
2461 but this may not be supported on some platforms (see L<perlport>).
2462 To be safe, you may need to set L<C<$E<verbar>>|perlvar/$E<verbar>>
2463 (C<$AUTOFLUSH> in L<English>) or call the C<autoflush> method of
2464 L<C<IO::Handle>|IO::Handle/METHODS> on any open handles to avoid lost
2467 Note that L<C<exec>|/exec LIST> will not call your C<END> blocks, nor
2468 will it invoke C<DESTROY> methods on your objects.
2470 Portability issues: L<perlport/exec>.
2473 X<exists> X<autovivification>
2475 =for Pod::Functions test whether a hash key is present
2477 Given an expression that specifies an element of a hash, returns true if the
2478 specified element in the hash has ever been initialized, even if the
2479 corresponding value is undefined.
2481 print "Exists\n" if exists $hash{$key};
2482 print "Defined\n" if defined $hash{$key};
2483 print "True\n" if $hash{$key};
2485 exists may also be called on array elements, but its behavior is much less
2486 obvious and is strongly tied to the use of L<C<delete>|/delete EXPR> on
2489 B<WARNING:> Calling L<C<exists>|/exists EXPR> on array values is
2490 strongly discouraged. The
2491 notion of deleting or checking the existence of Perl array elements is not
2492 conceptually coherent, and can lead to surprising behavior.
2494 print "Exists\n" if exists $array[$index];
2495 print "Defined\n" if defined $array[$index];
2496 print "True\n" if $array[$index];
2498 A hash or array element can be true only if it's defined and defined only if
2499 it exists, but the reverse doesn't necessarily hold true.
2501 Given an expression that specifies the name of a subroutine,
2502 returns true if the specified subroutine has ever been declared, even
2503 if it is undefined. Mentioning a subroutine name for exists or defined
2504 does not count as declaring it. Note that a subroutine that does not
2505 exist may still be callable: its package may have an C<AUTOLOAD>
2506 method that makes it spring into existence the first time that it is
2507 called; see L<perlsub>.
2509 print "Exists\n" if exists &subroutine;
2510 print "Defined\n" if defined &subroutine;
2512 Note that the EXPR can be arbitrarily complicated as long as the final
2513 operation is a hash or array key lookup or subroutine name:
2515 if (exists $ref->{A}->{B}->{$key}) { }
2516 if (exists $hash{A}{B}{$key}) { }
2518 if (exists $ref->{A}->{B}->[$ix]) { }
2519 if (exists $hash{A}{B}[$ix]) { }
2521 if (exists &{$ref->{A}{B}{$key}}) { }
2523 Although the most deeply nested array or hash element will not spring into
2524 existence just because its existence was tested, any intervening ones will.
2525 Thus C<< $ref->{"A"} >> and C<< $ref->{"A"}->{"B"} >> will spring
2526 into existence due to the existence test for the C<$key> element above.
2527 This happens anywhere the arrow operator is used, including even here:
2530 if (exists $ref->{"Some key"}) { }
2531 print $ref; # prints HASH(0x80d3d5c)
2533 Use of a subroutine call, rather than a subroutine name, as an argument
2534 to L<C<exists>|/exists EXPR> is an error.
2537 exists &sub(); # Error
2540 X<exit> X<terminate> X<abort>
2544 =for Pod::Functions terminate this program
2546 Evaluates EXPR and exits immediately with that value. Example:
2549 exit 0 if $ans =~ /^[Xx]/;
2551 See also L<C<die>|/die LIST>. If EXPR is omitted, exits with C<0>
2553 universally recognized values for EXPR are C<0> for success and C<1>
2554 for error; other values are subject to interpretation depending on the
2555 environment in which the Perl program is running. For example, exiting
2556 69 (EX_UNAVAILABLE) from a I<sendmail> incoming-mail filter will cause
2557 the mailer to return the item undelivered, but that's not true everywhere.
2559 Don't use L<C<exit>|/exit EXPR> to abort a subroutine if there's any
2560 chance that someone might want to trap whatever error happened. Use
2561 L<C<die>|/die LIST> instead, which can be trapped by an
2562 L<C<eval>|/eval EXPR>.
2564 The L<C<exit>|/exit EXPR> function does not always exit immediately. It
2565 calls any defined C<END> routines first, but these C<END> routines may
2566 not themselves abort the exit. Likewise any object destructors that
2567 need to be called are called before the real exit. C<END> routines and
2568 destructors can change the exit status by modifying L<C<$?>|perlvar/$?>.
2569 If this is a problem, you can call
2570 L<C<POSIX::_exit($status)>|POSIX/C<_exit>> to avoid C<END> and destructor
2571 processing. See L<perlmod> for details.
2573 Portability issues: L<perlport/exit>.
2576 X<exp> X<exponential> X<antilog> X<antilogarithm> X<e>
2580 =for Pod::Functions raise I<e> to a power
2582 Returns I<e> (the natural logarithm base) to the power of EXPR.
2583 If EXPR is omitted, gives C<exp($_)>.
2586 X<fc> X<foldcase> X<casefold> X<fold-case> X<case-fold>
2590 =for Pod::Functions +fc return casefolded version of a string
2592 Returns the casefolded version of EXPR. This is the internal function
2593 implementing the C<\F> escape in double-quoted strings.
2595 Casefolding is the process of mapping strings to a form where case
2596 differences are erased; comparing two strings in their casefolded
2597 form is effectively a way of asking if two strings are equal,
2600 Roughly, if you ever found yourself writing this
2602 lc($this) eq lc($that) # Wrong!
2604 uc($this) eq uc($that) # Also wrong!
2606 $this =~ /^\Q$that\E\z/i # Right!
2610 fc($this) eq fc($that)
2612 And get the correct results.
2614 Perl only implements the full form of casefolding, but you can access
2615 the simple folds using L<Unicode::UCD/B<casefold()>> and
2616 L<Unicode::UCD/B<prop_invmap()>>.
2617 For further information on casefolding, refer to
2618 the Unicode Standard, specifically sections 3.13 C<Default Case Operations>,
2619 4.2 C<Case-Normative>, and 5.18 C<Case Mappings>,
2620 available at L<http://www.unicode.org/versions/latest/>, as well as the
2621 Case Charts available at L<http://www.unicode.org/charts/case/>.
2623 If EXPR is omitted, uses L<C<$_>|perlvar/$_>.
2625 This function behaves the same way under various pragmas, such as within
2626 L<S<C<"use feature 'unicode_strings">>|feature/The 'unicode_strings' feature>,
2627 as L<C<lc>|/lc EXPR> does, with the single exception of
2628 L<C<fc>|/fc EXPR> of I<LATIN CAPITAL LETTER SHARP S> (U+1E9E) within the
2629 scope of L<S<C<use locale>>|locale>. The foldcase of this character
2630 would normally be C<"ss">, but as explained in the L<C<lc>|/lc EXPR>
2632 changes that cross the 255/256 boundary are problematic under locales,
2633 and are hence prohibited. Therefore, this function under locale returns
2634 instead the string C<"\x{17F}\x{17F}">, which is the I<LATIN SMALL LETTER
2635 LONG S>. Since that character itself folds to C<"s">, the string of two
2636 of them together should be equivalent to a single U+1E9E when foldcased.
2638 While the Unicode Standard defines two additional forms of casefolding,
2639 one for Turkic languages and one that never maps one character into multiple
2640 characters, these are not provided by the Perl core. However, the CPAN module
2641 L<C<Unicode::Casing>|Unicode::Casing> may be used to provide an implementation.
2643 L<C<fc>|/fc EXPR> is available only if the
2644 L<C<"fc"> feature|feature/The 'fc' feature> is enabled or if it is
2645 prefixed with C<CORE::>. The
2646 L<C<"fc"> feature|feature/The 'fc' feature> is enabled automatically
2647 with a C<use v5.16> (or higher) declaration in the current scope.
2649 =item fcntl FILEHANDLE,FUNCTION,SCALAR
2652 =for Pod::Functions file control system call
2654 Implements the L<fcntl(2)> function. You'll probably have to say
2658 first to get the correct constant definitions. Argument processing and
2659 value returned work just like L<C<ioctl>|/ioctl
2660 FILEHANDLE,FUNCTION,SCALAR> below. For example:
2663 my $flags = fcntl($filehandle, F_GETFL, 0)
2664 or die "Can't fcntl F_GETFL: $!";
2666 You don't have to check for L<C<defined>|/defined EXPR> on the return
2667 from L<C<fcntl>|/fcntl FILEHANDLE,FUNCTION,SCALAR>. Like
2668 L<C<ioctl>|/ioctl FILEHANDLE,FUNCTION,SCALAR>, it maps a C<0> return
2669 from the system call into C<"0 but true"> in Perl. This string is true
2670 in boolean context and C<0> in numeric context. It is also exempt from
2672 L<C<Argument "..." isn't numeric>|perldiag/Argument "%s" isn't numeric%s>
2673 L<warnings> on improper numeric conversions.
2675 Note that L<C<fcntl>|/fcntl FILEHANDLE,FUNCTION,SCALAR> raises an
2676 exception if used on a machine that doesn't implement L<fcntl(2)>. See
2677 the L<Fcntl> module or your L<fcntl(2)> manpage to learn what functions
2678 are available on your system.
2680 Here's an example of setting a filehandle named C<$REMOTE> to be
2681 non-blocking at the system level. You'll have to negotiate
2682 L<C<$E<verbar>>|perlvar/$E<verbar>> on your own, though.
2684 use Fcntl qw(F_GETFL F_SETFL O_NONBLOCK);
2686 my $flags = fcntl($REMOTE, F_GETFL, 0)
2687 or die "Can't get flags for the socket: $!\n";
2689 fcntl($REMOTE, F_SETFL, $flags | O_NONBLOCK)
2690 or die "Can't set flags for the socket: $!\n";
2692 Portability issues: L<perlport/fcntl>.
2697 =for Pod::Functions the name of the current source file
2699 A special token that returns the name of the file in which it occurs.
2701 =item fileno FILEHANDLE
2704 =item fileno DIRHANDLE
2706 =for Pod::Functions return file descriptor from filehandle
2708 Returns the file descriptor for a filehandle or directory handle,
2710 filehandle is not open. If there is no real file descriptor at the OS
2711 level, as can happen with filehandles connected to memory objects via
2712 L<C<open>|/open FILEHANDLE,EXPR> with a reference for the third
2713 argument, -1 is returned.
2715 This is mainly useful for constructing bitmaps for
2716 L<C<select>|/select RBITS,WBITS,EBITS,TIMEOUT> and low-level POSIX
2717 tty-handling operations.
2718 If FILEHANDLE is an expression, the value is taken as an indirect
2719 filehandle, generally its name.
2721 You can use this to find out whether two handles refer to the
2722 same underlying descriptor:
2724 if (fileno($this) != -1 && fileno($this) == fileno($that)) {
2725 print "\$this and \$that are dups\n";
2726 } elsif (fileno($this) != -1 && fileno($that) != -1) {
2727 print "\$this and \$that have different " .
2728 "underlying file descriptors\n";
2730 print "At least one of \$this and \$that does " .
2731 "not have a real file descriptor\n";
2734 The behavior of L<C<fileno>|/fileno FILEHANDLE> on a directory handle
2735 depends on the operating system. On a system with L<dirfd(3)> or
2736 similar, L<C<fileno>|/fileno FILEHANDLE> on a directory
2737 handle returns the underlying file descriptor associated with the
2738 handle; on systems with no such support, it returns the undefined value,
2739 and sets L<C<$!>|perlvar/$!> (errno).
2741 =item flock FILEHANDLE,OPERATION
2742 X<flock> X<lock> X<locking>
2744 =for Pod::Functions lock an entire file with an advisory lock
2746 Calls L<flock(2)>, or an emulation of it, on FILEHANDLE. Returns true
2747 for success, false on failure. Produces a fatal error if used on a
2748 machine that doesn't implement L<flock(2)>, L<fcntl(2)> locking, or
2749 L<lockf(3)>. L<C<flock>|/flock FILEHANDLE,OPERATION> is Perl's portable
2750 file-locking interface, although it locks entire files only, not
2753 Two potentially non-obvious but traditional L<C<flock>|/flock
2754 FILEHANDLE,OPERATION> semantics are
2755 that it waits indefinitely until the lock is granted, and that its locks
2756 are B<merely advisory>. Such discretionary locks are more flexible, but
2757 offer fewer guarantees. This means that programs that do not also use
2758 L<C<flock>|/flock FILEHANDLE,OPERATION> may modify files locked with
2759 L<C<flock>|/flock FILEHANDLE,OPERATION>. See L<perlport>,
2760 your port's specific documentation, and your system-specific local manpages
2761 for details. It's best to assume traditional behavior if you're writing
2762 portable programs. (But if you're not, you should as always feel perfectly
2763 free to write for your own system's idiosyncrasies (sometimes called
2764 "features"). Slavish adherence to portability concerns shouldn't get
2765 in the way of your getting your job done.)
2767 OPERATION is one of LOCK_SH, LOCK_EX, or LOCK_UN, possibly combined with
2768 LOCK_NB. These constants are traditionally valued 1, 2, 8 and 4, but
2769 you can use the symbolic names if you import them from the L<Fcntl> module,
2770 either individually, or as a group using the C<:flock> tag. LOCK_SH
2771 requests a shared lock, LOCK_EX requests an exclusive lock, and LOCK_UN
2772 releases a previously requested lock. If LOCK_NB is bitwise-or'ed with
2773 LOCK_SH or LOCK_EX, then L<C<flock>|/flock FILEHANDLE,OPERATION> returns
2774 immediately rather than blocking waiting for the lock; check the return
2775 status to see if you got it.
2777 To avoid the possibility of miscoordination, Perl now flushes FILEHANDLE
2778 before locking or unlocking it.
2780 Note that the emulation built with L<lockf(3)> doesn't provide shared
2781 locks, and it requires that FILEHANDLE be open with write intent. These
2782 are the semantics that L<lockf(3)> implements. Most if not all systems
2783 implement L<lockf(3)> in terms of L<fcntl(2)> locking, though, so the
2784 differing semantics shouldn't bite too many people.
2786 Note that the L<fcntl(2)> emulation of L<flock(3)> requires that FILEHANDLE
2787 be open with read intent to use LOCK_SH and requires that it be open
2788 with write intent to use LOCK_EX.
2790 Note also that some versions of L<C<flock>|/flock FILEHANDLE,OPERATION>
2791 cannot lock things over the network; you would need to use the more
2792 system-specific L<C<fcntl>|/fcntl FILEHANDLE,FUNCTION,SCALAR> for
2793 that. If you like you can force Perl to ignore your system's L<flock(2)>
2794 function, and so provide its own L<fcntl(2)>-based emulation, by passing
2795 the switch C<-Ud_flock> to the F<Configure> program when you configure
2796 and build a new Perl.
2798 Here's a mailbox appender for BSD systems.
2800 # import LOCK_* and SEEK_END constants
2801 use Fcntl qw(:flock SEEK_END);
2805 flock($fh, LOCK_EX) or die "Cannot lock mailbox - $!\n";
2806 # and, in case we're running on a very old UNIX
2807 # variant without the modern O_APPEND semantics...
2808 seek($fh, 0, SEEK_END) or die "Cannot seek - $!\n";
2813 flock($fh, LOCK_UN) or die "Cannot unlock mailbox - $!\n";
2816 open(my $mbox, ">>", "/usr/spool/mail/$ENV{'USER'}")
2817 or die "Can't open mailbox: $!";
2820 print $mbox $msg,"\n\n";
2823 On systems that support a real L<flock(2)>, locks are inherited across
2824 L<C<fork>|/fork> calls, whereas those that must resort to the more
2825 capricious L<fcntl(2)> function lose their locks, making it seriously
2826 harder to write servers.
2828 See also L<DB_File> for other L<C<flock>|/flock FILEHANDLE,OPERATION>
2831 Portability issues: L<perlport/flock>.
2834 X<fork> X<child> X<parent>
2836 =for Pod::Functions create a new process just like this one
2838 Does a L<fork(2)> system call to create a new process running the
2839 same program at the same point. It returns the child pid to the
2840 parent process, C<0> to the child process, or L<C<undef>|/undef EXPR> if
2842 unsuccessful. File descriptors (and sometimes locks on those descriptors)
2843 are shared, while everything else is copied. On most systems supporting
2844 L<fork(2)>, great care has gone into making it extremely efficient (for
2845 example, using copy-on-write technology on data pages), making it the
2846 dominant paradigm for multitasking over the last few decades.
2848 Perl attempts to flush all files opened for output before forking the
2849 child process, but this may not be supported on some platforms (see
2850 L<perlport>). To be safe, you may need to set
2851 L<C<$E<verbar>>|perlvar/$E<verbar>> (C<$AUTOFLUSH> in L<English>) or
2852 call the C<autoflush> method of L<C<IO::Handle>|IO::Handle/METHODS> on
2853 any open handles to avoid duplicate output.
2855 If you L<C<fork>|/fork> without ever waiting on your children, you will
2856 accumulate zombies. On some systems, you can avoid this by setting
2857 L<C<$SIG{CHLD}>|perlvar/%SIG> to C<"IGNORE">. See also L<perlipc> for
2858 more examples of forking and reaping moribund children.
2860 Note that if your forked child inherits system file descriptors like
2861 STDIN and STDOUT that are actually connected by a pipe or socket, even
2862 if you exit, then the remote server (such as, say, a CGI script or a
2863 backgrounded job launched from a remote shell) won't think you're done.
2864 You should reopen those to F</dev/null> if it's any issue.
2866 On some platforms such as Windows, where the L<fork(2)> system call is
2867 not available, Perl can be built to emulate L<C<fork>|/fork> in the Perl
2868 interpreter. The emulation is designed, at the level of the Perl
2869 program, to be as compatible as possible with the "Unix" L<fork(2)>.
2870 However it has limitations that have to be considered in code intended
2871 to be portable. See L<perlfork> for more details.
2873 Portability issues: L<perlport/fork>.
2878 =for Pod::Functions declare a picture format with use by the write() function
2880 Declare a picture format for use by the L<C<write>|/write FILEHANDLE>
2881 function. For example:
2884 Test: @<<<<<<<< @||||| @>>>>>
2885 $str, $%, '$' . int($num)
2889 $num = $cost/$quantity;
2893 See L<perlform> for many details and examples.
2895 =item formline PICTURE,LIST
2898 =for Pod::Functions internal function used for formats
2900 This is an internal function used by L<C<format>|/format>s, though you
2901 may call it, too. It formats (see L<perlform>) a list of values
2902 according to the contents of PICTURE, placing the output into the format
2903 output accumulator, L<C<$^A>|perlvar/$^A> (or C<$ACCUMULATOR> in
2904 L<English>). Eventually, when a L<C<write>|/write FILEHANDLE> is done,
2905 the contents of L<C<$^A>|perlvar/$^A> are written to some filehandle.
2906 You could also read L<C<$^A>|perlvar/$^A> and then set
2907 L<C<$^A>|perlvar/$^A> back to C<"">. Note that a format typically does
2908 one L<C<formline>|/formline PICTURE,LIST> per line of form, but the
2909 L<C<formline>|/formline PICTURE,LIST> function itself doesn't care how
2910 many newlines are embedded in the PICTURE. This means that the C<~> and
2911 C<~~> tokens treat the entire PICTURE as a single line. You may
2912 therefore need to use multiple formlines to implement a single record
2913 format, just like the L<C<format>|/format> compiler.
2915 Be careful if you put double quotes around the picture, because an C<@>
2916 character may be taken to mean the beginning of an array name.
2917 L<C<formline>|/formline PICTURE,LIST> always returns true. See
2918 L<perlform> for other examples.
2920 If you are trying to use this instead of L<C<write>|/write FILEHANDLE>
2921 to capture the output, you may find it easier to open a filehandle to a
2922 scalar (C<< open my $fh, ">", \$output >>) and write to that instead.
2924 =item getc FILEHANDLE
2925 X<getc> X<getchar> X<character> X<file, read>
2929 =for Pod::Functions get the next character from the filehandle
2931 Returns the next character from the input file attached to FILEHANDLE,
2932 or the undefined value at end of file or if there was an error (in
2933 the latter case L<C<$!>|perlvar/$!> is set). If FILEHANDLE is omitted,
2935 STDIN. This is not particularly efficient. However, it cannot be
2936 used by itself to fetch single characters without waiting for the user
2937 to hit enter. For that, try something more like:
2940 system "stty cbreak </dev/tty >/dev/tty 2>&1";
2943 system "stty", '-icanon', 'eol', "\001";
2946 my $key = getc(STDIN);
2949 system "stty -cbreak </dev/tty >/dev/tty 2>&1";
2952 system 'stty', 'icanon', 'eol', '^@'; # ASCII NUL
2956 Determination of whether C<$BSD_STYLE> should be set is left as an
2957 exercise to the reader.
2959 The L<C<POSIX::getattr>|POSIX/C<getattr>> function can do this more
2960 portably on systems purporting POSIX compliance. See also the
2961 L<C<Term::ReadKey>|Term::ReadKey> module on CPAN.
2964 X<getlogin> X<login>
2966 =for Pod::Functions return who logged in at this tty
2968 This implements the C library function of the same name, which on most
2969 systems returns the current login from F</etc/utmp>, if any. If it
2970 returns the empty string, use L<C<getpwuid>|/getpwuid UID>.
2972 my $login = getlogin || getpwuid($<) || "Kilroy";
2974 Do not consider L<C<getlogin>|/getlogin> for authentication: it is not
2975 as secure as L<C<getpwuid>|/getpwuid UID>.
2977 Portability issues: L<perlport/getlogin>.
2979 =item getpeername SOCKET
2980 X<getpeername> X<peer>
2982 =for Pod::Functions find the other end of a socket connection
2984 Returns the packed sockaddr address of the other end of the SOCKET
2988 my $hersockaddr = getpeername($sock);
2989 my ($port, $iaddr) = sockaddr_in($hersockaddr);
2990 my $herhostname = gethostbyaddr($iaddr, AF_INET);
2991 my $herstraddr = inet_ntoa($iaddr);
2996 =for Pod::Functions get process group
2998 Returns the current process group for the specified PID. Use
2999 a PID of C<0> to get the current process group for the
3000 current process. Will raise an exception if used on a machine that
3001 doesn't implement L<getpgrp(2)>. If PID is omitted, returns the process
3002 group of the current process. Note that the POSIX version of
3003 L<C<getpgrp>|/getpgrp PID> does not accept a PID argument, so only
3004 C<PID==0> is truly portable.
3006 Portability issues: L<perlport/getpgrp>.
3009 X<getppid> X<parent> X<pid>
3011 =for Pod::Functions get parent process ID
3013 Returns the process id of the parent process.
3015 Note for Linux users: Between v5.8.1 and v5.16.0 Perl would work
3016 around non-POSIX thread semantics the minority of Linux systems (and
3017 Debian GNU/kFreeBSD systems) that used LinuxThreads, this emulation
3018 has since been removed. See the documentation for L<$$|perlvar/$$> for
3021 Portability issues: L<perlport/getppid>.
3023 =item getpriority WHICH,WHO
3024 X<getpriority> X<priority> X<nice>
3026 =for Pod::Functions get current nice value
3028 Returns the current priority for a process, a process group, or a user.
3029 (See L<getpriority(2)>.) Will raise a fatal exception if used on a
3030 machine that doesn't implement L<getpriority(2)>.
3032 C<WHICH> can be any of C<PRIO_PROCESS>, C<PRIO_PGRP> or C<PRIO_USER>
3033 imported from L<POSIX/RESOURCE CONSTANTS>.
3035 Portability issues: L<perlport/getpriority>.
3038 X<getpwnam> X<getgrnam> X<gethostbyname> X<getnetbyname> X<getprotobyname>
3039 X<getpwuid> X<getgrgid> X<getservbyname> X<gethostbyaddr> X<getnetbyaddr>
3040 X<getprotobynumber> X<getservbyport> X<getpwent> X<getgrent> X<gethostent>
3041 X<getnetent> X<getprotoent> X<getservent> X<setpwent> X<setgrent> X<sethostent>
3042 X<setnetent> X<setprotoent> X<setservent> X<endpwent> X<endgrent> X<endhostent>
3043 X<endnetent> X<endprotoent> X<endservent>
3045 =for Pod::Functions get passwd record given user login name
3049 =for Pod::Functions get group record given group name
3051 =item gethostbyname NAME
3053 =for Pod::Functions get host record given name
3055 =item getnetbyname NAME
3057 =for Pod::Functions get networks record given name
3059 =item getprotobyname NAME
3061 =for Pod::Functions get protocol record given name
3065 =for Pod::Functions get passwd record given user ID
3069 =for Pod::Functions get group record given group user ID
3071 =item getservbyname NAME,PROTO
3073 =for Pod::Functions get services record given its name
3075 =item gethostbyaddr ADDR,ADDRTYPE
3077 =for Pod::Functions get host record given its address
3079 =item getnetbyaddr ADDR,ADDRTYPE
3081 =for Pod::Functions get network record given its address
3083 =item getprotobynumber NUMBER
3085 =for Pod::Functions get protocol record numeric protocol
3087 =item getservbyport PORT,PROTO
3089 =for Pod::Functions get services record given numeric port
3093 =for Pod::Functions get next passwd record
3097 =for Pod::Functions get next group record
3101 =for Pod::Functions get next hosts record
3105 =for Pod::Functions get next networks record
3109 =for Pod::Functions get next protocols record
3113 =for Pod::Functions get next services record
3117 =for Pod::Functions prepare passwd file for use
3121 =for Pod::Functions prepare group file for use
3123 =item sethostent STAYOPEN
3125 =for Pod::Functions prepare hosts file for use
3127 =item setnetent STAYOPEN
3129 =for Pod::Functions prepare networks file for use
3131 =item setprotoent STAYOPEN
3133 =for Pod::Functions prepare protocols file for use
3135 =item setservent STAYOPEN
3137 =for Pod::Functions prepare services file for use
3141 =for Pod::Functions be done using passwd file
3145 =for Pod::Functions be done using group file
3149 =for Pod::Functions be done using hosts file
3153 =for Pod::Functions be done using networks file
3157 =for Pod::Functions be done using protocols file
3161 =for Pod::Functions be done using services file
3163 These routines are the same as their counterparts in the
3164 system C library. In list context, the return values from the
3165 various get routines are as follows:
3168 my ( $name, $passwd, $gid, $members ) = getgr*
3169 my ( $name, $aliases, $addrtype, $net ) = getnet*
3170 my ( $name, $aliases, $port, $proto ) = getserv*
3171 my ( $name, $aliases, $proto ) = getproto*
3172 my ( $name, $aliases, $addrtype, $length, @addrs ) = gethost*
3173 my ( $name, $passwd, $uid, $gid, $quota,
3174 $comment, $gcos, $dir, $shell, $expire ) = getpw*
3177 (If the entry doesn't exist, the return value is a single meaningless true
3180 The exact meaning of the $gcos field varies but it usually contains
3181 the real name of the user (as opposed to the login name) and other
3182 information pertaining to the user. Beware, however, that in many
3183 system users are able to change this information and therefore it
3184 cannot be trusted and therefore the $gcos is tainted (see
3185 L<perlsec>). The $passwd and $shell, user's encrypted password and
3186 login shell, are also tainted, for the same reason.
3188 In scalar context, you get the name, unless the function was a
3189 lookup by name, in which case you get the other thing, whatever it is.
3190 (If the entry doesn't exist you get the undefined value.) For example:
3192 my $uid = getpwnam($name);
3193 my $name = getpwuid($num);
3194 my $name = getpwent();
3195 my $gid = getgrnam($name);
3196 my $name = getgrgid($num);
3197 my $name = getgrent();
3200 In I<getpw*()> the fields $quota, $comment, and $expire are special
3201 in that they are unsupported on many systems. If the
3202 $quota is unsupported, it is an empty scalar. If it is supported, it
3203 usually encodes the disk quota. If the $comment field is unsupported,
3204 it is an empty scalar. If it is supported it usually encodes some
3205 administrative comment about the user. In some systems the $quota
3206 field may be $change or $age, fields that have to do with password
3207 aging. In some systems the $comment field may be $class. The $expire
3208 field, if present, encodes the expiration period of the account or the
3209 password. For the availability and the exact meaning of these fields
3210 in your system, please consult L<getpwnam(3)> and your system's
3211 F<pwd.h> file. You can also find out from within Perl what your
3212 $quota and $comment fields mean and whether you have the $expire field
3213 by using the L<C<Config>|Config> module and the values C<d_pwquota>, C<d_pwage>,
3214 C<d_pwchange>, C<d_pwcomment>, and C<d_pwexpire>. Shadow password
3215 files are supported only if your vendor has implemented them in the
3216 intuitive fashion that calling the regular C library routines gets the
3217 shadow versions if you're running under privilege or if there exists
3218 the L<shadow(3)> functions as found in System V (this includes Solaris
3219 and Linux). Those systems that implement a proprietary shadow password
3220 facility are unlikely to be supported.
3222 The $members value returned by I<getgr*()> is a space-separated list of
3223 the login names of the members of the group.
3225 For the I<gethost*()> functions, if the C<h_errno> variable is supported in
3226 C, it will be returned to you via L<C<$?>|perlvar/$?> if the function
3228 C<@addrs> value returned by a successful call is a list of raw
3229 addresses returned by the corresponding library call. In the
3230 Internet domain, each address is four bytes long; you can unpack it
3231 by saying something like:
3233 my ($w,$x,$y,$z) = unpack('W4',$addr[0]);
3235 The Socket library makes this slightly easier:
3238 my $iaddr = inet_aton("127.1"); # or whatever address
3239 my $name = gethostbyaddr($iaddr, AF_INET);
3241 # or going the other way
3242 my $straddr = inet_ntoa($iaddr);
3244 In the opposite way, to resolve a hostname to the IP address
3248 my $packed_ip = gethostbyname("www.perl.org");
3250 if (defined $packed_ip) {
3251 $ip_address = inet_ntoa($packed_ip);
3254 Make sure L<C<gethostbyname>|/gethostbyname NAME> is called in SCALAR
3255 context and that its return value is checked for definedness.
3257 The L<C<getprotobynumber>|/getprotobynumber NUMBER> function, even
3258 though it only takes one argument, has the precedence of a list
3259 operator, so beware:
3261 getprotobynumber $number eq 'icmp' # WRONG
3262 getprotobynumber($number eq 'icmp') # actually means this
3263 getprotobynumber($number) eq 'icmp' # better this way
3265 If you get tired of remembering which element of the return list
3266 contains which return value, by-name interfaces are provided in standard
3267 modules: L<C<File::stat>|File::stat>, L<C<Net::hostent>|Net::hostent>,
3268 L<C<Net::netent>|Net::netent>, L<C<Net::protoent>|Net::protoent>,
3269 L<C<Net::servent>|Net::servent>, L<C<Time::gmtime>|Time::gmtime>,
3270 L<C<Time::localtime>|Time::localtime>, and
3271 L<C<User::grent>|User::grent>. These override the normal built-ins,
3272 supplying versions that return objects with the appropriate names for
3273 each field. For example:
3277 my $is_his = (stat($filename)->uid == pwent($whoever)->uid);
3279 Even though it looks as though they're the same method calls (uid),
3280 they aren't, because a C<File::stat> object is different from
3281 a C<User::pwent> object.
3283 Many of these functions are not safe in a multi-threaded environment
3284 where more than one thread can be using them. In particular, functions
3285 like C<getpwent()> iterate per-process and not per-thread, so if two
3286 threads are simultaneously iterating, neither will get all the records.
3288 Some systems have thread-safe versions of some of the functions, such as
3289 C<getpwnam_r()> instead of C<getpwnam()>. There, Perl automatically and
3290 invisibly substitutes the thread-safe version, without notice. This
3291 means that code that safely runs on some systems can fail on others that
3292 lack the thread-safe versions.
3294 Portability issues: L<perlport/getpwnam> to L<perlport/endservent>.
3296 =item getsockname SOCKET
3299 =for Pod::Functions retrieve the sockaddr for a given socket
3301 Returns the packed sockaddr address of this end of the SOCKET connection,
3302 in case you don't know the address because you have several different
3303 IPs that the connection might have come in on.
3306 my $mysockaddr = getsockname($sock);
3307 my ($port, $myaddr) = sockaddr_in($mysockaddr);
3308 printf "Connect to %s [%s]\n",
3309 scalar gethostbyaddr($myaddr, AF_INET),
3312 =item getsockopt SOCKET,LEVEL,OPTNAME
3315 =for Pod::Functions get socket options on a given socket
3317 Queries the option named OPTNAME associated with SOCKET at a given LEVEL.
3318 Options may exist at multiple protocol levels depending on the socket
3319 type, but at least the uppermost socket level SOL_SOCKET (defined in the
3320 L<C<Socket>|Socket> module) will exist. To query options at another
3321 level the protocol number of the appropriate protocol controlling the
3322 option should be supplied. For example, to indicate that an option is
3323 to be interpreted by the TCP protocol, LEVEL should be set to the
3324 protocol number of TCP, which you can get using
3325 L<C<getprotobyname>|/getprotobyname NAME>.
3327 The function returns a packed string representing the requested socket
3328 option, or L<C<undef>|/undef EXPR> on error, with the reason for the
3329 error placed in L<C<$!>|perlvar/$!>. Just what is in the packed string
3330 depends on LEVEL and OPTNAME; consult L<getsockopt(2)> for details. A
3331 common case is that the option is an integer, in which case the result
3332 is a packed integer, which you can decode using
3333 L<C<unpack>|/unpack TEMPLATE,EXPR> with the C<i> (or C<I>) format.
3335 Here's an example to test whether Nagle's algorithm is enabled on a socket:
3337 use Socket qw(:all);
3339 defined(my $tcp = getprotobyname("tcp"))
3340 or die "Could not determine the protocol number for tcp";
3341 # my $tcp = IPPROTO_TCP; # Alternative
3342 my $packed = getsockopt($socket, $tcp, TCP_NODELAY)
3343 or die "getsockopt TCP_NODELAY: $!";
3344 my $nodelay = unpack("I", $packed);
3345 print "Nagle's algorithm is turned ",
3346 $nodelay ? "off\n" : "on\n";
3348 Portability issues: L<perlport/getsockopt>.
3351 X<glob> X<wildcard> X<filename, expansion> X<expand>
3355 =for Pod::Functions expand filenames using wildcards
3357 In list context, returns a (possibly empty) list of filename expansions on
3358 the value of EXPR such as the standard Unix shell F</bin/csh> would do. In
3359 scalar context, glob iterates through such filename expansions, returning
3360 undef when the list is exhausted. This is the internal function
3361 implementing the C<< <*.c> >> operator, but you can use it directly. If
3362 EXPR is omitted, L<C<$_>|perlvar/$_> is used. The C<< <*.c> >> operator
3363 is discussed in more detail in L<perlop/"I/O Operators">.
3365 Note that L<C<glob>|/glob EXPR> splits its arguments on whitespace and
3367 each segment as separate pattern. As such, C<glob("*.c *.h")>
3368 matches all files with a F<.c> or F<.h> extension. The expression
3369 C<glob(".* *")> matches all files in the current working directory.
3370 If you want to glob filenames that might contain whitespace, you'll
3371 have to use extra quotes around the spacey filename to protect it.
3372 For example, to glob filenames that have an C<e> followed by a space
3373 followed by an C<f>, use one of:
3375 my @spacies = <"*e f*">;
3376 my @spacies = glob '"*e f*"';
3377 my @spacies = glob q("*e f*");
3379 If you had to get a variable through, you could do this:
3381 my @spacies = glob "'*${var}e f*'";
3382 my @spacies = glob qq("*${var}e f*");
3384 If non-empty braces are the only wildcard characters used in the
3385 L<C<glob>|/glob EXPR>, no filenames are matched, but potentially many
3386 strings are returned. For example, this produces nine strings, one for
3387 each pairing of fruits and colors:
3389 my @many = glob "{apple,tomato,cherry}={green,yellow,red}";
3391 This operator is implemented using the standard C<File::Glob> extension.
3392 See L<File::Glob> for details, including
3393 L<C<bsd_glob>|File::Glob/C<bsd_glob>>, which does not treat whitespace
3394 as a pattern separator.
3396 If a C<glob> expression is used as the condition of a C<while> or C<for>
3397 loop, then it will be implicitly assigned to C<$_>. If either a C<glob>
3398 expression or an explicit assignment of a C<glob> expression to a scalar
3399 is used as a C<while>/C<for> condition, then the condition actually
3400 tests for definedness of the expression's value, not for its regular
3403 Portability issues: L<perlport/glob>.
3406 X<gmtime> X<UTC> X<Greenwich>
3410 =for Pod::Functions convert UNIX time into record or string using Greenwich time
3412 Works just like L<C<localtime>|/localtime EXPR> but the returned values
3413 are localized for the standard Greenwich time zone.
3415 Note: When called in list context, $isdst, the last value
3416 returned by gmtime, is always C<0>. There is no
3417 Daylight Saving Time in GMT.
3419 Portability issues: L<perlport/gmtime>.
3422 X<goto> X<jump> X<jmp>
3428 =for Pod::Functions create spaghetti code
3430 The C<goto LABEL> form finds the statement labeled with LABEL and
3431 resumes execution there. It can't be used to get out of a block or
3432 subroutine given to L<C<sort>|/sort SUBNAME LIST>. It can be used to go
3433 almost anywhere else within the dynamic scope, including out of
3434 subroutines, but it's usually better to use some other construct such as
3435 L<C<last>|/last LABEL> or L<C<die>|/die LIST>. The author of Perl has
3436 never felt the need to use this form of L<C<goto>|/goto LABEL> (in Perl,
3437 that is; C is another matter). (The difference is that C does not offer
3438 named loops combined with loop control. Perl does, and this replaces
3439 most structured uses of L<C<goto>|/goto LABEL> in other languages.)
3441 The C<goto EXPR> form expects to evaluate C<EXPR> to a code reference or
3442 a label name. If it evaluates to a code reference, it will be handled
3443 like C<goto &NAME>, below. This is especially useful for implementing
3444 tail recursion via C<goto __SUB__>.
3446 If the expression evaluates to a label name, its scope will be resolved
3447 dynamically. This allows for computed L<C<goto>|/goto LABEL>s per
3448 FORTRAN, but isn't necessarily recommended if you're optimizing for
3451 goto ("FOO", "BAR", "GLARCH")[$i];
3453 As shown in this example, C<goto EXPR> is exempt from the "looks like a
3454 function" rule. A pair of parentheses following it does not (necessarily)
3455 delimit its argument. C<goto("NE")."XT"> is equivalent to C<goto NEXT>.
3456 Also, unlike most named operators, this has the same precedence as
3459 Use of C<goto LABEL> or C<goto EXPR> to jump into a construct is
3460 deprecated and will issue a warning. Even then, it may not be used to
3461 go into any construct that requires initialization, such as a
3462 subroutine, a C<foreach> loop, or a C<given>
3463 block. In general, it may not be used to jump into the parameter
3464 of a binary or list operator, but it may be used to jump into the
3465 I<first> parameter of a binary operator. (The C<=>
3466 assignment operator's "first" operand is its right-hand
3467 operand.) It also can't be used to go into a
3468 construct that is optimized away.
3470 The C<goto &NAME> form is quite different from the other forms of
3471 L<C<goto>|/goto LABEL>. In fact, it isn't a goto in the normal sense at
3472 all, and doesn't have the stigma associated with other gotos. Instead,
3473 it exits the current subroutine (losing any changes set by
3474 L<C<local>|/local EXPR>) and immediately calls in its place the named
3475 subroutine using the current value of L<C<@_>|perlvar/@_>. This is used
3476 by C<AUTOLOAD> subroutines that wish to load another subroutine and then
3477 pretend that the other subroutine had been called in the first place
3478 (except that any modifications to L<C<@_>|perlvar/@_> in the current
3479 subroutine are propagated to the other subroutine.) After the
3480 L<C<goto>|/goto LABEL>, not even L<C<caller>|/caller EXPR> will be able
3481 to tell that this routine was called first.
3483 NAME needn't be the name of a subroutine; it can be a scalar variable
3484 containing a code reference or a block that evaluates to a code
3487 =item grep BLOCK LIST
3490 =item grep EXPR,LIST
3492 =for Pod::Functions locate elements in a list test true against a given criterion
3494 This is similar in spirit to, but not the same as, L<grep(1)> and its
3495 relatives. In particular, it is not limited to using regular expressions.
3497 Evaluates the BLOCK or EXPR for each element of LIST (locally setting
3498 L<C<$_>|perlvar/$_> to each element) and returns the list value
3500 elements for which the expression evaluated to true. In scalar
3501 context, returns the number of times the expression was true.
3503 my @foo = grep(!/^#/, @bar); # weed out comments
3507 my @foo = grep {!/^#/} @bar; # weed out comments
3509 Note that L<C<$_>|perlvar/$_> is an alias to the list value, so it can
3511 modify the elements of the LIST. While this is useful and supported,
3512 it can cause bizarre results if the elements of LIST are not variables.
3513 Similarly, grep returns aliases into the original list, much as a for
3514 loop's index variable aliases the list elements. That is, modifying an
3515 element of a list returned by grep (for example, in a C<foreach>,
3516 L<C<map>|/map BLOCK LIST> or another L<C<grep>|/grep BLOCK LIST>)
3517 actually modifies the element in the original list.
3518 This is usually something to be avoided when writing clear code.
3520 See also L<C<map>|/map BLOCK LIST> for a list composed of the results of
3524 X<hex> X<hexadecimal>
3528 =for Pod::Functions convert a hexadecimal string to a number
3530 Interprets EXPR as a hex string and returns the corresponding numeric value.
3531 If EXPR is omitted, uses L<C<$_>|perlvar/$_>.
3533 print hex '0xAf'; # prints '175'
3534 print hex 'aF'; # same
3535 $valid_input =~ /\A(?:0?[xX])?(?:_?[0-9a-fA-F])*\z/
3537 A hex string consists of hex digits and an optional C<0x> or C<x> prefix.
3538 Each hex digit may be preceded by a single underscore, which will be ignored.
3539 Any other character triggers a warning and causes the rest of the string
3540 to be ignored (even leading whitespace, unlike L<C<oct>|/oct EXPR>).
3541 Only integers can be represented, and integer overflow triggers a warning.
3543 To convert strings that might start with any of C<0>, C<0x>, or C<0b>,
3544 see L<C<oct>|/oct EXPR>. To present something as hex, look into
3545 L<C<printf>|/printf FILEHANDLE FORMAT, LIST>,
3546 L<C<sprintf>|/sprintf FORMAT, LIST>, and
3547 L<C<unpack>|/unpack TEMPLATE,EXPR>.
3552 =for Pod::Functions patch a module's namespace into your own
3554 There is no builtin L<C<import>|/import LIST> function. It is just an
3555 ordinary method (subroutine) defined (or inherited) by modules that wish
3556 to export names to another module. The
3557 L<C<use>|/use Module VERSION LIST> function calls the
3558 L<C<import>|/import LIST> method for the package used. See also
3559 L<C<use>|/use Module VERSION LIST>, L<perlmod>, and L<Exporter>.
3561 =item index STR,SUBSTR,POSITION
3562 X<index> X<indexOf> X<InStr>
3564 =item index STR,SUBSTR
3566 =for Pod::Functions find a substring within a string
3568 The index function searches for one string within another, but without
3569 the wildcard-like behavior of a full regular-expression pattern match.
3570 It returns the position of the first occurrence of SUBSTR in STR at
3571 or after POSITION. If POSITION is omitted, starts searching from the
3572 beginning of the string. POSITION before the beginning of the string
3573 or after its end is treated as if it were the beginning or the end,
3574 respectively. POSITION and the return value are based at zero.
3575 If the substring is not found, L<C<index>|/index STR,SUBSTR,POSITION>
3579 X<int> X<integer> X<truncate> X<trunc> X<floor>
3583 =for Pod::Functions get the integer portion of a number
3585 Returns the integer portion of EXPR. If EXPR is omitted, uses
3586 L<C<$_>|perlvar/$_>.
3587 You should not use this function for rounding: one because it truncates
3588 towards C<0>, and two because machine representations of floating-point
3589 numbers can sometimes produce counterintuitive results. For example,
3590 C<int(-6.725/0.025)> produces -268 rather than the correct -269; that's
3591 because it's really more like -268.99999999999994315658 instead. Usually,
3592 the L<C<sprintf>|/sprintf FORMAT, LIST>,
3593 L<C<printf>|/printf FILEHANDLE FORMAT, LIST>, or the
3594 L<C<POSIX::floor>|POSIX/C<floor>> and L<C<POSIX::ceil>|POSIX/C<ceil>>
3595 functions will serve you better than will L<C<int>|/int EXPR>.
3597 =item ioctl FILEHANDLE,FUNCTION,SCALAR
3600 =for Pod::Functions system-dependent device control system call
3602 Implements the L<ioctl(2)> function. You'll probably first have to say
3604 require "sys/ioctl.ph"; # probably in
3605 # $Config{archlib}/sys/ioctl.ph
3607 to get the correct function definitions. If F<sys/ioctl.ph> doesn't
3608 exist or doesn't have the correct definitions you'll have to roll your
3609 own, based on your C header files such as F<< <sys/ioctl.h> >>.
3610 (There is a Perl script called B<h2ph> that comes with the Perl kit that
3611 may help you in this, but it's nontrivial.) SCALAR will be read and/or
3612 written depending on the FUNCTION; a C pointer to the string value of SCALAR
3613 will be passed as the third argument of the actual
3614 L<C<ioctl>|/ioctl FILEHANDLE,FUNCTION,SCALAR> call. (If SCALAR
3615 has no string value but does have a numeric value, that value will be
3616 passed rather than a pointer to the string value. To guarantee this to be
3617 true, add a C<0> to the scalar before using it.) The
3618 L<C<pack>|/pack TEMPLATE,LIST> and L<C<unpack>|/unpack TEMPLATE,EXPR>
3619 functions may be needed to manipulate the values of structures used by
3620 L<C<ioctl>|/ioctl FILEHANDLE,FUNCTION,SCALAR>.
3622 The return value of L<C<ioctl>|/ioctl FILEHANDLE,FUNCTION,SCALAR> (and
3623 L<C<fcntl>|/fcntl FILEHANDLE,FUNCTION,SCALAR>) is as follows:
3625 if OS returns: then Perl returns:
3627 0 string "0 but true"
3628 anything else that number
3630 Thus Perl returns true on success and false on failure, yet you can
3631 still easily determine the actual value returned by the operating
3634 my $retval = ioctl(...) || -1;
3635 printf "System returned %d\n", $retval;
3637 The special string C<"0 but true"> is exempt from
3638 L<C<Argument "..." isn't numeric>|perldiag/Argument "%s" isn't numeric%s>
3639 L<warnings> on improper numeric conversions.
3641 Portability issues: L<perlport/ioctl>.
3643 =item join EXPR,LIST
3646 =for Pod::Functions join a list into a string using a separator
3648 Joins the separate strings of LIST into a single string with fields
3649 separated by the value of EXPR, and returns that new string. Example:
3651 my $rec = join(':', $login,$passwd,$uid,$gid,$gcos,$home,$shell);
3653 Beware that unlike L<C<split>|/split E<sol>PATTERNE<sol>,EXPR,LIMIT>,
3654 L<C<join>|/join EXPR,LIST> doesn't take a pattern as its first argument.
3655 Compare L<C<split>|/split E<sol>PATTERNE<sol>,EXPR,LIMIT>.
3662 =for Pod::Functions retrieve list of indices from a hash
3664 Called in list context, returns a list consisting of all the keys of the
3665 named hash, or in Perl 5.12 or later only, the indices of an array. Perl
3666 releases prior to 5.12 will produce a syntax error if you try to use an
3667 array argument. In scalar context, returns the number of keys or indices.
3669 Hash entries are returned in an apparently random order. The actual random
3670 order is specific to a given hash; the exact same series of operations
3671 on two hashes may result in a different order for each hash. Any insertion
3672 into the hash may change the order, as will any deletion, with the exception
3673 that the most recent key returned by L<C<each>|/each HASH> or
3674 L<C<keys>|/keys HASH> may be deleted without changing the order. So
3675 long as a given hash is unmodified you may rely on
3676 L<C<keys>|/keys HASH>, L<C<values>|/values HASH> and L<C<each>|/each
3677 HASH> to repeatedly return the same order
3678 as each other. See L<perlsec/"Algorithmic Complexity Attacks"> for
3679 details on why hash order is randomized. Aside from the guarantees
3680 provided here the exact details of Perl's hash algorithm and the hash
3681 traversal order are subject to change in any release of Perl. Tied hashes
3682 may behave differently to Perl's hashes with respect to changes in order on
3683 insertion and deletion of items.
3685 As a side effect, calling L<C<keys>|/keys HASH> resets the internal
3686 iterator of the HASH or ARRAY (see L<C<each>|/each HASH>) before
3687 yielding the keys. In
3688 particular, calling L<C<keys>|/keys HASH> in void context resets the
3689 iterator with no other overhead.
3691 Here is yet another way to print your environment:
3693 my @keys = keys %ENV;
3694 my @values = values %ENV;
3696 print pop(@keys), '=', pop(@values), "\n";
3699 or how about sorted by key:
3701 foreach my $key (sort(keys %ENV)) {
3702 print $key, '=', $ENV{$key}, "\n";
3705 The returned values are copies of the original keys in the hash, so
3706 modifying them will not affect the original hash. Compare
3707 L<C<values>|/values HASH>.
3709 To sort a hash by value, you'll need to use a
3710 L<C<sort>|/sort SUBNAME LIST> function. Here's a descending numeric
3711 sort of a hash by its values:
3713 foreach my $key (sort { $hash{$b} <=> $hash{$a} } keys %hash) {
3714 printf "%4d %s\n", $hash{$key}, $key;
3717 Used as an lvalue, L<C<keys>|/keys HASH> allows you to increase the
3718 number of hash buckets
3719 allocated for the given hash. This can gain you a measure of efficiency if
3720 you know the hash is going to get big. (This is similar to pre-extending
3721 an array by assigning a larger number to $#array.) If you say
3725 then C<%hash> will have at least 200 buckets allocated for it--256 of them,
3726 in fact, since it rounds up to the next power of two. These
3727 buckets will be retained even if you do C<%hash = ()>, use C<undef
3728 %hash> if you want to free the storage while C<%hash> is still in scope.
3729 You can't shrink the number of buckets allocated for the hash using
3730 L<C<keys>|/keys HASH> in this way (but you needn't worry about doing
3731 this by accident, as trying has no effect). C<keys @array> in an lvalue
3732 context is a syntax error.
3734 Starting with Perl 5.14, an experimental feature allowed
3735 L<C<keys>|/keys HASH> to take a scalar expression. This experiment has
3736 been deemed unsuccessful, and was removed as of Perl 5.24.
3738 To avoid confusing would-be users of your code who are running earlier
3739 versions of Perl with mysterious syntax errors, put this sort of thing at
3740 the top of your file to signal that your code will work I<only> on Perls of
3743 use 5.012; # so keys/values/each work on arrays
3745 See also L<C<each>|/each HASH>, L<C<values>|/values HASH>, and
3746 L<C<sort>|/sort SUBNAME LIST>.
3748 =item kill SIGNAL, LIST
3753 =for Pod::Functions send a signal to a process or process group
3755 Sends a signal to a list of processes. Returns the number of arguments
3756 that were successfully used to signal (which is not necessarily the same
3757 as the number of processes actually killed, e.g. where a process group is
3760 my $cnt = kill 'HUP', $child1, $child2;
3761 kill 'KILL', @goners;
3763 SIGNAL may be either a signal name (a string) or a signal number. A signal
3764 name may start with a C<SIG> prefix, thus C<FOO> and C<SIGFOO> refer to the
3765 same signal. The string form of SIGNAL is recommended for portability because
3766 the same signal may have different numbers in different operating systems.
3768 A list of signal names supported by the current platform can be found in
3769 C<$Config{sig_name}>, which is provided by the L<C<Config>|Config>
3770 module. See L<Config> for more details.
3772 A negative signal name is the same as a negative signal number, killing process
3773 groups instead of processes. For example, C<kill '-KILL', $pgrp> and
3774 C<kill -9, $pgrp> will send C<SIGKILL> to
3775 the entire process group specified. That
3776 means you usually want to use positive not negative signals.
3778 If SIGNAL is either the number 0 or the string C<ZERO> (or C<SIGZERO>),
3779 no signal is sent to the process, but L<C<kill>|/kill SIGNAL, LIST>
3780 checks whether it's I<possible> to send a signal to it
3781 (that means, to be brief, that the process is owned by the same user, or we are
3782 the super-user). This is useful to check that a child process is still
3783 alive (even if only as a zombie) and hasn't changed its UID. See
3784 L<perlport> for notes on the portability of this construct.
3786 The behavior of kill when a I<PROCESS> number is zero or negative depends on
3787 the operating system. For example, on POSIX-conforming systems, zero will
3788 signal the current process group, -1 will signal all processes, and any
3789 other negative PROCESS number will act as a negative signal number and
3790 kill the entire process group specified.
3792 If both the SIGNAL and the PROCESS are negative, the results are undefined.
3793 A warning may be produced in a future version.
3795 See L<perlipc/"Signals"> for more details.
3797 On some platforms such as Windows where the L<fork(2)> system call is not
3798 available, Perl can be built to emulate L<C<fork>|/fork> at the
3800 This emulation has limitations related to kill that have to be considered,
3801 for code running on Windows and in code intended to be portable.
3803 See L<perlfork> for more details.
3805 If there is no I<LIST> of processes, no signal is sent, and the return
3806 value is 0. This form is sometimes used, however, because it causes
3807 tainting checks to be run. But see
3808 L<perlsec/Laundering and Detecting Tainted Data>.
3810 Portability issues: L<perlport/kill>.
3819 =for Pod::Functions exit a block prematurely
3821 The L<C<last>|/last LABEL> command is like the C<break> statement in C
3823 loops); it immediately exits the loop in question. If the LABEL is
3824 omitted, the command refers to the innermost enclosing
3825 loop. The C<last EXPR> form, available starting in Perl
3826 5.18.0, allows a label name to be computed at run time,
3827 and is otherwise identical to C<last LABEL>. The
3828 L<C<continue>|/continue BLOCK> block, if any, is not executed:
3830 LINE: while (<STDIN>) {
3831 last LINE if /^$/; # exit when done with header
3835 L<C<last>|/last LABEL> cannot return a value from a block that typically
3836 returns a value, such as C<eval {}>, C<sub {}>, or C<do {}>. It will perform
3837 its flow control behavior, which precludes any return value. It should not be
3838 used to exit a L<C<grep>|/grep BLOCK LIST> or L<C<map>|/map BLOCK LIST>
3841 Note that a block by itself is semantically identical to a loop
3842 that executes once. Thus L<C<last>|/last LABEL> can be used to effect
3843 an early exit out of such a block.
3845 See also L<C<continue>|/continue BLOCK> for an illustration of how
3846 L<C<last>|/last LABEL>, L<C<next>|/next LABEL>, and
3847 L<C<redo>|/redo LABEL> work.
3849 Unlike most named operators, this has the same precedence as assignment.
3850 It is also exempt from the looks-like-a-function rule, so
3851 C<last ("foo")."bar"> will cause "bar" to be part of the argument to
3852 L<C<last>|/last LABEL>.
3859 =for Pod::Functions return lower-case version of a string
3861 Returns a lowercased version of EXPR. This is the internal function
3862 implementing the C<\L> escape in double-quoted strings.
3864 If EXPR is omitted, uses L<C<$_>|perlvar/$_>.
3866 What gets returned depends on several factors:
3870 =item If C<use bytes> is in effect:
3872 The results follow ASCII rules. Only the characters C<A-Z> change,
3873 to C<a-z> respectively.
3875 =item Otherwise, if C<use locale> for C<LC_CTYPE> is in effect:
3877 Respects current C<LC_CTYPE> locale for code points < 256; and uses Unicode
3878 rules for the remaining code points (this last can only happen if
3879 the UTF8 flag is also set). See L<perllocale>.
3881 Starting in v5.20, Perl uses full Unicode rules if the locale is
3882 UTF-8. Otherwise, there is a deficiency in this scheme, which is that
3883 case changes that cross the 255/256
3884 boundary are not well-defined. For example, the lower case of LATIN CAPITAL
3885 LETTER SHARP S (U+1E9E) in Unicode rules is U+00DF (on ASCII
3886 platforms). But under C<use locale> (prior to v5.20 or not a UTF-8
3887 locale), the lower case of U+1E9E is
3888 itself, because 0xDF may not be LATIN SMALL LETTER SHARP S in the
3889 current locale, and Perl has no way of knowing if that character even
3890 exists in the locale, much less what code point it is. Perl returns
3891 a result that is above 255 (almost always the input character unchanged),
3892 for all instances (and there aren't many) where the 255/256 boundary
3893 would otherwise be crossed; and starting in v5.22, it raises a
3894 L<locale|perldiag/Can't do %s("%s") on non-UTF-8 locale; resolved to "%s".> warning.
3896 =item Otherwise, If EXPR has the UTF8 flag set:
3898 Unicode rules are used for the case change.
3900 =item Otherwise, if C<use feature 'unicode_strings'> or C<use locale ':not_characters'> is in effect:
3902 Unicode rules are used for the case change.
3906 ASCII rules are used for the case change. The lowercase of any character
3907 outside the ASCII range is the character itself.
3912 X<lcfirst> X<lowercase>
3916 =for Pod::Functions return a string with just the next letter in lower case
3918 Returns the value of EXPR with the first character lowercased. This
3919 is the internal function implementing the C<\l> escape in
3920 double-quoted strings.
3922 If EXPR is omitted, uses L<C<$_>|perlvar/$_>.
3924 This function behaves the same way under various pragmas, such as in a locale,
3925 as L<C<lc>|/lc EXPR> does.
3932 =for Pod::Functions return the number of characters in a string
3934 Returns the length in I<characters> of the value of EXPR. If EXPR is
3935 omitted, returns the length of L<C<$_>|perlvar/$_>. If EXPR is
3936 undefined, returns L<C<undef>|/undef EXPR>.
3938 This function cannot be used on an entire array or hash to find out how
3939 many elements these have. For that, use C<scalar @array> and C<scalar keys
3940 %hash>, respectively.
3942 Like all Perl character operations, L<C<length>|/length EXPR> normally
3944 characters, not physical bytes. For how many bytes a string encoded as
3945 UTF-8 would take up, use C<length(Encode::encode('UTF-8', EXPR))>
3946 (you'll have to C<use Encode> first). See L<Encode> and L<perlunicode>.
3951 =for Pod::Functions the current source line number
3953 A special token that compiles to the current line number.
3955 =item link OLDFILE,NEWFILE
3958 =for Pod::Functions create a hard link in the filesystem
3960 Creates a new filename linked to the old filename. Returns true for
3961 success, false otherwise.
3963 Portability issues: L<perlport/link>.
3965 =item listen SOCKET,QUEUESIZE
3968 =for Pod::Functions register your socket as a server
3970 Does the same thing that the L<listen(2)> system call does. Returns true if
3971 it succeeded, false otherwise. See the example in
3972 L<perlipc/"Sockets: Client/Server Communication">.
3977 =for Pod::Functions create a temporary value for a global variable (dynamic scoping)
3979 You really probably want to be using L<C<my>|/my VARLIST> instead,
3980 because L<C<local>|/local EXPR> isn't what most people think of as
3981 "local". See L<perlsub/"Private Variables via my()"> for details.
3983 A local modifies the listed variables to be local to the enclosing
3984 block, file, or eval. If more than one value is listed, the list must
3985 be placed in parentheses. See L<perlsub/"Temporary Values via local()">
3986 for details, including issues with tied arrays and hashes.
3988 The C<delete local EXPR> construct can also be used to localize the deletion
3989 of array/hash elements to the current block.
3990 See L<perlsub/"Localized deletion of elements of composite types">.
3992 =item localtime EXPR
3993 X<localtime> X<ctime>
3997 =for Pod::Functions convert UNIX time into record or string using local time
3999 Converts a time as returned by the time function to a 9-element list
4000 with the time analyzed for the local time zone. Typically used as
4004 my ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
4007 All list elements are numeric and come straight out of the C `struct
4008 tm'. C<$sec>, C<$min>, and C<$hour> are the seconds, minutes, and hours
4009 of the specified time.
4011 C<$mday> is the day of the month and C<$mon> the month in
4012 the range C<0..11>, with 0 indicating January and 11 indicating December.
4013 This makes it easy to get a month name from a list:
4015 my @abbr = qw(Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec);
4016 print "$abbr[$mon] $mday";
4017 # $mon=9, $mday=18 gives "Oct 18"
4019 C<$year> contains the number of years since 1900. To get a 4-digit
4024 To get the last two digits of the year (e.g., "01" in 2001) do:
4026 $year = sprintf("%02d", $year % 100);
4028 C<$wday> is the day of the week, with 0 indicating Sunday and 3 indicating
4029 Wednesday. C<$yday> is the day of the year, in the range C<0..364>
4030 (or C<0..365> in leap years.)
4032 C<$isdst> is true if the specified time occurs during Daylight Saving
4033 Time, false otherwise.
4035 If EXPR is omitted, L<C<localtime>|/localtime EXPR> uses the current
4036 time (as returned by L<C<time>|/time>).
4038 In scalar context, L<C<localtime>|/localtime EXPR> returns the
4041 my $now_string = localtime; # e.g., "Thu Oct 13 04:54:34 1994"
4043 The format of this scalar value is B<not> locale-dependent but built
4044 into Perl. For GMT instead of local time use the
4045 L<C<gmtime>|/gmtime EXPR> builtin. See also the
4046 L<C<Time::Local>|Time::Local> module (for converting seconds, minutes,
4047 hours, and such back to the integer value returned by L<C<time>|/time>),
4048 and the L<POSIX> module's L<C<strftime>|POSIX/C<strftime>> and
4049 L<C<mktime>|POSIX/C<mktime>> functions.
4051 To get somewhat similar but locale-dependent date strings, set up your
4052 locale environment variables appropriately (please see L<perllocale>) and
4055 use POSIX qw(strftime);
4056 my $now_string = strftime "%a %b %e %H:%M:%S %Y", localtime;
4057 # or for GMT formatted appropriately for your locale:
4058 my $now_string = strftime "%a %b %e %H:%M:%S %Y", gmtime;
4060 Note that C<%a> and C<%b>, the short forms of the day of the week
4061 and the month of the year, may not necessarily be three characters wide.
4063 The L<Time::gmtime> and L<Time::localtime> modules provide a convenient,
4064 by-name access mechanism to the L<C<gmtime>|/gmtime EXPR> and
4065 L<C<localtime>|/localtime EXPR> functions, respectively.
4067 For a comprehensive date and time representation look at the
4068 L<DateTime> module on CPAN.
4070 Portability issues: L<perlport/localtime>.
4075 =for Pod::Functions +5.005 get a thread lock on a variable, subroutine, or method
4077 This function places an advisory lock on a shared variable or referenced
4078 object contained in I<THING> until the lock goes out of scope.
4080 The value returned is the scalar itself, if the argument is a scalar, or a
4081 reference, if the argument is a hash, array or subroutine.
4083 L<C<lock>|/lock THING> is a "weak keyword"; this means that if you've
4085 by this name (before any calls to it), that function will be called
4086 instead. If you are not under C<use threads::shared> this does nothing.
4087 See L<threads::shared>.
4090 X<log> X<logarithm> X<e> X<ln> X<base>
4094 =for Pod::Functions retrieve the natural logarithm for a number
4096 Returns the natural logarithm (base I<e>) of EXPR. If EXPR is omitted,
4097 returns the log of L<C<$_>|perlvar/$_>. To get the
4098 log of another base, use basic algebra:
4099 The base-N log of a number is equal to the natural log of that number
4100 divided by the natural log of N. For example:
4104 return log($n)/log(10);
4107 See also L<C<exp>|/exp EXPR> for the inverse operation.
4109 =item lstat FILEHANDLE
4114 =item lstat DIRHANDLE
4118 =for Pod::Functions stat a symbolic link
4120 Does the same thing as the L<C<stat>|/stat FILEHANDLE> function
4121 (including setting the special C<_> filehandle) but stats a symbolic
4122 link instead of the file the symbolic link points to. If symbolic links
4123 are unimplemented on your system, a normal L<C<stat>|/stat FILEHANDLE>
4124 is done. For much more detailed information, please see the
4125 documentation for L<C<stat>|/stat FILEHANDLE>.
4127 If EXPR is omitted, stats L<C<$_>|perlvar/$_>.
4129 Portability issues: L<perlport/lstat>.
4133 =for Pod::Functions match a string with a regular expression pattern
4135 The match operator. See L<perlop/"Regexp Quote-Like Operators">.
4137 =item map BLOCK LIST
4142 =for Pod::Functions apply a change to a list to get back a new list with the changes
4144 Evaluates the BLOCK or EXPR for each element of LIST (locally setting
4145 L<C<$_>|perlvar/$_> to each element) and composes a list of the results of
4146 each such evaluation. Each element of LIST may produce zero, one, or more
4147 elements in the generated list, so the number of elements in the generated
4148 list may differ from that in LIST. In scalar context, returns the total
4149 number of elements so generated. In list context, returns the generated list.
4151 my @chars = map(chr, @numbers);
4153 translates a list of numbers to the corresponding characters.
4155 my @squares = map { $_ * $_ } @numbers;
4157 translates a list of numbers to their squared values.
4159 my @squares = map { $_ > 5 ? ($_ * $_) : () } @numbers;
4161 shows that number of returned elements can differ from the number of
4162 input elements. To omit an element, return an empty list ().
4163 This could also be achieved by writing
4165 my @squares = map { $_ * $_ } grep { $_ > 5 } @numbers;
4167 which makes the intention more clear.
4169 Map always returns a list, which can be
4170 assigned to a hash such that the elements
4171 become key/value pairs. See L<perldata> for more details.
4173 my %hash = map { get_a_key_for($_) => $_ } @array;
4175 is just a funny way to write
4179 $hash{get_a_key_for($_)} = $_;
4182 Note that L<C<$_>|perlvar/$_> is an alias to the list value, so it can
4183 be used to modify the elements of the LIST. While this is useful and
4184 supported, it can cause bizarre results if the elements of LIST are not
4185 variables. Using a regular C<foreach> loop for this purpose would be
4186 clearer in most cases. See also L<C<grep>|/grep BLOCK LIST> for a
4187 list composed of those items of the original list for which the BLOCK
4188 or EXPR evaluates to true.
4190 C<{> starts both hash references and blocks, so C<map { ...> could be either
4191 the start of map BLOCK LIST or map EXPR, LIST. Because Perl doesn't look
4192 ahead for the closing C<}> it has to take a guess at which it's dealing with
4193 based on what it finds just after the
4194 C<{>. Usually it gets it right, but if it
4195 doesn't it won't realize something is wrong until it gets to the C<}> and
4196 encounters the missing (or unexpected) comma. The syntax error will be
4197 reported close to the C<}>, but you'll need to change something near the C<{>
4198 such as using a unary C<+> or semicolon to give Perl some help:
4200 my %hash = map { "\L$_" => 1 } @array # perl guesses EXPR. wrong
4201 my %hash = map { +"\L$_" => 1 } @array # perl guesses BLOCK. right
4202 my %hash = map {; "\L$_" => 1 } @array # this also works
4203 my %hash = map { ("\L$_" => 1) } @array # as does this
4204 my %hash = map { lc($_) => 1 } @array # and this.
4205 my %hash = map +( lc($_) => 1 ), @array # this is EXPR and works!
4207 my %hash = map ( lc($_), 1 ), @array # evaluates to (1, @array)
4209 or to force an anon hash constructor use C<+{>:
4211 my @hashes = map +{ lc($_) => 1 }, @array # EXPR, so needs
4214 to get a list of anonymous hashes each with only one entry apiece.
4216 =item mkdir FILENAME,MODE
4217 X<mkdir> X<md> X<directory, create>
4219 =item mkdir FILENAME
4223 =for Pod::Functions create a directory
4225 Creates the directory specified by FILENAME, with permissions
4226 specified by MODE (as modified by L<C<umask>|/umask EXPR>). If it
4227 succeeds it returns true; otherwise it returns false and sets
4228 L<C<$!>|perlvar/$!> (errno).
4229 MODE defaults to 0777 if omitted, and FILENAME defaults
4230 to L<C<$_>|perlvar/$_> if omitted.
4232 In general, it is better to create directories with a permissive MODE
4233 and let the user modify that with their L<C<umask>|/umask EXPR> than it
4235 a restrictive MODE and give the user no way to be more permissive.
4236 The exceptions to this rule are when the file or directory should be
4237 kept private (mail files, for instance). The documentation for
4238 L<C<umask>|/umask EXPR> discusses the choice of MODE in more detail.
4240 Note that according to the POSIX 1003.1-1996 the FILENAME may have any
4241 number of trailing slashes. Some operating and filesystems do not get
4242 this right, so Perl automatically removes all trailing slashes to keep
4245 To recursively create a directory structure, look at
4246 the L<C<make_path>|File::Path/make_path( $dir1, $dir2, .... )> function
4247 of the L<File::Path> module.
4249 =item msgctl ID,CMD,ARG
4252 =for Pod::Functions SysV IPC message control operations
4254 Calls the System V IPC function L<msgctl(2)>. You'll probably have to say
4258 first to get the correct constant definitions. If CMD is C<IPC_STAT>,
4259 then ARG must be a variable that will hold the returned C<msqid_ds>
4260 structure. Returns like L<C<ioctl>|/ioctl FILEHANDLE,FUNCTION,SCALAR>:
4261 the undefined value for error, C<"0 but true"> for zero, or the actual
4262 return value otherwise. See also L<perlipc/"SysV IPC"> and the
4263 documentation for L<C<IPC::SysV>|IPC::SysV> and
4264 L<C<IPC::Semaphore>|IPC::Semaphore>.
4266 Portability issues: L<perlport/msgctl>.
4268 =item msgget KEY,FLAGS
4271 =for Pod::Functions get SysV IPC message queue
4273 Calls the System V IPC function L<msgget(2)>. Returns the message queue
4274 id, or L<C<undef>|/undef EXPR> on error. See also L<perlipc/"SysV IPC">
4275 and the documentation for L<C<IPC::SysV>|IPC::SysV> and
4276 L<C<IPC::Msg>|IPC::Msg>.
4278 Portability issues: L<perlport/msgget>.
4280 =item msgrcv ID,VAR,SIZE,TYPE,FLAGS
4283 =for Pod::Functions receive a SysV IPC message from a message queue
4285 Calls the System V IPC function msgrcv to receive a message from
4286 message queue ID into variable VAR with a maximum message size of
4287 SIZE. Note that when a message is received, the message type as a
4288 native long integer will be the first thing in VAR, followed by the
4289 actual message. This packing may be opened with C<unpack("l! a*")>.
4290 Taints the variable. Returns true if successful, false
4291 on error. See also L<perlipc/"SysV IPC"> and the documentation for
4292 L<C<IPC::SysV>|IPC::SysV> and L<C<IPC::Msg>|IPC::Msg>.
4294 Portability issues: L<perlport/msgrcv>.
4296 =item msgsnd ID,MSG,FLAGS
4299 =for Pod::Functions send a SysV IPC message to a message queue
4301 Calls the System V IPC function msgsnd to send the message MSG to the
4302 message queue ID. MSG must begin with the native long integer message
4303 type, be followed by the length of the actual message, and then finally
4304 the message itself. This kind of packing can be achieved with
4305 C<pack("l! a*", $type, $message)>. Returns true if successful,
4306 false on error. See also L<perlipc/"SysV IPC"> and the documentation
4307 for L<C<IPC::SysV>|IPC::SysV> and L<C<IPC::Msg>|IPC::Msg>.
4309 Portability issues: L<perlport/msgsnd>.
4314 =item my TYPE VARLIST
4316 =item my VARLIST : ATTRS
4318 =item my TYPE VARLIST : ATTRS
4320 =for Pod::Functions declare and assign a local variable (lexical scoping)
4322 A L<C<my>|/my VARLIST> declares the listed variables to be local
4323 (lexically) to the enclosing block, file, or L<C<eval>|/eval EXPR>. If
4324 more than one variable is listed, the list must be placed in
4327 The exact semantics and interface of TYPE and ATTRS are still
4328 evolving. TYPE may be a bareword, a constant declared
4329 with L<C<use constant>|constant>, or L<C<__PACKAGE__>|/__PACKAGE__>. It
4331 currently bound to the use of the L<fields> pragma,
4332 and attributes are handled using the L<attributes> pragma, or starting
4333 from Perl 5.8.0 also via the L<Attribute::Handlers> module. See
4334 L<perlsub/"Private Variables via my()"> for details.
4336 Note that with a parenthesised list, L<C<undef>|/undef EXPR> can be used
4337 as a dummy placeholder, for example to skip assignment of initial
4340 my ( undef, $min, $hour ) = localtime;
4349 =for Pod::Functions iterate a block prematurely
4351 The L<C<next>|/next LABEL> command is like the C<continue> statement in
4352 C; it starts the next iteration of the loop:
4354 LINE: while (<STDIN>) {
4355 next LINE if /^#/; # discard comments
4359 Note that if there were a L<C<continue>|/continue BLOCK> block on the
4361 executed even on discarded lines. If LABEL is omitted, the command
4362 refers to the innermost enclosing loop. The C<next EXPR> form, available
4363 as of Perl 5.18.0, allows a label name to be computed at run time, being
4364 otherwise identical to C<next LABEL>.
4366 L<C<next>|/next LABEL> cannot return a value from a block that typically
4367 returns a value, such as C<eval {}>, C<sub {}>, or C<do {}>. It will perform
4368 its flow control behavior, which precludes any return value. It should not be
4369 used to exit a L<C<grep>|/grep BLOCK LIST> or L<C<map>|/map BLOCK LIST>
4372 Note that a block by itself is semantically identical to a loop
4373 that executes once. Thus L<C<next>|/next LABEL> will exit such a block
4376 See also L<C<continue>|/continue BLOCK> for an illustration of how
4377 L<C<last>|/last LABEL>, L<C<next>|/next LABEL>, and
4378 L<C<redo>|/redo LABEL> work.
4380 Unlike most named operators, this has the same precedence as assignment.
4381 It is also exempt from the looks-like-a-function rule, so
4382 C<next ("foo")."bar"> will cause "bar" to be part of the argument to
4383 L<C<next>|/next LABEL>.
4385 =item no MODULE VERSION LIST
4389 =item no MODULE VERSION
4391 =item no MODULE LIST
4397 =for Pod::Functions unimport some module symbols or semantics at compile time
4399 See the L<C<use>|/use Module VERSION LIST> function, of which
4400 L<C<no>|/no MODULE VERSION LIST> is the opposite.
4403 X<oct> X<octal> X<hex> X<hexadecimal> X<binary> X<bin>
4407 =for Pod::Functions convert a string to an octal number
4409 Interprets EXPR as an octal string and returns the corresponding
4410 value. (If EXPR happens to start off with C<0x>, interprets it as a
4411 hex string. If EXPR starts off with C<0b>, it is interpreted as a
4412 binary string. Leading whitespace is ignored in all three cases.)
4413 The following will handle decimal, binary, octal, and hex in standard
4416 $val = oct($val) if $val =~ /^0/;
4418 If EXPR is omitted, uses L<C<$_>|perlvar/$_>. To go the other way
4419 (produce a number in octal), use L<C<sprintf>|/sprintf FORMAT, LIST> or
4420 L<C<printf>|/printf FILEHANDLE FORMAT, LIST>:
4422 my $dec_perms = (stat("filename"))[2] & 07777;
4423 my $oct_perm_str = sprintf "%o", $perms;
4425 The L<C<oct>|/oct EXPR> function is commonly used when a string such as
4427 to be converted into a file mode, for example. Although Perl
4428 automatically converts strings into numbers as needed, this automatic
4429 conversion assumes base 10.
4431 Leading white space is ignored without warning, as too are any trailing
4432 non-digits, such as a decimal point (L<C<oct>|/oct EXPR> only handles
4433 non-negative integers, not negative integers or floating point).
4435 =item open FILEHANDLE,EXPR
4436 X<open> X<pipe> X<file, open> X<fopen>
4438 =item open FILEHANDLE,MODE,EXPR
4440 =item open FILEHANDLE,MODE,EXPR,LIST
4442 =item open FILEHANDLE,MODE,REFERENCE
4444 =item open FILEHANDLE
4446 =for Pod::Functions open a file, pipe, or descriptor
4448 Opens the file whose filename is given by EXPR, and associates it with
4451 Simple examples to open a file for reading:
4453 open(my $fh, "<", "input.txt")
4454 or die "Can't open < input.txt: $!";
4458 open(my $fh, ">", "output.txt")
4459 or die "Can't open > output.txt: $!";
4461 (The following is a comprehensive reference to
4462 L<C<open>|/open FILEHANDLE,EXPR>: for a gentler introduction you may
4463 consider L<perlopentut>.)
4465 If FILEHANDLE is an undefined scalar variable (or array or hash element), a
4466 new filehandle is autovivified, meaning that the variable is assigned a
4467 reference to a newly allocated anonymous filehandle. Otherwise if
4468 FILEHANDLE is an expression, its value is the real filehandle. (This is
4469 considered a symbolic reference, so C<use strict "refs"> should I<not> be
4472 If three (or more) arguments are specified, the open mode (including
4473 optional encoding) in the second argument are distinct from the filename in
4474 the third. If MODE is C<< < >> or nothing, the file is opened for input.
4475 If MODE is C<< > >>, the file is opened for output, with existing files
4476 first being truncated ("clobbered") and nonexisting files newly created.
4477 If MODE is C<<< >> >>>, the file is opened for appending, again being
4478 created if necessary.
4480 You can put a C<+> in front of the C<< > >> or C<< < >> to
4481 indicate that you want both read and write access to the file; thus
4482 C<< +< >> is almost always preferred for read/write updates--the
4483 C<< +> >> mode would clobber the file first. You can't usually use
4484 either read-write mode for updating textfiles, since they have
4485 variable-length records. See the B<-i> switch in L<perlrun> for a
4486 better approach. The file is created with permissions of C<0666>
4487 modified by the process's L<C<umask>|/umask EXPR> value.
4489 These various prefixes correspond to the L<fopen(3)> modes of C<r>,
4490 C<r+>, C<w>, C<w+>, C<a>, and C<a+>.
4492 In the one- and two-argument forms of the call, the mode and filename
4493 should be concatenated (in that order), preferably separated by white
4494 space. You can--but shouldn't--omit the mode in these forms when that mode
4495 is C<< < >>. It is safe to use the two-argument form of
4496 L<C<open>|/open FILEHANDLE,EXPR> if the filename argument is a known literal.
4498 For three or more arguments if MODE is C<|->, the filename is
4499 interpreted as a command to which output is to be piped, and if MODE
4500 is C<-|>, the filename is interpreted as a command that pipes
4501 output to us. In the two-argument (and one-argument) form, one should
4502 replace dash (C<->) with the command.
4503 See L<perlipc/"Using open() for IPC"> for more examples of this.
4504 (You are not allowed to L<C<open>|/open FILEHANDLE,EXPR> to a command
4505 that pipes both in I<and> out, but see L<IPC::Open2>, L<IPC::Open3>, and
4506 L<perlipc/"Bidirectional Communication with Another Process"> for
4509 In the form of pipe opens taking three or more arguments, if LIST is specified
4510 (extra arguments after the command name) then LIST becomes arguments
4511 to the command invoked if the platform supports it. The meaning of
4512 L<C<open>|/open FILEHANDLE,EXPR> with more than three arguments for
4513 non-pipe modes is not yet defined, but experimental "layers" may give
4514 extra LIST arguments meaning.
4516 In the two-argument (and one-argument) form, opening C<< <- >>
4517 or C<-> opens STDIN and opening C<< >- >> opens STDOUT.
4519 You may (and usually should) use the three-argument form of open to specify
4520 I/O layers (sometimes referred to as "disciplines") to apply to the handle
4521 that affect how the input and output are processed (see L<open> and
4522 L<PerlIO> for more details). For example:
4524 open(my $fh, "<:encoding(UTF-8)", $filename)
4525 || die "Can't open UTF-8 encoded $filename: $!";
4527 opens the UTF8-encoded file containing Unicode characters;
4528 see L<perluniintro>. Note that if layers are specified in the
4529 three-argument form, then default layers stored in ${^OPEN} (see L<perlvar>;
4530 usually set by the L<open> pragma or the switch C<-CioD>) are ignored.
4531 Those layers will also be ignored if you specify a colon with no name
4532 following it. In that case the default layer for the operating system
4533 (:raw on Unix, :crlf on Windows) is used.
4535 Open returns nonzero on success, the undefined value otherwise. If
4536 the L<C<open>|/open FILEHANDLE,EXPR> involved a pipe, the return value
4537 happens to be the pid of the subprocess.
4539 On some systems (in general, DOS- and Windows-based systems)
4540 L<C<binmode>|/binmode FILEHANDLE, LAYER> is necessary when you're not
4541 working with a text file. For the sake of portability it is a good idea
4542 always to use it when appropriate, and never to use it when it isn't
4543 appropriate. Also, people can set their I/O to be by default
4544 UTF8-encoded Unicode, not bytes.
4546 When opening a file, it's seldom a good idea to continue
4547 if the request failed, so L<C<open>|/open FILEHANDLE,EXPR> is frequently
4548 used with L<C<die>|/die LIST>. Even if L<C<die>|/die LIST> won't do
4549 what you want (say, in a CGI script,
4550 where you want to format a suitable error message (but there are
4551 modules that can help with that problem)) always check
4552 the return value from opening a file.
4554 The filehandle will be closed when its reference count reaches zero.
4555 If it is a lexically scoped variable declared with L<C<my>|/my VARLIST>,
4557 means the end of the enclosing scope. However, this automatic close
4558 does not check for errors, so it is better to explicitly close
4559 filehandles, especially those used for writing:
4562 || warn "close failed: $!";
4564 An older style is to use a bareword as the filehandle, as
4566 open(FH, "<", "input.txt")
4567 or die "Can't open < input.txt: $!";
4569 Then you can use C<FH> as the filehandle, in C<< close FH >> and C<<
4570 <FH> >> and so on. Note that it's a global variable, so this form is
4571 not recommended in new code.
4573 As a shortcut a one-argument call takes the filename from the global
4574 scalar variable of the same name as the filehandle:
4577 open(ARTICLE) or die "Can't find article $ARTICLE: $!\n";
4579 Here C<$ARTICLE> must be a global (package) scalar variable - not one
4580 declared with L<C<my>|/my VARLIST> or L<C<state>|/state VARLIST>.
4582 As a special case the three-argument form with a read/write mode and the third
4583 argument being L<C<undef>|/undef EXPR>:
4585 open(my $tmp, "+>", undef) or die ...
4587 opens a filehandle to a newly created empty anonymous temporary file.
4588 (This happens under any mode, which makes C<< +> >> the only useful and
4589 sensible mode to use.) You will need to
4590 L<C<seek>|/seek FILEHANDLE,POSITION,WHENCE> to do the reading.
4592 Perl is built using PerlIO by default. Unless you've
4593 changed this (such as building Perl with C<Configure -Uuseperlio>), you can
4594 open filehandles directly to Perl scalars via:
4596 open(my $fh, ">", \$variable) || ..
4598 To (re)open C<STDOUT> or C<STDERR> as an in-memory file, close it first:
4601 open(STDOUT, ">", \$variable)
4602 or die "Can't open STDOUT: $!";
4604 The scalars for in-memory files are treated as octet strings: unless
4605 the file is being opened with truncation the scalar may not contain
4606 any code points over 0xFF.
4608 Opening in-memory files I<can> fail for a variety of reasons. As with
4609 any other C<open>, check the return value for success.
4611 See L<perliol> for detailed info on PerlIO.
4615 open(my $log, ">>", "/usr/spool/news/twitlog");
4616 # if the open fails, output is discarded
4618 open(my $dbase, "+<", "dbase.mine") # open for update
4619 or die "Can't open 'dbase.mine' for update: $!";
4621 open(my $dbase, "+<dbase.mine") # ditto
4622 or die "Can't open 'dbase.mine' for update: $!";
4624 open(my $article_fh, "-|", "caesar <$article") # decrypt
4626 or die "Can't start caesar: $!";
4628 open(my $article_fh, "caesar <$article |") # ditto
4629 or die "Can't start caesar: $!";
4631 open(my $out_fh, "|-", "sort >Tmp$$") # $$ is our process id
4632 or die "Can't start sort: $!";
4635 open(my $memory, ">", \$var)
4636 or die "Can't open memory file: $!";
4637 print $memory "foo!\n"; # output will appear in $var
4639 You may also, in the Bourne shell tradition, specify an EXPR beginning
4640 with C<< >& >>, in which case the rest of the string is interpreted
4641 as the name of a filehandle (or file descriptor, if numeric) to be
4642 duped (as in L<dup(2)>) and opened. You may use C<&> after C<< > >>,
4643 C<<< >> >>>, C<< < >>, C<< +> >>, C<<< +>> >>>, and C<< +< >>.
4644 The mode you specify should match the mode of the original filehandle.
4645 (Duping a filehandle does not take into account any existing contents
4646 of IO buffers.) If you use the three-argument
4647 form, then you can pass either a
4648 number, the name of a filehandle, or the normal "reference to a glob".
4650 Here is a script that saves, redirects, and restores C<STDOUT> and
4651 C<STDERR> using various methods:
4654 open(my $oldout, ">&STDOUT") or die "Can't dup STDOUT: $!";
4655 open(OLDERR, ">&", \*STDERR) or die "Can't dup STDERR: $!";
4657 open(STDOUT, '>', "foo.out") or die "Can't redirect STDOUT: $!";
4658 open(STDERR, ">&STDOUT") or die "Can't dup STDOUT: $!";
4660 select STDERR; $| = 1; # make unbuffered
4661 select STDOUT; $| = 1; # make unbuffered
4663 print STDOUT "stdout 1\n"; # this works for
4664 print STDERR "stderr 1\n"; # subprocesses too
4666 open(STDOUT, ">&", $oldout) or die "Can't dup \$oldout: $!";
4667 open(STDERR, ">&OLDERR") or die "Can't dup OLDERR: $!";
4669 print STDOUT "stdout 2\n";
4670 print STDERR "stderr 2\n";
4672 If you specify C<< '<&=X' >>, where C<X> is a file descriptor number
4673 or a filehandle, then Perl will do an equivalent of C's L<fdopen(3)> of
4674 that file descriptor (and not call L<dup(2)>); this is more
4675 parsimonious of file descriptors. For example:
4677 # open for input, reusing the fileno of $fd
4678 open(my $fh, "<&=", $fd)
4682 open(my $fh, "<&=$fd")
4686 # open for append, using the fileno of $oldfh
4687 open(my $fh, ">>&=", $oldfh)
4689 Being parsimonious on filehandles is also useful (besides being
4690 parsimonious) for example when something is dependent on file
4691 descriptors, like for example locking using
4692 L<C<flock>|/flock FILEHANDLE,OPERATION>. If you do just
4693 C<< open(my $A, ">>&", $B) >>, the filehandle C<$A> will not have the
4694 same file descriptor as C<$B>, and therefore C<flock($A)> will not
4695 C<flock($B)> nor vice versa. But with C<< open(my $A, ">>&=", $B) >>,
4696 the filehandles will share the same underlying system file descriptor.
4698 Note that under Perls older than 5.8.0, Perl uses the standard C library's'
4699 L<fdopen(3)> to implement the C<=> functionality. On many Unix systems,
4700 L<fdopen(3)> fails when file descriptors exceed a certain value, typically 255.
4701 For Perls 5.8.0 and later, PerlIO is (most often) the default.
4703 You can see whether your Perl was built with PerlIO by running
4704 C<perl -V:useperlio>. If it says C<'define'>, you have PerlIO;
4705 otherwise you don't.
4707 If you open a pipe on the command C<-> (that is, specify either C<|-> or C<-|>
4708 with the one- or two-argument forms of
4709 L<C<open>|/open FILEHANDLE,EXPR>), an implicit L<C<fork>|/fork> is done,
4710 so L<C<open>|/open FILEHANDLE,EXPR> returns twice: in the parent process
4712 of the child process, and in the child process it returns (a defined) C<0>.
4713 Use C<defined($pid)> or C<//> to determine whether the open was successful.
4715 For example, use either
4717 my $child_pid = open(my $from_kid, "-|") // die "Can't fork: $!";
4721 my $child_pid = open(my $to_kid, "|-") // die "Can't fork: $!";
4727 # either write $to_kid or else read $from_kid
4729 waitpid $child_pid, 0;
4731 # am the child; use STDIN/STDOUT normally
4736 The filehandle behaves normally for the parent, but I/O to that
4737 filehandle is piped from/to the STDOUT/STDIN of the child process.
4738 In the child process, the filehandle isn't opened--I/O happens from/to
4739 the new STDOUT/STDIN. Typically this is used like the normal
4740 piped open when you want to exercise more control over just how the
4741 pipe command gets executed, such as when running setuid and
4742 you don't want to have to scan shell commands for metacharacters.
4744 The following blocks are more or less equivalent:
4746 open(my $fh, "|tr '[a-z]' '[A-Z]'");
4747 open(my $fh, "|-", "tr '[a-z]' '[A-Z]'");
4748 open(my $fh, "|-") || exec 'tr', '[a-z]', '[A-Z]';
4749 open(my $fh, "|-", "tr", '[a-z]', '[A-Z]');
4751 open(my $fh, "cat -n '$file'|");
4752 open(my $fh, "-|", "cat -n '$file'");
4753 open(my $fh, "-|") || exec "cat", "-n", $file;
4754 open(my $fh, "-|", "cat", "-n", $file);
4756 The last two examples in each block show the pipe as "list form", which is
4757 not yet supported on all platforms. A good rule of thumb is that if
4758 your platform has a real L<C<fork>|/fork> (in other words, if your platform is
4759 Unix, including Linux and MacOS X), you can use the list form. You would
4760 want to use the list form of the pipe so you can pass literal arguments
4761 to the command without risk of the shell interpreting any shell metacharacters
4762 in them. However, this also bars you from opening pipes to commands
4763 that intentionally contain shell metacharacters, such as:
4765 open(my $fh, "|cat -n | expand -4 | lpr")
4766 || die "Can't open pipeline to lpr: $!";
4768 See L<perlipc/"Safe Pipe Opens"> for more examples of this.
4770 Perl will attempt to flush all files opened for
4771 output before any operation that may do a fork, but this may not be
4772 supported on some platforms (see L<perlport>). To be safe, you may need
4773 to set L<C<$E<verbar>>|perlvar/$E<verbar>> (C<$AUTOFLUSH> in L<English>)
4774 or call the C<autoflush> method of L<C<IO::Handle>|IO::Handle/METHODS>
4775 on any open handles.
4777 On systems that support a close-on-exec flag on files, the flag will
4778 be set for the newly opened file descriptor as determined by the value
4779 of L<C<$^F>|perlvar/$^F>. See L<perlvar/$^F>.
4781 Closing any piped filehandle causes the parent process to wait for the
4782 child to finish, then returns the status value in L<C<$?>|perlvar/$?> and
4783 L<C<${^CHILD_ERROR_NATIVE}>|perlvar/${^CHILD_ERROR_NATIVE}>.
4785 The filename passed to the one- and two-argument forms of
4786 L<C<open>|/open FILEHANDLE,EXPR> will
4787 have leading and trailing whitespace deleted and normal
4788 redirection characters honored. This property, known as "magic open",
4789 can often be used to good effect. A user could specify a filename of
4790 F<"rsh cat file |">, or you could change certain filenames as needed:
4792 $filename =~ s/(.*\.gz)\s*$/gzip -dc < $1|/;
4793 open(my $fh, $filename) or die "Can't open $filename: $!";
4795 Use the three-argument form to open a file with arbitrary weird characters in it,
4797 open(my $fh, "<", $file)
4798 || die "Can't open $file: $!";
4800 otherwise it's necessary to protect any leading and trailing whitespace:
4802 $file =~ s#^(\s)#./$1#;
4803 open(my $fh, "< $file\0")
4804 || die "Can't open $file: $!";
4806 (this may not work on some bizarre filesystems). One should
4807 conscientiously choose between the I<magic> and I<three-argument> form
4808 of L<C<open>|/open FILEHANDLE,EXPR>:
4810 open(my $in, $ARGV[0]) || die "Can't open $ARGV[0]: $!";
4812 will allow the user to specify an argument of the form C<"rsh cat file |">,
4813 but will not work on a filename that happens to have a trailing space, while
4815 open(my $in, "<", $ARGV[0])
4816 || die "Can't open $ARGV[0]: $!";
4818 will have exactly the opposite restrictions. (However, some shells
4819 support the syntax C<< perl your_program.pl <( rsh cat file ) >>, which
4820 produces a filename that can be opened normally.)
4822 If you want a "real" C L<open(2)>, then you should use the
4823 L<C<sysopen>|/sysopen FILEHANDLE,FILENAME,MODE> function, which involves
4824 no such magic (but uses different filemodes than Perl
4825 L<C<open>|/open FILEHANDLE,EXPR>, which corresponds to C L<fopen(3)>).
4826 This is another way to protect your filenames from interpretation. For
4830 sysopen(my $fh, $path, O_RDWR|O_CREAT|O_EXCL)
4831 or die "Can't open $path: $!";
4833 print $fh "stuff $$\n";
4835 print "File contains: ", readline($fh);
4837 See L<C<seek>|/seek FILEHANDLE,POSITION,WHENCE> for some details about
4838 mixing reading and writing.
4840 Portability issues: L<perlport/open>.
4842 =item opendir DIRHANDLE,EXPR
4845 =for Pod::Functions open a directory
4847 Opens a directory named EXPR for processing by
4848 L<C<readdir>|/readdir DIRHANDLE>, L<C<telldir>|/telldir DIRHANDLE>,
4849 L<C<seekdir>|/seekdir DIRHANDLE,POS>,
4850 L<C<rewinddir>|/rewinddir DIRHANDLE>, and
4851 L<C<closedir>|/closedir DIRHANDLE>. Returns true if successful.
4852 DIRHANDLE may be an expression whose value can be used as an indirect
4853 dirhandle, usually the real dirhandle name. If DIRHANDLE is an undefined
4854 scalar variable (or array or hash element), the variable is assigned a
4855 reference to a new anonymous dirhandle; that is, it's autovivified.
4856 Dirhandles are the same objects as filehandles; an I/O object can only
4857 be open as one of these handle types at once.
4859 See the example at L<C<readdir>|/readdir DIRHANDLE>.
4866 =for Pod::Functions find a character's numeric representation
4868 Returns the numeric value of the first character of EXPR.
4869 If EXPR is an empty string, returns 0. If EXPR is omitted, uses
4870 L<C<$_>|perlvar/$_>.
4871 (Note I<character>, not byte.)
4873 For the reverse, see L<C<chr>|/chr NUMBER>.
4874 See L<perlunicode> for more about Unicode.
4879 =item our TYPE VARLIST
4881 =item our VARLIST : ATTRS
4883 =item our TYPE VARLIST : ATTRS
4885 =for Pod::Functions +5.6.0 declare and assign a package variable (lexical scoping)
4887 L<C<our>|/our VARLIST> makes a lexical alias to a package (i.e. global)
4888 variable of the same name in the current package for use within the
4889 current lexical scope.
4891 L<C<our>|/our VARLIST> has the same scoping rules as
4892 L<C<my>|/my VARLIST> or L<C<state>|/state VARLIST>, meaning that it is
4893 only valid within a lexical scope. Unlike L<C<my>|/my VARLIST> and
4894 L<C<state>|/state VARLIST>, which both declare new (lexical) variables,
4895 L<C<our>|/our VARLIST> only creates an alias to an existing variable: a
4896 package variable of the same name.
4898 This means that when C<use strict 'vars'> is in effect, L<C<our>|/our
4899 VARLIST> lets you use a package variable without qualifying it with the
4900 package name, but only within the lexical scope of the
4901 L<C<our>|/our VARLIST> declaration. This applies immediately--even
4902 within the same statement.
4910 our $foo; # alias to $Foo::foo
4911 print $foo; # prints 23
4914 print $Foo::foo; # prints 23
4916 print $foo; # ERROR: requires explicit package name
4918 This works even if the package variable has not been used before, as
4919 package variables spring into existence when first used.
4924 our $foo = 23; # just like $Foo::foo = 23
4926 print $Foo::foo; # prints 23
4928 Because the variable becomes legal immediately under C<use strict 'vars'>, so
4929 long as there is no variable with that name is already in scope, you can then
4930 reference the package variable again even within the same statement.
4935 my $foo = $foo; # error, undeclared $foo on right-hand side
4936 our $foo = $foo; # no errors
4938 If more than one variable is listed, the list must be placed
4943 An L<C<our>|/our VARLIST> declaration declares an alias for a package
4944 variable that will be visible
4945 across its entire lexical scope, even across package boundaries. The
4946 package in which the variable is entered is determined at the point
4947 of the declaration, not at the point of use. This means the following
4951 our $bar; # declares $Foo::bar for rest of lexical scope
4955 print $bar; # prints 20, as it refers to $Foo::bar
4957 Multiple L<C<our>|/our VARLIST> declarations with the same name in the
4959 scope are allowed if they are in different packages. If they happen
4960 to be in the same package, Perl will emit warnings if you have asked
4961 for them, just like multiple L<C<my>|/my VARLIST> declarations. Unlike
4962 a second L<C<my>|/my VARLIST> declaration, which will bind the name to a
4963 fresh variable, a second L<C<our>|/our VARLIST> declaration in the same
4964 package, in the same scope, is merely redundant.
4968 our $bar; # declares $Foo::bar for rest of lexical scope
4972 our $bar = 30; # declares $Bar::bar for rest of lexical scope
4973 print $bar; # prints 30
4975 our $bar; # emits warning but has no other effect
4976 print $bar; # still prints 30
4978 An L<C<our>|/our VARLIST> declaration may also have a list of attributes
4981 The exact semantics and interface of TYPE and ATTRS are still
4982 evolving. TYPE is currently bound to the use of the L<fields> pragma,
4983 and attributes are handled using the L<attributes> pragma, or, starting
4984 from Perl 5.8.0, also via the L<Attribute::Handlers> module. See
4985 L<perlsub/"Private Variables via my()"> for details.
4987 Note that with a parenthesised list, L<C<undef>|/undef EXPR> can be used
4988 as a dummy placeholder, for example to skip assignment of initial
4991 our ( undef, $min, $hour ) = localtime;
4993 L<C<our>|/our VARLIST> differs from L<C<use vars>|vars>, which allows
4994 use of an unqualified name I<only> within the affected package, but
4997 =item pack TEMPLATE,LIST
5000 =for Pod::Functions convert a list into a binary representation
5002 Takes a LIST of values and converts it into a string using the rules
5003 given by the TEMPLATE. The resulting string is the concatenation of
5004 the converted values. Typically, each converted value looks
5005 like its machine-level representation. For example, on 32-bit machines
5006 an integer may be represented by a sequence of 4 bytes, which will in
5007 Perl be presented as a string that's 4 characters long.
5009 See L<perlpacktut> for an introduction to this function.
5011 The TEMPLATE is a sequence of characters that give the order and type
5012 of values, as follows:
5014 a A string with arbitrary binary data, will be null padded.
5015 A A text (ASCII) string, will be space padded.
5016 Z A null-terminated (ASCIZ) string, will be null padded.
5018 b A bit string (ascending bit order inside each byte,
5020 B A bit string (descending bit order inside each byte).
5021 h A hex string (low nybble first).
5022 H A hex string (high nybble first).
5024 c A signed char (8-bit) value.
5025 C An unsigned char (octet) value.
5026 W An unsigned char value (can be greater than 255).
5028 s A signed short (16-bit) value.
5029 S An unsigned short value.
5031 l A signed long (32-bit) value.
5032 L An unsigned long value.
5034 q A signed quad (64-bit) value.
5035 Q An unsigned quad value.
5036 (Quads are available only if your system supports 64-bit
5037 integer values _and_ if Perl has been compiled to support
5038 those. Raises an exception otherwise.)
5040 i A signed integer value.
5041 I An unsigned integer value.
5042 (This 'integer' is _at_least_ 32 bits wide. Its exact
5043 size depends on what a local C compiler calls 'int'.)
5045 n An unsigned short (16-bit) in "network" (big-endian) order.
5046 N An unsigned long (32-bit) in "network" (big-endian) order.
5047 v An unsigned short (16-bit) in "VAX" (little-endian) order.
5048 V An unsigned long (32-bit) in "VAX" (little-endian) order.
5050 j A Perl internal signed integer value (IV).
5051 J A Perl internal unsigned integer value (UV).
5053 f A single-precision float in native format.
5054 d A double-precision float in native format.
5056 F A Perl internal floating-point value (NV) in native format
5057 D A float of long-double precision in native format.
5058 (Long doubles are available only if your system supports
5059 long double values _and_ if Perl has been compiled to
5060 support those. Raises an exception otherwise.
5061 Note that there are different long double formats.)
5063 p A pointer to a null-terminated string.
5064 P A pointer to a structure (fixed-length string).
5066 u A uuencoded string.
5067 U A Unicode character number. Encodes to a character in char-
5068 acter mode and UTF-8 (or UTF-EBCDIC in EBCDIC platforms) in
5071 w A BER compressed integer (not an ASN.1 BER, see perlpacktut
5072 for details). Its bytes represent an unsigned integer in
5073 base 128, most significant digit first, with as few digits
5074 as possible. Bit eight (the high bit) is set on each byte
5077 x A null byte (a.k.a ASCII NUL, "\000", chr(0))
5079 @ Null-fill or truncate to absolute position, counted from the
5080 start of the innermost ()-group.
5081 . Null-fill or truncate to absolute position specified by
5083 ( Start of a ()-group.
5085 One or more modifiers below may optionally follow certain letters in the
5086 TEMPLATE (the second column lists letters for which the modifier is valid):
5088 ! sSlLiI Forces native (short, long, int) sizes instead
5089 of fixed (16-/32-bit) sizes.
5091 ! xX Make x and X act as alignment commands.
5093 ! nNvV Treat integers as signed instead of unsigned.
5095 ! @. Specify position as byte offset in the internal
5096 representation of the packed string. Efficient
5099 > sSiIlLqQ Force big-endian byte-order on the type.
5100 jJfFdDpP (The "big end" touches the construct.)
5102 < sSiIlLqQ Force little-endian byte-order on the type.
5103 jJfFdDpP (The "little end" touches the construct.)
5105 The C<< > >> and C<< < >> modifiers can also be used on C<()> groups
5106 to force a particular byte-order on all components in that group,
5107 including all its subgroups.
5111 Larry recalls that the hex and bit string formats (H, h, B, b) were added to
5112 pack for processing data from NASA's Magellan probe. Magellan was in an
5113 elliptical orbit, using the antenna for the radar mapping when close to
5114 Venus and for communicating data back to Earth for the rest of the orbit.
5115 There were two transmission units, but one of these failed, and then the
5116 other developed a fault whereby it would randomly flip the sense of all the
5117 bits. It was easy to automatically detect complete records with the correct
5118 sense, and complete records with all the bits flipped. However, this didn't
5119 recover the records where the sense flipped midway. A colleague of Larry's
5120 was able to pretty much eyeball where the records flipped, so they wrote an
5121 editor named kybble (a pun on the dog food Kibbles 'n Bits) to enable him to
5122 manually correct the records and recover the data. For this purpose pack
5123 gained the hex and bit string format specifiers.
5125 git shows that they were added to perl 3.0 in patch #44 (Jan 1991, commit
5126 27e2fb84680b9cc1), but the patch description makes no mention of their
5127 addition, let alone the story behind them.
5131 The following rules apply:
5137 Each letter may optionally be followed by a number indicating the repeat
5138 count. A numeric repeat count may optionally be enclosed in brackets, as
5139 in C<pack("C[80]", @arr)>. The repeat count gobbles that many values from
5140 the LIST when used with all format types other than C<a>, C<A>, C<Z>, C<b>,
5141 C<B>, C<h>, C<H>, C<@>, C<.>, C<x>, C<X>, and C<P>, where it means
5142 something else, described below. Supplying a C<*> for the repeat count
5143 instead of a number means to use however many items are left, except for:
5149 C<@>, C<x>, and C<X>, where it is equivalent to C<0>.
5153 <.>, where it means relative to the start of the string.
5157 C<u>, where it is equivalent to 1 (or 45, which here is equivalent).
5161 One can replace a numeric repeat count with a template letter enclosed in
5162 brackets to use the packed byte length of the bracketed template for the
5165 For example, the template C<x[L]> skips as many bytes as in a packed long,
5166 and the template C<"$t X[$t] $t"> unpacks twice whatever $t (when
5167 variable-expanded) unpacks. If the template in brackets contains alignment
5168 commands (such as C<x![d]>), its packed length is calculated as if the
5169 start of the template had the maximal possible alignment.
5171 When used with C<Z>, a C<*> as the repeat count is guaranteed to add a
5172 trailing null byte, so the resulting string is always one byte longer than
5173 the byte length of the item itself.
5175 When used with C<@>, the repeat count represents an offset from the start
5176 of the innermost C<()> group.
5178 When used with C<.>, the repeat count determines the starting position to
5179 calculate the value offset as follows:
5185 If the repeat count is C<0>, it's relative to the current position.
5189 If the repeat count is C<*>, the offset is relative to the start of the
5194 And if it's an integer I<n>, the offset is relative to the start of the
5195 I<n>th innermost C<( )> group, or to the start of the string if I<n> is
5196 bigger then the group level.
5200 The repeat count for C<u> is interpreted as the maximal number of bytes
5201 to encode per line of output, with 0, 1 and 2 replaced by 45. The repeat
5202 count should not be more than 65.
5206 The C<a>, C<A>, and C<Z> types gobble just one value, but pack it as a
5207 string of length count, padding with nulls or spaces as needed. When
5208 unpacking, C<A> strips trailing whitespace and nulls, C<Z> strips everything
5209 after the first null, and C<a> returns data with no stripping at all.
5211 If the value to pack is too long, the result is truncated. If it's too
5212 long and an explicit count is provided, C<Z> packs only C<$count-1> bytes,
5213 followed by a null byte. Thus C<Z> always packs a trailing null, except
5214 when the count is 0.
5218 Likewise, the C<b> and C<B> formats pack a string that's that many bits long.
5219 Each such format generates 1 bit of the result. These are typically followed
5220 by a repeat count like C<B8> or C<B64>.
5222 Each result bit is based on the least-significant bit of the corresponding
5223 input character, i.e., on C<ord($char)%2>. In particular, characters C<"0">
5224 and C<"1"> generate bits 0 and 1, as do characters C<"\000"> and C<"\001">.
5226 Starting from the beginning of the input string, each 8-tuple
5227 of characters is converted to 1 character of output. With format C<b>,
5228 the first character of the 8-tuple determines the least-significant bit of a
5229 character; with format C<B>, it determines the most-significant bit of
5232 If the length of the input string is not evenly divisible by 8, the
5233 remainder is packed as if the input string were padded by null characters
5234 at the end. Similarly during unpacking, "extra" bits are ignored.
5236 If the input string is longer than needed, remaining characters are ignored.
5238 A C<*> for the repeat count uses all characters of the input field.
5239 On unpacking, bits are converted to a string of C<0>s and C<1>s.
5243 The C<h> and C<H> formats pack a string that many nybbles (4-bit groups,
5244 representable as hexadecimal digits, C<"0".."9"> C<"a".."f">) long.
5246 For each such format, L<C<pack>|/pack TEMPLATE,LIST> generates 4 bits of result.
5247 With non-alphabetical characters, the result is based on the 4 least-significant
5248 bits of the input character, i.e., on C<ord($char)%16>. In particular,
5249 characters C<"0"> and C<"1"> generate nybbles 0 and 1, as do bytes
5250 C<"\000"> and C<"\001">. For characters C<"a".."f"> and C<"A".."F">, the result
5251 is compatible with the usual hexadecimal digits, so that C<"a"> and
5252 C<"A"> both generate the nybble C<0xA==10>. Use only these specific hex
5253 characters with this format.
5255 Starting from the beginning of the template to
5256 L<C<pack>|/pack TEMPLATE,LIST>, each pair
5257 of characters is converted to 1 character of output. With format C<h>, the
5258 first character of the pair determines the least-significant nybble of the
5259 output character; with format C<H>, it determines the most-significant
5262 If the length of the input string is not even, it behaves as if padded by
5263 a null character at the end. Similarly, "extra" nybbles are ignored during
5266 If the input string is longer than needed, extra characters are ignored.
5268 A C<*> for the repeat count uses all characters of the input field. For
5269 L<C<unpack>|/unpack TEMPLATE,EXPR>, nybbles are converted to a string of
5274 The C<p> format packs a pointer to a null-terminated string. You are
5275 responsible for ensuring that the string is not a temporary value, as that
5276 could potentially get deallocated before you got around to using the packed
5277 result. The C<P> format packs a pointer to a structure of the size indicated
5278 by the length. A null pointer is created if the corresponding value for
5279 C<p> or C<P> is L<C<undef>|/undef EXPR>; similarly with
5280 L<C<unpack>|/unpack TEMPLATE,EXPR>, where a null pointer unpacks into
5281 L<C<undef>|/undef EXPR>.
5283 If your system has a strange pointer size--meaning a pointer is neither as
5284 big as an int nor as big as a long--it may not be possible to pack or
5285 unpack pointers in big- or little-endian byte order. Attempting to do
5286 so raises an exception.
5290 The C</> template character allows packing and unpacking of a sequence of
5291 items where the packed structure contains a packed item count followed by
5292 the packed items themselves. This is useful when the structure you're
5293 unpacking has encoded the sizes or repeat counts for some of its fields
5294 within the structure itself as separate fields.
5296 For L<C<pack>|/pack TEMPLATE,LIST>, you write
5297 I<length-item>C</>I<sequence-item>, and the
5298 I<length-item> describes how the length value is packed. Formats likely
5299 to be of most use are integer-packing ones like C<n> for Java strings,
5300 C<w> for ASN.1 or SNMP, and C<N> for Sun XDR.
5302 For L<C<pack>|/pack TEMPLATE,LIST>, I<sequence-item> may have a repeat
5303 count, in which case
5304 the minimum of that and the number of available items is used as the argument
5305 for I<length-item>. If it has no repeat count or uses a '*', the number
5306 of available items is used.
5308 For L<C<unpack>|/unpack TEMPLATE,EXPR>, an internal stack of integer
5309 arguments unpacked so far is
5310 used. You write C</>I<sequence-item> and the repeat count is obtained by
5311 popping off the last element from the stack. The I<sequence-item> must not
5312 have a repeat count.
5314 If I<sequence-item> refers to a string type (C<"A">, C<"a">, or C<"Z">),
5315 the I<length-item> is the string length, not the number of strings. With
5316 an explicit repeat count for pack, the packed string is adjusted to that
5317 length. For example:
5319 This code: gives this result:
5321 unpack("W/a", "\004Gurusamy") ("Guru")
5322 unpack("a3/A A*", "007 Bond J ") (" Bond", "J")
5323 unpack("a3 x2 /A A*", "007: Bond, J.") ("Bond, J", ".")
5325 pack("n/a* w/a","hello,","world") "\000\006hello,\005world"
5326 pack("a/W2", ord("a") .. ord("z")) "2ab"
5328 The I<length-item> is not returned explicitly from
5329 L<C<unpack>|/unpack TEMPLATE,EXPR>.
5331 Supplying a count to the I<length-item> format letter is only useful with
5332 C<A>, C<a>, or C<Z>. Packing with a I<length-item> of C<a> or C<Z> may
5333 introduce C<"\000"> characters, which Perl does not regard as legal in
5338 The integer types C<s>, C<S>, C<l>, and C<L> may be
5339 followed by a C<!> modifier to specify native shorts or
5340 longs. As shown in the example above, a bare C<l> means
5341 exactly 32 bits, although the native C<long> as seen by the local C compiler
5342 may be larger. This is mainly an issue on 64-bit platforms. You can
5343 see whether using C<!> makes any difference this way:
5345 printf "format s is %d, s! is %d\n",
5346 length pack("s"), length pack("s!");
5348 printf "format l is %d, l! is %d\n",
5349 length pack("l"), length pack("l!");
5352 C<i!> and C<I!> are also allowed, but only for completeness' sake:
5353 they are identical to C<i> and C<I>.
5355 The actual sizes (in bytes) of native shorts, ints, longs, and long
5356 longs on the platform where Perl was built are also available from
5359 $ perl -V:{short,int,long{,long}}size
5365 or programmatically via the L<C<Config>|Config> module:
5368 print $Config{shortsize}, "\n";
5369 print $Config{intsize}, "\n";
5370 print $Config{longsize}, "\n";
5371 print $Config{longlongsize}, "\n";
5373 C<$Config{longlongsize}> is undefined on systems without
5378 The integer formats C<s>, C<S>, C<i>, C<I>, C<l>, C<L>, C<j>, and C<J> are
5379 inherently non-portable between processors and operating systems because
5380 they obey native byteorder and endianness. For example, a 4-byte integer
5381 0x12345678 (305419896 decimal) would be ordered natively (arranged in and
5382 handled by the CPU registers) into bytes as
5384 0x12 0x34 0x56 0x78 # big-endian
5385 0x78 0x56 0x34 0x12 # little-endian
5387 Basically, Intel and VAX CPUs are little-endian, while everybody else,
5388 including Motorola m68k/88k, PPC, Sparc, HP PA, Power, and Cray, are
5389 big-endian. Alpha and MIPS can be either: Digital/Compaq uses (well, used)
5390 them in little-endian mode, but SGI/Cray uses them in big-endian mode.
5392 The names I<big-endian> and I<little-endian> are comic references to the
5393 egg-eating habits of the little-endian Lilliputians and the big-endian
5394 Blefuscudians from the classic Jonathan Swift satire, I<Gulliver's Travels>.
5395 This entered computer lingo via the paper "On Holy Wars and a Plea for
5396 Peace" by Danny Cohen, USC/ISI IEN 137, April 1, 1980.
5398 Some systems may have even weirder byte orders such as
5403 These are called mid-endian, middle-endian, mixed-endian, or just weird.
5405 You can determine your system endianness with this incantation:
5407 printf("%#02x ", $_) for unpack("W*", pack L=>0x12345678);
5409 The byteorder on the platform where Perl was built is also available
5413 print "$Config{byteorder}\n";
5415 or from the command line:
5419 Byteorders C<"1234"> and C<"12345678"> are little-endian; C<"4321">
5420 and C<"87654321"> are big-endian. Systems with multiarchitecture binaries
5421 will have C<"ffff">, signifying that static information doesn't work,
5422 one must use runtime probing.
5424 For portably packed integers, either use the formats C<n>, C<N>, C<v>,
5425 and C<V> or else use the C<< > >> and C<< < >> modifiers described
5426 immediately below. See also L<perlport>.
5430 Also floating point numbers have endianness. Usually (but not always)
5431 this agrees with the integer endianness. Even though most platforms
5432 these days use the IEEE 754 binary format, there are differences,
5433 especially if the long doubles are involved. You can see the
5434 C<Config> variables C<doublekind> and C<longdblkind> (also C<doublesize>,
5435 C<longdblsize>): the "kind" values are enums, unlike C<byteorder>.
5437 Portability-wise the best option is probably to keep to the IEEE 754
5438 64-bit doubles, and of agreed-upon endianness. Another possibility
5439 is the C<"%a">) format of L<C<printf>|/printf FILEHANDLE FORMAT, LIST>.
5443 Starting with Perl 5.10.0, integer and floating-point formats, along with
5444 the C<p> and C<P> formats and C<()> groups, may all be followed by the
5445 C<< > >> or C<< < >> endianness modifiers to respectively enforce big-
5446 or little-endian byte-order. These modifiers are especially useful
5447 given how C<n>, C<N>, C<v>, and C<V> don't cover signed integers,
5448 64-bit integers, or floating-point values.
5450 Here are some concerns to keep in mind when using an endianness modifier:
5456 Exchanging signed integers between different platforms works only
5457 when all platforms store them in the same format. Most platforms store
5458 signed integers in two's-complement notation, so usually this is not an issue.
5462 The C<< > >> or C<< < >> modifiers can only be used on floating-point
5463 formats on big- or little-endian machines. Otherwise, attempting to
5464 use them raises an exception.
5468 Forcing big- or little-endian byte-order on floating-point values for
5469 data exchange can work only if all platforms use the same
5470 binary representation such as IEEE floating-point. Even if all
5471 platforms are using IEEE, there may still be subtle differences. Being able
5472 to use C<< > >> or C<< < >> on floating-point values can be useful,
5473 but also dangerous if you don't know exactly what you're doing.
5474 It is not a general way to portably store floating-point values.
5478 When using C<< > >> or C<< < >> on a C<()> group, this affects
5479 all types inside the group that accept byte-order modifiers,
5480 including all subgroups. It is silently ignored for all other
5481 types. You are not allowed to override the byte-order within a group
5482 that already has a byte-order modifier suffix.
5488 Real numbers (floats and doubles) are in native machine format only.
5489 Due to the multiplicity of floating-point formats and the lack of a
5490 standard "network" representation for them, no facility for interchange has been
5491 made. This means that packed floating-point data written on one machine
5492 may not be readable on another, even if both use IEEE floating-point
5493 arithmetic (because the endianness of the memory representation is not part
5494 of the IEEE spec). See also L<perlport>.
5496 If you know I<exactly> what you're doing, you can use the C<< > >> or C<< < >>
5497 modifiers to force big- or little-endian byte-order on floating-point values.
5499 Because Perl uses doubles (or long doubles, if configured) internally for
5500 all numeric calculation, converting from double into float and thence
5501 to double again loses precision, so C<unpack("f", pack("f", $foo)>)
5502 will not in general equal $foo.
5506 Pack and unpack can operate in two modes: character mode (C<C0> mode) where
5507 the packed string is processed per character, and UTF-8 byte mode (C<U0> mode)
5508 where the packed string is processed in its UTF-8-encoded Unicode form on
5509 a byte-by-byte basis. Character mode is the default
5510 unless the format string starts with C<U>. You
5511 can always switch mode mid-format with an explicit
5512 C<C0> or C<U0> in the format. This mode remains in effect until the next
5513 mode change, or until the end of the C<()> group it (directly) applies to.
5515 Using C<C0> to get Unicode characters while using C<U0> to get I<non>-Unicode
5516 bytes is not necessarily obvious. Probably only the first of these
5519 $ perl -CS -E 'say "\x{3B1}\x{3C9}"' |
5520 perl -CS -ne 'printf "%v04X\n", $_ for unpack("C0A*", $_)'
5522 $ perl -CS -E 'say "\x{3B1}\x{3C9}"' |
5523 perl -CS -ne 'printf "%v02X\n", $_ for unpack("U0A*", $_)'
5525 $ perl -CS -E 'say "\x{3B1}\x{3C9}"' |
5526 perl -C0 -ne 'printf "%v02X\n", $_ for unpack("C0A*", $_)'
5528 $ perl -CS -E 'say "\x{3B1}\x{3C9}"' |
5529 perl -C0 -ne 'printf "%v02X\n", $_ for unpack("U0A*", $_)'
5530 C3.8E.C2.B1.C3.8F.C2.89
5532 Those examples also illustrate that you should not try to use
5533 L<C<pack>|/pack TEMPLATE,LIST>/L<C<unpack>|/unpack TEMPLATE,EXPR> as a
5534 substitute for the L<Encode> module.
5538 You must yourself do any alignment or padding by inserting, for example,
5539 enough C<"x">es while packing. There is no way for
5540 L<C<pack>|/pack TEMPLATE,LIST> and L<C<unpack>|/unpack TEMPLATE,EXPR>
5541 to know where characters are going to or coming from, so they
5542 handle their output and input as flat sequences of characters.
5546 A C<()> group is a sub-TEMPLATE enclosed in parentheses. A group may
5547 take a repeat count either as postfix, or for
5548 L<C<unpack>|/unpack TEMPLATE,EXPR>, also via the C</>
5549 template character. Within each repetition of a group, positioning with
5550 C<@> starts over at 0. Therefore, the result of
5552 pack("@1A((@2A)@3A)", qw[X Y Z])
5554 is the string C<"\0X\0\0YZ">.
5558 C<x> and C<X> accept the C<!> modifier to act as alignment commands: they
5559 jump forward or back to the closest position aligned at a multiple of C<count>
5560 characters. For example, to L<C<pack>|/pack TEMPLATE,LIST> or
5561 L<C<unpack>|/unpack TEMPLATE,EXPR> a C structure like
5564 char c; /* one signed, 8-bit character */
5569 one may need to use the template C<c x![d] d c[2]>. This assumes that
5570 doubles must be aligned to the size of double.
5572 For alignment commands, a C<count> of 0 is equivalent to a C<count> of 1;
5577 C<n>, C<N>, C<v> and C<V> accept the C<!> modifier to
5578 represent signed 16-/32-bit integers in big-/little-endian order.
5579 This is portable only when all platforms sharing packed data use the
5580 same binary representation for signed integers; for example, when all
5581 platforms use two's-complement representation.
5585 Comments can be embedded in a TEMPLATE using C<#> through the end of line.
5586 White space can separate pack codes from each other, but modifiers and
5587 repeat counts must follow immediately. Breaking complex templates into
5588 individual line-by-line components, suitably annotated, can do as much to
5589 improve legibility and maintainability of pack/unpack formats as C</x> can
5590 for complicated pattern matches.
5594 If TEMPLATE requires more arguments than L<C<pack>|/pack TEMPLATE,LIST>
5595 is given, L<C<pack>|/pack TEMPLATE,LIST>
5596 assumes additional C<""> arguments. If TEMPLATE requires fewer arguments
5597 than given, extra arguments are ignored.
5601 Attempting to pack the special floating point values C<Inf> and C<NaN>
5602 (infinity, also in negative, and not-a-number) into packed integer values
5603 (like C<"L">) is a fatal error. The reason for this is that there simply
5604 isn't any sensible mapping for these special values into integers.
5610 $foo = pack("WWWW",65,66,67,68);
5612 $foo = pack("W4",65,66,67,68);
5614 $foo = pack("W4",0x24b6,0x24b7,0x24b8,0x24b9);
5615 # same thing with Unicode circled letters.
5616 $foo = pack("U4",0x24b6,0x24b7,0x24b8,0x24b9);
5617 # same thing with Unicode circled letters. You don't get the
5618 # UTF-8 bytes because the U at the start of the format caused
5619 # a switch to U0-mode, so the UTF-8 bytes get joined into
5621 $foo = pack("C0U4",0x24b6,0x24b7,0x24b8,0x24b9);
5622 # foo eq "\xe2\x92\xb6\xe2\x92\xb7\xe2\x92\xb8\xe2\x92\xb9"
5623 # This is the UTF-8 encoding of the string in the
5626 $foo = pack("ccxxcc",65,66,67,68);
5629 # NOTE: The examples above featuring "W" and "c" are true
5630 # only on ASCII and ASCII-derived systems such as ISO Latin 1
5631 # and UTF-8. On EBCDIC systems, the first example would be
5632 # $foo = pack("WWWW",193,194,195,196);
5634 $foo = pack("s2",1,2);
5635 # "\001\000\002\000" on little-endian
5636 # "\000\001\000\002" on big-endian
5638 $foo = pack("a4","abcd","x","y","z");
5641 $foo = pack("aaaa","abcd","x","y","z");
5644 $foo = pack("a14","abcdefg");
5645 # "abcdefg\0\0\0\0\0\0\0"
5647 $foo = pack("i9pl", gmtime);
5648 # a real struct tm (on my system anyway)
5650 $utmp_template = "Z8 Z8 Z16 L";
5651 $utmp = pack($utmp_template, @utmp1);
5652 # a struct utmp (BSDish)
5654 @utmp2 = unpack($utmp_template, $utmp);
5655 # "@utmp1" eq "@utmp2"
5658 unpack("N", pack("B32", substr("0" x 32 . shift, -32)));
5661 $foo = pack('sx2l', 12, 34);
5662 # short 12, two zero bytes padding, long 34
5663 $bar = pack('s@4l', 12, 34);
5664 # short 12, zero fill to position 4, long 34
5666 $baz = pack('s.l', 12, 4, 34);
5667 # short 12, zero fill to position 4, long 34
5669 $foo = pack('nN', 42, 4711);
5670 # pack big-endian 16- and 32-bit unsigned integers
5671 $foo = pack('S>L>', 42, 4711);
5673 $foo = pack('s<l<', -42, 4711);
5674 # pack little-endian 16- and 32-bit signed integers
5675 $foo = pack('(sl)<', -42, 4711);
5678 The same template may generally also be used in
5679 L<C<unpack>|/unpack TEMPLATE,EXPR>.
5681 =item package NAMESPACE
5683 =item package NAMESPACE VERSION
5684 X<package> X<module> X<namespace> X<version>
5686 =item package NAMESPACE BLOCK
5688 =item package NAMESPACE VERSION BLOCK
5689 X<package> X<module> X<namespace> X<version>
5691 =for Pod::Functions declare a separate global namespace
5693 Declares the BLOCK or the rest of the compilation unit as being in the
5694 given namespace. The scope of the package declaration is either the
5695 supplied code BLOCK or, in the absence of a BLOCK, from the declaration
5696 itself through the end of current scope (the enclosing block, file, or
5697 L<C<eval>|/eval EXPR>). That is, the forms without a BLOCK are
5698 operative through the end of the current scope, just like the
5699 L<C<my>|/my VARLIST>, L<C<state>|/state VARLIST>, and
5700 L<C<our>|/our VARLIST> operators. All unqualified dynamic identifiers
5701 in this scope will be in the given namespace, except where overridden by
5702 another L<C<package>|/package NAMESPACE> declaration or
5703 when they're one of the special identifiers that qualify into C<main::>,
5704 like C<STDOUT>, C<ARGV>, C<ENV>, and the punctuation variables.
5706 A package statement affects dynamic variables only, including those
5707 you've used L<C<local>|/local EXPR> on, but I<not> lexically-scoped
5708 variables, which are created with L<C<my>|/my VARLIST>,
5709 L<C<state>|/state VARLIST>, or L<C<our>|/our VARLIST>. Typically it
5710 would be the first declaration in a file included by
5711 L<C<require>|/require VERSION> or L<C<use>|/use Module VERSION LIST>.
5712 You can switch into a
5713 package in more than one place, since this only determines which default
5714 symbol table the compiler uses for the rest of that block. You can refer to
5715 identifiers in other packages than the current one by prefixing the identifier
5716 with the package name and a double colon, as in C<$SomePack::var>
5717 or C<ThatPack::INPUT_HANDLE>. If package name is omitted, the C<main>
5718 package as assumed. That is, C<$::sail> is equivalent to
5719 C<$main::sail> (as well as to C<$main'sail>, still seen in ancient
5720 code, mostly from Perl 4).
5722 If VERSION is provided, L<C<package>|/package NAMESPACE> sets the
5723 C<$VERSION> variable in the given
5724 namespace to a L<version> object with the VERSION provided. VERSION must be a
5725 "strict" style version number as defined by the L<version> module: a positive
5726 decimal number (integer or decimal-fraction) without exponentiation or else a
5727 dotted-decimal v-string with a leading 'v' character and at least three
5728 components. You should set C<$VERSION> only once per package.
5730 See L<perlmod/"Packages"> for more information about packages, modules,
5731 and classes. See L<perlsub> for other scoping issues.
5736 =for Pod::Functions +5.004 the current package
5738 A special token that returns the name of the package in which it occurs.
5740 =item pipe READHANDLE,WRITEHANDLE
5743 =for Pod::Functions open a pair of connected filehandles
5745 Opens a pair of connected pipes like the corresponding system call.
5746 Note that if you set up a loop of piped processes, deadlock can occur
5747 unless you are very careful. In addition, note that Perl's pipes use
5748 IO buffering, so you may need to set L<C<$E<verbar>>|perlvar/$E<verbar>>
5749 to flush your WRITEHANDLE after each command, depending on the
5752 Returns true on success.
5754 See L<IPC::Open2>, L<IPC::Open3>, and
5755 L<perlipc/"Bidirectional Communication with Another Process">
5756 for examples of such things.
5758 On systems that support a close-on-exec flag on files, that flag is set
5759 on all newly opened file descriptors whose
5760 L<C<fileno>|/fileno FILEHANDLE>s are I<higher> than the current value of
5761 L<C<$^F>|perlvar/$^F> (by default 2 for C<STDERR>). See L<perlvar/$^F>.
5768 =for Pod::Functions remove the last element from an array and return it
5770 Pops and returns the last value of the array, shortening the array by
5773 Returns the undefined value if the array is empty, although this may
5774 also happen at other times. If ARRAY is omitted, pops the
5775 L<C<@ARGV>|perlvar/@ARGV> array in the main program, but the
5776 L<C<@_>|perlvar/@_> array in subroutines, just like
5777 L<C<shift>|/shift ARRAY>.
5779 Starting with Perl 5.14, an experimental feature allowed
5780 L<C<pop>|/pop ARRAY> to take a
5781 scalar expression. This experiment has been deemed unsuccessful, and was
5782 removed as of Perl 5.24.
5785 X<pos> X<match, position>
5789 =for Pod::Functions find or set the offset for the last/next m//g search
5791 Returns the offset of where the last C<m//g> search left off for the
5792 variable in question (L<C<$_>|perlvar/$_> is used when the variable is not
5793 specified). This offset is in characters unless the
5794 (no-longer-recommended) L<C<use bytes>|bytes> pragma is in effect, in
5795 which case the offset is in bytes. Note that 0 is a valid match offset.
5796 L<C<undef>|/undef EXPR> indicates
5797 that the search position is reset (usually due to match failure, but
5798 can also be because no match has yet been run on the scalar).
5800 L<C<pos>|/pos SCALAR> directly accesses the location used by the regexp
5801 engine to store the offset, so assigning to L<C<pos>|/pos SCALAR> will
5802 change that offset, and so will also influence the C<\G> zero-width
5803 assertion in regular expressions. Both of these effects take place for
5804 the next match, so you can't affect the position with
5805 L<C<pos>|/pos SCALAR> during the current match, such as in
5806 C<(?{pos() = 5})> or C<s//pos() = 5/e>.
5808 Setting L<C<pos>|/pos SCALAR> also resets the I<matched with
5809 zero-length> flag, described
5810 under L<perlre/"Repeated Patterns Matching a Zero-length Substring">.
5812 Because a failed C<m//gc> match doesn't reset the offset, the return
5813 from L<C<pos>|/pos SCALAR> won't change either in this case. See
5814 L<perlre> and L<perlop>.
5816 =item print FILEHANDLE LIST
5819 =item print FILEHANDLE
5825 =for Pod::Functions output a list to a filehandle
5827 Prints a string or a list of strings. Returns true if successful.
5828 FILEHANDLE may be a scalar variable containing the name of or a reference
5829 to the filehandle, thus introducing one level of indirection. (NOTE: If
5830 FILEHANDLE is a variable and the next token is a term, it may be
5831 misinterpreted as an operator unless you interpose a C<+> or put
5832 parentheses around the arguments.) If FILEHANDLE is omitted, prints to the
5833 last selected (see L<C<select>|/select FILEHANDLE>) output handle. If
5834 LIST is omitted, prints L<C<$_>|perlvar/$_> to the currently selected
5835 output handle. To use FILEHANDLE alone to print the content of
5836 L<C<$_>|perlvar/$_> to it, you must use a bareword filehandle like
5837 C<FH>, not an indirect one like C<$fh>. To set the default output handle
5838 to something other than STDOUT, use the select operation.
5840 The current value of L<C<$,>|perlvar/$,> (if any) is printed between
5841 each LIST item. The current value of L<C<$\>|perlvar/$\> (if any) is
5842 printed after the entire LIST has been printed. Because print takes a
5843 LIST, anything in the LIST is evaluated in list context, including any
5844 subroutines whose return lists you pass to
5845 L<C<print>|/print FILEHANDLE LIST>. Be careful not to follow the print
5847 parenthesis unless you want the corresponding right parenthesis to
5848 terminate the arguments to the print; put parentheses around all arguments
5849 (or interpose a C<+>, but that doesn't look as good).
5851 If you're storing handles in an array or hash, or in general whenever
5852 you're using any expression more complex than a bareword handle or a plain,
5853 unsubscripted scalar variable to retrieve it, you will have to use a block
5854 returning the filehandle value instead, in which case the LIST may not be
5857 print { $files[$i] } "stuff\n";
5858 print { $OK ? *STDOUT : *STDERR } "stuff\n";
5860 Printing to a closed pipe or socket will generate a SIGPIPE signal. See
5861 L<perlipc> for more on signal handling.
5863 =item printf FILEHANDLE FORMAT, LIST
5866 =item printf FILEHANDLE
5868 =item printf FORMAT, LIST
5872 =for Pod::Functions output a formatted list to a filehandle
5874 Equivalent to C<print FILEHANDLE sprintf(FORMAT, LIST)>, except that
5875 L<C<$\>|perlvar/$\> (the output record separator) is not appended. The
5876 FORMAT and the LIST are actually parsed as a single list. The first
5877 argument of the list will be interpreted as the
5878 L<C<printf>|/printf FILEHANDLE FORMAT, LIST> format. This means that
5879 C<printf(@_)> will use C<$_[0]> as the format. See
5880 L<sprintf|/sprintf FORMAT, LIST> for an explanation of the format
5881 argument. If C<use locale> (including C<use locale ':not_characters'>)
5882 is in effect and L<C<POSIX::setlocale>|POSIX/C<setlocale>> has been
5883 called, the character used for the decimal separator in formatted
5884 floating-point numbers is affected by the C<LC_NUMERIC> locale setting.
5885 See L<perllocale> and L<POSIX>.
5887 For historical reasons, if you omit the list, L<C<$_>|perlvar/$_> is
5889 to use FILEHANDLE without a list, you must use a bareword filehandle like
5890 C<FH>, not an indirect one like C<$fh>. However, this will rarely do what
5891 you want; if L<C<$_>|perlvar/$_> contains formatting codes, they will be
5892 replaced with the empty string and a warning will be emitted if
5893 L<warnings> are enabled. Just use L<C<print>|/print FILEHANDLE LIST> if
5894 you want to print the contents of L<C<$_>|perlvar/$_>.
5896 Don't fall into the trap of using a
5897 L<C<printf>|/printf FILEHANDLE FORMAT, LIST> when a simple
5898 L<C<print>|/print FILEHANDLE LIST> would do. The
5899 L<C<print>|/print FILEHANDLE LIST> is more efficient and less error
5902 =item prototype FUNCTION
5907 =for Pod::Functions +5.002 get the prototype (if any) of a subroutine
5909 Returns the prototype of a function as a string (or
5910 L<C<undef>|/undef EXPR> if the
5911 function has no prototype). FUNCTION is a reference to, or the name of,
5912 the function whose prototype you want to retrieve. If FUNCTION is omitted,
5913 L<C<$_>|perlvar/$_> is used.
5915 If FUNCTION is a string starting with C<CORE::>, the rest is taken as a
5916 name for a Perl builtin. If the builtin's arguments
5917 cannot be adequately expressed by a prototype
5918 (such as L<C<system>|/system LIST>), L<C<prototype>|/prototype FUNCTION>
5919 returns L<C<undef>|/undef EXPR>, because the builtin
5920 does not really behave like a Perl function. Otherwise, the string
5921 describing the equivalent prototype is returned.
5923 =item push ARRAY,LIST
5926 =for Pod::Functions append one or more elements to an array
5928 Treats ARRAY as a stack by appending the values of LIST to the end of
5929 ARRAY. The length of ARRAY increases by the length of LIST. Has the same
5932 for my $value (LIST) {
5933 $ARRAY[++$#ARRAY] = $value;
5936 but is more efficient. Returns the number of elements in the array following
5937 the completed L<C<push>|/push ARRAY,LIST>.
5939 Starting with Perl 5.14, an experimental feature allowed
5940 L<C<push>|/push ARRAY,LIST> to take a
5941 scalar expression. This experiment has been deemed unsuccessful, and was
5942 removed as of Perl 5.24.
5946 =for Pod::Functions singly quote a string
5950 =for Pod::Functions doubly quote a string
5954 =for Pod::Functions quote a list of words
5958 =for Pod::Functions backquote quote a string
5960 Generalized quotes. See L<perlop/"Quote-Like Operators">.
5964 =for Pod::Functions +5.005 compile pattern
5966 Regexp-like quote. See L<perlop/"Regexp Quote-Like Operators">.
5968 =item quotemeta EXPR
5969 X<quotemeta> X<metacharacter>
5973 =for Pod::Functions quote regular expression magic characters
5975 Returns the value of EXPR with all the ASCII non-"word"
5976 characters backslashed. (That is, all ASCII characters not matching
5977 C</[A-Za-z_0-9]/> will be preceded by a backslash in the
5978 returned string, regardless of any locale settings.)
5979 This is the internal function implementing
5980 the C<\Q> escape in double-quoted strings.
5981 (See below for the behavior on non-ASCII code points.)
5983 If EXPR is omitted, uses L<C<$_>|perlvar/$_>.
5985 quotemeta (and C<\Q> ... C<\E>) are useful when interpolating strings into
5986 regular expressions, because by default an interpolated variable will be
5987 considered a mini-regular expression. For example:
5989 my $sentence = 'The quick brown fox jumped over the lazy dog';
5990 my $substring = 'quick.*?fox';
5991 $sentence =~ s{$substring}{big bad wolf};
5993 Will cause C<$sentence> to become C<'The big bad wolf jumped over...'>.
5997 my $sentence = 'The quick brown fox jumped over the lazy dog';
5998 my $substring = 'quick.*?fox';
5999 $sentence =~ s{\Q$substring\E}{big bad wolf};
6003 my $sentence = 'The quick brown fox jumped over the lazy dog';
6004 my $substring = 'quick.*?fox';
6005 my $quoted_substring = quotemeta($substring);
6006 $sentence =~ s{$quoted_substring}{big bad wolf};
6008 Will both leave the sentence as is.
6009 Normally, when accepting literal string input from the user,
6010 L<C<quotemeta>|/quotemeta EXPR> or C<\Q> must be used.
6012 In Perl v5.14, all non-ASCII characters are quoted in non-UTF-8-encoded
6013 strings, but not quoted in UTF-8 strings.
6015 Starting in Perl v5.16, Perl adopted a Unicode-defined strategy for
6016 quoting non-ASCII characters; the quoting of ASCII characters is
6019 Also unchanged is the quoting of non-UTF-8 strings when outside the
6021 L<C<use feature 'unicode_strings'>|feature/The 'unicode_strings' feature>,
6022 which is to quote all
6023 characters in the upper Latin1 range. This provides complete backwards
6024 compatibility for old programs which do not use Unicode. (Note that
6025 C<unicode_strings> is automatically enabled within the scope of a
6026 S<C<use v5.12>> or greater.)
6028 Within the scope of L<C<use locale>|locale>, all non-ASCII Latin1 code
6030 are quoted whether the string is encoded as UTF-8 or not. As mentioned
6031 above, locale does not affect the quoting of ASCII-range characters.
6032 This protects against those locales where characters such as C<"|"> are
6033 considered to be word characters.
6035 Otherwise, Perl quotes non-ASCII characters using an adaptation from
6036 Unicode (see L<http://www.unicode.org/reports/tr31/>).
6037 The only code points that are quoted are those that have any of the
6038 Unicode properties: Pattern_Syntax, Pattern_White_Space, White_Space,
6039 Default_Ignorable_Code_Point, or General_Category=Control.
6041 Of these properties, the two important ones are Pattern_Syntax and
6042 Pattern_White_Space. They have been set up by Unicode for exactly this
6043 purpose of deciding which characters in a regular expression pattern
6044 should be quoted. No character that can be in an identifier has these
6047 Perl promises, that if we ever add regular expression pattern
6048 metacharacters to the dozen already defined
6049 (C<\ E<verbar> ( ) [ { ^ $ * + ? .>), that we will only use ones that have the
6050 Pattern_Syntax property. Perl also promises, that if we ever add
6051 characters that are considered to be white space in regular expressions
6052 (currently mostly affected by C</x>), they will all have the
6053 Pattern_White_Space property.
6055 Unicode promises that the set of code points that have these two
6056 properties will never change, so something that is not quoted in v5.16
6057 will never need to be quoted in any future Perl release. (Not all the
6058 code points that match Pattern_Syntax have actually had characters
6059 assigned to them; so there is room to grow, but they are quoted
6060 whether assigned or not. Perl, of course, would never use an
6061 unassigned code point as an actual metacharacter.)
6063 Quoting characters that have the other 3 properties is done to enhance
6064 the readability of the regular expression and not because they actually
6065 need to be quoted for regular expression purposes (characters with the
6066 White_Space property are likely to be indistinguishable on the page or
6067 screen from those with the Pattern_White_Space property; and the other
6068 two properties contain non-printing characters).
6075 =for Pod::Functions retrieve the next pseudorandom number
6077 Returns a random fractional number greater than or equal to C<0> and less
6078 than the value of EXPR. (EXPR should be positive.) If EXPR is
6079 omitted, the value C<1> is used. Currently EXPR with the value C<0> is
6080 also special-cased as C<1> (this was undocumented before Perl 5.8.0
6081 and is subject to change in future versions of Perl). Automatically calls
6082 L<C<srand>|/srand EXPR> unless L<C<srand>|/srand EXPR> has already been
6083 called. See also L<C<srand>|/srand EXPR>.
6085 Apply L<C<int>|/int EXPR> to the value returned by L<C<rand>|/rand EXPR>
6086 if you want random integers instead of random fractional numbers. For
6091 returns a random integer between C<0> and C<9>, inclusive.
6093 (Note: If your rand function consistently returns numbers that are too
6094 large or too small, then your version of Perl was probably compiled
6095 with the wrong number of RANDBITS.)
6097 B<L<C<rand>|/rand EXPR> is not cryptographically secure. You should not rely
6098 on it in security-sensitive situations.> As of this writing, a
6099 number of third-party CPAN modules offer random number generators
6100 intended by their authors to be cryptographically secure,
6101 including: L<Data::Entropy>, L<Crypt::Random>, L<Math::Random::Secure>,
6102 and L<Math::TrulyRandom>.
6104 =item read FILEHANDLE,SCALAR,LENGTH,OFFSET
6105 X<read> X<file, read>
6107 =item read FILEHANDLE,SCALAR,LENGTH
6109 =for Pod::Functions fixed-length buffered input from a filehandle
6111 Attempts to read LENGTH I<characters> of data into variable SCALAR
6112 from the specified FILEHANDLE. Returns the number of characters
6113 actually read, C<0> at end of file, or undef if there was an error (in
6114 the latter case L<C<$!>|perlvar/$!> is also set). SCALAR will be grown
6116 so that the last character actually read is the last character of the
6117 scalar after the read.
6119 An OFFSET may be specified to place the read data at some place in the
6120 string other than the beginning. A negative OFFSET specifies
6121 placement at that many characters counting backwards from the end of
6122 the string. A positive OFFSET greater than the length of SCALAR
6123 results in the string being padded to the required size with C<"\0">
6124 bytes before the result of the read is appended.
6126 The call is implemented in terms of either Perl's or your system's native
6127 L<fread(3)> library function. To get a true L<read(2)> system call, see
6128 L<sysread|/sysread FILEHANDLE,SCALAR,LENGTH,OFFSET>.
6130 Note the I<characters>: depending on the status of the filehandle,
6131 either (8-bit) bytes or characters are read. By default, all
6132 filehandles operate on bytes, but for example if the filehandle has
6133 been opened with the C<:utf8> I/O layer (see
6134 L<C<open>|/open FILEHANDLE,EXPR>, and the L<open>
6135 pragma), the I/O will operate on UTF8-encoded Unicode
6136 characters, not bytes. Similarly for the C<:encoding> layer:
6137 in that case pretty much any characters can be read.
6139 =item readdir DIRHANDLE
6142 =for Pod::Functions get a directory from a directory handle
6144 Returns the next directory entry for a directory opened by
6145 L<C<opendir>|/opendir DIRHANDLE,EXPR>.
6146 If used in list context, returns all the rest of the entries in the
6147 directory. If there are no more entries, returns the undefined value in
6148 scalar context and the empty list in list context.
6150 If you're planning to filetest the return values out of a
6151 L<C<readdir>|/readdir DIRHANDLE>, you'd better prepend the directory in
6152 question. Otherwise, because we didn't L<C<chdir>|/chdir EXPR> there,
6153 it would have been testing the wrong file.
6155 opendir(my $dh, $some_dir) || die "Can't opendir $some_dir: $!";
6156 my @dots = grep { /^\./ && -f "$some_dir/$_" } readdir($dh);
6159 As of Perl 5.12 you can use a bare L<C<readdir>|/readdir DIRHANDLE> in a
6160 C<while> loop, which will set L<C<$_>|perlvar/$_> on every iteration.
6161 If either a C<readdir> expression or an explicit assignment of a
6162 C<readdir> expression to a scalar is used as a C<while>/C<for> condition,
6163 then the condition actually tests for definedness of the expression's
6164 value, not for its regular truth value.
6166 opendir(my $dh, $some_dir) || die "Can't open $some_dir: $!";
6167 while (readdir $dh) {
6168 print "$some_dir/$_\n";
6172 To avoid confusing would-be users of your code who are running earlier
6173 versions of Perl with mysterious failures, put this sort of thing at the
6174 top of your file to signal that your code will work I<only> on Perls of a
6177 use 5.012; # so readdir assigns to $_ in a lone while test
6182 X<readline> X<gets> X<fgets>
6184 =for Pod::Functions fetch a record from a file
6186 Reads from the filehandle whose typeglob is contained in EXPR (or from
6187 C<*ARGV> if EXPR is not provided). In scalar context, each call reads and
6188 returns the next line until end-of-file is reached, whereupon the
6189 subsequent call returns L<C<undef>|/undef EXPR>. In list context, reads
6190 until end-of-file is reached and returns a list of lines. Note that the
6191 notion of "line" used here is whatever you may have defined with
6192 L<C<$E<sol>>|perlvar/$E<sol>> (or C<$INPUT_RECORD_SEPARATOR> in
6193 L<English>). See L<perlvar/"$/">.
6195 When L<C<$E<sol>>|perlvar/$E<sol>> is set to L<C<undef>|/undef EXPR>,
6196 when L<C<readline>|/readline EXPR> is in scalar context (i.e., file
6197 slurp mode), and when an empty file is read, it returns C<''> the first
6198 time, followed by L<C<undef>|/undef EXPR> subsequently.
6200 This is the internal function implementing the C<< <EXPR> >>
6201 operator, but you can use it directly. The C<< <EXPR> >>
6202 operator is discussed in more detail in L<perlop/"I/O Operators">.
6205 my $line = readline(STDIN); # same thing
6207 If L<C<readline>|/readline EXPR> encounters an operating system error,
6208 L<C<$!>|perlvar/$!> will be set with the corresponding error message.
6209 It can be helpful to check L<C<$!>|perlvar/$!> when you are reading from
6210 filehandles you don't trust, such as a tty or a socket. The following
6211 example uses the operator form of L<C<readline>|/readline EXPR> and dies
6212 if the result is not defined.
6214 while ( ! eof($fh) ) {
6215 defined( $_ = readline $fh ) or die "readline failed: $!";
6219 Note that you have can't handle L<C<readline>|/readline EXPR> errors
6220 that way with the C<ARGV> filehandle. In that case, you have to open
6221 each element of L<C<@ARGV>|perlvar/@ARGV> yourself since
6222 L<C<eof>|/eof FILEHANDLE> handles C<ARGV> differently.
6224 foreach my $arg (@ARGV) {
6225 open(my $fh, $arg) or warn "Can't open $arg: $!";
6227 while ( ! eof($fh) ) {
6228 defined( $_ = readline $fh )
6229 or die "readline failed for $arg: $!";
6234 Like the C<< <EXPR> >> operator, if a C<readline> expression is
6235 used as the condition of a C<while> or C<for> loop, then it will be
6236 implicitly assigned to C<$_>. If either a C<readline> expression or
6237 an explicit assignment of a C<readline> expression to a scalar is used
6238 as a C<while>/C<for> condition, then the condition actually tests for
6239 definedness of the expression's value, not for its regular truth value.
6246 =for Pod::Functions determine where a symbolic link is pointing
6248 Returns the value of a symbolic link, if symbolic links are
6249 implemented. If not, raises an exception. If there is a system
6250 error, returns the undefined value and sets L<C<$!>|perlvar/$!> (errno).
6251 If EXPR is omitted, uses L<C<$_>|perlvar/$_>.
6253 Portability issues: L<perlport/readlink>.
6260 =for Pod::Functions execute a system command and collect standard output
6262 EXPR is executed as a system command.
6263 The collected standard output of the command is returned.
6264 In scalar context, it comes back as a single (potentially
6265 multi-line) string. In list context, returns a list of lines
6266 (however you've defined lines with L<C<$E<sol>>|perlvar/$E<sol>> (or
6267 C<$INPUT_RECORD_SEPARATOR> in L<English>)).
6268 This is the internal function implementing the C<qx/EXPR/>
6269 operator, but you can use it directly. The C<qx/EXPR/>
6270 operator is discussed in more detail in L<perlop/"I/O Operators">.
6271 If EXPR is omitted, uses L<C<$_>|perlvar/$_>.
6273 =item recv SOCKET,SCALAR,LENGTH,FLAGS
6276 =for Pod::Functions receive a message over a Socket
6278 Receives a message on a socket. Attempts to receive LENGTH characters
6279 of data into variable SCALAR from the specified SOCKET filehandle.
6280 SCALAR will be grown or shrunk to the length actually read. Takes the
6281 same flags as the system call of the same name. Returns the address
6282 of the sender if SOCKET's protocol supports this; returns an empty
6283 string otherwise. If there's an error, returns the undefined value.
6284 This call is actually implemented in terms of the L<recvfrom(2)> system call.
6285 See L<perlipc/"UDP: Message Passing"> for examples.
6287 Note that if the socket has been marked as C<:utf8>, C<recv> will
6288 throw an exception. The C<:encoding(...)> layer implicitly introduces
6289 the C<:utf8> layer. See L<C<binmode>|/binmode FILEHANDLE, LAYER>.
6298 =for Pod::Functions start this loop iteration over again
6300 The L<C<redo>|/redo LABEL> command restarts the loop block without
6301 evaluating the conditional again. The L<C<continue>|/continue BLOCK>
6302 block, if any, is not executed. If
6303 the LABEL is omitted, the command refers to the innermost enclosing
6304 loop. The C<redo EXPR> form, available starting in Perl 5.18.0, allows a
6305 label name to be computed at run time, and is otherwise identical to C<redo
6306 LABEL>. Programs that want to lie to themselves about what was just input
6307 normally use this command:
6309 # a simpleminded Pascal comment stripper
6310 # (warning: assumes no { or } in strings)
6311 LINE: while (<STDIN>) {
6312 while (s|({.*}.*){.*}|$1 |) {}
6317 if (/}/) { # end of comment?
6326 L<C<redo>|/redo LABEL> cannot return a value from a block that typically
6327 returns a value, such as C<eval {}>, C<sub {}>, or C<do {}>. It will perform
6328 its flow control behavior, which precludes any return value. It should not be
6329 used to exit a L<C<grep>|/grep BLOCK LIST> or L<C<map>|/map BLOCK LIST>
6332 Note that a block by itself is semantically identical to a loop
6333 that executes once. Thus L<C<redo>|/redo LABEL> inside such a block
6334 will effectively turn it into a looping construct.
6336 See also L<C<continue>|/continue BLOCK> for an illustration of how
6337 L<C<last>|/last LABEL>, L<C<next>|/next LABEL>, and
6338 L<C<redo>|/redo LABEL> work.
6340 Unlike most named operators, this has the same precedence as assignment.
6341 It is also exempt from the looks-like-a-function rule, so
6342 C<redo ("foo")."bar"> will cause "bar" to be part of the argument to
6343 L<C<redo>|/redo LABEL>.
6350 =for Pod::Functions find out the type of thing being referenced
6352 Examines the value of EXPR, expecting it to be a reference, and returns
6353 a string giving information about the reference and the type of referent.
6354 If EXPR is not specified, L<C<$_>|perlvar/$_> will be used.
6356 If the operand is not a reference, then the empty string will be returned.
6357 An empty string will only be returned in this situation. C<ref> is often
6358 useful to just test whether a value is a reference, which can be done
6359 by comparing the result to the empty string. It is a common mistake
6360 to use the result of C<ref> directly as a truth value: this goes wrong
6361 because C<0> (which is false) can be returned for a reference.
6363 If the operand is a reference to a blessed object, then the name of
6364 the class into which the referent is blessed will be returned. C<ref>
6365 doesn't care what the physical type of the referent is; blessing takes
6366 precedence over such concerns. Beware that exact comparison of C<ref>
6367 results against a class name doesn't perform a class membership test:
6368 a class's members also include objects blessed into subclasses, for
6369 which C<ref> will return the name of the subclass. Also beware that
6370 class names can clash with the built-in type names (described below).
6372 If the operand is a reference to an unblessed object, then the return
6373 value indicates the type of object. If the unblessed referent is not
6374 a scalar, then the return value will be one of the strings C<ARRAY>,
6375 C<HASH>, C<CODE>, C<FORMAT>, or C<IO>, indicating only which kind of
6376 object it is. If the unblessed referent is a scalar, then the return
6377 value will be one of the strings C<SCALAR>, C<VSTRING>, C<REF>, C<GLOB>,
6378 C<LVALUE>, or C<REGEXP>, depending on the kind of value the scalar
6379 currently has. Beware that these built-in type names can also be used as
6380 class names, so C<ref> returning one of these names doesn't unambiguously
6381 indicate that the referent is of the kind to which the name refers.
6383 The ambiguity between built-in type names and class names significantly
6384 limits the utility of C<ref>. For unambiguous information, use
6385 L<C<Scalar::Util::blessed()>|Scalar::Util/blessed> for information about
6386 blessing, and L<C<Scalar::Util::reftype()>|Scalar::Util/reftype> for
6387 information about physical types. Use L<the C<isa> method|UNIVERSAL/C<<
6388 $obj->isa( TYPE ) >>> for class membership tests, though one must be
6389 sure of blessedness before attempting a method call.
6391 See also L<perlref> and L<perlobj>.
6393 =item rename OLDNAME,NEWNAME
6394 X<rename> X<move> X<mv> X<ren>
6396 =for Pod::Functions change a filename
6398 Changes the name of a file; an existing file NEWNAME will be
6399 clobbered. Returns true for success, false otherwise.
6401 Behavior of this function varies wildly depending on your system
6402 implementation. For example, it will usually not work across file system
6403 boundaries, even though the system I<mv> command sometimes compensates
6404 for this. Other restrictions include whether it works on directories,
6405 open files, or pre-existing files. Check L<perlport> and either the
6406 L<rename(2)> manpage or equivalent system documentation for details.
6408 For a platform independent L<C<move>|File::Copy/move> function look at
6409 the L<File::Copy> module.
6411 Portability issues: L<perlport/rename>.
6413 =item require VERSION
6420 =for Pod::Functions load in external functions from a library at runtime
6422 Demands a version of Perl specified by VERSION, or demands some semantics
6423 specified by EXPR or by L<C<$_>|perlvar/$_> if EXPR is not supplied.
6425 VERSION may be either a literal such as v5.24.1, which will be
6426 compared to L<C<$^V>|perlvar/$^V> (or C<$PERL_VERSION> in L<English>),
6427 or a numeric argument of the form 5.024001, which will be compared to
6428 L<C<$]>|perlvar/$]>. An exception is raised if VERSION is greater than
6429 the version of the current Perl interpreter. Compare with
6430 L<C<use>|/use Module VERSION LIST>, which can do a similar check at
6433 Specifying VERSION as a numeric argument of the form 5.024001 should
6434 generally be avoided as older less readable syntax compared to
6435 v5.24.1. Before perl 5.8.0 (released in 2002), the more verbose numeric
6436 form was the only supported syntax, which is why you might see it in
6439 require v5.24.1; # run time version check
6440 require 5.24.1; # ditto
6441 require 5.024_001; # ditto; older syntax compatible
6444 Otherwise, L<C<require>|/require VERSION> demands that a library file be
6445 included if it hasn't already been included. The file is included via
6446 the do-FILE mechanism, which is essentially just a variety of
6447 L<C<eval>|/eval EXPR> with the
6448 caveat that lexical variables in the invoking script will be invisible
6449 to the included code. If it were implemented in pure Perl, it
6450 would have semantics similar to the following:
6456 my ($filename) = @_;
6457 if ( my $version = eval { version->parse($filename) } ) {
6458 if ( $version > $^V ) {
6459 my $vn = $version->normal;
6460 croak "Perl $vn required--this is only $^V, stopped";
6465 if (exists $INC{$filename}) {
6466 return 1 if $INC{$filename};
6467 croak "Compilation failed in require";
6470 foreach $prefix (@INC) {
6472 #... do other stuff - see text below ....
6474 # (see text below about possible appending of .pmc
6475 # suffix to $filename)
6476 my $realfilename = "$prefix/$filename";
6477 next if ! -e $realfilename || -d _ || -b _;
6478 $INC{$filename} = $realfilename;
6479 my $result = do($realfilename);
6480 # but run in caller's namespace
6482 if (!defined $result) {
6483 $INC{$filename} = undef;
6484 croak $@ ? "$@Compilation failed in require"
6485 : "Can't locate $filename: $!\n";
6488 delete $INC{$filename};
6489 croak "$filename did not return true value";
6494 croak "Can't locate $filename in \@INC ...";
6497 Note that the file will not be included twice under the same specified
6500 The file must return true as the last statement to indicate
6501 successful execution of any initialization code, so it's customary to
6502 end such a file with C<1;> unless you're sure it'll return true
6503 otherwise. But it's better just to put the C<1;>, in case you add more
6506 If EXPR is a bareword, L<C<require>|/require VERSION> assumes a F<.pm>
6507 extension and replaces C<::> with C</> in the filename for you,
6508 to make it easy to load standard modules. This form of loading of
6509 modules does not risk altering your namespace, however it will autovivify
6510 the stash for the required module.
6512 In other words, if you try this:
6514 require Foo::Bar; # a splendid bareword
6516 The require function will actually look for the F<Foo/Bar.pm> file in the
6517 directories specified in the L<C<@INC>|perlvar/@INC> array, and it will
6518 autovivify the C<Foo::Bar::> stash at compile time.
6520 But if you try this:
6522 my $class = 'Foo::Bar';
6523 require $class; # $class is not a bareword
6525 require "Foo::Bar"; # not a bareword because of the ""
6527 The require function will look for the F<Foo::Bar> file in the
6528 L<C<@INC>|perlvar/@INC> array and
6529 will complain about not finding F<Foo::Bar> there. In this case you can do:
6531 eval "require $class";
6535 require "Foo/Bar.pm";
6537 Neither of these forms will autovivify any stashes at compile time and
6538 only have run time effects.
6540 Now that you understand how L<C<require>|/require VERSION> looks for
6541 files with a bareword argument, there is a little extra functionality
6542 going on behind the scenes. Before L<C<require>|/require VERSION> looks
6543 for a F<.pm> extension, it will first look for a similar filename with a
6544 F<.pmc> extension. If this file is found, it will be loaded in place of
6545 any file ending in a F<.pm> extension. This applies to both the explicit
6546 C<require "Foo/Bar.pm";> form and the C<require Foo::Bar;> form.
6548 You can also insert hooks into the import facility by putting Perl code
6549 directly into the L<C<@INC>|perlvar/@INC> array. There are three forms
6550 of hooks: subroutine references, array references, and blessed objects.
6552 Subroutine references are the simplest case. When the inclusion system
6553 walks through L<C<@INC>|perlvar/@INC> and encounters a subroutine, this
6554 subroutine gets called with two parameters, the first a reference to
6555 itself, and the second the name of the file to be included (e.g.,
6556 F<Foo/Bar.pm>). The subroutine should return either nothing or else a
6557 list of up to four values in the following order:
6563 A reference to a scalar, containing any initial source code to prepend to
6564 the file or generator output.
6568 A filehandle, from which the file will be read.
6572 A reference to a subroutine. If there is no filehandle (previous item),
6573 then this subroutine is expected to generate one line of source code per
6574 call, writing the line into L<C<$_>|perlvar/$_> and returning 1, then
6575 finally at end of file returning 0. If there is a filehandle, then the
6576 subroutine will be called to act as a simple source filter, with the
6577 line as read in L<C<$_>|perlvar/$_>.
6578 Again, return 1 for each valid line, and 0 after all lines have been
6580 For historical reasons the subroutine will receive a meaningless argument
6581 (in fact always the numeric value zero) as C<$_[0]>.
6585 Optional state for the subroutine. The state is passed in as C<$_[1]>.
6589 If an empty list, L<C<undef>|/undef EXPR>, or nothing that matches the
6590 first 3 values above is returned, then L<C<require>|/require VERSION>
6591 looks at the remaining elements of L<C<@INC>|perlvar/@INC>.
6592 Note that this filehandle must be a real filehandle (strictly a typeglob
6593 or reference to a typeglob, whether blessed or unblessed); tied filehandles
6594 will be ignored and processing will stop there.
6596 If the hook is an array reference, its first element must be a subroutine
6597 reference. This subroutine is called as above, but the first parameter is
6598 the array reference. This lets you indirectly pass arguments to
6601 In other words, you can write:
6603 push @INC, \&my_sub;
6605 my ($coderef, $filename) = @_; # $coderef is \&my_sub
6611 push @INC, [ \&my_sub, $x, $y, ... ];
6613 my ($arrayref, $filename) = @_;
6614 # Retrieve $x, $y, ...
6615 my (undef, @parameters) = @$arrayref;
6619 If the hook is an object, it must provide an C<INC> method that will be
6620 called as above, the first parameter being the object itself. (Note that
6621 you must fully qualify the sub's name, as unqualified C<INC> is always forced
6622 into package C<main>.) Here is a typical code layout:
6628 my ($self, $filename) = @_;
6632 # In the main program
6633 push @INC, Foo->new(...);
6635 These hooks are also permitted to set the L<C<%INC>|perlvar/%INC> entry
6636 corresponding to the files they have loaded. See L<perlvar/%INC>.
6638 For a yet-more-powerful import facility, see
6639 L<C<use>|/use Module VERSION LIST> and L<perlmod>.
6646 =for Pod::Functions clear all variables of a given name
6648 Generally used in a L<C<continue>|/continue BLOCK> block at the end of a
6649 loop to clear variables and reset C<m?pattern?> searches so that they
6651 expression is interpreted as a list of single characters (hyphens
6652 allowed for ranges). All variables and arrays beginning with one of
6653 those letters are reset to their pristine state. If the expression is
6654 omitted, one-match searches (C<m?pattern?>) are reset to match again.
6655 Only resets variables or searches in the current package. Always returns
6658 reset 'X'; # reset all X variables
6659 reset 'a-z'; # reset lower case variables
6660 reset; # just reset m?one-time? searches
6662 Resetting C<"A-Z"> is not recommended because you'll wipe out your
6663 L<C<@ARGV>|perlvar/@ARGV> and L<C<@INC>|perlvar/@INC> arrays and your
6664 L<C<%ENV>|perlvar/%ENV> hash.
6665 Resets only package variables; lexical variables are unaffected, but
6666 they clean themselves up on scope exit anyway, so you'll probably want
6667 to use them instead. See L<C<my>|/my VARLIST>.
6674 =for Pod::Functions get out of a function early
6676 Returns from a subroutine, L<C<eval>|/eval EXPR>,
6677 L<C<do FILE>|/do EXPR>, L<C<sort>|/sort SUBNAME LIST> block or regex
6678 eval block (but not a L<C<grep>|/grep BLOCK LIST> or
6679 L<C<map>|/map BLOCK LIST> block) with the value
6680 given in EXPR. Evaluation of EXPR may be in list, scalar, or void
6681 context, depending on how the return value will be used, and the context
6682 may vary from one execution to the next (see
6683 L<C<wantarray>|/wantarray>). If no EXPR
6684 is given, returns an empty list in list context, the undefined value in
6685 scalar context, and (of course) nothing at all in void context.
6687 (In the absence of an explicit L<C<return>|/return EXPR>, a subroutine,
6688 L<C<eval>|/eval EXPR>,
6689 or L<C<do FILE>|/do EXPR> automatically returns the value of the last expression
6692 Unlike most named operators, this is also exempt from the
6693 looks-like-a-function rule, so C<return ("foo")."bar"> will
6694 cause C<"bar"> to be part of the argument to L<C<return>|/return EXPR>.
6697 X<reverse> X<rev> X<invert>
6699 =for Pod::Functions flip a string or a list
6701 In list context, returns a list value consisting of the elements
6702 of LIST in the opposite order. In scalar context, concatenates the
6703 elements of LIST and returns a string value with all characters
6704 in the opposite order.
6706 print join(", ", reverse "world", "Hello"); # Hello, world
6708 print scalar reverse "dlrow ,", "olleH"; # Hello, world
6710 Used without arguments in scalar context, L<C<reverse>|/reverse LIST>
6711 reverses L<C<$_>|perlvar/$_>.
6713 $_ = "dlrow ,olleH";
6714 print reverse; # No output, list context
6715 print scalar reverse; # Hello, world
6717 Note that reversing an array to itself (as in C<@a = reverse @a>) will
6718 preserve non-existent elements whenever possible; i.e., for non-magical
6719 arrays or for tied arrays with C<EXISTS> and C<DELETE> methods.
6721 This operator is also handy for inverting a hash, although there are some
6722 caveats. If a value is duplicated in the original hash, only one of those
6723 can be represented as a key in the inverted hash. Also, this has to
6724 unwind one hash and build a whole new one, which may take some time
6725 on a large hash, such as from a DBM file.
6727 my %by_name = reverse %by_address; # Invert the hash
6729 =item rewinddir DIRHANDLE
6732 =for Pod::Functions reset directory handle
6734 Sets the current position to the beginning of the directory for the
6735 L<C<readdir>|/readdir DIRHANDLE> routine on DIRHANDLE.
6737 Portability issues: L<perlport/rewinddir>.
6739 =item rindex STR,SUBSTR,POSITION
6742 =item rindex STR,SUBSTR
6744 =for Pod::Functions right-to-left substring search
6746 Works just like L<C<index>|/index STR,SUBSTR,POSITION> except that it
6747 returns the position of the I<last>
6748 occurrence of SUBSTR in STR. If POSITION is specified, returns the
6749 last occurrence beginning at or before that position.
6751 =item rmdir FILENAME
6752 X<rmdir> X<rd> X<directory, remove>
6756 =for Pod::Functions remove a directory
6758 Deletes the directory specified by FILENAME if that directory is
6759 empty. If it succeeds it returns true; otherwise it returns false and
6760 sets L<C<$!>|perlvar/$!> (errno). If FILENAME is omitted, uses
6761 L<C<$_>|perlvar/$_>.
6763 To remove a directory tree recursively (C<rm -rf> on Unix) look at
6764 the L<C<rmtree>|File::Path/rmtree( $dir )> function of the L<File::Path>
6769 =for Pod::Functions replace a pattern with a string
6771 The substitution operator. See L<perlop/"Regexp Quote-Like Operators">.
6773 =item say FILEHANDLE LIST
6776 =item say FILEHANDLE
6782 =for Pod::Functions +say output a list to a filehandle, appending a newline
6784 Just like L<C<print>|/print FILEHANDLE LIST>, but implicitly appends a
6785 newline. C<say LIST> is simply an abbreviation for
6786 C<{ local $\ = "\n"; print LIST }>. To use FILEHANDLE without a LIST to
6787 print the contents of L<C<$_>|perlvar/$_> to it, you must use a bareword
6788 filehandle like C<FH>, not an indirect one like C<$fh>.
6790 L<C<say>|/say FILEHANDLE LIST> is available only if the
6791 L<C<"say"> feature|feature/The 'say' feature> is enabled or if it is
6792 prefixed with C<CORE::>. The
6793 L<C<"say"> feature|feature/The 'say' feature> is enabled automatically
6794 with a C<use v5.10> (or higher) declaration in the current scope.
6797 X<scalar> X<context>
6799 =for Pod::Functions force a scalar context
6801 Forces EXPR to be interpreted in scalar context and returns the value
6804 my @counts = ( scalar @a, scalar @b, scalar @c );
6806 There is no equivalent operator to force an expression to
6807 be interpolated in list context because in practice, this is never
6808 needed. If you really wanted to do so, however, you could use
6809 the construction C<@{[ (some expression) ]}>, but usually a simple
6810 C<(some expression)> suffices.
6812 Because L<C<scalar>|/scalar EXPR> is a unary operator, if you
6814 parenthesized list for the EXPR, this behaves as a scalar comma expression,
6815 evaluating all but the last element in void context and returning the final
6816 element evaluated in scalar context. This is seldom what you want.
6818 The following single statement:
6820 print uc(scalar(foo(), $bar)), $baz;
6822 is the moral equivalent of these two:
6825 print(uc($bar), $baz);
6827 See L<perlop> for more details on unary operators and the comma operator,
6828 and L<perldata> for details on evaluating a hash in scalar contex.
6830 =item seek FILEHANDLE,POSITION,WHENCE
6831 X<seek> X<fseek> X<filehandle, position>
6833 =for Pod::Functions reposition file pointer for random-access I/O
6835 Sets FILEHANDLE's position, just like the L<fseek(3)> call of C C<stdio>.
6836 FILEHANDLE may be an expression whose value gives the name of the
6837 filehandle. The values for WHENCE are C<0> to set the new position
6838 I<in bytes> to POSITION; C<1> to set it to the current position plus
6839 POSITION; and C<2> to set it to EOF plus POSITION, typically
6840 negative. For WHENCE you may use the constants C<SEEK_SET>,
6841 C<SEEK_CUR>, and C<SEEK_END> (start of the file, current position, end
6842 of the file) from the L<Fcntl> module. Returns C<1> on success, false
6845 Note the emphasis on bytes: even if the filehandle has been set to operate
6846 on characters (for example using the C<:encoding(UTF-8)> I/O layer), the
6847 L<C<seek>|/seek FILEHANDLE,POSITION,WHENCE>,
6848 L<C<tell>|/tell FILEHANDLE>, and
6849 L<C<sysseek>|/sysseek FILEHANDLE,POSITION,WHENCE>
6850 family of functions use byte offsets, not character offsets,
6851 because seeking to a character offset would be very slow in a UTF-8 file.
6853 If you want to position the file for
6854 L<C<sysread>|/sysread FILEHANDLE,SCALAR,LENGTH,OFFSET> or
6855 L<C<syswrite>|/syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET>, don't use
6856 L<C<seek>|/seek FILEHANDLE,POSITION,WHENCE>, because buffering makes its
6857 effect on the file's read-write position unpredictable and non-portable.
6858 Use L<C<sysseek>|/sysseek FILEHANDLE,POSITION,WHENCE> instead.
6860 Due to the rules and rigors of ANSI C, on some systems you have to do a
6861 seek whenever you switch between reading and writing. Amongst other
6862 things, this may have the effect of calling stdio's L<clearerr(3)>.
6863 A WHENCE of C<1> (C<SEEK_CUR>) is useful for not moving the file position:
6867 This is also useful for applications emulating C<tail -f>. Once you hit
6868 EOF on your read and then sleep for a while, you (probably) have to stick in a
6869 dummy L<C<seek>|/seek FILEHANDLE,POSITION,WHENCE> to reset things. The
6870 L<C<seek>|/seek FILEHANDLE,POSITION,WHENCE> doesn't change the position,
6871 but it I<does> clear the end-of-file condition on the handle, so that the
6872 next C<readline FILE> makes Perl try again to read something. (We hope.)
6874 If that doesn't work (some I/O implementations are particularly
6875 cantankerous), you might need something like this:
6878 for ($curpos = tell($fh); $_ = readline($fh);
6879 $curpos = tell($fh)) {
6880 # search for some stuff and put it into files
6882 sleep($for_a_while);
6883 seek($fh, $curpos, 0);
6886 =item seekdir DIRHANDLE,POS
6889 =for Pod::Functions reposition directory pointer
6891 Sets the current position for the L<C<readdir>|/readdir DIRHANDLE>
6892 routine on DIRHANDLE. POS must be a value returned by
6893 L<C<telldir>|/telldir DIRHANDLE>. L<C<seekdir>|/seekdir DIRHANDLE,POS>
6894 also has the same caveats about possible directory compaction as the
6895 corresponding system library routine.
6897 =item select FILEHANDLE
6898 X<select> X<filehandle, default>
6902 =for Pod::Functions reset default output or do I/O multiplexing
6904 Returns the currently selected filehandle. If FILEHANDLE is supplied,
6905 sets the new current default filehandle for output. This has two
6906 effects: first, a L<C<write>|/write FILEHANDLE> or a L<C<print>|/print
6907 FILEHANDLE LIST> without a filehandle
6908 default to this FILEHANDLE. Second, references to variables related to
6909 output will refer to this output channel.
6911 For example, to set the top-of-form format for more than one
6912 output channel, you might do the following:
6919 FILEHANDLE may be an expression whose value gives the name of the
6920 actual filehandle. Thus:
6922 my $oldfh = select(STDERR); $| = 1; select($oldfh);
6924 Some programmers may prefer to think of filehandles as objects with
6925 methods, preferring to write the last example as:
6927 STDERR->autoflush(1);
6929 (Prior to Perl version 5.14, you have to C<use IO::Handle;> explicitly
6932 Portability issues: L<perlport/select>.
6934 =item select RBITS,WBITS,EBITS,TIMEOUT
6937 This calls the L<select(2)> syscall with the bit masks specified, which
6938 can be constructed using L<C<fileno>|/fileno FILEHANDLE> and
6939 L<C<vec>|/vec EXPR,OFFSET,BITS>, along these lines:
6941 my $rin = my $win = my $ein = '';
6942 vec($rin, fileno(STDIN), 1) = 1;
6943 vec($win, fileno(STDOUT), 1) = 1;
6946 If you want to select on many filehandles, you may wish to write a
6947 subroutine like this:
6952 for my $fh (@fhlist) {
6953 vec($bits, fileno($fh), 1) = 1;
6957 my $rin = fhbits(\*STDIN, $tty, $mysock);
6961 my ($nfound, $timeleft) =
6962 select(my $rout = $rin, my $wout = $win, my $eout = $ein,
6965 or to block until something becomes ready just do this
6968 select(my $rout = $rin, my $wout = $win, my $eout = $ein, undef);
6970 Most systems do not bother to return anything useful in C<$timeleft>, so
6971 calling L<C<select>|/select RBITS,WBITS,EBITS,TIMEOUT> in scalar context
6972 just returns C<$nfound>.
6974 Any of the bit masks can also be L<C<undef>|/undef EXPR>. The timeout,
6976 in seconds, which may be fractional. Note: not all implementations are
6977 capable of returning the C<$timeleft>. If not, they always return
6978 C<$timeleft> equal to the supplied C<$timeout>.
6980 You can effect a sleep of 250 milliseconds this way:
6982 select(undef, undef, undef, 0.25);
6984 Note that whether L<C<select>|/select RBITS,WBITS,EBITS,TIMEOUT> gets
6985 restarted after signals (say, SIGALRM) is implementation-dependent. See
6986 also L<perlport> for notes on the portability of
6987 L<C<select>|/select RBITS,WBITS,EBITS,TIMEOUT>.
6989 On error, L<C<select>|/select RBITS,WBITS,EBITS,TIMEOUT> behaves just
6990 like L<select(2)>: it returns C<-1> and sets L<C<$!>|perlvar/$!>.
6992 On some Unixes, L<select(2)> may report a socket file descriptor as
6993 "ready for reading" even when no data is available, and thus any
6994 subsequent L<C<read>|/read FILEHANDLE,SCALAR,LENGTH,OFFSET> would block.
6995 This can be avoided if you always use C<O_NONBLOCK> on the socket. See
6996 L<select(2)> and L<fcntl(2)> for further details.
6998 The standard L<C<IO::Select>|IO::Select> module provides a
6999 user-friendlier interface to
7000 L<C<select>|/select RBITS,WBITS,EBITS,TIMEOUT>, mostly because it does
7001 all the bit-mask work for you.
7003 B<WARNING>: One should not attempt to mix buffered I/O (like
7004 L<C<read>|/read FILEHANDLE,SCALAR,LENGTH,OFFSET> or
7005 L<C<readline>|/readline EXPR>) with
7006 L<C<select>|/select RBITS,WBITS,EBITS,TIMEOUT>, except as permitted by
7007 POSIX, and even then only on POSIX systems. You have to use
7008 L<C<sysread>|/sysread FILEHANDLE,SCALAR,LENGTH,OFFSET> instead.
7010 Portability issues: L<perlport/select>.
7012 =item semctl ID,SEMNUM,CMD,ARG
7015 =for Pod::Functions SysV semaphore control operations
7017 Calls the System V IPC function L<semctl(2)>. You'll probably have to say
7021 first to get the correct constant definitions. If CMD is IPC_STAT or
7022 GETALL, then ARG must be a variable that will hold the returned
7023 semid_ds structure or semaphore value array. Returns like
7024 L<C<ioctl>|/ioctl FILEHANDLE,FUNCTION,SCALAR>:
7025 the undefined value for error, "C<0 but true>" for zero, or the actual
7026 return value otherwise. The ARG must consist of a vector of native
7027 short integers, which may be created with C<pack("s!",(0)x$nsem)>.
7028 See also L<perlipc/"SysV IPC"> and the documentation for
7029 L<C<IPC::SysV>|IPC::SysV> and L<C<IPC::Semaphore>|IPC::Semaphore>.
7031 Portability issues: L<perlport/semctl>.
7033 =item semget KEY,NSEMS,FLAGS
7036 =for Pod::Functions get set of SysV semaphores
7038 Calls the System V IPC function L<semget(2)>. Returns the semaphore id, or
7039 the undefined value on error. See also
7040 L<perlipc/"SysV IPC"> and the documentation for
7041 L<C<IPC::SysV>|IPC::SysV> and L<C<IPC::Semaphore>|IPC::Semaphore>.
7043 Portability issues: L<perlport/semget>.
7045 =item semop KEY,OPSTRING
7048 =for Pod::Functions SysV semaphore operations
7050 Calls the System V IPC function L<semop(2)> for semaphore operations
7051 such as signalling and waiting. OPSTRING must be a packed array of
7052 semop structures. Each semop structure can be generated with
7053 C<pack("s!3", $semnum, $semop, $semflag)>. The length of OPSTRING
7054 implies the number of semaphore operations. Returns true if
7055 successful, false on error. As an example, the
7056 following code waits on semaphore $semnum of semaphore id $semid:
7058 my $semop = pack("s!3", $semnum, -1, 0);
7059 die "Semaphore trouble: $!\n" unless semop($semid, $semop);
7061 To signal the semaphore, replace C<-1> with C<1>. See also
7062 L<perlipc/"SysV IPC"> and the documentation for
7063 L<C<IPC::SysV>|IPC::SysV> and L<C<IPC::Semaphore>|IPC::Semaphore>.
7065 Portability issues: L<perlport/semop>.
7067 =item send SOCKET,MSG,FLAGS,TO
7070 =item send SOCKET,MSG,FLAGS
7072 =for Pod::Functions send a message over a socket
7074 Sends a message on a socket. Attempts to send the scalar MSG to the SOCKET
7075 filehandle. Takes the same flags as the system call of the same name. On
7076 unconnected sockets, you must specify a destination to I<send to>, in which
7077 case it does a L<sendto(2)> syscall. Returns the number of characters sent,
7078 or the undefined value on error. The L<sendmsg(2)> syscall is currently
7079 unimplemented. See L<perlipc/"UDP: Message Passing"> for examples.
7081 Note that if the socket has been marked as C<:utf8>, C<send> will
7082 throw an exception. The C<:encoding(...)> layer implicitly introduces
7083 the C<:utf8> layer. See L<C<binmode>|/binmode FILEHANDLE, LAYER>.
7085 =item setpgrp PID,PGRP
7088 =for Pod::Functions set the process group of a process
7090 Sets the current process group for the specified PID, C<0> for the current
7091 process. Raises an exception when used on a machine that doesn't
7092 implement POSIX L<setpgid(2)> or BSD L<setpgrp(2)>. If the arguments
7093 are omitted, it defaults to C<0,0>. Note that the BSD 4.2 version of
7094 L<C<setpgrp>|/setpgrp PID,PGRP> does not accept any arguments, so only
7095 C<setpgrp(0,0)> is portable. See also
7096 L<C<POSIX::setsid()>|POSIX/C<setsid>>.
7098 Portability issues: L<perlport/setpgrp>.
7100 =item setpriority WHICH,WHO,PRIORITY
7101 X<setpriority> X<priority> X<nice> X<renice>
7103 =for Pod::Functions set a process's nice value
7105 Sets the current priority for a process, a process group, or a user.
7106 (See L<setpriority(2)>.) Raises an exception when used on a machine
7107 that doesn't implement L<setpriority(2)>.
7109 C<WHICH> can be any of C<PRIO_PROCESS>, C<PRIO_PGRP> or C<PRIO_USER>
7110 imported from L<POSIX/RESOURCE CONSTANTS>.
7112 Portability issues: L<perlport/setpriority>.
7114 =item setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
7117 =for Pod::Functions set some socket options
7119 Sets the socket option requested. Returns L<C<undef>|/undef EXPR> on
7120 error. Use integer constants provided by the L<C<Socket>|Socket> module
7122 LEVEL and OPNAME. Values for LEVEL can also be obtained from
7123 getprotobyname. OPTVAL might either be a packed string or an integer.
7124 An integer OPTVAL is shorthand for pack("i", OPTVAL).
7126 An example disabling Nagle's algorithm on a socket:
7128 use Socket qw(IPPROTO_TCP TCP_NODELAY);
7129 setsockopt($socket, IPPROTO_TCP, TCP_NODELAY, 1);
7131 Portability issues: L<perlport/setsockopt>.
7138 =for Pod::Functions remove the first element of an array, and return it
7140 Shifts the first value of the array off and returns it, shortening the
7141 array by 1 and moving everything down. If there are no elements in the
7142 array, returns the undefined value. If ARRAY is omitted, shifts the
7143 L<C<@_>|perlvar/@_> array within the lexical scope of subroutines and
7144 formats, and the L<C<@ARGV>|perlvar/@ARGV> array outside a subroutine
7145 and also within the lexical scopes
7146 established by the C<eval STRING>, C<BEGIN {}>, C<INIT {}>, C<CHECK {}>,
7147 C<UNITCHECK {}>, and C<END {}> constructs.
7149 Starting with Perl 5.14, an experimental feature allowed
7150 L<C<shift>|/shift ARRAY> to take a
7151 scalar expression. This experiment has been deemed unsuccessful, and was
7152 removed as of Perl 5.24.
7154 See also L<C<unshift>|/unshift ARRAY,LIST>, L<C<push>|/push ARRAY,LIST>,
7155 and L<C<pop>|/pop ARRAY>. L<C<shift>|/shift ARRAY> and
7156 L<C<unshift>|/unshift ARRAY,LIST> do the same thing to the left end of
7157 an array that L<C<pop>|/pop ARRAY> and L<C<push>|/push ARRAY,LIST> do to
7160 =item shmctl ID,CMD,ARG
7163 =for Pod::Functions SysV shared memory operations
7165 Calls the System V IPC function shmctl. You'll probably have to say
7169 first to get the correct constant definitions. If CMD is C<IPC_STAT>,
7170 then ARG must be a variable that will hold the returned C<shmid_ds>
7171 structure. Returns like ioctl: L<C<undef>|/undef EXPR> for error; "C<0>
7172 but true" for zero; and the actual return value otherwise.
7173 See also L<perlipc/"SysV IPC"> and the documentation for
7174 L<C<IPC::SysV>|IPC::SysV>.
7176 Portability issues: L<perlport/shmctl>.
7178 =item shmget KEY,SIZE,FLAGS
7181 =for Pod::Functions get SysV shared memory segment identifier
7183 Calls the System V IPC function shmget. Returns the shared memory
7184 segment id, or L<C<undef>|/undef EXPR> on error.
7185 See also L<perlipc/"SysV IPC"> and the documentation for
7186 L<C<IPC::SysV>|IPC::SysV>.
7188 Portability issues: L<perlport/shmget>.
7190 =item shmread ID,VAR,POS,SIZE
7194 =for Pod::Functions read SysV shared memory
7196 =item shmwrite ID,STRING,POS,SIZE
7198 =for Pod::Functions write SysV shared memory
7200 Reads or writes the System V shared memory segment ID starting at
7201 position POS for size SIZE by attaching to it, copying in/out, and
7202 detaching from it. When reading, VAR must be a variable that will
7203 hold the data read. When writing, if STRING is too long, only SIZE
7204 bytes are used; if STRING is too short, nulls are written to fill out
7205 SIZE bytes. Return true if successful, false on error.
7206 L<C<shmread>|/shmread ID,VAR,POS,SIZE> taints the variable. See also
7207 L<perlipc/"SysV IPC"> and the documentation for
7208 L<C<IPC::SysV>|IPC::SysV> and the L<C<IPC::Shareable>|IPC::Shareable>
7211 Portability issues: L<perlport/shmread> and L<perlport/shmwrite>.
7213 =item shutdown SOCKET,HOW
7216 =for Pod::Functions close down just half of a socket connection
7218 Shuts down a socket connection in the manner indicated by HOW, which
7219 has the same interpretation as in the syscall of the same name.
7221 shutdown($socket, 0); # I/we have stopped reading data
7222 shutdown($socket, 1); # I/we have stopped writing data
7223 shutdown($socket, 2); # I/we have stopped using this socket
7225 This is useful with sockets when you want to tell the other
7226 side you're done writing but not done reading, or vice versa.
7227 It's also a more insistent form of close because it also
7228 disables the file descriptor in any forked copies in other
7231 Returns C<1> for success; on error, returns L<C<undef>|/undef EXPR> if
7232 the first argument is not a valid filehandle, or returns C<0> and sets
7233 L<C<$!>|perlvar/$!> for any other failure.
7236 X<sin> X<sine> X<asin> X<arcsine>
7240 =for Pod::Functions return the sine of a number
7242 Returns the sine of EXPR (expressed in radians). If EXPR is omitted,
7243 returns sine of L<C<$_>|perlvar/$_>.
7245 For the inverse sine operation, you may use the C<Math::Trig::asin>
7246 function, or use this relation:
7248 sub asin { atan2($_[0], sqrt(1 - $_[0] * $_[0])) }
7255 =for Pod::Functions block for some number of seconds
7257 Causes the script to sleep for (integer) EXPR seconds, or forever if no
7258 argument is given. Returns the integer number of seconds actually slept.
7260 May be interrupted if the process receives a signal such as C<SIGALRM>.
7263 local $SIG{ALRM} = sub { die "Alarm!\n" };
7266 die $@ unless $@ eq "Alarm!\n";
7268 You probably cannot mix L<C<alarm>|/alarm SECONDS> and
7269 L<C<sleep>|/sleep EXPR> calls, because L<C<sleep>|/sleep EXPR> is often
7270 implemented using L<C<alarm>|/alarm SECONDS>.
7272 On some older systems, it may sleep up to a full second less than what
7273 you requested, depending on how it counts seconds. Most modern systems
7274 always sleep the full amount. They may appear to sleep longer than that,
7275 however, because your process might not be scheduled right away in a
7276 busy multitasking system.
7278 For delays of finer granularity than one second, the L<Time::HiRes>
7279 module (from CPAN, and starting from Perl 5.8 part of the standard
7280 distribution) provides L<C<usleep>|Time::HiRes/usleep ( $useconds )>.
7281 You may also use Perl's four-argument
7282 version of L<C<select>|/select RBITS,WBITS,EBITS,TIMEOUT> leaving the
7283 first three arguments undefined, or you might be able to use the
7284 L<C<syscall>|/syscall NUMBER, LIST> interface to access L<setitimer(2)>
7285 if your system supports it. See L<perlfaq8> for details.
7287 See also the L<POSIX> module's L<C<pause>|POSIX/C<pause>> function.
7289 =item socket SOCKET,DOMAIN,TYPE,PROTOCOL
7292 =for Pod::Functions create a socket
7294 Opens a socket of the specified kind and attaches it to filehandle
7295 SOCKET. DOMAIN, TYPE, and PROTOCOL are specified the same as for
7296 the syscall of the same name. You should C<use Socket> first
7297 to get the proper definitions imported. See the examples in
7298 L<perlipc/"Sockets: Client/Server Communication">.
7300 On systems that support a close-on-exec flag on files, the flag will
7301 be set for the newly opened file descriptor, as determined by the
7302 value of L<C<$^F>|perlvar/$^F>. See L<perlvar/$^F>.
7304 =item socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
7307 =for Pod::Functions create a pair of sockets
7309 Creates an unnamed pair of sockets in the specified domain, of the
7310 specified type. DOMAIN, TYPE, and PROTOCOL are specified the same as
7311 for the syscall of the same name. If unimplemented, raises an exception.
7312 Returns true if successful.
7314 On systems that support a close-on-exec flag on files, the flag will
7315 be set for the newly opened file descriptors, as determined by the value
7316 of L<C<$^F>|perlvar/$^F>. See L<perlvar/$^F>.
7318 Some systems define L<C<pipe>|/pipe READHANDLE,WRITEHANDLE> in terms of
7319 L<C<socketpair>|/socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL>, in
7320 which a call to C<pipe($rdr, $wtr)> is essentially:
7323 socketpair(my $rdr, my $wtr, AF_UNIX, SOCK_STREAM, PF_UNSPEC);
7324 shutdown($rdr, 1); # no more writing for reader
7325 shutdown($wtr, 0); # no more reading for writer
7327 See L<perlipc> for an example of socketpair use. Perl 5.8 and later will
7328 emulate socketpair using IP sockets to localhost if your system implements
7329 sockets but not socketpair.
7331 Portability issues: L<perlport/socketpair>.
7333 =item sort SUBNAME LIST
7336 =item sort BLOCK LIST
7340 =for Pod::Functions sort a list of values
7342 In list context, this sorts the LIST and returns the sorted list value.
7343 In scalar context, the behaviour of L<C<sort>|/sort SUBNAME LIST> is
7346 If SUBNAME or BLOCK is omitted, L<C<sort>|/sort SUBNAME LIST>s in
7347 standard string comparison
7348 order. If SUBNAME is specified, it gives the name of a subroutine
7349 that returns an integer less than, equal to, or greater than C<0>,
7350 depending on how the elements of the list are to be ordered. (The
7351 C<< <=> >> and C<cmp> operators are extremely useful in such routines.)
7352 SUBNAME may be a scalar variable name (unsubscripted), in which case
7353 the value provides the name of (or a reference to) the actual
7354 subroutine to use. In place of a SUBNAME, you can provide a BLOCK as
7355 an anonymous, in-line sort subroutine.
7357 If the subroutine's prototype is C<($$)>, the elements to be compared are
7358 passed by reference in L<C<@_>|perlvar/@_>, as for a normal subroutine.
7359 This is slower than unprototyped subroutines, where the elements to be
7360 compared are passed into the subroutine as the package global variables
7361 C<$a> and C<$b> (see example below).
7363 If the subroutine is an XSUB, the elements to be compared are pushed on
7364 to the stack, the way arguments are usually passed to XSUBs. C<$a> and
7367 The values to be compared are always passed by reference and should not
7370 You also cannot exit out of the sort block or subroutine using any of the
7371 loop control operators described in L<perlsyn> or with
7372 L<C<goto>|/goto LABEL>.
7374 When L<C<use locale>|locale> (but not C<use locale ':not_characters'>)
7375 is in effect, C<sort LIST> sorts LIST according to the
7376 current collation locale. See L<perllocale>.
7378 L<C<sort>|/sort SUBNAME LIST> returns aliases into the original list,
7379 much as a for loop's index variable aliases the list elements. That is,
7380 modifying an element of a list returned by L<C<sort>|/sort SUBNAME LIST>
7381 (for example, in a C<foreach>, L<C<map>|/map BLOCK LIST> or
7382 L<C<grep>|/grep BLOCK LIST>)
7383 actually modifies the element in the original list. This is usually
7384 something to be avoided when writing clear code.
7386 Historically Perl has varied in whether sorting is stable by default.
7387 If stability matters, it can be controlled explicitly by using the
7393 my @articles = sort @files;
7395 # same thing, but with explicit sort routine
7396 my @articles = sort {$a cmp $b} @files;
7398 # now case-insensitively
7399 my @articles = sort {fc($a) cmp fc($b)} @files;
7401 # same thing in reversed order
7402 my @articles = sort {$b cmp $a} @files;
7404 # sort numerically ascending
7405 my @articles = sort {$a <=> $b} @files;
7407 # sort numerically descending
7408 my @articles = sort {$b <=> $a} @files;
7410 # this sorts the %age hash by value instead of key
7411 # using an in-line function
7412 my @eldest = sort { $age{$b} <=> $age{$a} } keys %age;
7414 # sort using explicit subroutine name
7416 $age{$a} <=> $age{$b}; # presuming numeric
7418 my @sortedclass = sort byage @class;
7420 sub backwards { $b cmp $a }
7421 my @harry = qw(dog cat x Cain Abel);
7422 my @george = qw(gone chased yz Punished Axed);
7424 # prints AbelCaincatdogx
7425 print sort backwards @harry;
7426 # prints xdogcatCainAbel
7427 print sort @george, 'to', @harry;
7428 # prints AbelAxedCainPunishedcatchaseddoggonetoxyz
7430 # inefficiently sort by descending numeric compare using
7431 # the first integer after the first = sign, or the
7432 # whole record case-insensitively otherwise
7435 ($b =~ /=(\d+)/)[0] <=> ($a =~ /=(\d+)/)[0]
7440 # same thing, but much more efficiently;
7441 # we'll build auxiliary indices instead
7445 push @nums, ( /=(\d+)/ ? $1 : undef );
7449 my @new = @old[ sort {
7450 $nums[$b] <=> $nums[$a]
7452 $caps[$a] cmp $caps[$b]
7456 # same thing, but without any temps
7457 my @new = map { $_->[0] }
7458 sort { $b->[1] <=> $a->[1]
7461 } map { [$_, /=(\d+)/, fc($_)] } @old;
7463 # using a prototype allows you to use any comparison subroutine
7464 # as a sort subroutine (including other package's subroutines)
7466 sub backwards ($$) { $_[1] cmp $_[0]; } # $a and $b are
7469 my @new = sort Other::backwards @old;
7471 # guarantee stability
7473 my @new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
7475 Warning: syntactical care is required when sorting the list returned from
7476 a function. If you want to sort the list returned by the function call
7477 C<find_records(@key)>, you can use:
7479 my @contact = sort { $a cmp $b } find_records @key;
7480 my @contact = sort +find_records(@key);
7481 my @contact = sort &find_records(@key);
7482 my @contact = sort(find_records(@key));
7484 If instead you want to sort the array C<@key> with the comparison routine
7485 C<find_records()> then you can use:
7487 my @contact = sort { find_records() } @key;
7488 my @contact = sort find_records(@key);
7489 my @contact = sort(find_records @key);
7490 my @contact = sort(find_records (@key));
7492 C<$a> and C<$b> are set as package globals in the package the sort() is
7493 called from. That means C<$main::a> and C<$main::b> (or C<$::a> and
7494 C<$::b>) in the C<main> package, C<$FooPack::a> and C<$FooPack::b> in the
7495 C<FooPack> package, etc. If the sort block is in scope of a C<my> or
7496 C<state> declaration of C<$a> and/or C<$b>, you I<must> spell out the full
7497 name of the variables in the sort block :
7500 my $a = "C"; # DANGER, Will Robinson, DANGER !!!
7502 print sort { $a cmp $b } qw(A C E G B D F H);
7504 sub badlexi { $a cmp $b }
7505 print sort badlexi qw(A C E G B D F H);
7507 # the above prints BACFEDGH or some other incorrect ordering
7509 print sort { $::a cmp $::b } qw(A C E G B D F H);
7511 print sort { our $a cmp our $b } qw(A C E G B D F H);
7513 print sort { our ($a, $b); $a cmp $b } qw(A C E G B D F H);
7515 sub lexi { our $a cmp our $b }
7516 print sort lexi qw(A C E G B D F H);
7518 # the above print ABCDEFGH
7520 With proper care you may mix package and my (or state) C<$a> and/or C<$b>:
7530 say sort { $a->{our $a} <=> $a->{our $b} }
7531 qw{ huge normal tiny small big};
7533 # prints tinysmallnormalbighuge
7535 C<$a> and C<$b> are implicitly local to the sort() execution and regain their
7536 former values upon completing the sort.
7538 Sort subroutines written using C<$a> and C<$b> are bound to their calling
7539 package. It is possible, but of limited interest, to define them in a
7540 different package, since the subroutine must still refer to the calling
7541 package's C<$a> and C<$b> :
7544 sub lexi { $Bar::a cmp $Bar::b }
7546 ... sort Foo::lexi ...
7548 Use the prototyped versions (see above) for a more generic alternative.
7550 The comparison function is required to behave. If it returns
7551 inconsistent results (sometimes saying C<$x[1]> is less than C<$x[2]> and
7552 sometimes saying the opposite, for example) the results are not
7555 Because C<< <=> >> returns L<C<undef>|/undef EXPR> when either operand
7556 is C<NaN> (not-a-number), be careful when sorting with a
7557 comparison function like C<< $a <=> $b >> any lists that might contain a
7558 C<NaN>. The following example takes advantage that C<NaN != NaN> to
7559 eliminate any C<NaN>s from the input list.
7561 my @result = sort { $a <=> $b } grep { $_ == $_ } @input;
7563 =item splice ARRAY,OFFSET,LENGTH,LIST
7566 =item splice ARRAY,OFFSET,LENGTH
7568 =item splice ARRAY,OFFSET
7572 =for Pod::Functions add or remove elements anywhere in an array
7574 Removes the elements designated by OFFSET and LENGTH from an array, and
7575 replaces them with the elements of LIST, if any. In list context,
7576 returns the elements removed from the array. In scalar context,
7577 returns the last element removed, or L<C<undef>|/undef EXPR> if no
7579 removed. The array grows or shrinks as necessary.
7580 If OFFSET is negative then it starts that far from the end of the array.
7581 If LENGTH is omitted, removes everything from OFFSET onward.
7582 If LENGTH is negative, removes the elements from OFFSET onward
7583 except for -LENGTH elements at the end of the array.
7584 If both OFFSET and LENGTH are omitted, removes everything. If OFFSET is
7585 past the end of the array and a LENGTH was provided, Perl issues a warning,
7586 and splices at the end of the array.
7588 The following equivalences hold (assuming C<< $#a >= $i >> )
7590 push(@a,$x,$y) splice(@a,@a,0,$x,$y)
7591 pop(@a) splice(@a,-1)
7592 shift(@a) splice(@a,0,1)
7593 unshift(@a,$x,$y) splice(@a,0,0,$x,$y)
7594 $a[$i] = $y splice(@a,$i,1,$y)
7596 L<C<splice>|/splice ARRAY,OFFSET,LENGTH,LIST> can be used, for example,
7597 to implement n-ary queue processing:
7601 while (my @next_n = splice @_, 0, $n) {
7602 say join q{ -- }, @next_n;
7606 nary_print(3, qw(a b c d e f g h));
7612 Starting with Perl 5.14, an experimental feature allowed
7613 L<C<splice>|/splice ARRAY,OFFSET,LENGTH,LIST> to take a
7614 scalar expression. This experiment has been deemed unsuccessful, and was
7615 removed as of Perl 5.24.
7617 =item split /PATTERN/,EXPR,LIMIT
7620 =item split /PATTERN/,EXPR
7622 =item split /PATTERN/
7626 =for Pod::Functions split up a string using a regexp delimiter
7628 Splits the string EXPR into a list of strings and returns the
7629 list in list context, or the size of the list in scalar context.
7630 (Prior to Perl 5.11, it also overwrote C<@_> with the list in
7631 void and scalar context. If you target old perls, beware.)
7633 If only PATTERN is given, EXPR defaults to L<C<$_>|perlvar/$_>.
7635 Anything in EXPR that matches PATTERN is taken to be a separator
7636 that separates the EXPR into substrings (called "I<fields>") that
7637 do B<not> include the separator. Note that a separator may be
7638 longer than one character or even have no characters at all (the
7639 empty string, which is a zero-width match).
7641 The PATTERN need not be constant; an expression may be used
7642 to specify a pattern that varies at runtime.
7644 If PATTERN matches the empty string, the EXPR is split at the match
7645 position (between characters). As an example, the following:
7647 print join(':', split(/b/, 'abc')), "\n";
7649 uses the C<b> in C<'abc'> as a separator to produce the output C<a:c>.
7652 print join(':', split(//, 'abc')), "\n";
7654 uses empty string matches as separators to produce the output
7655 C<a:b:c>; thus, the empty string may be used to split EXPR into a
7656 list of its component characters.
7658 As a special case for L<C<split>|/split E<sol>PATTERNE<sol>,EXPR,LIMIT>,
7659 the empty pattern given in
7660 L<match operator|perlop/"m/PATTERN/msixpodualngc"> syntax (C<//>)
7661 specifically matches the empty string, which is contrary to its usual
7662 interpretation as the last successful match.
7664 If PATTERN is C</^/>, then it is treated as if it used the
7665 L<multiline modifier|perlreref/OPERATORS> (C</^/m>), since it
7666 isn't much use otherwise.
7668 C<E<sol>m> and any of the other pattern modifiers valid for C<qr>
7669 (summarized in L<perlop/qrE<sol>STRINGE<sol>msixpodualn>) may be
7670 specified explicitly.
7672 As another special case,
7673 L<C<split>|/split E<sol>PATTERNE<sol>,EXPR,LIMIT> emulates the default
7675 command line tool B<awk> when the PATTERN is either omitted or a
7676 string composed of a single space character (such as S<C<' '>> or
7677 S<C<"\x20">>, but not e.g. S<C</ />>). In this case, any leading
7678 whitespace in EXPR is removed before splitting occurs, and the PATTERN is
7679 instead treated as if it were C</\s+/>; in particular, this means that
7680 I<any> contiguous whitespace (not just a single space character) is used as
7681 a separator. However, this special treatment can be avoided by specifying
7682 the pattern S<C</ />> instead of the string S<C<" ">>, thereby allowing
7683 only a single space character to be a separator. In earlier Perls this
7684 special case was restricted to the use of a plain S<C<" ">> as the
7685 pattern argument to split; in Perl 5.18.0 and later this special case is
7686 triggered by any expression which evaluates to the simple string S<C<" ">>.
7688 As of Perl 5.28, this special-cased whitespace splitting works as expected in
7689 the scope of L<< S<C<"use feature 'unicode_strings">>|feature/The
7690 'unicode_strings' feature >>. In previous versions, and outside the scope of
7691 that feature, it exhibits L<perlunicode/The "Unicode Bug">: characters that are
7692 whitespace according to Unicode rules but not according to ASCII rules can be
7693 treated as part of fields rather than as field separators, depending on the
7694 string's internal encoding.
7696 If omitted, PATTERN defaults to a single space, S<C<" ">>, triggering
7697 the previously described I<awk> emulation.
7699 If LIMIT is specified and positive, it represents the maximum number
7700 of fields into which the EXPR may be split; in other words, LIMIT is
7701 one greater than the maximum number of times EXPR may be split. Thus,
7702 the LIMIT value C<1> means that EXPR may be split a maximum of zero
7703 times, producing a maximum of one field (namely, the entire value of
7704 EXPR). For instance:
7706 print join(':', split(//, 'abc', 1)), "\n";
7708 produces the output C<abc>, and this:
7710 print join(':', split(//, 'abc', 2)), "\n";
7712 produces the output C<a:bc>, and each of these:
7714 print join(':', split(//, 'abc', 3)), "\n";
7715 print join(':', split(//, 'abc', 4)), "\n";
7717 produces the output C<a:b:c>.
7719 If LIMIT is negative, it is treated as if it were instead arbitrarily
7720 large; as many fields as possible are produced.
7722 If LIMIT is omitted (or, equivalently, zero), then it is usually
7723 treated as if it were instead negative but with the exception that
7724 trailing empty fields are stripped (empty leading fields are always
7725 preserved); if all fields are empty, then all fields are considered to
7726 be trailing (and are thus stripped in this case). Thus, the following:
7728 print join(':', split(/,/, 'a,b,c,,,')), "\n";
7730 produces the output C<a:b:c>, but the following:
7732 print join(':', split(/,/, 'a,b,c,,,', -1)), "\n";
7734 produces the output C<a:b:c:::>.
7736 In time-critical applications, it is worthwhile to avoid splitting
7737 into more fields than necessary. Thus, when assigning to a list,
7738 if LIMIT is omitted (or zero), then LIMIT is treated as though it
7739 were one larger than the number of variables in the list; for the
7740 following, LIMIT is implicitly 3:
7742 my ($login, $passwd) = split(/:/);
7744 Note that splitting an EXPR that evaluates to the empty string always
7745 produces zero fields, regardless of the LIMIT specified.
7747 An empty leading field is produced when there is a positive-width
7748 match at the beginning of EXPR. For instance:
7750 print join(':', split(/ /, ' abc')), "\n";
7752 produces the output C<:abc>. However, a zero-width match at the
7753 beginning of EXPR never produces an empty field, so that:
7755 print join(':', split(//, ' abc'));
7757 produces the output S<C< :a:b:c>> (rather than S<C<: :a:b:c>>).
7759 An empty trailing field, on the other hand, is produced when there is a
7760 match at the end of EXPR, regardless of the length of the match
7761 (of course, unless a non-zero LIMIT is given explicitly, such fields are
7762 removed, as in the last example). Thus:
7764 print join(':', split(//, ' abc', -1)), "\n";
7766 produces the output S<C< :a:b:c:>>.
7768 If the PATTERN contains
7769 L<capturing groups|perlretut/Grouping things and hierarchical matching>,
7770 then for each separator, an additional field is produced for each substring
7771 captured by a group (in the order in which the groups are specified,
7772 as per L<backreferences|perlretut/Backreferences>); if any group does not
7773 match, then it captures the L<C<undef>|/undef EXPR> value instead of a
7775 note that any such additional field is produced whenever there is a
7776 separator (that is, whenever a split occurs), and such an additional field
7777 does B<not> count towards the LIMIT. Consider the following expressions
7778 evaluated in list context (each returned list is provided in the associated
7781 split(/-|,/, "1-10,20", 3)
7784 split(/(-|,)/, "1-10,20", 3)
7785 # ('1', '-', '10', ',', '20')
7787 split(/-|(,)/, "1-10,20", 3)
7788 # ('1', undef, '10', ',', '20')
7790 split(/(-)|,/, "1-10,20", 3)
7791 # ('1', '-', '10', undef, '20')
7793 split(/(-)|(,)/, "1-10,20", 3)
7794 # ('1', '-', undef, '10', undef, ',', '20')
7796 =item sprintf FORMAT, LIST
7799 =for Pod::Functions formatted print into a string
7801 Returns a string formatted by the usual
7802 L<C<printf>|/printf FILEHANDLE FORMAT, LIST> conventions of the C
7803 library function L<C<sprintf>|/sprintf FORMAT, LIST>. See below for
7804 more details and see L<sprintf(3)> or L<printf(3)> on your system for an
7805 explanation of the general principles.
7809 # Format number with up to 8 leading zeroes
7810 my $result = sprintf("%08d", $number);
7812 # Round number to 3 digits after decimal point
7813 my $rounded = sprintf("%.3f", $number);
7815 Perl does its own L<C<sprintf>|/sprintf FORMAT, LIST> formatting: it
7817 function L<sprintf(3)>, but doesn't use it except for floating-point
7818 numbers, and even then only standard modifiers are allowed.
7819 Non-standard extensions in your local L<sprintf(3)> are
7820 therefore unavailable from Perl.
7822 Unlike L<C<printf>|/printf FILEHANDLE FORMAT, LIST>,
7823 L<C<sprintf>|/sprintf FORMAT, LIST> does not do what you probably mean
7824 when you pass it an array as your first argument.
7825 The array is given scalar context,
7826 and instead of using the 0th element of the array as the format, Perl will
7827 use the count of elements in the array as the format, which is almost never
7830 Perl's L<C<sprintf>|/sprintf FORMAT, LIST> permits the following
7831 universally-known conversions:
7834 %c a character with the given number
7836 %d a signed integer, in decimal
7837 %u an unsigned integer, in decimal
7838 %o an unsigned integer, in octal
7839 %x an unsigned integer, in hexadecimal
7840 %e a floating-point number, in scientific notation
7841 %f a floating-point number, in fixed decimal notation
7842 %g a floating-point number, in %e or %f notation
7844 In addition, Perl permits the following widely-supported conversions:
7846 %X like %x, but using upper-case letters
7847 %E like %e, but using an upper-case "E"
7848 %G like %g, but with an upper-case "E" (if applicable)
7849 %b an unsigned integer, in binary
7850 %B like %b, but using an upper-case "B" with the # flag
7851 %p a pointer (outputs the Perl value's address in hexadecimal)
7852 %n special: *stores* the number of characters output so far
7853 into the next argument in the parameter list
7854 %a hexadecimal floating point
7855 %A like %a, but using upper-case letters
7857 Finally, for backward (and we do mean "backward") compatibility, Perl
7858 permits these unnecessary but widely-supported conversions:
7861 %D a synonym for %ld
7862 %U a synonym for %lu
7863 %O a synonym for %lo
7866 Note that the number of exponent digits in the scientific notation produced
7867 by C<%e>, C<%E>, C<%g> and C<%G> for numbers with the modulus of the
7868 exponent less than 100 is system-dependent: it may be three or less
7869 (zero-padded as necessary). In other words, 1.23 times ten to the
7870 99th may be either "1.23e99" or "1.23e099". Similarly for C<%a> and C<%A>:
7871 the exponent or the hexadecimal digits may float: especially the
7872 "long doubles" Perl configuration option may cause surprises.
7874 Between the C<%> and the format letter, you may specify several
7875 additional attributes controlling the interpretation of the format.
7876 In order, these are:
7880 =item format parameter index
7882 An explicit format parameter index, such as C<2$>. By default sprintf
7883 will format the next unused argument in the list, but this allows you
7884 to take the arguments out of order:
7886 printf '%2$d %1$d', 12, 34; # prints "34 12"
7887 printf '%3$d %d %1$d', 1, 2, 3; # prints "3 1 1"
7893 space prefix non-negative number with a space
7894 + prefix non-negative number with a plus sign
7895 - left-justify within the field
7896 0 use zeros, not spaces, to right-justify
7897 # ensure the leading "0" for any octal,
7898 prefix non-zero hexadecimal with "0x" or "0X",
7899 prefix non-zero binary with "0b" or "0B"
7903 printf '<% d>', 12; # prints "< 12>"
7904 printf '<% d>', 0; # prints "< 0>"
7905 printf '<% d>', -12; # prints "<-12>"
7906 printf '<%+d>', 12; # prints "<+12>"
7907 printf '<%+d>', 0; # prints "<+0>"
7908 printf '<%+d>', -12; # prints "<-12>"
7909 printf '<%6s>', 12; # prints "< 12>"
7910 printf '<%-6s>', 12; # prints "<12 >"
7911 printf '<%06s>', 12; # prints "<000012>"
7912 printf '<%#o>', 12; # prints "<014>"
7913 printf '<%#x>', 12; # prints "<0xc>"
7914 printf '<%#X>', 12; # prints "<0XC>"
7915 printf '<%#b>', 12; # prints "<0b1100>"
7916 printf '<%#B>', 12; # prints "<0B1100>"
7918 When a space and a plus sign are given as the flags at once,
7919 the space is ignored.
7921 printf '<%+ d>', 12; # prints "<+12>"
7922 printf '<% +d>', 12; # prints "<+12>"
7924 When the # flag and a precision are given in the %o conversion,
7925 the precision is incremented if it's necessary for the leading "0".
7927 printf '<%#.5o>', 012; # prints "<00012>"
7928 printf '<%#.5o>', 012345; # prints "<012345>"
7929 printf '<%#.0o>', 0; # prints "<0>"
7933 This flag tells Perl to interpret the supplied string as a vector of
7934 integers, one for each character in the string. Perl applies the format to
7935 each integer in turn, then joins the resulting strings with a separator (a
7936 dot C<.> by default). This can be useful for displaying ordinal values of
7937 characters in arbitrary strings:
7939 printf "%vd", "AB\x{100}"; # prints "65.66.256"
7940 printf "version is v%vd\n", $^V; # Perl's version
7942 Put an asterisk C<*> before the C<v> to override the string to
7943 use to separate the numbers:
7945 printf "address is %*vX\n", ":", $addr; # IPv6 address
7946 printf "bits are %0*v8b\n", " ", $bits; # random bitstring
7948 You can also explicitly specify the argument number to use for
7949 the join string using something like C<*2$v>; for example:
7951 printf '%*4$vX %*4$vX %*4$vX', # 3 IPv6 addresses
7954 =item (minimum) width
7956 Arguments are usually formatted to be only as wide as required to
7957 display the given value. You can override the width by putting
7958 a number here, or get the width from the next argument (with C<*>)
7959 or from a specified argument (e.g., with C<*2$>):
7961 printf "<%s>", "a"; # prints "<a>"
7962 printf "<%6s>", "a"; # prints "< a>"
7963 printf "<%*s>", 6, "a"; # prints "< a>"
7964 printf '<%*2$s>', "a", 6; # prints "< a>"
7965 printf "<%2s>", "long"; # prints "<long>" (does not truncate)
7967 If a field width obtained through C<*> is negative, it has the same
7968 effect as the C<-> flag: left-justification.
7970 =item precision, or maximum width
7973 You can specify a precision (for numeric conversions) or a maximum
7974 width (for string conversions) by specifying a C<.> followed by a number.
7975 For floating-point formats except C<g> and C<G>, this specifies
7976 how many places right of the decimal point to show (the default being 6).
7979 # these examples are subject to system-specific variation
7980 printf '<%f>', 1; # prints "<1.000000>"
7981 printf '<%.1f>', 1; # prints "<1.0>"
7982 printf '<%.0f>', 1; # prints "<1>"
7983 printf '<%e>', 10; # prints "<1.000000e+01>"
7984 printf '<%.1e>', 10; # prints "<1.0e+01>"
7986 For "g" and "G", this specifies the maximum number of significant digits to
7989 # These examples are subject to system-specific variation.
7990 printf '<%g>', 1; # prints "<1>"
7991 printf '<%.10g>', 1; # prints "<1>"
7992 printf '<%g>', 100; # prints "<100>"
7993 printf '<%.1g>', 100; # prints "<1e+02>"
7994 printf '<%.2g>', 100.01; # prints "<1e+02>"
7995 printf '<%.5g>', 100.01; # prints "<100.01>"
7996 printf '<%.4g>', 100.01; # prints "<100>"
7997 printf '<%.1g>', 0.0111; # prints "<0.01>"
7998 printf '<%.2g>', 0.0111; # prints "<0.011>"
7999 printf '<%.3g>', 0.0111; # prints "<0.0111>"
8001 For integer conversions, specifying a precision implies that the
8002 output of the number itself should be zero-padded to this width,
8003 where the 0 flag is ignored:
8005 printf '<%.6d>', 1; # prints "<000001>"
8006 printf '<%+.6d>', 1; # prints "<+000001>"
8007 printf '<%-10.6d>', 1; # prints "<000001 >"
8008 printf '<%10.6d>', 1; # prints "< 000001>"
8009 printf '<%010.6d>', 1; # prints "< 000001>"
8010 printf '<%+10.6d>', 1; # prints "< +000001>"
8012 printf '<%.6x>', 1; # prints "<000001>"
8013 printf '<%#.6x>', 1; # prints "<0x000001>"
8014 printf '<%-10.6x>', 1; # prints "<000001 >"
8015 printf '<%10.6x>', 1; # prints "< 000001>"
8016 printf '<%010.6x>', 1; # prints "< 000001>"
8017 printf '<%#10.6x>', 1; # prints "< 0x000001>"
8019 For string conversions, specifying a precision truncates the string
8020 to fit the specified width:
8022 printf '<%.5s>', "truncated"; # prints "<trunc>"
8023 printf '<%10.5s>', "truncated"; # prints "< trunc>"
8025 You can also get the precision from the next argument using C<.*>, or from a
8026 specified argument (e.g., with C<.*2$>):
8028 printf '<%.6x>', 1; # prints "<000001>"
8029 printf '<%.*x>', 6, 1; # prints "<000001>"
8031 printf '<%.*2$x>', 1, 6; # prints "<000001>"
8033 printf '<%6.*2$x>', 1, 4; # prints "< 0001>"
8035 If a precision obtained through C<*> is negative, it counts
8036 as having no precision at all.
8038 printf '<%.*s>', 7, "string"; # prints "<string>"
8039 printf '<%.*s>', 3, "string"; # prints "<str>"
8040 printf '<%.*s>', 0, "string"; # prints "<>"
8041 printf '<%.*s>', -1, "string"; # prints "<string>"
8043 printf '<%.*d>', 1, 0; # prints "<0>"
8044 printf '<%.*d>', 0, 0; # prints "<>"
8045 printf '<%.*d>', -1, 0; # prints "<0>"
8049 For numeric conversions, you can specify the size to interpret the
8050 number as using C<l>, C<h>, C<V>, C<q>, C<L>, or C<ll>. For integer
8051 conversions (C<d u o x X b i D U O>), numbers are usually assumed to be
8052 whatever the default integer size is on your platform (usually 32 or 64
8053 bits), but you can override this to use instead one of the standard C types,
8054 as supported by the compiler used to build Perl:
8056 hh interpret integer as C type "char" or "unsigned
8057 char" on Perl 5.14 or later
8058 h interpret integer as C type "short" or
8060 j interpret integer as C type "intmax_t" on Perl
8061 5.14 or later; and only with a C99 compiler
8062 prior to Perl 5.30 (unportable)
8063 l interpret integer as C type "long" or
8065 q, L, or ll interpret integer as C type "long long",
8066 "unsigned long long", or "quad" (typically
8068 t interpret integer as C type "ptrdiff_t" on Perl
8070 z interpret integer as C type "size_t" on Perl 5.14
8073 As of 5.14, none of these raises an exception if they are not supported on
8074 your platform. However, if warnings are enabled, a warning of the
8075 L<C<printf>|warnings> warning class is issued on an unsupported
8076 conversion flag. Should you instead prefer an exception, do this:
8078 use warnings FATAL => "printf";
8080 If you would like to know about a version dependency before you
8081 start running the program, put something like this at its top:
8083 use 5.014; # for hh/j/t/z/ printf modifiers
8085 You can find out whether your Perl supports quads via L<Config>:
8088 if ($Config{use64bitint} eq "define"
8089 || $Config{longsize} >= 8) {
8090 print "Nice quads!\n";
8093 For floating-point conversions (C<e f g E F G>), numbers are usually assumed
8094 to be the default floating-point size on your platform (double or long double),
8095 but you can force "long double" with C<q>, C<L>, or C<ll> if your
8096 platform supports them. You can find out whether your Perl supports long
8097 doubles via L<Config>:
8100 print "long doubles\n" if $Config{d_longdbl} eq "define";
8102 You can find out whether Perl considers "long double" to be the default
8103 floating-point size to use on your platform via L<Config>:
8106 if ($Config{uselongdouble} eq "define") {
8107 print "long doubles by default\n";
8110 It can also be that long doubles and doubles are the same thing:
8113 ($Config{doublesize} == $Config{longdblsize}) &&
8114 print "doubles are long doubles\n";
8116 The size specifier C<V> has no effect for Perl code, but is supported for
8117 compatibility with XS code. It means "use the standard size for a Perl
8118 integer or floating-point number", which is the default.
8120 =item order of arguments
8122 Normally, L<C<sprintf>|/sprintf FORMAT, LIST> takes the next unused
8123 argument as the value to
8124 format for each format specification. If the format specification
8125 uses C<*> to require additional arguments, these are consumed from
8126 the argument list in the order they appear in the format
8127 specification I<before> the value to format. Where an argument is
8128 specified by an explicit index, this does not affect the normal
8129 order for the arguments, even when the explicitly specified index
8130 would have been the next argument.
8134 printf "<%*.*s>", $a, $b, $c;
8136 uses C<$a> for the width, C<$b> for the precision, and C<$c>
8137 as the value to format; while:
8139 printf '<%*1$.*s>', $a, $b;
8141 would use C<$a> for the width and precision, and C<$b> as the
8144 Here are some more examples; be aware that when using an explicit
8145 index, the C<$> may need escaping:
8147 printf "%2\$d %d\n", 12, 34; # will print "34 12\n"
8148 printf "%2\$d %d %d\n", 12, 34; # will print "34 12 34\n"
8149 printf "%3\$d %d %d\n", 12, 34, 56; # will print "56 12 34\n"
8150 printf "%2\$*3\$d %d\n", 12, 34, 3; # will print " 34 12\n"
8151 printf "%*1\$.*f\n", 4, 5, 10; # will print "5.0000\n"
8155 If L<C<use locale>|locale> (including C<use locale ':not_characters'>)
8156 is in effect and L<C<POSIX::setlocale>|POSIX/C<setlocale>> has been
8158 the character used for the decimal separator in formatted floating-point
8159 numbers is affected by the C<LC_NUMERIC> locale. See L<perllocale>
8163 X<sqrt> X<root> X<square root>
8167 =for Pod::Functions square root function
8169 Return the positive square root of EXPR. If EXPR is omitted, uses
8170 L<C<$_>|perlvar/$_>. Works only for non-negative operands unless you've
8171 loaded the L<C<Math::Complex>|Math::Complex> module.
8174 print sqrt(-4); # prints 2i
8177 X<srand> X<seed> X<randseed>
8181 =for Pod::Functions seed the random number generator
8183 Sets and returns the random number seed for the L<C<rand>|/rand EXPR>
8186 The point of the function is to "seed" the L<C<rand>|/rand EXPR>
8187 function so that L<C<rand>|/rand EXPR> can produce a different sequence
8188 each time you run your program. When called with a parameter,
8189 L<C<srand>|/srand EXPR> uses that for the seed; otherwise it
8190 (semi-)randomly chooses a seed. In either case, starting with Perl 5.14,
8191 it returns the seed. To signal that your code will work I<only> on Perls
8192 of a recent vintage:
8194 use 5.014; # so srand returns the seed
8196 If L<C<srand>|/srand EXPR> is not called explicitly, it is called
8197 implicitly without a parameter at the first use of the
8198 L<C<rand>|/rand EXPR> operator. However, there are a few situations
8199 where programs are likely to want to call L<C<srand>|/srand EXPR>. One
8200 is for generating predictable results, generally for testing or
8201 debugging. There, you use C<srand($seed)>, with the same C<$seed> each
8202 time. Another case is that you may want to call L<C<srand>|/srand EXPR>
8203 after a L<C<fork>|/fork> to avoid child processes sharing the same seed
8204 value as the parent (and consequently each other).
8206 Do B<not> call C<srand()> (i.e., without an argument) more than once per
8207 process. The internal state of the random number generator should
8208 contain more entropy than can be provided by any seed, so calling
8209 L<C<srand>|/srand EXPR> again actually I<loses> randomness.
8211 Most implementations of L<C<srand>|/srand EXPR> take an integer and will
8213 truncate decimal numbers. This means C<srand(42)> will usually
8214 produce the same results as C<srand(42.1)>. To be safe, always pass
8215 L<C<srand>|/srand EXPR> an integer.
8217 A typical use of the returned seed is for a test program which has too many
8218 combinations to test comprehensively in the time available to it each run. It
8219 can test a random subset each time, and should there be a failure, log the seed
8220 used for that run so that it can later be used to reproduce the same results.
8222 B<L<C<rand>|/rand EXPR> is not cryptographically secure. You should not rely
8223 on it in security-sensitive situations.> As of this writing, a
8224 number of third-party CPAN modules offer random number generators
8225 intended by their authors to be cryptographically secure,
8226 including: L<Data::Entropy>, L<Crypt::Random>, L<Math::Random::Secure>,
8227 and L<Math::TrulyRandom>.
8229 =item stat FILEHANDLE
8230 X<stat> X<file, status> X<ctime>
8234 =item stat DIRHANDLE
8238 =for Pod::Functions get a file's status information
8240 Returns a 13-element list giving the status info for a file, either
8241 the file opened via FILEHANDLE or DIRHANDLE, or named by EXPR. If EXPR is
8242 omitted, it stats L<C<$_>|perlvar/$_> (not C<_>!). Returns the empty
8243 list if L<C<stat>|/stat FILEHANDLE> fails. Typically
8246 my ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size,
8247 $atime,$mtime,$ctime,$blksize,$blocks)
8250 Not all fields are supported on all filesystem types. Here are the
8251 meanings of the fields:
8253 0 dev device number of filesystem
8255 2 mode file mode (type and permissions)
8256 3 nlink number of (hard) links to the file
8257 4 uid numeric user ID of file's owner
8258 5 gid numeric group ID of file's owner
8259 6 rdev the device identifier (special files only)
8260 7 size total size of file, in bytes
8261 8 atime last access time in seconds since the epoch
8262 9 mtime last modify time in seconds since the epoch
8263 10 ctime inode change time in seconds since the epoch (*)
8264 11 blksize preferred I/O size in bytes for interacting with the
8265 file (may vary from file to file)
8266 12 blocks actual number of system-specific blocks allocated
8267 on disk (often, but not always, 512 bytes each)
8269 (The epoch was at 00:00 January 1, 1970 GMT.)
8271 (*) Not all fields are supported on all filesystem types. Notably, the
8272 ctime field is non-portable. In particular, you cannot expect it to be a
8273 "creation time"; see L<perlport/"Files and Filesystems"> for details.
8275 If L<C<stat>|/stat FILEHANDLE> is passed the special filehandle
8276 consisting of an underline, no stat is done, but the current contents of
8277 the stat structure from the last L<C<stat>|/stat FILEHANDLE>,
8278 L<C<lstat>|/lstat FILEHANDLE>, or filetest are returned. Example:
8280 if (-x $file && (($d) = stat(_)) && $d < 0) {
8281 print "$file is executable NFS file\n";
8284 (This works on machines only for which the device number is negative
8287 On some platforms inode numbers are of a type larger than perl knows how
8288 to handle as integer numerical values. If necessary, an inode number will
8289 be returned as a decimal string in order to preserve the entire value.
8290 If used in a numeric context, this will be converted to a floating-point
8291 numerical value, with rounding, a fate that is best avoided. Therefore,
8292 you should prefer to compare inode numbers using C<eq> rather than C<==>.
8293 C<eq> will work fine on inode numbers that are represented numerically,
8294 as well as those represented as strings.
8296 Because the mode contains both the file type and its permissions, you
8297 should mask off the file type portion and (s)printf using a C<"%o">
8298 if you want to see the real permissions.
8300 my $mode = (stat($filename))[2];
8301 printf "Permissions are %04o\n", $mode & 07777;
8303 In scalar context, L<C<stat>|/stat FILEHANDLE> returns a boolean value
8305 or failure, and, if successful, sets the information associated with
8306 the special filehandle C<_>.
8308 The L<File::stat> module provides a convenient, by-name access mechanism:
8311 my $sb = stat($filename);
8312 printf "File is %s, size is %s, perm %04o, mtime %s\n",
8313 $filename, $sb->size, $sb->mode & 07777,
8314 scalar localtime $sb->mtime;
8316 You can import symbolic mode constants (C<S_IF*>) and functions
8317 (C<S_IS*>) from the L<Fcntl> module:
8321 my $mode = (stat($filename))[2];
8323 my $user_rwx = ($mode & S_IRWXU) >> 6;
8324 my $group_read = ($mode & S_IRGRP) >> 3;
8325 my $other_execute = $mode & S_IXOTH;
8327 printf "Permissions are %04o\n", S_IMODE($mode), "\n";
8329 my $is_setuid = $mode & S_ISUID;
8330 my $is_directory = S_ISDIR($mode);
8332 You could write the last two using the C<-u> and C<-d> operators.
8333 Commonly available C<S_IF*> constants are:
8335 # Permissions: read, write, execute, for user, group, others.
8337 S_IRWXU S_IRUSR S_IWUSR S_IXUSR
8338 S_IRWXG S_IRGRP S_IWGRP S_IXGRP
8339 S_IRWXO S_IROTH S_IWOTH S_IXOTH
8341 # Setuid/Setgid/Stickiness/SaveText.
8342 # Note that the exact meaning of these is system-dependent.
8344 S_ISUID S_ISGID S_ISVTX S_ISTXT
8346 # File types. Not all are necessarily available on
8349 S_IFREG S_IFDIR S_IFLNK S_IFBLK S_IFCHR
8350 S_IFIFO S_IFSOCK S_IFWHT S_ENFMT
8352 # The following are compatibility aliases for S_IRUSR,
8353 # S_IWUSR, and S_IXUSR.
8355 S_IREAD S_IWRITE S_IEXEC
8357 and the C<S_IF*> functions are
8359 S_IMODE($mode) the part of $mode containing the permission
8360 bits and the setuid/setgid/sticky bits
8362 S_IFMT($mode) the part of $mode containing the file type
8363 which can be bit-anded with (for example)
8364 S_IFREG or with the following functions
8366 # The operators -f, -d, -l, -b, -c, -p, and -S.
8368 S_ISREG($mode) S_ISDIR($mode) S_ISLNK($mode)
8369 S_ISBLK($mode) S_ISCHR($mode) S_ISFIFO($mode) S_ISSOCK($mode)
8371 # No direct -X operator counterpart, but for the first one
8372 # the -g operator is often equivalent. The ENFMT stands for
8373 # record flocking enforcement, a platform-dependent feature.
8375 S_ISENFMT($mode) S_ISWHT($mode)
8377 See your native L<chmod(2)> and L<stat(2)> documentation for more details
8378 about the C<S_*> constants. To get status info for a symbolic link
8379 instead of the target file behind the link, use the
8380 L<C<lstat>|/lstat FILEHANDLE> function.
8382 Portability issues: L<perlport/stat>.
8387 =item state TYPE VARLIST
8389 =item state VARLIST : ATTRS
8391 =item state TYPE VARLIST : ATTRS
8393 =for Pod::Functions +state declare and assign a persistent lexical variable
8395 L<C<state>|/state VARLIST> declares a lexically scoped variable, just
8396 like L<C<my>|/my VARLIST>.
8397 However, those variables will never be reinitialized, contrary to
8398 lexical variables that are reinitialized each time their enclosing block
8400 See L<perlsub/"Persistent Private Variables"> for details.
8402 If more than one variable is listed, the list must be placed in
8403 parentheses. With a parenthesised list, L<C<undef>|/undef EXPR> can be
8405 dummy placeholder. However, since initialization of state variables in
8406 such lists is currently not possible this would serve no purpose.
8408 L<C<state>|/state VARLIST> is available only if the
8409 L<C<"state"> feature|feature/The 'state' feature> is enabled or if it is
8410 prefixed with C<CORE::>. The
8411 L<C<"state"> feature|feature/The 'state' feature> is enabled
8412 automatically with a C<use v5.10> (or higher) declaration in the current
8421 =for Pod::Functions no-op, formerly optimized input data for repeated searches
8423 At this time, C<study> does nothing. This may change in the future.
8425 Prior to Perl version 5.16, it would create an inverted index of all characters
8426 that occurred in the given SCALAR (or L<C<$_>|perlvar/$_> if unspecified). When
8427 matching a pattern, the rarest character from the pattern would be looked up in
8428 this index. Rarity was based on some static frequency tables constructed from
8429 some C programs and English text.
8432 =item sub NAME BLOCK
8435 =item sub NAME (PROTO) BLOCK
8437 =item sub NAME : ATTRS BLOCK
8439 =item sub NAME (PROTO) : ATTRS BLOCK
8441 =for Pod::Functions declare a subroutine, possibly anonymously
8443 This is subroutine definition, not a real function I<per se>. Without a
8444 BLOCK it's just a forward declaration. Without a NAME, it's an anonymous
8445 function declaration, so does return a value: the CODE ref of the closure
8448 See L<perlsub> and L<perlref> for details about subroutines and
8449 references; see L<attributes> and L<Attribute::Handlers> for more
8450 information about attributes.
8455 =for Pod::Functions +current_sub the current subroutine, or C<undef> if not in a subroutine
8457 A special token that returns a reference to the current subroutine, or
8458 L<C<undef>|/undef EXPR> outside of a subroutine.
8460 The behaviour of L<C<__SUB__>|/__SUB__> within a regex code block (such
8461 as C</(?{...})/>) is subject to change.
8463 This token is only available under C<use v5.16> or the
8464 L<C<"current_sub"> feature|feature/The 'current_sub' feature>.
8467 =item substr EXPR,OFFSET,LENGTH,REPLACEMENT
8468 X<substr> X<substring> X<mid> X<left> X<right>
8470 =item substr EXPR,OFFSET,LENGTH
8472 =item substr EXPR,OFFSET
8474 =for Pod::Functions get or alter a portion of a string
8476 Extracts a substring out of EXPR and returns it. First character is at
8477 offset zero. If OFFSET is negative, starts
8478 that far back from the end of the string. If LENGTH is omitted, returns
8479 everything through the end of the string. If LENGTH is negative, leaves that
8480 many characters off the end of the string.
8482 my $s = "The black cat climbed the green tree";
8483 my $color = substr $s, 4, 5; # black
8484 my $middle = substr $s, 4, -11; # black cat climbed the
8485 my $end = substr $s, 14; # climbed the green tree
8486 my $tail = substr $s, -4; # tree
8487 my $z = substr $s, -4, 2; # tr
8489 You can use the L<C<substr>|/substr EXPR,OFFSET,LENGTH,REPLACEMENT>
8490 function as an lvalue, in which case EXPR
8491 must itself be an lvalue. If you assign something shorter than LENGTH,
8492 the string will shrink, and if you assign something longer than LENGTH,
8493 the string will grow to accommodate it. To keep the string the same
8494 length, you may need to pad or chop your value using
8495 L<C<sprintf>|/sprintf FORMAT, LIST>.
8497 If OFFSET and LENGTH specify a substring that is partly outside the
8498 string, only the part within the string is returned. If the substring
8499 is beyond either end of the string,
8500 L<C<substr>|/substr EXPR,OFFSET,LENGTH,REPLACEMENT> returns the undefined
8501 value and produces a warning. When used as an lvalue, specifying a
8502 substring that is entirely outside the string raises an exception.
8503 Here's an example showing the behavior for boundary cases:
8506 substr($name, 4) = 'dy'; # $name is now 'freddy'
8507 my $null = substr $name, 6, 2; # returns "" (no warning)
8508 my $oops = substr $name, 7; # returns undef, with warning
8509 substr($name, 7) = 'gap'; # raises an exception
8511 An alternative to using
8512 L<C<substr>|/substr EXPR,OFFSET,LENGTH,REPLACEMENT> as an lvalue is to
8514 replacement string as the 4th argument. This allows you to replace
8515 parts of the EXPR and return what was there before in one operation,
8516 just as you can with
8517 L<C<splice>|/splice ARRAY,OFFSET,LENGTH,LIST>.
8519 my $s = "The black cat climbed the green tree";
8520 my $z = substr $s, 14, 7, "jumped from"; # climbed
8521 # $s is now "The black cat jumped from the green tree"
8523 Note that the lvalue returned by the three-argument version of
8524 L<C<substr>|/substr EXPR,OFFSET,LENGTH,REPLACEMENT> acts as
8525 a 'magic bullet'; each time it is assigned to, it remembers which part
8526 of the original string is being modified; for example:
8529 for (substr($x,1,2)) {
8530 $_ = 'a'; print $x,"\n"; # prints 1a4
8531 $_ = 'xyz'; print $x,"\n"; # prints 1xyz4
8533 $_ = 'pq'; print $x,"\n"; # prints 5pq9
8536 With negative offsets, it remembers its position from the end of the string
8537 when the target string is modified:
8540 for (substr($x, -3, 2)) {
8541 $_ = 'a'; print $x,"\n"; # prints 1a4, as above
8543 print $_,"\n"; # prints f
8546 Prior to Perl version 5.10, the result of using an lvalue multiple times was
8547 unspecified. Prior to 5.16, the result with negative offsets was
8550 =item symlink OLDFILE,NEWFILE
8551 X<symlink> X<link> X<symbolic link> X<link, symbolic>
8553 =for Pod::Functions create a symbolic link to a file
8555 Creates a new filename symbolically linked to the old filename.
8556 Returns C<1> for success, C<0> otherwise. On systems that don't support
8557 symbolic links, raises an exception. To check for that,
8560 my $symlink_exists = eval { symlink("",""); 1 };
8562 Portability issues: L<perlport/symlink>.
8564 =item syscall NUMBER, LIST
8565 X<syscall> X<system call>
8567 =for Pod::Functions execute an arbitrary system call
8569 Calls the system call specified as the first element of the list,
8570 passing the remaining elements as arguments to the system call. If
8571 unimplemented, raises an exception. The arguments are interpreted
8572 as follows: if a given argument is numeric, the argument is passed as
8573 an int. If not, the pointer to the string value is passed. You are
8574 responsible to make sure a string is pre-extended long enough to
8575 receive any result that might be written into a string. You can't use a
8576 string literal (or other read-only string) as an argument to
8577 L<C<syscall>|/syscall NUMBER, LIST> because Perl has to assume that any
8578 string pointer might be written through. If your
8579 integer arguments are not literals and have never been interpreted in a
8580 numeric context, you may need to add C<0> to them to force them to look
8581 like numbers. This emulates the
8582 L<C<syswrite>|/syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET> function (or
8585 require 'syscall.ph'; # may need to run h2ph
8586 my $s = "hi there\n";
8587 syscall(SYS_write(), fileno(STDOUT), $s, length $s);
8589 Note that Perl supports passing of up to only 14 arguments to your syscall,
8590 which in practice should (usually) suffice.
8592 Syscall returns whatever value returned by the system call it calls.
8593 If the system call fails, L<C<syscall>|/syscall NUMBER, LIST> returns
8594 C<-1> and sets L<C<$!>|perlvar/$!> (errno).
8595 Note that some system calls I<can> legitimately return C<-1>. The proper
8596 way to handle such calls is to assign C<$! = 0> before the call, then
8597 check the value of L<C<$!>|perlvar/$!> if
8598 L<C<syscall>|/syscall NUMBER, LIST> returns C<-1>.
8600 There's a problem with C<syscall(SYS_pipe())>: it returns the file
8601 number of the read end of the pipe it creates, but there is no way
8602 to retrieve the file number of the other end. You can avoid this
8603 problem by using L<C<pipe>|/pipe READHANDLE,WRITEHANDLE> instead.
8605 Portability issues: L<perlport/syscall>.
8607 =item sysopen FILEHANDLE,FILENAME,MODE
8610 =item sysopen FILEHANDLE,FILENAME,MODE,PERMS
8612 =for Pod::Functions +5.002 open a file, pipe, or descriptor
8614 Opens the file whose filename is given by FILENAME, and associates it with
8615 FILEHANDLE. If FILEHANDLE is an expression, its value is used as the real
8616 filehandle wanted; an undefined scalar will be suitably autovivified. This
8617 function calls the underlying operating system's L<open(2)> function with the
8618 parameters FILENAME, MODE, and PERMS.
8620 Returns true on success and L<C<undef>|/undef EXPR> otherwise.
8622 The possible values and flag bits of the MODE parameter are
8623 system-dependent; they are available via the standard module
8624 L<C<Fcntl>|Fcntl>. See the documentation of your operating system's
8625 L<open(2)> syscall to see
8626 which values and flag bits are available. You may combine several flags
8627 using the C<|>-operator.
8629 Some of the most common values are C<O_RDONLY> for opening the file in
8630 read-only mode, C<O_WRONLY> for opening the file in write-only mode,
8631 and C<O_RDWR> for opening the file in read-write mode.
8632 X<O_RDONLY> X<O_RDWR> X<O_WRONLY>
8634 For historical reasons, some values work on almost every system
8635 supported by Perl: 0 means read-only, 1 means write-only, and 2
8636 means read/write. We know that these values do I<not> work under
8637 OS/390 and on the Macintosh; you probably don't want to
8638 use them in new code.
8640 If the file named by FILENAME does not exist and the
8641 L<C<open>|/open FILEHANDLE,EXPR> call creates
8642 it (typically because MODE includes the C<O_CREAT> flag), then the value of
8643 PERMS specifies the permissions of the newly created file. If you omit
8644 the PERMS argument to L<C<sysopen>|/sysopen FILEHANDLE,FILENAME,MODE>,
8645 Perl uses the octal value C<0666>.
8646 These permission values need to be in octal, and are modified by your
8647 process's current L<C<umask>|/umask EXPR>.
8650 In many systems the C<O_EXCL> flag is available for opening files in
8651 exclusive mode. This is B<not> locking: exclusiveness means here that
8652 if the file already exists,
8653 L<C<sysopen>|/sysopen FILEHANDLE,FILENAME,MODE> fails. C<O_EXCL> may
8655 on network filesystems, and has no effect unless the C<O_CREAT> flag
8656 is set as well. Setting C<O_CREAT|O_EXCL> prevents the file from
8657 being opened if it is a symbolic link. It does not protect against
8658 symbolic links in the file's path.
8661 Sometimes you may want to truncate an already-existing file. This
8662 can be done using the C<O_TRUNC> flag. The behavior of
8663 C<O_TRUNC> with C<O_RDONLY> is undefined.
8666 You should seldom if ever use C<0644> as argument to
8667 L<C<sysopen>|/sysopen FILEHANDLE,FILENAME,MODE>, because
8668 that takes away the user's option to have a more permissive umask.
8669 Better to omit it. See L<C<umask>|/umask EXPR> for more on this.
8671 Note that under Perls older than 5.8.0,
8672 L<C<sysopen>|/sysopen FILEHANDLE,FILENAME,MODE> depends on the
8673 L<fdopen(3)> C library function. On many Unix systems, L<fdopen(3)> is known
8674 to fail when file descriptors exceed a certain value, typically 255. If
8675 you need more file descriptors than that, consider using the
8676 L<C<POSIX::open>|POSIX/C<open>> function. For Perls 5.8.0 and later,
8677 PerlIO is (most often) the default.
8679 See L<perlopentut> for a kinder, gentler explanation of opening files.
8681 Portability issues: L<perlport/sysopen>.
8683 =item sysread FILEHANDLE,SCALAR,LENGTH,OFFSET
8686 =item sysread FILEHANDLE,SCALAR,LENGTH
8688 =for Pod::Functions fixed-length unbuffered input from a filehandle
8690 Attempts to read LENGTH bytes of data into variable SCALAR from the
8691 specified FILEHANDLE, using L<read(2)>. It bypasses
8692 buffered IO, so mixing this with other kinds of reads,
8693 L<C<print>|/print FILEHANDLE LIST>, L<C<write>|/write FILEHANDLE>,
8694 L<C<seek>|/seek FILEHANDLE,POSITION,WHENCE>,
8695 L<C<tell>|/tell FILEHANDLE>, or L<C<eof>|/eof FILEHANDLE> can cause
8696 confusion because the
8697 perlio or stdio layers usually buffer data. Returns the number of
8698 bytes actually read, C<0> at end of file, or undef if there was an
8699 error (in the latter case L<C<$!>|perlvar/$!> is also set). SCALAR will
8701 shrunk so that the last byte actually read is the last byte of the
8702 scalar after the read.
8704 An OFFSET may be specified to place the read data at some place in the
8705 string other than the beginning. A negative OFFSET specifies
8706 placement at that many characters counting backwards from the end of
8707 the string. A positive OFFSET greater than the length of SCALAR
8708 results in the string being padded to the required size with C<"\0">
8709 bytes before the result of the read is appended.
8711 There is no syseof() function, which is ok, since
8712 L<C<eof>|/eof FILEHANDLE> doesn't work well on device files (like ttys)
8713 anyway. Use L<C<sysread>|/sysread FILEHANDLE,SCALAR,LENGTH,OFFSET> and
8714 check for a return value of 0 to decide whether you're done.
8716 Note that if the filehandle has been marked as C<:utf8>, C<sysread> will
8717 throw an exception. The C<:encoding(...)> layer implicitly
8718 introduces the C<:utf8> layer. See
8719 L<C<binmode>|/binmode FILEHANDLE, LAYER>,
8720 L<C<open>|/open FILEHANDLE,EXPR>, and the L<open> pragma.
8722 =item sysseek FILEHANDLE,POSITION,WHENCE
8725 =for Pod::Functions +5.004 position I/O pointer on handle used with sysread and syswrite
8727 Sets FILEHANDLE's system position I<in bytes> using L<lseek(2)>. FILEHANDLE may
8728 be an expression whose value gives the name of the filehandle. The values
8729 for WHENCE are C<0> to set the new position to POSITION; C<1> to set the it
8730 to the current position plus POSITION; and C<2> to set it to EOF plus
8731 POSITION, typically negative.
8733 Note the emphasis on bytes: even if the filehandle has been set to operate
8734 on characters (for example using the C<:encoding(UTF-8)> I/O layer), the
8735 L<C<seek>|/seek FILEHANDLE,POSITION,WHENCE>,
8736 L<C<tell>|/tell FILEHANDLE>, and
8737 L<C<sysseek>|/sysseek FILEHANDLE,POSITION,WHENCE>
8738 family of functions use byte offsets, not character offsets,
8739 because seeking to a character offset would be very slow in a UTF-8 file.
8741 L<C<sysseek>|/sysseek FILEHANDLE,POSITION,WHENCE> bypasses normal
8742 buffered IO, so mixing it with reads other than
8743 L<C<sysread>|/sysread FILEHANDLE,SCALAR,LENGTH,OFFSET> (for example
8744 L<C<readline>|/readline EXPR> or
8745 L<C<read>|/read FILEHANDLE,SCALAR,LENGTH,OFFSET>),
8746 L<C<print>|/print FILEHANDLE LIST>, L<C<write>|/write FILEHANDLE>,
8747 L<C<seek>|/seek FILEHANDLE,POSITION,WHENCE>,
8748 L<C<tell>|/tell FILEHANDLE>, or L<C<eof>|/eof FILEHANDLE> may cause
8751 For WHENCE, you may also use the constants C<SEEK_SET>, C<SEEK_CUR>,
8752 and C<SEEK_END> (start of the file, current position, end of the file)
8753 from the L<Fcntl> module. Use of the constants is also more portable
8754 than relying on 0, 1, and 2. For example to define a "systell" function:
8756 use Fcntl 'SEEK_CUR';
8757 sub systell { sysseek($_[0], 0, SEEK_CUR) }
8759 Returns the new position, or the undefined value on failure. A position
8760 of zero is returned as the string C<"0 but true">; thus
8761 L<C<sysseek>|/sysseek FILEHANDLE,POSITION,WHENCE> returns
8762 true on success and false on failure, yet you can still easily determine
8768 =item system PROGRAM LIST
8770 =for Pod::Functions run a separate program
8772 Does exactly the same thing as L<C<exec>|/exec LIST>, except that a fork is
8773 done first and the parent process waits for the child process to
8774 exit. Note that argument processing varies depending on the
8775 number of arguments. If there is more than one argument in LIST,
8776 or if LIST is an array with more than one value, starts the program
8777 given by the first element of the list with arguments given by the
8778 rest of the list. If there is only one scalar argument, the argument
8779 is checked for shell metacharacters, and if there are any, the
8780 entire argument is passed to the system's command shell for parsing
8781 (this is C</bin/sh -c> on Unix platforms, but varies on other
8782 platforms). If there are no shell metacharacters in the argument,
8783 it is split into words and passed directly to C<execvp>, which is
8784 more efficient. On Windows, only the C<system PROGRAM LIST> syntax will
8785 reliably avoid using the shell; C<system LIST>, even with more than one
8786 element, will fall back to the shell if the first spawn fails.
8788 Perl will attempt to flush all files opened for
8789 output before any operation that may do a fork, but this may not be
8790 supported on some platforms (see L<perlport>). To be safe, you may need
8791 to set L<C<$E<verbar>>|perlvar/$E<verbar>> (C<$AUTOFLUSH> in L<English>)
8792 or call the C<autoflush> method of L<C<IO::Handle>|IO::Handle/METHODS>
8793 on any open handles.
8795 The return value is the exit status of the program as returned by the
8796 L<C<wait>|/wait> call. To get the actual exit value, shift right by
8797 eight (see below). See also L<C<exec>|/exec LIST>. This is I<not> what
8798 you want to use to capture the output from a command; for that you
8799 should use merely backticks or
8800 L<C<qxE<sol>E<sol>>|/qxE<sol>STRINGE<sol>>, as described in
8801 L<perlop/"`STRING`">. Return value of -1 indicates a failure to start
8802 the program or an error of the L<wait(2)> system call (inspect
8803 L<C<$!>|perlvar/$!> for the reason).
8805 If you'd like to make L<C<system>|/system LIST> (and many other bits of
8806 Perl) die on error, have a look at the L<autodie> pragma.
8808 Like L<C<exec>|/exec LIST>, L<C<system>|/system LIST> allows you to lie
8809 to a program about its name if you use the C<system PROGRAM LIST>
8810 syntax. Again, see L<C<exec>|/exec LIST>.
8812 Since C<SIGINT> and C<SIGQUIT> are ignored during the execution of
8813 L<C<system>|/system LIST>, if you expect your program to terminate on
8814 receipt of these signals you will need to arrange to do so yourself
8815 based on the return value.
8817 my @args = ("command", "arg1", "arg2");
8819 or die "system @args failed: $?";
8821 If you'd like to manually inspect L<C<system>|/system LIST>'s failure,
8822 you can check all possible failure modes by inspecting
8823 L<C<$?>|perlvar/$?> like this:
8826 print "failed to execute: $!\n";
8829 printf "child died with signal %d, %s coredump\n",
8830 ($? & 127), ($? & 128) ? 'with' : 'without';
8833 printf "child exited with value %d\n", $? >> 8;
8836 Alternatively, you may inspect the value of
8837 L<C<${^CHILD_ERROR_NATIVE}>|perlvar/${^CHILD_ERROR_NATIVE}> with the
8838 L<C<W*()>|POSIX/C<WIFEXITED>> calls from the L<POSIX> module.
8840 When L<C<system>|/system LIST>'s arguments are executed indirectly by
8841 the shell, results and return codes are subject to its quirks.
8842 See L<perlop/"`STRING`"> and L<C<exec>|/exec LIST> for details.
8844 Since L<C<system>|/system LIST> does a L<C<fork>|/fork> and
8845 L<C<wait>|/wait> it may affect a C<SIGCHLD> handler. See L<perlipc> for
8848 Portability issues: L<perlport/system>.
8850 =item syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET
8853 =item syswrite FILEHANDLE,SCALAR,LENGTH
8855 =item syswrite FILEHANDLE,SCALAR
8857 =for Pod::Functions fixed-length unbuffered output to a filehandle
8859 Attempts to write LENGTH bytes of data from variable SCALAR to the
8860 specified FILEHANDLE, using L<write(2)>. If LENGTH is
8861 not specified, writes whole SCALAR. It bypasses buffered IO, so
8862 mixing this with reads (other than C<sysread)>),
8863 L<C<print>|/print FILEHANDLE LIST>, L<C<write>|/write FILEHANDLE>,
8864 L<C<seek>|/seek FILEHANDLE,POSITION,WHENCE>,
8865 L<C<tell>|/tell FILEHANDLE>, or L<C<eof>|/eof FILEHANDLE> may cause
8866 confusion because the perlio and stdio layers usually buffer data.
8867 Returns the number of bytes actually written, or L<C<undef>|/undef EXPR>
8868 if there was an error (in this case the errno variable
8869 L<C<$!>|perlvar/$!> is also set). If the LENGTH is greater than the
8870 data available in the SCALAR after the OFFSET, only as much data as is
8871 available will be written.
8873 An OFFSET may be specified to write the data from some part of the
8874 string other than the beginning. A negative OFFSET specifies writing
8875 that many characters counting backwards from the end of the string.
8876 If SCALAR is of length zero, you can only use an OFFSET of 0.
8878 B<WARNING>: If the filehandle is marked C<:utf8>, C<syswrite> will raise an exception.
8879 The C<:encoding(...)> layer implicitly introduces the C<:utf8> layer.
8880 Alternately, if the handle is not marked with an encoding but you
8881 attempt to write characters with code points over 255, raises an exception.
8882 See L<C<binmode>|/binmode FILEHANDLE, LAYER>,
8883 L<C<open>|/open FILEHANDLE,EXPR>, and the L<open> pragma.
8885 =item tell FILEHANDLE
8890 =for Pod::Functions get current seekpointer on a filehandle
8892 Returns the current position I<in bytes> for FILEHANDLE, or -1 on
8893 error. FILEHANDLE may be an expression whose value gives the name of
8894 the actual filehandle. If FILEHANDLE is omitted, assumes the file
8897 Note the emphasis on bytes: even if the filehandle has been set to operate
8898 on characters (for example using the C<:encoding(UTF-8)> I/O layer), the
8899 L<C<seek>|/seek FILEHANDLE,POSITION,WHENCE>,
8900 L<C<tell>|/tell FILEHANDLE>, and
8901 L<C<sysseek>|/sysseek FILEHANDLE,POSITION,WHENCE>
8902 family of functions use byte offsets, not character offsets,
8903 because seeking to a character offset would be very slow in a UTF-8 file.
8905 The return value of L<C<tell>|/tell FILEHANDLE> for the standard streams
8906 like the STDIN depends on the operating system: it may return -1 or
8907 something else. L<C<tell>|/tell FILEHANDLE> on pipes, fifos, and
8908 sockets usually returns -1.
8910 There is no C<systell> function. Use
8911 L<C<sysseek($fh, 0, 1)>|/sysseek FILEHANDLE,POSITION,WHENCE> for that.
8913 Do not use L<C<tell>|/tell FILEHANDLE> (or other buffered I/O
8914 operations) on a filehandle that has been manipulated by
8915 L<C<sysread>|/sysread FILEHANDLE,SCALAR,LENGTH,OFFSET>,
8916 L<C<syswrite>|/syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET>, or
8917 L<C<sysseek>|/sysseek FILEHANDLE,POSITION,WHENCE>. Those functions
8918 ignore the buffering, while L<C<tell>|/tell FILEHANDLE> does not.
8920 =item telldir DIRHANDLE
8923 =for Pod::Functions get current seekpointer on a directory handle
8925 Returns the current position of the L<C<readdir>|/readdir DIRHANDLE>
8926 routines on DIRHANDLE. Value may be given to
8927 L<C<seekdir>|/seekdir DIRHANDLE,POS> to access a particular location in
8928 a directory. L<C<telldir>|/telldir DIRHANDLE> has the same caveats
8929 about possible directory compaction as the corresponding system library
8932 =item tie VARIABLE,CLASSNAME,LIST
8935 =for Pod::Functions +5.002 bind a variable to an object class
8937 This function binds a variable to a package class that will provide the
8938 implementation for the variable. VARIABLE is the name of the variable
8939 to be enchanted. CLASSNAME is the name of a class implementing objects
8940 of correct type. Any additional arguments are passed to the
8941 appropriate constructor
8942 method of the class (meaning C<TIESCALAR>, C<TIEHANDLE>, C<TIEARRAY>,
8943 or C<TIEHASH>). Typically these are arguments such as might be passed
8944 to the L<dbm_open(3)> function of C. The object returned by the
8945 constructor is also returned by the
8946 L<C<tie>|/tie VARIABLE,CLASSNAME,LIST> function, which would be useful
8947 if you want to access other methods in CLASSNAME.
8949 Note that functions such as L<C<keys>|/keys HASH> and
8950 L<C<values>|/values HASH> may return huge lists when used on large
8951 objects, like DBM files. You may prefer to use the L<C<each>|/each
8952 HASH> function to iterate over such. Example:
8954 # print out history file offsets
8956 tie(my %HIST, 'NDBM_File', '/usr/lib/news/history', 1, 0);
8957 while (my ($key,$val) = each %HIST) {
8958 print $key, ' = ', unpack('L', $val), "\n";
8961 A class implementing a hash should have the following methods:
8963 TIEHASH classname, LIST
8965 STORE this, key, value
8970 NEXTKEY this, lastkey
8975 A class implementing an ordinary array should have the following methods:
8977 TIEARRAY classname, LIST
8979 STORE this, key, value
8981 STORESIZE this, count
8987 SPLICE this, offset, length, LIST
8994 A class implementing a filehandle should have the following methods:
8996 TIEHANDLE classname, LIST
8997 READ this, scalar, length, offset
9000 WRITE this, scalar, length, offset
9002 PRINTF this, format, LIST
9006 SEEK this, position, whence
9008 OPEN this, mode, LIST
9013 A class implementing a scalar should have the following methods:
9015 TIESCALAR classname, LIST
9021 Not all methods indicated above need be implemented. See L<perltie>,
9022 L<Tie::Hash>, L<Tie::Array>, L<Tie::Scalar>, and L<Tie::Handle>.
9024 Unlike L<C<dbmopen>|/dbmopen HASH,DBNAME,MASK>, the
9025 L<C<tie>|/tie VARIABLE,CLASSNAME,LIST> function will not
9026 L<C<use>|/use Module VERSION LIST> or L<C<require>|/require VERSION> a
9027 module for you; you need to do that explicitly yourself. See L<DB_File>
9028 or the L<Config> module for interesting
9029 L<C<tie>|/tie VARIABLE,CLASSNAME,LIST> implementations.
9031 For further details see L<perltie>, L<C<tied>|/tied VARIABLE>.
9036 =for Pod::Functions get a reference to the object underlying a tied variable
9038 Returns a reference to the object underlying VARIABLE (the same value
9039 that was originally returned by the
9040 L<C<tie>|/tie VARIABLE,CLASSNAME,LIST> call that bound the variable
9041 to a package.) Returns the undefined value if VARIABLE isn't tied to a
9047 =for Pod::Functions return number of seconds since 1970
9049 Returns the number of non-leap seconds since whatever time the system
9050 considers to be the epoch, suitable for feeding to
9051 L<C<gmtime>|/gmtime EXPR> and L<C<localtime>|/localtime EXPR>. On most
9052 systems the epoch is 00:00:00 UTC, January 1, 1970;
9053 a prominent exception being Mac OS Classic which uses 00:00:00, January 1,
9054 1904 in the current local time zone for its epoch.
9056 For measuring time in better granularity than one second, use the
9057 L<Time::HiRes> module from Perl 5.8 onwards (or from CPAN before then), or,
9058 if you have L<gettimeofday(2)>, you may be able to use the
9059 L<C<syscall>|/syscall NUMBER, LIST> interface of Perl. See L<perlfaq8>
9062 For date and time processing look at the many related modules on CPAN.
9063 For a comprehensive date and time representation look at the
9069 =for Pod::Functions return elapsed time for self and child processes
9071 Returns a four-element list giving the user and system times in
9072 seconds for this process and any exited children of this process.
9074 my ($user,$system,$cuser,$csystem) = times;
9076 In scalar context, L<C<times>|/times> returns C<$user>.
9078 Children's times are only included for terminated children.
9080 Portability issues: L<perlport/times>.
9084 =for Pod::Functions transliterate a string
9086 The transliteration operator. Same as
9087 L<C<yE<sol>E<sol>E<sol>>|/yE<sol>E<sol>E<sol>>. See
9088 L<perlop/"Quote-Like Operators">.
9090 =item truncate FILEHANDLE,LENGTH
9093 =item truncate EXPR,LENGTH
9095 =for Pod::Functions shorten a file
9097 Truncates the file opened on FILEHANDLE, or named by EXPR, to the
9098 specified length. Raises an exception if truncate isn't implemented
9099 on your system. Returns true if successful, L<C<undef>|/undef EXPR> on
9102 The behavior is undefined if LENGTH is greater than the length of the
9105 The position in the file of FILEHANDLE is left unchanged. You may want to
9106 call L<seek|/"seek FILEHANDLE,POSITION,WHENCE"> before writing to the
9109 Portability issues: L<perlport/truncate>.
9112 X<uc> X<uppercase> X<toupper>
9116 =for Pod::Functions return upper-case version of a string
9118 Returns an uppercased version of EXPR. This is the internal function
9119 implementing the C<\U> escape in double-quoted strings.
9120 It does not attempt to do titlecase mapping on initial letters. See
9121 L<C<ucfirst>|/ucfirst EXPR> for that.
9123 If EXPR is omitted, uses L<C<$_>|perlvar/$_>.
9125 This function behaves the same way under various pragmas, such as in a locale,
9126 as L<C<lc>|/lc EXPR> does.
9129 X<ucfirst> X<uppercase>
9133 =for Pod::Functions return a string with just the next letter in upper case
9135 Returns the value of EXPR with the first character in uppercase
9136 (titlecase in Unicode). This is the internal function implementing
9137 the C<\u> escape in double-quoted strings.
9139 If EXPR is omitted, uses L<C<$_>|perlvar/$_>.
9141 This function behaves the same way under various pragmas, such as in a locale,
9142 as L<C<lc>|/lc EXPR> does.
9149 =for Pod::Functions set file creation mode mask
9151 Sets the umask for the process to EXPR and returns the previous value.
9152 If EXPR is omitted, merely returns the current umask.
9154 The Unix permission C<rwxr-x---> is represented as three sets of three
9155 bits, or three octal digits: C<0750> (the leading 0 indicates octal
9156 and isn't one of the digits). The L<C<umask>|/umask EXPR> value is such
9157 a number representing disabled permissions bits. The permission (or
9158 "mode") values you pass L<C<mkdir>|/mkdir FILENAME,MODE> or
9159 L<C<sysopen>|/sysopen FILEHANDLE,FILENAME,MODE> are modified by your
9160 umask, so even if you tell
9161 L<C<sysopen>|/sysopen FILEHANDLE,FILENAME,MODE> to create a file with
9162 permissions C<0777>, if your umask is C<0022>, then the file will
9163 actually be created with permissions C<0755>. If your
9164 L<C<umask>|/umask EXPR> were C<0027> (group can't write; others can't
9165 read, write, or execute), then passing
9166 L<C<sysopen>|/sysopen FILEHANDLE,FILENAME,MODE> C<0666> would create a
9167 file with mode C<0640> (because C<0666 &~ 027> is C<0640>).
9169 Here's some advice: supply a creation mode of C<0666> for regular
9170 files (in L<C<sysopen>|/sysopen FILEHANDLE,FILENAME,MODE>) and one of
9171 C<0777> for directories (in L<C<mkdir>|/mkdir FILENAME,MODE>) and
9172 executable files. This gives users the freedom of
9173 choice: if they want protected files, they might choose process umasks
9174 of C<022>, C<027>, or even the particularly antisocial mask of C<077>.
9175 Programs should rarely if ever make policy decisions better left to
9176 the user. The exception to this is when writing files that should be
9177 kept private: mail files, web browser cookies, F<.rhosts> files, and
9180 If L<umask(2)> is not implemented on your system and you are trying to
9181 restrict access for I<yourself> (i.e., C<< (EXPR & 0700) > 0 >>),
9182 raises an exception. If L<umask(2)> is not implemented and you are
9183 not trying to restrict access for yourself, returns
9184 L<C<undef>|/undef EXPR>.
9186 Remember that a umask is a number, usually given in octal; it is I<not> a
9187 string of octal digits. See also L<C<oct>|/oct EXPR>, if all you have
9190 Portability issues: L<perlport/umask>.
9193 X<undef> X<undefine>
9197 =for Pod::Functions remove a variable or function definition
9199 Undefines the value of EXPR, which must be an lvalue. Use only on a
9200 scalar value, an array (using C<@>), a hash (using C<%>), a subroutine
9201 (using C<&>), or a typeglob (using C<*>). Saying C<undef $hash{$key}>
9202 will probably not do what you expect on most predefined variables or
9203 DBM list values, so don't do that; see L<C<delete>|/delete EXPR>.
9204 Always returns the undefined value.
9205 You can omit the EXPR, in which case nothing is
9206 undefined, but you still get an undefined value that you could, for
9207 instance, return from a subroutine, assign to a variable, or pass as a
9208 parameter. Examples:
9211 undef $bar{'blurfl'}; # Compare to: delete $bar{'blurfl'};
9215 undef *xyz; # destroys $xyz, @xyz, %xyz, &xyz, etc.
9216 return (wantarray ? (undef, $errmsg) : undef) if $they_blew_it;
9217 select undef, undef, undef, 0.25;
9218 my ($x, $y, undef, $z) = foo(); # Ignore third value returned
9220 Note that this is a unary operator, not a list operator.
9223 X<unlink> X<delete> X<remove> X<rm> X<del>
9227 =for Pod::Functions remove one link to a file
9229 Deletes a list of files. On success, it returns the number of files
9230 it successfully deleted. On failure, it returns false and sets
9231 L<C<$!>|perlvar/$!> (errno):
9233 my $unlinked = unlink 'a', 'b', 'c';
9235 unlink glob "*.bak";
9237 On error, L<C<unlink>|/unlink LIST> will not tell you which files it
9239 If you want to know which files you could not remove, try them one
9242 foreach my $file ( @goners ) {
9243 unlink $file or warn "Could not unlink $file: $!";
9246 Note: L<C<unlink>|/unlink LIST> will not attempt to delete directories
9248 superuser and the B<-U> flag is supplied to Perl. Even if these
9249 conditions are met, be warned that unlinking a directory can inflict
9250 damage on your filesystem. Finally, using L<C<unlink>|/unlink LIST> on
9251 directories is not supported on many operating systems. Use
9252 L<C<rmdir>|/rmdir FILENAME> instead.
9254 If LIST is omitted, L<C<unlink>|/unlink LIST> uses L<C<$_>|perlvar/$_>.
9256 =item unpack TEMPLATE,EXPR
9259 =item unpack TEMPLATE
9261 =for Pod::Functions convert binary structure into normal perl variables
9263 L<C<unpack>|/unpack TEMPLATE,EXPR> does the reverse of
9264 L<C<pack>|/pack TEMPLATE,LIST>: it takes a string
9265 and expands it out into a list of values.
9266 (In scalar context, it returns merely the first value produced.)
9268 If EXPR is omitted, unpacks the L<C<$_>|perlvar/$_> string.
9269 See L<perlpacktut> for an introduction to this function.
9271 The string is broken into chunks described by the TEMPLATE. Each chunk
9272 is converted separately to a value. Typically, either the string is a result
9273 of L<C<pack>|/pack TEMPLATE,LIST>, or the characters of the string
9274 represent a C structure of some kind.
9276 The TEMPLATE has the same format as in the
9277 L<C<pack>|/pack TEMPLATE,LIST> function.
9278 Here's a subroutine that does substring:
9281 my ($what, $where, $howmuch) = @_;
9282 unpack("x$where a$howmuch", $what);
9287 sub ordinal { unpack("W",$_[0]); } # same as ord()
9289 In addition to fields allowed in L<C<pack>|/pack TEMPLATE,LIST>, you may
9290 prefix a field with a %<number> to indicate that
9291 you want a <number>-bit checksum of the items instead of the items
9292 themselves. Default is a 16-bit checksum. The checksum is calculated by
9293 summing numeric values of expanded values (for string fields the sum of
9294 C<ord($char)> is taken; for bit fields the sum of zeroes and ones).
9296 For example, the following
9297 computes the same number as the System V sum program:
9301 unpack("%32W*", readline) % 65535;
9304 The following efficiently counts the number of set bits in a bit vector:
9306 my $setbits = unpack("%32b*", $selectmask);
9308 The C<p> and C<P> formats should be used with care. Since Perl
9309 has no way of checking whether the value passed to
9310 L<C<unpack>|/unpack TEMPLATE,EXPR>
9311 corresponds to a valid memory location, passing a pointer value that's
9312 not known to be valid is likely to have disastrous consequences.
9314 If there are more pack codes or if the repeat count of a field or a group
9315 is larger than what the remainder of the input string allows, the result
9316 is not well defined: the repeat count may be decreased, or
9317 L<C<unpack>|/unpack TEMPLATE,EXPR> may produce empty strings or zeros,
9318 or it may raise an exception.
9319 If the input string is longer than one described by the TEMPLATE,
9320 the remainder of that input string is ignored.
9322 See L<C<pack>|/pack TEMPLATE,LIST> for more examples and notes.
9324 =item unshift ARRAY,LIST
9327 =for Pod::Functions prepend more elements to the beginning of a list
9329 Does the opposite of a L<C<shift>|/shift ARRAY>. Or the opposite of a
9330 L<C<push>|/push ARRAY,LIST>,
9331 depending on how you look at it. Prepends list to the front of the
9332 array and returns the new number of elements in the array.
9334 unshift(@ARGV, '-e') unless $ARGV[0] =~ /^-/;
9336 Note the LIST is prepended whole, not one element at a time, so the
9337 prepended elements stay in the same order. Use
9338 L<C<reverse>|/reverse LIST> to do the reverse.
9340 Starting with Perl 5.14, an experimental feature allowed
9341 L<C<unshift>|/unshift ARRAY,LIST> to take
9342 a scalar expression. This experiment has been deemed unsuccessful, and was
9343 removed as of Perl 5.24.
9345 =item untie VARIABLE
9348 =for Pod::Functions break a tie binding to a variable
9350 Breaks the binding between a variable and a package.
9351 (See L<tie|/tie VARIABLE,CLASSNAME,LIST>.)
9352 Has no effect if the variable is not tied.
9354 =item use Module VERSION LIST
9355 X<use> X<module> X<import>
9357 =item use Module VERSION
9359 =item use Module LIST
9365 =for Pod::Functions load in a module at compile time and import its namespace
9367 Imports some semantics into the current package from the named module,
9368 generally by aliasing certain subroutine or variable names into your
9369 package. It is exactly equivalent to
9371 BEGIN { require Module; Module->import( LIST ); }
9373 except that Module I<must> be a bareword.
9374 The importation can be made conditional by using the L<if> module.
9376 In the C<use VERSION> form, VERSION may be either a v-string such as
9377 v5.24.1, which will be compared to L<C<$^V>|perlvar/$^V> (aka
9378 $PERL_VERSION), or a numeric argument of the form 5.024001, which will
9379 be compared to L<C<$]>|perlvar/$]>. An exception is raised if VERSION
9380 is greater than the version of the current Perl interpreter; Perl will
9381 not attempt to parse the rest of the file. Compare with
9382 L<C<require>|/require VERSION>, which can do a similar check at run
9383 time. Symmetrically, C<no VERSION> allows you to specify that you
9384 want a version of Perl older than the specified one.
9386 Specifying VERSION as a numeric argument of the form 5.024001 should
9387 generally be avoided as older less readable syntax compared to
9388 v5.24.1. Before perl 5.8.0 released in 2002 the more verbose numeric
9389 form was the only supported syntax, which is why you might see it in
9391 use v5.24.1; # compile time version check
9393 use 5.024_001; # ditto; older syntax compatible with perl 5.6
9395 This is often useful if you need to check the current Perl version before
9396 L<C<use>|/use Module VERSION LIST>ing library modules that won't work
9397 with older versions of Perl.
9398 (We try not to do this more than we have to.)
9400 C<use VERSION> also lexically enables all features available in the requested
9401 version as defined by the L<feature> pragma, disabling any features
9402 not in the requested version's feature bundle. See L<feature>.
9403 Similarly, if the specified Perl version is greater than or equal to
9404 5.12.0, strictures are enabled lexically as
9405 with L<C<use strict>|strict>. Any explicit use of
9406 C<use strict> or C<no strict> overrides C<use VERSION>, even if it comes
9407 before it. Later use of C<use VERSION>
9408 will override all behavior of a previous
9409 C<use VERSION>, possibly removing the C<strict> and C<feature> added by
9410 C<use VERSION>. C<use VERSION> does not
9411 load the F<feature.pm> or F<strict.pm>
9414 The C<BEGIN> forces the L<C<require>|/require VERSION> and
9415 L<C<import>|/import LIST> to happen at compile time. The
9416 L<C<require>|/require VERSION> makes sure the module is loaded into
9417 memory if it hasn't been yet. The L<C<import>|/import LIST> is not a
9418 builtin; it's just an ordinary static method
9419 call into the C<Module> package to tell the module to import the list of
9420 features back into the current package. The module can implement its
9421 L<C<import>|/import LIST> method any way it likes, though most modules
9422 just choose to derive their L<C<import>|/import LIST> method via
9423 inheritance from the C<Exporter> class that is defined in the
9424 L<C<Exporter>|Exporter> module. See L<Exporter>. If no
9425 L<C<import>|/import LIST> method can be found, then the call is skipped,
9426 even if there is an AUTOLOAD method.
9428 If you do not want to call the package's L<C<import>|/import LIST>
9429 method (for instance,
9430 to stop your namespace from being altered), explicitly supply the empty list:
9434 That is exactly equivalent to
9436 BEGIN { require Module }
9438 If the VERSION argument is present between Module and LIST, then the
9439 L<C<use>|/use Module VERSION LIST> will call the C<VERSION> method in
9440 class Module with the given version as an argument:
9446 BEGIN { require Module; Module->VERSION(12.34) }
9448 The L<default C<VERSION> method|UNIVERSAL/C<VERSION ( [ REQUIRE ] )>>,
9449 inherited from the L<C<UNIVERSAL>|UNIVERSAL> class, croaks if the given
9450 version is larger than the value of the variable C<$Module::VERSION>.
9452 The VERSION argument cannot be an arbitrary expression. It only counts
9453 as a VERSION argument if it is a version number literal, starting with
9454 either a digit or C<v> followed by a digit. Anything that doesn't
9455 look like a version literal will be parsed as the start of the LIST.
9456 Nevertheless, many attempts to use an arbitrary expression as a VERSION
9457 argument will appear to work, because L<Exporter>'s C<import> method
9458 handles numeric arguments specially, performing version checks rather
9459 than treating them as things to export.
9461 Again, there is a distinction between omitting LIST (L<C<import>|/import
9462 LIST> called with no arguments) and an explicit empty LIST C<()>
9463 (L<C<import>|/import LIST> not called). Note that there is no comma
9466 Because this is a wide-open interface, pragmas (compiler directives)
9467 are also implemented this way. Some of the currently implemented
9473 use sigtrap qw(SEGV BUS);
9474 use strict qw(subs vars refs);
9475 use subs qw(afunc blurfl);
9476 use warnings qw(all);
9477 use sort qw(stable);
9479 Some of these pseudo-modules import semantics into the current
9480 block scope (like L<C<strict>|strict> or L<C<integer>|integer>, unlike
9481 ordinary modules, which import symbols into the current package (which
9482 are effective through the end of the file).
9484 Because L<C<use>|/use Module VERSION LIST> takes effect at compile time,
9485 it doesn't respect the ordinary flow control of the code being compiled.
9486 In particular, putting a L<C<use>|/use Module VERSION LIST> inside the
9487 false branch of a conditional doesn't prevent it
9488 from being processed. If a module or pragma only needs to be loaded
9489 conditionally, this can be done using the L<if> pragma:
9491 use if $] < 5.008, "utf8";
9492 use if WANT_WARNINGS, warnings => qw(all);
9494 There's a corresponding L<C<no>|/no MODULE VERSION LIST> declaration
9495 that unimports meanings imported by L<C<use>|/use Module VERSION LIST>,
9496 i.e., it calls C<< Module->unimport(LIST) >> instead of
9497 L<C<import>|/import LIST>. It behaves just as L<C<import>|/import LIST>
9498 does with VERSION, an omitted or empty LIST,
9499 or no unimport method being found.
9505 Care should be taken when using the C<no VERSION> form of L<C<no>|/no
9506 MODULE VERSION LIST>. It is
9507 I<only> meant to be used to assert that the running Perl is of a earlier
9508 version than its argument and I<not> to undo the feature-enabling side effects
9511 See L<perlmodlib> for a list of standard modules and pragmas. See L<perlrun>
9512 for the C<-M> and C<-m> command-line options to Perl that give
9513 L<C<use>|/use Module VERSION LIST> functionality from the command-line.
9518 =for Pod::Functions set a file's last access and modify times
9520 Changes the access and modification times on each file of a list of
9521 files. The first two elements of the list must be the NUMERIC access
9522 and modification times, in that order. Returns the number of files
9523 successfully changed. The inode change time of each file is set
9524 to the current time. For example, this code has the same effect as the
9525 Unix L<touch(1)> command when the files I<already exist> and belong to
9526 the user running the program:
9529 my $atime = my $mtime = time;
9530 utime $atime, $mtime, @ARGV;
9532 Since Perl 5.8.0, if the first two elements of the list are
9533 L<C<undef>|/undef EXPR>,
9534 the L<utime(2)> syscall from your C library is called with a null second
9535 argument. On most systems, this will set the file's access and
9536 modification times to the current time (i.e., equivalent to the example
9537 above) and will work even on files you don't own provided you have write
9540 for my $file (@ARGV) {
9541 utime(undef, undef, $file)
9542 || warn "Couldn't touch $file: $!";
9545 Under NFS this will use the time of the NFS server, not the time of
9546 the local machine. If there is a time synchronization problem, the
9547 NFS server and local machine will have different times. The Unix
9548 L<touch(1)> command will in fact normally use this form instead of the
9549 one shown in the first example.
9551 Passing only one of the first two elements as L<C<undef>|/undef EXPR> is
9552 equivalent to passing a 0 and will not have the effect described when
9553 both are L<C<undef>|/undef EXPR>. This also triggers an
9554 uninitialized warning.
9556 On systems that support L<futimes(2)>, you may pass filehandles among the
9557 files. On systems that don't support L<futimes(2)>, passing filehandles raises
9558 an exception. Filehandles must be passed as globs or glob references to be
9559 recognized; barewords are considered filenames.
9561 Portability issues: L<perlport/utime>.
9568 =for Pod::Functions return a list of the values in a hash
9570 In list context, returns a list consisting of all the values of the named
9571 hash. In Perl 5.12 or later only, will also return a list of the values of
9572 an array; prior to that release, attempting to use an array argument will
9573 produce a syntax error. In scalar context, returns the number of values.
9575 Hash entries are returned in an apparently random order. The actual random
9576 order is specific to a given hash; the exact same series of operations
9577 on two hashes may result in a different order for each hash. Any insertion
9578 into the hash may change the order, as will any deletion, with the exception
9579 that the most recent key returned by L<C<each>|/each HASH> or
9580 L<C<keys>|/keys HASH> may be deleted without changing the order. So
9581 long as a given hash is unmodified you may rely on
9582 L<C<keys>|/keys HASH>, L<C<values>|/values HASH> and
9583 L<C<each>|/each HASH> to repeatedly return the same order
9584 as each other. See L<perlsec/"Algorithmic Complexity Attacks"> for
9585 details on why hash order is randomized. Aside from the guarantees
9586 provided here the exact details of Perl's hash algorithm and the hash
9587 traversal order are subject to change in any release of Perl. Tied hashes
9588 may behave differently to Perl's hashes with respect to changes in order on
9589 insertion and deletion of items.
9591 As a side effect, calling L<C<values>|/values HASH> resets the HASH or
9592 ARRAY's internal iterator (see L<C<each>|/each HASH>) before yielding the
9593 values. In particular,
9594 calling L<C<values>|/values HASH> in void context resets the iterator
9595 with no other overhead.
9597 Apart from resetting the iterator,
9598 C<values @array> in list context is the same as plain C<@array>.
9599 (We recommend that you use void context C<keys @array> for this, but
9600 reasoned that taking C<values @array> out would require more
9601 documentation than leaving it in.)
9603 Note that the values are not copied, which means modifying them will
9604 modify the contents of the hash:
9606 for (values %hash) { s/foo/bar/g } # modifies %hash values
9607 for (@hash{keys %hash}) { s/foo/bar/g } # same
9609 Starting with Perl 5.14, an experimental feature allowed
9610 L<C<values>|/values HASH> to take a
9611 scalar expression. This experiment has been deemed unsuccessful, and was
9612 removed as of Perl 5.24.
9614 To avoid confusing would-be users of your code who are running earlier
9615 versions of Perl with mysterious syntax errors, put this sort of thing at
9616 the top of your file to signal that your code will work I<only> on Perls of
9619 use 5.012; # so keys/values/each work on arrays
9621 See also L<C<keys>|/keys HASH>, L<C<each>|/each HASH>, and
9622 L<C<sort>|/sort SUBNAME LIST>.
9624 =item vec EXPR,OFFSET,BITS
9625 X<vec> X<bit> X<bit vector>
9627 =for Pod::Functions test or set particular bits in a string
9629 Treats the string in EXPR as a bit vector made up of elements of
9630 width BITS and returns the value of the element specified by OFFSET
9631 as an unsigned integer. BITS therefore specifies the number of bits
9632 that are reserved for each element in the bit vector. This must
9633 be a power of two from 1 to 32 (or 64, if your platform supports
9636 If BITS is 8, "elements" coincide with bytes of the input string.
9638 If BITS is 16 or more, bytes of the input string are grouped into chunks
9639 of size BITS/8, and each group is converted to a number as with
9640 L<C<pack>|/pack TEMPLATE,LIST>/L<C<unpack>|/unpack TEMPLATE,EXPR> with
9641 big-endian formats C<n>/C<N> (and analogously for BITS==64). See
9642 L<C<pack>|/pack TEMPLATE,LIST> for details.
9644 If bits is 4 or less, the string is broken into bytes, then the bits
9645 of each byte are broken into 8/BITS groups. Bits of a byte are
9646 numbered in a little-endian-ish way, as in C<0x01>, C<0x02>,
9647 C<0x04>, C<0x08>, C<0x10>, C<0x20>, C<0x40>, C<0x80>. For example,
9648 breaking the single input byte C<chr(0x36)> into two groups gives a list
9649 C<(0x6, 0x3)>; breaking it into 4 groups gives C<(0x2, 0x1, 0x3, 0x0)>.
9651 L<C<vec>|/vec EXPR,OFFSET,BITS> may also be assigned to, in which case
9652 parentheses are needed
9653 to give the expression the correct precedence as in
9655 vec($image, $max_x * $x + $y, 8) = 3;
9657 If the selected element is outside the string, the value 0 is returned.
9658 If an element off the end of the string is written to, Perl will first
9659 extend the string with sufficiently many zero bytes. It is an error
9660 to try to write off the beginning of the string (i.e., negative OFFSET).
9662 If the string happens to be encoded as UTF-8 internally (and thus has
9663 the UTF8 flag set), L<C<vec>|/vec EXPR,OFFSET,BITS> tries to convert it
9664 to use a one-byte-per-character internal representation. However, if the
9665 string contains characters with values of 256 or higher, that conversion
9666 will fail, and a deprecation message will be raised. In that situation,
9667 C<vec> will operate on the underlying buffer regardless, in its internal
9668 UTF-8 representation. In Perl 5.32, this will be a fatal error.
9670 Strings created with L<C<vec>|/vec EXPR,OFFSET,BITS> can also be
9671 manipulated with the logical
9672 operators C<|>, C<&>, C<^>, and C<~>. These operators will assume a bit
9673 vector operation is desired when both operands are strings.
9674 See L<perlop/"Bitwise String Operators">.
9676 The following code will build up an ASCII string saying C<'PerlPerlPerl'>.
9677 The comments show the string after each step. Note that this code works
9678 in the same way on big-endian or little-endian machines.
9681 vec($foo, 0, 32) = 0x5065726C; # 'Perl'
9683 # $foo eq "Perl" eq "\x50\x65\x72\x6C", 32 bits
9684 print vec($foo, 0, 8); # prints 80 == 0x50 == ord('P')
9686 vec($foo, 2, 16) = 0x5065; # 'PerlPe'
9687 vec($foo, 3, 16) = 0x726C; # 'PerlPerl'
9688 vec($foo, 8, 8) = 0x50; # 'PerlPerlP'
9689 vec($foo, 9, 8) = 0x65; # 'PerlPerlPe'
9690 vec($foo, 20, 4) = 2; # 'PerlPerlPe' . "\x02"
9691 vec($foo, 21, 4) = 7; # 'PerlPerlPer'
9693 vec($foo, 45, 2) = 3; # 'PerlPerlPer' . "\x0c"
9694 vec($foo, 93, 1) = 1; # 'PerlPerlPer' . "\x2c"
9695 vec($foo, 94, 1) = 1; # 'PerlPerlPerl'
9698 To transform a bit vector into a string or list of 0's and 1's, use these:
9700 my $bits = unpack("b*", $vector);
9701 my @bits = split(//, unpack("b*", $vector));
9703 If you know the exact length in bits, it can be used in place of the C<*>.
9705 Here is an example to illustrate how the bits actually fall in place:
9711 unpack("V",$_) 01234567890123456789012345678901
9712 ------------------------------------------------------------------
9717 for ($shift=0; $shift < $width; ++$shift) {
9718 for ($off=0; $off < 32/$width; ++$off) {
9719 $str = pack("B*", "0"x32);
9720 $bits = (1<<$shift);
9721 vec($str, $off, $width) = $bits;
9722 $res = unpack("b*",$str);
9723 $val = unpack("V", $str);
9730 vec($_,@#,@#) = @<< == @######### @>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
9731 $off, $width, $bits, $val, $res
9735 Regardless of the machine architecture on which it runs, the
9736 example above should print the following table:
9739 unpack("V",$_) 01234567890123456789012345678901
9740 ------------------------------------------------------------------
9741 vec($_, 0, 1) = 1 == 1 10000000000000000000000000000000
9742 vec($_, 1, 1) = 1 == 2 01000000000000000000000000000000
9743 vec($_, 2, 1) = 1 == 4 00100000000000000000000000000000
9744 vec($_, 3, 1) = 1 == 8 00010000000000000000000000000000
9745 vec($_, 4, 1) = 1 == 16 00001000000000000000000000000000
9746 vec($_, 5, 1) = 1 == 32 00000100000000000000000000000000
9747 vec($_, 6, 1) = 1 == 64 00000010000000000000000000000000
9748 vec($_, 7, 1) = 1 == 128 00000001000000000000000000000000
9749 vec($_, 8, 1) = 1 == 256 00000000100000000000000000000000
9750 vec($_, 9, 1) = 1 == 512 00000000010000000000000000000000
9751 vec($_,10, 1) = 1 == 1024 00000000001000000000000000000000
9752 vec($_,11, 1) = 1 == 2048 00000000000100000000000000000000
9753 vec($_,12, 1) = 1 == 4096 00000000000010000000000000000000
9754 vec($_,13, 1) = 1 == 8192 00000000000001000000000000000000
9755 vec($_,14, 1) = 1 == 16384 00000000000000100000000000000000
9756 vec($_,15, 1) = 1 == 32768 00000000000000010000000000000000
9757 vec($_,16, 1) = 1 == 65536 00000000000000001000000000000000
9758 vec($_,17, 1) = 1 == 131072 00000000000000000100000000000000
9759 vec($_,18, 1) = 1 == 262144 00000000000000000010000000000000
9760 vec($_,19, 1) = 1 == 524288 00000000000000000001000000000000
9761 vec($_,20, 1) = 1 == 1048576 00000000000000000000100000000000
9762 vec($_,21, 1) = 1 == 2097152 00000000000000000000010000000000
9763 vec($_,22, 1) = 1 == 4194304 00000000000000000000001000000000
9764 vec($_,23, 1) = 1 == 8388608 00000000000000000000000100000000
9765 vec($_,24, 1) = 1 == 16777216 00000000000000000000000010000000
9766 vec($_,25, 1) = 1 == 33554432 00000000000000000000000001000000
9767 vec($_,26, 1) = 1 == 67108864 00000000000000000000000000100000
9768 vec($_,27, 1) = 1 == 134217728 00000000000000000000000000010000
9769 vec($_,28, 1) = 1 == 268435456 00000000000000000000000000001000
9770 vec($_,29, 1) = 1 == 536870912 00000000000000000000000000000100
9771 vec($_,30, 1) = 1 == 1073741824 00000000000000000000000000000010
9772 vec($_,31, 1) = 1 == 2147483648 00000000000000000000000000000001
9773 vec($_, 0, 2) = 1 == 1 10000000000000000000000000000000
9774 vec($_, 1, 2) = 1 == 4 00100000000000000000000000000000
9775 vec($_, 2, 2) = 1 == 16 00001000000000000000000000000000
9776 vec($_, 3, 2) = 1 == 64 00000010000000000000000000000000
9777 vec($_, 4, 2) = 1 == 256 00000000100000000000000000000000
9778 vec($_, 5, 2) = 1 == 1024 00000000001000000000000000000000
9779 vec($_, 6, 2) = 1 == 4096 00000000000010000000000000000000
9780 vec($_, 7, 2) = 1 == 16384 00000000000000100000000000000000
9781 vec($_, 8, 2) = 1 == 65536 00000000000000001000000000000000
9782 vec($_, 9, 2) = 1 == 262144 00000000000000000010000000000000
9783 vec($_,10, 2) = 1 == 1048576 00000000000000000000100000000000
9784 vec($_,11, 2) = 1 == 4194304 00000000000000000000001000000000
9785 vec($_,12, 2) = 1 == 16777216 00000000000000000000000010000000
9786 vec($_,13, 2) = 1 == 67108864 00000000000000000000000000100000
9787 vec($_,14, 2) = 1 == 268435456 00000000000000000000000000001000
9788 vec($_,15, 2) = 1 == 1073741824 00000000000000000000000000000010
9789 vec($_, 0, 2) = 2 == 2 01000000000000000000000000000000
9790 vec($_, 1, 2) = 2 == 8 00010000000000000000000000000000
9791 vec($_, 2, 2) = 2 == 32 00000100000000000000000000000000
9792 vec($_, 3, 2) = 2 == 128 00000001000000000000000000000000
9793 vec($_, 4, 2) = 2 == 512 00000000010000000000000000000000
9794 vec($_, 5, 2) = 2 == 2048 00000000000100000000000000000000
9795 vec($_, 6, 2) = 2 == 8192 00000000000001000000000000000000
9796 vec($_, 7, 2) = 2 == 32768 00000000000000010000000000000000
9797 vec($_, 8, 2) = 2 == 131072 00000000000000000100000000000000
9798 vec($_, 9, 2) = 2 == 524288 00000000000000000001000000000000
9799 vec($_,10, 2) = 2 == 2097152 00000000000000000000010000000000
9800 vec($_,11, 2) = 2 == 8388608 00000000000000000000000100000000
9801 vec($_,12, 2) = 2 == 33554432 00000000000000000000000001000000
9802 vec($_,13, 2) = 2 == 134217728 00000000000000000000000000010000
9803 vec($_,14, 2) = 2 == 536870912 00000000000000000000000000000100
9804 vec($_,15, 2) = 2 == 2147483648 00000000000000000000000000000001
9805 vec($_, 0, 4) = 1 == 1 10000000000000000000000000000000
9806 vec($_, 1, 4) = 1 == 16 00001000000000000000000000000000
9807 vec($_, 2, 4) = 1 == 256 00000000100000000000000000000000
9808 vec($_, 3, 4) = 1 == 4096 00000000000010000000000000000000
9809 vec($_, 4, 4) = 1 == 65536 00000000000000001000000000000000
9810 vec($_, 5, 4) = 1 == 1048576 00000000000000000000100000000000
9811 vec($_, 6, 4) = 1 == 16777216 00000000000000000000000010000000
9812 vec($_, 7, 4) = 1 == 268435456 00000000000000000000000000001000
9813 vec($_, 0, 4) = 2 == 2 01000000000000000000000000000000
9814 vec($_, 1, 4) = 2 == 32 00000100000000000000000000000000
9815 vec($_, 2, 4) = 2 == 512 00000000010000000000000000000000
9816 vec($_, 3, 4) = 2 == 8192 00000000000001000000000000000000
9817 vec($_, 4, 4) = 2 == 131072 00000000000000000100000000000000
9818 vec($_, 5, 4) = 2 == 2097152 00000000000000000000010000000000
9819 vec($_, 6, 4) = 2 == 33554432 00000000000000000000000001000000
9820 vec($_, 7, 4) = 2 == 536870912 00000000000000000000000000000100
9821 vec($_, 0, 4) = 4 == 4 00100000000000000000000000000000
9822 vec($_, 1, 4) = 4 == 64 00000010000000000000000000000000
9823 vec($_, 2, 4) = 4 == 1024 00000000001000000000000000000000
9824 vec($_, 3, 4) = 4 == 16384 00000000000000100000000000000000
9825 vec($_, 4, 4) = 4 == 262144 00000000000000000010000000000000
9826 vec($_, 5, 4) = 4 == 4194304 00000000000000000000001000000000
9827 vec($_, 6, 4) = 4 == 67108864 00000000000000000000000000100000
9828 vec($_, 7, 4) = 4 == 1073741824 00000000000000000000000000000010
9829 vec($_, 0, 4) = 8 == 8 00010000000000000000000000000000
9830 vec($_, 1, 4) = 8 == 128 00000001000000000000000000000000
9831 vec($_, 2, 4) = 8 == 2048 00000000000100000000000000000000
9832 vec($_, 3, 4) = 8 == 32768 00000000000000010000000000000000
9833 vec($_, 4, 4) = 8 == 524288 00000000000000000001000000000000
9834 vec($_, 5, 4) = 8 == 8388608 00000000000000000000000100000000
9835 vec($_, 6, 4) = 8 == 134217728 00000000000000000000000000010000
9836 vec($_, 7, 4) = 8 == 2147483648 00000000000000000000000000000001
9837 vec($_, 0, 8) = 1 == 1 10000000000000000000000000000000
9838 vec($_, 1, 8) = 1 == 256 00000000100000000000000000000000
9839 vec($_, 2, 8) = 1 == 65536 00000000000000001000000000000000
9840 vec($_, 3, 8) = 1 == 16777216 00000000000000000000000010000000
9841 vec($_, 0, 8) = 2 == 2 01000000000000000000000000000000
9842 vec($_, 1, 8) = 2 == 512 00000000010000000000000000000000
9843 vec($_, 2, 8) = 2 == 131072 00000000000000000100000000000000
9844 vec($_, 3, 8) = 2 == 33554432 00000000000000000000000001000000
9845 vec($_, 0, 8) = 4 == 4 00100000000000000000000000000000
9846 vec($_, 1, 8) = 4 == 1024 00000000001000000000000000000000
9847 vec($_, 2, 8) = 4 == 262144 00000000000000000010000000000000
9848 vec($_, 3, 8) = 4 == 67108864 00000000000000000000000000100000
9849 vec($_, 0, 8) = 8 == 8 00010000000000000000000000000000
9850 vec($_, 1, 8) = 8 == 2048 00000000000100000000000000000000
9851 vec($_, 2, 8) = 8 == 524288 00000000000000000001000000000000
9852 vec($_, 3, 8) = 8 == 134217728 00000000000000000000000000010000
9853 vec($_, 0, 8) = 16 == 16 00001000000000000000000000000000
9854 vec($_, 1, 8) = 16 == 4096 00000000000010000000000000000000
9855 vec($_, 2, 8) = 16 == 1048576 00000000000000000000100000000000
9856 vec($_, 3, 8) = 16 == 268435456 00000000000000000000000000001000
9857 vec($_, 0, 8) = 32 == 32 00000100000000000000000000000000
9858 vec($_, 1, 8) = 32 == 8192 00000000000001000000000000000000
9859 vec($_, 2, 8) = 32 == 2097152 00000000000000000000010000000000
9860 vec($_, 3, 8) = 32 == 536870912 00000000000000000000000000000100
9861 vec($_, 0, 8) = 64 == 64 00000010000000000000000000000000
9862 vec($_, 1, 8) = 64 == 16384 00000000000000100000000000000000
9863 vec($_, 2, 8) = 64 == 4194304 00000000000000000000001000000000
9864 vec($_, 3, 8) = 64 == 1073741824 00000000000000000000000000000010
9865 vec($_, 0, 8) = 128 == 128 00000001000000000000000000000000
9866 vec($_, 1, 8) = 128 == 32768 00000000000000010000000000000000
9867 vec($_, 2, 8) = 128 == 8388608 00000000000000000000000100000000
9868 vec($_, 3, 8) = 128 == 2147483648 00000000000000000000000000000001
9873 =for Pod::Functions wait for any child process to die
9875 Behaves like L<wait(2)> on your system: it waits for a child
9876 process to terminate and returns the pid of the deceased process, or
9877 C<-1> if there are no child processes. The status is returned in
9878 L<C<$?>|perlvar/$?> and
9879 L<C<${^CHILD_ERROR_NATIVE}>|perlvar/${^CHILD_ERROR_NATIVE}>.
9880 Note that a return value of C<-1> could mean that child processes are
9881 being automatically reaped, as described in L<perlipc>.
9883 If you use L<C<wait>|/wait> in your handler for
9884 L<C<$SIG{CHLD}>|perlvar/%SIG>, it may accidentally wait for the child
9885 created by L<C<qx>|/qxE<sol>STRINGE<sol>> or L<C<system>|/system LIST>.
9886 See L<perlipc> for details.
9888 Portability issues: L<perlport/wait>.
9890 =item waitpid PID,FLAGS
9893 =for Pod::Functions wait for a particular child process to die
9895 Waits for a particular child process to terminate and returns the pid of
9896 the deceased process, or C<-1> if there is no such child process. A
9897 non-blocking wait (with L<WNOHANG|POSIX/C<WNOHANG>> in FLAGS) can return 0 if
9898 there are child processes matching PID but none have terminated yet.
9899 The status is returned in L<C<$?>|perlvar/$?> and
9900 L<C<${^CHILD_ERROR_NATIVE}>|perlvar/${^CHILD_ERROR_NATIVE}>.
9902 A PID of C<0> indicates to wait for any child process whose process group ID is
9903 equal to that of the current process. A PID of less than C<-1> indicates to
9904 wait for any child process whose process group ID is equal to -PID. A PID of
9905 C<-1> indicates to wait for any child process.
9909 use POSIX ":sys_wait_h";
9913 $kid = waitpid(-1, WNOHANG);
9918 1 while waitpid(-1, WNOHANG) > 0;
9920 then you can do a non-blocking wait for all pending zombie processes (see
9922 Non-blocking wait is available on machines supporting either the
9923 L<waitpid(2)> or L<wait4(2)> syscalls. However, waiting for a particular
9924 pid with FLAGS of C<0> is implemented everywhere. (Perl emulates the
9925 system call by remembering the status values of processes that have
9926 exited but have not been harvested by the Perl script yet.)
9928 Note that on some systems, a return value of C<-1> could mean that child
9929 processes are being automatically reaped. See L<perlipc> for details,
9930 and for other examples.
9932 Portability issues: L<perlport/waitpid>.
9935 X<wantarray> X<context>
9937 =for Pod::Functions get void vs scalar vs list context of current subroutine call
9939 Returns true if the context of the currently executing subroutine or
9940 L<C<eval>|/eval EXPR> is looking for a list value. Returns false if the
9942 looking for a scalar. Returns the undefined value if the context is
9943 looking for no value (void context).
9945 return unless defined wantarray; # don't bother doing more
9946 my @a = complex_calculation();
9947 return wantarray ? @a : "@a";
9949 L<C<wantarray>|/wantarray>'s result is unspecified in the top level of a file,
9950 in a C<BEGIN>, C<UNITCHECK>, C<CHECK>, C<INIT> or C<END> block, or
9951 in a C<DESTROY> method.
9953 This function should have been named wantlist() instead.
9956 X<warn> X<warning> X<STDERR>
9958 =for Pod::Functions print debugging info
9960 Emits a warning, usually by printing it to C<STDERR>. C<warn> interprets
9961 its operand LIST in the same way as C<die>, but is slightly different
9962 in what it defaults to when LIST is empty or makes an empty string.
9963 If it is empty and L<C<$@>|perlvar/$@> already contains an exception
9964 value then that value is used after appending C<"\t...caught">. If it
9965 is empty and C<$@> is also empty then the string C<"Warning: Something's
9968 By default, the exception derived from the operand LIST is stringified
9969 and printed to C<STDERR>. This behaviour can be altered by installing
9970 a L<C<$SIG{__WARN__}>|perlvar/%SIG> handler. If there is such a
9971 handler then no message is automatically printed; it is the handler's
9972 responsibility to deal with the exception
9973 as it sees fit (like, for instance, converting it into a
9974 L<C<die>|/die LIST>). Most
9975 handlers must therefore arrange to actually display the
9976 warnings that they are not prepared to deal with, by calling
9977 L<C<warn>|/warn LIST>
9978 again in the handler. Note that this is quite safe and will not
9979 produce an endless loop, since C<__WARN__> hooks are not called from
9982 You will find this behavior is slightly different from that of
9983 L<C<$SIG{__DIE__}>|perlvar/%SIG> handlers (which don't suppress the
9984 error text, but can instead call L<C<die>|/die LIST> again to change
9987 Using a C<__WARN__> handler provides a powerful way to silence all
9988 warnings (even the so-called mandatory ones). An example:
9990 # wipe out *all* compile-time warnings
9991 BEGIN { $SIG{'__WARN__'} = sub { warn $_[0] if $DOWARN } }
9993 my $foo = 20; # no warning about duplicate my $foo,
9994 # but hey, you asked for it!
9995 # no compile-time or run-time warnings before here
9998 # run-time warnings enabled after here
9999 warn "\$foo is alive and $foo!"; # does show up
10001 See L<perlvar> for details on setting L<C<%SIG>|perlvar/%SIG> entries
10003 examples. See the L<Carp> module for other kinds of warnings using its
10004 C<carp> and C<cluck> functions.
10006 =item write FILEHANDLE
10013 =for Pod::Functions print a picture record
10015 Writes a formatted record (possibly multi-line) to the specified FILEHANDLE,
10016 using the format associated with that file. By default the format for
10017 a file is the one having the same name as the filehandle, but the
10018 format for the current output channel (see the
10019 L<C<select>|/select FILEHANDLE> function) may be set explicitly by
10020 assigning the name of the format to the L<C<$~>|perlvar/$~> variable.
10022 Top of form processing is handled automatically: if there is insufficient
10023 room on the current page for the formatted record, the page is advanced by
10024 writing a form feed and a special top-of-page
10025 format is used to format the new
10026 page header before the record is written. By default, the top-of-page
10027 format is the name of the filehandle with C<_TOP> appended, or C<top>
10028 in the current package if the former does not exist. This would be a
10029 problem with autovivified filehandles, but it may be dynamically set to the
10030 format of your choice by assigning the name to the L<C<$^>|perlvar/$^>
10031 variable while that filehandle is selected. The number of lines
10032 remaining on the current page is in variable L<C<$->|perlvar/$->, which
10033 can be set to C<0> to force a new page.
10035 If FILEHANDLE is unspecified, output goes to the current default output
10036 channel, which starts out as STDOUT but may be changed by the
10037 L<C<select>|/select FILEHANDLE> operator. If the FILEHANDLE is an EXPR,
10038 then the expression
10039 is evaluated and the resulting string is used to look up the name of
10040 the FILEHANDLE at run time. For more on formats, see L<perlform>.
10042 Note that write is I<not> the opposite of
10043 L<C<read>|/read FILEHANDLE,SCALAR,LENGTH,OFFSET>. Unfortunately.
10047 =for Pod::Functions transliterate a string
10049 The transliteration operator. Same as
10050 L<C<trE<sol>E<sol>E<sol>>|/trE<sol>E<sol>E<sol>>. See
10051 L<perlop/"Quote-Like Operators">.
10055 =head2 Non-function Keywords by Cross-reference
10065 These keywords are documented in L<perldata/"Special Literals">.
10083 These compile phase keywords are documented in L<perlmod/"BEGIN, UNITCHECK, CHECK, INIT and END">.
10093 This method keyword is documented in L<perlobj/"Destructors">.
10125 These operators are documented in L<perlop>.
10135 This keyword is documented in L<perlsub/"Autoloading">.
10159 These flow-control keywords are documented in L<perlsyn/"Compound Statements">.
10163 The "else if" keyword is spelled C<elsif> in Perl. There's no C<elif>
10164 or C<else if> either. It does parse C<elseif>, but only to warn you
10165 about not using it.
10167 See the documentation for flow-control keywords in L<perlsyn/"Compound
10180 These flow-control keywords related to the experimental switch feature are
10181 documented in L<perlsyn/"Switch Statements">.