Processes (Guile Reference Manual)

Processes (Guile Reference Manual)
Next:
Signals
, Previous:
Runtime Environment
, Up:
POSIX
System Calls and Networking
Contents
][
Index
7.2.7 Processes
Scheme Procedure:
chdir
str
C Function:
scm_chdir
(str)
Change the current working directory to
str
str
can be a
string containing a file name, or a port if supported by the system.
(provided? 'chdir-port)
reports whether ports are supported.
The return value is unspecified.
Scheme Procedure:
getcwd
C Function:
scm_getcwd
()
Return the name of the current working directory.
Scheme Procedure:
umask
[mode]
C Function:
scm_umask
(mode)
If
mode
is omitted, returns a decimal number representing the
current file creation mask. Otherwise the file creation mask is set
to
mode
and the previous value is returned. See
Assigning File Permissions
in
The GNU C Library
Reference Manual
, for more on how to use umasks.
E.g.,
(umask #o022)
sets the mask to octal 22/decimal 18.
Scheme Procedure:
chroot
path
C Function:
scm_chroot
(path)
Change the root directory to that specified in
path
This directory will be used for path names beginning with
. The root directory is inherited by all children
of the current process. Only the superuser may change the
root directory.
Scheme Procedure:
getpid
C Function:
scm_getpid
()
Return an integer representing the current process ID.
Scheme Procedure:
getgroups
C Function:
scm_getgroups
()
Return a vector of integers representing the current
supplementary group IDs.
Scheme Procedure:
getppid
C Function:
scm_getppid
()
Return an integer representing the process ID of the parent
process.
Scheme Procedure:
getuid
C Function:
scm_getuid
()
Return an integer representing the current real user ID.
Scheme Procedure:
getgid
C Function:
scm_getgid
()
Return an integer representing the current real group ID.
Scheme Procedure:
geteuid
C Function:
scm_geteuid
()
Return an integer representing the current effective user ID.
If the system does not support effective IDs, then the real ID
is returned.
(provided? 'EIDs)
reports whether the
system supports effective IDs.
Scheme Procedure:
getegid
C Function:
scm_getegid
()
Return an integer representing the current effective group ID.
If the system does not support effective IDs, then the real ID
is returned.
(provided? 'EIDs)
reports whether the
system supports effective IDs.
Scheme Procedure:
setgroups
vec
C Function:
scm_setgroups
(vec)
Set the current set of supplementary group IDs to the integers in the
given vector
vec
. The return value is unspecified.
Generally only the superuser can set the process group IDs
(see
Setting the Group IDs
in
The GNU C
Library Reference Manual
).
Scheme Procedure:
setuid
id
C Function:
scm_setuid
(id)
Sets both the real and effective user IDs to the integer
id
, provided
the process has appropriate privileges.
The return value is unspecified.
Scheme Procedure:
setgid
id
C Function:
scm_setgid
(id)
Sets both the real and effective group IDs to the integer
id
, provided
the process has appropriate privileges.
The return value is unspecified.
Scheme Procedure:
seteuid
id
C Function:
scm_seteuid
(id)
Sets the effective user ID to the integer
id
, provided the process
has appropriate privileges. If effective IDs are not supported, the
real ID is set instead—
(provided? 'EIDs)
reports whether the
system supports effective IDs.
The return value is unspecified.
Scheme Procedure:
setegid
id
C Function:
scm_setegid
(id)
Sets the effective group ID to the integer
id
, provided the process
has appropriate privileges. If effective IDs are not supported, the
real ID is set instead—
(provided? 'EIDs)
reports whether the
system supports effective IDs.
The return value is unspecified.
Scheme Procedure:
getpgrp
C Function:
scm_getpgrp
()
Return an integer representing the current process group ID.
This is the
POSIX
definition, not
BSD
Scheme Procedure:
setpgid
pid pgid
C Function:
scm_setpgid
(pid, pgid)
Move the process
pid
into the process group
pgid
pid
or
pgid
must be integers: they can be zero to indicate the ID of the
current process.
Fails on systems that do not support job control.
The return value is unspecified.
Scheme Procedure:
setsid
C Function:
scm_setsid
()
Creates a new session. The current process becomes the session leader
and is put in a new process group. The process will be detached
from its controlling terminal if it has one.
The return value is an integer representing the new process group ID.
Scheme Procedure:
getsid
pid
C Function:
scm_getsid
(pid)
Returns the session ID of process
pid
. (The session
ID of a process is the process group ID of its session leader.)
Scheme Procedure:
waitpid
pid [options]
C Function:
scm_waitpid
(pid, options)
This procedure collects status information from a child process which
has terminated or (optionally) stopped. Normally it will
suspend the calling process until this can be done. If more than one
child process is eligible then one will be chosen by the operating system.
The value of
pid
determines the behavior:
pid
greater than 0
Request status information from the specified child process.
pid
equal to -1 or
WAIT_ANY
Request status information for any child process.
pid
equal to 0 or
WAIT_MYPGRP
Request status information for any child process in the current process
group.
pid
less than -1
Request status information for any child process whose process group ID
is -
pid
The
options
argument, if supplied, should be the bitwise OR of the
values of zero or more of the following variables:
Variable:
WNOHANG
Return immediately even if there are no child processes to be collected.
Variable:
WUNTRACED
Report status information for stopped processes as well as terminated
processes.
The return value is a pair containing:
The process ID of the child process, or 0 if
WNOHANG
was
specified and no process was collected.
The integer status value (see
Process Completion Status
in
The
GNU C Library Reference Manual
).
The following three
functions can be used to decode the integer status value returned by
waitpid
Scheme Procedure:
status:exit-val
status
C Function:
scm_status_exit_val
(status)
Return the exit status value, as would be set if a process
ended normally through a call to
exit
or
_exit
if any, otherwise
#f
Scheme Procedure:
status:term-sig
status
C Function:
scm_status_term_sig
(status)
Return the signal number which terminated the process, if any,
otherwise
#f
Scheme Procedure:
status:stop-sig
status
C Function:
scm_status_stop_sig
(status)
Return the signal number which stopped the process, if any,
otherwise
#f
Scheme Procedure:
system
[cmd]
C Function:
scm_system
(cmd)
Execute
cmd
using the operating system’s “command
processor”. Under Unix this is usually the default shell
sh
. The value returned is
cmd
’s exit status as
returned by
waitpid
, which can be interpreted using the
functions above.
If
system
is called without arguments, return a boolean
indicating whether the command processor is available.
Scheme Procedure:
system*
arg1 arg2 …
C Function:
scm_system_star
(args)
Execute the command indicated by
arg1
arg2
...
. The
first element must be a string indicating the command to be executed,
and the remaining items must be strings representing each of the
arguments to that command.
This function returns the exit status of the command as provided by
waitpid
. This value can be handled with
status:exit-val
and the related functions.
system*
is similar to
system
, but accepts only one
string per-argument, and performs no shell interpretation. The
command is executed using fork and execlp. Accordingly this function
may be safer than
system
in situations where shell
interpretation is not required.
Example: (system* "echo" "foo" "bar")
Scheme Procedure:
quit
[status]
Scheme Procedure:
exit
[status]
Terminate the current process with proper unwinding of the Scheme stack.
The exit status zero if
status
is not supplied. If
status
is supplied, and it is an integer, that integer is used as the exit
status. If
status
is
#t
or
#f
, the exit status is
EXIT_SUCCESS
or
EXIT_FAILURE
, respectively.
The procedure
exit
is an alias of
quit
. They have the
same functionality.
Scheme Variable:
EXIT_SUCCESS
Scheme Variable:
EXIT_FAILURE
These constants represent the standard exit codes for success (zero) or
failure (one.)
Scheme Procedure:
primitive-exit
[status]
Scheme Procedure:
primitive-_exit
[status]
C Function:
scm_primitive_exit
(status)
C Function:
scm_primitive__exit
(status)
Terminate the current process without unwinding the Scheme stack. The
exit status is
status
if supplied, otherwise zero.
primitive-exit
uses the C
exit
function and hence runs
usual C level cleanups (flush output streams, call
atexit
functions, etc, see
Normal Termination
in
The GNU C Library
Reference Manual
)).
primitive-_exit
is the
_exit
system call
(see
Termination Internals
in
The GNU C Library Reference
Manual
). This terminates the program immediately, with neither
Scheme-level nor C-level cleanups.
The typical use for
primitive-_exit
is from a child process
created with
primitive-fork
. For example in a Gdk program the
child process inherits the X server connection and a C-level
atexit
cleanup which will close that connection. But closing
in the child would upset the protocol in the parent, so
primitive-_exit
should be used to exit without that.
Scheme Procedure:
execl
filename arg …
C Function:
scm_execl
(filename, args)
Executes the file named by
filename
as a new process image.
The remaining arguments are supplied to the process; from a C program
they are accessible as the
argv
argument to
main
Conventionally the first
arg
is the same as
filename
All arguments must be strings.
If
arg
is missing,
filename
is executed with a null
argument list, which may have system-dependent side-effects.
This procedure is currently implemented using the
execv
system
call, but we call it
execl
because of its Scheme calling interface.
Scheme Procedure:
execlp
filename arg …
C Function:
scm_execlp
(filename, args)
Similar to
execl
, however if
filename
does not contain a slash
then the file to execute will be located by searching the
directories listed in the
PATH
environment variable.
This procedure is currently implemented using the
execvp
system
call, but we call it
execlp
because of its Scheme calling interface.
Scheme Procedure:
execle
filename env arg …
C Function:
scm_execle
(filename, env, args)
Similar to
execl
, but the environment of the new process is
specified by
env
, which must be a list of strings as returned by the
environ
procedure.
This procedure is currently implemented using the
execve
system
call, but we call it
execle
because of its Scheme calling interface.
Scheme Procedure:
primitive-fork
C Function:
scm_fork
()
Creates a new “child” process by duplicating the current “parent” process.
In the child the return value is 0. In the parent the return value is
the integer process ID of the child.
Note that it is unsafe to fork a process that has multiple threads
running, as only the thread that calls
primitive-fork
will
persist in the child. Any resources that other threads held, such as
locked mutexes or open file descriptors, are lost. Indeed,
POSIX
specifies that only async-signal-safe procedures are
safe to call after a multithreaded fork, which is a very limited set.
Guile issues a warning if it detects a fork from a multi-threaded
program.
Note:
If you are looking to spawn a process with some pipes set up, using the
spawn
procedure described below will be more robust (in
particular in multi-threaded contexts), more portable, and usually more
efficient than the combination of
primitive-fork
and
execl
This procedure has been renamed from
fork
to avoid a naming conflict
with the scsh fork.
Scheme Procedure:
spawn
program
arguments
[#:environment=(environ)] [#:input=(current-input-port)] [#:output=(current-output-port)] [#:error=(current-error-port)] [#:search-path?=#t]
Spawn a new child process executing
program
with the
given
arguments
, a list of one or more strings (by
convention, the first argument is typically
program
),
and return its PID. Raise a
system-error
exception if
program
could not be found or could not be executed.
If the keyword argument
#:search-path?
is true, it
selects whether the
PATH
environment variable should be
inspected to find
program
. It is true by default.
The
#:environment
keyword parameter specifies the
list of environment variables of the child process. It
defaults to
(environ)
The keyword arguments
#:input
#:output
, and
#:error
specify the port or file descriptor for the
child process to use as standard input, standard output, and
standard error. No other file descriptors are inherited
from the parent process.
The example below shows how to spawn the
uname
program with
the
-o
option (see
uname invocation
in
GNU
Coreutils
), redirect its standard output to a pipe, and read from it:
(use-modules (rnrs io ports))

(let* ((input+output (pipe))
(pid (spawn "uname" '("uname" "-o")
#:output (cdr input+output))))
(close-port (cdr input+output))
(format #t "read ~s~%" (get-string-all (car input+output)))
(close-port (car input+output))
(waitpid pid))

-| read "GNU/Linux\n"
⇒ (1234 . 0)
Scheme Procedure:
nice
incr
C Function:
scm_nice
(incr)
Increment the priority of the current process by
incr
. A higher
priority value means that the process runs less often.
The return value is unspecified.
Scheme Procedure:
setpriority
which who prio
C Function:
scm_setpriority
(which, who, prio)
Set the scheduling priority of the process, process group
or user, as indicated by
which
and
who
which
is one of the variables
PRIO_PROCESS
PRIO_PGRP
or
PRIO_USER
, and
who
is interpreted relative to
which
(a process identifier for
PRIO_PROCESS
process group identifier for
PRIO_PGRP
, and a user
identifier for
PRIO_USER
. A zero value of
who
denotes the current process, process group, or user.
prio
is a value in the range [-20,20]. The default
priority is 0; lower priorities (in numerical terms) cause more
favorable scheduling. Sets the priority of all of the specified
processes. Only the super-user may lower priorities. The return
value is not specified.
Scheme Procedure:
getpriority
which who
C Function:
scm_getpriority
(which, who)
Return the scheduling priority of the process, process group
or user, as indicated by
which
and
who
which
is one of the variables
PRIO_PROCESS
PRIO_PGRP
or
PRIO_USER
, and
who
should be interpreted depending on
which
(a process identifier for
PRIO_PROCESS
process group identifier for
PRIO_PGRP
, and a user
identifier for
PRIO_USER
). A zero value of
who
denotes the current process, process group, or user. Return
the highest priority (lowest numerical value) of any of the
specified processes.
Scheme Procedure:
getaffinity
pid
C Function:
scm_getaffinity
(pid)
Return a bitvector representing the CPU affinity mask for
process
pid
. Each CPU the process has affinity with
has its corresponding bit set in the returned bitvector.
The number of bits set is a good estimate of how many CPUs
Guile can use without stepping on other processes’ toes.
Currently this procedure is only defined on GNU variants
(see
sched_getaffinity
in
The
GNU C Library Reference Manual
).
Scheme Procedure:
setaffinity
pid mask
C Function:
scm_setaffinity
(pid, mask)
Install the CPU affinity mask
mask
, a bitvector, for
the process or thread with ID
pid
. The return value
is unspecified.
Currently this procedure is only defined on GNU variants
(see
sched_setaffinity
in
The
GNU C Library Reference Manual
).
See
Threads
, for information on how get the number of processors
available on a system.
Next:
Signals
, Previous:
Runtime Environment
, Up:
POSIX
System Calls and Networking
Contents
][
Index