mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-05-02 04:40:29 +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>
* scheme-modules.texi (Environments): only available when

346
doc/ref/posix.texi
View file

@ -1,5 +1,5 @@
@node POSIX
@chapter POSIX System Calls and Networking
@chapter @acronym{POSIX} System Calls and Networking
@menu
* Conventions:: Conventions employed by the POSIX interface.
@ -20,17 +20,17 @@
@end menu
@node Conventions
@section POSIX Interface Conventions
@section @acronym{POSIX} Interface Conventions
These interfaces provide access to operating system facilities.
They provide a simple wrapping around the underlying C interfaces
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
facility. There are some exceptions, such as procedures implemented for
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
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
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}
exception. The value of the Unix @code{errno} variable is available
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)}.
File ports are implemented using low-level operating system I/O
facilities, with optional buffering to improve efficiency
@pxref{File Ports}
facilities, with optional buffering to improve efficiency; see
@ref{File Ports}.
Note that some procedures (e.g., @code{recv!}) will accept ports as
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.
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.
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
can therefore ensure that the revealed count will be greater than
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
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
port is kept open (i.e., is pointed to by a live Scheme binding) while
the file descriptor is in use.
To correspond with traditional Unix behaviour, the three file
descriptors (0, 1 and 2) are automatically imported when a program
starts up and assigned to the initial values of the current input,
output and error ports. The revealed count for each is initially set to
one, so that dropping references to one of these ports will not result
in its garbage collection: it could be retrieved with fdopen or
fdes->ports.
To correspond with traditional Unix behaviour, three file descriptors
(0, 1, and 2) are automatically imported when a program starts up and
assigned to the initial values of the current/standard input, output,
and error ports, respectively. The revealed count for each is
initially set to one, so that dropping references to one of these
ports will not result in its garbage collection: it could be retrieved
with @code{fdopen} or @code{fdes->ports}.
@deffn {Scheme Procedure} 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
@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.
@end deffn
@ -169,10 +169,10 @@ side effect the revealed count of @var{port} is incremented.
@deffn {Scheme Procedure} fdopen fdes modes
@deffnx {C Function} scm_fdopen (fdes, modes)
Return a new port based on the file descriptor @var{fdes}.
Modes are given by the string @var{modes}. The revealed count
of the port is initialized to zero. The modes string is the
same as that accepted by @ref{File Ports, open-file}.
Return a new port based on the file descriptor @var{fdes}. Modes are
given by the string @var{modes}. The revealed count of the port is
initialized to zero. The @var{modes} string is the same as that
accepted by @code{open-file} (@pxref{File Ports, open-file}).
@end deffn
@deffn {Scheme Procedure} fdes->ports fd
@ -228,9 +228,9 @@ The return value is unspecified.
@deffnx {C Function} scm_open (path, flags, mode)
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{mode} is an integer specifying the permission bits of the file, if
it needs to be created, before the umask is applied. The default is 666
(Unix itself has no default).
@var{mode} is an integer specifying the permission bits of the file,
if it needs to be created, before the umask (@pxref{Processes}) is
applied. The default is 666 (Unix itself has no default).
@var{flags} can be constructed by combining variables using @code{logior}.
Basic flags are:
@ -251,7 +251,7 @@ Append to the file instead of truncating.
Create the file if it does not already exist.
@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.
@end deffn
@ -263,7 +263,7 @@ a port.
@deffn {Scheme Procedure} 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
effect of closing a file descriptor is that any ports using that file
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
@deffnx {C Function} scm_close_fdes (fd)
A simple wrapper for the @code{close} system call.
Close file descriptor @var{fd}, which must be an integer.
Unlike close (@pxref{Ports and File Descriptors, close}),
the file descriptor will be closed even if a port is using it.
The return value is unspecified.
A simple wrapper for the @code{close} system call. Close file
descriptor @var{fd}, which must be an integer. Unlike @code{close},
the file descriptor will be closed even if a port is using it. The
return value is unspecified.
@end deffn
@deffn {Scheme Procedure} 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
next read operation. If called multiple times, the unread characters
will be read again in last-in first-out order. If @var{port} is
not supplied, the current input port is used.
Place @var{char} in @var{port} so that it will be read by the next
read operation on that port. If called multiple times, the unread
characters will be read again in ``last-in, first-out'' order (i.e.@:
a stack). If @var{port} is not supplied, the current input port is
used.
@end deffn
@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
@deffnx {C Function} scm_pipe ()
Return a newly created pipe: a pair of ports which are linked
together on the local machine. The @emph{car} is the input
port and the @emph{cdr} is the output port. Data written (and
together on the local machine. The @acronym{CAR} is the input
port and the @acronym{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
@ -384,7 +384,7 @@ Copies the file descriptor @var{oldfd} to descriptor
number @var{newfd}, replacing the previous meaning
of @var{newfd}. Both @var{oldfd} and @var{newfd} must
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}.
The return value is unspecified.
@end deffn
@ -392,18 +392,19 @@ The return value is unspecified.
@deffn {Scheme Procedure} port-mode port
Return the port modes associated with the open port @var{port}.
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.
@end deffn
@deffn {Scheme Procedure} port-for-each proc
@deffnx {C Function} scm_port_for_each (proc)
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,
@var{proc} is applied exactly once to every port that exists
in the system at the time @var{port-for-each} is invoked.
Changes to the port table while @var{port-for-each} is running
have no effect as far as @var{port-for-each} is concerned.
@var{proc} is applied exactly once to every port that exists in the
system at the time @code{port-for-each} is invoked. Changes to the
port table while @code{port-for-each} is running have no effect as far
as @code{port-for-each} is concerned.
@end deffn
@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
Set the process that owns a socket to @var{value}, for @code{SIGIO} signals.
@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}.
@end table
@end deffn
@ -593,8 +594,9 @@ from stat:mode in a more convenient form:
@table @code
@item stat:type
A symbol representing the type of file. Possible values are
regular, directory, symlink, block-special, char-special, fifo,
socket and unknown
@samp{regular}, @samp{directory}, @samp{symlink},
@samp{block-special}, @samp{char-special}, @samp{fifo}, @samp{socket},
and @samp{unknown}.
@item stat:perms
An integer representing the access permission bits.
@end table
@ -617,12 +619,12 @@ string), i.e., the file that the link points to.
@findex lchown
@deffn {Scheme Procedure} 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
the integer values @var{owner} and @var{group}. @var{object} can be
a string containing a file name or, if the platform
supports fchown, a port or integer file descriptor
which is open on the file. The return value
is unspecified.
Change the ownership and group of the file referred to by @var{object}
to the integer values @var{owner} and @var{group}. @var{object} can
be a string containing a file name or, if the platform supports
@code{fchown} (@pxref{File Owner,,,libc,The GNU C Library Reference
Manual}), a port or integer file descriptor which is open on the file.
The return value is unspecified.
If @var{object} is a symbolic link, either the
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
@deffn {Scheme Procedure} 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
@deffn {Scheme Procedure} 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.
@end deffn
@ -686,16 +689,16 @@ system.
@deffn {Scheme Procedure} 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)
@var{path-from}. The return value is unspecified.
Create a symbolic link named @var{newpath} with the value (i.e., pointing to)
@var{oldpath}. The return value is unspecified.
@end deffn
@deffn {Scheme Procedure} mkdir path [mode]
@deffnx {C Function} scm_mkdir (path, mode)
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
umask. Otherwise they are set to the decimal value specified with
@var{mode}. The return value is unspecified.
umask (@pxref{Processes}). Otherwise they are set to the decimal
value specified with @var{mode}. The return value is unspecified.
@end deffn
@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
@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.
@end deffn
@deffn {Scheme Procedure} directory-stream? obj
@deffnx {C Function} scm_directory_stream_p (obj)
@deffn {Scheme Procedure} directory-stream? object
@deffnx {C Function} scm_directory_stream_p (object)
Return a boolean indicating whether @var{object} is a directory
stream as returned by @code{opendir}.
@end deffn
@deffn {Scheme Procedure} readdir port
@deffnx {C Function} scm_readdir (port)
@deffn {Scheme Procedure} readdir stream
@deffnx {C Function} scm_readdir (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
end of file object is returned.
@end deffn
@deffn {Scheme Procedure} rewinddir port
@deffnx {C Function} scm_rewinddir (port)
@deffn {Scheme Procedure} rewinddir stream
@deffnx {C Function} scm_rewinddir (stream)
Reset the directory port @var{stream} so that the next call to
@code{readdir} will return the first directory entry.
@end deffn
@deffn {Scheme Procedure} closedir port
@deffnx {C Function} scm_closedir (port)
@deffn {Scheme Procedure} closedir stream
@deffnx {C Function} scm_closedir (stream)
Close the directory stream @var{stream}.
The return value is unspecified.
@end deffn
@ -755,13 +758,13 @@ The return value is unspecified.
@deffn {Scheme Procedure} 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.
@var{path} specifies the name of the file. @var{type} should
be one of the following symbols:
regular, directory, symlink, block-special, char-special,
fifo, or socket. @var{perms} (an integer) specifies the file permissions.
@var{dev} (an integer) specifies which device the special file refers
to. Its exact interpretation depends on the kind of special file
being created.
@var{path} specifies the name of the file. @var{type} should be one
of the following symbols: @samp{regular}, @samp{directory},
@samp{symlink}, @samp{block-special}, @samp{char-special},
@samp{fifo}, or @samp{socket}. @var{perms} (an integer) specifies the
file permissions. @var{dev} (an integer) specifies which device the
special file refers to. Its exact interpretation depends on the kind
of special file being created.
E.g.,
@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
buffered port open for reading and writing to the file.
@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.
@end deffn
@ -949,14 +952,14 @@ information cannot be obtained.
@deffn {Scheme Procedure} 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.
@end deffn
@deffn {Scheme Procedure} gettimeofday
@deffnx {C Function} scm_gettimeofday ()
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
operating system.
@end deffn
@ -984,10 +987,10 @@ Day of the week (0-6) with Sunday represented as 0.
@item tm:yday, set-tm:yday
Day of the year (0-364, 365 in leap years).
@item tm:isdst, set-tm:isdst
Daylight saving indicator (0 for "no", greater than 0 for "yes", less than
0 for "unknown").
Daylight saving indicator (0 for ``no'', greater than 0 for ``yes'', less than
0 for ``unknown'').
@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
Time zone label (a string), not necessarily unique.
@end table
@ -998,31 +1001,32 @@ Return an object representing the broken down components of
@var{time}, an integer like the one returned by
@code{current-time}. The time zone for the calculation is
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
@deffn {Scheme Procedure} gmtime time
@deffnx {C Function} scm_gmtime (time)
Return 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.
@code{current-time}. The values are calculated for @acronym{UTC}.
@end deffn
@deffn {Scheme Procedure} 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}
is an optional time zone specifier (otherwise the TZ environment variable
or the system default is used).
@var{sbd-time} is an object representing broken down time and
@code{zone} is an optional time zone specifier (otherwise the @env{TZ}
environment variable or the system default is used).
Returns a pair: the car is a corresponding
integer time value like that returned
by @code{current-time}; the cdr is a broken down time object, similar to
as @var{bd-time} but with normalized values.
Returns a pair: the @acronym{CAR} is a corresponding integer time
value like that returned by @code{current-time}; the @acronym{CDR} is
a broken down time object, similar to @var{sbd-time} but with
normalized values; i.e.@: with corrected @code{tm:wday} and
@code{tm:yday} fields.
@end deffn
@deffn {Scheme Procedure} 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
since it's done automatically by other procedures that depend on the
timezone.
@ -1033,10 +1037,10 @@ timezone.
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
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
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
(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{template}. The interpretation of month and day names is
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},
but the time zone components
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.
@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
environment, which is also the default environment for child
processes, to the supplied list of strings. Each member of
@var{env} should be of the form @code{NAME=VALUE} and values of
@code{NAME} should not be duplicated. If @var{env} is supplied
@var{env} should be of the form @var{NAME}=@var{VALUE} and values of
@var{NAME} should not be duplicated. If @var{env} is supplied
then the return value is unspecified.
@end deffn
@ -1182,11 +1186,13 @@ Return the name of the current working directory.
@deffn {Scheme Procedure} umask [mode]
@deffnx {C Function} scm_umask (mode)
If @var{mode} is omitted, returns a decimal number representing the current
file creation mask. Otherwise the file creation mask is set to
@var{mode} and the previous value is returned.
If @var{mode} is omitted, returns a decimal number representing the
current file creation mask. Otherwise the file creation mask is set
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
@deffn {Scheme Procedure} chroot path
@ -1259,7 +1265,7 @@ The return value is unspecified.
@deffnx {C Function} scm_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
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.
The return value is unspecified.
@end deffn
@ -1268,7 +1274,7 @@ The return value is unspecified.
@deffnx {C Function} scm_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
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.
The return value is unspecified.
@end deffn
@ -1276,7 +1282,7 @@ The return value is unspecified.
@deffn {Scheme Procedure} getpgrp
@deffnx {C Function} scm_getpgrp ()
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
@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:
@table @r
@table @asis
@item @var{pid} greater than 0
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.
@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
group.
@item @var{pid} less than -1
Request status information for any child process whose process group ID
is -@var{PID}.
is @minus{}@var{pid}.
@end table
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]
@deffnx {C Function} scm_system (cmd)
Execute @var{cmd} using the operating system's "command
processor". Under Unix this is usually the default shell
Execute @var{cmd} using the operating system's ``command
processor''. Under Unix this is usually the default shell
@code{sh}. The value returned is @var{cmd}'s exit status as
returned by @code{waitpid}, which can be interpreted using the
functions above.
@ -1421,7 +1427,7 @@ call, but we call it @code{execle} because of its Scheme calling interface.
@deffn {Scheme Procedure} primitive-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
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
identifier for @code{PRIO_USER}. A zero value of @var{who}
denotes the current process, process group, or user.
@var{prio} is a value in the range -20 and 20, the default
priority is 0; lower priorities cause more favorable
scheduling. Sets the priority of all of the specified
processes. Only the super-user may lower priorities.
The return value is not specified.
@var{prio} is a value in the range [@minus{}20,20]. The default
priority is 0; lower priorities (in numerical terms) cause more
favorable scheduling. Sets the priority of all of the specified
processes. Only the super-user may lower priorities. The return
value is not specified.
@end deffn
@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
or user, as indicated by @var{which} and @var{who}. @var{which}
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},
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
the highest priority (lowest numerical value) of any of the
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:
@table @r
@table @asis
@item @var{pid} greater than 0
The process whose identifier is @var{pid}.
@item @var{pid} equal to 0
@ -1502,12 +1508,15 @@ Hang-up signal.
@defvar SIGINT
Interrupt signal.
@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
@deffn {Scheme Procedure} raise sig
@deffnx {C Function} scm_raise (sig)
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
@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}.
If @var{handler} is omitted, @code{sigaction} returns a pair: the
CAR is the current
signal hander, which will be either an integer with the value @code{SIG_DFL}
(default action) or @code{SIG_IGN} (ignore), or the Scheme procedure which
handles the signal, or @code{#f} if a non-Scheme procedure handles the
signal. The CDR contains the current @code{sigaction} flags for the handler.
@acronym{CAR} is the current signal hander, which will be either an
integer with the value @code{SIG_DFL} (default action) or
@code{SIG_IGN} (ignore), or the Scheme procedure which handles the
signal, or @code{#f} if a non-Scheme procedure handles the signal.
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
@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
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
provide solutions to the problem of consistent access to data
structures.
@ -1580,8 +1590,8 @@ of seconds remaining otherwise.
@deffn {Scheme Procedure} usleep i
@deffnx {C Function} scm_usleep (i)
Sleep for I microseconds. @code{usleep} is not available on
all platforms.
Sleep for @var{i} microseconds. @code{usleep} is not available on
all platforms. [FIXME: so what happens when it isn't?]
@end deffn
@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.
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},
and @code{ITIMER_PROF}.
@ -1605,9 +1613,7 @@ the seconds and microseconds of the timer @code{it_value}.
@deffn {Scheme Procedure} getitimer which_timer
@deffnx {C Function} scm_getitimer (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''.
Return information about the timer specified by @var{which_timer}.
The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
and @code{ITIMER_PROF}.
@ -1667,7 +1673,7 @@ controlling terminal. The return value is unspecified.
@section Pipes
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:
@smalllisp
@ -1826,7 +1832,7 @@ The following functions accept a host object and return a selected
component:
@deffn {Scheme Procedure} hostent:name host
The "official" hostname for @var{host}.
The ``official'' hostname for @var{host}.
@end deffn
@deffn {Scheme Procedure} hostent:aliases 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:
@deffn {Scheme Procedure} netent:name net
The "official" network name.
The ``official'' network name.
@end deffn
@deffn {Scheme Procedure} netent:aliases net
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:
@deffn {Scheme Procedure} protoent:name protocol
The "official" protocol name.
The ``official'' protocol name.
@end deffn
@deffn {Scheme Procedure} protoent:aliases 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:
@deffn {Scheme Procedure} servent:name serv
The "official" name of the network service.
The ``official'' name of the network service.
@end deffn
@deffn {Scheme Procedure} servent:aliases serv
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}.
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
@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
are always held in host order at the Scheme level. The procedures in
this section automatically convert between host and network order when
required. The arguments and return values are thus in host order.
The convention used for ``host'' vs.@: ``network'' addresses is that
addresses are always held in host order at the Scheme level. The
procedures in this section automatically convert between host and
network order when required. The arguments and return values are thus
in host order.
@deffn {Scheme Procedure} 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.
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
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.
@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
will be irrevocably lost.
The optional @var{flags} argument is a value or
bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.
The optional @var{flags} argument is a value or bitwise OR of
@code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
The value returned is the number of bytes read from the
socket.
@ -2324,14 +2331,11 @@ any unread buffered port data is ignored.
@deffn {Scheme Procedure} send sock message [flags]
@deffnx {C Function} scm_send (sock, message, flags)
Transmit the string @var{message} on a socket port @var{sock}.
@var{sock} must already be bound to a destination address. The
value returned is the number of bytes transmitted --
it's possible for
this to be less than the length of @var{message}
if the socket is
set to be non-blocking. The optional @var{flags} argument
is a value or
bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.
@var{sock} must already be bound to a destination address. The value
returned is the number of bytes transmitted---it's possible for this
to be less than the length of @var{message} if the socket is set to be
non-blocking. The optional @var{flags} argument is a value or bitwise
OR of @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
Note that the data is written directly to the socket
file descriptor:
@ -2352,8 +2356,8 @@ data will be irrevocably lost.
The optional @var{flags} argument is a value or bitwise OR of
@code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
The value returned is a pair: the @emph{car} is the number of
bytes read from the socket and the @emph{cdr} an address object
The value returned is a pair: the @acronym{CAR} is the number of
bytes read from the socket and the @acronym{CDR} an address object
in the same form as returned by @code{accept}. The address
will given as @code{#f} if not available, as is usually the
case for stream sockets.
@ -2375,7 +2379,7 @@ destination address is specified using the @var{fam},
@code{connect} procedure. @var{args_and_flags} contains
the usual connection arguments optionally followed by
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 --
it's possible for
@ -2388,7 +2392,7 @@ any unflushed buffered port data is ignored.
@end deffn
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
be done when sending or receiving encoded integer data from the network.
@ -2479,8 +2483,8 @@ client.
@example
(let ((s (socket AF_INET SOCK_STREAM 0)))
(setsockopt s SOL_SOCKET SO_REUSEADDR 1)
;; Specific address?
;; (bind s AF_INET (inet-aton "127.0.0.1") 2904)
;; @r{Specific address?}
;; @r{(bind s AF_INET (inet-aton "127.0.0.1") 2904)}
(bind s AF_INET INADDR_ANY 2904)
(listen s 5)
@ -2498,7 +2502,7 @@ client.
(gethostbyaddr
(sockaddr:addr client-details)))
(newline)
;; Send back the greeting to the client port
;; @r{Send back the greeting to the client port}
(display "Hello client\r\n" client)
(close client))))
@end example
@ -2547,10 +2551,12 @@ specified.
@c FIXME::martin: Not in libguile!
@deffn {Scheme Procedure} software-type
Return a symbol describing the current platform's operating system.
This may be one of AIX, VMS, UNIX, COHERENT, WINDOWS, MS-DOS, OS/2,
THINKC, AMIGA, ATARIST, MACH, or ACORN.
This may be one of @samp{AIX}, @samp{VMS}, @samp{UNIX},
@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
on every operating system, it is usually better to test for the presence
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]
@deffnx {C Function} scm_setlocale (category, locale)
If @var{locale} is omitted, return the current value of the
specified locale category as a system-dependent string.
@var{category} should be specified using the values
@code{LC_COLLATE}, @code{LC_ALL} etc.
If @var{locale} is omitted, return the current value of the specified
locale @var{category} as a system-dependent string. @var{category}
should be specified using the values @code{LC_COLLATE}, @code{LC_ALL}
etc; see @inforef{Locating Catalogs,, gettext}.
Otherwise the specified locale category is set to the string
@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
primarily used for their role as items of generic data. By
@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
@ref{Compound Data Types}.
One of the great strengths of Scheme is that there is no straightforward
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
@item
@ -59,16 +59,13 @@ equality predicates @code{eq?}, @code{eqv?} and @code{equal?}
@lisp
(<= 3 8)
@result{}
#t
@result{} #t
(<= 3 -3)
@result{}
#f
@result{} #f
(equal? "house" "houses")
@result{}
#f
@result{} #f
(eq? #f #f)
@result{}
@ -82,16 +79,13 @@ value at all except @code{#f}.
@lisp
(if #t "yes" "no")
@result{}
"yes"
@result{} "yes"
(if 0 "yes" "no")
@result{}
"yes"
@result{} "yes"
(if #f "yes" "no")
@result{}
"no"
@result{} "no"
@end lisp
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
in Scheme, which is particularly clear and accessible: see
@xref{Numbers,,,r5rs}.
@ref{Numbers,,,r5rs,R5RS}.
@menu
* 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
numbers:
@itemize @bullet
@item
integers (whole numbers)
@table @dfn
@item integers
Whole numbers, positive or negative; e.g.@: --5, 0, 18.
@item
rationals (the set of numbers that can be expressed as P/Q where P and Q
are integers)
@item rationals
The set of numbers that can be expressed as @math{@var{p}/@var{q}}
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
real numbers (the set of numbers that describes all possible positions
along a one dimensional line)
@item real numbers
The set of numbers that describes all possible positions along a
one-dimensional line. This includes rationals as well as irrational
numbers.
@item
complex numbers (the set of numbers that describes all possible
positions in a two dimensional space)
@end itemize
@item complex numbers
The set of numbers that describes all possible positions in a two
dimensional space. This includes real as well as imaginary numbers
(@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
follows it, in the sense that every integer is also a rational, every
@ -200,17 +200,14 @@ For example:
@lisp
(number? 3)
@result{}
#t
@result{} #t
(number? "hello there!")
@result{}
#f
@result{} #f
(define pi 3.141592654)
(number? pi)
@result{}
#t
@result{} #t
@end lisp
The next few subsections document each of Guile's numerical data types
@ -224,7 +221,7 @@ in detail.
@rnindex integer?
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
example.
@ -237,16 +234,13 @@ example.
(loop (- n 1) (* product n)))))
(factorial 3)
@result{}
6
@result{} 6
(factorial 20)
@result{}
2432902008176640000
@result{} 2432902008176640000
(- (factorial 45))
@result{}
-119622220865480194561963161495657715064383733760000000000
@result{} -119622220865480194561963161495657715064383733760000000000
@end lisp
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
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,
together with reals and rationals.
@ -272,16 +266,13 @@ Return @code{#t} if @var{x} is an integer number, else @code{#f}.
@lisp
(integer? 487)
@result{}
#t
@result{} #t
(integer? -3.4)
@result{}
#f
@result{} #f
(integer? +inf.0)
@result{}
#t
@result{} #t
@end lisp
@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
all possible points along a continuous, infinite, one-dimensional line.
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
also real, but there are real numbers that are not rational, for example
the square root of 2, and pi.
fractions @var{p}/@var{q}, where @var{p} and @var{q} are integers.
All rational numbers are also real, but there are real numbers that
are not rational, for example the square root of 2, and pi.
Guile represents both real and rational numbers approximately using a
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
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,
@code{-0.00000142857931198} is the same as @code{142857931198} divided by
@code{100000000000000000}. In Guile's current incarnation, therefore,
the @code{rational?} and @code{real?} predicates are equivalent.
@samp{-0.00000142857931198} is the same as @minus{}142857931198 divided by
100000000000000000. In Guile's current incarnation, therefore, the
@code{rational?} and @code{real?} predicates are equivalent.
Another aspect of this equivalence is that Guile currently does not
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.
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,
the @samp{+inf.0}, @samp{-inf.0}, and @samp{+nan.0} values are
implemented using the corresponding IEEE 754 values. They behave in
arithmetic operations like IEEE 754 describes it, i.e., @code{(=
+nan.0 +nan.0) @result{#f}}.
On platforms that follow @acronym{IEEE} 754 for their floating point
arithmetic, the @samp{+inf.0}, @samp{-inf.0}, and @samp{+nan.0} values
are implemented using the corresponding @acronym{IEEE} 754 values.
They behave in arithmetic operations like @acronym{IEEE} 754 describes
it, i.e., @code{(= +nan.0 +nan.0) @result{#f}}.
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
@ -437,9 +428,9 @@ rational or integer number.
R5RS requires that a calculation involving inexact numbers always
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
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
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
the number is exact or inexact. The supported base codes are:
@itemize @bullet
@item
@code{#b}, @code{#B} --- the integer is written in binary (base 2)
@table @code
@item #b
@itemx #B
the integer is written in binary (base 2)
@item
@code{#o}, @code{#O} --- the integer is written in octal (base 8)
@item #o
@itemx #O
the integer is written in octal (base 8)
@item
@code{#d}, @code{#D} --- the integer is written in decimal (base 10)
@item #d
@itemx #D
the integer is written in decimal (base 10)
@item
@code{#x}, @code{#X} --- the integer is written in hexadecimal (base 16).
@end itemize
@item #x
@itemx #X
the integer is written in hexadecimal (base 16)
@end table
If the base code is omitted, the integer is assumed to be decimal. The
following examples show how these base codes are used.
@lisp
-13
@result{}
-13
@result{} -13
#d-13
@result{}
-13
@result{} -13
#x-13
@result{}
-19
@result{} -19
#b+1101
@result{}
13
@result{} 13
#o377
@result{}
255
@result{} 255
@end lisp
The codes for indicating exactness (which can, incidentally, be applied
to all numerical values) are:
@itemize @bullet
@item
@code{#e}, @code{#E} --- the number is exact
@table @code
@item #e
@itemx #E
the number is exact
@item
@code{#i}, @code{#I} --- the number is inexact.
@end itemize
@item #i
@itemx #I
the number is inexact.
@end table
If the exactness indicator is omitted, the integer is assumed to be exact,
since Guile's internal representation for integers is always exact.
Real numbers have limited precision similar to the precision of the
@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
limited number of decimal places, say N, can be made into an integer by
multiplying by 10^N.
all real numbers in Guile are also rational, since any number @var{r} with a
limited number of decimal places, say @var{n}, can be made into an integer by
multiplying by @math{10^n}.
Guile also understands the syntax @samp{+inf.0} and @samp{-inf.0} for
plus and minus infinity, respectively. The value must be written
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}
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}.
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}.
@node Integer Operations
@subsection Operations on Integer Values
@ -963,7 +955,8 @@ Return the arccosine of @var{x}.
@c begin (texi-doc-string "guile" "$atan")
@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
@deffn {Scheme Procedure} $atan2 x y
@ -1058,7 +1051,7 @@ Naturally, these C functions expect and return @code{double} arguments.
@subsection Bitwise Operations
@deffn {Scheme Procedure} logand n1 n2
Return the bitwise AND of the integer arguments.
Return the bitwise @sc{and} of the integer arguments.
@lisp
(logand) @result{} -1
@ -1068,7 +1061,7 @@ Return the bitwise AND of the integer arguments.
@end deffn
@deffn {Scheme Procedure} logior n1 n2
Return the bitwise OR of the integer arguments.
Return the bitwise @sc{or} of the integer arguments.
@lisp
(logior) @result{} 0
@ -1078,7 +1071,7 @@ Return the bitwise OR of the integer arguments.
@end deffn
@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.
@lisp
(logxor) @result{} 0
@ -1126,12 +1119,12 @@ argument.
@deffn {Scheme Procedure} ash n cnt
@deffnx {C Function} scm_ash (n, cnt)
The function ash performs an arithmetic shift left by @var{cnt}
bits (or shift right, if @var{cnt} is negative). 'Arithmetic'
means, that the function does not guarantee to keep the bit
The function @code{ash} performs an arithmetic shift left by @var{cnt}
bits (or shift right, if @var{cnt} is negative). `Arithmetic'
means that the function does not guarantee to keep the bit
structure of @var{n}, but rather guarantees that the result
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.
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]
@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
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.
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]
@deffnx {C Function} scm_random_exp (state)
Return an inexact real in an exponential distribution with mean
1. For an exponential distribution with mean u use (* u
(random:exp)).
1. For an exponential distribution with mean @var{u} use @code{(*
@var{u} (random:exp))}.
@end deffn
@deffn {Scheme Procedure} random:hollow-sphere! v [state]
@deffnx {C Function} scm_random_hollow_sphere_x (v, state)
Fills vect with inexact real random numbers
the sum of whose squares is equal to 1.0.
Thinking of vect as coordinates in space of
dimension n = (vector-length vect), the coordinates
are uniformly distributed over the surface of the
unit n-sphere.
@deffn {Scheme Procedure} random:hollow-sphere! vect [state]
@deffnx {C Function} scm_random_hollow_sphere_x (vect, state)
Fills @var{vect} with inexact real random numbers the sum of whose
squares is equal to 1.0. Thinking of @var{vect} as coordinates in
space of dimension @var{n} @math{=} @code{(vector-length @var{vect})},
the coordinates are uniformly distributed over the surface of the unit
n-sphere.
@end deffn
@deffn {Scheme Procedure} random:normal [state]
@deffnx {C Function} scm_random_normal (state)
Return an inexact real in a normal distribution. The
distribution used has mean 0 and standard deviation 1. For a
normal distribution with mean m and standard deviation d use
@code{(+ m (* d (random:normal)))}.
Return an inexact real in a normal distribution. The distribution
used has mean 0 and standard deviation 1. For a normal distribution
with mean @var{m} and standard deviation @var{d} use @code{(+ @var{m}
(* @var{d} (random:normal)))}.
@end deffn
@deffn {Scheme Procedure} random:normal-vector! v [state]
@deffnx {C Function} scm_random_normal_vector_x (v, state)
Fills vect with inexact real random numbers that are
@deffn {Scheme Procedure} random:normal-vector! vect [state]
@deffnx {C Function} scm_random_normal_vector_x (vect, state)
Fills @var{vect} with inexact real random numbers that are
independent and standard normally distributed
(i.e., with mean 0 and variance 1).
@end deffn
@deffn {Scheme Procedure} random:solid-sphere! v [state]
@deffnx {C Function} scm_random_solid_sphere_x (v, state)
Fills vect with inexact real random numbers
the sum of whose squares is less than 1.0.
Thinking of vect as coordinates in space of
dimension n = (vector-length vect), the coordinates
are uniformly distributed within the unit n-sphere.
The sum of the squares of the numbers is returned.
@deffn {Scheme Procedure} random:solid-sphere! vect [state]
@deffnx {C Function} scm_random_solid_sphere_x (vect, state)
Fills @var{vect} with inexact real random numbers the sum of whose
squares is less than 1.0. Thinking of @var{vect} as coordinates in
space of dimension @var{n} @math{=} @code{(vector-length @var{vect})},
the coordinates are uniformly distributed within the unit
@var{n}-sphere. The sum of the squares of the numbers is returned.
@c FIXME: What does this mean, particularly the n-sphere part?
@end deffn
@deffn {Scheme Procedure} random:uniform [state]
@ -1284,9 +1276,14 @@ Return a new random state using @var{seed}.
@section Characters
@tpindex Characters
Most of the characters in the ASCII character set may be referred to by
name: for example, @code{#\tab}, @code{#\esc}, @code{#\stx}, and so on.
The following table describes the ASCII names for each character.
@noindent
[@strong{FIXME}: how do you specify regular (non-control) characters?]
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
@item 0 = @code{#\nul}
@ -1324,27 +1321,21 @@ The following table describes the ASCII names for each character.
@item 32 = @code{#\sp}
@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}.
Several characters have more than one name:
@itemize @bullet
@item
@code{#\space}, @code{#\sp}
@item
@code{#\newline}, @code{#\nl}
@item
@code{#\tab}, @code{#\ht}
@item
@code{#\backspace}, @code{#\bs}
@item
@code{#\return}, @code{#\cr}
@item
@code{#\page}, @code{#\np}
@item
@code{#\null}, @code{#\nul}
@end itemize
@multitable {@code{#\backspace}} {Original}
@item Alias @tab Original
@item @code{#\space} @tab @code{#\sp}
@item @code{#\newline} @tab @code{#\nl}
@item @code{#\tab} @tab @code{#\ht}
@item @code{#\backspace} @tab @code{#\bs}
@item @code{#\return} @tab @code{#\cr}
@item @code{#\page} @tab @code{#\np}
@item @code{#\null} @tab @code{#\nul}
@end multitable
@rnindex char?
@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<?
@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}.
@end deffn
@rnindex char<=?
@deffn {Scheme Procedure} char<=? x y
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
@rnindex char>?
@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}.
@end deffn
@rnindex char>=?
@deffn {Scheme Procedure} char>=? x y
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
@rnindex char-ci=?
@ -1389,81 +1380,81 @@ case, else @code{#f}.
@rnindex char-ci<?
@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}.
@end deffn
@rnindex char-ci<=?
@deffn {Scheme Procedure} char-ci<=? x y
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
@rnindex char-ci>?
@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}.
@end deffn
@rnindex char-ci>=?
@deffn {Scheme Procedure} char-ci>=? x y
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
@rnindex char-alphabetic?
@deffn {Scheme Procedure} char-alphabetic? chr
@deffnx {C Function} scm_char_alphabetic_p (chr)
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
@rnindex char-numeric?
@deffn {Scheme Procedure} char-numeric? chr
@deffnx {C Function} scm_char_numeric_p (chr)
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
@rnindex char-whitespace?
@deffn {Scheme Procedure} char-whitespace? chr
@deffnx {C Function} scm_char_whitespace_p (chr)
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
@rnindex char-upper-case?
@deffn {Scheme Procedure} char-upper-case? chr
@deffnx {C Function} scm_char_upper_case_p (chr)
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
@rnindex char-lower-case?
@deffn {Scheme Procedure} char-lower-case? chr
@deffnx {C Function} scm_char_lower_case_p (chr)
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
@deffn {Scheme Procedure} char-is-both? chr
@deffnx {C Function} scm_char_is_both_p (chr)
Return @code{#t} iff @var{chr} is either uppercase or lowercase, else @code{#f}.
Uppercase and lowercase are as defined by the isupper and islower
C library functions.
Return @code{#t} iff @var{chr} is either uppercase or lowercase, else
@code{#f}. Uppercase and lowercase are as defined by the
@code{isupper} and @code{islower} C library functions.
@end deffn
@rnindex char->integer
@deffn {Scheme Procedure} char->integer chr
@deffnx {C Function} scm_char_to_integer (chr)
Return the number corresponding to ordinal position of @var{chr} in the
ASCII sequence.
@acronym{ASCII} sequence.
@end deffn
@rnindex integer->char
@deffn {Scheme Procedure} integer->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
@rnindex char-upcase
@ -1478,6 +1469,10 @@ Return the uppercase character version of @var{chr}.
Return the lowercase character version of @var{chr}.
@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
@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
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
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
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,
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
strings to be zero-terminated, they might do unexpected things when
called with string containing unusual characters.
@ -1515,11 +1510,12 @@ called with string containing unusual characters.
@subsection String Read Syntax
The read syntax for strings is an arbitrarily long sequence of
characters enclosed in double quotes (@code{"}). @footnote{Actually, the
current implementation restricts strings to a length of 2^24
characters.} If you want to insert a double quote character into a
string literal, it must be prefixed with a backslash @code{\} character
(called an @dfn{escape character}).
characters enclosed in double quotes (@code{"}).@footnote{Actually,
the current implementation restricts strings to a length of
@math{2^24}, or 16,777,216, characters. Sorry.} If you want to
insert a double quote character into a string literal, it must be
prefixed with a backslash @samp{\} character (called an @dfn{escape
character}).
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
exact integers satisfying:
0 <= @var{start} <= @var{end} <= (string-length @var{str}).
0 <= @var{start} <= @var{end} <= @code{(string-length @var{str})}.
@end deffn
@node String Modification
@ -2103,7 +2099,7 @@ specified @var{item}s and returns that.
@end deffn
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
information in the match structure, consisting of the fields and text
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}
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:
@itemize @bullet