perl.man.2

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