Perl System Interaction
alarm(SECONDS)
alarm SECONDS
Arranges to have a `SIGALRM' delivered to this process after the specified number of seconds (minus 1, actually) have elapsed. Thus, alarm(15) will cause a `SIGALRM' at some point more than 14 seconds in the future. Only one timer may be counting at once. Each call disables the previous timer, and an argument of 0 may be supplied to cancel the previous timer without starting a new one. The returned value is the amount of time remaining on the previous timer.
chroot(FILENAME)
chroot FILENAME
chroot
Does the same as the system call of that name. If you don't know what it does, don't worry about it. If FILENAME is omitted, does chroot to `$_'.
die(LIST)
die LIST
die
Outside of an eval, prints the value of LIST to `STDERR' and exits with the current value of `$!' (errno). As of version 3.0 patchlevel 27, die without LIST specified is equivalent to
die 'Died';
If `$!' is 0, exits with the value of `($? >>
' (`command` status). If `($? >>
' is 0, exits with 255. Inside an eval, the error message is stuffed into `$@' and the eval is terminated with the undefined value. Equivalent examples:
die "Can't cd to spool: $!\n" unless chdir '/usr/spool/news';
chdir '/usr/spool/news' || die "Can't cd to spool: $!\n"
If the value of EXPR does not end in a newline, the current script line number and input line number (if any) are also printed, and a newline is supplied. Hint: sometimes appending ", stopped" to your message will cause it to make better sense when the string "at foo line 123" is appended. Suppose you are running script "canasta".
die "/etc/games is no good";
die "/etc/games is no good, stopped";
produce, respectively
/etc/games is no good at canasta line 123.
/etc/games is no good, stopped at canasta line 123.
See also exit.
exec(LIST)
exec LIST
If there is more than one argument in LIST, or if LIST is an array with more than one value, calls execvp() with the arguments in LIST. If there is only one scalar argument, the argument is checked for shell metacharacters. If there are any, the entire argument is passed to `/bin/sh -c' for parsing. If there are none, the argument is split into words and passed directly to execvp(), which is more efficient. Note: exec (and system) do not flush your output buffer, so you may need to set `$|' to avoid lost output. Examples:
exec '/bin/echo', 'Your arguments are: ', @ARGV;
exec "sort $outfile | uniq";
If you don't really want to execute the first argument, but want to lie to the program you are executing about its own name, you can specify the program you actually want to run by assigning that to a variable and putting the name of the variable in front of the LIST without a comma. (This always forces interpretation of the LIST as a multi-valued list, even if there is only a single scalar in the list.) Example:
$shell = '/bin/csh';
exec $shell '-sh'; # pretend it's a login shell
exit(EXPR)
exit EXPR
Evaluates EXPR and exits immediately with that value. Example:
$ans =
;
exit 0 if $ans =~ /^[Xx]/;
See also die. If EXPR is omitted, exits with 0 status.
fork
Does a fork() call. Returns the child pid to the parent process and 0 to the child process. Note: unflushed buffers remain unflushed in both processes, which means you may need to set `$|' to avoid duplicate output.
getpwnam(NAME)
getgrnam(NAME)
gethostbyname(NAME)
getnetbyname(NAME)
getprotobyname(NAME)
getpwuid(UID)
getgrgid(GID)
getservbyname(NAME,PROTO)
gethostbyaddr(ADDR,ADDRTYPE)
getnetbyaddr(ADDR,ADDRTYPE)
getprotobynumber(NUMBER)
getservbyport(PORT,PROTO)
getpwent
getgrent
gethostent
getnetent
getprotoent
getservent
setpwent
setgrent
sethostent(STAYOPEN)
setnetent(STAYOPEN)
setprotoent(STAYOPEN)
setservent(STAYOPEN)
endpwent
endgrent
endhostent
endnetent
endprotoent
endservent
These routines perform the same functions as their counterparts in the system library. With an array context, the return values from the various get routines are as follows:
($name,$passwd,$uid,$gid,
$quota,$comment,$gcos,$dir,$shell) = getpw...
($name,$passwd,$gid,$members) = getgr...
($name,$aliases,$addrtype,$length,@addrs) = gethost...
($name,$aliases,$addrtype,$net) = getnet...
($name,$aliases,$proto) = getproto...
($name,$aliases,$port,$proto) = getserv...
(If the entry doesn't exist you get a null list.) Within a scalar context, you get the name, unless the function was a lookup by name, in which case you get the other thing, whatever it is. (If the entry doesn't exist you get the undefined value.) For example:
$uid = getpwnam
$name = getpwuid
$name = getpwent
$gid = getgrnam
$name = getgrgid
$name = getgrent
etc.
The `$members' value returned by getgr... is a space separated list of the login names of the members of the group. For the gethost... functions, if the h_errno variable is supported in C, it will be returned to you via `$?' if the function call fails. The `@addrs' value returned by a successful call is a list of the raw addresses returned by the corresponding system library call. In the Internet domain, each address is four bytes long and you can unpack it by saying something like:
($a,$b,$c,$d) = unpack('C4',$addr[0]);
getlogin
Returns the current login from `/etc/utmp', if any. If null, use getpwuid.
$login = getlogin || (getpwuid($<))[0] || "Somebody";
getpgrp(PID)
getpgrp PID
getpgrp
Returns the current process group for the specified PID, 0 for the current process. Will produce a fatal error if used on a machine that doesn't implement getpgrp(2). If PID is omitted, returns process group of current process. PID can be an expression.
getppid
Returns the process id of the parent process.
getpriority(WHICH,WHO)
Returns the current priority for a process, a process group, or a user. (See the getpriority(2) man page.) Will produce a fatal error if used on a machine that doesn't implement getpriority(2).
ioctl(FILEHANDLE,FUNCTION,SCALAR)
Implements the ioctl(2) function. You'll probably have to say
require "ioctl.ph"; # probably `/usr/local/lib/perl/ioctl.ph'
first to get the correct function definitions. If `ioctl.ph' doesn't exist or doesn't have the correct definitions you'll have to roll your own, based on your C header files such as `'. (There is a perl script called h2ph that comes with the perl kit which may help you in this.) SCALAR will be read and/or written depending on the FUNCTION---a pointer to the string value of SCALAR will be passed as the third argument of the actual ioctl call. (If SCALAR has no string value but does have a numeric value, that value will be passed rather than a pointer to the string value. To guarantee this to be true, add a 0 to the scalar before using it.) The pack() and unpack() functions are useful for manipulating the values of structures used by ioctl(). The following example sets the erase character to DEL.
require 'ioctl.ph';
$sgttyb_t = "ccccs"; # 4 chars and a short
if (ioctl(STDIN,$TIOCGETP,$sgttyb)) {
@ary = unpack($sgttyb_t,$sgttyb);
$ary[2] = 127;
$sgttyb = pack($sgttyb_t,@ary);
ioctl(STDIN,$TIOCSETP,$sgttyb)
|| die "Can't ioctl: $!";
}
The return value of ioctl (and fcntl) is as follows:
if OS returns: perl returns:
-1 undefined value
0 string "0 but true"
anything else that number
Thus perl returns true on success and false on failure, yet you can still easily determine the actual value returned by the operating system:
($retval = ioctl(...)) || ($retval = -1);
printf "System returned %d\n", $retval;
kill(LIST)
kill LIST
Sends a signal to a list of processes. The first element of the list must be the signal to send. Returns the number of processes successfully signaled.
$cnt = kill 1, $child1, $child2;
kill 9, @goners;
If the signal is negative, kills process groups instead of processes. (On System V, a negative process number will also kill process groups, but that's not portable.) You may use a signal name in quotes.
setpgrp(PID,PGRP)
Sets the current process group for the specified PID, 0 for the current process. Will produce a fatal error if used on a machine that doesn't implement setpgrp(2).
setpriority(WHICH,WHO,PRIORITY)
Sets the current priority for a process, a process group, or a user. (See the setpriority(2) man page.) Will produce a fatal error if used on a machine that doesn't implement setpriority(2).
sleep(EXPR)
sleep EXPR
sleep
Causes the script to sleep for EXPR seconds, or forever if no EXPR. May be interrupted by sending the process a `SIGALRM'. Returns the number of seconds actually slept. You probably cannot mix alarm() and sleep() calls, since sleep() is often implemented using alarm().
syscall(LIST)
syscall LIST
Calls the system call specified as the first element of the list, passing the remaining elements as arguments to the system call. If unimplemented, produces a fatal error. The arguments are interpreted as follows: if a given argument is numeric, the argument is passed as an int. If not, the pointer to the string value is passed. You are responsible to make sure a string is pre-extended long enough to receive any result that might be written into a string. If your integer arguments are not literals and have never been interpreted in a numeric context, you may need to add 0 to them to force them to look like numbers.
require 'syscall.ph'; # may need to run h2ph
syscall(&SYS_write, fileno(STDOUT), "hi there\n", 9);
sysread(FILEHANDLE,SCALAR,LENGTH,OFFSET)
sysread(FILEHANDLE,SCALAR,LENGTH)
Attempts to read LENGTH bytes of data into variable SCALAR from the specified FILEHANDLE, using the system call read(2). It bypasses stdio, so mixing this with other kinds of reads may cause confusion. Returns the number of bytes actually read, or undef if there was an error. SCALAR will be grown or shrunk to the length actually read. An OFFSET may be specified to place the read data at some other place than the beginning of the string.
syswrite(FILEHANDLE,SCALAR,LENGTH,OFFSET)
syswrite(FILEHANDLE,SCALAR,LENGTH)
Attempts to write LENGTH bytes of data from variable SCALAR to the specified FILEHANDLE, using the system call write(2). It bypasses stdio, so mixing this with prints may cause confusion. Returns the number of bytes actually written, or undef if there was an error. An OFFSET may be specified to place the read data at some other place than the beginning of the string.
system(LIST)
system LIST
Does exactly the same thing as `exec LIST' except that a fork is done first, and the parent process waits for the child process to complete. Note that argument processing varies depending on the number of arguments. The return value is the exit status of the program as returned by the wait() call. To get the actual exit value divide by 256. See also exec.
times
Returns a four-element array giving the user and system times, in seconds, for this process and the children of this process.
($user,$system,$cuser,$csystem) = times;
umask(EXPR)
umask EXPR
umask
Sets the umask for the process and returns the old one. If EXPR is omitted, merely returns current umask.
wait
Waits for a child process to terminate and returns the pid of the deceased process, or -1 if there are no child processes. The status is returned in `$?'.
waitpid(PID,FLAGS)
Waits for a particular child process to terminate and returns the pid of the deceased process or -1 if there are no such child process. The status is returns in `$?'. If you say
require "sys/wait.ph";
...
waitpid(-1,&WNOHANG);
then you can do a non-blocking wait for any process. Non-blocking wait is only available on machines supporting either the waitpid(2) or wait4(2) system calls. However, waiting for a particular pid with FLAGS of 0 is implemented everywhere. (Perl emulates the system call by remembering the status values of processes that have exited but have not been harvested by the Perl script yet.)
warn(LIST)
warn LIST
Produces a message on `STDERR' just like die, but doesn't exit.
