Commit | Line | Data |
a687059c |
1 | ''' Beginning of part 3 |
33b78306 |
2 | ''' $Header: perl_man.3,v 3.0.1.8 90/08/09 04:39:04 lwall Locked $ |
a687059c |
3 | ''' |
4 | ''' $Log: perl.man.3,v $ |
33b78306 |
5 | ''' Revision 3.0.1.8 90/08/09 04:39:04 lwall |
6 | ''' patch19: added require operator |
7 | ''' patch19: added truncate operator |
8 | ''' patch19: unpack can do checksumming |
9 | ''' |
10 | ''' Revision 3.0.1.7 90/08/03 11:15:42 lwall |
11 | ''' patch19: Intermediate diffs for Randal |
12 | ''' |
0f85fab0 |
13 | ''' Revision 3.0.1.6 90/03/27 16:17:56 lwall |
14 | ''' patch16: MSDOS support |
15 | ''' |
79a0689e |
16 | ''' Revision 3.0.1.5 90/03/12 16:52:21 lwall |
17 | ''' patch13: documented that print $filehandle &foo is ambiguous |
18 | ''' patch13: added splice operator: @oldelems = splice(@array,$offset,$len,LIST) |
19 | ''' |
ac58e20f |
20 | ''' Revision 3.0.1.4 90/02/28 18:00:09 lwall |
21 | ''' patch9: added pipe function |
22 | ''' patch9: documented how to handle arbitrary weird characters in filenames |
23 | ''' patch9: documented the unflushed buffers problem on piped opens |
24 | ''' patch9: documented how to force top of page |
25 | ''' |
663a0e37 |
26 | ''' Revision 3.0.1.3 89/12/21 20:10:12 lwall |
27 | ''' patch7: documented that s`pat`repl` does command substitution on replacement |
28 | ''' patch7: documented that $timeleft from select() is likely not implemented |
29 | ''' |
ffed7fef |
30 | ''' Revision 3.0.1.2 89/11/17 15:31:05 lwall |
31 | ''' patch5: fixed some manual typos and indent problems |
32 | ''' patch5: added warning about print making an array context |
33 | ''' |
ae986130 |
34 | ''' Revision 3.0.1.1 89/11/11 04:45:06 lwall |
35 | ''' patch2: made some line breaks depend on troff vs. nroff |
36 | ''' |
a687059c |
37 | ''' Revision 3.0 89/10/18 15:21:46 lwall |
38 | ''' 3.0 baseline |
39 | ''' |
40 | .Ip "next LABEL" 8 8 |
41 | .Ip "next" 8 |
42 | The |
43 | .I next |
44 | command is like the |
45 | .I continue |
46 | statement in C; it starts the next iteration of the loop: |
47 | .nf |
48 | |
49 | .ne 4 |
50 | line: while (<STDIN>) { |
51 | next line if /\|^#/; # discard comments |
52 | .\|.\|. |
53 | } |
54 | |
55 | .fi |
56 | Note that if there were a |
57 | .I continue |
58 | block on the above, it would get executed even on discarded lines. |
59 | If the LABEL is omitted, the command refers to the innermost enclosing loop. |
60 | .Ip "oct(EXPR)" 8 4 |
61 | .Ip "oct EXPR" 8 |
62 | Returns the decimal value of EXPR interpreted as an octal string. |
63 | (If EXPR happens to start off with 0x, interprets it as a hex string instead.) |
64 | The following will handle decimal, octal and hex in the standard notation: |
65 | .nf |
66 | |
67 | $val = oct($val) if $val =~ /^0/; |
68 | |
69 | .fi |
70 | If EXPR is omitted, uses $_. |
71 | .Ip "open(FILEHANDLE,EXPR)" 8 8 |
72 | .Ip "open(FILEHANDLE)" 8 |
73 | .Ip "open FILEHANDLE" 8 |
74 | Opens the file whose filename is given by EXPR, and associates it with |
75 | FILEHANDLE. |
76 | If FILEHANDLE is an expression, its value is used as the name of the |
77 | real filehandle wanted. |
78 | If EXPR is omitted, the scalar variable of the same name as the FILEHANDLE |
79 | contains the filename. |
80 | If the filename begins with \*(L"<\*(R" or nothing, the file is opened for |
81 | input. |
82 | If the filename begins with \*(L">\*(R", the file is opened for output. |
83 | If the filename begins with \*(L">>\*(R", the file is opened for appending. |
84 | (You can put a \'+\' in front of the \'>\' or \'<\' to indicate that you |
85 | want both read and write access to the file.) |
86 | If the filename begins with \*(L"|\*(R", the filename is interpreted |
87 | as a command to which output is to be piped, and if the filename ends |
88 | with a \*(L"|\*(R", the filename is interpreted as command which pipes |
89 | input to us. |
90 | (You may not have a command that pipes both in and out.) |
91 | Opening \'\-\' opens |
92 | .I STDIN |
93 | and opening \'>\-\' opens |
94 | .IR STDOUT . |
95 | Open returns non-zero upon success, the undefined value otherwise. |
96 | If the open involved a pipe, the return value happens to be the pid |
97 | of the subprocess. |
98 | Examples: |
99 | .nf |
100 | |
101 | .ne 3 |
102 | $article = 100; |
103 | open article || die "Can't find article $article: $!\en"; |
104 | while (<article>) {\|.\|.\|. |
105 | |
ae986130 |
106 | .ie t \{\ |
a687059c |
107 | open(LOG, \'>>/usr/spool/news/twitlog\'\|); # (log is reserved) |
ae986130 |
108 | 'br\} |
109 | .el \{\ |
110 | open(LOG, \'>>/usr/spool/news/twitlog\'\|); |
111 | # (log is reserved) |
112 | 'br\} |
a687059c |
113 | |
ae986130 |
114 | .ie t \{\ |
a687059c |
115 | open(article, "caesar <$article |"\|); # decrypt article |
ae986130 |
116 | 'br\} |
117 | .el \{\ |
118 | open(article, "caesar <$article |"\|); |
119 | # decrypt article |
120 | 'br\} |
a687059c |
121 | |
ae986130 |
122 | .ie t \{\ |
a687059c |
123 | open(extract, "|sort >/tmp/Tmp$$"\|); # $$ is our process# |
ae986130 |
124 | 'br\} |
125 | .el \{\ |
126 | open(extract, "|sort >/tmp/Tmp$$"\|); |
127 | # $$ is our process# |
128 | 'br\} |
a687059c |
129 | |
130 | .ne 7 |
131 | # process argument list of files along with any includes |
132 | |
133 | foreach $file (@ARGV) { |
134 | do process($file, \'fh00\'); # no pun intended |
135 | } |
136 | |
137 | sub process { |
138 | local($filename, $input) = @_; |
139 | $input++; # this is a string increment |
140 | unless (open($input, $filename)) { |
141 | print STDERR "Can't open $filename: $!\en"; |
142 | return; |
143 | } |
ae986130 |
144 | .ie t \{\ |
a687059c |
145 | while (<$input>) { # note the use of indirection |
ae986130 |
146 | 'br\} |
147 | .el \{\ |
148 | while (<$input>) { # note use of indirection |
149 | 'br\} |
a687059c |
150 | if (/^#include "(.*)"/) { |
151 | do process($1, $input); |
152 | next; |
153 | } |
154 | .\|.\|. # whatever |
155 | } |
156 | } |
157 | |
158 | .fi |
159 | You may also, in the Bourne shell tradition, specify an EXPR beginning |
160 | with \*(L">&\*(R", in which case the rest of the string |
161 | is interpreted as the name of a filehandle |
162 | (or file descriptor, if numeric) which is to be duped and opened. |
ae986130 |
163 | You may use & after >, >>, <, +>, +>> and +<. |
164 | The mode you specify should match the mode of the original filehandle. |
a687059c |
165 | Here is a script that saves, redirects, and restores |
166 | .I STDOUT |
167 | and |
ae986130 |
168 | .IR STDERR : |
a687059c |
169 | .nf |
170 | |
171 | .ne 21 |
172 | #!/usr/bin/perl |
173 | open(SAVEOUT, ">&STDOUT"); |
174 | open(SAVEERR, ">&STDERR"); |
175 | |
176 | open(STDOUT, ">foo.out") || die "Can't redirect stdout"; |
177 | open(STDERR, ">&STDOUT") || die "Can't dup stdout"; |
178 | |
179 | select(STDERR); $| = 1; # make unbuffered |
180 | select(STDOUT); $| = 1; # make unbuffered |
181 | |
182 | print STDOUT "stdout 1\en"; # this works for |
183 | print STDERR "stderr 1\en"; # subprocesses too |
184 | |
185 | close(STDOUT); |
186 | close(STDERR); |
187 | |
188 | open(STDOUT, ">&SAVEOUT"); |
189 | open(STDERR, ">&SAVEERR"); |
190 | |
191 | print STDOUT "stdout 2\en"; |
192 | print STDERR "stderr 2\en"; |
193 | |
194 | .fi |
195 | If you open a pipe on the command \*(L"\-\*(R", i.e. either \*(L"|\-\*(R" or \*(L"\-|\*(R", |
196 | then there is an implicit fork done, and the return value of open |
197 | is the pid of the child within the parent process, and 0 within the child |
198 | process. |
199 | (Use defined($pid) to determine if the open was successful.) |
200 | The filehandle behaves normally for the parent, but i/o to that |
201 | filehandle is piped from/to the |
202 | .IR STDOUT / STDIN |
203 | of the child process. |
204 | In the child process the filehandle isn't opened\*(--i/o happens from/to |
205 | the new |
206 | .I STDOUT |
207 | or |
208 | .IR STDIN . |
209 | Typically this is used like the normal piped open when you want to exercise |
210 | more control over just how the pipe command gets executed, such as when |
211 | you are running setuid, and don't want to have to scan shell commands |
212 | for metacharacters. |
33b78306 |
213 | The following pairs are more or less equivalent: |
a687059c |
214 | .nf |
215 | |
216 | .ne 5 |
217 | open(FOO, "|tr \'[a\-z]\' \'[A\-Z]\'"); |
218 | open(FOO, "|\-") || exec \'tr\', \'[a\-z]\', \'[A\-Z]\'; |
219 | |
33b78306 |
220 | open(FOO, "cat \-n '$file'|"); |
a687059c |
221 | open(FOO, "\-|") || exec \'cat\', \'\-n\', $file; |
222 | |
223 | .fi |
224 | Explicitly closing any piped filehandle causes the parent process to wait for the |
225 | child to finish, and returns the status value in $?. |
ac58e20f |
226 | Note: on any operation which may do a fork, |
227 | unflushed buffers remain unflushed in both |
228 | processes, which means you may need to set $| to |
229 | avoid duplicate output. |
230 | .Sp |
231 | The filename that is passed to open will have leading and trailing |
232 | whitespace deleted. |
233 | In order to open a file with arbitrary weird characters in it, it's necessary |
234 | to protect any leading and trailing whitespace thusly: |
235 | .nf |
236 | |
237 | .ne 2 |
238 | $file =~ s#^(\es)#./$1#; |
239 | open(FOO, "< $file\e0"); |
240 | |
241 | .fi |
a687059c |
242 | .Ip "opendir(DIRHANDLE,EXPR)" 8 3 |
243 | Opens a directory named EXPR for processing by readdir(), telldir(), seekdir(), |
244 | rewinddir() and closedir(). |
245 | Returns true if successful. |
246 | DIRHANDLEs have their own namespace separate from FILEHANDLEs. |
247 | .Ip "ord(EXPR)" 8 4 |
248 | .Ip "ord EXPR" 8 |
0f85fab0 |
249 | Returns the numeric ascii value of the first character of EXPR. |
a687059c |
250 | If EXPR is omitted, uses $_. |
33b78306 |
251 | ''' Comments on f & d by gnb@melba.bby.oz.au 22/11/89 |
a687059c |
252 | .Ip "pack(TEMPLATE,LIST)" 8 4 |
253 | Takes an array or list of values and packs it into a binary structure, |
254 | returning the string containing the structure. |
255 | The TEMPLATE is a sequence of characters that give the order and type |
256 | of values, as follows: |
257 | .nf |
258 | |
259 | A An ascii string, will be space padded. |
260 | a An ascii string, will be null padded. |
33b78306 |
261 | c A signed char value. |
a687059c |
262 | C An unsigned char value. |
263 | s A signed short value. |
264 | S An unsigned short value. |
265 | i A signed integer value. |
266 | I An unsigned integer value. |
267 | l A signed long value. |
268 | L An unsigned long value. |
269 | n A short in \*(L"network\*(R" order. |
270 | N A long in \*(L"network\*(R" order. |
33b78306 |
271 | f A single-precision float in the native format. |
272 | d A double-precision float in the native format. |
a687059c |
273 | p A pointer to a string. |
274 | x A null byte. |
33b78306 |
275 | X Back up a byte. |
276 | @ Null fill to absolute position. |
277 | u A uuencoded string. |
a687059c |
278 | |
279 | .fi |
280 | Each letter may optionally be followed by a number which gives a repeat |
281 | count. |
282 | With all types except "a" and "A" the pack function will gobble up that many values |
283 | from the LIST. |
33b78306 |
284 | A * for the repeat count means to use however many items are left. |
285 | The "a" and "A" types gobble just one value, but pack it as a string of length |
286 | count, |
a687059c |
287 | padding with nulls or spaces as necessary. |
288 | (When unpacking, "A" strips trailing spaces and nulls, but "a" does not.) |
33b78306 |
289 | Real numbers (floats and doubles) are in the nnativeative machine format |
290 | only; due to the multiplicity of floating formats around, and the lack |
291 | of a standard \*(L"network\*(R" representation, no facility for |
292 | interchange has been made. |
293 | This means that packed floating point data |
294 | written on one machine may not be readable on another - even if both |
295 | use IEEE floating point arithmetic (as the endian-ness of the memory |
296 | representation is not part of the IEEE spec). |
297 | Note that perl uses |
298 | doubles internally for all numeric calculation, and converting from |
299 | double -> float -> double will loose precision (i.e. unpack("f", |
300 | pack("f", $foo)) will not in general equal $foo). |
301 | .br |
a687059c |
302 | Examples: |
303 | .nf |
304 | |
305 | $foo = pack("cccc",65,66,67,68); |
306 | # foo eq "ABCD" |
307 | $foo = pack("c4",65,66,67,68); |
308 | # same thing |
309 | |
310 | $foo = pack("ccxxcc",65,66,67,68); |
311 | # foo eq "AB\e0\e0CD" |
312 | |
313 | $foo = pack("s2",1,2); |
314 | # "\e1\e0\e2\e0" on little-endian |
315 | # "\e0\e1\e0\e2" on big-endian |
316 | |
317 | $foo = pack("a4","abcd","x","y","z"); |
318 | # "abcd" |
319 | |
320 | $foo = pack("aaaa","abcd","x","y","z"); |
321 | # "axyz" |
322 | |
323 | $foo = pack("a14","abcdefg"); |
324 | # "abcdefg\e0\e0\e0\e0\e0\e0\e0" |
325 | |
ae986130 |
326 | $foo = pack("i9pl", gmtime); |
a687059c |
327 | # a real struct tm (on my system anyway) |
328 | |
329 | .fi |
330 | The same template may generally also be used in the unpack function. |
ac58e20f |
331 | .Ip "pipe(READHANDLE,WRITEHANDLE)" 8 3 |
332 | Opens a pair of connected pipes like the corresponding system call. |
333 | Note that if you set up a loop of piped processes, deadlock can occur |
334 | unless you are very careful. |
335 | In addition, note that perl's pipes use stdio buffering, so you may need |
336 | to set $| to flush your WRITEHANDLE after each command, depending on |
337 | the application. |
338 | [Requires version 3.0 patchlevel 9.] |
a687059c |
339 | .Ip "pop(ARRAY)" 8 |
340 | .Ip "pop ARRAY" 8 6 |
341 | Pops and returns the last value of the array, shortening the array by 1. |
342 | Has the same effect as |
343 | .nf |
344 | |
345 | $tmp = $ARRAY[$#ARRAY\-\|\-]; |
346 | |
347 | .fi |
348 | If there are no elements in the array, returns the undefined value. |
349 | .Ip "print(FILEHANDLE LIST)" 8 10 |
350 | .Ip "print(LIST)" 8 |
351 | .Ip "print FILEHANDLE LIST" 8 |
352 | .Ip "print LIST" 8 |
353 | .Ip "print" 8 |
354 | Prints a string or a comma-separated list of strings. |
355 | Returns non-zero if successful. |
356 | FILEHANDLE may be a scalar variable name, in which case the variable contains |
357 | the name of the filehandle, thus introducing one level of indirection. |
79a0689e |
358 | (NOTE: If FILEHANDLE is a variable and the next token is a term, it may be |
359 | misinterpreted as an operator unless you interpose a + or put parens around |
360 | the arguments.) |
a687059c |
361 | If FILEHANDLE is omitted, prints by default to standard output (or to the |
362 | last selected output channel\*(--see select()). |
363 | If LIST is also omitted, prints $_ to |
364 | .IR STDOUT . |
365 | To set the default output channel to something other than |
366 | .I STDOUT |
367 | use the select operation. |
ffed7fef |
368 | Note that, because print takes a LIST, anything in the LIST is evaluated |
369 | in an array context, and any subroutine that you call will have one or more |
370 | of its expressions evaluated in an array context. |
79a0689e |
371 | Also be careful not to follow the print keyword with a left parenthesis |
372 | unless you want the corresponding right parenthesis to terminate the |
373 | arguments to the print--interpose a + or put parens around all the arguments. |
a687059c |
374 | .Ip "printf(FILEHANDLE LIST)" 8 10 |
375 | .Ip "printf(LIST)" 8 |
376 | .Ip "printf FILEHANDLE LIST" 8 |
377 | .Ip "printf LIST" 8 |
378 | Equivalent to a \*(L"print FILEHANDLE sprintf(LIST)\*(R". |
379 | .Ip "push(ARRAY,LIST)" 8 7 |
380 | Treats ARRAY (@ is optional) as a stack, and pushes the values of LIST |
381 | onto the end of ARRAY. |
382 | The length of ARRAY increases by the length of LIST. |
383 | Has the same effect as |
384 | .nf |
385 | |
386 | for $value (LIST) { |
387 | $ARRAY[++$#ARRAY] = $value; |
388 | } |
389 | |
390 | .fi |
391 | but is more efficient. |
392 | .Ip "q/STRING/" 8 5 |
393 | .Ip "qq/STRING/" 8 |
394 | These are not really functions, but simply syntactic sugar to let you |
395 | avoid putting too many backslashes into quoted strings. |
396 | The q operator is a generalized single quote, and the qq operator a |
397 | generalized double quote. |
33b78306 |
398 | Any non-alphanumeric delimiter can be used in place of /, including newline. |
a687059c |
399 | If the delimiter is an opening bracket or parenthesis, the final delimiter |
400 | will be the corresponding closing bracket or parenthesis. |
401 | (Embedded occurrences of the closing bracket need to be backslashed as usual.) |
402 | Examples: |
403 | .nf |
404 | |
405 | .ne 5 |
406 | $foo = q!I said, "You said, \'She said it.\'"!; |
407 | $bar = q(\'This is it.\'); |
408 | $_ .= qq |
409 | *** The previous line contains the naughty word "$&".\en |
410 | if /(ibm|apple|awk)/; # :-) |
411 | |
412 | .fi |
413 | .Ip "rand(EXPR)" 8 8 |
414 | .Ip "rand EXPR" 8 |
415 | .Ip "rand" 8 |
416 | Returns a random fractional number between 0 and the value of EXPR. |
417 | (EXPR should be positive.) |
418 | If EXPR is omitted, returns a value between 0 and 1. |
419 | See also srand(). |
420 | .Ip "read(FILEHANDLE,SCALAR,LENGTH)" 8 5 |
421 | Attempts to read LENGTH bytes of data into variable SCALAR from the specified |
422 | FILEHANDLE. |
423 | Returns the number of bytes actually read. |
424 | SCALAR will be grown or shrunk to the length actually read. |
425 | .Ip "readdir(DIRHANDLE)" 8 3 |
ae986130 |
426 | .Ip "readdir DIRHANDLE" 8 |
a687059c |
427 | Returns the next directory entry for a directory opened by opendir(). |
428 | If used in an array context, returns all the rest of the entries in the |
429 | directory. |
430 | If there are no more entries, returns an undefined value in a scalar context |
431 | or a null list in an array context. |
432 | .Ip "readlink(EXPR)" 8 6 |
433 | .Ip "readlink EXPR" 8 |
434 | Returns the value of a symbolic link, if symbolic links are implemented. |
435 | If not, gives a fatal error. |
436 | If there is some system error, returns the undefined value and sets $! (errno). |
437 | If EXPR is omitted, uses $_. |
438 | .Ip "recv(SOCKET,SCALAR,LEN,FLAGS)" 8 4 |
439 | Receives a message on a socket. |
440 | Attempts to receive LENGTH bytes of data into variable SCALAR from the specified |
441 | SOCKET filehandle. |
442 | Returns the address of the sender, or the undefined value if there's an error. |
443 | SCALAR will be grown or shrunk to the length actually read. |
444 | Takes the same flags as the system call of the same name. |
445 | .Ip "redo LABEL" 8 8 |
446 | .Ip "redo" 8 |
447 | The |
448 | .I redo |
449 | command restarts the loop block without evaluating the conditional again. |
450 | The |
451 | .I continue |
452 | block, if any, is not executed. |
453 | If the LABEL is omitted, the command refers to the innermost enclosing loop. |
454 | This command is normally used by programs that want to lie to themselves |
455 | about what was just input: |
456 | .nf |
457 | |
458 | .ne 16 |
459 | # a simpleminded Pascal comment stripper |
460 | # (warning: assumes no { or } in strings) |
461 | line: while (<STDIN>) { |
462 | while (s|\|({.*}.*\|){.*}|$1 \||) {} |
463 | s|{.*}| \||; |
464 | if (s|{.*| \||) { |
465 | $front = $_; |
466 | while (<STDIN>) { |
467 | if (\|/\|}/\|) { # end of comment? |
468 | s|^|$front{|; |
469 | redo line; |
470 | } |
471 | } |
472 | } |
473 | print; |
474 | } |
475 | |
476 | .fi |
477 | .Ip "rename(OLDNAME,NEWNAME)" 8 2 |
478 | Changes the name of a file. |
479 | Returns 1 for success, 0 otherwise. |
480 | Will not work across filesystem boundaries. |
33b78306 |
481 | .Ip "require(EXPR)" 8 6 |
482 | .Ip "require EXPR" 8 |
483 | .Ip "require" 8 |
484 | Includes the library file specified by EXPR, or by $_ if EXPR is not supplied. |
485 | Has semantics similar to the following subroutine: |
486 | .nf |
487 | |
488 | sub require { |
489 | local($filename) = @_; |
490 | return 1 if $INC{$filename}; |
491 | local($realfilename,$result); |
492 | ITER: { |
493 | foreach $prefix (@INC) { |
494 | $realfilename = "$prefix/$filename"; |
495 | if (-f $realfilename) { |
496 | $result = do $realfilename; |
497 | last ITER; |
498 | } |
499 | } |
500 | die "Can't find $filename in \e@INC"; |
501 | } |
502 | die $@ if $@; |
503 | die "$filename did not return true value" unless $result; |
504 | $INC{$filename} = $realfilename; |
505 | $result; |
506 | } |
507 | |
508 | .fi |
509 | Note that the file will not be included twice under the same specified name. |
a687059c |
510 | .Ip "reset(EXPR)" 8 6 |
511 | .Ip "reset EXPR" 8 |
512 | .Ip "reset" 8 |
513 | Generally used in a |
514 | .I continue |
515 | block at the end of a loop to clear variables and reset ?? searches |
516 | so that they work again. |
517 | The expression is interpreted as a list of single characters (hyphens allowed |
518 | for ranges). |
519 | All variables and arrays beginning with one of those letters are reset to |
520 | their pristine state. |
521 | If the expression is omitted, one-match searches (?pattern?) are reset to |
522 | match again. |
523 | Only resets variables or searches in the current package. |
524 | Always returns 1. |
525 | Examples: |
526 | .nf |
527 | |
528 | .ne 3 |
529 | reset \'X\'; \h'|2i'# reset all X variables |
530 | reset \'a\-z\';\h'|2i'# reset lower case variables |
531 | reset; \h'|2i'# just reset ?? searches |
532 | |
533 | .fi |
534 | Note: resetting \*(L"A\-Z\*(R" is not recommended since you'll wipe out your ARGV and ENV |
535 | arrays. |
536 | .Sp |
537 | The use of reset on dbm associative arrays does not change the dbm file. |
538 | (It does, however, flush any entries cached by perl, which may be useful if |
539 | you are sharing the dbm file. |
540 | Then again, maybe not.) |
541 | .Ip "return LIST" 8 3 |
542 | Returns from a subroutine with the value specified. |
543 | (Note that a subroutine can automatically return |
544 | the value of the last expression evaluated. |
545 | That's the preferred method\*(--use of an explicit |
546 | .I return |
547 | is a bit slower.) |
548 | .Ip "reverse(LIST)" 8 4 |
549 | .Ip "reverse LIST" 8 |
550 | Returns an array value consisting of the elements of LIST in the opposite order. |
551 | .Ip "rewinddir(DIRHANDLE)" 8 5 |
552 | .Ip "rewinddir DIRHANDLE" 8 |
553 | Sets the current position to the beginning of the directory for the readdir() routine on DIRHANDLE. |
554 | .Ip "rindex(STR,SUBSTR)" 8 4 |
555 | Works just like index except that it |
556 | returns the position of the LAST occurrence of SUBSTR in STR. |
557 | .Ip "rmdir(FILENAME)" 8 4 |
558 | .Ip "rmdir FILENAME" 8 |
559 | Deletes the directory specified by FILENAME if it is empty. |
560 | If it succeeds it returns 1, otherwise it returns 0 and sets $! (errno). |
561 | If FILENAME is omitted, uses $_. |
562 | .Ip "s/PATTERN/REPLACEMENT/gieo" 8 3 |
563 | Searches a string for a pattern, and if found, replaces that pattern with the |
564 | replacement text and returns the number of substitutions made. |
565 | Otherwise it returns false (0). |
566 | The \*(L"g\*(R" is optional, and if present, indicates that all occurrences |
567 | of the pattern are to be replaced. |
568 | The \*(L"i\*(R" is also optional, and if present, indicates that matching |
569 | is to be done in a case-insensitive manner. |
570 | The \*(L"e\*(R" is likewise optional, and if present, indicates that |
571 | the replacement string is to be evaluated as an expression rather than just |
572 | as a double-quoted string. |
33b78306 |
573 | Any non-alphanumeric delimiter may replace the slashes; |
574 | if single quotes are used, no |
a687059c |
575 | interpretation is done on the replacement string (the e modifier overrides |
663a0e37 |
576 | this, however); if backquotes are used, the replacement string is a command |
577 | to execute whose output will be used as the actual replacement text. |
a687059c |
578 | If no string is specified via the =~ or !~ operator, |
579 | the $_ string is searched and modified. |
580 | (The string specified with =~ must be a scalar variable, an array element, |
581 | or an assignment to one of those, i.e. an lvalue.) |
582 | If the pattern contains a $ that looks like a variable rather than an |
583 | end-of-string test, the variable will be interpolated into the pattern at |
584 | run-time. |
585 | If you only want the pattern compiled once the first time the variable is |
586 | interpolated, add an \*(L"o\*(R" at the end. |
587 | See also the section on regular expressions. |
588 | Examples: |
589 | .nf |
590 | |
591 | s/\|\e\|bgreen\e\|b/mauve/g; # don't change wintergreen |
592 | |
593 | $path \|=~ \|s|\|/usr/bin|\|/usr/local/bin|; |
594 | |
595 | s/Login: $foo/Login: $bar/; # run-time pattern |
596 | |
597 | ($foo = $bar) =~ s/bar/foo/; |
598 | |
599 | $_ = \'abc123xyz\'; |
600 | s/\ed+/$&*2/e; # yields \*(L'abc246xyz\*(R' |
601 | s/\ed+/sprintf("%5d",$&)/e; # yields \*(L'abc 246xyz\*(R' |
602 | s/\ew/$& x 2/eg; # yields \*(L'aabbcc 224466xxyyzz\*(R' |
603 | |
604 | s/\|([^ \|]*\|) *\|([^ \|]*\|)\|/\|$2 $1/; # reverse 1st two fields |
605 | |
606 | .fi |
607 | (Note the use of $ instead of \|\e\| in the last example. See section |
608 | on regular expressions.) |
609 | .Ip "seek(FILEHANDLE,POSITION,WHENCE)" 8 3 |
610 | Randomly positions the file pointer for FILEHANDLE, just like the fseek() |
611 | call of stdio. |
612 | FILEHANDLE may be an expression whose value gives the name of the filehandle. |
613 | Returns 1 upon success, 0 otherwise. |
614 | .Ip "seekdir(DIRHANDLE,POS)" 8 3 |
615 | Sets the current position for the readdir() routine on DIRHANDLE. |
616 | POS must be a value returned by seekdir(). |
617 | Has the same caveats about possible directory compaction as the corresponding |
618 | system library routine. |
619 | .Ip "select(FILEHANDLE)" 8 3 |
620 | .Ip "select" 8 3 |
621 | Returns the currently selected filehandle. |
622 | Sets the current default filehandle for output, if FILEHANDLE is supplied. |
623 | This has two effects: first, a |
624 | .I write |
625 | or a |
626 | .I print |
627 | without a filehandle will default to this FILEHANDLE. |
628 | Second, references to variables related to output will refer to this output |
629 | channel. |
630 | For example, if you have to set the top of form format for more than |
631 | one output channel, you might do the following: |
632 | .nf |
633 | |
634 | .ne 4 |
635 | select(REPORT1); |
636 | $^ = \'report1_top\'; |
637 | select(REPORT2); |
638 | $^ = \'report2_top\'; |
639 | |
640 | .fi |
641 | FILEHANDLE may be an expression whose value gives the name of the actual filehandle. |
642 | Thus: |
643 | .nf |
644 | |
645 | $oldfh = select(STDERR); $| = 1; select($oldfh); |
646 | |
647 | .fi |
648 | .Ip "select(RBITS,WBITS,EBITS,TIMEOUT)" 8 3 |
649 | This calls the select system call with the bitmasks specified, which can |
650 | be constructed using fileno() and vec(), along these lines: |
651 | .nf |
652 | |
653 | $rin = $win = $ein = ''; |
654 | vec($rin,fileno(STDIN),1) = 1; |
655 | vec($win,fileno(STDOUT),1) = 1; |
656 | $ein = $rin | $win; |
657 | |
658 | .fi |
659 | If you want to select on many filehandles you might wish to write a subroutine: |
660 | .nf |
661 | |
662 | sub fhbits { |
663 | local(@fhlist) = split(' ',$_[0]); |
664 | local($bits); |
665 | for (@fhlist) { |
666 | vec($bits,fileno($_),1) = 1; |
667 | } |
668 | $bits; |
669 | } |
670 | $rin = &fhbits('STDIN TTY SOCK'); |
671 | |
672 | .fi |
673 | The usual idiom is: |
674 | .nf |
675 | |
676 | ($nfound,$timeleft) = |
677 | select($rout=$rin, $wout=$win, $eout=$ein, $timeout); |
678 | |
679 | or to block until something becomes ready: |
680 | |
ae986130 |
681 | .ie t \{\ |
a687059c |
682 | $nfound = select($rout=$rin, $wout=$win, $eout=$ein, undef); |
ae986130 |
683 | 'br\} |
684 | .el \{\ |
685 | $nfound = select($rout=$rin, $wout=$win, |
686 | $eout=$ein, undef); |
687 | 'br\} |
a687059c |
688 | |
689 | .fi |
690 | Any of the bitmasks can also be undef. |
691 | The timeout, if specified, is in seconds, which may be fractional. |
663a0e37 |
692 | NOTE: not all implementations are capable of returning the $timeleft. |
693 | If not, they always return $timeleft equal to the supplied $timeout. |
a687059c |
694 | .Ip "send(SOCKET,MSG,FLAGS,TO)" 8 4 |
695 | .Ip "send(SOCKET,MSG,FLAGS)" 8 |
696 | Sends a message on a socket. |
697 | Takes the same flags as the system call of the same name. |
698 | On unconnected sockets you must specify a destination to send TO. |
699 | Returns the number of characters sent, or the undefined value if |
700 | there is an error. |
33b78306 |
701 | .Ip "setpgrp(PID,PGRP)" 8 4 |
702 | Sets the current process group for the specified PID, 0 for the current |
703 | process. |
704 | Will produce a fatal error if used on a machine that doesn't implement |
705 | setpgrp(2). |
a687059c |
706 | .Ip "setpriority(WHICH,WHO,PRIORITY)" 8 4 |
707 | Sets the current priority for a process, a process group, or a user. |
708 | (See setpriority(2).) |
709 | Will produce a fatal error if used on a machine that doesn't implement |
710 | setpriority(2). |
711 | .Ip "setsockopt(SOCKET,LEVEL,OPTNAME,OPTVAL)" 8 3 |
712 | Sets the socket option requested. |
713 | Returns undefined if there is an error. |
714 | OPTVAL may be specified as undef if you don't want to pass an argument. |
715 | .Ip "shift(ARRAY)" 8 6 |
716 | .Ip "shift ARRAY" 8 |
717 | .Ip "shift" 8 |
718 | Shifts the first value of the array off and returns it, |
719 | shortening the array by 1 and moving everything down. |
720 | If there are no elements in the array, returns the undefined value. |
721 | If ARRAY is omitted, shifts the @ARGV array in the main program, and the @_ |
722 | array in subroutines. |
723 | See also unshift(), push() and pop(). |
724 | Shift() and unshift() do the same thing to the left end of an array that push() |
725 | and pop() do to the right end. |
726 | .Ip "shutdown(SOCKET,HOW)" 8 3 |
727 | Shuts down a socket connection in the manner indicated by HOW, which has |
728 | the same interpretation as in the system call of the same name. |
729 | .Ip "sin(EXPR)" 8 4 |
730 | .Ip "sin EXPR" 8 |
731 | Returns the sine of EXPR (expressed in radians). |
732 | If EXPR is omitted, returns sine of $_. |
733 | .Ip "sleep(EXPR)" 8 6 |
734 | .Ip "sleep EXPR" 8 |
735 | .Ip "sleep" 8 |
736 | Causes the script to sleep for EXPR seconds, or forever if no EXPR. |
737 | May be interrupted by sending the process a SIGALARM. |
738 | Returns the number of seconds actually slept. |
739 | .Ip "socket(SOCKET,DOMAIN,TYPE,PROTOCOL)" 8 3 |
740 | Opens a socket of the specified kind and attaches it to filehandle SOCKET. |
741 | DOMAIN, TYPE and PROTOCOL are specified the same as for the system call |
742 | of the same name. |
743 | You may need to run makelib on sys/socket.h to get the proper values handy |
744 | in a perl library file. |
745 | Return true if successful. |
746 | See the example in the section on Interprocess Communication. |
747 | .Ip "socketpair(SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL)" 8 3 |
748 | Creates an unnamed pair of sockets in the specified domain, of the specified |
749 | type. |
750 | DOMAIN, TYPE and PROTOCOL are specified the same as for the system call |
751 | of the same name. |
752 | If unimplemented, yields a fatal error. |
753 | Return true if successful. |
754 | .Ip "sort(SUBROUTINE LIST)" 8 9 |
755 | .Ip "sort(LIST)" 8 |
756 | .Ip "sort SUBROUTINE LIST" 8 |
757 | .Ip "sort LIST" 8 |
758 | Sorts the LIST and returns the sorted array value. |
759 | Nonexistent values of arrays are stripped out. |
760 | If SUBROUTINE is omitted, sorts in standard string comparison order. |
761 | If SUBROUTINE is specified, gives the name of a subroutine that returns |
762 | an integer less than, equal to, or greater than 0, |
763 | depending on how the elements of the array are to be ordered. |
764 | In the interests of efficiency the normal calling code for subroutines |
765 | is bypassed, with the following effects: the subroutine may not be a recursive |
766 | subroutine, and the two elements to be compared are passed into the subroutine |
767 | not via @_ but as $a and $b (see example below). |
768 | They are passed by reference so don't modify $a and $b. |
769 | SUBROUTINE may be a scalar variable name, in which case the value provides |
770 | the name of the subroutine to use. |
771 | Examples: |
772 | .nf |
773 | |
774 | .ne 4 |
775 | sub byage { |
776 | $age{$a} - $age{$b}; # presuming integers |
777 | } |
778 | @sortedclass = sort byage @class; |
779 | |
780 | .ne 9 |
781 | sub reverse { $a lt $b ? 1 : $a gt $b ? \-1 : 0; } |
782 | @harry = (\'dog\',\'cat\',\'x\',\'Cain\',\'Abel\'); |
783 | @george = (\'gone\',\'chased\',\'yz\',\'Punished\',\'Axed\'); |
784 | print sort @harry; |
785 | # prints AbelCaincatdogx |
786 | print sort reverse @harry; |
787 | # prints xdogcatCainAbel |
788 | print sort @george, \'to\', @harry; |
789 | # prints AbelAxedCainPunishedcatchaseddoggonetoxyz |
790 | |
791 | .fi |
79a0689e |
792 | .Ip "splice(ARRAY,OFFSET,LENGTH,LIST)" 8 8 |
793 | .Ip "splice(ARRAY,OFFSET,LENGTH)" 8 |
794 | .Ip "splice(ARRAY,OFFSET)" 8 |
795 | Removes the elements designated by OFFSET and LENGTH from an array, and |
796 | replaces them with the elements of LIST, if any. |
797 | Returns the elements removed from the array. |
798 | The array grows or shrinks as necessary. |
799 | If LENGTH is omitted, removes everything from OFFSET onward. |
800 | The following equivalencies hold (assuming $[ == 0): |
801 | .nf |
802 | |
803 | push(@a,$x,$y)\h'|3.5i'splice(@a,$#x+1,0,$x,$y) |
804 | pop(@a)\h'|3.5i'splice(@a,-1) |
805 | shift(@a)\h'|3.5i'splice(@a,0,1) |
806 | unshift(@a,$x,$y)\h'|3.5i'splice(@a,0,0,$x,$y) |
807 | $a[$x] = $y\h'|3.5i'splice(@a,$x,1,$y); |
808 | |
809 | Example, assuming array lengths are passed before arrays: |
810 | |
811 | sub aeq { # compare two array values |
812 | local(@a) = splice(@_,0,shift); |
813 | local(@b) = splice(@_,0,shift); |
814 | return 0 unless @a == @b; # same len? |
815 | while (@a) { |
816 | return 0 if pop(@a) ne pop(@b); |
817 | } |
818 | return 1; |
819 | } |
820 | if (&aeq($len,@foo[1..$len],0+@bar,@bar)) { ... } |
821 | |
822 | .fi |
a687059c |
823 | .Ip "split(/PATTERN/,EXPR,LIMIT)" 8 8 |
824 | .Ip "split(/PATTERN/,EXPR)" 8 8 |
825 | .Ip "split(/PATTERN/)" 8 |
826 | .Ip "split" 8 |
827 | Splits a string into an array of strings, and returns it. |
828 | (If not in an array context, returns the number of fields found and splits |
ac58e20f |
829 | into the @_ array. |
830 | (In an array context, you can force the split into @_ |
831 | by using ?? as the pattern delimiters, but it still returns the array value.)) |
a687059c |
832 | If EXPR is omitted, splits the $_ string. |
833 | If PATTERN is also omitted, splits on whitespace (/[\ \et\en]+/). |
834 | Anything matching PATTERN is taken to be a delimiter separating the fields. |
835 | (Note that the delimiter may be longer than one character.) |
836 | If LIMIT is specified, splits into no more than that many fields (though it |
837 | may split into fewer). |
838 | If LIMIT is unspecified, trailing null fields are stripped (which |
839 | potential users of pop() would do well to remember). |
33b78306 |
840 | A pattern matching the null string (not to be confused with a null pattern //, |
841 | which is just one member of the set of patterns matching a null string) |
a687059c |
842 | will split the value of EXPR into separate characters at each point it |
843 | matches that way. |
844 | For example: |
845 | .nf |
846 | |
847 | print join(\':\', split(/ */, \'hi there\')); |
848 | |
849 | .fi |
850 | produces the output \*(L'h:i:t:h:e:r:e\*(R'. |
ffed7fef |
851 | .Sp |
663a0e37 |
852 | The LIMIT parameter can be used to partially split a line |
a687059c |
853 | .nf |
854 | |
855 | ($login, $passwd, $remainder) = split(\|/\|:\|/\|, $_, 3); |
856 | |
857 | .fi |
663a0e37 |
858 | (When assigning to a list, if LIMIT is omitted, perl supplies a LIMIT one |
a687059c |
859 | larger than the number of variables in the list, to avoid unnecessary work. |
663a0e37 |
860 | For the list above LIMIT would have been 4 by default. |
a687059c |
861 | In time critical applications it behooves you not to split into |
862 | more fields than you really need.) |
863 | .Sp |
864 | If the PATTERN contains parentheses, additional array elements are created |
865 | from each matching substring in the delimiter. |
866 | .Sp |
867 | split(/([,-])/,"1-10,20"); |
868 | .Sp |
869 | produces the array value |
870 | .Sp |
871 | (1,'-',10,',',20) |
872 | .Sp |
873 | The pattern /PATTERN/ may be replaced with an expression to specify patterns |
874 | that vary at runtime. |
875 | (To do runtime compilation only once, use /$variable/o.) |
876 | As a special case, specifying a space (\'\ \') will split on white space |
877 | just as split with no arguments does, but leading white space does NOT |
878 | produce a null first field. |
879 | Thus, split(\'\ \') can be used to emulate |
880 | .IR awk 's |
881 | default behavior, whereas |
882 | split(/\ /) will give you as many null initial fields as there are |
883 | leading spaces. |
884 | .Sp |
885 | Example: |
886 | .nf |
887 | |
888 | .ne 5 |
889 | open(passwd, \'/etc/passwd\'); |
890 | while (<passwd>) { |
891 | .ie t \{\ |
892 | ($login, $passwd, $uid, $gid, $gcos, $home, $shell) = split(\|/\|:\|/\|); |
893 | 'br\} |
894 | .el \{\ |
895 | ($login, $passwd, $uid, $gid, $gcos, $home, $shell) |
896 | = split(\|/\|:\|/\|); |
897 | 'br\} |
898 | .\|.\|. |
899 | } |
900 | |
901 | .fi |
902 | (Note that $shell above will still have a newline on it. See chop().) |
903 | See also |
904 | .IR join . |
905 | .Ip "sprintf(FORMAT,LIST)" 8 4 |
906 | Returns a string formatted by the usual printf conventions. |
907 | The * character is not supported. |
908 | .Ip "sqrt(EXPR)" 8 4 |
909 | .Ip "sqrt EXPR" 8 |
910 | Return the square root of EXPR. |
911 | If EXPR is omitted, returns square root of $_. |
912 | .Ip "srand(EXPR)" 8 4 |
913 | .Ip "srand EXPR" 8 |
914 | Sets the random number seed for the |
915 | .I rand |
916 | operator. |
917 | If EXPR is omitted, does srand(time). |
ae986130 |
918 | .Ip "stat(FILEHANDLE)" 8 8 |
a687059c |
919 | .Ip "stat FILEHANDLE" 8 |
920 | .Ip "stat(EXPR)" 8 |
ae986130 |
921 | .Ip "stat SCALARVARIABLE" 8 |
a687059c |
922 | Returns a 13-element array giving the statistics for a file, either the file |
923 | opened via FILEHANDLE, or named by EXPR. |
924 | Typically used as follows: |
925 | .nf |
926 | |
927 | .ne 3 |
928 | ($dev,$ino,$mode,$nlink,$uid,$gid,$rdev,$size, |
929 | $atime,$mtime,$ctime,$blksize,$blocks) |
930 | = stat($filename); |
931 | |
932 | .fi |
933 | If stat is passed the special filehandle consisting of an underline, |
934 | no stat is done, but the current contents of the stat structure from |
935 | the last stat or filetest are returned. |
936 | Example: |
937 | .nf |
938 | |
939 | .ne 3 |
940 | if (-x $file && (($d) = stat(_)) && $d < 0) { |
941 | print "$file is executable NFS file\en"; |
942 | } |
943 | |
944 | .fi |
945 | .Ip "study(SCALAR)" 8 6 |
946 | .Ip "study SCALAR" 8 |
947 | .Ip "study" |
948 | Takes extra time to study SCALAR ($_ if unspecified) in anticipation of |
949 | doing many pattern matches on the string before it is next modified. |
950 | This may or may not save time, depending on the nature and number of patterns |
951 | you are searching on, and on the distribution of character frequencies in |
952 | the string to be searched\*(--you probably want to compare runtimes with and |
953 | without it to see which runs faster. |
954 | Those loops which scan for many short constant strings (including the constant |
955 | parts of more complex patterns) will benefit most. |
956 | You may have only one study active at a time\*(--if you study a different |
957 | scalar the first is \*(L"unstudied\*(R". |
958 | (The way study works is this: a linked list of every character in the string |
959 | to be searched is made, so we know, for example, where all the \*(L'k\*(R' characters |
960 | are. |
961 | From each search string, the rarest character is selected, based on some |
962 | static frequency tables constructed from some C programs and English text. |
963 | Only those places that contain this \*(L"rarest\*(R" character are examined.) |
964 | .Sp |
965 | For example, here is a loop which inserts index producing entries before any line |
966 | containing a certain pattern: |
967 | .nf |
968 | |
969 | .ne 8 |
970 | while (<>) { |
971 | study; |
972 | print ".IX foo\en" if /\ebfoo\eb/; |
973 | print ".IX bar\en" if /\ebbar\eb/; |
974 | print ".IX blurfl\en" if /\ebblurfl\eb/; |
975 | .\|.\|. |
976 | print; |
977 | } |
978 | |
979 | .fi |
980 | In searching for /\ebfoo\eb/, only those locations in $_ that contain \*(L'f\*(R' |
981 | will be looked at, because \*(L'f\*(R' is rarer than \*(L'o\*(R'. |
982 | In general, this is a big win except in pathological cases. |
983 | The only question is whether it saves you more time than it took to build |
984 | the linked list in the first place. |
985 | .Sp |
986 | Note that if you have to look for strings that you don't know till runtime, |
987 | you can build an entire loop as a string and eval that to avoid recompiling |
988 | all your patterns all the time. |
989 | Together with setting $/ to input entire files as one record, this can |
990 | be very fast, often faster than specialized programs like fgrep. |
991 | The following scans a list of files (@files) |
992 | for a list of words (@words), and prints out the names of those files that |
993 | contain a match: |
994 | .nf |
995 | |
996 | .ne 12 |
997 | $search = \'while (<>) { study;\'; |
998 | foreach $word (@words) { |
999 | $search .= "++\e$seen{\e$ARGV} if /\eb$word\eb/;\en"; |
1000 | } |
1001 | $search .= "}"; |
1002 | @ARGV = @files; |
1003 | $/ = "\e177"; # something that doesn't occur |
1004 | eval $search; # this screams |
1005 | $/ = "\en"; # put back to normal input delim |
1006 | foreach $file (sort keys(%seen)) { |
1007 | print $file, "\en"; |
1008 | } |
1009 | |
1010 | .fi |
1011 | .Ip "substr(EXPR,OFFSET,LEN)" 8 2 |
1012 | Extracts a substring out of EXPR and returns it. |
1013 | First character is at offset 0, or whatever you've set $[ to. |
1014 | If OFFSET is negative, starts that far from the end of the string. |
1015 | You can use the substr() function as an lvalue, in which case EXPR must |
1016 | be an lvalue. |
1017 | If you assign something shorter than LEN, the string will shrink, and |
ae986130 |
1018 | if you assign something longer than LEN, the string will grow to accommodate it. |
a687059c |
1019 | To keep the string the same length you may need to pad or chop your value using |
1020 | sprintf(). |
33b78306 |
1021 | .Ip "symlink(OLDFILE,NEWFILE)" 8 2 |
1022 | Creates a new filename symbolically linked to the old filename. |
1023 | Returns 1 for success, 0 otherwise. |
1024 | On systems that don't support symbolic links, produces a fatal error at |
1025 | run time. |
1026 | To check for that, use eval: |
1027 | .nf |
1028 | |
1029 | $symlink_exists = (eval \'symlink("","");\', $@ eq \'\'); |
1030 | |
1031 | .fi |
a687059c |
1032 | .Ip "syscall(LIST)" 8 6 |
1033 | .Ip "syscall LIST" 8 |
1034 | Calls the system call specified as the first element of the list, passing |
1035 | the remaining elements as arguments to the system call. |
1036 | If unimplemented, produces a fatal error. |
1037 | The arguments are interpreted as follows: if a given argument is numeric, |
1038 | the argument is passed as an int. |
1039 | If not, the pointer to the string value is passed. |
1040 | You are responsible to make sure a string is pre-extended long enough |
1041 | to receive any result that might be written into a string. |
1042 | If your integer arguments are not literals and have never been interpreted |
1043 | in a numeric context, you may need to add 0 to them to force them to look |
1044 | like numbers. |
1045 | .nf |
1046 | |
33b78306 |
1047 | require 'syscall.ph'; # may need to run makelib |
a687059c |
1048 | syscall(&SYS_write, fileno(STDOUT), "hi there\en", 9); |
1049 | |
1050 | .fi |
1051 | .Ip "system(LIST)" 8 6 |
1052 | .Ip "system LIST" 8 |
1053 | Does exactly the same thing as \*(L"exec LIST\*(R" except that a fork |
1054 | is done first, and the parent process waits for the child process to complete. |
1055 | Note that argument processing varies depending on the number of arguments. |
1056 | The return value is the exit status of the program as returned by the wait() |
1057 | call. |
1058 | To get the actual exit value divide by 256. |
1059 | See also |
1060 | .IR exec . |
a687059c |
1061 | .Ip "tell(FILEHANDLE)" 8 6 |
1062 | .Ip "tell FILEHANDLE" 8 6 |
1063 | .Ip "tell" 8 |
1064 | Returns the current file position for FILEHANDLE. |
1065 | FILEHANDLE may be an expression whose value gives the name of the actual |
1066 | filehandle. |
1067 | If FILEHANDLE is omitted, assumes the file last read. |
1068 | .Ip "telldir(DIRHANDLE)" 8 5 |
1069 | .Ip "telldir DIRHANDLE" 8 |
1070 | Returns the current position of the readdir() routines on DIRHANDLE. |
1071 | Value may be given to seekdir() to access a particular location in |
1072 | a directory. |
1073 | Has the same caveats about possible directory compaction as the corresponding |
1074 | system library routine. |
1075 | .Ip "time" 8 4 |
1076 | Returns the number of non-leap seconds since January 1, 1970, UTC. |
1077 | Suitable for feeding to gmtime() and localtime(). |
1078 | .Ip "times" 8 4 |
1079 | Returns a four-element array giving the user and system times, in seconds, for this |
1080 | process and the children of this process. |
1081 | .Sp |
1082 | ($user,$system,$cuser,$csystem) = times; |
1083 | .Sp |
1084 | .Ip "tr/SEARCHLIST/REPLACEMENTLIST/" 8 5 |
1085 | .Ip "y/SEARCHLIST/REPLACEMENTLIST/" 8 |
1086 | Translates all occurrences of the characters found in the search list with |
1087 | the corresponding character in the replacement list. |
1088 | It returns the number of characters replaced. |
1089 | If no string is specified via the =~ or !~ operator, |
1090 | the $_ string is translated. |
1091 | (The string specified with =~ must be a scalar variable, an array element, |
1092 | or an assignment to one of those, i.e. an lvalue.) |
1093 | For |
1094 | .I sed |
1095 | devotees, |
1096 | .I y |
1097 | is provided as a synonym for |
1098 | .IR tr . |
1099 | Examples: |
1100 | .nf |
1101 | |
1102 | $ARGV[1] \|=~ \|y/A\-Z/a\-z/; \h'|3i'# canonicalize to lower case |
1103 | |
1104 | $cnt = tr/*/*/; \h'|3i'# count the stars in $_ |
1105 | |
1106 | ($HOST = $host) =~ tr/a\-z/A\-Z/; |
1107 | |
1108 | y/\e001\-@[\-_{\-\e177/ /; \h'|3i'# change non-alphas to space |
1109 | |
1110 | .fi |
33b78306 |
1111 | .Ip "truncate(FILEHANDLE,LENGTH)" 8 4 |
1112 | .Ip "truncate(EXPR,LENGTH)" 8 |
1113 | Truncates the file opened on FILEHANDLE, or named by EXPR, to the specified |
1114 | length. |
1115 | Produces a fatal error if truncate isn't implemented on your system. |
a687059c |
1116 | .Ip "umask(EXPR)" 8 4 |
1117 | .Ip "umask EXPR" 8 |
ae986130 |
1118 | .Ip "umask" 8 |
a687059c |
1119 | Sets the umask for the process and returns the old one. |
1120 | If EXPR is omitted, merely returns current umask. |
1121 | .Ip "undef(EXPR)" 8 6 |
1122 | .Ip "undef EXPR" 8 |
1123 | .Ip "undef" 8 |
1124 | Undefines the value of EXPR, which must be an lvalue. |
1125 | Use only on a scalar value, an entire array, or a subroutine name (using &). |
1126 | (Undef will probably not do what you expect on most predefined variables or |
1127 | dbm array values.) |
1128 | Always returns the undefined value. |
1129 | You can omit the EXPR, in which case nothing is undefined, but you still |
1130 | get an undefined value that you could, for instance, return from a subroutine. |
1131 | Examples: |
1132 | .nf |
1133 | |
1134 | .ne 6 |
1135 | undef $foo; |
1136 | undef $bar{'blurfl'}; |
1137 | undef @ary; |
1138 | undef %assoc; |
1139 | undef &mysub; |
1140 | return (wantarray ? () : undef) if $they_blew_it; |
1141 | |
1142 | .fi |
1143 | .Ip "unlink(LIST)" 8 4 |
1144 | .Ip "unlink LIST" 8 |
1145 | Deletes a list of files. |
1146 | Returns the number of files successfully deleted. |
1147 | .nf |
1148 | |
1149 | .ne 2 |
1150 | $cnt = unlink \'a\', \'b\', \'c\'; |
1151 | unlink @goners; |
1152 | unlink <*.bak>; |
1153 | |
1154 | .fi |
1155 | Note: unlink will not delete directories unless you are superuser and the |
1156 | .B \-U |
1157 | flag is supplied to |
1158 | .IR perl . |
1159 | Even if these conditions are met, be warned that unlinking a directory |
1160 | can inflict damage on your filesystem. |
1161 | Use rmdir instead. |
1162 | .Ip "unpack(TEMPLATE,EXPR)" 8 4 |
1163 | Unpack does the reverse of pack: it takes a string representing |
1164 | a structure and expands it out into an array value, returning the array |
1165 | value. |
33b78306 |
1166 | (In a scalar context, it merely returns the first value produced.) |
a687059c |
1167 | The TEMPLATE has the same format as in the pack function. |
1168 | Here's a subroutine that does substring: |
1169 | .nf |
1170 | |
1171 | .ne 4 |
1172 | sub substr { |
1173 | local($what,$where,$howmuch) = @_; |
1174 | unpack("x$where a$howmuch", $what); |
1175 | } |
1176 | |
1177 | .ne 3 |
1178 | and then there's |
1179 | |
1180 | sub ord { unpack("c",$_[0]); } |
1181 | |
1182 | .fi |
33b78306 |
1183 | In addition, you may prefix a field with a %<number> to indicate that |
1184 | you want a <number>-bit checksum of the items instead of the items themselves. |
1185 | Default is a 16-bit checksum. |
1186 | For example, the following computes the same number as the System V sum program: |
1187 | .nf |
1188 | |
1189 | .ne 4 |
1190 | while (<>) { |
1191 | $checksum += unpack("%16C*", $_); |
1192 | } |
1193 | $checksum %= 65536; |
1194 | |
1195 | .fi |
a687059c |
1196 | .Ip "unshift(ARRAY,LIST)" 8 4 |
1197 | Does the opposite of a |
1198 | .IR shift . |
1199 | Or the opposite of a |
1200 | .IR push , |
1201 | depending on how you look at it. |
1202 | Prepends list to the front of the array, and returns the number of elements |
1203 | in the new array. |
1204 | .nf |
1205 | |
1206 | unshift(ARGV, \'\-e\') unless $ARGV[0] =~ /^\-/; |
1207 | |
1208 | .fi |
1209 | .Ip "utime(LIST)" 8 2 |
1210 | .Ip "utime LIST" 8 2 |
1211 | Changes the access and modification times on each file of a list of files. |
1212 | The first two elements of the list must be the NUMERICAL access and |
1213 | modification times, in that order. |
1214 | Returns the number of files successfully changed. |
1215 | The inode modification time of each file is set to the current time. |
1216 | Example of a \*(L"touch\*(R" command: |
1217 | .nf |
1218 | |
1219 | .ne 3 |
1220 | #!/usr/bin/perl |
1221 | $now = time; |
1222 | utime $now, $now, @ARGV; |
1223 | |
1224 | .fi |
1225 | .Ip "values(ASSOC_ARRAY)" 8 6 |
1226 | .Ip "values ASSOC_ARRAY" 8 |
1227 | Returns a normal array consisting of all the values of the named associative |
1228 | array. |
1229 | The values are returned in an apparently random order, but it is the same order |
1230 | as either the keys() or each() function would produce on the same array. |
1231 | See also keys() and each(). |
1232 | .Ip "vec(EXPR,OFFSET,BITS)" 8 2 |
1233 | Treats a string as a vector of unsigned integers, and returns the value |
1234 | of the bitfield specified. |
1235 | May also be assigned to. |
1236 | BITS must be a power of two from 1 to 32. |
1237 | .Sp |
1238 | Vectors created with vec() can also be manipulated with the logical operators |
1239 | |, & and ^, |
1240 | which will assume a bit vector operation is desired when both operands are |
1241 | strings. |
1242 | This interpretation is not enabled unless there is at least one vec() in |
1243 | your program, to protect older programs. |
1244 | .Ip "wait" 8 6 |
1245 | Waits for a child process to terminate and returns the pid of the deceased |
ae986130 |
1246 | process, or -1 if there are no child processes. |
a687059c |
1247 | The status is returned in $?. |
ae986130 |
1248 | If you expected a child and didn't find it, you probably had a call to |
1249 | system, a close on a pipe, or backticks between the fork and the wait. |
1250 | These constructs also do a wait and may have harvested your child process. |
a687059c |
1251 | .Ip "wantarray" 8 4 |
1252 | Returns true if the context of the currently executing subroutine |
1253 | is looking for an array value. |
1254 | Returns false if the context is looking for a scalar. |
1255 | .nf |
1256 | |
1257 | return wantarray ? () : undef; |
1258 | |
1259 | .fi |
1260 | .Ip "warn(LIST)" 8 4 |
1261 | .Ip "warn LIST" 8 |
1262 | Produces a message on STDERR just like \*(L"die\*(R", but doesn't exit. |
1263 | .Ip "write(FILEHANDLE)" 8 6 |
1264 | .Ip "write(EXPR)" 8 |
ae986130 |
1265 | .Ip "write" 8 |
a687059c |
1266 | Writes a formatted record (possibly multi-line) to the specified file, |
1267 | using the format associated with that file. |
1268 | By default the format for a file is the one having the same name is the |
1269 | filehandle, but the format for the current output channel (see |
1270 | .IR select ) |
1271 | may be set explicitly |
1272 | by assigning the name of the format to the $~ variable. |
1273 | .Sp |
1274 | Top of form processing is handled automatically: |
1275 | if there is insufficient room on the current page for the formatted |
ac58e20f |
1276 | record, the page is advanced by writing a form feed, |
1277 | a special top-of-page format is used |
a687059c |
1278 | to format the new page header, and then the record is written. |
1279 | By default the top-of-page format is \*(L"top\*(R", but it |
1280 | may be set to the |
1281 | format of your choice by assigning the name to the $^ variable. |
ac58e20f |
1282 | The number of lines remaining on the current page is in variable $-, which |
1283 | can be set to 0 to force a new page. |
a687059c |
1284 | .Sp |
1285 | If FILEHANDLE is unspecified, output goes to the current default output channel, |
1286 | which starts out as |
1287 | .I STDOUT |
1288 | but may be changed by the |
1289 | .I select |
1290 | operator. |
1291 | If the FILEHANDLE is an EXPR, then the expression is evaluated and the |
1292 | resulting string is used to look up the name of the FILEHANDLE at run time. |
1293 | For more on formats, see the section on formats later on. |
1294 | .Sp |
1295 | Note that write is NOT the opposite of read. |