Low level Unix interfaces
*************************

The low level Unix interfaces are currently available by default in the Guile top level.  However in the future they will probably be placed in a module and use-modules or something similar will be required to make them available.

Low level Unix conventions
==========================

The low-level interfaces are designed to give Scheme programs access to as much functionality as possible from the underlying Unix system.  They can be used to implement higher level intefaces such as the Scheme shell scsh.

Generally there is a single procedure for each corresponding Unix facility.  However some of the procedures are implemented for speed and convenience in Scheme and have no Unix equivalent (e.g., read-delimited, copy-file.)

This interface is intended as far as possible to be portable across different versions of Unix, so that Scheme programmers don't need to be concerned with implementation differences.  In some cases procedures which can't be implemented (or reimplemented) on particular systems may become no-ops, or perform limited actions.  In other cases they may throw errors.  It should be possible to use the feature system to determine what functionality is available.

General naming conventions are as follows:

  * The Scheme name is often identical to the name of the underlying Unix facility.

  * Underscores in Unix names are converted to hyphens.

  * Procedures which destructively modify Scheme data gain postpended exclaimation marks, e.g., recv!.

  * Predicates are postpended with question marks, e.g., access?.

  * Some names are changed to avoid conflict with dissimilar interfaces defined by scsh.

  * Unix preprocessor names such as EPERM or R_OK are converted to Scheme variables of the same name (underscores are not replaced with hyphens)

Most of the Unix interface procedures can be relied on to return a well-specified value.  Unexpected conditions are handled by raising exceptions.

There are a few procedures which return a special value if they don't succeed, e.g., getenv returns #f if it the requested string is not found in the environment.  These cases will be noted in the documentation.

For ways to deal with exceptions, Exceptions.

Errors which the C-library would report by returning a NULL pointer or through some other means cause a system-error exception to be raised.  The value of the Unix errno variable is available in the data passed by the exception, so there is no need to access the global errno value (doing so would be unreliable in the presence of continuations or multiple threads).

 -- procedure: errno [n]

 -- procedure: perror string

Ports and file descriptors
==========================

 -- procedure: move->fdes port fd

 -- procedure: release-port-handle port

 -- procedure: set-port-revealed! PORT count

 -- procedure: fdes->ports fdes

 -- procedure: fileno port

 -- procedure: fdopen fdes modes

 -- procedure: duplicate-port port modes

 -- procedure: redirect-port into-port from-port

 -- procedure: freopen filename modes port

Extended I/O
============

Extended I/O procedures are available which read or write lines of text, read text delimited by a specified set of characters, or report or set the current position of a port.

Interfaces to read/fread and write/fwrite are also available, as uniform-array-read! and uniform-array-write!, Uniform arrays.

 -- procedure: read-line [port] [handle-delim]
     Return a line of text from PORT if specified, otherwise from the value returned by (current-input-port).  Under Unix, a line of text is terminated by the first end-of-line character or by end-of-file.

     If HANDLE-DELIM is specified, it should be one of the following symbols:

     trim
          Discard the terminating delimiter.  This is the default, but it will be impossible to tell whether the read terminated with a delimiter or end-of-file.

     concat
          Append the terminating delimiter (if any) to the returned string.

     peek
          Push the terminating delimiter (if any) back on to the port.

     split
          Return a pair containing the string read from the port and the terminating delimiter or end-of-file object.

          NOTE: if the scsh module is loaded then multiple values are returned instead of a pair.

 -- procedure: read-line! buf [port]
     Read a line of text into the supplied string BUF and return the number of characters added to BUF.  If BUF is filled, then #f is returned. Read from PORT if specified, otherwise from the value returned by (current-input-port).

 -- procedure: read-delimited delims [port] [handle-delim]
     Read text until one of the characters in the string DELIMS is found or end-of-file is reached.  Read from PORT if supplied, otherwise from the value returned by (current-input-port). HANDLE-DELIM takes the same values as described for read-line.

     NOTE: if the scsh module is loaded then DELIMS must be an scsh char-set, not a string.

 -- procedure: read-delimited! delims buf [port] [handle-delim] [start] [end]
     Read text into the supplied string BUF and return the number of characters added to BUF (subject to HANDLE-DELIM, which takes the same values specified for read-line.  If BUF is filled, #f is returned for both the number of characters read and the delimiter.  Also terminates if one of the characters in the string DELIMS is found or end-of-file is reached.  Read from PORT if supplied, otherwise from the value returned by (current-input-port).

     NOTE: if the scsh module is loaded then DELIMS must be an scsh char-set, not a string.

 -- procedure: write-line obj [port]
     Display OBJ and a new-line character to PORT if specified, otherwise to the value returned by (current-output-port); equivalent to:

          (display obj [port])
          (newline [port])

 -- procedure: ftell port
     Returns an integer representing the current position of PORT, measured from the beginning.

 -- procedure: fseek port offset whence
     Sets the current position of PORT to the integer OFFSET, which is interpreted according to the value of WHENCE.

     One of the following variables should be supplied for WHENCE:
      -- Variable: SEEK_SET
          Seek from the beginning of the file.

      -- Variable: SEEK_CUR
          Seek from the current position.

      -- Variable: SEEK_END
          Seek from the end of the file.

File system
===========

These procedures query and set file system attributes (such as owner, permissions, sizes and types of files); deleting, copying, renaming and linking files; creating and removing directories and querying their contents; and the sync interface.

 -- procedure: access? path how
     Evaluates to #t if PATH corresponds to an existing file and the current process has the type of access specified by HOW, otherwise #f. HOW should be specified using the values of the variables listed below.  Multiple values can be combined using a bitwise or, in which case #t will only be returned if all accesses are granted.

     Permissions are checked using the real id of the current process, not the effective id, although it's the effective id which determines whether the access would actually be granted.

      -- Variable: R_OK
          test for read permission.

      -- Variable: W_OK
          test for write permission.

      -- Variable: X_OK
          test for execute permission.

      -- Variable: F_OK
          test for existence of the file.

 -- procedure: stat obj
     Evaluates to an object containing various information about the file determined by OBJ. OBJ can be a string containing a file name or a port or file descriptor which is open on a file (in which case fstat is used as the underlying system call).

     The object returned by stat can be passed as a single parameter to the following procedures, all of which return integers:

     stat:dev
          The device containing the file.

     stat:ino
          The file serial number, which distinguishes this file from all other files on the same device.

     stat:mode
          The mode of the file.  This includes file type information and the file permission bits.  See stat:type and stat:perms below.

     stat:nlink
          The number of hard links to the file.

     stat:uid
          The user ID of the file's owner.

     stat:gid
          The group ID of the file.

     stat:rdev
          Device ID; this entry is defined only for character or block special files.

     stat:size
          The size of a regular file in bytes.

     stat:atime
          The last access time for the file.

     stat:mtime
          The last modification time for the file.

     stat:ctime
          The last modification time for the attributes of the file.

     stat:blksize
          The optimal block size for reading or writing the file, in bytes.

     stat:blocks
          The amount of disk space that the file occupies measured in units of 512 byte blocks.

     In addition, the following procedures return the information from stat:mode in a more convenient form:

     stat:type
          A symbol representing the type of file.  Possible values are currently: regular, directory, symlink, block-special, char-special, fifo, socket, unknown

     stat:perms
          An integer representing the access permission bits.

 -- procedure: lstat path
     Similar to stat, but does not follow symbolic links, i.e., it will return information about a symbolic link itself, not the file it points to.  PATH must be a string.

 -- procedure: readlink path

 -- procedure: chown path owner group

 -- procedure: chmod port-or-path mode

 -- procedure: utime path [actime] [modtime]

 -- procedure: delete-file path

 -- procedure: copy-file path-from path-to

 -- procedure: rename-file path-from path-to

 -- procedure: link path-from path-to

 -- procedure: symlink path-from path-to

 -- procedure: mkdir path [mode]

 -- procedure: rmdir path

 -- procedure: opendir path

 -- procedure: readdir port

 -- procedure: rewinddir port

 -- procedure: closedir port

 -- procedure: sync

User database
=============

 -- procedure: getpwuid uid

 -- procedure: getpwnam name

 -- procedure: getpwent

 -- procedure: setpwent port

 -- procedure: endpwent

 -- procedure: getgrgid uid

 -- procedure: getgrnam name

 -- procedure: getgrent

 -- procedure: setgrent port

 -- procedure: endgrent

Processes
=========

 -- procedure: chdir path

 -- procedure: getcwd

 -- procedure: umask [mode]

 -- procedure: getpid

 -- procedure: getgroups

 -- procedure: kill pid sig

     SIG should be specified using a variable corresponding to the Unix symbolic name, e.g,
      -- Variable: SIGHUP
          Hang-up signal.

      -- Variable: SIGINT
          Interrupt signal.

 -- procedure: waitpid pid options
      -- Variable: WAIT_ANY

      -- Variable: WAIT_MYPGRP

      -- Variable: WNOHANG

      -- Variable: WUNTRACED

 -- procedure: getppid

 -- procedure: getuid

 -- procedure: getgid

 -- procedure: geteuid

 -- procedure: getegid

 -- procedure: setuid id

 -- procedure: setgid id

 -- procedure: seteuid id

 -- procedure: setegid id

 -- procedure: getpgrp

 -- procedure: setpgid pid pgid

 -- procedure: setsid

 -- procedure: execl arg ...

 -- procedure: execlp arg ...

 -- procedure: primitive-fork

 -- procedure: environ [env]

 -- procedure: putenv string

 -- procedure: nice incr

Terminals and pseudo-terminals
==============================

 -- procedure: isatty? port

 -- procedure: ttyname port

 -- procedure: ctermid

 -- procedure: tcgetpgrp port

 -- procedure: tcsetpgrp port pgid

Network address conversion and system databases
===============================================

 -- procedure: inet-aton address

 -- procedure: inet-ntoa number

 -- procedure: inet-netof address

 -- procedure: inet-lnaof address

 -- procedure: inet-makeaddr net lna

 -- procedure: gethostbyname name

 -- procedure: gethostbyaddr address

 -- procedure: gethostent

 -- procedure: sethostent port

 -- procedure: endhostent

 -- procedure: getnetbyname name

 -- procedure: getnetbyaddr address

 -- procedure: getnetent

 -- procedure: setnetent port

 -- procedure: endnetent

 -- procedure: getprotobyname name

 -- procedure: getprotobynumber number

 -- procedure: getprotoent

 -- procedure: setprotoent port

 -- procedure: endprotoent

 -- procedure: getservbyname name protocol

 -- procedure: getservbyport port protocol

 -- procedure: getservent

 -- procedure: setservent port

 -- procedure: endservent

BSD socket library interface
============================

 -- procedure: socket family style protocol

 -- procedure: socketpair family style protocol

 -- procedure: getsockopt socket level optname

 -- procedure: setsockopt socket level optname value

 -- procedure: shutdown socket how

 -- procedure: connect socket family address arg ...

 -- procedure: bind socket family address arg ...

 -- procedure: listen socket backlog

 -- procedure: accept socket

 -- procedure: getsockname socket

 -- procedure: getpeername socket

 -- procedure: recv! socket buf [flags]

 -- procedure: send socket message [flags]

 -- procedure: recvfrom! socket buf [flags] [start] [end]

 -- procedure: sendto socket message family address args ... [flags]

Miscellaneous Unix interfaces
=============================

Things which haven't been classified elsewhere (yet?).

 -- procedure: open path flags [mode]
      -- Variable: O_RDONLY

      -- Variable: O_WRONLY

      -- Variable: O_RDWR

      -- Variable: O_CREAT

      -- Variable: O_EXCL

      -- Variable: O_NOCTTY

      -- Variable: O_TRUNC

      -- Variable: O_APPEND

      -- Variable: O_NONBLOCK

      -- Variable: O_NDELAY

      -- Variable: O_SYNC

 -- procedure: select reads writes excepts secs msecs

 -- procedure: uname

 -- procedure: pipe

 -- procedure: open-pipe command modes

 -- procedure: open-input-pipe command

 -- procedure: open-output-pipe command

 -- procedure: setlocale category [locale]
      -- Variable: LC_COLLATE

      -- Variable: LC_CTYPE

      -- Variable: LC_MONETARY

      -- Variable: LC_NUMERIC

      -- Variable: LC_TIME

      -- Variable: LC_MESSAGES

      -- Variable: LC_ALL

 -- procedure: strftime format stime

 -- procedure: strptime format string

 -- procedure: mknod

The Scheme shell (scsh)
***********************

Guile includes an incomplete port of the Scheme shell (scsh) 0.4.4.

For information about scsh on the Web see http://www-swiss.ai.mit.edu/scsh/scsh.html. The original scsh is available by ftp from ftp://swiss-ftp.ai.mit.edu:/pub/su.

This port of scsh does not currently use the Guile module system, but can be initialized using:

     (load-from-path "scsh/init")

Note that SLIB must be installed before scsh can be initialized, see SLIB for details.

Programming Threads.
********************