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