guile/guile-doc/ref posix.texi

[Neil Jerram]

CVSROOT:        /cvs
Module name:    guile
Changes by:     Neil Jerram <address@hidden>    00/09/22 05:02:58

Modified files:
        guile-doc/ref  : posix.texi 

Log message:
        * Lots more docstring comments added, and docs synchronized with
        versions from libguile source.

CVSWeb URLs:
http://subversions.gnu.org/cgi-bin/cvsweb/guile/guile-doc/ref/posix.texi.diff?r1=1.13&r2=1.14

Patches:
Index: guile/guile-doc/ref/posix.texi
diff -u guile/guile-doc/ref/posix.texi:1.13 guile/guile-doc/ref/posix.texi:1.14
--- guile/guile-doc/ref/posix.texi:1.13 Fri Aug 18 10:09:50 2000
+++ guile/guile-doc/ref/posix.texi      Fri Sep 22 05:02:58 2000
@@ -150,13 +150,17 @@
 in its garbage collection: it could be retrieved with fdopen or
 fdes->ports.
 
address@hidden docstring begin (c-doc-string "ports.c" "port-revealed")
address@hidden docstring md5 "1b7c38c06c8f072cdafa2710b72f7f3b"
 @deffn primitive port-revealed port
 Returns the revealed count for @var{port}.
 @end deffn
 
address@hidden primitive set-port-revealed! port count
-Sets the revealed count for a port to a given value.  The return value
-is unspecified.
address@hidden docstring begin (c-doc-string "ports.c" "set-port-revealed!")
address@hidden docstring md5 "84596c3911799dc63419755ab4a79901"
address@hidden primitive set-port-revealed! port rcount
+Sets the revealed count for a port to a given value.
+The return value is unspecified.
 @end deffn
 
 @c docstring begin (c-doc-string "ioext.c" "fileno")
@@ -280,6 +284,7 @@
 their revealed counts set to zero.
 @end deffn
 
address@hidden docstring begin (c-doc-string "ports.c" "unread-char")
 @deffn primitive unread-char char [port]
 Place @var{char} in @var{port} so that it will be read by the
 next read operation.  If called multiple times, the unread characters
@@ -287,6 +292,7 @@
 not supplied, the current input port is used.
 @end deffn
 
address@hidden docstring begin (c-doc-string "ports.c" "unread-string")
 @deffn primitive unread-string str [port]
 Place the string @var{str} in @var{port} so that its characters will be
 read in subsequent read operations.  If called multiple times, the
@@ -294,14 +300,23 @@
 @var{port} is not supplied, the current-input-port is used.
 @end deffn
 
address@hidden docstring begin (c-doc-string "posix.c" "pipe")
address@hidden docstring md5 "b21d64a66a4e2c47fece645b9828d479"
 @deffn primitive pipe
-Creates a pipe which can be used for communication.  The return value
-is a pair in which the CAR contains an input port and the CDR an
-output port.  Data written to the output port can be read from the
-input port.  Note that both ports are buffered so it may be necessary
-to flush the output port before data will actually be sent across the pipe.
-Alternatively a buffer can be added to the port using @code{setvbuf}
-(see below).
+Returns a newly created pipe: a pair of ports which are linked
+together on the local machine.  The CAR is the input port and
+the CDR is the output port.  Data written (and flushed) to the
+output port can be read from the input port.
+Pipes are commonly used for communication with a newly
+forked child process.  The need to flush the output port
+can be avoided by making it unbuffered using @code{setvbuf}.
+
+Writes occur atomically provided the size of the data in
+bytes is not greater than the value of @code{PIPE_BUF}
+Note that the output port is likely to block if too much data
+(typically equal to @code{PIPE_BUF}) has been written but not
+yet read from the input port
+
 @end deffn
 
 The next group of procedures perform a @code{dup2}
@@ -370,6 +385,8 @@
 revealed counts.
 @end deffn
 
address@hidden docstring begin (c-doc-string "ports.c" "port-mode")
address@hidden docstring md5 "cbcb46422ab6eb230fd54bb014026d79"
 @deffn primitive port-mode port
 Returns the port modes associated with the open port @var{port}.  These
 will not necessarily be identical to the modes used when the port was
@@ -377,13 +394,17 @@
 port creation are not retained.
 @end deffn
 
address@hidden primitive close-all-ports-except port @dots{}
address@hidden docstring begin (c-doc-string "ports.c" "close-all-ports-except")
address@hidden docstring md5 "cc236f9737a0e718d33eb00106cd33f9"
address@hidden primitive close-all-ports-except . ports
 Close all open file ports used by the interpreter
 except for those supplied as arguments.  This procedure
 is intended to be used before an exec call to close file descriptors
 which are not needed in the new process.
 @end deffn
 
address@hidden docstring begin (c-doc-string "fports.c" "setvbuf")
address@hidden docstring md5 "5395a53e279959cd6b364a3411887c0b"
 @deffn primitive setvbuf port mode [size]
 Set the buffering mode for @var{port}.  @var{mode} can be:
 @table @code
@@ -471,6 +492,8 @@
 linking files; creating and removing directories and querying their
 contents; syncing the file system and creating special files.
 
address@hidden docstring begin (c-doc-string "posix.c" "access?")
address@hidden docstring md5 "fec352f04f8b19b3630c323ba6335b50"
 @deffn primitive access? path how
 Returns @code{#t} if @var{path} corresponds to an existing
 file and the current process
@@ -607,7 +630,9 @@
 The return value is unspecified.
 @end deffn
 
address@hidden primitive utime path [actime] [modtime]
address@hidden docstring begin (c-doc-string "posix.c" "utime")
address@hidden docstring md5 "a597b09b22a3bc59ca04020d6bb400a1"
address@hidden primitive utime pathname [actime [modtime]]
 @code{utime} sets the access and modification times for
 the file named by @var{path}.  If @var{actime} or @var{modtime}
 is not supplied, then the current time is used.
@@ -714,11 +739,15 @@
 The return value is unspecified.
 @end deffn
 
address@hidden docstring begin (c-doc-string "posix.c" "sync")
address@hidden docstring md5 "809c00c0d6bb882356fbbaf6dd0ac9ac"
 @deffn primitive sync
 Flush the operating system disk buffers.
 The return value is unspecified.
 @end deffn
 
address@hidden docstring begin (c-doc-string "posix.c" "mknod")
address@hidden docstring md5 "37bb82ebe81454e550e191712db6cc1d"
 @deffn primitive mknod path type perms dev
 Creates a new special file, such as a file corresponding to a device.
 @var{path} specifies the name of the file.  @var{type} should
@@ -737,6 +766,8 @@
 The return value is unspecified.
 @end deffn
 
address@hidden docstring begin (c-doc-string "posix.c" "tmpnam")
address@hidden docstring md5 "3bdd82c1272c895eec4c85721803e3a4"
 @deffn primitive tmpnam
 Create a new file in the file system with a unique name.  The return
 value is the name of the new file.  This function is implemented with
@@ -806,13 +837,17 @@
 Closes the stream used by @code{getpwent}.  The return value is unspecified.
 @end deffn
 
address@hidden primitive setpw [reset?]
address@hidden docstring begin (c-doc-string "posix.c" "setpw")
address@hidden docstring md5 "f39c63ddaf54069d21088cde473078ee"
address@hidden primitive setpw [arg]
 If called with a true argument, initialize or reset the password data
 stream.  Otherwise, close the stream.  The @code{setpwent} and
 @code{endpwent} procedures are implemented on top of this.
 @end deffn
 
address@hidden primitive getpw [obj]
address@hidden docstring begin (c-doc-string "posix.c" "getpw")
address@hidden docstring md5 "d05295a6037f032998eb0c4927943258"
address@hidden primitive getpw [user]
 Look up an entry in the user database.  @var{obj} can be an integer,
 a string, or omitted, giving the behaviour of getpwuid, getpwnam
 or getpwent respectively.
@@ -856,13 +891,17 @@
 The return value is unspecified.
 @end deffn
 
address@hidden primitive setgr [reset?]
address@hidden docstring begin (c-doc-string "posix.c" "setgr")
address@hidden docstring md5 "c6e15cd397d2ca16aadcb82a424d1237"
address@hidden primitive setgr [arg]
 If called with a true argument, initialize or reset the group data
 stream.  Otherwise, close the stream.  The @code{setgrent} and
 @code{endgrent} procedures are implemented on top of this.
 @end deffn
 
address@hidden primitive getgr [obj]
address@hidden docstring begin (c-doc-string "posix.c" "getgr")
address@hidden docstring md5 "19d002f8bf8c9b053e5b627ef0c0c12f"
address@hidden primitive getgr [name]
 Look up an entry in the group database.  @var{obj} can be an integer,
 a string, or omitted, giving the behaviour of getgrgid, getgrnam
 or getgrent respectively.
@@ -871,11 +910,15 @@
 @node Time
 @section Time
 
address@hidden docstring begin (c-doc-string "stime.c" "current-time")
address@hidden docstring md5 "76ada7f61352b11add7ccf27e827c00e"
 @deffn primitive current-time
 Returns the number of seconds since 1970-01-01 00:00:00 UTC, excluding
 leap seconds.
 @end deffn
 
address@hidden docstring begin (c-doc-string "stime.c" "gettimeofday")
address@hidden docstring md5 "6173388c8f5f06a9e6e617b7fbff8b06"
 @deffn primitive gettimeofday
 Returns a pair containing the number of seconds and microseconds since
 1970-01-01 00:00:00 UTC, excluding leap seconds.  Note: whether true
@@ -913,6 +956,8 @@
 Time zone label (a string), not necessarily unique.
 @end table
 
address@hidden docstring begin (c-doc-string "stime.c" "localtime")
address@hidden docstring md5 "2cd2c36738ad96121f1fd05b02a5f6c8"
 @deffn primitive localtime time [zone]
 Returns an object representing the broken down components of @var{time},
 an integer like the one returned by @code{current-time}.  The time zone
@@ -921,13 +966,17 @@
 used.
 @end deffn
 
address@hidden docstring begin (c-doc-string "stime.c" "gmtime")
address@hidden docstring md5 "b2cc512c9fdda6b204c6e69faa51696d"
 @deffn primitive gmtime time
 Returns an object representing the broken down components of @var{time},
 an integer like the one returned by @code{current-time}.  The values
 are calculated for UTC.
 @end deffn
 
address@hidden primitive mktime bd-time [zone]
address@hidden docstring begin (c-doc-string "stime.c" "mktime")
address@hidden docstring md5 "b0a52e1fa300c648f6d42c3fc5a9741a"
address@hidden primitive mktime sbd_time [zone]
 @var{bd-time} is an object representing broken down time and @code{zone}
 is an optional time zone specifier (otherwise the TZ environment variable
 or the system default is used).
@@ -938,14 +987,18 @@
 as @var{bd-time} but with normalized values.
 @end deffn
 
address@hidden docstring begin (c-doc-string "stime.c" "tzset")
address@hidden docstring md5 "19a4fe747252c8d6acd0bd77966b1caa"
 @deffn primitive tzset
-Initialize the timezone from the TZ environment variable or the system
-default.  Usually this is done automatically by other procedures which
-use the time zone, but this procedure may need to be used if TZ
-is changed.
+Initialize the timezone from the TZ environment variable
+or the system default.  It's not usually necessary to call this procedure
+since it's done automatically by other procedures that depend on the
+timezone.
 @end deffn
 
address@hidden primitive strftime template time
address@hidden docstring begin (c-doc-string "stime.c" "strftime")
address@hidden docstring md5 "d48f88a920766a67d4c189d73c0b69be"
address@hidden primitive strftime format stime
 Formats a time specification @var{time} using @var{template}.  @var{time}
 is an object with time components in the form returned by @code{localtime}
 or @code{gmtime}.  @var{template} is a string which can include formatting
@@ -955,7 +1008,9 @@
 @xref{Formatting Date and Time, , , libc, The GNU C Library Reference Manual}.)
 @end deffn
 
address@hidden primitive strptime template string
address@hidden docstring begin (c-doc-string "stime.c" "strptime")
address@hidden docstring md5 "661008b711878fa53539faa1a029642a"
address@hidden primitive strptime format string
 Performs the reverse action to @code{strftime}, parsing @var{string}
 according to the specification supplied in @var{template}.  The
 interpretation of month and day names is dependent on the current
@@ -973,6 +1028,8 @@
 reported by the following procedures.
 @end defvar
 
address@hidden docstring begin (c-doc-string "stime.c" "times")
address@hidden docstring md5 "b0aa01e543a9c263ece37ca05f7f84df"
 @deffn primitive times
 Returns an object with information about real and processor time.
 The following procedures accept such an object as an argument and
@@ -995,14 +1052,17 @@
 @end table
 @end deffn
 
address@hidden docstring begin (c-doc-string "stime.c" "get-internal-real-time")
address@hidden docstring md5 "4f434d8279713973fdf950a0e18ce2d7"
 @deffn primitive get-internal-real-time
 Returns the number of time units since the interpreter was started.
 @end deffn
 
address@hidden docstring begin (c-doc-string "stime.c" "get-internal-run-time")
address@hidden docstring md5 "2c97d4f310b90b5801d9174cc04b7a17"
 @deffn primitive get-internal-run-time
 Returns the number of time units of processor time used by the interpreter.
-Both "system" and "user" time
-are included but subprocesses are not.
+Both "system" and "user" time are included but subprocesses are not.
 @end deffn
 
 @node Runtime Environment
@@ -1095,26 +1155,38 @@
 E.g., @code{(umask #o022)} sets the mask to octal 22, decimal 18.
 @end deffn
 
address@hidden docstring begin (c-doc-string "posix.c" "getpid")
address@hidden docstring md5 "d64b0376645a2061be247c643f452cb9"
 @deffn primitive getpid
 Returns an integer representing the current process ID.
 @end deffn
 
address@hidden docstring begin (c-doc-string "posix.c" "getgroups")
address@hidden docstring md5 "d89f8836ad2d17963495d668c764a73f"
 @deffn primitive getgroups
 Returns a vector of integers representing the current supplimentary group IDs.
 @end deffn
 
address@hidden docstring begin (c-doc-string "posix.c" "getppid")
address@hidden docstring md5 "0cdc7ef0d2c250329872db2b7098231f"
 @deffn primitive getppid
 Returns an integer representing the process ID of the parent process.
 @end deffn
 
address@hidden docstring begin (c-doc-string "posix.c" "getuid")
address@hidden docstring md5 "628a0e80108003152f3d376c5ab3eaac"
 @deffn primitive getuid
 Returns an integer representing the current real user ID.
 @end deffn
 
address@hidden docstring begin (c-doc-string "posix.c" "getgid")
address@hidden docstring md5 "45faad2fa3e5db9f71132fa04d33402f"
 @deffn primitive getgid
 Returns an integer representing the current real group ID.
 @end deffn
 
address@hidden docstring begin (c-doc-string "posix.c" "geteuid")
address@hidden docstring md5 "87092a4dd6a394ace63c9295c19ab843"
 @deffn primitive geteuid
 Returns an integer representing the current effective user ID.
 If the system does not support effective IDs, then the real ID
@@ -1122,6 +1194,8 @@
 supports effective IDs.
 @end deffn
 
address@hidden docstring begin (c-doc-string "posix.c" "getegid")
address@hidden docstring md5 "bfc32b3275906666e8811e76bdf99cad"
 @deffn primitive getegid
 Returns an integer representing the current effective group ID.
 If the system does not support effective IDs, then the real ID
@@ -1129,18 +1203,24 @@
 supports effective IDs.
 @end deffn
 
address@hidden docstring begin (c-doc-string "posix.c" "setuid")
address@hidden docstring md5 "fa6f3d61ce1397155d101c2069b171c0"
 @deffn primitive setuid id
 Sets both the real and effective user IDs to the integer @var{id}, provided
 the process has appropriate privileges.
 The return value is unspecified.
 @end deffn
 
address@hidden docstring begin (c-doc-string "posix.c" "setgid")
address@hidden docstring md5 "316a8122112a57369ab9d61729428743"
 @deffn primitive setgid id
 Sets both the real and effective group IDs to the integer @var{id}, provided
 the process has appropriate privileges.
 The return value is unspecified.
 @end deffn
 
address@hidden docstring begin (c-doc-string "posix.c" "seteuid")
address@hidden docstring md5 "60e9495314eb531c1829fac934f3ad3c"
 @deffn primitive seteuid id
 Sets the effective user ID to the integer @var{id}, provided the process
 has appropriate privileges.  If effective IDs are not supported, the
@@ -1149,6 +1229,8 @@
 The return value is unspecified.
 @end deffn
 
address@hidden docstring begin (c-doc-string "posix.c" "setegid")
address@hidden docstring md5 "8b73eeb128697b61a76866128ba57210"
 @deffn primitive setegid id
 Sets the effective group ID to the integer @var{id}, provided the process
 has appropriate privileges.  If effective IDs are not supported, the
@@ -1157,11 +1239,15 @@
 The return value is unspecified.
 @end deffn
 
address@hidden docstring begin (c-doc-string "posix.c" "getpgrp")
address@hidden docstring md5 "8c78e5e22c15d0826c9faf29b1019877"
 @deffn primitive getpgrp
 Returns an integer representing the current process group ID.
 This is the POSIX definition, not BSD.
 @end deffn
 
address@hidden docstring begin (c-doc-string "posix.c" "setpgid")
address@hidden docstring md5 "b554c02ee5a2eb9dbacd35ff8213e54f"
 @deffn primitive setpgid pid pgid
 Move the process @var{pid} into the process group @var{pgid}.  @var{pid} or
 @var{pgid} must be integers: they can be zero to indicate the ID of the
@@ -1170,6 +1256,8 @@
 The return value is unspecified.
 @end deffn
 
address@hidden docstring begin (c-doc-string "posix.c" "setsid")
address@hidden docstring md5 "0d7a41500edeeb36881d9a1dc9859d58"
 @deffn primitive 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
@@ -1177,6 +1265,8 @@
 The return value is an integer representing the new process group ID.
 @end deffn
 
address@hidden docstring begin (c-doc-string "posix.c" "waitpid")
address@hidden docstring md5 "7d85e72e16d275d85603b5411271f980"
 @deffn primitive waitpid pid [options]
 This procedure collects status information from a child process which
 has terminated or (optionally) stopped.  Normally it will
@@ -1225,22 +1315,30 @@
 functions can be used to decode the process status code returned
 by @code{waitpid}.
 
address@hidden docstring begin (c-doc-string "posix.c" "status:exit-val")
address@hidden docstring md5 "df18364eb12231a4a0c93b295c630082"
 @deffn primitive status:exit-val status
 Returns the exit status value, as would be
 set if a process ended normally through a
 call to @code{exit} or @code{_exit}, if any, otherwise @code{#f}.
 @end deffn
 
address@hidden docstring begin (c-doc-string "posix.c" "status:term-sig")
address@hidden docstring md5 "7f91f18c1c62586bb4f034f42efaffae"
 @deffn primitive status:term-sig status
 Returns the signal number which terminated the
 process, if any, otherwise @code{#f}.
 @end deffn
 
address@hidden docstring begin (c-doc-string "posix.c" "status:stop-sig")
address@hidden docstring md5 "633f8a62bb90a33cf87cd00930645733"
 @deffn primitive status:stop-sig status
 Returns the signal number which stopped the
 process, if any, otherwise @code{#f}.
 @end deffn
 
address@hidden docstring begin (c-doc-string "simpos.c" "system")
address@hidden docstring md5 "7c50840a0247c0bbfc1ac441f86a00c2"
 @deffn primitive system [cmd]
 Executes @var{cmd} using the operating system's "command processor".
 Under Unix this is usually the default shell @code{sh}.  The value
@@ -1251,13 +1349,17 @@
 indicating whether the command processor is available.
 @end deffn
 
address@hidden docstring begin (c-doc-string "simpos.c" "primitive-exit")
address@hidden docstring md5 "57f4d6971bfc4b6ca0a9df4fc2c00d25"
 @deffn primitive primitive-exit [status]
 Terminate the current process without unwinding the Scheme stack.
 This is would typically be useful after a fork.  The exit status
 is @var{status} if supplied, otherwise zero.
 @end deffn
 
address@hidden primitive execl path [arg] ...
address@hidden docstring begin (c-doc-string "posix.c" "execl")
address@hidden docstring md5 "cd0d489078f789de94be773713ecb674"
address@hidden primitive execl filename . args
 Executes the file named by @var{path} as a new process image.
 The remaining arguments are supplied to the process; from a C program
 they are accessable as the @code{argv} argument to @code{main}.
@@ -1271,17 +1373,21 @@
 call, but we call it @code{execl} because of its Scheme calling interface.
 @end deffn
 
address@hidden primitive execlp path [arg] ...
address@hidden docstring begin (c-doc-string "posix.c" "execlp")
address@hidden docstring md5 "c3f02c5d2a9269ce276001169c94655e"
address@hidden primitive execlp filename . args
 Similar to @code{execl}, however if
 @var{filename} does not contain a slash
 then the file to execute will be located by searching the
 directories listed in the @code{PATH} environment variable.
 
-This procedure is currently implemented using the @code{execlv} system
+This procedure is currently implemented using the @code{execvp} system
 call, but we call it @code{execlp} because of its Scheme calling interface.
 @end deffn
 
address@hidden primitive execle path env [arg] ...
address@hidden docstring begin (c-doc-string "posix.c" "execle")
address@hidden docstring md5 "d10c587e80f8ee6cff0592fbceeec910"
address@hidden primitive execle filename env . args
 Similar to @code{execl}, but the environment of the new process is
 specified by @var{env}, which must be a list of strings as returned by the
 @code{environ} procedure.
@@ -1290,6 +1396,8 @@
 call, but we call it @code{execle} because of its Scheme calling interface.
 @end deffn
 
address@hidden docstring begin (c-doc-string "posix.c" "primitive-fork")
address@hidden docstring md5 "eabfa452559e1470c613e80264e7044a"
 @deffn primitive primitive-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
@@ -1299,6 +1407,8 @@
 with the scsh fork.
 @end deffn
 
address@hidden docstring begin (c-doc-string "posix.c" "nice")
address@hidden docstring md5 "51b6f142ac4d280e5202794c5833cce3"
 @deffn primitive nice incr
 Increment the priority of the current process by @var{incr}.  A higher
 priority value means that the process runs less often.
@@ -1310,8 +1420,9 @@
 
 Procedures to raise, handle and wait for signals.
 
address@hidden docstring begin (c-doc-string "posix.c" "kill")
address@hidden docstring md5 "89234a82ee49845eeb05e34ce0f3de1d"
 @deffn primitive kill pid sig
-
 Sends a signal to the specified process or group of processes.
 
 @var{pid} specifies the processes to which the signal is sent:
@@ -1341,15 +1452,18 @@
 @end defvar
 @end deffn
 
address@hidden docstring begin (c-doc-string "scmsigs.c" "raise")
address@hidden docstring md5 "34d64fd2e6c30628d87f1fbfe95529ba"
 @deffn primitive raise sig
 
 Sends a specified signal @var{sig} to the current process, where
 @var{sig} is as described for the kill procedure.
 @end deffn
-
address@hidden primitive sigaction signum [action] [flags]
 
-Install or report the signal hander for a specified signal.
address@hidden docstring begin (c-doc-string "scmsigs.c" "sigaction")
address@hidden docstring md5 "711e4020d3560c464f4d7389fd5a192b"
address@hidden primitive sigaction signum [handler [flags]]
+Install or report the signal handler for a specified signal.
 
 @var{signum} is the signal number, which can be specified using the value
 of variables such as @code{SIGINT}.
@@ -1367,7 +1481,7 @@
 @code{SIG_IGN} (ignore), or @code{#f} to restore whatever signal handler
 was installed before @code{sigaction} was first used.  Flags can
 optionally be specified for the new handler (@code{SA_RESTART} will
-always be added if it's available and the system is using rstartable
+always be added if it's available and the system is using restartable
 system calls.)  The return value is a pair with information about the
 old handler as described above.
 
@@ -1377,12 +1491,16 @@
 structures.
 @end deffn
 
address@hidden docstring begin (c-doc-string "scmsigs.c" "restore-signals")
address@hidden docstring md5 "eddce6d08083df8e1b1e1db2085990a1"
 @deffn primitive restore-signals
 Return all signal handlers to the values they had before any call to
 @code{sigaction} was made.  The return value is unspecified.
 @end deffn
 
address@hidden primitive alarm secs
address@hidden docstring begin (c-doc-string "scmsigs.c" "alarm")
address@hidden docstring md5 "fb201fc65cdf59655d3e9fe4d56f5413"
address@hidden primitive alarm i
 Set a timer to raise a @code{SIGALRM} signal after the specified
 number of seconds (an integer).  It's advisable to install a signal
 handler for
@@ -1394,18 +1512,28 @@
 no previous alarm, the return value is zero.
 @end deffn
 
address@hidden docstring begin (c-doc-string "scmsigs.c" "pause")
address@hidden docstring md5 "e7a27b324a4e166e8106ab72e3bf76d2"
 @deffn primitive pause
 Pause the current process (thread?) until a signal arrives whose
 action is to either terminate the current process or invoke a
 handler procedure.  The return value is unspecified.
 @end deffn
 
address@hidden primitive sleep secs
address@hidden docstring begin (c-doc-string "scmsigs.c" "sleep")
address@hidden docstring md5 "29a83fb23c767777af8c568af52986f0"
address@hidden primitive sleep i
 Wait for the given number of seconds (an integer) or until a signal
 arrives.  The return value is zero if the time elapses or the number
 of seconds remaining otherwise.
 @end deffn
 
address@hidden docstring begin (c-doc-string "scmsigs.c" "usleep")
address@hidden docstring md5 "b14fae046cbe4af8d61e44ef4b6c17b1"
address@hidden primitive usleep i
+Sleep for I microseconds.
+`usleep' is not available on all platforms.
address@hidden deffn
 
 @node Terminals and Ptys
 @section Terminals and Ptys
@@ -1417,16 +1545,22 @@
 non-file device, otherwise @code{#f}.
 @end deffn
 
address@hidden docstring begin (c-doc-string "posix.c" "ttyname")
address@hidden docstring md5 "769ec94e0f90139be8922437146e3709"
 @deffn primitive ttyname port
 Returns a string with the name of the serial terminal device underlying
 @var{port}.
 @end deffn
 
address@hidden docstring begin (c-doc-string "posix.c" "ctermid")
address@hidden docstring md5 "3fd556dfb560cb868465ec099c5d606a"
 @deffn primitive ctermid
 Returns a string containing the file name of the controlling terminal
 for the current process.
 @end deffn
 
address@hidden docstring begin (c-doc-string "posix.c" "tcgetpgrp")
address@hidden docstring md5 "dbcc77abaa96c964be12da405c8dabb3"
 @deffn primitive tcgetpgrp port
 Returns the process group ID of the foreground
 process group associated with the terminal open on the file descriptor
@@ -1440,6 +1574,8 @@
 foreground.
 @end deffn
 
address@hidden docstring begin (c-doc-string "posix.c" "tcsetpgrp")
address@hidden docstring md5 "c09a1fa2ae2242c5c52aa775c98a7e60"
 @deffn primitive tcsetpgrp port pgid
 Set the foreground process group ID for the terminal used by the file
 descriptor underlying @var{port} to the integer @var{pgid}.
@@ -1460,7 +1596,7 @@
 @end smalllisp
 
 @findex popen
address@hidden primitive open-pipe command modes
address@hidden procedure open-pipe command modes
 Executes the shell command @var{command} (a string) in a subprocess.
 A pipe to the process is created and returned.  @var{modes} specifies
 whether an input or output pipe to the process is created: it should 
@@ -1476,7 +1612,7 @@
 @end deffn
 
 @findex pclose
address@hidden primitive close-pipe port
address@hidden procedure close-pipe port
 Closes the pipe created by @code{open-pipe}, then waits for the process
 to terminate and returns its status value, @xref{Processes, waitpid}, for
 information on how to interpret this value.
@@ -1821,7 +1957,9 @@
 this section automatically convert between host and network order when
 required.  The arguments and return values are thus in host order.
 
address@hidden primitive socket family style protocol
address@hidden docstring begin (c-doc-string "socket.c" "socket")
address@hidden docstring md5 "965daf176c8ac254b6cddc4934625264"
address@hidden primitive socket family style proto
 Returns a new socket port of the type specified by @var{family}, @var{style}
 and @var{protocol}.  All three parameters are integers.  Typical values
 for @var{family} are the values of @code{AF_UNIX}
@@ -1836,7 +1974,9 @@
 it has been connected to another socket.
 @end deffn
 
address@hidden primitive socketpair family style protocol
address@hidden docstring begin (c-doc-string "socket.c" "socketpair")
address@hidden docstring md5 "ef9f03e6277e74fe68ea3b9a01a37815"
address@hidden primitive socketpair family style proto
 Returns a pair of connected (but unnamed) socket ports of the type specified
 by @var{family}, @var{style} and @var{protocol}.
 Many systems support only
@@ -1844,7 +1984,9 @@
 the only meaningful value for @var{protocol}.
 @end deffn
 
address@hidden primitive getsockopt socket level optname
address@hidden docstring begin (c-doc-string "socket.c" "getsockopt")
address@hidden docstring md5 "e73f6a51446d47ced30b5e3f749ddc99"
address@hidden primitive getsockopt sock level optname
 Returns the value of a particular socket option for the socket
 port @var{socket}.  @var{level} is an integer code for type of option
 being requested, e.g., @code{SOL_SOCKET} for socket-level options.
@@ -1856,7 +1998,9 @@
 pair of integers.
 @end deffn
 
address@hidden primitive setsockopt socket level optname value
address@hidden docstring begin (c-doc-string "socket.c" "setsockopt")
address@hidden docstring md5 "e84af63ac4248fd180ce5b416d4e94f0"
address@hidden primitive setsockopt sock level optname value
 Sets the value of a particular socket option for the socket
 port @var{socket}.  @var{level} is an integer code for type of option
 being set, e.g., @code{SOL_SOCKET} for socket-level options.
@@ -1870,7 +2014,9 @@
 The return value is unspecified.
 @end deffn
 
address@hidden primitive shutdown socket how
address@hidden docstring begin (c-doc-string "socket.c" "shutdown")
address@hidden docstring md5 "5732740941f750f78f6a8968e0ff2d60"
address@hidden primitive shutdown sock how
 Sockets can be closed simply by using @code{close-port}. The
 @code{shutdown} procedure allows reception or tranmission on a
 connection to be shut down individually, according to the parameter
@@ -1890,7 +2036,9 @@
 The return value is unspecified.
 @end deffn
 
address@hidden primitive connect socket family address [arg ...]
address@hidden docstring begin (c-doc-string "socket.c" "connect")
address@hidden docstring md5 "3bd3faf268d08e8f7c806531ebd831d4"
address@hidden primitive connect sock fam address . args
 Initiates a connection from @var{socket} to the address
 specified by @var{address} and possibly @var{arg @dots{}}.  The format
 required for @var{address}
@@ -1907,7 +2055,9 @@
 The return value is unspecified.
 @end deffn
 
address@hidden primitive bind socket family address arg ...
address@hidden docstring begin (c-doc-string "socket.c" "bind")
address@hidden docstring md5 "79e4fbd1add7b475192c5f9b096ea53e"
address@hidden primitive bind sock fam address . args
 Assigns an address to the socket port @var{socket}.
 Generally this only needs to be done for server sockets,
 so they know where to look for incoming connections.  A socket
@@ -1946,7 +2096,9 @@
 The return value is unspecified.
 @end deffn
 
address@hidden primitive listen socket backlog
address@hidden docstring begin (c-doc-string "socket.c" "listen")
address@hidden docstring md5 "1e6d6047057201e563c89d0249643f12"
address@hidden primitive listen sock backlog
 This procedure enables @var{socket} to accept connection
 requests.  @var{backlog} is an integer specifying
 the maximum length of the queue for pending connections.
@@ -1956,7 +2108,9 @@
 The return value is unspecified.
 @end deffn
 
address@hidden primitive accept socket
address@hidden docstring begin (c-doc-string "socket.c" "accept")
address@hidden docstring md5 "1aefc750ffb6a5bb46d9fa07c06bc740"
address@hidden primitive accept sock
 Accepts a connection on a bound, listening socket @var{socket}.  If there
 are no pending connections in the queue, it waits until
 one is available unless the non-blocking option has been set on the
@@ -1991,20 +2145,26 @@
 number.
 @end table
 
address@hidden primitive getsockname socket
address@hidden docstring begin (c-doc-string "socket.c" "getsockname")
address@hidden docstring md5 "f205624ada648b4497f8152eed3680b7"
address@hidden primitive getsockname sock
 Returns the address of @var{socket}, in the same form as the object
 returned by @code{accept}.  On many systems the address of a socket
 in the @code{AF_FILE} namespace cannot be read.
 @end deffn
 
address@hidden primitive getpeername socket
address@hidden docstring begin (c-doc-string "socket.c" "getpeername")
address@hidden docstring md5 "2bc2e07bdc4aeb7234bcbb9b2c60492c"
address@hidden primitive getpeername sock
 Returns the address of the socket that the socket @var{socket} is connected to,
 in the same form as the object
 returned by @code{accept}.  On many systems the address of a socket
 in the @code{AF_FILE} namespace cannot be read.
 @end deffn
 
address@hidden primitive recv! socket buf [flags]
address@hidden docstring begin (c-doc-string "socket.c" "recv!")
address@hidden docstring md5 "6641b9492d91a8ed93b7a014573f7b7e"
address@hidden primitive recv! sock buf [flags]
 Receives data from the socket port @var{socket}.  @var{socket} must already
 be bound to the address from which data is to be received.
 @var{buf} is a string into which
@@ -2022,7 +2182,9 @@
 any unread buffered port data is ignored.
 @end deffn
 
address@hidden primitive send socket message [flags]
address@hidden docstring begin (c-doc-string "socket.c" "send")
address@hidden docstring md5 "a730daa282f9da71cf70b3e0ace5aad6"
address@hidden primitive send sock message [flags]
 Transmits the string @var{message} on the socket port @var{socket}. 
 @var{socket} must already be bound to a destination address.  The
 value returned is the number of bytes transmitted -- it's possible for
@@ -2034,7 +2196,9 @@
 any unflushed buffered port data is ignored.
 @end deffn
 
address@hidden primitive recvfrom! socket buf [flags] [start] [end]
address@hidden docstring begin (c-doc-string "socket.c" "recvfrom!")
address@hidden docstring md5 "35d7a3685b8e1381fb636ff7f932b435"
address@hidden primitive recvfrom! sock buf [flags [start [end]]]
 Returns data from the socket port @var{socket} and also information about
 where the data was received from.  @var{socket} must already
 be bound to the address from which data is to be received.
@@ -2058,7 +2222,9 @@
 any unread buffered port data is ignored.
 @end deffn
 
address@hidden primitive sendto socket message family address arg ... [flags]
address@hidden docstring begin (c-doc-string "socket.c" "sendto")
address@hidden docstring md5 "b3dd6558686046ac2ddaea96094f42c6"
address@hidden primitive sendto sock message fam address . args_and_flags
 Transmits the string @var{message} on the socket port @var{socket}.  The
 destination address is specified using the @var{family}, @var{address} and
 @var{arg} arguments, in a similar way to the @code{connect}
@@ -2077,25 +2243,33 @@
 this automatically for addresses, the conversion will still need to
 be done when sending or receiving encoded integer data from the network.
 
address@hidden primitive htons value
address@hidden docstring begin (c-doc-string "socket.c" "htons")
address@hidden docstring md5 "4596612c4f4d3efcbc749a99cda1b6c0"
address@hidden primitive htons in
 Returns a new integer from @var{value} by converting from host to
 network order. @var{value} must be within the range of a C unsigned
 short integer.
 @end deffn
 
address@hidden primitive ntohs value
address@hidden docstring begin (c-doc-string "socket.c" "ntohs")
address@hidden docstring md5 "6787f327922baea1a73a92cd8bfb4705"
address@hidden primitive ntohs in
 Returns a new integer from @var{value} by converting from network to
 host order.  @var{value} must be within the range of a C unsigned short
 integer.
 @end deffn
 
address@hidden primitive htonl value
address@hidden docstring begin (c-doc-string "socket.c" "htonl")
address@hidden docstring md5 "7eb14613b521f039a1e3e054b9a375c3"
address@hidden primitive htonl in
 Returns a new integer from @var{value} by converting from host to
 network order. @var{value} must be within the range of a C unsigned
 long integer.
 @end deffn
 
address@hidden primitive ntohl value
address@hidden docstring begin (c-doc-string "socket.c" "ntohl")
address@hidden docstring md5 "e0a3274acc7b73c3f9cc5bda9006b925"
address@hidden primitive ntohl in
 Returns a new integer from @var{value} by converting from network to
 host order. @var{value} must be within the range of a C unsigned
 long integer.
@@ -2120,6 +2294,8 @@
 @node System Identification
 @section System Identification
 
address@hidden docstring begin (c-doc-string "posix.c" "uname")
address@hidden docstring md5 "3c16496be65edfe89cabf2fc65c69c46"
 @deffn primitive uname
 Returns an object with some information about the computer system the
 program is running on.
@@ -2157,6 +2333,8 @@
 @node Locales
 @section Locales
 
address@hidden docstring begin (c-doc-string "posix.c" "setlocale")
address@hidden docstring md5 "46992e5988838154fce306044f430a60"
 @deffn primitive setlocale category [locale]
 If @var{locale} is omitted, returns the current value of the specified
 locale category