perl.man.2

   1 ''' Beginning of part 2
   2 ''' $Header: perl.man.2,v 3.0.1.2 89/11/17 15:30:16 lwall Locked $
   3 '''
   4 ''' $Log:       perl.man.2,v $
   5 ''' Revision 3.0.1.2  89/11/17  15:30:16  lwall
   6 ''' patch5: fixed some manual typos and indent problems
   7 '''
   8 ''' Revision 3.0.1.1  89/11/11  04:43:10  lwall
   9 ''' patch2: made some line breaks depend on troff vs. nroff
  10 ''' patch2: example of unshift had args backwards
  11 '''
  12 ''' Revision 3.0  89/10/18  15:21:37  lwall
  13 ''' 3.0 baseline
  14 '''
  15 '''
  16 .PP
  17 Along with the literals and variables mentioned earlier,
  18 the operations in the following section can serve as terms in an expression.
  19 Some of these operations take a LIST as an argument.
  20 Such a list can consist of any combination of scalar arguments or array values;
  21 the array values will be included in the list as if each individual element were
  22 interpolated at that point in the list, forming a longer single-dimensional
  23 array value.
  24 Elements of the LIST should be separated by commas.
  25 If an operation is listed both with and without parentheses around its
  26 arguments, it means you can either use it as a unary operator or
  27 as a function call.
  28 To use it as a function call, the next token on the same line must
  29 be a left parenthesis.
  30 (There may be intervening white space.)
  31 Such a function then has highest precedence, as you would expect from
  32 a function.
  33 If any token other than a left parenthesis follows, then it is a
  34 unary operator, with a precedence depending only on whether it is a LIST
  35 operator or not.
  36 LIST operators have lowest precedence.
  37 All other unary operators have a precedence greater than relational operators
  38 but less than arithmetic operators.
  39 See the section on Precedence.
  40 .Ip "/PATTERN/" 8 4
  41 See m/PATTERN/.
  42 .Ip "?PATTERN?" 8 4
  43 This is just like the /pattern/ search, except that it matches only once between
  44 calls to the
  45 .I reset
  46 operator.
  47 This is a useful optimization when you only want to see the first occurrence of
  48 something in each file of a set of files, for instance.
  49 Only ?? patterns local to the current package are reset.
  50 .Ip "accept(NEWSOCKET,GENERICSOCKET)" 8 2
  51 Does the same thing that the accept system call does.
  52 Returns true if it succeeded, false otherwise.
  53 See example in section on Interprocess Communication.
  54 .Ip "atan2(X,Y)" 8 2
  55 Returns the arctangent of X/Y in the range
  56 .if t \-\(*p to \(*p.
  57 .if n \-PI to PI.
  58 .Ip "bind(SOCKET,NAME)" 8 2
  59 Does the same thing that the bind system call does.
  60 Returns true if it succeeded, false otherwise.
  61 NAME should be a packed address of the proper type for the socket.
  62 See example in section on Interprocess Communication.
  63 .Ip "chdir(EXPR)" 8 2
  64 .Ip "chdir EXPR" 8 2
  65 Changes the working directory to EXPR, if possible.
  66 If EXPR is omitted, changes to home directory.
  67 Returns 1 upon success, 0 otherwise.
  68 See example under
  69 .IR die .
  70 .Ip "chmod(LIST)" 8 2
  71 .Ip "chmod LIST" 8 2
  72 Changes the permissions of a list of files.
  73 The first element of the list must be the numerical mode.
  74 Returns the number of files successfully changed.
  75 .nf
  76
  77 .ne 2
  78         $cnt = chmod 0755, \'foo\', \'bar\';
  79         chmod 0755, @executables;
  80
  81 .fi
  82 .Ip "chop(LIST)" 8 7
  83 .Ip "chop(VARIABLE)" 8
  84 .Ip "chop VARIABLE" 8
  85 .Ip "chop" 8
  86 Chops off the last character of a string and returns the character chopped.
  87 It's used primarily to remove the newline from the end of an input record,
  88 but is much more efficient than s/\en// because it neither scans nor copies
  89 the string.
  90 If VARIABLE is omitted, chops $_.
  91 Example:
  92 .nf
  93
  94 .ne 5
  95         while (<>) {
  96                 chop;   # avoid \en on last field
  97                 @array = split(/:/);
  98                 .\|.\|.
  99         }
 100
 101 .fi
 102 You can actually chop anything that's an lvalue, including an assignment:
 103 .nf
 104
 105         chop($cwd = \`pwd\`);
 106         chop($answer = <STDIN>);
 107
 108 .fi
 109 If you chop a list, each element is chopped.
 110 Only the value of the last chop is returned.
 111 .Ip "chown(LIST)" 8 2
 112 .Ip "chown LIST" 8 2
 113 Changes the owner (and group) of a list of files.
 114 The first two elements of the list must be the NUMERICAL uid and gid,
 115 in that order.
 116 Returns the number of files successfully changed.
 117 .nf
 118
 119 .ne 2
 120         $cnt = chown $uid, $gid, \'foo\', \'bar\';
 121         chown $uid, $gid, @filenames;
 122
 123 .fi
 124 .ne 23
 125 Here's an example of looking up non-numeric uids:
 126 .nf
 127
 128         print "User: ";
 129         $user = <STDIN>;
 130         chop($user);
 131         print "Files: "
 132         $pattern = <STDIN>;
 133         chop($pattern);
 134 .ie t \{\
 135         open(pass, \'/etc/passwd\') || die "Can't open passwd: $!\en";
 136 'br\}
 137 .el \{\
 138         open(pass, \'/etc/passwd\')
 139                 || die "Can't open passwd: $!\en";
 140 'br\}
 141         while (<pass>) {
 142                 ($login,$pass,$uid,$gid) = split(/:/);
 143                 $uid{$login} = $uid;
 144                 $gid{$login} = $gid;
 145         }
 146         @ary = <${pattern}>;    # get filenames
 147         if ($uid{$user} eq \'\') {
 148                 die "$user not in passwd file";
 149         }
 150         else {
 151                 chown $uid{$user}, $gid{$user}, @ary;
 152         }
 153
 154 .fi
 155 .Ip "chroot(FILENAME)" 8 5
 156 .Ip "chroot FILENAME" 8
 157 Does the same as the system call of that name.
 158 If you don't know what it does, don't worry about it.
 159 If FILENAME is omitted, does chroot to $_.
 160 .Ip "close(FILEHANDLE)" 8 5
 161 .Ip "close FILEHANDLE" 8
 162 Closes the file or pipe associated with the file handle.
 163 You don't have to close FILEHANDLE if you are immediately going to
 164 do another open on it, since open will close it for you.
 165 (See
 166 .IR open .)
 167 However, an explicit close on an input file resets the line counter ($.), while
 168 the implicit close done by
 169 .I open
 170 does not.
 171 Also, closing a pipe will wait for the process executing on the pipe to complete,
 172 in case you want to look at the output of the pipe afterwards.
 173 Closing a pipe explicitly also puts the status value of the command into $?.
 174 Example:
 175 .nf
 176
 177 .ne 4
 178         open(OUTPUT, \'|sort >foo\');   # pipe to sort
 179         .\|.\|. # print stuff to output
 180         close OUTPUT;           # wait for sort to finish
 181         open(INPUT, \'foo\');   # get sort's results
 182
 183 .fi
 184 FILEHANDLE may be an expression whose value gives the real filehandle name.
 185 .Ip "closedir(DIRHANDLE)" 8 5
 186 .Ip "closedir DIRHANDLE" 8
 187 Closes a directory opened by opendir().
 188 .Ip "connect(SOCKET,NAME)" 8 2
 189 Does the same thing that the connect system call does.
 190 Returns true if it succeeded, false otherwise.
 191 NAME should be a package address of the proper type for the socket.
 192 See example in section on Interprocess Communication.
 193 .Ip "cos(EXPR)" 8 6
 194 .Ip "cos EXPR" 8 6
 195 Returns the cosine of EXPR (expressed in radians).
 196 If EXPR is omitted takes cosine of $_.
 197 .Ip "crypt(PLAINTEXT,SALT)" 8 6
 198 Encrypts a string exactly like the crypt() function in the C library.
 199 Useful for checking the password file for lousy passwords.
 200 Only the guys wearing white hats should do this.
 201 .Ip "dbmclose(ASSOC_ARRAY)" 8 6
 202 .Ip "dbmclose ASSOC_ARRAY" 8
 203 Breaks the binding between a dbm file and an associative array.
 204 The values remaining in the associative array are meaningless unless
 205 you happen to want to know what was in the cache for the dbm file.
 206 This function is only useful if you have ndbm.
 207 .Ip "dbmopen(ASSOC,DBNAME,MODE)" 8 6
 208 This binds a dbm or ndbm file to an associative array.
 209 ASSOC is the name of the associative array.
 210 (Unlike normal open, the first argument is NOT a filehandle, even though
 211 it looks like one).
 212 DBNAME is the name of the database (without the .dir or .pag extension).
 213 If the database does not exist, it is created with protection specified
 214 by MODE (as modified by the umask).
 215 If your system only supports the older dbm functions, you may only have one
 216 dbmopen in your program.
 217 If your system has neither dbm nor ndbm, calling dbmopen produces a fatal
 218 error.
 219 .Sp
 220 Values assigned to the associative array prior to the dbmopen are lost.
 221 A certain number of values from the dbm file are cached in memory.
 222 By default this number is 64, but you can increase it by preallocating
 223 that number of garbage entries in the associative array before the dbmopen.
 224 You can flush the cache if necessary with the reset command.
 225 .Sp
 226 If you don't have write access to the dbm file, you can only read
 227 associative array variables, not set them.
 228 If you want to test whether you can write, either use file tests or
 229 try setting a dummy array entry inside an eval, which will trap the error.
 230 .Sp
 231 Note that functions such as keys() and values() may return huge array values
 232 when used on large dbm files.
 233 You may prefer to use the each() function to iterate over large dbm files.
 234 Example:
 235 .nf
 236
 237 .ne 6
 238         # print out history file offsets
 239         dbmopen(HIST,'/usr/lib/news/history',0666);
 240         while (($key,$val) = each %HIST) {
 241                 print $key, ' = ', unpack('L',$val), "\en";
 242         }
 243         dbmclose(HIST);
 244
 245 .fi
 246 .Ip "defined(EXPR)" 8 6
 247 .Ip "defined EXPR" 8
 248 Returns a boolean value saying whether the lvalue EXPR has a real value
 249 or not.
 250 Many operations return the undefined value under exceptional conditions,
 251 such as end of file, uninitialized variable, system error and such.
 252 This function allows you to distinguish between an undefined null string
 253 and a defined null string with operations that might return a real null
 254 string, in particular referencing elements of an array.
 255 You may also check to see if arrays or subroutines exist.
 256 Use on predefined variables is not guaranteed to produce intuitive results.
 257 Examples:
 258 .nf
 259
 260 .ne 7
 261         print if defined $switch{'D'};
 262         print "$val\en" while defined($val = pop(@ary));
 263         die "Can't readlink $sym: $!"
 264                 unless defined($value = readlink $sym);
 265         eval '@foo = ()' if defined(@foo);
 266         die "No XYZ package defined" unless defined %_XYZ;
 267         sub foo { defined &bar ? &bar(@_) : die "No bar"; }
 268
 269 .fi
 270 See also undef.
 271 .Ip "delete $ASSOC{KEY}" 8 6
 272 Deletes the specified value from the specified associative array.
 273 Returns the deleted value, or the undefined value if nothing was deleted.
 274 Deleting from $ENV{} modifies the environment.
 275 Deleting from an array bound to a dbm file deletes the entry from the dbm
 276 file.
 277 .Sp
 278 The following deletes all the values of an associative array:
 279 .nf
 280
 281 .ne 3
 282         foreach $key (keys %ARRAY) {
 283                 delete $ARRAY{$key};
 284         }
 285
 286 .fi
 287 (But it would be faster to use the
 288 .I reset
 289 command.
 290 Saying undef %ARRAY is faster yet.)
 291 .Ip "die(LIST)" 8
 292 .Ip "die LIST" 8
 293 Prints the value of LIST to
 294 .I STDERR
 295 and exits with the current value of $!
 296 (errno).
 297 If $! is 0, exits with the value of ($? >> 8) (\`command\` status).
 298 If ($? >> 8) is 0, exits with 255.
 299 Equivalent examples:
 300 .nf
 301
 302 .ne 3
 303 .ie t \{\
 304         die "Can't cd to spool: $!\en" unless chdir \'/usr/spool/news\';
 305 'br\}
 306 .el \{\
 307         die "Can't cd to spool: $!\en"
 308                 unless chdir \'/usr/spool/news\';
 309 'br\}
 310
 311         chdir \'/usr/spool/news\' || die "Can't cd to spool: $!\en"
 312
 313 .fi
 314 .Sp
 315 If the value of EXPR does not end in a newline, the current script line
 316 number and input line number (if any) are also printed, and a newline is
 317 supplied.
 318 Hint: sometimes appending \*(L", stopped\*(R" to your message will cause it to make
 319 better sense when the string \*(L"at foo line 123\*(R" is appended.
 320 Suppose you are running script \*(L"canasta\*(R".
 321 .nf
 322
 323 .ne 7
 324         die "/etc/games is no good";
 325         die "/etc/games is no good, stopped";
 326
 327 produce, respectively
 328
 329         /etc/games is no good at canasta line 123.
 330         /etc/games is no good, stopped at canasta line 123.
 331
 332 .fi
 333 See also
 334 .IR exit .
 335 .Ip "do BLOCK" 8 4
 336 Returns the value of the last command in the sequence of commands indicated
 337 by BLOCK.
 338 When modified by a loop modifier, executes the BLOCK once before testing the
 339 loop condition.
 340 (On other statements the loop modifiers test the conditional first.)
 341 .Ip "do SUBROUTINE (LIST)" 8 3
 342 Executes a SUBROUTINE declared by a
 343 .I sub
 344 declaration, and returns the value
 345 of the last expression evaluated in SUBROUTINE.
 346 If there is no subroutine by that name, produces a fatal error.
 347 (You may use the \*(L"defined\*(R" operator to determine if a subroutine
 348 exists.)
 349 If you pass arrays as part of LIST you may wish to pass the length
 350 of the array in front of each array.
 351 (See the section on subroutines later on.)
 352 SUBROUTINE may be a scalar variable, in which case the variable contains
 353 the name of the subroutine to execute.
 354 The parentheses are required to avoid confusion with the \*(L"do EXPR\*(R"
 355 form.
 356 .Sp
 357 As an alternate form, you may call a subroutine by prefixing the name with
 358 an ampersand: &foo(@args).
 359 If you aren't passing any arguments, you don't have to use parentheses.
 360 If you omit the parentheses, no @_ array is passed to the subroutine.
 361 The & form is also used to specify subroutines to the defined and undef
 362 operators.
 363 .Ip "do EXPR" 8 3
 364 Uses the value of EXPR as a filename and executes the contents of the file
 365 as a
 366 .I perl
 367 script.
 368 Its primary use is to include subroutines from a
 369 .I perl
 370 subroutine library.
 371 .nf
 372
 373         do \'stat.pl\';
 374
 375 is just like
 376
 377         eval \`cat stat.pl\`;
 378
 379 .fi
 380 except that it's more efficient, more concise, keeps track of the current
 381 filename for error messages, and searches all the
 382 .B \-I
 383 libraries if the file
 384 isn't in the current directory (see also the @INC array in Predefined Names).
 385 It's the same, however, in that it does reparse the file every time you
 386 call it, so if you are going to use the file inside a loop you might prefer
 387 to use \-P and #include, at the expense of a little more startup time.
 388 (The main problem with #include is that cpp doesn't grok # comments\*(--a
 389 workaround is to use \*(L";#\*(R" for standalone comments.)
 390 Note that the following are NOT equivalent:
 391 .nf
 392
 393 .ne 2
 394         do $foo;        # eval a file
 395         do $foo();      # call a subroutine
 396
 397 .fi
 398 .Ip "dump LABEL" 8 6
 399 This causes an immediate core dump.
 400 Primarily this is so that you can use the undump program to turn your
 401 core dump into an executable binary after having initialized all your
 402 variables at the beginning of the program.
 403 When the new binary is executed it will begin by executing a "goto LABEL"
 404 (with all the restrictions that goto suffers).
 405 Think of it as a goto with an intervening core dump and reincarnation.
 406 If LABEL is omitted, restarts the program from the top.
 407 WARNING: any files opened at the time of the dump will NOT be open any more
 408 when the program is reincarnated, with possible resulting confusion on the part
 409 of perl.
 410 See also \-u.
 411 .Sp
 412 Example:
 413 .nf
 414
 415 .ne 16
 416         #!/usr/bin/perl
 417         do 'getopt.pl';
 418         do 'stat.pl';
 419         %days = (
 420             'Sun',1,
 421             'Mon',2,
 422             'Tue',3,
 423             'Wed',4,
 424             'Thu',5,
 425             'Fri',6,
 426             'Sat',7);
 427
 428         dump QUICKSTART if $ARGV[0] eq '-d';
 429
 430     QUICKSTART:
 431         do Getopt('f');
 432
 433 .fi
 434 .Ip "each(ASSOC_ARRAY)" 8 6
 435 .Ip "each ASSOC_ARRAY" 8
 436 Returns a 2 element array consisting of the key and value for the next
 437 value of an associative array, so that you can iterate over it.
 438 Entries are returned in an apparently random order.
 439 When the array is entirely read, a null array is returned (which when
 440 assigned produces a FALSE (0) value).
 441 The next call to each() after that will start iterating again.
 442 The iterator can be reset only by reading all the elements from the array.
 443 You must not modify the array while iterating over it.
 444 There is a single iterator for each associative array, shared by all
 445 each(), keys() and values() function calls in the program.
 446 The following prints out your environment like the printenv program, only
 447 in a different order:
 448 .nf
 449
 450 .ne 3
 451         while (($key,$value) = each %ENV) {
 452                 print "$key=$value\en";
 453         }
 454
 455 .fi
 456 See also keys() and values().
 457 .Ip "eof(FILEHANDLE)" 8 8
 458 .Ip "eof()" 8
 459 .Ip "eof" 8
 460 Returns 1 if the next read on FILEHANDLE will return end of file, or if
 461 FILEHANDLE is not open.
 462 FILEHANDLE may be an expression whose value gives the real filehandle name.
 463 An eof without an argument returns the eof status for the last file read.
 464 Empty parentheses () may be used to indicate the pseudo file formed of the
 465 files listed on the command line, i.e. eof() is reasonable to use inside
 466 a while (<>) loop to detect the end of only the last file.
 467 Use eof(ARGV) or eof without the parentheses to test EACH file in a while (<>) loop.
 468 Examples:
 469 .nf
 470
 471 .ne 7
 472         # insert dashes just before last line of last file
 473         while (<>) {
 474                 if (eof()) {
 475                         print "\-\|\-\|\-\|\-\|\-\|\-\|\-\|\-\|\-\|\-\|\-\|\-\|\-\|\-\en";
 476                 }
 477                 print;
 478         }
 479
 480 .ne 7
 481         # reset line numbering on each input file
 482         while (<>) {
 483                 print "$.\et$_";
 484                 if (eof) {      # Not eof().
 485                         close(ARGV);
 486                 }
 487         }
 488
 489 .fi
 490 .Ip "eval(EXPR)" 8 6
 491 .Ip "eval EXPR" 8 6
 492 EXPR is parsed and executed as if it were a little
 493 .I perl
 494 program.
 495 It is executed in the context of the current
 496 .I perl
 497 program, so that
 498 any variable settings, subroutine or format definitions remain afterwards.
 499 The value returned is the value of the last expression evaluated, just
 500 as with subroutines.
 501 If there is a syntax error or runtime error, a null string is returned by
 502 eval, and $@ is set to the error message.
 503 If there was no error, $@ is null.
 504 If EXPR is omitted, evaluates $_.
 505 The final semicolon, if any, may be omitted from the expression.
 506 .Sp
 507 Note that, since eval traps otherwise-fatal errors, it is useful for
 508 determining whether a particular feature
 509 (such as dbmopen or symlink) is implemented.
 510 .Ip "exec(LIST)" 8 8
 511 .Ip "exec LIST" 8 6
 512 If there is more than one argument in LIST, or if LIST is an array with
 513 more than one value,
 514 calls execvp() with the arguments in LIST.
 515 If there is only one scalar argument, the argument is checked for shell metacharacters.
 516 If there are any, the entire argument is passed to \*(L"/bin/sh \-c\*(R" for parsing.
 517 If there are none, the argument is split into words and passed directly to
 518 execvp(), which is more efficient.
 519 Note: exec (and system) do not flush your output buffer, so you may need to
 520 set $| to avoid lost output.
 521 Examples:
 522 .nf
 523
 524         exec \'/bin/echo\', \'Your arguments are: \', @ARGV;
 525         exec "sort $outfile | uniq";
 526
 527 .fi
 528 .Sp
 529 If you don't really want to execute the first argument, but want to lie
 530 to the program you are executing about its own name, you can specify
 531 the program you actually want to run by assigning that to a variable and
 532 putting the name of the variable in front of the LIST without a comma.
 533 (This always forces interpretation of the LIST as a multi-valued list, even
 534 if there is only a single scalar in the list.)
 535 Example:
 536 .nf
 537
 538 .ne 2
 539         $shell = '/bin/csh';
 540         exec $shell '-sh';              # pretend it's a login shell
 541
 542 .fi
 543 .Ip "exit(EXPR)" 8 6
 544 .Ip "exit EXPR" 8
 545 Evaluates EXPR and exits immediately with that value.
 546 Example:
 547 .nf
 548
 549 .ne 2
 550         $ans = <STDIN>;
 551         exit 0 \|if \|$ans \|=~ \|/\|^[Xx]\|/\|;
 552
 553 .fi
 554 See also
 555 .IR die .
 556 If EXPR is omitted, exits with 0 status.
 557 .Ip "exp(EXPR)" 8 3
 558 .Ip "exp EXPR" 8
 559 Returns
 560 .I e
 561 to the power of EXPR.
 562 If EXPR is omitted, gives exp($_).
 563 .Ip "fcntl(FILEHANDLE,FUNCTION,SCALAR)" 8 4
 564 Implements the fcntl(2) function.
 565 You'll probably have to say
 566 .nf
 567
 568         do "fcntl.h";   # probably /usr/local/lib/perl/fcntl.h
 569
 570 .fi
 571 first to get the correct function definitions.
 572 If fcntl.h doesn't exist or doesn't have the correct definitions
 573 you'll have to roll
 574 your own, based on your C header files such as <sys/fcntl.h>.
 575 (There is a perl script called makelib that comes with the perl kit
 576 which may help you in this.)
 577 Argument processing and value return works just like ioctl below.
 578 Note that fcntl will produce a fatal error if used on a machine that doesn't implement
 579 fcntl(2).
 580 .Ip "fileno(FILEHANDLE)" 8 4
 581 .Ip "fileno FILEHANDLE" 8 4
 582 Returns the file descriptor for a filehandle.
 583 Useful for constructing bitmaps for select().
 584 If FILEHANDLE is an expression, the value is taken as the name of
 585 the filehandle.
 586 .Ip "flock(FILEHANDLE,OPERATION)" 8 4
 587 Calls flock(2) on FILEHANDLE.
 588 See manual page for flock(2) for definition of OPERATION.
 589 Will produce a fatal error if used on a machine that doesn't implement
 590 flock(2).
 591 Here's a mailbox appender for BSD systems.
 592 .nf
 593
 594 .ne 20
 595         $LOCK_SH = 1;
 596         $LOCK_EX = 2;
 597         $LOCK_NB = 4;
 598         $LOCK_UN = 8;
 599
 600         sub lock {
 601             flock(MBOX,$LOCK_EX);
 602             # and, in case someone appended
 603             # while we were waiting...
 604             seek(MBOX, 0, 2);
 605         }
 606
 607         sub unlock {
 608             flock(MBOX,$LOCK_UN);
 609         }
 610
 611         open(MBOX, ">>/usr/spool/mail/$USER")
 612                 || die "Can't open mailbox: $!";
 613
 614         do lock();
 615         print MBOX $msg,"\en\en";
 616         do unlock();
 617
 618 .fi
 619 .Ip "fork" 8 4
 620 Does a fork() call.
 621 Returns the child pid to the parent process and 0 to the child process.
 622 Note: unflushed buffers remain unflushed in both processes, which means
 623 you may need to set $| to avoid duplicate output.
 624 .Ip "getc(FILEHANDLE)" 8 4
 625 .Ip "getc FILEHANDLE" 8
 626 .Ip "getc" 8
 627 Returns the next character from the input file attached to FILEHANDLE, or
 628 a null string at EOF.
 629 If FILEHANDLE is omitted, reads from STDIN.
 630 .Ip "getlogin" 8 3
 631 Returns the current login from /etc/utmp, if any.
 632 If null, use getpwuid.
 633
 634         ($login = getlogin) || (($login) = getpwuid($<));
 635
 636 .Ip "getpeername(SOCKET)" 8 3
 637 Returns the packed sockaddr address of other end of the SOCKET connection.
 638 .nf
 639
 640 .ne 4
 641         # An internet sockaddr
 642         $sockaddr = 'S n a4 x8';
 643         $hersockaddr = getpeername(S);
 644 .ie t \{\
 645         ($family, $port, $heraddr) = unpack($sockaddr,$hersockaddr);
 646 'br\}
 647 .el \{\
 648         ($family, $port, $heraddr) =
 649                         unpack($sockaddr,$hersockaddr);
 650 'br\}
 651
 652 .fi
 653 .Ip "getpgrp(PID)" 8 4
 654 .Ip "getpgrp PID" 8
 655 Returns the current process group for the specified PID, 0 for the current
 656 process.
 657 Will produce a fatal error if used on a machine that doesn't implement
 658 getpgrp(2).
 659 If EXPR is omitted, returns process group of current process.
 660 .Ip "getppid" 8 4
 661 Returns the process id of the parent process.
 662 .Ip "getpriority(WHICH,WHO)" 8 4
 663 Returns the current priority for a process, a process group, or a user.
 664 (See getpriority(2).)
 665 Will produce a fatal error if used on a machine that doesn't implement
 666 getpriority(2).
 667 .Ip "getpwnam(NAME)" 8
 668 .Ip "getgrnam(NAME)" 8
 669 .Ip "gethostbyname(NAME)" 8
 670 .Ip "getnetbyname(NAME)" 8
 671 .Ip "getprotobyname(NAME)" 8
 672 .Ip "getpwuid(UID)" 8
 673 .Ip "getgrgid(GID)" 8
 674 .Ip "getservbyname(NAME,PROTO)" 8
 675 .Ip "gethostbyaddr(ADDR,ADDRTYPE)" 8
 676 .Ip "getnetbyaddr(ADDR,ADDRTYPE)" 8
 677 .Ip "getprotobynumber(NUMBER)" 8
 678 .Ip "getservbyport(PORT,PROTO)" 8
 679 .Ip "getpwent" 8
 680 .Ip "getgrent" 8
 681 .Ip "gethostent" 8
 682 .Ip "getnetent" 8
 683 .Ip "getprotoent" 8
 684 .Ip "getservent" 8
 685 .Ip "setpwent" 8
 686 .Ip "setgrent" 8
 687 .Ip "sethostent(STAYOPEN)" 8
 688 .Ip "setnetent(STAYOPEN)" 8
 689 .Ip "setprotoent(STAYOPEN)" 8
 690 .Ip "setservent(STAYOPEN)" 8
 691 .Ip "endpwent" 8
 692 .Ip "endgrent" 8
 693 .Ip "endhostent" 8
 694 .Ip "endnetent" 8
 695 .Ip "endprotoent" 8
 696 .Ip "endservent" 8
 697 These routines perform the same functions as their counterparts in the
 698 system library.
 699 The return values from the various get routines are as follows:
 700 .nf
 701
 702         ($name,$passwd,$uid,$gid,
 703            $quota,$comment,$gcos,$dir,$shell) = getpw.\|.\|.
 704         ($name,$passwd,$gid,$members) = getgr.\|.\|.
 705         ($name,$aliases,$addrtype,$length,@addrs) = gethost.\|.\|.
 706         ($name,$aliases,$addrtype,$net) = getnet.\|.\|.
 707         ($name,$aliases,$proto) = getproto.\|.\|.
 708         ($name,$aliases,$port,$proto) = getserv.\|.\|.
 709
 710 .fi
 711 The $members value returned by getgr.\|.\|. is a space separated list
 712 of the login names of the members of the group.
 713 .Sp
 714 The @addrs value returned by the gethost.\|.\|. functions is a list of the
 715 raw addresses returned by the corresponding system library call.
 716 In the Internet domain, each address is four bytes long and you can unpack
 717 it by saying something like:
 718 .nf
 719
 720         ($a,$b,$c,$d) = unpack('C4',$addr[0]);
 721
 722 .fi
 723 .Ip "getsockname(SOCKET)" 8 3
 724 Returns the packed sockaddr address of this end of the SOCKET connection.
 725 .nf
 726
 727 .ne 4
 728         # An internet sockaddr
 729         $sockaddr = 'S n a4 x8';
 730         $mysockaddr = getsockname(S);
 731 .ie t \{\
 732         ($family, $port, $myaddr) = unpack($sockaddr,$mysockaddr);
 733 'br\}
 734 .el \{\
 735         ($family, $port, $myaddr) =
 736                         unpack($sockaddr,$mysockaddr);
 737 'br\}
 738
 739 .fi
 740 .Ip "getsockopt(SOCKET,LEVEL,OPTNAME)" 8 3
 741 Returns the socket option requested, or undefined if there is an error.
 742 .Ip "gmtime(EXPR)" 8 4
 743 .Ip "gmtime EXPR" 8
 744 Converts a time as returned by the time function to a 9-element array with
 745 the time analyzed for the Greenwich timezone.
 746 Typically used as follows:
 747 .nf
 748
 749 .ne 3
 750 .ie t \{\
 751     ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = gmtime(time);
 752 'br\}
 753 .el \{\
 754     ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
 755                                                 gmtime(time);
 756 'br\}
 757
 758 .fi
 759 All array elements are numeric, and come straight out of a struct tm.
 760 In particular this means that $mon has the range 0.\|.11 and $wday has the
 761 range 0.\|.6.
 762 If EXPR is omitted, does gmtime(time).
 763 .Ip "goto LABEL" 8 6
 764 Finds the statement labeled with LABEL and resumes execution there.
 765 Currently you may only go to statements in the main body of the program
 766 that are not nested inside a do {} construct.
 767 This statement is not implemented very efficiently, and is here only to make
 768 the
 769 .IR sed -to- perl
 770 translator easier.
 771 I may change its semantics at any time, consistent with support for translated
 772 .I sed
 773 scripts.
 774 Use it at your own risk.
 775 Better yet, don't use it at all.
 776 .Ip "grep(EXPR,LIST)" 8 4
 777 Evaluates EXPR for each element of LIST (locally setting $_ to each element)
 778 and returns the array value consisting of those elements for which the
 779 expression evaluated to true.
 780 .nf
 781
 782         @foo = grep(!/^#/, @bar);    # weed out comments
 783
 784 .fi
 785 .Ip "hex(EXPR)" 8 4
 786 .Ip "hex EXPR" 8
 787 Returns the decimal value of EXPR interpreted as an hex string.
 788 (To interpret strings that might start with 0 or 0x see oct().)
 789 If EXPR is omitted, uses $_.
 790 .Ip "ioctl(FILEHANDLE,FUNCTION,SCALAR)" 8 4
 791 Implements the ioctl(2) function.
 792 You'll probably have to say
 793 .nf
 794
 795         do "ioctl.h";   # probably /usr/local/lib/perl/ioctl.h
 796
 797 .fi
 798 first to get the correct function definitions.
 799 If ioctl.h doesn't exist or doesn't have the correct definitions
 800 you'll have to roll
 801 your own, based on your C header files such as <sys/ioctl.h>.
 802 (There is a perl script called makelib that comes with the perl kit
 803 which may help you in this.)
 804 SCALAR will be read and/or written depending on the FUNCTION\*(--a pointer
 805 to the string value of SCALAR will be passed as the third argument of
 806 the actual ioctl call.
 807 (If SCALAR has no string value but does have a numeric value, that value
 808 will be passed rather than a pointer to the string value.
 809 To guarantee this to be true, add a 0 to the scalar before using it.)
 810 The pack() and unpack() functions are useful for manipulating the values
 811 of structures used by ioctl().
 812 The following example sets the erase character to DEL.
 813 .nf
 814
 815 .ne 9
 816         do 'ioctl.h';
 817         $sgttyb_t = "ccccs";            # 4 chars and a short
 818         if (ioctl(STDIN,$TIOCGETP,$sgttyb)) {
 819                 @ary = unpack($sgttyb_t,$sgttyb);
 820                 $ary[2] = 127;
 821                 $sgttyb = pack($sgttyb_t,@ary);
 822                 ioctl(STDIN,$TIOCSETP,$sgttyb)
 823                         || die "Can't ioctl: $!";
 824         }
 825
 826 .fi
 827 The return value of ioctl (and fcntl) is as follows:
 828 .nf
 829
 830 .ne 4
 831         if OS returns:\h'|3i'perl returns:
 832           -1\h'|3i'  undefined value
 833           0\h'|3i'  string "0 but true"
 834           anything else\h'|3i'  that number
 835
 836 .fi
 837 Thus perl returns true on success and false on failure, yet you can still
 838 easily determine the actual value returned by the operating system:
 839 .nf
 840
 841         ($retval = ioctl(...)) || ($retval = -1);
 842         printf "System returned %d\en", $retval;
 843 .fi
 844 .Ip "index(STR,SUBSTR)" 8 4
 845 Returns the position of the first occurrence of SUBSTR in STR, based at 0, or whatever you've
 846 set the $[ variable to.
 847 If the substring is not found, returns one less than the base, ordinarily \-1.
 848 .Ip "int(EXPR)" 8 4
 849 .Ip "int EXPR" 8
 850 Returns the integer portion of EXPR.
 851 If EXPR is omitted, uses $_.
 852 .Ip "join(EXPR,LIST)" 8 8
 853 .Ip "join(EXPR,ARRAY)" 8
 854 Joins the separate strings of LIST or ARRAY into a single string with fields
 855 separated by the value of EXPR, and returns the string.
 856 Example:
 857 .nf
 858
 859 .ie t \{\
 860     $_ = join(\|\':\', $login,$passwd,$uid,$gid,$gcos,$home,$shell);
 861 'br\}
 862 .el \{\
 863     $_ = join(\|\':\',
 864                 $login,$passwd,$uid,$gid,$gcos,$home,$shell);
 865 'br\}
 866
 867 .fi
 868 See
 869 .IR split .
 870 .Ip "keys(ASSOC_ARRAY)" 8 6
 871 .Ip "keys ASSOC_ARRAY" 8
 872 Returns a normal array consisting of all the keys of the named associative
 873 array.
 874 The keys are returned in an apparently random order, but it is the same order
 875 as either the values() or each() function produces (given that the associative array
 876 has not been modified).
 877 Here is yet another way to print your environment:
 878 .nf
 879
 880 .ne 5
 881         @keys = keys %ENV;
 882         @values = values %ENV;
 883         while ($#keys >= 0) {
 884                 print pop(keys), \'=\', pop(values), "\en";
 885         }
 886
 887 or how about sorted by key:
 888
 889 .ne 3
 890         foreach $key (sort(keys %ENV)) {
 891                 print $key, \'=\', $ENV{$key}, "\en";
 892         }
 893
 894 .fi
 895 .Ip "kill(LIST)" 8 8
 896 .Ip "kill LIST" 8 2
 897 Sends a signal to a list of processes.
 898 The first element of the list must be the signal to send.
 899 Returns the number of processes successfully signaled.
 900 .nf
 901
 902         $cnt = kill 1, $child1, $child2;
 903         kill 9, @goners;
 904
 905 .fi
 906 If the signal is negative, kills process groups instead of processes.
 907 (On System V, a negative \fIprocess\fR number will also kill process groups,
 908 but that's not portable.)
 909 You may use a signal name in quotes.
 910 .Ip "last LABEL" 8 8
 911 .Ip "last" 8
 912 The
 913 .I last
 914 command is like the
 915 .I break
 916 statement in C (as used in loops); it immediately exits the loop in question.
 917 If the LABEL is omitted, the command refers to the innermost enclosing loop.
 918 The
 919 .I continue
 920 block, if any, is not executed:
 921 .nf
 922
 923 .ne 4
 924         line: while (<STDIN>) {
 925                 last line if /\|^$/;    # exit when done with header
 926                 .\|.\|.
 927         }
 928
 929 .fi
 930 .Ip "length(EXPR)" 8 4
 931 .Ip "length EXPR" 8
 932 Returns the length in characters of the value of EXPR.
 933 If EXPR is omitted, returns length of $_.
 934 .Ip "link(OLDFILE,NEWFILE)" 8 2
 935 Creates a new filename linked to the old filename.
 936 Returns 1 for success, 0 otherwise.
 937 .Ip "listen(SOCKET,QUEUESIZE)" 8 2
 938 Does the same thing that the listen system call does.
 939 Returns true if it succeeded, false otherwise.
 940 See example in section on Interprocess Communication.
 941 .Ip "local(LIST)" 8 4
 942 Declares the listed variables to be local to the enclosing block,
 943 subroutine, eval or \*(L"do\*(R".
 944 All the listed elements must be legal lvalues.
 945 This operator works by saving the current values of those variables in LIST
 946 on a hidden stack and restoring them upon exiting the block, subroutine or eval.
 947 This means that called subroutines can also reference the local variable,
 948 but not the global one.
 949 The LIST may be assigned to if desired, which allows you to initialize
 950 your local variables.
 951 (If no initializer is given, all scalars are initialized to the null string
 952 and all arrays and associative arrays to the null array.)
 953 Commonly this is used to name the parameters to a subroutine.
 954 Examples:
 955 .nf
 956
 957 .ne 13
 958         sub RANGEVAL {
 959                 local($min, $max, $thunk) = @_;
 960                 local($result) = \'\';
 961                 local($i);
 962
 963                 # Presumably $thunk makes reference to $i
 964
 965                 for ($i = $min; $i < $max; $i++) {
 966                         $result .= eval $thunk;
 967                 }
 968
 969                 $result;
 970         }
 971
 972 .ne 6
 973         if ($sw eq \'-v\') {
 974             # init local array with global array
 975             local(@ARGV) = @ARGV;
 976             unshift(@ARGV,\'echo\');
 977             system @ARGV;
 978         }
 979         # @ARGV restored
 980
 981 .ne 6
 982         # temporarily add to digits associative array
 983         if ($base12) {
 984                 # (NOTE: not claiming this is efficient!)
 985                 local(%digits) = (%digits,'t',10,'e',11);
 986                 do parse_num();
 987         }
 988
 989 .fi
 990 Note that local() is a run-time command, and so gets executed every time
 991 through a loop, using up more stack storage each time until it's all
 992 released at once when the loop is exited.
 993 .Ip "localtime(EXPR)" 8 4
 994 .Ip "localtime EXPR" 8
 995 Converts a time as returned by the time function to a 9-element array with
 996 the time analyzed for the local timezone.
 997 Typically used as follows:
 998 .nf
 999
1000 .ne 3
1001 .ie t \{\
1002     ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = localtime(time);
1003 'br\}
1004 .el \{\
1005     ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) =
1006                                                 localtime(time);
1007 'br\}
1008
1009 .fi
1010 All array elements are numeric, and come straight out of a struct tm.
1011 In particular this means that $mon has the range 0.\|.11 and $wday has the
1012 range 0.\|.6.
1013 If EXPR is omitted, does localtime(time).
1014 .Ip "log(EXPR)" 8 4
1015 .Ip "log EXPR" 8
1016 Returns logarithm (base
1017 .IR e )
1018 of EXPR.
1019 If EXPR is omitted, returns log of $_.
1020 .Ip "lstat(FILEHANDLE)" 8 6
1021 .Ip "lstat FILEHANDLE" 8
1022 .Ip "lstat(EXPR)" 8
1023 .Ip "lstat SCALARVARIABLE" 8
1024 Does the same thing as the stat() function, but stats a symbolic link
1025 instead of the file the symbolic link points to.
1026 If symbolic links are unimplemented on your system, a normal stat is done.
1027 .Ip "m/PATTERN/io" 8 4
1028 .Ip "/PATTERN/io" 8
1029 Searches a string for a pattern match, and returns true (1) or false (\'\').
1030 If no string is specified via the =~ or !~ operator,
1031 the $_ string is searched.
1032 (The string specified with =~ need not be an lvalue\*(--it may be the result of an expression evaluation, but remember the =~ binds rather tightly.)
1033 See also the section on regular expressions.
1034 .Sp
1035 If / is the delimiter then the initial \*(L'm\*(R' is optional.
1036 With the \*(L'm\*(R' you can use any pair of characters as delimiters.
1037 This is particularly useful for matching Unix path names that contain \*(L'/\*(R'.
1038 If the final delimiter is followed by the optional letter \*(L'i\*(R', the matching is
1039 done in a case-insensitive manner.
1040 PATTERN may contain references to scalar variables, which will be interpolated
1041 (and the pattern recompiled) every time the pattern search is evaluated.
1042 If you want such a pattern to be compiled only once, add an \*(L"o\*(R" after
1043 the trailing delimiter.
1044 This avoids expensive run-time recompilations, and
1045 is useful when the value you are interpolating won't change over the
1046 life of the script.
1047 .Sp
1048 If used in a context that requires an array value, a pattern match returns an
1049 array consisting of the subexpressions matched by the parentheses in the
1050 pattern,
1051 i.e. ($1, $2, $3.\|.\|.).
1052 It does NOT actually set $1, $2, etc. in this case, nor does it set $+, $`, $&
1053 or $'.
1054 If the match fails, a null array is returned.
1055 .Sp
1056 Examples:
1057 .nf
1058
1059 .ne 4
1060     open(tty, \'/dev/tty\');
1061     <tty> \|=~ \|/\|^y\|/i \|&& \|do foo(\|);   # do foo if desired
1062
1063     if (/Version: \|*\|([0\-9.]*\|)\|/\|) { $version = $1; }
1064
1065     next if m#^/usr/spool/uucp#;
1066
1067 .ne 5
1068     # poor man's grep
1069     $arg = shift;
1070     while (<>) {
1071             print if /$arg/o;   # compile only once
1072     }
1073
1074     if (($F1, $F2, $Etc) = ($foo =~ /^(\eS+)\es+(\eS+)\es*(.*)/))
1075
1076 .fi
1077 This last example splits $foo into the first two words and the remainder
1078 of the line, and assigns those three fields to $F1, $F2 and $Etc.
1079 The conditional is true if any variables were assigned, i.e. if the pattern
1080 matched.
1081 .Ip "mkdir(FILENAME,MODE)" 8 3
1082 Creates the directory specified by FILENAME, with permissions specified by
1083 MODE (as modified by umask).
1084 If it succeeds it returns 1, otherwise it returns 0 and sets $! (errno).