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