mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-05-02 13:00:26 +02:00
Code Activity

Applied patches (mostly Texinfo markup) from Stephen Compall.

Browse source
This commit is contained in:
Neil Jerram 2002-11-17 22:08:45 +00:00
parent 428561f263
commit 7403e409f0
3 changed files with 361 additions and 346 deletions
Download patch file Download diff file Expand all files Collapse all files

13
doc/ref/ChangeLog
View file

@ -1,3 +1,16 @@
2002-11-17 Neil Jerram <neil@ossau.uklinux.net>
Applied patch from Stephen Compall as follows. (Thanks!)
2002-10-26 Stephen Compall <rushing@sigecom.net>
* scheme-data.texi: Addition and change of many Texinfo tags,
particularly usage of @var and @samp, as well as reformatting of
some lists into tables and usage of @result.
Notes about some things I didn't understand, as well as a
missing section on non-control characters.
2002-10-27 Gary Houston <ghouston@arglist.com> 2002-10-27 Gary Houston <ghouston@arglist.com>
* scheme-modules.texi (Environments): only available when * scheme-modules.texi (Environments): only available when

346
doc/ref/posix.texi
View file

@ -1,5 +1,5 @@
@node POSIX @node POSIX
@chapter POSIX System Calls and Networking @chapter @acronym{POSIX} System Calls and Networking
@menu @menu
* Conventions:: Conventions employed by the POSIX interface. * Conventions:: Conventions employed by the POSIX interface.
@ -20,17 +20,17 @@
@end menu @end menu
@node Conventions @node Conventions
@section POSIX Interface Conventions @section @acronym{POSIX} Interface Conventions
These interfaces provide access to operating system facilities. These interfaces provide access to operating system facilities.
They provide a simple wrapping around the underlying C interfaces They provide a simple wrapping around the underlying C interfaces
to make usage from Scheme more convenient. They are also used to make usage from Scheme more convenient. They are also used
to implement the Guile port of @ref{The Scheme shell (scsh)}. to implement the Guile port of scsh (@pxref{The Scheme shell (scsh)}).
Generally there is a single procedure for each corresponding Unix Generally there is a single procedure for each corresponding Unix
facility. There are some exceptions, such as procedures implemented for facility. There are some exceptions, such as procedures implemented for
speed and convenience in Scheme with no primitive Unix equivalent, speed and convenience in Scheme with no primitive Unix equivalent,
e.g., @code{copy-file}. e.g.@: @code{copy-file}.
The interfaces are intended as far as possible to be portable across The interfaces are intended as far as possible to be portable across
different versions of Unix. In some cases procedures which can't be different versions of Unix. In some cases procedures which can't be
@ -66,9 +66,9 @@ succeed, e.g., @code{getenv} returns @code{#f} if it the requested
string is not found in the environment. These cases are noted in string is not found in the environment. These cases are noted in
the documentation. the documentation.
For ways to deal with exceptions, @ref{Exceptions}. For ways to deal with exceptions, see @ref{Exceptions}.
Errors which the C-library would report by returning a NULL pointer or Errors which the C library would report by returning a null pointer or
through some other means are reported by raising a @code{system-error} through some other means are reported by raising a @code{system-error}
exception. The value of the Unix @code{errno} variable is available exception. The value of the Unix @code{errno} variable is available
in the data passed by the exception. in the data passed by the exception.
@ -98,8 +98,8 @@ It can be extracted with the function @code{system-error-errno}:
Conventions generally follow those of scsh, @ref{The Scheme shell (scsh)}. Conventions generally follow those of scsh, @ref{The Scheme shell (scsh)}.
File ports are implemented using low-level operating system I/O File ports are implemented using low-level operating system I/O
facilities, with optional buffering to improve efficiency facilities, with optional buffering to improve efficiency; see
@pxref{File Ports} @ref{File Ports}.
Note that some procedures (e.g., @code{recv!}) will accept ports as Note that some procedures (e.g., @code{recv!}) will accept ports as
arguments, but will actually operate directly on the file descriptor arguments, but will actually operate directly on the file descriptor
@ -122,28 +122,28 @@ it's likely that the garbage collector would free the port, with the
side-effect of closing the file descriptor prematurely. side-effect of closing the file descriptor prematurely.
To assist the programmer in avoiding this problem, each port has an To assist the programmer in avoiding this problem, each port has an
associated "revealed count" which can be used to keep track of how many associated @dfn{revealed count} which can be used to keep track of how many
times the underlying file descriptor has been stored in other places. times the underlying file descriptor has been stored in other places.
If a port's revealed count is greater than zero, the file descriptor If a port's revealed count is greater than zero, the file descriptor
will not be closed when the port is garbage collected. A programmer will not be closed when the port is garbage collected. A programmer
can therefore ensure that the revealed count will be greater than can therefore ensure that the revealed count will be greater than
zero if the file descriptor is needed elsewhere. zero if the file descriptor is needed elsewhere.
For the simple case where a file descriptor is "imported" once to become For the simple case where a file descriptor is ``imported'' once to become
a port, it does not matter if the file descriptor is closed when the a port, it does not matter if the file descriptor is closed when the
port is garbage collected. There is no need to maintain a revealed port is garbage collected. There is no need to maintain a revealed
count. Likewise when "exporting" a file descriptor to the external count. Likewise when ``exporting'' a file descriptor to the external
environment, setting the revealed count is not required provided the environment, setting the revealed count is not required provided the
port is kept open (i.e., is pointed to by a live Scheme binding) while port is kept open (i.e., is pointed to by a live Scheme binding) while
the file descriptor is in use. the file descriptor is in use.
To correspond with traditional Unix behaviour, the three file To correspond with traditional Unix behaviour, three file descriptors
descriptors (0, 1 and 2) are automatically imported when a program (0, 1, and 2) are automatically imported when a program starts up and
starts up and assigned to the initial values of the current input, assigned to the initial values of the current/standard input, output,
output and error ports. The revealed count for each is initially set to and error ports, respectively. The revealed count for each is
one, so that dropping references to one of these ports will not result initially set to one, so that dropping references to one of these
in its garbage collection: it could be retrieved with fdopen or ports will not result in its garbage collection: it could be retrieved
fdes->ports. with @code{fdopen} or @code{fdes->ports}.
@deffn {Scheme Procedure} port-revealed port @deffn {Scheme Procedure} port-revealed port
@deffnx {C Function} scm_port_revealed (port) @deffnx {C Function} scm_port_revealed (port)
@ -152,7 +152,7 @@ Return the revealed count for @var{port}.
@deffn {Scheme Procedure} set-port-revealed! port rcount @deffn {Scheme Procedure} set-port-revealed! port rcount
@deffnx {C Function} scm_set_port_revealed_x (port, rcount) @deffnx {C Function} scm_set_port_revealed_x (port, rcount)
Sets the revealed count for a port to a given value. Sets the revealed count for a @var{port} to @var{rcount}.
The return value is unspecified. The return value is unspecified.
@end deffn @end deffn
@ -169,10 +169,10 @@ side effect the revealed count of @var{port} is incremented.
@deffn {Scheme Procedure} fdopen fdes modes @deffn {Scheme Procedure} fdopen fdes modes
@deffnx {C Function} scm_fdopen (fdes, modes) @deffnx {C Function} scm_fdopen (fdes, modes)
Return a new port based on the file descriptor @var{fdes}. Return a new port based on the file descriptor @var{fdes}. Modes are
Modes are given by the string @var{modes}. The revealed count given by the string @var{modes}. The revealed count of the port is
of the port is initialized to zero. The modes string is the initialized to zero. The @var{modes} string is the same as that
same as that accepted by @ref{File Ports, open-file}. accepted by @code{open-file} (@pxref{File Ports, open-file}).
@end deffn @end deffn
@deffn {Scheme Procedure} fdes->ports fd @deffn {Scheme Procedure} fdes->ports fd
@ -228,9 +228,9 @@ The return value is unspecified.
@deffnx {C Function} scm_open (path, flags, mode) @deffnx {C Function} scm_open (path, flags, mode)
Open the file named by @var{path} for reading and/or writing. Open the file named by @var{path} for reading and/or writing.
@var{flags} is an integer specifying how the file should be opened. @var{flags} is an integer specifying how the file should be opened.
@var{mode} is an integer specifying the permission bits of the file, if @var{mode} is an integer specifying the permission bits of the file,
it needs to be created, before the umask is applied. The default is 666 if it needs to be created, before the umask (@pxref{Processes}) is
(Unix itself has no default). applied. The default is 666 (Unix itself has no default).
@var{flags} can be constructed by combining variables using @code{logior}. @var{flags} can be constructed by combining variables using @code{logior}.
Basic flags are: Basic flags are:
@ -251,7 +251,7 @@ Append to the file instead of truncating.
Create the file if it does not already exist. Create the file if it does not already exist.
@end defvar @end defvar
See the Unix documentation of the @code{open} system call @xref{File Status Flags,,,libc,The GNU C Library Reference Manual},
for additional flags. for additional flags.
@end deffn @end deffn
@ -263,7 +263,7 @@ a port.
@deffn {Scheme Procedure} close fd_or_port @deffn {Scheme Procedure} close fd_or_port
@deffnx {C Function} scm_close (fd_or_port) @deffnx {C Function} scm_close (fd_or_port)
Similar to close-port (@pxref{Closing, close-port}), Similar to @code{close-port} (@pxref{Closing, close-port}),
but also works on file descriptors. A side but also works on file descriptors. A side
effect of closing a file descriptor is that any ports using that file effect of closing a file descriptor is that any ports using that file
descriptor are moved to a different file descriptor and have descriptor are moved to a different file descriptor and have
@ -272,19 +272,19 @@ their revealed counts set to zero.
@deffn {Scheme Procedure} close-fdes fd @deffn {Scheme Procedure} close-fdes fd
@deffnx {C Function} scm_close_fdes (fd) @deffnx {C Function} scm_close_fdes (fd)
A simple wrapper for the @code{close} system call. A simple wrapper for the @code{close} system call. Close file
Close file descriptor @var{fd}, which must be an integer. descriptor @var{fd}, which must be an integer. Unlike @code{close},
Unlike close (@pxref{Ports and File Descriptors, close}), the file descriptor will be closed even if a port is using it. The
the file descriptor will be closed even if a port is using it. return value is unspecified.
The return value is unspecified.
@end deffn @end deffn
@deffn {Scheme Procedure} unread-char char [port] @deffn {Scheme Procedure} unread-char char [port]
@deffnx {C Function} scm_unread_char (char, port) @deffnx {C Function} scm_unread_char (char, port)
Place @var{char} in @var{port} so that it will be read by the Place @var{char} in @var{port} so that it will be read by the next
next read operation. If called multiple times, the unread characters read operation on that port. If called multiple times, the unread
will be read again in last-in first-out order. If @var{port} is characters will be read again in ``last-in, first-out'' order (i.e.@:
not supplied, the current input port is used. a stack). If @var{port} is not supplied, the current input port is
used.
@end deffn @end deffn
@deffn {Scheme Procedure} unread-string str port @deffn {Scheme Procedure} unread-string str port
@ -297,8 +297,8 @@ unread characters will be read again in last-in first-out order. If
@deffn {Scheme Procedure} pipe @deffn {Scheme Procedure} pipe
@deffnx {C Function} scm_pipe () @deffnx {C Function} scm_pipe ()
Return a newly created pipe: a pair of ports which are linked Return a newly created pipe: a pair of ports which are linked
together on the local machine. The @emph{car} is the input together on the local machine. The @acronym{CAR} is the input
port and the @emph{cdr} is the output port. Data written (and port and the @acronym{CDR} is the output port. Data written (and
flushed) to the output port can be read from the input port. flushed) to the output port can be read from the input port.
Pipes are commonly used for communication with a newly forked Pipes are commonly used for communication with a newly forked
child process. The need to flush the output port can be child process. The need to flush the output port can be
@ -384,7 +384,7 @@ Copies the file descriptor @var{oldfd} to descriptor
number @var{newfd}, replacing the previous meaning number @var{newfd}, replacing the previous meaning
of @var{newfd}. Both @var{oldfd} and @var{newfd} must of @var{newfd}. Both @var{oldfd} and @var{newfd} must
be integers. be integers.
Unlike for dup->fdes or primitive-move->fdes, no attempt Unlike for @code{dup->fdes} or @code{primitive-move->fdes}, no attempt
is made to move away ports which are using @var{newfd}. is made to move away ports which are using @var{newfd}.
The return value is unspecified. The return value is unspecified.
@end deffn @end deffn
@ -392,18 +392,19 @@ The return value is unspecified.
@deffn {Scheme Procedure} port-mode port @deffn {Scheme Procedure} port-mode port
Return the port modes associated with the open port @var{port}. Return the port modes associated with the open port @var{port}.
These will not necessarily be identical to the modes used when These will not necessarily be identical to the modes used when
the port was opened, since modes such as "append" which are the port was opened, since modes such as ``append'' which are
used only during port creation are not retained. used only during port creation are not retained.
@end deffn @end deffn
@deffn {Scheme Procedure} port-for-each proc @deffn {Scheme Procedure} port-for-each proc
@deffnx {C Function} scm_port_for_each (proc) @deffnx {C Function} scm_port_for_each (proc)
Apply @var{proc} to each port in the Guile port table Apply @var{proc} to each port in the Guile port table
(FIXME: what is the Guile port table?)
in turn. The return value is unspecified. More specifically, in turn. The return value is unspecified. More specifically,
@var{proc} is applied exactly once to every port that exists @var{proc} is applied exactly once to every port that exists in the
in the system at the time @var{port-for-each} is invoked. system at the time @code{port-for-each} is invoked. Changes to the
Changes to the port table while @var{port-for-each} is running port table while @code{port-for-each} is running have no effect as far
have no effect as far as @var{port-for-each} is concerned. as @code{port-for-each} is concerned.
@end deffn @end deffn
@deffn {Scheme Procedure} setvbuf port mode [size] @deffn {Scheme Procedure} setvbuf port mode [size]
@ -444,7 +445,7 @@ Get the process ID of a socket's owner, for @code{SIGIO} signals.
@item F_SETOWN @item F_SETOWN
Set the process that owns a socket to @var{value}, for @code{SIGIO} signals. Set the process that owns a socket to @var{value}, for @code{SIGIO} signals.
@item FD_CLOEXEC @item FD_CLOEXEC
The value used to indicate the "close on exec" flag with @code{F_GETFL} or The value used to indicate the ``close on exec'' flag with @code{F_GETFL} or
@code{F_SETFL}. @code{F_SETFL}.
@end table @end table
@end deffn @end deffn
@ -593,8 +594,9 @@ from stat:mode in a more convenient form:
@table @code @table @code
@item stat:type @item stat:type
A symbol representing the type of file. Possible values are A symbol representing the type of file. Possible values are
regular, directory, symlink, block-special, char-special, fifo, @samp{regular}, @samp{directory}, @samp{symlink},
socket and unknown @samp{block-special}, @samp{char-special}, @samp{fifo}, @samp{socket},
and @samp{unknown}.
@item stat:perms @item stat:perms
An integer representing the access permission bits. An integer representing the access permission bits.
@end table @end table
@ -617,12 +619,12 @@ string), i.e., the file that the link points to.
@findex lchown @findex lchown
@deffn {Scheme Procedure} chown object owner group @deffn {Scheme Procedure} chown object owner group
@deffnx {C Function} scm_chown (object, owner, group) @deffnx {C Function} scm_chown (object, owner, group)
Change the ownership and group of the file referred to by @var{object} to Change the ownership and group of the file referred to by @var{object}
the integer values @var{owner} and @var{group}. @var{object} can be to the integer values @var{owner} and @var{group}. @var{object} can
a string containing a file name or, if the platform be a string containing a file name or, if the platform supports
supports fchown, a port or integer file descriptor @code{fchown} (@pxref{File Owner,,,libc,The GNU C Library Reference
which is open on the file. The return value Manual}), a port or integer file descriptor which is open on the file.
is unspecified. The return value is unspecified.
If @var{object} is a symbolic link, either the If @var{object} is a symbolic link, either the
ownership of the link or the ownership of the referenced file will be ownership of the link or the ownership of the referenced file will be
@ -660,12 +662,13 @@ modification time to the current time.
@findex unlink @findex unlink
@deffn {Scheme Procedure} delete-file str @deffn {Scheme Procedure} delete-file str
@deffnx {C Function} scm_delete_file (str) @deffnx {C Function} scm_delete_file (str)
Deletes (or "unlinks") the file specified by @var{path}. Deletes (or ``unlinks'') the file whose path is specified by
@var{str}.
@end deffn @end deffn
@deffn {Scheme Procedure} copy-file oldfile newfile @deffn {Scheme Procedure} copy-file oldfile newfile
@deffnx {C Function} scm_copy_file (oldfile, newfile) @deffnx {C Function} scm_copy_file (oldfile, newfile)
Copy the file specified by @var{path-from} to @var{path-to}. Copy the file specified by @var{oldfile} to @var{newfile}.
The return value is unspecified. The return value is unspecified.
@end deffn @end deffn
@ -686,16 +689,16 @@ system.
@deffn {Scheme Procedure} symlink oldpath newpath @deffn {Scheme Procedure} symlink oldpath newpath
@deffnx {C Function} scm_symlink (oldpath, newpath) @deffnx {C Function} scm_symlink (oldpath, newpath)
Create a symbolic link named @var{path-to} with the value (i.e., pointing to) Create a symbolic link named @var{newpath} with the value (i.e., pointing to)
@var{path-from}. The return value is unspecified. @var{oldpath}. The return value is unspecified.
@end deffn @end deffn
@deffn {Scheme Procedure} mkdir path [mode] @deffn {Scheme Procedure} mkdir path [mode]
@deffnx {C Function} scm_mkdir (path, mode) @deffnx {C Function} scm_mkdir (path, mode)
Create a new directory named by @var{path}. If @var{mode} is omitted Create a new directory named by @var{path}. If @var{mode} is omitted
then the permissions of the directory file are set using the current then the permissions of the directory file are set using the current
umask. Otherwise they are set to the decimal value specified with umask (@pxref{Processes}). Otherwise they are set to the decimal
@var{mode}. The return value is unspecified. value specified with @var{mode}. The return value is unspecified.
@end deffn @end deffn
@deffn {Scheme Procedure} rmdir path @deffn {Scheme Procedure} rmdir path
@ -706,31 +709,31 @@ be empty for this to succeed. The return value is unspecified.
@deffn {Scheme Procedure} opendir dirname @deffn {Scheme Procedure} opendir dirname
@deffnx {C Function} scm_opendir (dirname) @deffnx {C Function} scm_opendir (dirname)
Open the directory specified by @var{path} and return a directory Open the directory specified by @var{dirname} and return a directory
stream. stream.
@end deffn @end deffn
@deffn {Scheme Procedure} directory-stream? obj @deffn {Scheme Procedure} directory-stream? object
@deffnx {C Function} scm_directory_stream_p (obj) @deffnx {C Function} scm_directory_stream_p (object)
Return a boolean indicating whether @var{object} is a directory Return a boolean indicating whether @var{object} is a directory
stream as returned by @code{opendir}. stream as returned by @code{opendir}.
@end deffn @end deffn
@deffn {Scheme Procedure} readdir port @deffn {Scheme Procedure} readdir stream
@deffnx {C Function} scm_readdir (port) @deffnx {C Function} scm_readdir (stream)
Return (as a string) the next directory entry from the directory stream Return (as a string) the next directory entry from the directory stream
@var{stream}. If there is no remaining entry to be read then the @var{stream}. If there is no remaining entry to be read then the
end of file object is returned. end of file object is returned.
@end deffn @end deffn
@deffn {Scheme Procedure} rewinddir port @deffn {Scheme Procedure} rewinddir stream
@deffnx {C Function} scm_rewinddir (port) @deffnx {C Function} scm_rewinddir (stream)
Reset the directory port @var{stream} so that the next call to Reset the directory port @var{stream} so that the next call to
@code{readdir} will return the first directory entry. @code{readdir} will return the first directory entry.
@end deffn @end deffn
@deffn {Scheme Procedure} closedir port @deffn {Scheme Procedure} closedir stream
@deffnx {C Function} scm_closedir (port) @deffnx {C Function} scm_closedir (stream)
Close the directory stream @var{stream}. Close the directory stream @var{stream}.
The return value is unspecified. The return value is unspecified.
@end deffn @end deffn
@ -755,13 +758,13 @@ The return value is unspecified.
@deffn {Scheme Procedure} mknod path type perms dev @deffn {Scheme Procedure} mknod path type perms dev
@deffnx {C Function} scm_mknod (path, type, perms, dev) @deffnx {C Function} scm_mknod (path, type, perms, dev)
Creates a new special file, such as a file corresponding to a device. Creates a new special file, such as a file corresponding to a device.
@var{path} specifies the name of the file. @var{type} should @var{path} specifies the name of the file. @var{type} should be one
be one of the following symbols: of the following symbols: @samp{regular}, @samp{directory},
regular, directory, symlink, block-special, char-special, @samp{symlink}, @samp{block-special}, @samp{char-special},
fifo, or socket. @var{perms} (an integer) specifies the file permissions. @samp{fifo}, or @samp{socket}. @var{perms} (an integer) specifies the
@var{dev} (an integer) specifies which device the special file refers file permissions. @var{dev} (an integer) specifies which device the
to. Its exact interpretation depends on the kind of special file special file refers to. Its exact interpretation depends on the kind
being created. of special file being created.
E.g., E.g.,
@lisp @lisp
@ -785,7 +788,7 @@ Care should be taken if opening the file, e.g., use the
Create a new unique file in the file system and returns a new Create a new unique file in the file system and returns a new
buffered port open for reading and writing to the file. buffered port open for reading and writing to the file.
@var{tmpl} is a string specifying where the file should be @var{tmpl} is a string specifying where the file should be
created: it must end with @code{XXXXXX} and will be changed in created: it must end with @samp{XXXXXX} and will be changed in
place to return the name of the temporary file. place to return the name of the temporary file.
@end deffn @end deffn
@ -949,14 +952,14 @@ information cannot be obtained.
@deffn {Scheme Procedure} current-time @deffn {Scheme Procedure} current-time
@deffnx {C Function} scm_current_time () @deffnx {C Function} scm_current_time ()
Return the number of seconds since 1970-01-01 00:00:00 UTC, Return the number of seconds since 1970-01-01 00:00:00 @acronym{UTC},
excluding leap seconds. excluding leap seconds.
@end deffn @end deffn
@deffn {Scheme Procedure} gettimeofday @deffn {Scheme Procedure} gettimeofday
@deffnx {C Function} scm_gettimeofday () @deffnx {C Function} scm_gettimeofday ()
Return a pair containing the number of seconds and microseconds Return a pair containing the number of seconds and microseconds
since 1970-01-01 00:00:00 UTC, excluding leap seconds. Note: since 1970-01-01 00:00:00 @acronym{UTC}, excluding leap seconds. Note:
whether true microsecond resolution is available depends on the whether true microsecond resolution is available depends on the
operating system. operating system.
@end deffn @end deffn
@ -984,10 +987,10 @@ Day of the week (0-6) with Sunday represented as 0.
@item tm:yday, set-tm:yday @item tm:yday, set-tm:yday
Day of the year (0-364, 365 in leap years). Day of the year (0-364, 365 in leap years).
@item tm:isdst, set-tm:isdst @item tm:isdst, set-tm:isdst
Daylight saving indicator (0 for "no", greater than 0 for "yes", less than Daylight saving indicator (0 for ``no'', greater than 0 for ``yes'', less than
0 for "unknown"). 0 for ``unknown'').
@item tm:gmtoff, set-tm:gmtoff @item tm:gmtoff, set-tm:gmtoff
Time zone offset in seconds west of UTC (-46800 to 43200). Time zone offset in seconds west of @acronym{UTC} (-46800 to 43200).
@item tm:zone, set-tm:zone @item tm:zone, set-tm:zone
Time zone label (a string), not necessarily unique. Time zone label (a string), not necessarily unique.
@end table @end table
@ -998,31 +1001,32 @@ Return an object representing the broken down components of
@var{time}, an integer like the one returned by @var{time}, an integer like the one returned by
@code{current-time}. The time zone for the calculation is @code{current-time}. The time zone for the calculation is
optionally specified by @var{zone} (a string), otherwise the optionally specified by @var{zone} (a string), otherwise the
@code{TZ} environment variable or the system default is used. @env{TZ} environment variable or the system default is used.
@end deffn @end deffn
@deffn {Scheme Procedure} gmtime time @deffn {Scheme Procedure} gmtime time
@deffnx {C Function} scm_gmtime (time) @deffnx {C Function} scm_gmtime (time)
Return an object representing the broken down components of Return an object representing the broken down components of
@var{time}, an integer like the one returned by @var{time}, an integer like the one returned by
@code{current-time}. The values are calculated for UTC. @code{current-time}. The values are calculated for @acronym{UTC}.
@end deffn @end deffn
@deffn {Scheme Procedure} mktime sbd_time [zone] @deffn {Scheme Procedure} mktime sbd_time [zone]
@deffnx {C Function} scm_mktime (sbd_time, zone) @deffnx {C Function} scm_mktime (sbd_time, zone)
@var{bd-time} is an object representing broken down time and @code{zone} @var{sbd-time} is an object representing broken down time and
is an optional time zone specifier (otherwise the TZ environment variable @code{zone} is an optional time zone specifier (otherwise the @env{TZ}
or the system default is used). environment variable or the system default is used).
Returns a pair: the car is a corresponding Returns a pair: the @acronym{CAR} is a corresponding integer time
integer time value like that returned value like that returned by @code{current-time}; the @acronym{CDR} is
by @code{current-time}; the cdr is a broken down time object, similar to a broken down time object, similar to @var{sbd-time} but with
as @var{bd-time} but with normalized values. normalized values; i.e.@: with corrected @code{tm:wday} and
@code{tm:yday} fields.
@end deffn @end deffn
@deffn {Scheme Procedure} tzset @deffn {Scheme Procedure} tzset
@deffnx {C Function} scm_tzset () @deffnx {C Function} scm_tzset ()
Initialize the timezone from the TZ environment variable Initialize the timezone from the @env{TZ} environment variable
or the system default. It's not usually necessary to call this procedure 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 since it's done automatically by other procedures that depend on the
timezone. timezone.
@ -1033,10 +1037,10 @@ timezone.
Formats a time specification @var{time} using @var{template}. @var{time} Formats a time specification @var{time} using @var{template}. @var{time}
is an object with time components in the form returned by @code{localtime} 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 or @code{gmtime}. @var{template} is a string which can include formatting
specifications introduced by a @code{%} character. The formatting of specifications introduced by a @samp{%} character. The formatting of
month and day names is dependent on the current locale. The value returned month and day names is dependent on the current locale. The value returned
is the formatted string. is the formatted string.
@xref{Formatting Date and Time, , , libc, The GNU C Library Reference Manual}.) @xref{Formatting Date and Time, , , libc, The GNU C Library Reference Manual}.
@lisp @lisp
(strftime "%c" (localtime (current-time))) (strftime "%c" (localtime (current-time)))
@ -1050,11 +1054,11 @@ Performs the reverse action to @code{strftime}, parsing
@var{string} according to the specification supplied in @var{string} according to the specification supplied in
@var{template}. The interpretation of month and day names is @var{template}. The interpretation of month and day names is
dependent on the current locale. The value returned is a pair. dependent on the current locale. The value returned is a pair.
The car has an object with time components The @acronym{CAR} has an object with time components
in the form returned by @code{localtime} or @code{gmtime}, in the form returned by @code{localtime} or @code{gmtime},
but the time zone components but the time zone components
are not usefully set. are not usefully set.
The cdr reports the number of characters from @var{string} The @acronym{CDR} reports the number of characters from @var{string}
which were used for the conversion. which were used for the conversion.
@end deffn @end deffn
@ -1143,8 +1147,8 @@ If @var{env} is omitted, return the current environment (in the
Unix sense) as a list of strings. Otherwise set the current Unix sense) as a list of strings. Otherwise set the current
environment, which is also the default environment for child environment, which is also the default environment for child
processes, to the supplied list of strings. Each member of processes, to the supplied list of strings. Each member of
@var{env} should be of the form @code{NAME=VALUE} and values of @var{env} should be of the form @var{NAME}=@var{VALUE} and values of
@code{NAME} should not be duplicated. If @var{env} is supplied @var{NAME} should not be duplicated. If @var{env} is supplied
then the return value is unspecified. then the return value is unspecified.
@end deffn @end deffn
@ -1182,11 +1186,13 @@ Return the name of the current working directory.
@deffn {Scheme Procedure} umask [mode] @deffn {Scheme Procedure} umask [mode]
@deffnx {C Function} scm_umask (mode) @deffnx {C Function} scm_umask (mode)
If @var{mode} is omitted, returns a decimal number representing the current If @var{mode} is omitted, returns a decimal number representing the
file creation mask. Otherwise the file creation mask is set to current file creation mask. Otherwise the file creation mask is set
@var{mode} and the previous value is returned. to @var{mode} and the previous value is returned. @xref{Setting
Permissions,,Assigning File Permissions,libc,The GNU C Library
Reference Manual}, for more on how to use umasks.
E.g., @code{(umask #o022)} sets the mask to octal 22, decimal 18. E.g., @code{(umask #o022)} sets the mask to octal 22/decimal 18.
@end deffn @end deffn
@deffn {Scheme Procedure} chroot path @deffn {Scheme Procedure} chroot path
@ -1259,7 +1265,7 @@ The return value is unspecified.
@deffnx {C Function} scm_seteuid (id) @deffnx {C Function} scm_seteuid (id)
Sets the effective user ID to the integer @var{id}, provided the process Sets the effective user ID to the integer @var{id}, provided the process
has appropriate privileges. If effective IDs are not supported, the has appropriate privileges. If effective IDs are not supported, the
real ID is set instead -- @code{(provided? 'EIDs)} reports whether the real ID is set instead---@code{(provided? 'EIDs)} reports whether the
system supports effective IDs. system supports effective IDs.
The return value is unspecified. The return value is unspecified.
@end deffn @end deffn
@ -1268,7 +1274,7 @@ The return value is unspecified.
@deffnx {C Function} scm_setegid (id) @deffnx {C Function} scm_setegid (id)
Sets the effective group ID to the integer @var{id}, provided the process Sets the effective group ID to the integer @var{id}, provided the process
has appropriate privileges. If effective IDs are not supported, the has appropriate privileges. If effective IDs are not supported, the
real ID is set instead -- @code{(provided? 'EIDs)} reports whether the real ID is set instead---@code{(provided? 'EIDs)} reports whether the
system supports effective IDs. system supports effective IDs.
The return value is unspecified. The return value is unspecified.
@end deffn @end deffn
@ -1276,7 +1282,7 @@ The return value is unspecified.
@deffn {Scheme Procedure} getpgrp @deffn {Scheme Procedure} getpgrp
@deffnx {C Function} scm_getpgrp () @deffnx {C Function} scm_getpgrp ()
Return an integer representing the current process group ID. Return an integer representing the current process group ID.
This is the POSIX definition, not BSD. This is the @acronym{POSIX} definition, not @acronym{BSD}.
@end deffn @end deffn
@deffn {Scheme Procedure} setpgid pid pgid @deffn {Scheme Procedure} setpgid pid pgid
@ -1305,17 +1311,17 @@ child process is eligible then one will be chosen by the operating system.
The value of @var{pid} determines the behaviour: The value of @var{pid} determines the behaviour:
@table @r @table @asis
@item @var{pid} greater than 0 @item @var{pid} greater than 0
Request status information from the specified child process. Request status information from the specified child process.
@item @var{pid} equal to -1 or WAIT_ANY @item @var{pid} equal to -1 or @code{WAIT_ANY}
Request status information for any child process. Request status information for any child process.
@item @var{pid} equal to 0 or WAIT_MYPGRP @item @var{pid} equal to 0 or @code{WAIT_MYPGRP}
Request status information for any child process in the current process Request status information for any child process in the current process
group. group.
@item @var{pid} less than -1 @item @var{pid} less than -1
Request status information for any child process whose process group ID Request status information for any child process whose process group ID
is -@var{PID}. is @minus{}@var{pid}.
@end table @end table
The @var{options} argument, if supplied, should be the bitwise OR of the The @var{options} argument, if supplied, should be the bitwise OR of the
@ -1366,8 +1372,8 @@ otherwise @code{#f}.
@deffn {Scheme Procedure} system [cmd] @deffn {Scheme Procedure} system [cmd]
@deffnx {C Function} scm_system (cmd) @deffnx {C Function} scm_system (cmd)
Execute @var{cmd} using the operating system's "command Execute @var{cmd} using the operating system's ``command
processor". Under Unix this is usually the default shell processor''. Under Unix this is usually the default shell
@code{sh}. The value returned is @var{cmd}'s exit status as @code{sh}. The value returned is @var{cmd}'s exit status as
returned by @code{waitpid}, which can be interpreted using the returned by @code{waitpid}, which can be interpreted using the
functions above. functions above.
@ -1421,7 +1427,7 @@ call, but we call it @code{execle} because of its Scheme calling interface.
@deffn {Scheme Procedure} primitive-fork @deffn {Scheme Procedure} primitive-fork
@deffnx {C Function} scm_fork () @deffnx {C Function} scm_fork ()
Creates a new "child" process by duplicating the current "parent" process. 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 In the child the return value is 0. In the parent the return value is
the integer process ID of the child. the integer process ID of the child.
@ -1446,11 +1452,11 @@ or @code{PRIO_USER}, and @var{who} is interpreted relative to
hhhhprocess group identifier for @code{PRIO_PGRP}, and a user hhhhprocess group identifier for @code{PRIO_PGRP}, and a user
identifier for @code{PRIO_USER}. A zero value of @var{who} identifier for @code{PRIO_USER}. A zero value of @var{who}
denotes the current process, process group, or user. denotes the current process, process group, or user.
@var{prio} is a value in the range -20 and 20, the default @var{prio} is a value in the range [@minus{}20,20]. The default
priority is 0; lower priorities cause more favorable priority is 0; lower priorities (in numerical terms) cause more
scheduling. Sets the priority of all of the specified favorable scheduling. Sets the priority of all of the specified
processes. Only the super-user may lower priorities. processes. Only the super-user may lower priorities. The return
The return value is not specified. value is not specified.
@end deffn @end deffn
@deffn {Scheme Procedure} getpriority which who @deffn {Scheme Procedure} getpriority which who
@ -1458,10 +1464,10 @@ The return value is not specified.
Return the scheduling priority of the process, process group Return the scheduling priority of the process, process group
or user, as indicated by @var{which} and @var{who}. @var{which} or user, as indicated by @var{which} and @var{who}. @var{which}
is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP} is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
or @code{PRIO_USER}, and @var{who} is interpreted relative to or @code{PRIO_USER}, and @var{who} should be interpreted depending on
@var{which} (a process identifier for @code{PRIO_PROCESS}, @var{which} (a process identifier for @code{PRIO_PROCESS},
process group identifier for @code{PRIO_PGRP}, and a user process group identifier for @code{PRIO_PGRP}, and a user
identifier for @code{PRIO_USER}. A zero value of @var{who} identifier for @code{PRIO_USER}). A zero value of @var{who}
denotes the current process, process group, or user. Return denotes the current process, process group, or user. Return
the highest priority (lowest numerical value) of any of the the highest priority (lowest numerical value) of any of the
specified processes. specified processes.
@ -1479,7 +1485,7 @@ Sends a signal to the specified process or group of processes.
@var{pid} specifies the processes to which the signal is sent: @var{pid} specifies the processes to which the signal is sent:
@table @r @table @asis
@item @var{pid} greater than 0 @item @var{pid} greater than 0
The process whose identifier is @var{pid}. The process whose identifier is @var{pid}.
@item @var{pid} equal to 0 @item @var{pid} equal to 0
@ -1502,12 +1508,15 @@ Hang-up signal.
@defvar SIGINT @defvar SIGINT
Interrupt signal. Interrupt signal.
@end defvar @end defvar
A full list of signals on the GNU system may be found in @ref{Standard
Signals,,,libc,The GNU C Library Reference Manual}.
@end deffn @end deffn
@deffn {Scheme Procedure} raise sig @deffn {Scheme Procedure} raise sig
@deffnx {C Function} scm_raise (sig) @deffnx {C Function} scm_raise (sig)
Sends a specified signal @var{sig} to the current process, where Sends a specified signal @var{sig} to the current process, where
@var{sig} is as described for the kill procedure. @var{sig} is as described for the @code{kill} procedure.
@end deffn @end deffn
@deffn {Scheme Procedure} sigaction signum [handler [flags [thread]]] @deffn {Scheme Procedure} sigaction signum [handler [flags [thread]]]
@ -1519,11 +1528,12 @@ Install or report the signal handler for a specified signal.
of variables such as @code{SIGINT}. of variables such as @code{SIGINT}.
If @var{handler} is omitted, @code{sigaction} returns a pair: the If @var{handler} is omitted, @code{sigaction} returns a pair: the
CAR is the current @acronym{CAR} is the current signal hander, which will be either an
signal hander, which will be either an integer with the value @code{SIG_DFL} integer with the value @code{SIG_DFL} (default action) or
(default action) or @code{SIG_IGN} (ignore), or the Scheme procedure which @code{SIG_IGN} (ignore), or the Scheme procedure which handles the
handles the signal, or @code{#f} if a non-Scheme procedure handles the signal, or @code{#f} if a non-Scheme procedure handles the signal.
signal. The CDR contains the current @code{sigaction} flags for the handler. The @acronym{CDR} contains the current @code{sigaction} flags for the
handler.
If @var{handler} is provided, it is installed as the new handler for If @var{handler} is provided, it is installed as the new handler for
@var{signum}. @var{handler} can be a Scheme procedure taking one @var{signum}. @var{handler} can be a Scheme procedure taking one
@ -1539,7 +1549,7 @@ will always be added if it's available and the system is using
restartable system calls.) The return value is a pair with information restartable system calls.) The return value is a pair with information
about the old handler as described above. about the old handler as described above.
This interface does not provide access to the "signal blocking" This interface does not provide access to the ``signal blocking''
facility. Maybe this is not needed, since the thread support may facility. Maybe this is not needed, since the thread support may
provide solutions to the problem of consistent access to data provide solutions to the problem of consistent access to data
structures. structures.
@ -1580,8 +1590,8 @@ of seconds remaining otherwise.
@deffn {Scheme Procedure} usleep i @deffn {Scheme Procedure} usleep i
@deffnx {C Function} scm_usleep (i) @deffnx {C Function} scm_usleep (i)
Sleep for I microseconds. @code{usleep} is not available on Sleep for @var{i} microseconds. @code{usleep} is not available on
all platforms. all platforms. [FIXME: so what happens when it isn't?]
@end deffn @end deffn
@deffn {Scheme Procedure} setitimer which_timer interval_seconds interval_microseconds value_seconds value_microseconds @deffn {Scheme Procedure} setitimer which_timer interval_seconds interval_microseconds value_seconds value_microseconds
@ -1591,8 +1601,6 @@ Set the timer specified by @var{which_timer} according to the given
@var{value_seconds}, and @var{value_microseconds} values. @var{value_seconds}, and @var{value_microseconds} values.
Return information about the timer's previous setting. Return information about the timer's previous setting.
Errors are handled as described in the guile info pages under ``POSIX
Interface Conventions''.
The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL}, The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
and @code{ITIMER_PROF}. and @code{ITIMER_PROF}.
@ -1605,9 +1613,7 @@ the seconds and microseconds of the timer @code{it_value}.
@deffn {Scheme Procedure} getitimer which_timer @deffn {Scheme Procedure} getitimer which_timer
@deffnx {C Function} scm_getitimer (which_timer) @deffnx {C Function} scm_getitimer (which_timer)
Return information about the timer specified by @var{which_timer} Return information about the timer specified by @var{which_timer}.
Errors are handled as described in the guile info pages under ``POSIX
Interface Conventions''.
The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL}, The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
and @code{ITIMER_PROF}. and @code{ITIMER_PROF}.
@ -1667,7 +1673,7 @@ controlling terminal. The return value is unspecified.
@section Pipes @section Pipes
The following procedures provide an interface to the @code{popen} and The following procedures provide an interface to the @code{popen} and
@code{pclose} system routines. The code is in a separate "popen" @code{pclose} system routines. The code is in a separate ``popen''
module: module:
@smalllisp @smalllisp
@ -1826,7 +1832,7 @@ The following functions accept a host object and return a selected
component: component:
@deffn {Scheme Procedure} hostent:name host @deffn {Scheme Procedure} hostent:name host
The "official" hostname for @var{host}. The ``official'' hostname for @var{host}.
@end deffn @end deffn
@deffn {Scheme Procedure} hostent:aliases host @deffn {Scheme Procedure} hostent:aliases host
A list of aliases for @var{host}. A list of aliases for @var{host}.
@ -1900,7 +1906,7 @@ The following functions accept an object representing a network
and return a selected component: and return a selected component:
@deffn {Scheme Procedure} netent:name net @deffn {Scheme Procedure} netent:name net
The "official" network name. The ``official'' network name.
@end deffn @end deffn
@deffn {Scheme Procedure} netent:aliases net @deffn {Scheme Procedure} netent:aliases net
A list of aliases for the network. A list of aliases for the network.
@ -1958,7 +1964,7 @@ The following functions accept an object representing a protocol
and return a selected component: and return a selected component:
@deffn {Scheme Procedure} protoent:name protocol @deffn {Scheme Procedure} protoent:name protocol
The "official" protocol name. The ``official'' protocol name.
@end deffn @end deffn
@deffn {Scheme Procedure} protoent:aliases protocol @deffn {Scheme Procedure} protoent:aliases protocol
A list of aliases for the protocol. A list of aliases for the protocol.
@ -2011,7 +2017,7 @@ The following functions accept an object representing a service
and return a selected component: and return a selected component:
@deffn {Scheme Procedure} servent:name serv @deffn {Scheme Procedure} servent:name serv
The "official" name of the network service. The ``official'' name of the network service.
@end deffn @end deffn
@deffn {Scheme Procedure} servent:aliases serv @deffn {Scheme Procedure} servent:aliases serv
A list of aliases for the network service. A list of aliases for the network service.
@ -2080,12 +2086,13 @@ Otherwise it is equivalent to @code{setservent stayopen}.
Socket ports can be created using @code{socket} and @code{socketpair}. Socket ports can be created using @code{socket} and @code{socketpair}.
The ports are initially unbuffered, to make reading and writing to the The ports are initially unbuffered, to make reading and writing to the
same port more reliable. A buffer can be added to the port using same port more reliable. A buffer can be added to the port using
@code{setvbuf}, @xref{Ports and File Descriptors}. @code{setvbuf}; see @ref{Ports and File Descriptors}.
The convention used for "host" vs "network" addresses is that addresses The convention used for ``host'' vs.@: ``network'' addresses is that
are always held in host order at the Scheme level. The procedures in addresses are always held in host order at the Scheme level. The
this section automatically convert between host and network order when procedures in this section automatically convert between host and
required. The arguments and return values are thus in host order. network order when required. The arguments and return values are thus
in host order.
@deffn {Scheme Procedure} socket family style proto @deffn {Scheme Procedure} socket family style proto
@deffnx {C Function} scm_socket (family, style, proto) @deffnx {C Function} scm_socket (family, style, proto)
@ -2255,9 +2262,9 @@ one is available unless the non-blocking option has been
set on the socket. set on the socket.
The return value is a The return value is a
pair in which the @emph{car} is a new socket port for the pair in which the @acronym{CAR} is a new socket port for the
connection and connection and
the @emph{cdr} is an object with address information about the the @acronym{CDR} is an object with address information about the
client which initiated the connection. client which initiated the connection.
@var{sock} does not become part of the @var{sock} does not become part of the
@ -2310,8 +2317,8 @@ protocols, if a packet larger than this limit is encountered
then some data then some data
will be irrevocably lost. will be irrevocably lost.
The optional @var{flags} argument is a value or The optional @var{flags} argument is a value or bitwise OR of
bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc. @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
The value returned is the number of bytes read from the The value returned is the number of bytes read from the
socket. socket.
@ -2324,14 +2331,11 @@ any unread buffered port data is ignored.
@deffn {Scheme Procedure} send sock message [flags] @deffn {Scheme Procedure} send sock message [flags]
@deffnx {C Function} scm_send (sock, message, flags) @deffnx {C Function} scm_send (sock, message, flags)
Transmit the string @var{message} on a socket port @var{sock}. Transmit the string @var{message} on a socket port @var{sock}.
@var{sock} must already be bound to a destination address. The @var{sock} must already be bound to a destination address. The value
value returned is the number of bytes transmitted -- returned is the number of bytes transmitted---it's possible for this
it's possible for to be less than the length of @var{message} if the socket is set to be
this to be less than the length of @var{message} non-blocking. The optional @var{flags} argument is a value or bitwise
if the socket is OR of @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
set to be non-blocking. The optional @var{flags} argument
is a value or
bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.
Note that the data is written directly to the socket Note that the data is written directly to the socket
file descriptor: file descriptor:
@ -2352,8 +2356,8 @@ data will be irrevocably lost.
The optional @var{flags} argument is a value or bitwise OR of The optional @var{flags} argument is a value or bitwise OR of
@code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc. @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
The value returned is a pair: the @emph{car} is the number of The value returned is a pair: the @acronym{CAR} is the number of
bytes read from the socket and the @emph{cdr} an address object bytes read from the socket and the @acronym{CDR} an address object
in the same form as returned by @code{accept}. The address in the same form as returned by @code{accept}. The address
will given as @code{#f} if not available, as is usually the will given as @code{#f} if not available, as is usually the
case for stream sockets. case for stream sockets.
@ -2375,7 +2379,7 @@ destination address is specified using the @var{fam},
@code{connect} procedure. @var{args_and_flags} contains @code{connect} procedure. @var{args_and_flags} contains
the usual connection arguments optionally followed by the usual connection arguments optionally followed by
a flags argument, which is a value or a flags argument, which is a value or
bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc. bitwise OR of @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
The value returned is the number of bytes transmitted -- The value returned is the number of bytes transmitted --
it's possible for it's possible for
@ -2388,7 +2392,7 @@ any unflushed buffered port data is ignored.
@end deffn @end deffn
The following functions can be used to convert short and long integers The following functions can be used to convert short and long integers
between "host" and "network" order. Although the procedures above do between ``host'' and ``network'' order. Although the procedures above do
this automatically for addresses, the conversion will still need to this automatically for addresses, the conversion will still need to
be done when sending or receiving encoded integer data from the network. be done when sending or receiving encoded integer data from the network.
@ -2479,8 +2483,8 @@ client.
@example @example
(let ((s (socket AF_INET SOCK_STREAM 0))) (let ((s (socket AF_INET SOCK_STREAM 0)))
(setsockopt s SOL_SOCKET SO_REUSEADDR 1) (setsockopt s SOL_SOCKET SO_REUSEADDR 1)
;; Specific address? ;; @r{Specific address?}
;; (bind s AF_INET (inet-aton "127.0.0.1") 2904) ;; @r{(bind s AF_INET (inet-aton "127.0.0.1") 2904)}
(bind s AF_INET INADDR_ANY 2904) (bind s AF_INET INADDR_ANY 2904)
(listen s 5) (listen s 5)
@ -2498,7 +2502,7 @@ client.
(gethostbyaddr (gethostbyaddr
(sockaddr:addr client-details))) (sockaddr:addr client-details)))
(newline) (newline)
;; Send back the greeting to the client port ;; @r{Send back the greeting to the client port}
(display "Hello client\r\n" client) (display "Hello client\r\n" client)
(close client)))) (close client))))
@end example @end example
@ -2547,10 +2551,12 @@ specified.
@c FIXME::martin: Not in libguile! @c FIXME::martin: Not in libguile!
@deffn {Scheme Procedure} software-type @deffn {Scheme Procedure} software-type
Return a symbol describing the current platform's operating system. Return a symbol describing the current platform's operating system.
This may be one of AIX, VMS, UNIX, COHERENT, WINDOWS, MS-DOS, OS/2, This may be one of @samp{AIX}, @samp{VMS}, @samp{UNIX},
THINKC, AMIGA, ATARIST, MACH, or ACORN. @samp{COHERENT}, @samp{WINDOWS}, @samp{MS-DOS}, @samp{OS/2},
@samp{THINKC}, @samp{AMIGA}, @samp{ATARIST}, @samp{MACH}, or
@samp{ACORN}.
Note that most varieties of Unix are considered to be simply "UNIX". Note that most varieties of Unix are considered to be simply @samp{UNIX}.
That is because when a program depends on features that are not present That is because when a program depends on features that are not present
on every operating system, it is usually better to test for the presence on every operating system, it is usually better to test for the presence
or absence of that specific feature. The return value of or absence of that specific feature. The return value of
@ -2563,10 +2569,10 @@ no other easy or unambiguous way of detecting such features.
@deffn {Scheme Procedure} setlocale category [locale] @deffn {Scheme Procedure} setlocale category [locale]
@deffnx {C Function} scm_setlocale (category, locale) @deffnx {C Function} scm_setlocale (category, locale)
If @var{locale} is omitted, return the current value of the If @var{locale} is omitted, return the current value of the specified
specified locale category as a system-dependent string. locale @var{category} as a system-dependent string. @var{category}
@var{category} should be specified using the values should be specified using the values @code{LC_COLLATE}, @code{LC_ALL}
@code{LC_COLLATE}, @code{LC_ALL} etc. etc; see @inforef{Locating Catalogs,, gettext}.
Otherwise the specified locale category is set to the string Otherwise the specified locale category is set to the string
@var{locale} and the new value is returned as a @var{locale} and the new value is returned as a

348
doc/ref/scheme-data.texi
View file

@ -5,13 +5,13 @@
This chapter describes those of Guile's simple data types which are This chapter describes those of Guile's simple data types which are
primarily used for their role as items of generic data. By primarily used for their role as items of generic data. By
@dfn{simple} we mean data types that are not primarily used as @dfn{simple} we mean data types that are not primarily used as
containers to hold other data --- i.e. pairs, lists, vectors and so on. containers to hold other data --- i.e.@: pairs, lists, vectors and so on.
For the documentation of such @dfn{compound} data types, see For the documentation of such @dfn{compound} data types, see
@ref{Compound Data Types}. @ref{Compound Data Types}.
One of the great strengths of Scheme is that there is no straightforward One of the great strengths of Scheme is that there is no straightforward
distinction between ``data'' and ``functionality''. For example, distinction between ``data'' and ``functionality''. For example,
Guile's support for dynamic linking could be described Guile's support for dynamic linking could be described:
@itemize @bullet @itemize @bullet
@item @item
@ -59,16 +59,13 @@ equality predicates @code{eq?}, @code{eqv?} and @code{equal?}
@lisp @lisp
(<= 3 8) (<= 3 8)
@result{} @result{} #t
#t
(<= 3 -3) (<= 3 -3)
@result{} @result{} #f
#f
(equal? "house" "houses") (equal? "house" "houses")
@result{} @result{} #f
#f
(eq? #f #f) (eq? #f #f)
@result{} @result{}
@ -82,16 +79,13 @@ value at all except @code{#f}.
@lisp @lisp
(if #t "yes" "no") (if #t "yes" "no")
@result{} @result{} "yes"
"yes"
(if 0 "yes" "no") (if 0 "yes" "no")
@result{} @result{} "yes"
"yes"
(if #f "yes" "no") (if #f "yes" "no")
@result{} @result{} "no"
"no"
@end lisp @end lisp
A result of this asymmetry is that typical Scheme source code more often A result of this asymmetry is that typical Scheme source code more often
@ -133,7 +127,7 @@ data. This section of the manual documents those types and functions.
You may also find it illuminating to read R5RS's presentation of numbers You may also find it illuminating to read R5RS's presentation of numbers
in Scheme, which is particularly clear and accessible: see in Scheme, which is particularly clear and accessible: see
@xref{Numbers,,,r5rs}. @ref{Numbers,,,r5rs,R5RS}.
@menu @menu
* Numerical Tower:: Scheme's numerical "tower". * Numerical Tower:: Scheme's numerical "tower".
@ -161,22 +155,28 @@ in Scheme, which is particularly clear and accessible: see
Scheme's numerical ``tower'' consists of the following categories of Scheme's numerical ``tower'' consists of the following categories of
numbers: numbers:
@itemize @bullet @table @dfn
@item @item integers
integers (whole numbers) Whole numbers, positive or negative; e.g.@: --5, 0, 18.
@item @item rationals
rationals (the set of numbers that can be expressed as P/Q where P and Q The set of numbers that can be expressed as @math{@var{p}/@var{q}}
are integers) where @var{p} and @var{q} are integers; e.g.@: @math{9/16} works, but
pi (an irrational number) doesn't. These include integers
(@math{@var{n}/1}).
@item @item real numbers
real numbers (the set of numbers that describes all possible positions The set of numbers that describes all possible positions along a
along a one dimensional line) one-dimensional line. This includes rationals as well as irrational
numbers.
@item @item complex numbers
complex numbers (the set of numbers that describes all possible The set of numbers that describes all possible positions in a two
positions in a two dimensional space) dimensional space. This includes real as well as imaginary numbers
@end itemize (@math{@var{a}+@var{b}i}, where @var{a} is the @dfn{real part},
@var{b} is the @dfn{imaginary part}, and @math{i} is the square root of
@minus{}1.)
@end table
It is called a tower because each category ``sits on'' the one that It is called a tower because each category ``sits on'' the one that
follows it, in the sense that every integer is also a rational, every follows it, in the sense that every integer is also a rational, every
@ -200,17 +200,14 @@ For example:
@lisp @lisp
(number? 3) (number? 3)
@result{} @result{} #t
#t
(number? "hello there!") (number? "hello there!")
@result{} @result{} #f
#f
(define pi 3.141592654) (define pi 3.141592654)
(number? pi) (number? pi)
@result{} @result{} #t
#t
@end lisp @end lisp
The next few subsections document each of Guile's numerical data types The next few subsections document each of Guile's numerical data types
@ -224,7 +221,7 @@ in detail.
@rnindex integer? @rnindex integer?
Integers are whole numbers, that is numbers with no fractional part, Integers are whole numbers, that is numbers with no fractional part,
such as 2, 83 and -3789. such as 2, 83, and @minus{}3789.
Integers in Guile can be arbitrarily big, as shown by the following Integers in Guile can be arbitrarily big, as shown by the following
example. example.
@ -237,16 +234,13 @@ example.
(loop (- n 1) (* product n))))) (loop (- n 1) (* product n)))))
(factorial 3) (factorial 3)
@result{} @result{} 6
6
(factorial 20) (factorial 20)
@result{} @result{} 2432902008176640000
2432902008176640000
(- (factorial 45)) (- (factorial 45))
@result{} @result{} -119622220865480194561963161495657715064383733760000000000
-119622220865480194561963161495657715064383733760000000000
@end lisp @end lisp
Readers whose background is in programming languages where integers are Readers whose background is in programming languages where integers are
@ -259,7 +253,7 @@ representation where the required number does not fit in the native
form. Conversion between these two representations is automatic and form. Conversion between these two representations is automatic and
completely invisible to the Scheme level programmer. completely invisible to the Scheme level programmer.
The infinities @code{+inf.0} and @code{-inf.0} are considered to be The infinities @samp{+inf.0} and @samp{-inf.0} are considered to be
inexact integers. They are explained in detail in the next section, inexact integers. They are explained in detail in the next section,
together with reals and rationals. together with reals and rationals.
@ -272,16 +266,13 @@ Return @code{#t} if @var{x} is an integer number, else @code{#f}.
@lisp @lisp
(integer? 487) (integer? 487)
@result{} @result{} #t
#t
(integer? -3.4) (integer? -3.4)
@result{} @result{} #f
#f
(integer? +inf.0) (integer? +inf.0)
@result{} @result{} #t
#t
@end lisp @end lisp
@end deffn @end deffn
@ -297,9 +288,9 @@ Return @code{#t} if @var{x} is an integer number, else @code{#f}.
Mathematically, the real numbers are the set of numbers that describe Mathematically, the real numbers are the set of numbers that describe
all possible points along a continuous, infinite, one-dimensional line. all possible points along a continuous, infinite, one-dimensional line.
The rational numbers are the set of all numbers that can be written as The rational numbers are the set of all numbers that can be written as
fractions P/Q, where P and Q are integers. All rational numbers are fractions @var{p}/@var{q}, where @var{p} and @var{q} are integers.
also real, but there are real numbers that are not rational, for example All rational numbers are also real, but there are real numbers that
the square root of 2, and pi. are not rational, for example the square root of 2, and pi.
Guile represents both real and rational numbers approximately using a Guile represents both real and rational numbers approximately using a
floating point encoding with limited precision. Even though the actual floating point encoding with limited precision. Even though the actual
@ -318,9 +309,9 @@ numbers. For example:
The limited precision of Guile's encoding means that any ``real'' number The limited precision of Guile's encoding means that any ``real'' number
in Guile can be written in a rational form, by multiplying and then dividing in Guile can be written in a rational form, by multiplying and then dividing
by sufficient powers of 10 (or in fact, 2). For example, by sufficient powers of 10 (or in fact, 2). For example,
@code{-0.00000142857931198} is the same as @code{142857931198} divided by @samp{-0.00000142857931198} is the same as @minus{}142857931198 divided by
@code{100000000000000000}. In Guile's current incarnation, therefore, 100000000000000000. In Guile's current incarnation, therefore, the
the @code{rational?} and @code{real?} predicates are equivalent. @code{rational?} and @code{real?} predicates are equivalent.
Another aspect of this equivalence is that Guile currently does not Another aspect of this equivalence is that Guile currently does not
preserve the exactness that is possible with rational arithmetic. preserve the exactness that is possible with rational arithmetic.
@ -344,13 +335,13 @@ respectibly. This syntax is also recognized by @code{read} as an
extension to the usual Scheme syntax. extension to the usual Scheme syntax.
Dividing zero by zero yields something that is not a number at all: Dividing zero by zero yields something that is not a number at all:
@samp{+nan.0}. This is the special 'not a number' value. @samp{+nan.0}. This is the special `not a number' value.
On platforms that follow IEEE 754 for their floating point arithmetic, On platforms that follow @acronym{IEEE} 754 for their floating point
the @samp{+inf.0}, @samp{-inf.0}, and @samp{+nan.0} values are arithmetic, the @samp{+inf.0}, @samp{-inf.0}, and @samp{+nan.0} values
implemented using the corresponding IEEE 754 values. They behave in are implemented using the corresponding @acronym{IEEE} 754 values.
arithmetic operations like IEEE 754 describes it, i.e., @code{(= They behave in arithmetic operations like @acronym{IEEE} 754 describes
+nan.0 +nan.0) @result{#f}}. it, i.e., @code{(= +nan.0 +nan.0) @result{#f}}.
The infinities are inexact integers and are considered to be both even The infinities are inexact integers and are considered to be both even
and odd. While @samp{+nan.0} is not @code{=} to itself, it is and odd. While @samp{+nan.0} is not @code{=} to itself, it is
@ -437,9 +428,9 @@ rational or integer number.
R5RS requires that a calculation involving inexact numbers always R5RS requires that a calculation involving inexact numbers always
produces an inexact result. To meet this requirement, Guile produces an inexact result. To meet this requirement, Guile
distinguishes between an exact integer value such as @code{5} and the distinguishes between an exact integer value such as @samp{5} and the
corresponding inexact real value which, to the limited precision corresponding inexact real value which, to the limited precision
available, has no fractional part, and is printed as @code{5.0}. Guile available, has no fractional part, and is printed as @samp{5.0}. Guile
will only convert the latter value to the former when forced to do so by will only convert the latter value to the former when forced to do so by
an invocation of the @code{inexact->exact} procedure. an invocation of the @code{inexact->exact} procedure.
@ -474,70 +465,71 @@ preceded by a minus or plus character, a code indicating the
base in which the integer is encoded, and a code indicating whether base in which the integer is encoded, and a code indicating whether
the number is exact or inexact. The supported base codes are: the number is exact or inexact. The supported base codes are:
@itemize @bullet @table @code
@item @item #b
@code{#b}, @code{#B} --- the integer is written in binary (base 2) @itemx #B
the integer is written in binary (base 2)
@item @item #o
@code{#o}, @code{#O} --- the integer is written in octal (base 8) @itemx #O
the integer is written in octal (base 8)
@item @item #d
@code{#d}, @code{#D} --- the integer is written in decimal (base 10) @itemx #D
the integer is written in decimal (base 10)
@item @item #x
@code{#x}, @code{#X} --- the integer is written in hexadecimal (base 16). @itemx #X
@end itemize the integer is written in hexadecimal (base 16)
@end table
If the base code is omitted, the integer is assumed to be decimal. The If the base code is omitted, the integer is assumed to be decimal. The
following examples show how these base codes are used. following examples show how these base codes are used.
@lisp @lisp
-13 -13
@result{} @result{} -13
-13
#d-13 #d-13
@result{} @result{} -13
-13
#x-13 #x-13
@result{} @result{} -19
-19
#b+1101 #b+1101
@result{} @result{} 13
13
#o377 #o377
@result{} @result{} 255
255
@end lisp @end lisp
The codes for indicating exactness (which can, incidentally, be applied The codes for indicating exactness (which can, incidentally, be applied
to all numerical values) are: to all numerical values) are:
@itemize @bullet @table @code
@item @item #e
@code{#e}, @code{#E} --- the number is exact @itemx #E
the number is exact
@item @item #i
@code{#i}, @code{#I} --- the number is inexact. @itemx #I
@end itemize the number is inexact.
@end table
If the exactness indicator is omitted, the integer is assumed to be exact, If the exactness indicator is omitted, the integer is assumed to be exact,
since Guile's internal representation for integers is always exact. since Guile's internal representation for integers is always exact.
Real numbers have limited precision similar to the precision of the Real numbers have limited precision similar to the precision of the
@code{double} type in C. A consequence of the limited precision is that @code{double} type in C. A consequence of the limited precision is that
all real numbers in Guile are also rational, since any number R with a all real numbers in Guile are also rational, since any number @var{r} with a
limited number of decimal places, say N, can be made into an integer by limited number of decimal places, say @var{n}, can be made into an integer by
multiplying by 10^N. multiplying by @math{10^n}.
Guile also understands the syntax @samp{+inf.0} and @samp{-inf.0} for Guile also understands the syntax @samp{+inf.0} and @samp{-inf.0} for
plus and minus infinity, respectively. The value must be written plus and minus infinity, respectively. The value must be written
exactly as shown, that is, the always must have a sign and exactly one exactly as shown, that is, the always must have a sign and exactly one
zero digit after the decimal point. It also understands @samp{+nan.0} zero digit after the decimal point. It also understands @samp{+nan.0}
and @samp{-nan.0} for the special 'not-a-number' value. The sign is and @samp{-nan.0} for the special `not-a-number' value. The sign is
ignored for 'not-a-number' and the value is always printed as @samp{+nan.0}. ignored for `not-a-number' and the value is always printed as @samp{+nan.0}.
@node Integer Operations @node Integer Operations
@subsection Operations on Integer Values @subsection Operations on Integer Values
@ -963,7 +955,8 @@ Return the arccosine of @var{x}.
@c begin (texi-doc-string "guile" "$atan") @c begin (texi-doc-string "guile" "$atan")
@deffn {Scheme Procedure} $atan x @deffn {Scheme Procedure} $atan x
Return the arctangent of @var{x} in the range -PI/2 to PI/2. Return the arctangent of @var{x} in the range @minus{}@math{PI/2} to
@math{PI/2}.
@end deffn @end deffn
@deffn {Scheme Procedure} $atan2 x y @deffn {Scheme Procedure} $atan2 x y
@ -1058,7 +1051,7 @@ Naturally, these C functions expect and return @code{double} arguments.
@subsection Bitwise Operations @subsection Bitwise Operations
@deffn {Scheme Procedure} logand n1 n2 @deffn {Scheme Procedure} logand n1 n2
Return the bitwise AND of the integer arguments. Return the bitwise @sc{and} of the integer arguments.
@lisp @lisp
(logand) @result{} -1 (logand) @result{} -1
@ -1068,7 +1061,7 @@ Return the bitwise AND of the integer arguments.
@end deffn @end deffn
@deffn {Scheme Procedure} logior n1 n2 @deffn {Scheme Procedure} logior n1 n2
Return the bitwise OR of the integer arguments. Return the bitwise @sc{or} of the integer arguments.
@lisp @lisp
(logior) @result{} 0 (logior) @result{} 0
@ -1078,7 +1071,7 @@ Return the bitwise OR of the integer arguments.
@end deffn @end deffn
@deffn {Scheme Procedure} logxor n1 n2 @deffn {Scheme Procedure} logxor n1 n2
Return the bitwise XOR of the integer arguments. A bit is Return the bitwise @sc{xor} of the integer arguments. A bit is
set in the result if it is set in an odd number of arguments. set in the result if it is set in an odd number of arguments.
@lisp @lisp
(logxor) @result{} 0 (logxor) @result{} 0
@ -1126,12 +1119,12 @@ argument.
@deffn {Scheme Procedure} ash n cnt @deffn {Scheme Procedure} ash n cnt
@deffnx {C Function} scm_ash (n, cnt) @deffnx {C Function} scm_ash (n, cnt)
The function ash performs an arithmetic shift left by @var{cnt} The function @code{ash} performs an arithmetic shift left by @var{cnt}
bits (or shift right, if @var{cnt} is negative). 'Arithmetic' bits (or shift right, if @var{cnt} is negative). `Arithmetic'
means, that the function does not guarantee to keep the bit means that the function does not guarantee to keep the bit
structure of @var{n}, but rather guarantees that the result structure of @var{n}, but rather guarantees that the result
will always be rounded towards minus infinity. Therefore, the will always be rounded towards minus infinity. Therefore, the
results of ash and a corresponding bitwise shift will differ if results of @code{ash} and a corresponding bitwise shift will differ if
@var{n} is negative. @var{n} is negative.
Formally, the function returns an integer equivalent to Formally, the function returns an integer equivalent to
@ -1212,11 +1205,11 @@ Return a copy of the random state @var{state}.
@deffn {Scheme Procedure} random n [state] @deffn {Scheme Procedure} random n [state]
@deffnx {C Function} scm_random (n, state) @deffnx {C Function} scm_random (n, state)
Return a number in [0, N). Return a number in [0, @var{n}).
Accepts a positive integer or real n and returns a Accepts a positive integer or real n and returns a
number of the same type between zero (inclusive) and number of the same type between zero (inclusive) and
N (exclusive). The values returned have a uniform @var{n} (exclusive). The values returned have a uniform
distribution. distribution.
The optional argument @var{state} must be of the type produced The optional argument @var{state} must be of the type produced
@ -1229,43 +1222,42 @@ as a side effect of the random operation.
@deffn {Scheme Procedure} random:exp [state] @deffn {Scheme Procedure} random:exp [state]
@deffnx {C Function} scm_random_exp (state) @deffnx {C Function} scm_random_exp (state)
Return an inexact real in an exponential distribution with mean Return an inexact real in an exponential distribution with mean
1. For an exponential distribution with mean u use (* u 1. For an exponential distribution with mean @var{u} use @code{(*
(random:exp)). @var{u} (random:exp))}.
@end deffn @end deffn
@deffn {Scheme Procedure} random:hollow-sphere! v [state] @deffn {Scheme Procedure} random:hollow-sphere! vect [state]
@deffnx {C Function} scm_random_hollow_sphere_x (v, state) @deffnx {C Function} scm_random_hollow_sphere_x (vect, state)
Fills vect with inexact real random numbers Fills @var{vect} with inexact real random numbers the sum of whose
the sum of whose squares is equal to 1.0. squares is equal to 1.0. Thinking of @var{vect} as coordinates in
Thinking of vect as coordinates in space of space of dimension @var{n} @math{=} @code{(vector-length @var{vect})},
dimension n = (vector-length vect), the coordinates the coordinates are uniformly distributed over the surface of the unit
are uniformly distributed over the surface of the n-sphere.
unit n-sphere.
@end deffn @end deffn
@deffn {Scheme Procedure} random:normal [state] @deffn {Scheme Procedure} random:normal [state]
@deffnx {C Function} scm_random_normal (state) @deffnx {C Function} scm_random_normal (state)
Return an inexact real in a normal distribution. The Return an inexact real in a normal distribution. The distribution
distribution used has mean 0 and standard deviation 1. For a used has mean 0 and standard deviation 1. For a normal distribution
normal distribution with mean m and standard deviation d use with mean @var{m} and standard deviation @var{d} use @code{(+ @var{m}
@code{(+ m (* d (random:normal)))}. (* @var{d} (random:normal)))}.
@end deffn @end deffn
@deffn {Scheme Procedure} random:normal-vector! v [state] @deffn {Scheme Procedure} random:normal-vector! vect [state]
@deffnx {C Function} scm_random_normal_vector_x (v, state) @deffnx {C Function} scm_random_normal_vector_x (vect, state)
Fills vect with inexact real random numbers that are Fills @var{vect} with inexact real random numbers that are
independent and standard normally distributed independent and standard normally distributed
(i.e., with mean 0 and variance 1). (i.e., with mean 0 and variance 1).
@end deffn @end deffn
@deffn {Scheme Procedure} random:solid-sphere! v [state] @deffn {Scheme Procedure} random:solid-sphere! vect [state]
@deffnx {C Function} scm_random_solid_sphere_x (v, state) @deffnx {C Function} scm_random_solid_sphere_x (vect, state)
Fills vect with inexact real random numbers Fills @var{vect} with inexact real random numbers the sum of whose
the sum of whose squares is less than 1.0. squares is less than 1.0. Thinking of @var{vect} as coordinates in
Thinking of vect as coordinates in space of space of dimension @var{n} @math{=} @code{(vector-length @var{vect})},
dimension n = (vector-length vect), the coordinates the coordinates are uniformly distributed within the unit
are uniformly distributed within the unit n-sphere. @var{n}-sphere. The sum of the squares of the numbers is returned.
The sum of the squares of the numbers is returned. @c FIXME: What does this mean, particularly the n-sphere part?
@end deffn @end deffn
@deffn {Scheme Procedure} random:uniform [state] @deffn {Scheme Procedure} random:uniform [state]
@ -1284,9 +1276,14 @@ Return a new random state using @var{seed}.
@section Characters @section Characters
@tpindex Characters @tpindex Characters
Most of the characters in the ASCII character set may be referred to by @noindent
name: for example, @code{#\tab}, @code{#\esc}, @code{#\stx}, and so on. [@strong{FIXME}: how do you specify regular (non-control) characters?]
The following table describes the ASCII names for each character.
Most of the ``control characters'' (those below codepoint 32) in the
@acronym{ASCII} character set, as well as the space, may be referred
to by name: for example, @code{#\tab}, @code{#\esc}, @code{#\stx}, and
so on. The following table describes the @acronym{ASCII} names for
each character.
@multitable @columnfractions .25 .25 .25 .25 @multitable @columnfractions .25 .25 .25 .25
@item 0 = @code{#\nul} @item 0 = @code{#\nul}
@ -1324,27 +1321,21 @@ The following table describes the ASCII names for each character.
@item 32 = @code{#\sp} @item 32 = @code{#\sp}
@end multitable @end multitable
The @code{delete} character (octal 177) may be referred to with the name The ``delete'' character (octal 177) may be referred to with the name
@code{#\del}. @code{#\del}.
Several characters have more than one name: Several characters have more than one name:
@itemize @bullet @multitable {@code{#\backspace}} {Original}
@item @item Alias @tab Original
@code{#\space}, @code{#\sp} @item @code{#\space} @tab @code{#\sp}
@item @item @code{#\newline} @tab @code{#\nl}
@code{#\newline}, @code{#\nl} @item @code{#\tab} @tab @code{#\ht}
@item @item @code{#\backspace} @tab @code{#\bs}
@code{#\tab}, @code{#\ht} @item @code{#\return} @tab @code{#\cr}
@item @item @code{#\page} @tab @code{#\np}
@code{#\backspace}, @code{#\bs} @item @code{#\null} @tab @code{#\nul}
@item @end multitable
@code{#\return}, @code{#\cr}
@item
@code{#\page}, @code{#\np}
@item
@code{#\null}, @code{#\nul}
@end itemize
@rnindex char? @rnindex char?
@deffn {Scheme Procedure} char? x @deffn {Scheme Procedure} char? x
@ -1359,26 +1350,26 @@ Return @code{#t} iff @var{x} is the same character as @var{y}, else @code{#f}.
@rnindex char<? @rnindex char<?
@deffn {Scheme Procedure} char<? x y @deffn {Scheme Procedure} char<? x y
Return @code{#t} iff @var{x} is less than @var{y} in the ASCII sequence, Return @code{#t} iff @var{x} is less than @var{y} in the @acronym{ASCII} sequence,
else @code{#f}. else @code{#f}.
@end deffn @end deffn
@rnindex char<=? @rnindex char<=?
@deffn {Scheme Procedure} char<=? x y @deffn {Scheme Procedure} char<=? x y
Return @code{#t} iff @var{x} is less than or equal to @var{y} in the Return @code{#t} iff @var{x} is less than or equal to @var{y} in the
ASCII sequence, else @code{#f}. @acronym{ASCII} sequence, else @code{#f}.
@end deffn @end deffn
@rnindex char>? @rnindex char>?
@deffn {Scheme Procedure} char>? x y @deffn {Scheme Procedure} char>? x y
Return @code{#t} iff @var{x} is greater than @var{y} in the ASCII Return @code{#t} iff @var{x} is greater than @var{y} in the @acronym{ASCII}
sequence, else @code{#f}. sequence, else @code{#f}.
@end deffn @end deffn
@rnindex char>=? @rnindex char>=?
@deffn {Scheme Procedure} char>=? x y @deffn {Scheme Procedure} char>=? x y
Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the
ASCII sequence, else @code{#f}. @acronym{ASCII} sequence, else @code{#f}.
@end deffn @end deffn
@rnindex char-ci=? @rnindex char-ci=?
@ -1389,81 +1380,81 @@ case, else @code{#f}.
@rnindex char-ci<? @rnindex char-ci<?
@deffn {Scheme Procedure} char-ci<? x y @deffn {Scheme Procedure} char-ci<? x y
Return @code{#t} iff @var{x} is less than @var{y} in the ASCII sequence Return @code{#t} iff @var{x} is less than @var{y} in the @acronym{ASCII} sequence
ignoring case, else @code{#f}. ignoring case, else @code{#f}.
@end deffn @end deffn
@rnindex char-ci<=? @rnindex char-ci<=?
@deffn {Scheme Procedure} char-ci<=? x y @deffn {Scheme Procedure} char-ci<=? x y
Return @code{#t} iff @var{x} is less than or equal to @var{y} in the Return @code{#t} iff @var{x} is less than or equal to @var{y} in the
ASCII sequence ignoring case, else @code{#f}. @acronym{ASCII} sequence ignoring case, else @code{#f}.
@end deffn @end deffn
@rnindex char-ci>? @rnindex char-ci>?
@deffn {Scheme Procedure} char-ci>? x y @deffn {Scheme Procedure} char-ci>? x y
Return @code{#t} iff @var{x} is greater than @var{y} in the ASCII Return @code{#t} iff @var{x} is greater than @var{y} in the @acronym{ASCII}
sequence ignoring case, else @code{#f}. sequence ignoring case, else @code{#f}.
@end deffn @end deffn
@rnindex char-ci>=? @rnindex char-ci>=?
@deffn {Scheme Procedure} char-ci>=? x y @deffn {Scheme Procedure} char-ci>=? x y
Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the
ASCII sequence ignoring case, else @code{#f}. @acronym{ASCII} sequence ignoring case, else @code{#f}.
@end deffn @end deffn
@rnindex char-alphabetic? @rnindex char-alphabetic?
@deffn {Scheme Procedure} char-alphabetic? chr @deffn {Scheme Procedure} char-alphabetic? chr
@deffnx {C Function} scm_char_alphabetic_p (chr) @deffnx {C Function} scm_char_alphabetic_p (chr)
Return @code{#t} iff @var{chr} is alphabetic, else @code{#f}. Return @code{#t} iff @var{chr} is alphabetic, else @code{#f}.
Alphabetic means the same thing as the isalpha C library function. Alphabetic means the same thing as the @code{isalpha} C library function.
@end deffn @end deffn
@rnindex char-numeric? @rnindex char-numeric?
@deffn {Scheme Procedure} char-numeric? chr @deffn {Scheme Procedure} char-numeric? chr
@deffnx {C Function} scm_char_numeric_p (chr) @deffnx {C Function} scm_char_numeric_p (chr)
Return @code{#t} iff @var{chr} is numeric, else @code{#f}. Return @code{#t} iff @var{chr} is numeric, else @code{#f}.
Numeric means the same thing as the isdigit C library function. Numeric means the same thing as the @code{isdigit} C library function.
@end deffn @end deffn
@rnindex char-whitespace? @rnindex char-whitespace?
@deffn {Scheme Procedure} char-whitespace? chr @deffn {Scheme Procedure} char-whitespace? chr
@deffnx {C Function} scm_char_whitespace_p (chr) @deffnx {C Function} scm_char_whitespace_p (chr)
Return @code{#t} iff @var{chr} is whitespace, else @code{#f}. Return @code{#t} iff @var{chr} is whitespace, else @code{#f}.
Whitespace means the same thing as the isspace C library function. Whitespace means the same thing as the @code{isspace} C library function.
@end deffn @end deffn
@rnindex char-upper-case? @rnindex char-upper-case?
@deffn {Scheme Procedure} char-upper-case? chr @deffn {Scheme Procedure} char-upper-case? chr
@deffnx {C Function} scm_char_upper_case_p (chr) @deffnx {C Function} scm_char_upper_case_p (chr)
Return @code{#t} iff @var{chr} is uppercase, else @code{#f}. Return @code{#t} iff @var{chr} is uppercase, else @code{#f}.
Uppercase means the same thing as the isupper C library function. Uppercase means the same thing as the @code{isupper} C library function.
@end deffn @end deffn
@rnindex char-lower-case? @rnindex char-lower-case?
@deffn {Scheme Procedure} char-lower-case? chr @deffn {Scheme Procedure} char-lower-case? chr
@deffnx {C Function} scm_char_lower_case_p (chr) @deffnx {C Function} scm_char_lower_case_p (chr)
Return @code{#t} iff @var{chr} is lowercase, else @code{#f}. Return @code{#t} iff @var{chr} is lowercase, else @code{#f}.
Lowercase means the same thing as the islower C library function. Lowercase means the same thing as the @code{islower} C library function.
@end deffn @end deffn
@deffn {Scheme Procedure} char-is-both? chr @deffn {Scheme Procedure} char-is-both? chr
@deffnx {C Function} scm_char_is_both_p (chr) @deffnx {C Function} scm_char_is_both_p (chr)
Return @code{#t} iff @var{chr} is either uppercase or lowercase, else @code{#f}. Return @code{#t} iff @var{chr} is either uppercase or lowercase, else
Uppercase and lowercase are as defined by the isupper and islower @code{#f}. Uppercase and lowercase are as defined by the
C library functions. @code{isupper} and @code{islower} C library functions.
@end deffn @end deffn
@rnindex char->integer @rnindex char->integer
@deffn {Scheme Procedure} char->integer chr @deffn {Scheme Procedure} char->integer chr
@deffnx {C Function} scm_char_to_integer (chr) @deffnx {C Function} scm_char_to_integer (chr)
Return the number corresponding to ordinal position of @var{chr} in the Return the number corresponding to ordinal position of @var{chr} in the
ASCII sequence. @acronym{ASCII} sequence.
@end deffn @end deffn
@rnindex integer->char @rnindex integer->char
@deffn {Scheme Procedure} integer->char n @deffn {Scheme Procedure} integer->char n
@deffnx {C Function} scm_integer_to_char (n) @deffnx {C Function} scm_integer_to_char (n)
Return the character at position @var{n} in the ASCII sequence. Return the character at position @var{n} in the @acronym{ASCII} sequence.
@end deffn @end deffn
@rnindex char-upcase @rnindex char-upcase
@ -1478,6 +1469,10 @@ Return the uppercase character version of @var{chr}.
Return the lowercase character version of @var{chr}. Return the lowercase character version of @var{chr}.
@end deffn @end deffn
@xref{Classification of Characters,,,libc,GNU C Library Reference
Manual}, for information about the @code{is*} Standard C functions
mentioned above.
@node Strings @node Strings
@section Strings @section Strings
@ -1485,7 +1480,7 @@ Return the lowercase character version of @var{chr}.
Strings are fixed-length sequences of characters. They can be created Strings are fixed-length sequences of characters. They can be created
by calling constructor procedures, but they can also literally get by calling constructor procedures, but they can also literally get
entered at the REPL or in Scheme source files. entered at the @acronym{REPL} or in Scheme source files.
Guile provides a rich set of string processing procedures, because text Guile provides a rich set of string processing procedures, because text
handling is very important when Guile is used as a scripting language. handling is very important when Guile is used as a scripting language.
@ -1493,7 +1488,7 @@ handling is very important when Guile is used as a scripting language.
Strings always carry the information about how many characters they are Strings always carry the information about how many characters they are
composed of with them, so there is no special end-of-string character, composed of with them, so there is no special end-of-string character,
like in C. That means that Scheme strings can contain any character, like in C. That means that Scheme strings can contain any character,
even the NUL character @code{'\0'}. But note: Since most operating even the @samp{NUL} character @samp{\0}. But note: Since most operating
system calls dealing with strings (such as for file operations) expect system calls dealing with strings (such as for file operations) expect
strings to be zero-terminated, they might do unexpected things when strings to be zero-terminated, they might do unexpected things when
called with string containing unusual characters. called with string containing unusual characters.
@ -1515,11 +1510,12 @@ called with string containing unusual characters.
@subsection String Read Syntax @subsection String Read Syntax
The read syntax for strings is an arbitrarily long sequence of The read syntax for strings is an arbitrarily long sequence of
characters enclosed in double quotes (@code{"}). @footnote{Actually, the characters enclosed in double quotes (@code{"}).@footnote{Actually,
current implementation restricts strings to a length of 2^24 the current implementation restricts strings to a length of
characters.} If you want to insert a double quote character into a @math{2^24}, or 16,777,216, characters. Sorry.} If you want to
string literal, it must be prefixed with a backslash @code{\} character insert a double quote character into a string literal, it must be
(called an @dfn{escape character}). prefixed with a backslash @samp{\} character (called an @dfn{escape
character}).
The following are examples of string literals: The following are examples of string literals:
@ -1656,7 +1652,7 @@ ending with index @var{end} (exclusive).
@var{str} must be a string, @var{start} and @var{end} must be @var{str} must be a string, @var{start} and @var{end} must be
exact integers satisfying: exact integers satisfying:
0 <= @var{start} <= @var{end} <= (string-length @var{str}). 0 <= @var{start} <= @var{end} <= @code{(string-length @var{str})}.
@end deffn @end deffn
@node String Modification @node String Modification
@ -2103,7 +2099,7 @@ specified @var{item}s and returns that.
@end deffn @end deffn
The following example takes a regular expression that matches a standard The following example takes a regular expression that matches a standard
YYYYMMDD-format date such as @code{"20020828"}. The @sc{yyyymmdd}-format date such as @code{"20020828"}. The
@code{regexp-substitute} call returns a string computed from the @code{regexp-substitute} call returns a string computed from the
information in the match structure, consisting of the fields and text information in the match structure, consisting of the fields and text
from the original string reordered and reformatted. from the original string reordered and reformatted.
@ -2124,7 +2120,7 @@ argument, @code{regexp-substitute/global} takes two string arguments: a
@var{regexp} string describing a regular expression, and a @var{target} @var{regexp} string describing a regular expression, and a @var{target}
string which should be matched against this regular expression. string which should be matched against this regular expression.
Each @var{item} behaves as in @var{regexp-substitute}, with the Each @var{item} behaves as in @code{regexp-substitute}, with the
following exceptions: following exceptions:
@itemize @bullet @itemize @bullet