Next: , Previous: , Up: Services   [Contents][Index]

4.4 Service De- and Constructors

All of the procedures listed below return procedures generated from the supplied arguments. These procedures take one argument in the case of destructors and no arguments in the case of constructors.

procedure: make-system-constructor command

The returned procedure will execute command in a shell and return #t if execution was successful, otherwise #f. For convenience, it takes multiple arguments which will be concatenated first.

procedure: make-system-destructor command

Similar to make-system-constructor, but returns #f if execution of the command was successful, #t if not.

procedure: make-forkexec-constructor command [#:user #f] [#:group #f] [#:pid-file #f] [#:pid-file-timeout (default-pid-file-timeout)] [#:log-file #f] [#:directory (default-service-directory)] [#:file-creation-mask #f] [#:environment-variables (default-environment-variables)]

Return a procedure that forks a child process, closes all file descriptors except the standard output and standard error descriptors, sets the current directory to directory, sets the umask to file-creation-mask unless it is #f, changes the environment to environment-variables (using the environ procedure), sets the current user to user and the current group to group unless they are #f, and executes command (a list of strings.) The result of the procedure will be the PID of the child process. Note that this will not work as expected if the process “daemonizes” (forks); in that case, you will need to pass #:pid-file, as explained below.

When pid-file is true, it must be the name of a PID file associated with the process being launched; the return value is the PID once that file has been created. If pid-file does not show up in less than pid-file-timeout seconds, the service is considered as failing to start.

When log-file is true, it names the file to which the service’s standard output and standard error are redirected. log-file is created if it does not exist, otherwise it is appended to.

procedure: make-kill-destructor [signal]

Return a procedure that sends signal to the process group of the PID given as argument, where signal defaults to SIGTERM.

This does work together with respawning services, because in that case the stop method of the <service> class sets the running slot to #f before actually calling the destructor; if it would not do that, killing the process in the destructor would immediately respawn the service.

The make-forkexec-constructor procedure builds upon the following procedures.

procedure: exec-command command [#:user #f] [#:group #f] [#:log-file #f] [#:directory (default-service-directory)] [#:file-creation-mask #f] [#:environment-variables (default-environment-variables)]
procedure: fork+exec-command command [#:user #f] [#:group #f] [#:directory (default-service-directory)] [#:file-creation-mask #f] [#:environment-variables (default-environment-variables)]

Run command as the current process from directory, with file-creation-mask if it’s true, and with environment-variables (a list of strings like "PATH=/bin".) File descriptors 1 and 2 are kept as is or redirected to log-file if it’s true, whereas file descriptor 0 (standard input) points to /dev/null; all other file descriptors are closed prior to yielding control to command.

By default, command is run as the current user. If the user keyword argument is present and not false, change to user immediately before invoking command. user may be a string, indicating a user name, or a number, indicating a user ID. Likewise, command will be run under the current group, unless the group keyword argument is present and not false.

fork+exec-command does the same as exec-command, but in a separate process whose PID it returns.

Scheme Variable: default-environment-variables

This parameter (see Parameters in GNU Guile Reference Manual) specifies the default list of environment variables to be defined when the procedures above create a new process.

It must be a list of strings where each string has the format name=value. It defaults to what environ returns when the program starts (see environ in GNU Guile Reference Manual).

Scheme Variable: default-pid-file-timeout

This parameter (see Parameters in GNU Guile Reference Manual) specified the default PID file timeout in seconds, when #:pid-file is used (see above). It defaults to 5 seconds.

Next: , Previous: , Up: Services   [Contents][Index]