This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Clarify "User-visible changes"
[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
798dc914
KW
2038In the first form, often referred to as a "string eval", the return
2039value of EXPR is parsed and executed as if it
c7cc6f1c 2040were a little Perl program. The value of the expression (which is itself
8f1da26d 2041determined within scalar context) is first parsed, and if there were no
2341804c 2042errors, executed as a block within the lexical context of the current Perl
df4833a8 2043program. This means, that in particular, any outer lexical variables are
2341804c
DM
2044visible to it, and any package variable settings or subroutine and format
2045definitions remain afterwards.
2046
2263ed23
LM
2047Note that the value is parsed every time the L<C<eval>|/eval EXPR>
2048executes. If EXPR is omitted, evaluates L<C<$_>|perlvar/$_>. This form
2049is typically used to delay parsing and subsequent execution of the text
2050of EXPR until run time.
2051
2052If the
2053L<C<"unicode_eval"> feature|feature/The 'unicode_eval' and 'evalbytes' features>
2054is enabled (which is the default under a
2055C<use 5.16> or higher declaration), EXPR or L<C<$_>|perlvar/$_> is
2056treated as a string of characters, so L<C<use utf8>|utf8> declarations
2057have no effect, and source filters are forbidden. In the absence of the
2058L<C<"unicode_eval"> feature|feature/The 'unicode_eval' and 'evalbytes' features>,
2059will sometimes be treated as characters and sometimes as bytes,
2060depending on the internal encoding, and source filters activated within
2061the L<C<eval>|/eval EXPR> exhibit the erratic, but historical, behaviour
2062of affecting some outer file scope that is still compiling. See also
2063the L<C<evalbytes>|/evalbytes EXPR> operator, which always treats its
2064input as a byte stream and works properly with source filters, and the
2065L<feature> pragma.
7289c5e6 2066
798dc914
KW
2067Problems can arise if the string expands a scalar containing a floating
2068point number. That scalar can expand to letters, such as C<"NaN"> or
2263ed23
LM
2069C<"Infinity">; or, within the scope of a L<C<use locale>|locale>, the
2070decimal point character may be something other than a dot (such as a
2071comma). None of these are likely to parse as you are likely expecting.
798dc914 2072
c7cc6f1c 2073In the second form, the code within the BLOCK is parsed only once--at the
2263ed23
LM
2074same time the code surrounding the L<C<eval>|/eval EXPR> itself was
2075parsed--and executed
c7cc6f1c
GS
2076within the context of the current Perl program. This form is typically
2077used to trap exceptions more efficiently than the first (see below), while
2078also providing the benefit of checking the code within BLOCK at compile
2079time.
2080
2081The final semicolon, if any, may be omitted from the value of EXPR or within
2082the BLOCK.
2083
2084In both forms, the value returned is the value of the last expression
5a964f20 2085evaluated inside the mini-program; a return statement may be also used, just
c7cc6f1c 2086as with subroutines. The expression providing the return value is evaluated
2263ed23
LM
2087in void, scalar, or list context, depending on the context of the
2088L<C<eval>|/eval EXPR> itself. See L<C<wantarray>|/wantarray> for more
2089on how the evaluation context can be determined.
2090
2091If there is a syntax error or runtime error, or a L<C<die>|/die LIST>
2092statement is executed, L<C<eval>|/eval EXPR> returns
2093L<C<undef>|/undef EXPR> in scalar context or an empty list in list
2094context, and L<C<$@>|perlvar/$@> is set to the error message. (Prior to
20955.16, a bug caused L<C<undef>|/undef EXPR> to be returned in list
2096context for syntax errors, but not for runtime errors.) If there was no
2097error, L<C<$@>|perlvar/$@> is set to the empty string. A control flow
2098operator like L<C<last>|/last LABEL> or L<C<goto>|/goto LABEL> can
2099bypass the setting of L<C<$@>|perlvar/$@>. Beware that using
2100L<C<eval>|/eval EXPR> neither silences Perl from printing warnings to
2101STDERR, nor does it stuff the text of warning messages into
2102L<C<$@>|perlvar/$@>. To do either of those, you have to use the
2103L<C<$SIG{__WARN__}>|perlvar/%SIG> facility, or turn off warnings inside
2104the BLOCK or EXPR using S<C<no warnings 'all'>>. See
2105L<C<warn>|/warn LIST>, L<perlvar>, and L<warnings>.
2106
2107Note that, because L<C<eval>|/eval EXPR> traps otherwise-fatal errors,
2108it is useful for determining whether a particular feature (such as
2109L<C<socket>|/socket SOCKET,DOMAIN,TYPE,PROTOCOL> or
2110L<C<symlink>|/symlink OLDFILE,NEWFILE>) is implemented. It is also
2111Perl's exception-trapping mechanism, where the L<C<die>|/die LIST>
2112operator is used to raise exceptions.
a0d0e21e 2113
5f1da31c
NT
2114If you want to trap errors when loading an XS module, some problems with
2115the binary interface (such as Perl version skew) may be fatal even with
2263ed23
LM
2116L<C<eval>|/eval EXPR> unless C<$ENV{PERL_DL_NONLAZY}> is set. See
2117L<perlrun>.
5f1da31c 2118
a0d0e21e
LW
2119If the code to be executed doesn't vary, you may use the eval-BLOCK
2120form to trap run-time errors without incurring the penalty of
2263ed23
LM
2121recompiling each time. The error, if any, is still returned in
2122L<C<$@>|perlvar/$@>.
a0d0e21e
LW
2123Examples:
2124
54310121 2125 # make divide-by-zero nonfatal
a0d0e21e
LW
2126 eval { $answer = $a / $b; }; warn $@ if $@;
2127
2128 # same thing, but less efficient
2129 eval '$answer = $a / $b'; warn $@ if $@;
2130
2131 # a compile-time error
5ed4f2ec 2132 eval { $answer = }; # WRONG
a0d0e21e
LW
2133
2134 # a run-time error
5ed4f2ec 2135 eval '$answer ='; # sets $@
a0d0e21e 2136
2263ed23 2137Using the C<eval {}> form as an exception trap in libraries does have some
cf264981
SP
2138issues. Due to the current arguably broken state of C<__DIE__> hooks, you
2139may wish not to trigger any C<__DIE__> hooks that user code may have installed.
2b5ab1e7 2140You can use the C<local $SIG{__DIE__}> construct for this purpose,
80d38338 2141as this example shows:
774d564b 2142
80d38338 2143 # a private exception trap for divide-by-zero
f86cebdf
GS
2144 eval { local $SIG{'__DIE__'}; $answer = $a / $b; };
2145 warn $@ if $@;
774d564b
PP
2146
2147This is especially significant, given that C<__DIE__> hooks can call
2263ed23
LM
2148L<C<die>|/die LIST> again, which has the effect of changing their error
2149messages:
774d564b
PP
2150
2151 # __DIE__ hooks may modify error messages
2152 {
f86cebdf
GS
2153 local $SIG{'__DIE__'} =
2154 sub { (my $x = $_[0]) =~ s/foo/bar/g; die $x };
c7cc6f1c
GS
2155 eval { die "foo lives here" };
2156 print $@ if $@; # prints "bar lives here"
774d564b
PP
2157 }
2158
19799a22 2159Because this promotes action at a distance, this counterintuitive behavior
2b5ab1e7
TC
2160may be fixed in a future release.
2161
2263ed23
LM
2162With an L<C<eval>|/eval EXPR>, you should be especially careful to
2163remember what's being looked at when:
a0d0e21e 2164
5ed4f2ec 2165 eval $x; # CASE 1
2166 eval "$x"; # CASE 2
a0d0e21e 2167
5ed4f2ec 2168 eval '$x'; # CASE 3
2169 eval { $x }; # CASE 4
a0d0e21e 2170
5ed4f2ec 2171 eval "\$$x++"; # CASE 5
2172 $$x++; # CASE 6
a0d0e21e 2173
2f9daede 2174Cases 1 and 2 above behave identically: they run the code contained in
19799a22 2175the variable $x. (Although case 2 has misleading double quotes making
2f9daede 2176the reader wonder what else might be happening (nothing is).) Cases 3
7660c0ab 2177and 4 likewise behave in the same way: they run the code C<'$x'>, which
19799a22 2178does nothing but return the value of $x. (Case 4 is preferred for
2f9daede
TPG
2179purely visual reasons, but it also has the advantage of compiling at
2180compile-time instead of at run-time.) Case 5 is a place where
19799a22 2181normally you I<would> like to use double quotes, except that in this
2f9daede
TPG
2182particular situation, you can just use symbolic references instead, as
2183in case 6.
a0d0e21e 2184
2263ed23
LM
2185Before Perl 5.14, the assignment to L<C<$@>|perlvar/$@> occurred before
2186restoration
bade7fbc 2187of localized variables, which means that for your code to run on older
b208c909 2188versions, a temporary is required if you want to mask some but not all
8a5a710d
DN
2189errors:
2190
2191 # alter $@ on nefarious repugnancy only
2192 {
2193 my $e;
2194 {
f7051f2c
FC
2195 local $@; # protect existing $@
2196 eval { test_repugnancy() };
2197 # $@ =~ /nefarious/ and die $@; # Perl 5.14 and higher only
2198 $@ =~ /nefarious/ and $e = $@;
8a5a710d
DN
2199 }
2200 die $e if defined $e
2201 }
2202
4968c1e4 2203C<eval BLOCK> does I<not> count as a loop, so the loop control statements
2263ed23
LM
2204L<C<next>|/next LABEL>, L<C<last>|/last LABEL>, or
2205L<C<redo>|/redo LABEL> cannot be used to leave or restart the block.
4968c1e4 2206
4f00fc7e
FC
2207An C<eval ''> executed within a subroutine defined
2208in the C<DB> package doesn't see the usual
3b10bc60 2209surrounding lexical scope, but rather the scope of the first non-DB piece
df4833a8 2210of code that called it. You don't normally need to worry about this unless
3b10bc60 2211you are writing a Perl debugger.
d819b83a 2212
7289c5e6
FC
2213=item evalbytes EXPR
2214X<evalbytes>
2215
2216=item evalbytes
2217
d9b04284 2218=for Pod::Functions +evalbytes similar to string eval, but intend to parse a bytestream
c17cdb72 2219
2263ed23
LM
2220This function is like L<C<eval>|/eval EXPR> with a string argument,
2221except it always parses its argument, or L<C<$_>|perlvar/$_> if EXPR is
2222omitted, as a string of bytes. A string containing characters whose
2223ordinal value exceeds 255 results in an error. Source filters activated
2224within the evaluated code apply to the code itself.
7289c5e6 2225
2263ed23
LM
2226L<C<evalbytes>|/evalbytes EXPR> is available only if the
2227L<C<"evalbytes"> feature|feature/The 'unicode_eval' and 'evalbytes' features>
2228is enabled or if it is prefixed with C<CORE::>. The
2229L<C<"evalbytes"> feature|feature/The 'unicode_eval' and 'evalbytes' features>
2230is enabled automatically with a C<use v5.16> (or higher) declaration in
2231the current scope.
7289c5e6 2232
a0d0e21e 2233=item exec LIST
d74e8afc 2234X<exec> X<execute>
a0d0e21e 2235
8bf3b016
GS
2236=item exec PROGRAM LIST
2237
c17cdb72
NC
2238=for Pod::Functions abandon this program to run another
2239
2263ed23
LM
2240The L<C<exec>|/exec LIST> function executes a system command I<and never
2241returns>; use L<C<system>|/system LIST> instead of L<C<exec>|/exec LIST>
2242if you want it to return. It fails and
19799a22 2243returns false only if the command does not exist I<and> it is executed
fb73857a 2244directly instead of via your system's command shell (see below).
a0d0e21e 2245
2263ed23
LM
2246Since it's a common mistake to use L<C<exec>|/exec LIST> instead of
2247L<C<system>|/system LIST>, Perl warns you if L<C<exec>|/exec LIST> is
2248called in void context and if there is a following statement that isn't
2249L<C<die>|/die LIST>, L<C<warn>|/warn LIST>, or L<C<exit>|/exit EXPR> (if
2250L<warnings> are enabled--but you always do that, right?). If you
2251I<really> want to follow an L<C<exec>|/exec LIST> with some other
2252statement, you can use one of these styles to avoid the warning:
55d729e4 2253
5a964f20
TC
2254 exec ('foo') or print STDERR "couldn't exec foo: $!";
2255 { exec ('foo') }; print STDERR "couldn't exec foo: $!";
55d729e4 2256
2263ed23 2257If there is more than one argument in LIST, this calls L<execvp(3)> with the
667eac0c
RS
2258arguments in LIST. If there is only one element in LIST, the argument is
2259checked for shell metacharacters, and if there are any, the entire
2260argument is passed to the system's command shell for parsing (this is
2261C</bin/sh -c> on Unix platforms, but varies on other platforms). If
2262there are no shell metacharacters in the argument, it is split into words
2263and passed directly to C<execvp>, which is more efficient. Examples:
a0d0e21e 2264
19799a22
GS
2265 exec '/bin/echo', 'Your arguments are: ', @ARGV;
2266 exec "sort $outfile | uniq";
a0d0e21e
LW
2267
2268If you don't really want to execute the first argument, but want to lie
2269to the program you are executing about its own name, you can specify
2270the program you actually want to run as an "indirect object" (without a
94d4006a
TS
2271comma) in front of the LIST, as in C<exec PROGRAM LIST>. (This always
2272forces interpretation of the LIST as a multivalued list, even if there
2273is only a single scalar in the list.) Example:
a0d0e21e 2274
2263ed23 2275 my $shell = '/bin/csh';
5ed4f2ec 2276 exec $shell '-sh'; # pretend it's a login shell
a0d0e21e
LW
2277
2278or, more directly,
2279
5ed4f2ec 2280 exec {'/bin/csh'} '-sh'; # pretend it's a login shell
a0d0e21e 2281
3b10bc60 2282When the arguments get executed via the system shell, results are
2283subject to its quirks and capabilities. See L<perlop/"`STRING`">
bb32b41a
GS
2284for details.
2285
2263ed23
LM
2286Using an indirect object with L<C<exec>|/exec LIST> or
2287L<C<system>|/system LIST> is also more secure. This usage (which also
2288works fine with L<C<system>|/system LIST>) forces
19799a22
GS
2289interpretation of the arguments as a multivalued list, even if the
2290list had just one argument. That way you're safe from the shell
2291expanding wildcards or splitting up words with whitespace in them.
5a964f20 2292
2263ed23 2293 my @args = ( "echo surprise" );
5a964f20 2294
2b5ab1e7 2295 exec @args; # subject to shell escapes
f86cebdf 2296 # if @args == 1
2b5ab1e7 2297 exec { $args[0] } @args; # safe even with one-arg list
5a964f20
TC
2298
2299The first version, the one without the indirect object, ran the I<echo>
80d38338
TC
2300program, passing it C<"surprise"> an argument. The second version didn't;
2301it tried to run a program named I<"echo surprise">, didn't find it, and set
2263ed23 2302L<C<$?>|perlvar/$?> to a non-zero value indicating failure.
5a964f20 2303
94d4006a
TS
2304On Windows, only the C<exec PROGRAM LIST> indirect object syntax will
2305reliably avoid using the shell; C<exec LIST>, even with more than one
2306element, will fall back to the shell if the first spawn fails.
2307
e9fa405d
BF
2308Perl attempts to flush all files opened for output before the exec,
2309but this may not be supported on some platforms (see L<perlport>).
2263ed23
LM
2310To be safe, you may need to set L<C<$E<verbar>>|perlvar/$E<verbar>>
2311(C<$AUTOFLUSH> in L<English>) or call the C<autoflush> method of
2312L<C<IO::Handle>|IO::Handle/METHODS> on any open handles to avoid lost
2313output.
0f897271 2314
2263ed23
LM
2315Note that L<C<exec>|/exec LIST> will not call your C<END> blocks, nor
2316will it invoke C<DESTROY> methods on your objects.
7660c0ab 2317
ea9eb35a 2318Portability issues: L<perlport/exec>.
2319
a0d0e21e 2320=item exists EXPR
d74e8afc 2321X<exists> X<autovivification>
a0d0e21e 2322
c17cdb72
NC
2323=for Pod::Functions test whether a hash key is present
2324
d0a76353
RS
2325Given an expression that specifies an element of a hash, returns true if the
2326specified element in the hash has ever been initialized, even if the
2327corresponding value is undefined.
a0d0e21e 2328
5ed4f2ec 2329 print "Exists\n" if exists $hash{$key};
2330 print "Defined\n" if defined $hash{$key};
01020589
GS
2331 print "True\n" if $hash{$key};
2332
d0a76353 2333exists may also be called on array elements, but its behavior is much less
2263ed23
LM
2334obvious and is strongly tied to the use of L<C<delete>|/delete EXPR> on
2335arrays.
2fbadc08 2336
2263ed23
LM
2337B<WARNING:> Calling L<C<exists>|/exists EXPR> on array values is
2338strongly discouraged. The
2fbadc08
RS
2339notion of deleting or checking the existence of Perl array elements is not
2340conceptually coherent, and can lead to surprising behavior.
d0a76353 2341
5ed4f2ec 2342 print "Exists\n" if exists $array[$index];
2343 print "Defined\n" if defined $array[$index];
01020589 2344 print "True\n" if $array[$index];
a0d0e21e 2345
8f1da26d 2346A hash or array element can be true only if it's defined and defined only if
a0d0e21e
LW
2347it exists, but the reverse doesn't necessarily hold true.
2348
afebc493
GS
2349Given an expression that specifies the name of a subroutine,
2350returns true if the specified subroutine has ever been declared, even
2351if it is undefined. Mentioning a subroutine name for exists or defined
80d38338 2352does not count as declaring it. Note that a subroutine that does not
847c7ebe
DD
2353exist may still be callable: its package may have an C<AUTOLOAD>
2354method that makes it spring into existence the first time that it is
3b10bc60 2355called; see L<perlsub>.
afebc493 2356
5ed4f2ec 2357 print "Exists\n" if exists &subroutine;
2358 print "Defined\n" if defined &subroutine;
afebc493 2359
a0d0e21e 2360Note that the EXPR can be arbitrarily complicated as long as the final
afebc493 2361operation is a hash or array key lookup or subroutine name:
a0d0e21e 2362
5ed4f2ec 2363 if (exists $ref->{A}->{B}->{$key}) { }
2364 if (exists $hash{A}{B}{$key}) { }
2b5ab1e7 2365
5ed4f2ec 2366 if (exists $ref->{A}->{B}->[$ix]) { }
2367 if (exists $hash{A}{B}[$ix]) { }
01020589 2368
afebc493
GS
2369 if (exists &{$ref->{A}{B}{$key}}) { }
2370
9590a7cd 2371Although the most deeply nested array or hash element will not spring into
3b10bc60 2372existence just because its existence was tested, any intervening ones will.
61eff3bc 2373Thus C<< $ref->{"A"} >> and C<< $ref->{"A"}->{"B"} >> will spring
2263ed23 2374into existence due to the existence test for the C<$key> element above.
3b10bc60 2375This happens anywhere the arrow operator is used, including even here:
5a964f20 2376
2b5ab1e7 2377 undef $ref;
5ed4f2ec 2378 if (exists $ref->{"Some key"}) { }
2379 print $ref; # prints HASH(0x80d3d5c)
2b5ab1e7
TC
2380
2381This surprising autovivification in what does not at first--or even
2382second--glance appear to be an lvalue context may be fixed in a future
5a964f20 2383release.
a0d0e21e 2384
afebc493 2385Use of a subroutine call, rather than a subroutine name, as an argument
2263ed23 2386to L<C<exists>|/exists EXPR> is an error.
afebc493 2387
5ed4f2ec 2388 exists &sub; # OK
2389 exists &sub(); # Error
afebc493 2390
a0d0e21e 2391=item exit EXPR
d74e8afc 2392X<exit> X<terminate> X<abort>
a0d0e21e 2393
ce2984c3
PF
2394=item exit
2395
c17cdb72
NC
2396=for Pod::Functions terminate this program
2397
2b5ab1e7 2398Evaluates EXPR and exits immediately with that value. Example:
a0d0e21e 2399
2263ed23 2400 my $ans = <STDIN>;
a0d0e21e
LW
2401 exit 0 if $ans =~ /^[Xx]/;
2402
2263ed23
LM
2403See also L<C<die>|/die LIST>. If EXPR is omitted, exits with C<0>
2404status. The only
2b5ab1e7
TC
2405universally recognized values for EXPR are C<0> for success and C<1>
2406for error; other values are subject to interpretation depending on the
2407environment in which the Perl program is running. For example, exiting
240869 (EX_UNAVAILABLE) from a I<sendmail> incoming-mail filter will cause
2409the mailer to return the item undelivered, but that's not true everywhere.
a0d0e21e 2410
2263ed23
LM
2411Don't use L<C<exit>|/exit EXPR> to abort a subroutine if there's any
2412chance that someone might want to trap whatever error happened. Use
2413L<C<die>|/die LIST> instead, which can be trapped by an
2414L<C<eval>|/eval EXPR>.
28757baa 2415
2263ed23
LM
2416The L<C<exit>|/exit EXPR> function does not always exit immediately. It
2417calls any defined C<END> routines first, but these C<END> routines may
2418not themselves abort the exit. Likewise any object destructors that
2419need to be called are called before the real exit. C<END> routines and
2420destructors can change the exit status by modifying L<C<$?>|perlvar/$?>.
2421If this is a problem, you can call
2422L<C<POSIX::_exit($status)>|POSIX/C<_exit>> to avoid C<END> and destructor
2423processing. See L<perlmod> for details.
5a964f20 2424
ea9eb35a 2425Portability issues: L<perlport/exit>.
2426
a0d0e21e 2427=item exp EXPR
d74e8afc 2428X<exp> X<exponential> X<antilog> X<antilogarithm> X<e>
a0d0e21e 2429
54310121 2430=item exp
bbce6d69 2431
c17cdb72
NC
2432=for Pod::Functions raise I<e> to a power
2433
b76cc8ba 2434Returns I<e> (the natural logarithm base) to the power of EXPR.
a0d0e21e
LW
2435If EXPR is omitted, gives C<exp($_)>.
2436
628253b8
BF
2437=item fc EXPR
2438X<fc> X<foldcase> X<casefold> X<fold-case> X<case-fold>
2439
2440=item fc
2441
d9b04284 2442=for Pod::Functions +fc return casefolded version of a string
c17cdb72 2443
628253b8
BF
2444Returns the casefolded version of EXPR. This is the internal function
2445implementing the C<\F> escape in double-quoted strings.
2446
2447Casefolding is the process of mapping strings to a form where case
2448differences are erased; comparing two strings in their casefolded
2449form is effectively a way of asking if two strings are equal,
2450regardless of case.
2451
2452Roughly, if you ever found yourself writing this
2453
f6c6dcb6 2454 lc($this) eq lc($that) # Wrong!
628253b8 2455 # or
f6c6dcb6 2456 uc($this) eq uc($that) # Also wrong!
628253b8 2457 # or
f6c6dcb6 2458 $this =~ /^\Q$that\E\z/i # Right!
628253b8
BF
2459
2460Now you can write
2461
2462 fc($this) eq fc($that)
2463
2464And get the correct results.
2465
2263ed23
LM
2466Perl only implements the full form of casefolding, but you can access
2467the simple folds using L<Unicode::UCD/B<casefold()>> and
2468L<Unicode::UCD/B<prop_invmap()>>.
628253b8
BF
2469For further information on casefolding, refer to
2470the Unicode Standard, specifically sections 3.13 C<Default Case Operations>,
24714.2 C<Case-Normative>, and 5.18 C<Case Mappings>,
2472available at L<http://www.unicode.org/versions/latest/>, as well as the
2473Case Charts available at L<http://www.unicode.org/charts/case/>.
2474
2263ed23 2475If EXPR is omitted, uses L<C<$_>|perlvar/$_>.
628253b8 2476
2263ed23
LM
2477This function behaves the same way under various pragmas, such as within
2478L<S<C<"use feature 'unicode_strings">>|feature/The 'unicode_strings' feature>,
2479as L<C<lc>|/lc EXPR> does, with the single exception of
2480L<C<fc>|/fc EXPR> of I<LATIN CAPITAL LETTER SHARP S> (U+1E9E) within the
2481scope of L<S<C<use locale>>|locale>. The foldcase of this character
2482would normally be C<"ss">, but as explained in the L<C<lc>|/lc EXPR>
2483section, case
1ca267a5
KW
2484changes that cross the 255/256 boundary are problematic under locales,
2485and are hence prohibited. Therefore, this function under locale returns
2263ed23
LM
2486instead the string C<"\x{17F}\x{17F}">, which is the I<LATIN SMALL LETTER
2487LONG S>. Since that character itself folds to C<"s">, the string of two
1ca267a5 2488of them together should be equivalent to a single U+1E9E when foldcased.
628253b8
BF
2489
2490While the Unicode Standard defines two additional forms of casefolding,
2491one for Turkic languages and one that never maps one character into multiple
2263ed23
LM
2492characters, these are not provided by the Perl core. However, the CPAN module
2493L<C<Unicode::Casing>|Unicode::Casing> may be used to provide an implementation.
628253b8 2494
2263ed23
LM
2495L<C<fc>|/fc EXPR> is available only if the
2496L<C<"fc"> feature|feature/The 'fc' feature> is enabled or if it is
2497prefixed with C<CORE::>. The
2498L<C<"fc"> feature|feature/The 'fc' feature> is enabled automatically
2499with a C<use v5.16> (or higher) declaration in the current scope.
628253b8 2500
a0d0e21e 2501=item fcntl FILEHANDLE,FUNCTION,SCALAR
d74e8afc 2502X<fcntl>
a0d0e21e 2503
c17cdb72
NC
2504=for Pod::Functions file control system call
2505
2263ed23 2506Implements the L<fcntl(2)> function. You'll probably have to say
a0d0e21e
LW
2507
2508 use Fcntl;
2509
0ade1984 2510first to get the correct constant definitions. Argument processing and
2263ed23
LM
2511value returned work just like L<C<ioctl>|/ioctl
2512FILEHANDLE,FUNCTION,SCALAR> below. For example:
a0d0e21e
LW
2513
2514 use Fcntl;
d5eedefe 2515 my $flags = fcntl($filehandle, F_GETFL, 0)
2263ed23
LM
2516 or die "Can't fcntl F_GETFL: $!";
2517
2518You don't have to check for L<C<defined>|/defined EXPR> on the return
2519from L<C<fcntl>|/fcntl FILEHANDLE,FUNCTION,SCALAR>. Like
2520L<C<ioctl>|/ioctl FILEHANDLE,FUNCTION,SCALAR>, it maps a C<0> return
2521from the system call into C<"0 but true"> in Perl. This string is true
2522in boolean context and C<0> in numeric context. It is also exempt from
2523the normal
2524L<C<Argument "..." isn't numeric>|perldiag/Argument "%s" isn't numeric%s>
2525L<warnings> on improper numeric conversions.
2526
2527Note that L<C<fcntl>|/fcntl FILEHANDLE,FUNCTION,SCALAR> raises an
2528exception if used on a machine that doesn't implement L<fcntl(2)>. See
2529the L<Fcntl> module or your L<fcntl(2)> manpage to learn what functions
2530are available on your system.
2531
2532Here's an example of setting a filehandle named C<$REMOTE> to be
2533non-blocking at the system level. You'll have to negotiate
2534L<C<$E<verbar>>|perlvar/$E<verbar>> on your own, though.
be2f7487 2535
2536 use Fcntl qw(F_GETFL F_SETFL O_NONBLOCK);
2537
2263ed23
LM
2538 my $flags = fcntl($REMOTE, F_GETFL, 0)
2539 or die "Can't get flags for the socket: $!\n";
be2f7487 2540
2263ed23
LM
2541 fcntl($REMOTE, F_SETFL, $flags | O_NONBLOCK)
2542 or die "Can't set flags for the socket: $!\n";
be2f7487 2543
ea9eb35a 2544Portability issues: L<perlport/fcntl>.
2545
cfa52385
FC
2546=item __FILE__
2547X<__FILE__>
2548
c17cdb72
NC
2549=for Pod::Functions the name of the current source file
2550
cfa52385
FC
2551A special token that returns the name of the file in which it occurs.
2552
a0d0e21e 2553=item fileno FILEHANDLE
d74e8afc 2554X<fileno>
a0d0e21e 2555
c17cdb72
NC
2556=for Pod::Functions return file descriptor from filehandle
2557
2b5ab1e7 2558Returns the file descriptor for a filehandle, or undefined if the
a7c1632d
FC
2559filehandle is not open. If there is no real file descriptor at the OS
2560level, as can happen with filehandles connected to memory objects via
2263ed23
LM
2561L<C<open>|/open FILEHANDLE,EXPR> with a reference for the third
2562argument, -1 is returned.
a7c1632d 2563
2263ed23
LM
2564This is mainly useful for constructing bitmaps for
2565L<C<select>|/select RBITS,WBITS,EBITS,TIMEOUT> and low-level POSIX
2566tty-handling operations.
2b5ab1e7
TC
2567If FILEHANDLE is an expression, the value is taken as an indirect
2568filehandle, generally its name.
5a964f20 2569
b76cc8ba 2570You can use this to find out whether two handles refer to the
5a964f20
TC
2571same underlying descriptor:
2572
2263ed23
LM
2573 if (fileno($this) != -1 && fileno($this) == fileno($that)) {
2574 print "\$this and \$that are dups\n";
2575 } elsif (fileno($this) != -1 && fileno($that) != -1) {
2576 print "\$this and \$that have different " .
555bd962 2577 "underlying file descriptors\n";
3231d257 2578 } else {
2263ed23 2579 print "At least one of \$this and \$that does " .
555bd962 2580 "not have a real file descriptor\n";
b76cc8ba
NIS
2581 }
2582
2263ed23
LM
2583The behavior of L<C<fileno>|/fileno FILEHANDLE> on a directory handle
2584depends on the operating system. On a system with L<dirfd(3)> or
2585similar, L<C<fileno>|/fileno FILEHANDLE> on a directory
67f2cc75
AC
2586handle returns the underlying file descriptor associated with the
2587handle; on systems with no such support, it returns the undefined value,
2263ed23 2588and sets L<C<$!>|perlvar/$!> (errno).
67f2cc75 2589
a0d0e21e 2590=item flock FILEHANDLE,OPERATION
d74e8afc 2591X<flock> X<lock> X<locking>
a0d0e21e 2592
c17cdb72
NC
2593=for Pod::Functions lock an entire file with an advisory lock
2594
2263ed23 2595Calls L<flock(2)>, or an emulation of it, on FILEHANDLE. Returns true
19799a22 2596for success, false on failure. Produces a fatal error if used on a
2263ed23
LM
2597machine that doesn't implement L<flock(2)>, L<fcntl(2)> locking, or
2598L<lockf(3)>. L<C<flock>|/flock FILEHANDLE,OPERATION> is Perl's portable
2599file-locking interface, although it locks entire files only, not
2600records.
2b5ab1e7 2601
2263ed23
LM
2602Two potentially non-obvious but traditional L<C<flock>|/flock
2603FILEHANDLE,OPERATION> semantics are
2b5ab1e7 2604that it waits indefinitely until the lock is granted, and that its locks
dbfe1e81
FC
2605are B<merely advisory>. Such discretionary locks are more flexible, but
2606offer fewer guarantees. This means that programs that do not also use
2263ed23
LM
2607L<C<flock>|/flock FILEHANDLE,OPERATION> may modify files locked with
2608L<C<flock>|/flock FILEHANDLE,OPERATION>. See L<perlport>,
8f1da26d 2609your port's specific documentation, and your system-specific local manpages
2b5ab1e7
TC
2610for details. It's best to assume traditional behavior if you're writing
2611portable programs. (But if you're not, you should as always feel perfectly
2612free to write for your own system's idiosyncrasies (sometimes called
2613"features"). Slavish adherence to portability concerns shouldn't get
2614in the way of your getting your job done.)
a3cb178b 2615
8ebc5c01
PP
2616OPERATION is one of LOCK_SH, LOCK_EX, or LOCK_UN, possibly combined with
2617LOCK_NB. These constants are traditionally valued 1, 2, 8 and 4, but
8f1da26d
TC
2618you can use the symbolic names if you import them from the L<Fcntl> module,
2619either individually, or as a group using the C<:flock> tag. LOCK_SH
68dc0745 2620requests a shared lock, LOCK_EX requests an exclusive lock, and LOCK_UN
ea3105be 2621releases a previously requested lock. If LOCK_NB is bitwise-or'ed with
2263ed23
LM
2622LOCK_SH or LOCK_EX, then L<C<flock>|/flock FILEHANDLE,OPERATION> returns
2623immediately rather than blocking waiting for the lock; check the return
2624status to see if you got it.
68dc0745 2625
2b5ab1e7
TC
2626To avoid the possibility of miscoordination, Perl now flushes FILEHANDLE
2627before locking or unlocking it.
8ebc5c01 2628
2263ed23 2629Note that the emulation built with L<lockf(3)> doesn't provide shared
8ebc5c01 2630locks, and it requires that FILEHANDLE be open with write intent. These
2263ed23
LM
2631are the semantics that L<lockf(3)> implements. Most if not all systems
2632implement L<lockf(3)> in terms of L<fcntl(2)> locking, though, so the
8ebc5c01
PP
2633differing semantics shouldn't bite too many people.
2634
2263ed23 2635Note that the L<fcntl(2)> emulation of L<flock(3)> requires that FILEHANDLE
becacb53
TM
2636be open with read intent to use LOCK_SH and requires that it be open
2637with write intent to use LOCK_EX.
2638
2263ed23
LM
2639Note also that some versions of L<C<flock>|/flock FILEHANDLE,OPERATION>
2640cannot lock things over the network; you would need to use the more
2641system-specific L<C<fcntl>|/fcntl FILEHANDLE,FUNCTION,SCALAR> for
2642that. If you like you can force Perl to ignore your system's L<flock(2)>
2643function, and so provide its own L<fcntl(2)>-based emulation, by passing
8ebc5c01 2644the switch C<-Ud_flock> to the F<Configure> program when you configure
8f1da26d 2645and build a new Perl.
4633a7c4
LW
2646
2647Here's a mailbox appender for BSD systems.
a0d0e21e 2648
f7051f2c
FC
2649 # import LOCK_* and SEEK_END constants
2650 use Fcntl qw(:flock SEEK_END);
a0d0e21e
LW
2651
2652 sub lock {
a9a5a0dc
VP
2653 my ($fh) = @_;
2654 flock($fh, LOCK_EX) or die "Cannot lock mailbox - $!\n";
7ed5353d 2655
a9a5a0dc
VP
2656 # and, in case someone appended while we were waiting...
2657 seek($fh, 0, SEEK_END) or die "Cannot seek - $!\n";
a0d0e21e
LW
2658 }
2659
2660 sub unlock {
a9a5a0dc
VP
2661 my ($fh) = @_;
2662 flock($fh, LOCK_UN) or die "Cannot unlock mailbox - $!\n";
a0d0e21e
LW
2663 }
2664
b0169937 2665 open(my $mbox, ">>", "/usr/spool/mail/$ENV{'USER'}")
5ed4f2ec 2666 or die "Can't open mailbox: $!";
a0d0e21e 2667
7ed5353d 2668 lock($mbox);
b0169937 2669 print $mbox $msg,"\n\n";
7ed5353d 2670 unlock($mbox);
a0d0e21e 2671
2263ed23
LM
2672On systems that support a real L<flock(2)>, locks are inherited across
2673L<C<fork>|/fork> calls, whereas those that must resort to the more
2674capricious L<fcntl(2)> function lose their locks, making it seriously
2675harder to write servers.
2b5ab1e7 2676
2263ed23
LM
2677See also L<DB_File> for other L<C<flock>|/flock FILEHANDLE,OPERATION>
2678examples.
a0d0e21e 2679
ea9eb35a 2680Portability issues: L<perlport/flock>.
2681
a0d0e21e 2682=item fork
d74e8afc 2683X<fork> X<child> X<parent>
a0d0e21e 2684
c17cdb72
NC
2685=for Pod::Functions create a new process just like this one
2686
2263ed23 2687Does a L<fork(2)> system call to create a new process running the
2b5ab1e7 2688same program at the same point. It returns the child pid to the
2263ed23
LM
2689parent process, C<0> to the child process, or L<C<undef>|/undef EXPR> if
2690the fork is
2b5ab1e7
TC
2691unsuccessful. File descriptors (and sometimes locks on those descriptors)
2692are shared, while everything else is copied. On most systems supporting
2263ed23 2693L<fork(2)>, great care has gone into making it extremely efficient (for
2b5ab1e7
TC
2694example, using copy-on-write technology on data pages), making it the
2695dominant paradigm for multitasking over the last few decades.
5a964f20 2696
2263ed23
LM
2697Perl attempts to flush all files opened for output before forking the
2698child process, but this may not be supported on some platforms (see
2699L<perlport>). To be safe, you may need to set
2700L<C<$E<verbar>>|perlvar/$E<verbar>> (C<$AUTOFLUSH> in L<English>) or
2701call the C<autoflush> method of L<C<IO::Handle>|IO::Handle/METHODS> on
2702any open handles to avoid duplicate output.
a0d0e21e 2703
2263ed23 2704If you L<C<fork>|/fork> without ever waiting on your children, you will
2b5ab1e7 2705accumulate zombies. On some systems, you can avoid this by setting
2263ed23
LM
2706L<C<$SIG{CHLD}>|perlvar/%SIG> to C<"IGNORE">. See also L<perlipc> for
2707more examples of forking and reaping moribund children.
cb1a09d0 2708
28757baa
PP
2709Note that if your forked child inherits system file descriptors like
2710STDIN and STDOUT that are actually connected by a pipe or socket, even
2b5ab1e7 2711if you exit, then the remote server (such as, say, a CGI script or a
19799a22 2712backgrounded job launched from a remote shell) won't think you're done.
2b5ab1e7 2713You should reopen those to F</dev/null> if it's any issue.
28757baa 2714
2263ed23
LM
2715On some platforms such as Windows, where the L<fork(2)> system call is
2716not available, Perl can be built to emulate L<C<fork>|/fork> in the Perl
2717interpreter. The emulation is designed, at the level of the Perl
2718program, to be as compatible as possible with the "Unix" L<fork(2)>.
2719However it has limitations that have to be considered in code intended
2720to be portable. See L<perlfork> for more details.
ea9eb35a 2721
2722Portability issues: L<perlport/fork>.
2723
cb1a09d0 2724=item format
d74e8afc 2725X<format>
cb1a09d0 2726
c17cdb72
NC
2727=for Pod::Functions declare a picture format with use by the write() function
2728
2263ed23
LM
2729Declare a picture format for use by the L<C<write>|/write FILEHANDLE>
2730function. For example:
cb1a09d0 2731
54310121 2732 format Something =
a9a5a0dc
VP
2733 Test: @<<<<<<<< @||||| @>>>>>
2734 $str, $%, '$' . int($num)
cb1a09d0
AD
2735 .
2736
2737 $str = "widget";
184e9718 2738 $num = $cost/$quantity;
cb1a09d0
AD
2739 $~ = 'Something';
2740 write;
2741
2742See L<perlform> for many details and examples.
2743
8903cb82 2744=item formline PICTURE,LIST
d74e8afc 2745X<formline>
a0d0e21e 2746
c17cdb72
NC
2747=for Pod::Functions internal function used for formats
2748
2263ed23
LM
2749This is an internal function used by L<C<format>|/format>s, though you
2750may call it, too. It formats (see L<perlform>) a list of values
2751according to the contents of PICTURE, placing the output into the format
2752output accumulator, L<C<$^A>|perlvar/$^A> (or C<$ACCUMULATOR> in
2753L<English>). Eventually, when a L<C<write>|/write FILEHANDLE> is done,
2754the contents of L<C<$^A>|perlvar/$^A> are written to some filehandle.
2755You could also read L<C<$^A>|perlvar/$^A> and then set
2756L<C<$^A>|perlvar/$^A> back to C<"">. Note that a format typically does
2757one L<C<formline>|/formline PICTURE,LIST> per line of form, but the
2758L<C<formline>|/formline PICTURE,LIST> function itself doesn't care how
2759many newlines are embedded in the PICTURE. This means that the C<~> and
2760C<~~> tokens treat the entire PICTURE as a single line. You may
2761therefore need to use multiple formlines to implement a single record
2762format, just like the L<C<format>|/format> compiler.
748a9306 2763
19799a22 2764Be careful if you put double quotes around the picture, because an C<@>
748a9306 2765character may be taken to mean the beginning of an array name.
2263ed23
LM
2766L<C<formline>|/formline PICTURE,LIST> always returns true. See
2767L<perlform> for other examples.
a0d0e21e 2768
2263ed23
LM
2769If you are trying to use this instead of L<C<write>|/write FILEHANDLE>
2770to capture the output, you may find it easier to open a filehandle to a
2771scalar (C<< open my $fh, ">", \$output >>) and write to that instead.
445b09e5 2772
a0d0e21e 2773=item getc FILEHANDLE
f723aae1 2774X<getc> X<getchar> X<character> X<file, read>
a0d0e21e
LW
2775
2776=item getc
2777
c17cdb72
NC
2778=for Pod::Functions get the next character from the filehandle
2779
a0d0e21e 2780Returns the next character from the input file attached to FILEHANDLE,
3b10bc60 2781or the undefined value at end of file or if there was an error (in
2263ed23
LM
2782the latter case L<C<$!>|perlvar/$!> is set). If FILEHANDLE is omitted,
2783reads from
b5fe5ca2
SR
2784STDIN. This is not particularly efficient. However, it cannot be
2785used by itself to fetch single characters without waiting for the user
2786to hit enter. For that, try something more like:
4633a7c4
LW
2787
2788 if ($BSD_STYLE) {
a9a5a0dc 2789 system "stty cbreak </dev/tty >/dev/tty 2>&1";
4633a7c4
LW
2790 }
2791 else {
a9a5a0dc 2792 system "stty", '-icanon', 'eol', "\001";
4633a7c4
LW
2793 }
2794
2263ed23 2795 my $key = getc(STDIN);
4633a7c4
LW
2796
2797 if ($BSD_STYLE) {
a9a5a0dc 2798 system "stty -cbreak </dev/tty >/dev/tty 2>&1";
4633a7c4
LW
2799 }
2800 else {
3b10bc60 2801 system 'stty', 'icanon', 'eol', '^@'; # ASCII NUL
4633a7c4
LW
2802 }
2803 print "\n";
2804
2263ed23
LM
2805Determination of whether C<$BSD_STYLE> should be set is left as an
2806exercise to the reader.
cb1a09d0 2807
2263ed23
LM
2808The L<C<POSIX::getattr>|POSIX/C<getattr>> function can do this more
2809portably on systems purporting POSIX compliance. See also the
2810L<C<Term::ReadKey>|Term::ReadKey> module on CPAN.
a0d0e21e
LW
2811
2812=item getlogin
d74e8afc 2813X<getlogin> X<login>
a0d0e21e 2814
c17cdb72
NC
2815=for Pod::Functions return who logged in at this tty
2816
cf264981 2817This implements the C library function of the same name, which on most
3b10bc60 2818systems returns the current login from F</etc/utmp>, if any. If it
2263ed23 2819returns the empty string, use L<C<getpwuid>|/getpwuid UID>.
a0d0e21e 2820
2263ed23 2821 my $login = getlogin || getpwuid($<) || "Kilroy";
a0d0e21e 2822
2263ed23
LM
2823Do not consider L<C<getlogin>|/getlogin> for authentication: it is not
2824as secure as L<C<getpwuid>|/getpwuid UID>.
4633a7c4 2825
ea9eb35a 2826Portability issues: L<perlport/getlogin>.
2827
a0d0e21e 2828=item getpeername SOCKET
d74e8afc 2829X<getpeername> X<peer>
a0d0e21e 2830
c17cdb72
NC
2831=for Pod::Functions find the other end of a socket connection
2832
a3390c9f
FC
2833Returns the packed sockaddr address of the other end of the SOCKET
2834connection.
a0d0e21e 2835
4633a7c4 2836 use Socket;
2263ed23
LM
2837 my $hersockaddr = getpeername($sock);
2838 my ($port, $iaddr) = sockaddr_in($hersockaddr);
2839 my $herhostname = gethostbyaddr($iaddr, AF_INET);
2840 my $herstraddr = inet_ntoa($iaddr);
a0d0e21e
LW
2841
2842=item getpgrp PID
d74e8afc 2843X<getpgrp> X<group>
a0d0e21e 2844
c17cdb72
NC
2845=for Pod::Functions get process group
2846
47e29363 2847Returns the current process group for the specified PID. Use
7660c0ab 2848a PID of C<0> to get the current process group for the
4633a7c4 2849current process. Will raise an exception if used on a machine that
2263ed23
LM
2850doesn't implement L<getpgrp(2)>. If PID is omitted, returns the process
2851group of the current process. Note that the POSIX version of
2852L<C<getpgrp>|/getpgrp PID> does not accept a PID argument, so only
2853C<PID==0> is truly portable.
a0d0e21e 2854
ea9eb35a 2855Portability issues: L<perlport/getpgrp>.
2856
a0d0e21e 2857=item getppid
d74e8afc 2858X<getppid> X<parent> X<pid>
a0d0e21e 2859
c17cdb72
NC
2860=for Pod::Functions get parent process ID
2861
a0d0e21e
LW
2862Returns the process id of the parent process.
2863
d7c042c9
AB
2864Note for Linux users: Between v5.8.1 and v5.16.0 Perl would work
2865around non-POSIX thread semantics the minority of Linux systems (and
2866Debian GNU/kFreeBSD systems) that used LinuxThreads, this emulation
7161e5c2 2867has since been removed. See the documentation for L<$$|perlvar/$$> for
d7c042c9 2868details.
4d76a344 2869
ea9eb35a 2870Portability issues: L<perlport/getppid>.
2871
a0d0e21e 2872=item getpriority WHICH,WHO
d74e8afc 2873X<getpriority> X<priority> X<nice>
a0d0e21e 2874
c17cdb72
NC
2875=for Pod::Functions get current nice value
2876
4633a7c4 2877Returns the current priority for a process, a process group, or a user.
01aa884e 2878(See L<getpriority(2)>.) Will raise a fatal exception if used on a
2263ed23 2879machine that doesn't implement L<getpriority(2)>.
a0d0e21e 2880
ea9eb35a 2881Portability issues: L<perlport/getpriority>.
2882
a0d0e21e 2883=item getpwnam NAME
d74e8afc
ITB
2884X<getpwnam> X<getgrnam> X<gethostbyname> X<getnetbyname> X<getprotobyname>
2885X<getpwuid> X<getgrgid> X<getservbyname> X<gethostbyaddr> X<getnetbyaddr>
2886X<getprotobynumber> X<getservbyport> X<getpwent> X<getgrent> X<gethostent>
2887X<getnetent> X<getprotoent> X<getservent> X<setpwent> X<setgrent> X<sethostent>
2888X<setnetent> X<setprotoent> X<setservent> X<endpwent> X<endgrent> X<endhostent>
2263ed23 2889X<endnetent> X<endprotoent> X<endservent>
a0d0e21e 2890
c17cdb72
NC
2891=for Pod::Functions get passwd record given user login name
2892
a0d0e21e
LW
2893=item getgrnam NAME
2894
c17cdb72
NC
2895=for Pod::Functions get group record given group name
2896
a0d0e21e
LW
2897=item gethostbyname NAME
2898
c17cdb72
NC
2899=for Pod::Functions get host record given name
2900
a0d0e21e
LW
2901=item getnetbyname NAME
2902
c17cdb72
NC
2903=for Pod::Functions get networks record given name
2904
a0d0e21e
LW
2905=item getprotobyname NAME
2906
c17cdb72
NC
2907=for Pod::Functions get protocol record given name
2908
a0d0e21e
LW
2909=item getpwuid UID
2910
c17cdb72
NC
2911=for Pod::Functions get passwd record given user ID
2912
a0d0e21e
LW
2913=item getgrgid GID
2914
c17cdb72
NC
2915=for Pod::Functions get group record given group user ID
2916
a0d0e21e
LW
2917=item getservbyname NAME,PROTO
2918
c17cdb72
NC
2919=for Pod::Functions get services record given its name
2920
a0d0e21e
LW
2921=item gethostbyaddr ADDR,ADDRTYPE
2922
c17cdb72
NC
2923=for Pod::Functions get host record given its address
2924
a0d0e21e
LW
2925=item getnetbyaddr ADDR,ADDRTYPE
2926
c17cdb72
NC
2927=for Pod::Functions get network record given its address
2928
a0d0e21e
LW
2929=item getprotobynumber NUMBER
2930
c17cdb72
NC
2931=for Pod::Functions get protocol record numeric protocol
2932
a0d0e21e
LW
2933=item getservbyport PORT,PROTO
2934
c17cdb72
NC
2935=for Pod::Functions get services record given numeric port
2936
a0d0e21e
LW
2937=item getpwent
2938
c17cdb72
NC
2939=for Pod::Functions get next passwd record
2940
a0d0e21e
LW
2941=item getgrent
2942
c17cdb72
NC
2943=for Pod::Functions get next group record
2944
a0d0e21e
LW
2945=item gethostent
2946
c17cdb72
NC
2947=for Pod::Functions get next hosts record
2948
a0d0e21e
LW
2949=item getnetent
2950
c17cdb72
NC
2951=for Pod::Functions get next networks record
2952
a0d0e21e
LW
2953=item getprotoent
2954
c17cdb72
NC
2955=for Pod::Functions get next protocols record
2956
a0d0e21e
LW
2957=item getservent
2958
c17cdb72
NC
2959=for Pod::Functions get next services record
2960
a0d0e21e
LW
2961=item setpwent
2962
c17cdb72
NC
2963=for Pod::Functions prepare passwd file for use
2964
a0d0e21e
LW
2965=item setgrent
2966
c17cdb72
NC
2967=for Pod::Functions prepare group file for use
2968
a0d0e21e
LW
2969=item sethostent STAYOPEN
2970
c17cdb72
NC
2971=for Pod::Functions prepare hosts file for use
2972
a0d0e21e
LW
2973=item setnetent STAYOPEN
2974
c17cdb72
NC
2975=for Pod::Functions prepare networks file for use
2976
a0d0e21e
LW
2977=item setprotoent STAYOPEN
2978
c17cdb72
NC
2979=for Pod::Functions prepare protocols file for use
2980
a0d0e21e
LW
2981=item setservent STAYOPEN
2982
c17cdb72
NC
2983=for Pod::Functions prepare services file for use
2984
a0d0e21e
LW
2985=item endpwent
2986
c17cdb72
NC
2987=for Pod::Functions be done using passwd file
2988
a0d0e21e
LW
2989=item endgrent
2990
c17cdb72
NC
2991=for Pod::Functions be done using group file
2992
a0d0e21e
LW
2993=item endhostent
2994
c17cdb72
NC
2995=for Pod::Functions be done using hosts file
2996
a0d0e21e
LW
2997=item endnetent
2998
c17cdb72
NC
2999=for Pod::Functions be done using networks file
3000
a0d0e21e
LW
3001=item endprotoent
3002
c17cdb72
NC
3003=for Pod::Functions be done using protocols file
3004
a0d0e21e
LW
3005=item endservent
3006
c17cdb72
NC
3007=for Pod::Functions be done using services file
3008
80d38338
TC
3009These routines are the same as their counterparts in the
3010system C library. In list context, the return values from the
a0d0e21e
LW
3011various get routines are as follows:
3012
2263ed23
LM
3013 # 0 1 2 3 4
3014 my ( $name, $passwd, $gid, $members ) = getgr*
3015 my ( $name, $aliases, $addrtype, $net ) = getnet*
3016 my ( $name, $aliases, $port, $proto ) = getserv*
3017 my ( $name, $aliases, $proto ) = getproto*
3018 my ( $name, $aliases, $addrtype, $length, @addrs ) = gethost*
3019 my ( $name, $passwd, $uid, $gid, $quota,
3020 $comment, $gcos, $dir, $shell, $expire ) = getpw*
3021 # 5 6 7 8 9
a0d0e21e 3022
75f7c783
FC
3023(If the entry doesn't exist, the return value is a single meaningless true
3024value.)
a0d0e21e 3025
4602f195
JH
3026The exact meaning of the $gcos field varies but it usually contains
3027the real name of the user (as opposed to the login name) and other
3028information pertaining to the user. Beware, however, that in many
3029system users are able to change this information and therefore it
106325ad 3030cannot be trusted and therefore the $gcos is tainted (see
2959b6e3 3031L<perlsec>). The $passwd and $shell, user's encrypted password and
a3390c9f 3032login shell, are also tainted, for the same reason.
4602f195 3033
5a964f20 3034In scalar context, you get the name, unless the function was a
a0d0e21e
LW
3035lookup by name, in which case you get the other thing, whatever it is.
3036(If the entry doesn't exist you get the undefined value.) For example:
3037
2263ed23
LM
3038 my $uid = getpwnam($name);
3039 my $name = getpwuid($num);
3040 my $name = getpwent();
3041 my $gid = getgrnam($name);
3042 my $name = getgrgid($num);
3043 my $name = getgrent();
3044 # etc.
a0d0e21e 3045
4602f195 3046In I<getpw*()> the fields $quota, $comment, and $expire are special
80d38338 3047in that they are unsupported on many systems. If the
4602f195
JH
3048$quota is unsupported, it is an empty scalar. If it is supported, it
3049usually encodes the disk quota. If the $comment field is unsupported,
3050it is an empty scalar. If it is supported it usually encodes some
3051administrative comment about the user. In some systems the $quota
3052field may be $change or $age, fields that have to do with password
3053aging. In some systems the $comment field may be $class. The $expire
3054field, if present, encodes the expiration period of the account or the
3055password. For the availability and the exact meaning of these fields
2263ed23 3056in your system, please consult L<getpwnam(3)> and your system's
4602f195
JH
3057F<pwd.h> file. You can also find out from within Perl what your
3058$quota and $comment fields mean and whether you have the $expire field
2263ed23 3059by using the L<C<Config>|Config> module and the values C<d_pwquota>, C<d_pwage>,
4602f195 3060C<d_pwchange>, C<d_pwcomment>, and C<d_pwexpire>. Shadow password
3b10bc60 3061files are supported only if your vendor has implemented them in the
4602f195 3062intuitive fashion that calling the regular C library routines gets the
5d3a0a3b 3063shadow versions if you're running under privilege or if there exists
2263ed23 3064the L<shadow(3)> functions as found in System V (this includes Solaris
a3390c9f 3065and Linux). Those systems that implement a proprietary shadow password
5d3a0a3b 3066facility are unlikely to be supported.
6ee623d5 3067
a3390c9f 3068The $members value returned by I<getgr*()> is a space-separated list of
a0d0e21e
LW
3069the login names of the members of the group.
3070
3071For the I<gethost*()> functions, if the C<h_errno> variable is supported in
2263ed23
LM
3072C, it will be returned to you via L<C<$?>|perlvar/$?> if the function
3073call fails. The
3b10bc60 3074C<@addrs> value returned by a successful call is a list of raw
3075addresses returned by the corresponding library call. In the
3076Internet domain, each address is four bytes long; you can unpack it
a0d0e21e
LW
3077by saying something like:
3078
2263ed23 3079 my ($w,$x,$y,$z) = unpack('W4',$addr[0]);
a0d0e21e 3080
2b5ab1e7
TC
3081The Socket library makes this slightly easier:
3082
3083 use Socket;
2263ed23
LM
3084 my $iaddr = inet_aton("127.1"); # or whatever address
3085 my $name = gethostbyaddr($iaddr, AF_INET);
2b5ab1e7
TC
3086
3087 # or going the other way
2263ed23 3088 my $straddr = inet_ntoa($iaddr);
2b5ab1e7 3089
d760c846
GS
3090In the opposite way, to resolve a hostname to the IP address
3091you can write this:
3092
3093 use Socket;
2263ed23
LM
3094 my $packed_ip = gethostbyname("www.perl.org");
3095 my $ip_address;
d760c846
GS
3096 if (defined $packed_ip) {
3097 $ip_address = inet_ntoa($packed_ip);
3098 }
3099
2263ed23
LM
3100Make sure L<C<gethostbyname>|/gethostbyname NAME> is called in SCALAR
3101context and that its return value is checked for definedness.
d760c846 3102
2263ed23
LM
3103The L<C<getprotobynumber>|/getprotobynumber NUMBER> function, even
3104though it only takes one argument, has the precedence of a list
3105operator, so beware:
0d043efa
FC
3106
3107 getprotobynumber $number eq 'icmp' # WRONG
3108 getprotobynumber($number eq 'icmp') # actually means this
3109 getprotobynumber($number) eq 'icmp' # better this way
3110
19799a22 3111If you get tired of remembering which element of the return list
2263ed23
LM
3112contains which return value, by-name interfaces are provided in standard
3113modules: L<C<File::stat>|File::stat>, L<C<Net::hostent>|Net::hostent>,
3114L<C<Net::netent>|Net::netent>, L<C<Net::protoent>|Net::protoent>,
3115L<C<Net::servent>|Net::servent>, L<C<Time::gmtime>|Time::gmtime>,
3116L<C<Time::localtime>|Time::localtime>, and
3117L<C<User::grent>|User::grent>. These override the normal built-ins,
3118supplying versions that return objects with the appropriate names for
3119each field. For example:
5a964f20
TC
3120
3121 use File::stat;
3122 use User::pwent;
2263ed23 3123 my $is_his = (stat($filename)->uid == pwent($whoever)->uid);
5a964f20 3124
a3390c9f 3125Even though it looks as though they're the same method calls (uid),
b76cc8ba 3126they aren't, because a C<File::stat> object is different from
19799a22 3127a C<User::pwent> object.
5a964f20 3128
ea9eb35a 3129Portability issues: L<perlport/getpwnam> to L<perlport/endservent>.
3130
a0d0e21e 3131=item getsockname SOCKET
d74e8afc 3132X<getsockname>
a0d0e21e 3133
c17cdb72
NC
3134=for Pod::Functions retrieve the sockaddr for a given socket
3135
19799a22
GS
3136Returns the packed sockaddr address of this end of the SOCKET connection,
3137in case you don't know the address because you have several different
3138IPs that the connection might have come in on.
a0d0e21e 3139
4633a7c4 3140 use Socket;
2263ed23
LM
3141 my $mysockaddr = getsockname($sock);
3142 my ($port, $myaddr) = sockaddr_in($mysockaddr);
b76cc8ba 3143 printf "Connect to %s [%s]\n",
19799a22
GS
3144 scalar gethostbyaddr($myaddr, AF_INET),
3145 inet_ntoa($myaddr);
a0d0e21e
LW
3146
3147=item getsockopt SOCKET,LEVEL,OPTNAME
d74e8afc 3148X<getsockopt>
a0d0e21e 3149
c17cdb72
NC
3150=for Pod::Functions get socket options on a given socket
3151
636e6b1f
TH
3152Queries the option named OPTNAME associated with SOCKET at a given LEVEL.
3153Options may exist at multiple protocol levels depending on the socket
3154type, but at least the uppermost socket level SOL_SOCKET (defined in the
2263ed23
LM
3155L<C<Socket>|Socket> module) will exist. To query options at another
3156level the protocol number of the appropriate protocol controlling the
3157option should be supplied. For example, to indicate that an option is
3158to be interpreted by the TCP protocol, LEVEL should be set to the
3159protocol number of TCP, which you can get using
3160L<C<getprotobyname>|/getprotobyname NAME>.
636e6b1f 3161
80d38338 3162The function returns a packed string representing the requested socket
2263ed23
LM
3163option, or L<C<undef>|/undef EXPR> on error, with the reason for the
3164error placed in L<C<$!>|perlvar/$!>. Just what is in the packed string
3165depends on LEVEL and OPTNAME; consult L<getsockopt(2)> for details. A
3166common case is that the option is an integer, in which case the result
3167is a packed integer, which you can decode using
3168L<C<unpack>|/unpack TEMPLATE,EXPR> with the C<i> (or C<I>) format.
636e6b1f 3169