4.29.3 PID files programming API

The following bindings are exported by the library (vicare posix pid-files).

Function: create-pid-file

If requested: create the PID file and write the PID number in it, followed a newline. Return unspecified values.

This function makes use of the following parameters:

pid-pathname

When #f do nothing. Else use the string value as PID file pathname.

file-existence-procedure

Use the referenced procedure to test for PID file existence.

textual-contents-writing-procedure

Use the referenced procedure to write the PID file contents.

Raised exceptions:

• If the file already exists, raise an exception with condition components: &pid-file-already-exists, &who, &message, &irritants.
• If creating the file fails, add a condition object of type &pid-file-creation to whatever condition object is raised by the underlying procedure.

Function: remove-pid-file

Remove the PID file, if any; if PID file use is disabled: do nothing. Return unspecified values.

This function makes use of the following parameters:

pid-pathname

When #f do nothing. Else use the string value as PID file pathname.

file-existence-procedure

Use the referenced procedure to test for PID file existence.

textual-contents-reading-procedure

Use the referenced procedure to read the PID file contents.

file-removal-procedure

Use the referenced procedure to remove the PID file.

Raised exceptions:

• If the file does not exist, raise an exception with condition components: &pid-file-missing, &who, &message, &irritants.
• If reading the file fails, add a condition object of type &pid-file-removal to whatever condition object is raised by the underlying procedure.
• If the file contents are invalid, raise an exception with condition component: &pid-file-invalid-contents, &who, &message, &irritants.
• If removing the file fails, add a condition object of type &pid-file-removal to whatever condition object is raised by the underlying procedure.

Function: setup-compensated-pid-file-creation

Call the function create-pid-file and push a call to remove-pid-file to the current compensations stack. (vicare-scheme)Compensation stacks.

Beware of creating the compensation stack inside the dynamic environment configuration for PID file creation; in the following example the with-compensations syntax must be inside the parametrise syntax:

(parametrise ((pid-pathname "..."))
  (with-compensations
   (setup-compensated-pid-file-creation)
   ...))