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