| 1 | ''' Beginning of part 3 |
| 2 | ''' $Header: perl_man.3,v 3.0.1.11 90/11/10 01:48:21 lwall Locked $ |
| 3 | ''' |
| 4 | ''' $Log: perl.man.3,v $ |
| 5 | ''' Revision 3.0.1.11 90/11/10 01:48:21 lwall |
| 6 | ''' patch38: random cleanup |
| 7 | ''' patch38: documented tr///cds |
| 8 | ''' |
| 9 | ''' Revision 3.0.1.10 90/10/20 02:15:17 lwall |
| 10 | ''' patch37: patch37: fixed various typos in man page |
| 11 | ''' |
| 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 | ''' |
| 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 | ''' |
| 29 | ''' Revision 3.0.1.6 90/03/27 16:17:56 lwall |
| 30 | ''' patch16: MSDOS support |
| 31 | ''' |
| 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 | ''' |
| 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 | ''' |
| 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 | ''' |
| 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 | ''' |
| 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 | ''' |
| 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 | |
| 122 | .ie t \{\ |
| 123 | open(LOG, \'>>/usr/spool/news/twitlog\'\|); # (log is reserved) |
| 124 | 'br\} |
| 125 | .el \{\ |
| 126 | open(LOG, \'>>/usr/spool/news/twitlog\'\|); |
| 127 | # (log is reserved) |
| 128 | 'br\} |
| 129 | |
| 130 | .ie t \{\ |
| 131 | open(article, "caesar <$article |"\|); # decrypt article |
| 132 | 'br\} |
| 133 | .el \{\ |
| 134 | open(article, "caesar <$article |"\|); |
| 135 | # decrypt article |
| 136 | 'br\} |
| 137 | |
| 138 | .ie t \{\ |
| 139 | open(extract, "|sort >/tmp/Tmp$$"\|); # $$ is our process# |
| 140 | 'br\} |
| 141 | .el \{\ |
| 142 | open(extract, "|sort >/tmp/Tmp$$"\|); |
| 143 | # $$ is our process# |
| 144 | 'br\} |
| 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 | } |
| 160 | .ie t \{\ |
| 161 | while (<$input>) { # note the use of indirection |
| 162 | 'br\} |
| 163 | .el \{\ |
| 164 | while (<$input>) { # note use of indirection |
| 165 | 'br\} |
| 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. |
| 179 | You may use & after >, >>, <, +>, +>> and +<. |
| 180 | The mode you specify should match the mode of the original filehandle. |
| 181 | Here is a script that saves, redirects, and restores |
| 182 | .I STDOUT |
| 183 | and |
| 184 | .IR STDERR : |
| 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. |
| 229 | The following pairs are more or less equivalent: |
| 230 | .nf |
| 231 | |
| 232 | .ne 5 |
| 233 | open(FOO, "|tr \'[a\-z]\' \'[A\-Z]\'"); |
| 234 | open(FOO, "|\-") || exec \'tr\', \'[a\-z]\', \'[A\-Z]\'; |
| 235 | |
| 236 | open(FOO, "cat \-n '$file'|"); |
| 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 $?. |
| 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 |
| 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 |
| 265 | Returns the numeric ascii value of the first character of EXPR. |
| 266 | If EXPR is omitted, uses $_. |
| 267 | ''' Comments on f & d by gnb@melba.bby.oz.au 22/11/89 |
| 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. |
| 277 | c A signed char value. |
| 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. |
| 287 | f A single-precision float in the native format. |
| 288 | d A double-precision float in the native format. |
| 289 | p A pointer to a string. |
| 290 | x A null byte. |
| 291 | X Back up a byte. |
| 292 | @ Null fill to absolute position. |
| 293 | u A uuencoded string. |
| 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. |
| 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, |
| 303 | padding with nulls or spaces as necessary. |
| 304 | (When unpacking, "A" strips trailing spaces and nulls, but "a" does not.) |
| 305 | Real numbers (floats and doubles) are in the native machine format |
| 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 |
| 315 | double -> float -> double will lose precision (i.e. unpack("f", |
| 316 | pack("f", $foo)) will not in general equal $foo). |
| 317 | .br |
| 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 | |
| 342 | $foo = pack("i9pl", gmtime); |
| 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. |
| 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.] |
| 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. |
| 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.) |
| 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. |
| 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. |
| 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 |
| 389 | arguments to the print\*(--interpose a + or put parens around all the arguments. |
| 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. |
| 414 | Any non-alphanumeric delimiter can be used in place of /, including newline. |
| 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(). |
| 436 | .Ip "read(FILEHANDLE,SCALAR,LENGTH,OFFSET)" 8 5 |
| 437 | .Ip "read(FILEHANDLE,SCALAR,LENGTH)" 8 5 |
| 438 | Attempts to read LENGTH bytes of data into variable SCALAR from the specified |
| 439 | FILEHANDLE. |
| 440 | Returns the number of bytes actually read, or undef if there was an error. |
| 441 | SCALAR will be grown or shrunk to the length actually read. |
| 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. |
| 446 | .Ip "readdir(DIRHANDLE)" 8 3 |
| 447 | .Ip "readdir DIRHANDLE" 8 |
| 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. |
| 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. |
| 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 |
| 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. |
| 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. |
| 578 | .Ip "rindex(STR,SUBSTR,POSITION)" 8 6 |
| 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. |
| 582 | If POSITION is specified, returns the last occurrence at or before that |
| 583 | position. |
| 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. |
| 600 | Any non-alphanumeric delimiter may replace the slashes; |
| 601 | if single quotes are used, no |
| 602 | interpretation is done on the replacement string (the e modifier overrides |
| 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. |
| 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.) |
| 636 | .Ip "scalar(EXPR)" 8 3 |
| 637 | Forces EXPR to be interpreted in a scalar context and returns the value |
| 638 | of EXPR. |
| 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. |
| 646 | POS must be a value returned by telldir(). |
| 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 | |
| 711 | .ie t \{\ |
| 712 | $nfound = select($rout=$rin, $wout=$win, $eout=$ein, undef); |
| 713 | 'br\} |
| 714 | .el \{\ |
| 715 | $nfound = select($rout=$rin, $wout=$win, |
| 716 | $eout=$ein, undef); |
| 717 | 'br\} |
| 718 | |
| 719 | .fi |
| 720 | Any of the bitmasks can also be undef. |
| 721 | The timeout, if specified, is in seconds, which may be fractional. |
| 722 | NOTE: not all implementations are capable of returning the $timeleft. |
| 723 | If not, they always return $timeleft equal to the supplied $timeout. |
| 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 |
| 737 | \&'pack("sss", $semnum, $semop, $semflag)'. The number of semaphore |
| 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); |
| 744 | die "Semaphore trouble: $!\en" unless semop($semid, $semop); |
| 745 | |
| 746 | .fi |
| 747 | To signal the semaphore, replace "-1" with "1". |
| 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. |
| 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). |
| 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. |
| 777 | (This is determined lexically.) |
| 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. |
| 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. |
| 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. |
| 815 | You may need to run h2ph on sys/socket.h to get the proper values handy |
| 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 |
| 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 | |
| 875 | push(@a,$x,$y)\h'|3.5i'splice(@a,$#a+1,0,$x,$y) |
| 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 |
| 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 |
| 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.)) |
| 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). |
| 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) |
| 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'. |
| 923 | .Sp |
| 924 | The LIMIT parameter can be used to partially split a line |
| 925 | .nf |
| 926 | |
| 927 | ($login, $passwd, $remainder) = split(\|/\|:\|/\|, $_, 3); |
| 928 | |
| 929 | .fi |
| 930 | (When assigning to a list, if LIMIT is omitted, perl supplies a LIMIT one |
| 931 | larger than the number of variables in the list, to avoid unnecessary work. |
| 932 | For the list above LIMIT would have been 4 by default. |
| 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). |
| 990 | .Ip "stat(FILEHANDLE)" 8 8 |
| 991 | .Ip "stat FILEHANDLE" 8 |
| 992 | .Ip "stat(EXPR)" 8 |
| 993 | .Ip "stat SCALARVARIABLE" 8 |
| 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 |
| 1084 | .Ip "substr(EXPR,OFFSET)" 8 2 |
| 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. |
| 1088 | If LEN is omitted, returns everything to the end of the string. |
| 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 |
| 1092 | if you assign something longer than LEN, the string will grow to accommodate it. |
| 1093 | To keep the string the same length you may need to pad or chop your value using |
| 1094 | sprintf(). |
| 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 |
| 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 | |
| 1121 | require 'syscall.ph'; # may need to run h2ph |
| 1122 | syscall(&SYS_write, fileno(STDOUT), "hi there\en", 9); |
| 1123 | |
| 1124 | .fi |
| 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. |
| 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 . |
| 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. |
| 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 |
| 1169 | Returns the number of non-leap seconds since 00:00:00 UTC, January 1, 1970. |
| 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 |
| 1177 | .Ip "tr/SEARCHLIST/REPLACEMENTLIST/cds" 8 5 |
| 1178 | .Ip "y/SEARCHLIST/REPLACEMENTLIST/cds" 8 |
| 1179 | Translates all occurrences of the characters found in the search list with |
| 1180 | the corresponding character in the replacement list. |
| 1181 | It returns the number of characters replaced or deleted. |
| 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 . |
| 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 |
| 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 | |
| 1217 | $cnt = tr/0\-9//; \h'|3i'# count the digits in $_ |
| 1218 | |
| 1219 | tr/a\-zA\-Z//s; \h'|3i'# bookkeeper \-> bokeper |
| 1220 | |
| 1221 | ($HOST = $host) =~ tr/a\-z/A\-Z/; |
| 1222 | |
| 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 |
| 1226 | |
| 1227 | .fi |
| 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. |
| 1233 | .Ip "umask(EXPR)" 8 4 |
| 1234 | .Ip "umask EXPR" 8 |
| 1235 | .Ip "umask" 8 |
| 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. |
| 1283 | (In a scalar context, it merely returns the first value produced.) |
| 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 |
| 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 |
| 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 |
| 1363 | process, or -1 if there are no child processes. |
| 1364 | The status is returned in $?. |
| 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.) |
| 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 |
| 1401 | .Ip "write" 8 |
| 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 |
| 1412 | record, the page is advanced by writing a form feed, |
| 1413 | a special top-of-page format is used |
| 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. |
| 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. |
| 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. |