info guile

7.2.7 Processes

Scheme Procedure: chdir str
C Function: scm_chdir (str): Change the current working directory to str. 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 behaviour:

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.

The following three functions can be used to decode the process status code 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 0 or 1, respectively.

The procedure exit is an alias of quit. They have the same functionality.

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.

If you are going to exec soon after forking, the procedures in (ice-9 popen) may be useful to you, as they fork and exec within an async-signal-safe function carefully written to ensure robust program behavior, even in the presence of threads. See section Pipes, for more.

This procedure has been renamed from fork to avoid a naming conflict with the scsh fork.

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).

Scheme Procedure: total-processor-count

C Function: scm_total_processor_count ()

Return the total number of processors of the machine, which is guaranteed to be at least 1. A “processor” here is a thread execution unit, which can be either:

an execution core in a (possibly multi-core) chip, in a (possibly multi- chip) module, in a single computer, or
a thread execution unit inside a core in the case of hyper-threaded CPUs.

Which of the two definitions is used, is unspecified.

Scheme Procedure: current-processor-count
C Function: scm_current_processor_count (): Like total-processor-count, but return the number of processors available to the current process. See setaffinity and getaffinity for more information.

This document was generated on April 20, 2013 using texi2html 5.0.