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