System Interaction Routines

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.

chdir(EXPR)

chdir EXPR

Changes the working directory to EXPR, if possible. If EXPR is omitted, changes to home directory. Returns 1 upon success, 0 otherwise. See example under die.

chroot(FILENAME)

chroot FILENAME

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

Outside of an eval, prints the value of LIST to STDERR and exits with the current value of $! (errno). If $! is 0, exits with the value of ($? >> 8) (\`command\` status). If ($? >> 8) 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 = <STDIN>;
	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.

getlogin

Returns the current login from /etc/utmp, if any. If null, use getpwuid. $login = getlogin || (getpwuid($<))[0] || "Somebody";

getpgrp(PID)

getpgrp PID

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 EXPR is omitted, returns process group of current process.

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 getpriority(2).) Will produce a fatal error if used on a machine that doesn't implement getpriority(2).

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 setpriority(2).) 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);

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.

time

Returns the number of non-leap seconds since 00:00:00 UTC, January 1, 1970. Suitable for feeding to gmtime() and localtime().

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 is no such child process. The status is returned in $?. If you say

	require "sys/wait.h";
	...
	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.