Scsh Reference Manual

#
Chapter 10
Miscellaneous routines

## 10.1 Integer bitwise ops

`(arithmetic-shift i j)` ---> integer (procedure)
`(bitwise-and i j)` ---> integer (procedure)
`(bitwise-ior i j)` ---> integer (procedure)
`(bitwise-not i)` ---> integer (procedure)
`(bitwise-xor i j)` ---> integer (procedure)

> These operations operate on integers representing semi-infinite bit strings, using a 2's-complement encoding.

> `arithmetic-shift` shifts i by j bits. A left shift is j > 0; a right shift is j < 0.

## 10.2 Password encryption

`(crypt key salt)` ---> encrypted value (procedure)

Decrypts key by directly calling the `crypt` function using salt to perturb the hashing algorithm. Salt must be a two-character string consisting of digits, alphabetic characters, ``.'' or ```\`''. The length of key may be at most eight.

## 10.3 Dot-Locking

Section 3.2.8 already points out that POSIX's file locks are almost useless in practice. To bypass this restriction other advisory locking mechanisms, based only on standard file operations, where invented. One of them is the so-called dot-locking scheme where the lock of file-name is represented by the file file-name`.lock`. Care is taken that only one process may generate the lock for a given file.

Here is scsh's interface to dot-locking:

`(obtain-dot-lock file-name [interval retry-number stale-time])` ---> boolean (procedure)

> Tries to obtain the lock for file-name. If the file is already locked, the thread sleeps for interval seconds (default is 1) before it retries. If the lock cannot be obtained after retry-number attempts, the procedure returns `#f`, otherwise `#t`. The default value of retry-number is `#f` which corresponds to an infinite number of retires.

> If stale-time is non-`#f`, it specifies the minimum age a lock may have (in seconds) before it is considered stale. `Obtain-dot-lock` attempts to delete stale locks. If it was succcessful obtaining a lock after breaking it, `obtain-dot-lock` returns `broken`. If stale-time is `#f`, `obtain-dot-lock` never considers a lock stale. The default for stale-time is 300.

> Note that it is possible that `obtain-dot-lock` breaks a lock but nevertheless fails to obtain it otherwise. If it is necessary to handle this case specially, use `break-dot-lock` directly (see below) rather than specifying a non-`#f` stale-time

`(break-dot-lock file-name)` ---> undefined (procedure)

> Breaks the lock for file-name if one exists. Note that breaking a lock does not imply a subsequent `obtain-dot-lock` will succeed, as another party may have acquired the lock between `break-dot-lock` and `obtain-dot-lock`.

`(release-dot-lock file-name)` ---> boolean (procedure)

> Releases the lock for file-name. On success, `release-dot-lock` returns `#t`, otherwise `#f`. Note that this procedure can also be used to break the lock for file-name.

`(with-dot-lock* file-name thunk)` ---> value(s) of thunk (procedure)
`(with-dot-lock file-name body `...`)` ---> value(s) of body (syntax)

> The procedure `with-dot-lock*` obtains the requested lock, and then calls `(thunk)`. When thunk returns, the lock is released. A non-local exit (e.g., throwing to a saved continuation or raising an exception) also causes the lock to be released.

> After a normal return from thunk, its return values are returned by `with-dot-lock*`. The `with-dot-lock` special form is equivalent syntactic sugar.

## 10.4 Syslog facility

(Note: the functionality presented in this section is still somewhat experimental and thus subject to interface changes.)

The procedures in this section provide access to the 4.2BSD syslog facility present in most POSIX systems. The functionality is in a structure called `syslog`. There's an additional structure `syslog-channels` documented below. The scsh interface to the syslog facility differs significantly from that of the Unix library functionality in order to support multiple simultaneous connections to the syslog facility.

Log messages carry a variety of parameters beside the text of the message itself, namely a set of options controlling the output format and destination, the facility identifying the class of programs the message is coming from, an identifier specifying the conrete program, and the level identifying the importance of the message. Moreover, a log mask can prevent messages at certain levels to be actually sent to the syslog daemon.

### Log options

A log option specifies details of the I/O behavior of the syslog facility. A syslog option is an element of a finite type (see the Scheme 48 manual) constructed by the `syslog-option` macro. The syslog facility works with sets of options which are represented as enum sets (see the Scheme 48 manual).

`(syslog-option option-name)` ---> option (syntax)

`(syslog-option? x)` ---> boolean (procedure)

`(make-syslog-options list)` ---> options (procedure)

`(syslog-options option-name `...`)` ---> options (syntax)

`(syslog-options? x)` ---> boolean (procedure)

> `Syslog-option` constructs a log option from the name of an option. (The possible names are listed below.) `Syslog-option?` is a predicate for log options. Options are comparable using `eq?`. `Make-syslog-options` constructs a set of options from a list of options. `Syslog-options` is a macro which expands into an expression returning a set of options from names. `Syslog-options?` is a predicate for sets of options.

Here is a list of possible names of syslog options:

`console`
  If syslog cannot pass the message to syslogd it will attempt to write the message to the console.

`delay`
  Delay opening the connection to syslogd immediately until the first message is logged.

`no-delay`
  Open the connection to syslogd immediately. Normally the open is delayed until the first message is logged. Useful for programs that need to manage the order in which file descriptors are allocated.

  NOTA BENE: The `delay` and `no-delay` options are included for completeness, but do not have the expected effect in the present Scheme interface: Because the Scheme interface has to multiplex multiple simultaneous connections to the syslog facility over a single one, open and close operations on that facility happen at unpredictable times.

`log-pid`
  Log the process id with each message: useful for identifying instantiations of daemons.

### Log facilities

A log facility identifies the originator of a log message from a finite set known to the system. Each originator is identified by a name:

`(syslog-facility facility-name)` ---> facility (syntax)

`(syslog-facility? x)` ---> boolean (procedure)

> `Syslog-facility` is macro that expands into an expression returning a facility for a given name. `Syslog-facility?` is a predicate for facilities. Facilities are comparable via `eq?`.

Here is a list of possible names of syslog facilities:

`authorization`
  The authorization system: login, su, getty, etc.

`cron`
  The cron daemon.

`daemon`
  System daemons, such as routed, that are not provided for explicitly by other facilities.

`kernel`
  Messages generated by the kernel.

`lpr`
  The line printer spooling system: lpr, lpc, lpd, etc.

`mail`
  The mail system.

`news`
  The network news system.

`user`
  Messages generated by random user processes.

`uucp`
  The uucp system.

`local0` `local1` `local2` `local3` `local4` `local5` `local6` `local7`
  Reserved for local use.

### Log levels

A log level identifies the importance of a message from a fixed set of possible levels.

`(syslog-level level-name)` ---> level (syntax)

`(syslog-level? x)` ---> boolean (procedure)

> `Syslog-level` is macro that expands into an expression returning a facility for a given name. `Syslog-level?` is a predicate for facilities. Levels are comparable via `eq?`.

Here is a list of possible names of syslog levels:

`emergency`
  A panic condition. This is normally broadcast to all users.

`alert`
  A condition that should be corrected immediately, such as a corrupted system database.

`critical`
  Critical conditions, e.g., hard device errors.

`error`
  Errors.

`warning`
  Warning messages.

`notice`
  Conditions that are not error conditions, but should possibly be handled specially.

`info`
  Informational messages.

`debug`
  Messages that contain information normally of use only when debugging a program.

### Log masks

A log masks can mask out log messages at a set of levels. A log mask is an enum set of log levels.

`(make-syslog-mask list)` ---> mask (procedure)

`(syslog-mask level-name `...`)` ---> mask (syntax)

`syslog-mask-all` mask

`(syslog-mask-upto level)` ---> mask (procedure)

`(syslog-mask? x)` ---> boolean (procedure)

> `Make-syslog-mask` constructs a mask from a list of levels. `Syslog-mask` is a macro which constructs a mask from names of levels. `Syslog-mask-all` is a predefined log mask containing all levels. `Syslog-mask-upto` returns a mask consisting of all levels up to and including a certain level, starting with `emergency`.

### Logging

Scheme 48 dynamically maintains implicit connections to the syslog facility specifying a current identifier, current options, a current facility and a current log mask. This implicit connection is held in a thread fluid (see Section 9.5). Hence, every thread maintains it own implicit connection to syslog. Note that the connection is not implicitly preserved across a `spawn`, but it is preserved across a `fork-thread`:

`(with-syslog-destination string options facility mask thunk)` ---> value (procedure)

`(set-syslog-destination! string options facility mask)` ---> undefined (procedure)

> `With-syslog-destination` dynamically binds parameters of the implicit connection to the syslog facility and runs thunk within those parameter bindings, returning what thunk returns. Each of the parameters may be `#f` in which case the previous values will be used. `Set-syslog-destination!` sets the parameters of the implicit connection of the current thread.

`(syslog level message)` ---> undefined (procedure)

`(syslog level message [string options syslog-facility])` ---> undefined (procedure)

> `Syslog` actually logs a message. Each of the parameters of the implicit connection (except for the log mask) can be explicitly specified as well for the current call to `syslog`, overriding the parameters of the channel. The parameters revert to their original values after the call.

### Syslog channels

The `syslog-channels` structure allows direct manipulation of syslog channels, the objects that represent connections to the syslog facility. Note that it is not necessary to explicitly open a syslog channel to do logging.

`(open-syslog-channel string options facility mask)` ---> channel (procedure)

`(close-syslog-channel channel)` ---> undefined (procedure)

`(syslog level message channel)` ---> undefined (procedure)

> `Open-syslog-channel` and `close-syslog-channel` create and destroy a connection to the syslog facility, respectively. The specified form of calling `syslog` logs to the specified channel.

## 10.5 MD5 interface

Scsh provides a direct interface to the MD5 functions to compute the ``fingerprint'' or ``message digest'' of a file or string. It uses the C library written by Colin Plum.

`(md5-digest-for-string string)` ---> md5-digest (procedure)

> Calculates the MD5 digest for the given string.

`(md5-digest-for-port port [buffer-size])` ---> md5-digest (procedure)

> Reads the contents of the port and calculates the MD5 digest for it. The optional argument buffer-size determines the size of the port's input buffer in bytes. It defaults to 1024 bytes.

`(md5-digest? thing)` ---> boolean (procedure)

> The type predicate for MD5 digests: `md5-digest?` returns true if and only if thing is a MD5 digest.

`(md5-digest->number md5-digest)` ---> number (procedure)

> Returns the number corresponding to the MD5 digest.

`(number->md5-digest number)` ---> md5-digest (procedure)

> Creates a MD5 digest from a number.

`(make-md5-context)` ---> md5-context (procedure)
`(md5-context? thing)` ---> boolean (procedure)
`(update-md5-context! md5-context string)` ---> undefined (procedure)
`(md5-context->md5-digest md5-context)` ---> md5-digest (procedure)

> These procedures provide a low-level interface to the library. A md5-context stores the state of a MD5 computation, it is created by `make-md5-context`, its type predicate is `md5-context?`. The procedure `update-md5-context!` extends the md5-context by the given string. Finally, `md5-context->md5-digest` returns the md5-digest for the md5-context. With these procedures it is possible to incrementally add strings to a md5-context before computing the digest.

## 10.6 Configuration variables

This section describes procedures to access the configuration parameters used to compile scsh and flags needed to build C extensions for scsh.

`(host)` ---> string (procedure)
`(machine)` ---> string (procedure)
`(vendor)` ---> string (procedure)
`(os)` ---> string (procedure)

> These procedures return the description of the host, scsh was built on, as determined by the script `config.guess`.

`(prefix)` ---> string (procedure)
`(exec-prefix)` ---> string (procedure)
`(bin-dir)` ---> string (procedure)
`(lib-dir)` ---> string (procedure)
`(include-dir)` ---> string (procedure)
`(man-dir)` ---> string (procedure)

> These procedures return the various directories of the scsh installation.

`(lib-dirs-list)` ---> symbol list (procedure)

> Returns the default list of library directories. See Section 11.1.5 for more information about the library search facility.

`(libs)` ---> string (procedure)
`(defs)` ---> string (procedure)
`(cflags)` ---> string (procedure)
`(cppflags)` ---> string (procedure)
`(ldflags)` ---> string (procedure)

> The values returned by these procedures correspond to the values `make` used to compile scsh's C files.

`(compiler-flags)` ---> string (procedure)

> The procedure compiler-flags returns flags suitable for running the C compiler when compiling a C file that uses scsh's foreign function interface.

`(linker-flags)` ---> string (procedure)

> Scsh also comes as a library that can be linked into other programs. The procedure linker-flags returns the appropriate flags to link the scsh library to another program.