mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-04-30 03:40:34 +02:00
Code Activity

* scheme-options.texi, scheme-procedures.texi,

Browse source 
scheme-modules.texi, scheme-memory.texi, scheme-control.texi,
	scheme-utility.texi, scheme-io.texi, scheme-evaluation.texi,
	scheme-data.texi: Removed a lot of ARGFIXME's after tweaking
	docstrings and C source.

	* new-docstrings.texi, scheme-io.texi, scheme-data.texi,
	posix.texi, scheme-control.texi, scheme-evaluation.texi,
	scheme-memory.texi, scheme-procedures.texi, scheme-modules.texi,
	scheme-scheduling.texi: Automated docstring merging.
This commit is contained in:
Martin Grabmüller 2001-04-03 13:11:14 +00:00
parent abaec75d1d
commit ae9f3a1582
15 changed files with 1641 additions and 1875 deletions
Download patch file Download diff file Expand all files Collapse all files

13
doc/ChangeLog
View file

@ -1,3 +1,16 @@
2001-04-03 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
* scheme-options.texi, scheme-procedures.texi,
scheme-modules.texi, scheme-memory.texi, scheme-control.texi,
scheme-utility.texi, scheme-io.texi, scheme-evaluation.texi,
scheme-data.texi: Removed a lot of ARGFIXME's after tweaking
docstrings and C source.
* new-docstrings.texi, scheme-io.texi, scheme-data.texi,
posix.texi, scheme-control.texi, scheme-evaluation.texi,
scheme-memory.texi, scheme-procedures.texi, scheme-modules.texi,
scheme-scheduling.texi: Automated docstring merging.
2001-04-02 Neil Jerram <neil@ossau.uklinux.net>
* data-rep.texi (Immediates vs. Non-immediates): Update

4
doc/maint/ChangeLog
View file

@ -1,3 +1,7 @@
2001-04-03 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
* guile.texi: Automated docstring merging.
2001-03-23 Neil Jerram <neil@ossau.uklinux.net>
* ChangeLog, README, docstring.el, guile.texi: New files.

1713
doc/maint/guile.texi
View file

File diff suppressed because it is too large Load diff

19
doc/new-docstrings.texi
View file

@ -29,26 +29,26 @@ If @var{env} contains no bindings, this function simply returns
@var{init}.
If @var{env} binds the symbol sym1 to the value val1, sym2 to
val2, and so on, then this procedure computes:
@example
@lisp
(proc sym1 val1
(proc sym2 val2
...
(proc symn valn
init)))
@end example
@end lisp
Each binding in @var{env} will be processed exactly once.
@code{environment-fold} makes no guarantees about the order in
which the bindings are processed.
Here is a function which, given an environment, constructs an
association list representing that environment's bindings,
using environment-fold:
@example
@lisp
(define (environment->alist env)
(environment-fold env
(lambda (sym val tail)
(cons (cons sym val) tail))
'()))
@end example
@end lisp
@end deffn
@deffn primitive environment-define env sym val
@ -586,12 +586,11 @@ crypt(3) library call
@end deffn
@deffn primitive mkstemp! tmpl
mkstemp creates 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 place to return the name of the
temporary file.
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
place to return the name of the temporary file.
@end deffn
@deffn primitive %tag-body body

493
doc/posix.texi
View file

@ -152,7 +152,7 @@ fdes->ports.
@c docstring begin (texi-doc-string "guile" "port-revealed")
@deffn primitive port-revealed port
Returns the revealed count for @var{port}.
Return the revealed count for @var{port}.
@end deffn
@c docstring begin (texi-doc-string "guile" "set-port-revealed!")
@ -163,8 +163,8 @@ The return value is unspecified.
@c docstring begin (texi-doc-string "guile" "fileno")
@deffn primitive fileno port
Returns the integer file descriptor underlying @var{port}.
Does not change its revealed count.
Return the integer file descriptor underlying @var{port}. Does
not change its revealed count.
@end deffn
@deffn procedure port->fdes port
@ -174,16 +174,17 @@ side effect the revealed count of @var{port} is incremented.
@c docstring begin (texi-doc-string "guile" "fdopen")
@deffn primitive fdopen fdes modes
Returns 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 modes string is the
same as that accepted by @ref{File Ports, open-file}.
@end deffn
@c docstring begin (texi-doc-string "guile" "fdes->ports")
@deffn primitive fdes->ports fd
Returns a list of existing ports which have @var{fdes} as an
underlying file descriptor, without changing their revealed counts.
Return a list of existing ports which have @var{fdes} as an
underlying file descriptor, without changing their revealed
counts.
@end deffn
@deffn procedure fdes->inport fdes
@ -261,8 +262,8 @@ for additional flags.
@c docstring begin (texi-doc-string "guile" "open-fdes")
@deffn primitive open-fdes path flags [mode]
Similar to @code{open} but returns a file descriptor instead of a
port.
Similar to @code{open} but return a file descriptor instead of
a port.
@end deffn
@c docstring begin (texi-doc-string "guile" "close")
@ -300,19 +301,18 @@ unread characters will be read again in last-in first-out order. If
@c docstring begin (texi-doc-string "guile" "pipe")
@deffn primitive pipe
Returns a newly created pipe: a pair of ports which are linked
together on the local machine. The CAR is the input port and
the CDR is the output port. Data written (and flushed) to the
output port can be read from the input port.
Pipes are commonly used for communication with a newly
forked child process. The need to flush the output port
can be avoided by making it unbuffered using @code{setvbuf}.
Writes occur atomically provided the size of the data in
bytes is not greater than the value of @code{PIPE_BUF}
Note that the output port is likely to block if too much data
(typically equal to @code{PIPE_BUF}) has been written but not
yet read from the input port.
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
flushed) to the output port can be read from the input port.
Pipes are commonly used for communication with a newly forked
child process. The need to flush the output port can be
avoided by making it unbuffered using @code{setvbuf}.
Writes occur atomically provided the size of the data in bytes
is not greater than the value of @code{PIPE_BUF}. Note that
the output port is likely to block if too much data (typically
equal to @code{PIPE_BUF}) has been written but not yet read
from the input port.
@end deffn
The next group of procedures perform a @code{dup2}
@ -327,7 +327,9 @@ their revealed counts set to zero.
@c docstring begin (texi-doc-string "guile" "dup->fdes")
@deffn primitive dup->fdes fd_or_port [fd]
Returns an integer file descriptor.
Return a new integer file descriptor referring to the open file
designated by @var{fd_or_port}, which must be either an open
file port or a file descriptor.
@end deffn
@deffn procedure dup->inport port/fd [newfd]
@ -393,10 +395,10 @@ The return value is unspecified.
@c docstring begin (texi-doc-string "guile" "port-mode")
@deffn primitive port-mode port
Returns the port modes associated with the open port @var{port}. These
will not necessarily be identical to the modes used when the port was
opened, since modes such as "append" which are used only during
port creation are not retained.
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
used only during port creation are not retained.
@end deffn
@c docstring begin (texi-doc-string "guile" "close-all-ports-except")
@ -506,19 +508,15 @@ contents; syncing the file system and creating special files.
@c docstring begin (texi-doc-string "guile" "access?")
@deffn primitive access? path how
Returns @code{#t} if @var{path} corresponds to an existing
file and the current process
has the type of access specified by @var{how}, otherwise
@code{#f}.
@var{how} should be specified
using the values of the variables listed below. Multiple values can
be combined using a bitwise or, in which case @code{#t} will only
be returned if all accesses are granted.
Permissions are checked using the real id of the current process,
not the effective id, although it's the effective id which determines
whether the access would actually be granted.
Return @code{#t} if @var{path} corresponds to an existing file
and the current process has the type of access specified by
@var{how}, otherwise @code{#f}. @var{how} should be specified
using the values of the variables listed below. Multiple
values can be combined using a bitwise or, in which case
@code{#t} will only be returned if all accesses are granted.
Permissions are checked using the real id of the current
process, not the effective id, although it's the effective id
which determines whether the access would actually be granted.
@defvar R_OK
test for read permission.
@end defvar
@ -536,25 +534,24 @@ test for existence of the file.
@findex fstat
@c docstring begin (texi-doc-string "guile" "stat")
@deffn primitive stat object
Returns an object containing various information
about the file determined by @var{obj}.
@var{obj} can be a string containing a file name or a port or integer file
descriptor which is open on a file (in which case @code{fstat} is used
as the underlying system call).
The object returned by @code{stat} can be passed as a single parameter
to the following procedures, all of which return integers:
Return an object containing various information about the file
determined by @var{obj}. @var{obj} can be a string containing
a file name or a port or integer file descriptor which is open
on a file (in which case @code{fstat} is used as the underlying
system call).
The object returned by @code{stat} can be passed as a single
parameter to the following procedures, all of which return
integers:
@table @code
@item stat:dev
The device containing the file.
@item stat:ino
The file serial number, which distinguishes this file from all other
files on the same device.
The file serial number, which distinguishes this file from all
other files on the same device.
@item stat:mode
The mode of the file. This includes file type information
and the file permission bits. See @code{stat:type} and @code{stat:perms}
below.
The mode of the file. This includes file type information and
the file permission bits. See @code{stat:type} and
@code{stat:perms} below.
@item stat:nlink
The number of hard links to the file.
@item stat:uid
@ -573,20 +570,19 @@ The last modification time for the file.
@item stat:ctime
The last modification time for the attributes of the file.
@item stat:blksize
The optimal block size for reading or writing the file, in bytes.
The optimal block size for reading or writing the file, in
bytes.
@item stat:blocks
The amount of disk space that the file occupies measured in units of
512 byte blocks.
The amount of disk space that the file occupies measured in
units of 512 byte blocks.
@end table
In addition, the following procedures return the information
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
regular, directory, symlink, block-special, char-special, fifo,
socket and unknown
@item stat:perms
An integer representing the access permission bits.
@end table
@ -601,9 +597,8 @@ file it points to. @var{path} must be a string.
@c docstring begin (texi-doc-string "guile" "readlink")
@deffn primitive readlink path
Returns the value of the symbolic link named by
@var{path} (a string), i.e., the
file that the link points to.
Return the value of the symbolic link named by @var{path} (a
string), i.e., the file that the link points to.
@end deffn
@findex fchown
@ -638,21 +633,16 @@ The return value is unspecified.
@c docstring begin (texi-doc-string "guile" "utime")
@deffn primitive utime pathname [actime [modtime]]
@code{utime} sets the access and modification times for
the file named by @var{path}. If @var{actime} or @var{modtime}
is not supplied, then the current time is used.
@var{actime} and @var{modtime}
must be integer time values as returned by the @code{current-time}
procedure.
E.g.,
@smalllisp
@code{utime} sets the access and modification times for the
file named by @var{path}. If @var{actime} or @var{modtime} is
not supplied, then the current time is used. @var{actime} and
@var{modtime} must be integer time values as returned by the
@code{current-time} procedure.
@lisp
(utime "foo" (- (current-time) 3600))
@end smalllisp
will set the access time to one hour in the past and the modification
time to the current time.
@end lisp
will set the access time to one hour in the past and the
modification time to the current time.
@end deffn
@findex unlink
@ -710,8 +700,8 @@ stream.
@c docstring begin (texi-doc-string "guile" "directory-stream?")
@deffn primitive directory-stream? obj
Returns a boolean indicating whether @var{object} is a directory stream
as returned by @code{opendir}.
Return a boolean indicating whether @var{object} is a directory
stream as returned by @code{opendir}.
@end deffn
@c docstring begin (texi-doc-string "guile" "readdir")
@ -751,20 +741,20 @@ to. Its exact interpretation depends on the kind of special file
being created.
E.g.,
@example
@lisp
(mknod "/dev/fd0" 'block-special #o660 (+ (* 2 256) 2))
@end example
@end lisp
The return value is unspecified.
@end deffn
@c docstring begin (texi-doc-string "guile" "tmpnam")
@deffn primitive tmpnam
tmpnam returns a name in the file system that does not match
any existing file. However there is no guarantee that
another process will not create the file after tmpnam
is called. Care should be taken if opening the file,
e.g., use the O_EXCL open flag or use @code{mkstemp!} instead.
Return a name in the file system that does not match any
existing file. However there is no guarantee that another
process will not create the file after @code{tmpnam} is called.
Care should be taken if opening the file, e.g., use the
@code{O_EXCL} open flag or use @code{mkstemp!} instead.
@end deffn
@c docstring begin (texi-doc-string "guile" "dirname")
@ -904,15 +894,16 @@ or getgrent respectively.
@c docstring begin (texi-doc-string "guile" "current-time")
@deffn primitive current-time
Returns the number of seconds since 1970-01-01 00:00:00 UTC, excluding
leap seconds.
Return the number of seconds since 1970-01-01 00:00:00 UTC,
excluding leap seconds.
@end deffn
@c docstring begin (texi-doc-string "guile" "gettimeofday")
@deffn primitive gettimeofday
Returns a pair containing the number of seconds and microseconds since
1970-01-01 00:00:00 UTC, excluding leap seconds. Note: whether true
microsecond resolution is available depends on the operating system.
Return a pair containing the number of seconds and microseconds
since 1970-01-01 00:00:00 UTC, excluding leap seconds. Note:
whether true microsecond resolution is available depends on the
operating system.
@end deffn
The following procedures either accept an object representing a broken down
@ -948,18 +939,18 @@ Time zone label (a string), not necessarily unique.
@c docstring begin (texi-doc-string "guile" "localtime")
@deffn primitive localtime time [zone]
Returns an object representing the broken down components of @var{time},
an integer like the one returned by @code{current-time}. The time zone
for the calculation is optionally specified by @var{zone} (a string),
otherwise the @code{TZ} environment variable or the system default is
used.
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.
@end deffn
@c docstring begin (texi-doc-string "guile" "gmtime")
@deffn primitive gmtime time
Returns an object representing the broken down components of @var{time},
an integer like the one returned by @code{current-time}. The values
are calculated for UTC.
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.
@end deffn
@c docstring begin (texi-doc-string "guile" "mktime")
@ -1014,10 +1005,9 @@ reported by the following procedures.
@c docstring begin (texi-doc-string "guile" "times")
@deffn primitive times
Returns an object with information about real and processor time.
The following procedures accept such an object as an argument and
return a selected component:
Return an object with information about real and processor
time. The following procedures accept such an object as an
argument and return a selected component:
@table @code
@item tms:clock
The current real time, expressed as time units relative to an
@ -1025,10 +1015,12 @@ arbitrary base.
@item tms:utime
The CPU time units used by the calling process.
@item tms:stime
The CPU time units used by the system on behalf of the calling process.
The CPU time units used by the system on behalf of the calling
process.
@item tms:cutime
The CPU time units used by terminated child processes of the calling
process, whose status has been collected (e.g., using @code{waitpid}).
The CPU time units used by terminated child processes of the
calling process, whose status has been collected (e.g., using
@code{waitpid}).
@item tms:cstime
Similarly, the CPU times units used by the system on behalf of
terminated child processes.
@ -1037,13 +1029,15 @@ terminated child processes.
@c docstring begin (texi-doc-string "guile" "get-internal-real-time")
@deffn primitive get-internal-real-time
Returns the number of time units since the interpreter was started.
Return the number of time units since the interpreter was
started.
@end deffn
@c docstring begin (texi-doc-string "guile" "get-internal-run-time")
@deffn primitive get-internal-run-time
Returns the number of time units of processor time used by the interpreter.
Both "system" and "user" time are included but subprocesses are not.
Return the number of time units of processor time used by the
interpreter. Both @emph{system} and @emph{user} time are
included but subprocesses are not.
@end deffn
@node Runtime Environment
@ -1080,12 +1074,13 @@ The return value is unspecified.
@c docstring begin (texi-doc-string "guile" "environ")
@deffn primitive environ [env]
If @var{env} is omitted, returns the current environment as a list of strings.
Otherwise it sets 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 then the return value is unspecified.
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
then the return value is unspecified.
@end deffn
@c docstring begin (texi-doc-string "guile" "putenv")
@ -1117,7 +1112,7 @@ The return value is unspecified.
@findex pwd
@c docstring begin (texi-doc-string "guile" "getcwd")
@deffn primitive getcwd
Returns the name of the current working directory.
Return the name of the current working directory.
@end deffn
@c docstring begin (texi-doc-string "guile" "umask")
@ -1131,43 +1126,45 @@ E.g., @code{(umask #o022)} sets the mask to octal 22, decimal 18.
@c docstring begin (texi-doc-string "guile" "getpid")
@deffn primitive getpid
Returns an integer representing the current process ID.
Return an integer representing the current process ID.
@end deffn
@c docstring begin (texi-doc-string "guile" "getgroups")
@deffn primitive getgroups
Returns a vector of integers representing the current supplimentary group IDs.
Return a vector of integers representing the current
supplimentary group IDs.
@end deffn
@c docstring begin (texi-doc-string "guile" "getppid")
@deffn primitive getppid
Returns an integer representing the process ID of the parent process.
Return an integer representing the process ID of the parent
process.
@end deffn
@c docstring begin (texi-doc-string "guile" "getuid")
@deffn primitive getuid
Returns an integer representing the current real user ID.
Return an integer representing the current real user ID.
@end deffn
@c docstring begin (texi-doc-string "guile" "getgid")
@deffn primitive getgid
Returns an integer representing the current real group ID.
Return an integer representing the current real group ID.
@end deffn
@c docstring begin (texi-doc-string "guile" "geteuid")
@deffn primitive geteuid
Returns an integer representing the current effective user ID.
Return an integer representing the current effective user ID.
If the system does not support effective IDs, then the real ID
is returned. @code{(feature? 'EIDs)} reports whether the system
supports effective IDs.
is returned. @code{(feature? 'EIDs)} reports whether the
system supports effective IDs.
@end deffn
@c docstring begin (texi-doc-string "guile" "getegid")
@deffn primitive getegid
Returns an integer representing the current effective group ID.
Return an integer representing the current effective group ID.
If the system does not support effective IDs, then the real ID
is returned. @code{(feature? 'EIDs)} reports whether the system
supports effective IDs.
is returned. @code{(feature? 'EIDs)} reports whether the
system supports effective IDs.
@end deffn
@c docstring begin (texi-doc-string "guile" "setuid")
@ -1204,7 +1201,7 @@ The return value is unspecified.
@c docstring begin (texi-doc-string "guile" "getpgrp")
@deffn primitive getpgrp
Returns an integer representing the current process group ID.
Return an integer representing the current process group ID.
This is the POSIX definition, not BSD.
@end deffn
@ -1276,31 +1273,31 @@ by @code{waitpid}.
@c docstring begin (texi-doc-string "guile" "status:exit-val")
@deffn primitive status:exit-val status
Returns the exit status value, as would be
set if a process ended normally through a
call to @code{exit} or @code{_exit}, if any, otherwise @code{#f}.
Return the exit status value, as would be set if a process
ended normally through a call to @code{exit} or @code{_exit},
if any, otherwise @code{#f}.
@end deffn
@c docstring begin (texi-doc-string "guile" "status:term-sig")
@deffn primitive status:term-sig status
Returns the signal number which terminated the
process, if any, otherwise @code{#f}.
Return the signal number which terminated the process, if any,
otherwise @code{#f}.
@end deffn
@c docstring begin (texi-doc-string "guile" "status:stop-sig")
@deffn primitive status:stop-sig status
Returns the signal number which stopped the
process, if any, otherwise @code{#f}.
Return the signal number which stopped the process, if any,
otherwise @code{#f}.
@end deffn
@c docstring begin (texi-doc-string "guile" "system")
@deffn primitive system [cmd]
Executes @var{cmd} using the operating system's "command processor".
Under Unix this is usually the default shell @code{sh}. The value
returned is @var{cmd}'s exit status as returned by @code{waitpid}, which
can be interpreted using the functions above.
If @code{system} is called without arguments, it returns a boolean
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.
If @code{system} is called without arguments, return a boolean
indicating whether the command processor is available.
@end deffn
@ -1480,28 +1477,27 @@ all platforms.
@c docstring begin (texi-doc-string "guile" "isatty?")
@deffn primitive isatty? port
Returns @code{#t} if @var{port} is using a serial
non-file device, otherwise @code{#f}.
Return @code{#t} if @var{port} is using a serial non--file
device, otherwise @code{#f}.
@end deffn
@c docstring begin (texi-doc-string "guile" "ttyname")
@deffn primitive ttyname port
Returns a string with the name of the serial terminal device underlying
@var{port}.
Return a string with the name of the serial terminal device
underlying @var{port}.
@end deffn
@c docstring begin (texi-doc-string "guile" "ctermid")
@deffn primitive ctermid
Returns a string containing the file name of the controlling terminal
for the current process.
Return a string containing the file name of the controlling
terminal for the current process.
@end deffn
@c docstring begin (texi-doc-string "guile" "tcgetpgrp")
@deffn primitive tcgetpgrp port
Returns the process group ID of the foreground
process group associated with the terminal open on the file descriptor
Return the process group ID of the foreground process group
associated with the terminal open on the file descriptor
underlying @var{port}.
If there is no foreground process group, the return value is a
number greater than 1 that does not match the process group ID
of any existing process group. This can happen if all of the
@ -1575,52 +1571,48 @@ the database routines since they are not reentrant.
@c docstring begin (texi-doc-string "guile" "inet-aton")
@deffn primitive inet-aton address
Converts a string containing an Internet host address in the traditional
dotted decimal notation into an integer.
@smalllisp
Converts a string containing an Internet host address in the
traditional dotted decimal notation into an integer.
@lisp
(inet-aton "127.0.0.1") @result{} 2130706433
@end smalllisp
@end lisp
@end deffn
@c docstring begin (texi-doc-string "guile" "inet-ntoa")
@deffn primitive inet-ntoa inetid
Converts an integer Internet host address into a string with the
traditional dotted decimal representation.
@smalllisp
Converts an integer Internet host address into a string with
the traditional dotted decimal representation.
@lisp
(inet-ntoa 2130706433) @result{} "127.0.0.1"
@end smalllisp
@end lisp
@end deffn
@c docstring begin (texi-doc-string "guile" "inet-netof")
@deffn primitive inet-netof address
Returns the network number part of the given integer Internet address.
@smalllisp
Return the network number part of the given integer Internet
address.
@lisp
(inet-netof 2130706433) @result{} 127
@end smalllisp
@end lisp
@end deffn
@c docstring begin (texi-doc-string "guile" "inet-lnaof")
@deffn primitive inet-lnaof address
Returns the local-address-with-network part of the given Internet
address.
@smalllisp
Return the local-address-with-network part of the given
Internet address.
@lisp
(inet-lnaof 2130706433) @result{} 1
@end smalllisp
@end lisp
@end deffn
@c docstring begin (texi-doc-string "guile" "inet-makeaddr")
@deffn primitive inet-makeaddr net lna
Makes an Internet host address by combining the network number @var{net}
with the local-address-within-network number @var{lna}.
@smalllisp
Makes an Internet host address by combining the network number
@var{net} with the local-address-within-network number
@var{lna}.
@lisp
(inet-makeaddr 127 1) @result{} 2130706433
@end smalllisp
@end lisp
@end deffn
@subsubsection The Host Database
@ -1881,40 +1873,38 @@ required. The arguments and return values are thus in host order.
@c docstring begin (texi-doc-string "guile" "socket")
@deffn primitive socket family style proto
Returns a new socket port of the type specified by @var{family}, @var{style}
and @var{protocol}. All three parameters are integers. Typical values
for @var{family} are the values of @code{AF_UNIX}
and @code{AF_INET}. Typical values for @var{style} are
the values of @code{SOCK_STREAM}, @code{SOCK_DGRAM} and @code{SOCK_RAW}.
Return a new socket port of the type specified by @var{family},
@var{style} and @var{protocol}. All three parameters are
integers. Typical values for @var{family} are the values of
@code{AF_UNIX} and @code{AF_INET}. Typical values for
@var{style} are the values of @code{SOCK_STREAM},
@code{SOCK_DGRAM} and @code{SOCK_RAW}.
@var{protocol} can be obtained from a protocol name using
@code{getprotobyname}. A value of
zero specifies the default protocol, which is usually right.
A single socket port cannot by used for communication until
it has been connected to another socket.
@code{getprotobyname}. A value of zero specifies the default
protocol, which is usually right.
A single socket port cannot by used for communication until it
has been connected to another socket.
@end deffn
@c docstring begin (texi-doc-string "guile" "socketpair")
@deffn primitive socketpair family style proto
Returns a pair of connected (but unnamed) socket ports of the type specified
by @var{family}, @var{style} and @var{protocol}.
Many systems support only
socket pairs of the @code{AF_UNIX} family. Zero is likely to be
the only meaningful value for @var{protocol}.
Return a pair of connected (but unnamed) socket ports of the
type specified by @var{family}, @var{style} and @var{protocol}.
Many systems support only socket pairs of the @code{AF_UNIX}
family. Zero is likely to be the only meaningful value for
@var{protocol}.
@end deffn
@c docstring begin (texi-doc-string "guile" "getsockopt")
@deffn primitive getsockopt sock level optname
Returns the value of a particular socket option for the socket
port @var{socket}. @var{level} is an integer code for type of option
being requested, e.g., @code{SOL_SOCKET} for socket-level options.
@var{optname} is an
integer code for the option required and should be specified using one of
the symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc.
The returned value is typically an integer but @code{SO_LINGER} returns a
pair of integers.
Return the value of a particular socket option for the socket
port @var{socket}. @var{level} is an integer code for type of
option being requested, e.g., @code{SOL_SOCKET} for
socket-level options. @var{optname} is an integer code for the
option required and should be specified using one of the
symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc.
The returned value is typically an integer but @code{SO_LINGER}
returns a pair of integers.
@end deffn
@c docstring begin (texi-doc-string "guile" "setsockopt")
@ -2060,17 +2050,17 @@ number.
@c docstring begin (texi-doc-string "guile" "getsockname")
@deffn primitive getsockname sock
Returns the address of @var{socket}, in the same form as the object
returned by @code{accept}. On many systems the address of a socket
in the @code{AF_FILE} namespace cannot be read.
Return the address of @var{socket}, in the same form as the
object returned by @code{accept}. On many systems the address
of a socket in the @code{AF_FILE} namespace cannot be read.
@end deffn
@c docstring begin (texi-doc-string "guile" "getpeername")
@deffn primitive getpeername sock
Returns the address of the socket that the socket @var{socket} is connected to,
in the same form as the object
returned by @code{accept}. On many systems the address of a socket
in the @code{AF_FILE} namespace cannot be read.
Return the address of the socket that the socket @var{socket}
is connected to, in the same form as the object returned by
@code{accept}. On many systems the address of a socket in the
@code{AF_FILE} namespace cannot be read.
@end deffn
@c docstring begin (texi-doc-string "guile" "recv!")
@ -2107,27 +2097,23 @@ any unflushed buffered port data is ignored.
@c docstring begin (texi-doc-string "guile" "recvfrom!")
@deffn primitive recvfrom! sock str [flags [start [end]]]
Returns data from the socket port @var{socket} and also information about
where the data was received from. @var{socket} must already
be bound to the address from which data is to be received.
@code{str}, is a string into which
the data will be written. The size of @var{str} limits the amount of
data which can be received: in the case of packet
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 value returned is a pair: the CAR is the number of bytes read from
the socket and the CDR an address object in the same form as returned by
@code{accept}.
The @var{start} and @var{end} arguments specify a substring of @var{str}
to which the data should be written.
Note that the data is read directly from the socket file descriptor:
any unread buffered port data is ignored.
Return data from the socket port @var{socket} and also
information about where the data was received from.
@var{socket} must already be bound to the address from which
data is to be received. @code{str}, is a string into which the
data will be written. The size of @var{str} limits the amount
of data which can be received: in the case of packet 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
@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
in the same form as returned by @code{accept}.
The @var{start} and @var{end} arguments specify a substring of
@var{str} to which the data should be written.
Note that the data is read directly from the socket file
descriptor: any unread buffered port data is ignored.
@end deffn
@c docstring begin (texi-doc-string "guile" "sendto")
@ -2152,30 +2138,30 @@ be done when sending or receiving encoded integer data from the network.
@c docstring begin (texi-doc-string "guile" "htons")
@deffn primitive htons in
Returns a new integer from @var{value} by converting from host to
network order. @var{value} must be within the range of a C unsigned
short integer.
Return a new integer from @var{value} by converting from host
to network order. @var{value} must be within the range of a C
unsigned short integer.
@end deffn
@c docstring begin (texi-doc-string "guile" "ntohs")
@deffn primitive ntohs in
Returns a new integer from @var{value} by converting from network to
host order. @var{value} must be within the range of a C unsigned short
integer.
Return a new integer from @var{value} by converting from
network to host order. @var{value} must be within the range of
a C unsigned short integer.
@end deffn
@c docstring begin (texi-doc-string "guile" "htonl")
@deffn primitive htonl in
Returns a new integer from @var{value} by converting from host to
network order. @var{value} must be within the range of a C unsigned
long integer.
Return a new integer from @var{value} by converting from host
to network order. @var{value} must be within the range of a C
unsigned long integer.
@end deffn
@c docstring begin (texi-doc-string "guile" "ntohl")
@deffn primitive ntohl in
Returns a new integer from @var{value} by converting from network to
host order. @var{value} must be within the range of a C unsigned
long integer.
Return a new integer from @var{value} by converting from
network to host order. @var{value} must be within the range of
a C unsigned long integer.
@end deffn
These procedures are inconvenient to use at present, but consider:
@ -2199,8 +2185,8 @@ These procedures are inconvenient to use at present, but consider:
@c docstring begin (texi-doc-string "guile" "uname")
@deffn primitive uname
Returns an object with some information about the computer system the
program is running on.
Return an object with some information about the computer
system the program is running on.
@end deffn
The following procedures accept an object as returned by @code{uname}
@ -2237,13 +2223,12 @@ no other easy or unambiguous way of detecting such features.
@c docstring begin (texi-doc-string "guile" "setlocale")
@deffn primitive setlocale category [locale]
If @var{locale} is omitted, returns 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.
Otherwise the specified locale category is set to
the string @var{locale}
and the new value is returned as a system-dependent string. If @var{locale}
is an empty string, the locale will be set using envirionment variables.
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.
Otherwise the specified locale category is set to the string
@var{locale} and the new value is returned as a
system-dependent string. If @var{locale} is an empty string,
the locale will be set using envirionment variables.
@end deffn

96
doc/scheme-control.texi
View file

@ -88,28 +88,22 @@ Instead of using @code{call-with-current-continuation}, the exception
primitives documented here are implemented as built-ins that take
advantage of the @emph{upward only} nature of exceptions.
@c ARGFIXME tag/key
@c docstring begin (texi-doc-string "guile" "catch")
@deffn primitive catch tag thunk handler
@deffn primitive catch key thunk handler
Invoke @var{thunk} in the dynamic context of @var{handler} for
exceptions matching @var{key}. If thunk throws to the symbol @var{key},
then @var{handler} is invoked this way:
@example
exceptions matching @var{key}. If thunk throws to the symbol
@var{key}, then @var{handler} is invoked this way:
@lisp
(handler key args ...)
@end example
@var{key} is a symbol or #t.
@var{thunk} takes no arguments. If @var{thunk} returns normally, that
is the return value of @code{catch}.
Handler is invoked outside the scope of its own @code{catch}. If
@var{handler} again throws to the same key, a new handler from further
up the call chain is invoked.
If the key is @code{#t}, then a throw to @emph{any} symbol will match
this call to @code{catch}.
@end lisp
@var{key} is a symbol or @code{#t}.
@var{thunk} takes no arguments. If @var{thunk} returns
normally, that is the return value of @code{catch}.
Handler is invoked outside the scope of its own @code{catch}.
If @var{handler} again throws to the same key, a new handler
from further up the call chain is invoked.
If the key is @code{#t}, then a throw to @emph{any} symbol will
match this call to @code{catch}.
@end deffn
@c docstring begin (texi-doc-string "guile" "throw")
@ -124,7 +118,7 @@ If there is no handler at all, an error is signaled.
@end deffn
@c docstring begin (texi-doc-string "guile" "lazy-catch")
@deffn primitive lazy-catch tag thunk handler
@deffn primitive lazy-catch key thunk handler
This behaves exactly like @code{catch}, except that it does
not unwind the stack (this is the major difference), and if
handler returns, its value is returned from the throw.
@ -145,25 +139,27 @@ displaying @var{msg} and writing @var{args}.
@end deffn
@c end
@c ARGFIXME rest/data
@c docstring begin (texi-doc-string "guile" "scm-error")
@deffn primitive scm-error key subr message args rest
Raise an error with key @var{key}. @var{subr} can be a string naming
the procedure associated with the error, or @code{#f}. @var{message}
is the error message string, possibly containing @code{~S} and @code{~A}
escapes. When an error is reported, these are replaced by formating the
corresponding members of @var{args}: @code{~A} (was @code{%s}) formats using @code{display}
and @code{~S} (was @code{%S}) formats using @code{write}. @var{data} is a
list or @code{#f} depending on @var{key}: if @var{key} is
@code{system-error} then it should be a list
containing the Unix @code{errno} value; If @var{key} is @code{signal} then
it should be a list containing the Unix signal number; otherwise it
will usually be @code{#f}.
@deffn primitive scm-error key subr message args data
Raise an error with key @var{key}. @var{subr} can be a string
naming the procedure associated with the error, or @code{#f}.
@var{message} is the error message string, possibly containing
@code{~S} and @code{~A} escapes. When an error is reported,
these are replaced by formatting the corresponding members of
@var{args}: @code{~A} (was @code{%s} in older versions of
Guile) formats using @code{display} and @code{~S} (was
@code{%S}) formats using @code{write}. @var{data} is a list or
@code{#f} depending on @var{key}: if @var{key} is
@code{system-error} then it should be a list containing the
Unix @code{errno} value; If @var{key} is @code{signal} then it
should be a list containing the Unix signal number; otherwise
it will usually be @code{#f}.
@end deffn
@c docstring begin (texi-doc-string "guile" "strerror")
@deffn primitive strerror err
Returns the Unix error message corresponding to @var{err}, an integer.
Return the Unix error message corresponding to @var{err}, which
must be an integer value.
@end deffn
@c begin (scm-doc-string "boot-9.scm" "false-if-exception")
@ -181,23 +177,20 @@ if an exception occurs then @code{#f} is returned instead.
be reviewed]
@r5index dynamic-wind
@c ARGFIXME in-guard/thunk1 thunk/thunk2 out-guard/thunk3
@c docstring begin (texi-doc-string "guile" "dynamic-wind")
@deffn primitive dynamic-wind thunk1 thunk2 thunk3
@deffn primitive dynamic-wind in_guard thunk out_guard
All three arguments must be 0-argument procedures.
@var{in-guard} is called, then @var{thunk}, then @var{out-guard}.
If, any time during the execution of @var{thunk}, the continuation
of the @code{dynamic-wind} expression is escaped non-locally, @var{out-guard}
is called. If the continuation of the dynamic-wind is re-entered,
@var{in-guard} is called. Thus @var{in-guard} and @var{out-guard} may
be called any number of times.
@example
@var{in_guard} is called, then @var{thunk}, then
@var{out_guard}.
If, any time during the execution of @var{thunk}, the
continuation of the @code{dynamic_wind} expression is escaped
non-locally, @var{out_guard} is called. If the continuation of
the dynamic-wind is re-entered, @var{in_guard} is called. Thus
@var{in_guard} and @var{out_guard} may be called any number of
times.
@lisp
(define x 'normal-binding)
@result{} x
(define a-cont (call-with-current-continuation
(lambda (escape)
(let ((old-x x))
@ -205,38 +198,31 @@ be called any number of times.
;; in-guard:
;;
(lambda () (set! x 'special-binding))
;; thunk
;;
(lambda () (display x) (newline)
(call-with-current-continuation escape)
(display x) (newline)
x)
;; out-guard:
;;
(lambda () (set! x old-x)))))))
;; Prints:
special-binding
;; Evaluates to:
@result{} a-cont
x
@result{} normal-binding
(a-cont #f)
;; Prints:
special-binding
;; Evaluates to:
@result{} a-cont ;; the value of the (define a-cont...)
x
@result{} normal-binding
a-cont
@result{} special-binding
@end example
@end lisp
@end deffn
@c Local Variables:
@c TeX-master: "guile.texi"

729
doc/scheme-data.texi
View file

File diff suppressed because it is too large Load diff

14
doc/scheme-evaluation.texi
View file

@ -123,11 +123,11 @@ environment given by @var{environment specifier}.
@r5index interaction-environment
@c docstring begin (texi-doc-string "guile" "interaction-environment")
@deffn primitive interaction-environment
This procedure returns a specifier for the environment that contains
implementation-defined bindings, typically a superset of those listed in
the report. The intent is that this procedure will return the
environment in which the implementation would evaluate expressions
dynamically typed by the user.
Return a specifier for the environment that contains
implementation--defined bindings, typically a superset of those
listed in the report. The intent is that this procedure will
return the environment in which the implementation would
evaluate expressions dynamically typed by the user.
@end deffn
@c docstring begin (texi-doc-string "guile" "eval-string")
@ -189,7 +189,6 @@ any code is loaded. See documentation for @code{%load-hook} later in
this section.
@end deffn
@c ARGFIXME file/filename
@c docstring begin (texi-doc-string "guile" "primitive-load")
@deffn primitive primitive-load filename
Load the file named @var{filename} and evaluate its contents in
@ -201,7 +200,6 @@ that will be called before any code is loaded. See the
documentation for @code{%load-hook} later in this section.
@end deffn
@c ARGFIXME file/filename
@c docstring begin (texi-doc-string "guile" "primitive-load-path")
@deffn primitive primitive-load-path filename
Search @var{%load-path} for the file named @var{filename} and
@ -210,7 +208,6 @@ relative pathname and is not found in the list of search paths,
an error is signalled.
@end deffn
@c ARGFIXME file/filename
@c docstring begin (texi-doc-string "guile" "%search-load-path")
@deffn primitive %search-load-path filename
Search @var{%load-path} for the file named @var{filename},
@ -257,7 +254,6 @@ list @code{("" ".scm")}.
[delay]
@c ARGFIXME x/obj
@c docstring begin (texi-doc-string "guile" "promise?")
@deffn primitive promise? obj
Return true if @var{obj} is a promise, i.e. a delayed computation

235
doc/scheme-io.texi
View file

@ -35,7 +35,7 @@ ports} are two interesting and powerful examples of this technique.
@r5index input-port?
@c docstring begin (texi-doc-string "guile" "input-port?")
@deffn primitive input-port? x
Returns @code{#t} if @var{x} is an input port, otherwise returns
Return @code{#t} if @var{x} is an input port, otherwise return
@code{#f}. Any object satisfying this predicate also satisfies
@code{port?}.
@end deffn
@ -43,14 +43,14 @@ Returns @code{#t} if @var{x} is an input port, otherwise returns
@r5index output-port?
@c docstring begin (texi-doc-string "guile" "output-port?")
@deffn primitive output-port? x
Returns @code{#t} if @var{x} is an output port, otherwise returns
Return @code{#t} if @var{x} is an output port, otherwise return
@code{#f}. Any object satisfying this predicate also satisfies
@code{port?}.
@end deffn
@c docstring begin (texi-doc-string "guile" "port?")
@deffn primitive port? x
Returns a boolean indicating whether @var{x} is a port.
Return a boolean indicating whether @var{x} is a port.
Equivalent to @code{(or (input-port? @var{x}) (output-port?
@var{x}))}.
@end deffn
@ -64,50 +64,51 @@ Equivalent to @code{(or (input-port? @var{x}) (output-port?
@r5index eof-object?
@c docstring begin (texi-doc-string "guile" "eof-object?")
@deffn primitive eof-object? x
Returns @code{#t} if @var{x} is an end-of-file object; otherwise
returns @code{#f}.
Return @code{#t} if @var{x} is an end-of-file object; otherwise
return @code{#f}.
@end deffn
@r5index char-ready?
@c docstring begin (texi-doc-string "guile" "char-ready?")
@deffn primitive char-ready? [port]
Returns @code{#t} if a character is ready on input @var{port} and
returns @code{#f} otherwise. If @code{char-ready?} returns @code{#t}
then the next @code{read-char} operation on @var{port} is
guaranteed not to hang. If @var{port} is a file port at end of
file then @code{char-ready?} returns @code{#t}.
Return @code{#t} if a character is ready on input @var{port}
and return @code{#f} otherwise. If @code{char-ready?} returns
@code{#t} then the next @code{read-char} operation on
@var{port} is guaranteed not to hang. If @var{port} is a file
port at end of file then @code{char-ready?} returns @code{#t}.
@footnote{@code{char-ready?} exists to make it possible for a
program to accept characters from interactive ports without getting
stuck waiting for input. Any input editors associated with such ports
must make sure that characters whose existence has been asserted by
@code{char-ready?} cannot be rubbed out. If @code{char-ready?} were to
return @code{#f} at end of file, a port at end of file would be
indistinguishable from an interactive port that has no ready
characters.}
program to accept characters from interactive ports without
getting stuck waiting for input. Any input editors associated
with such ports must make sure that characters whose existence
has been asserted by @code{char-ready?} cannot be rubbed out.
If @code{char-ready?} were to return @code{#f} at end of file,
a port at end of file would be indistinguishable from an
interactive port that has no ready characters.}
@end deffn
@r5index read-char?
@c docstring begin (texi-doc-string "guile" "read-char")
@deffn primitive read-char [port]
Returns the next character available from @var{port}, updating
Return the next character available from @var{port}, updating
@var{port} to point to the following character. If no more
characters are available, an end-of-file object is returned.
characters are available, the end-of-file object is returned.
@end deffn
@r5index peek-char?
@c docstring begin (texi-doc-string "guile" "peek-char")
@deffn primitive peek-char [port]
Returns the next character available from @var{port},
Return the next character available from @var{port},
@emph{without} updating @var{port} to point to the following
character. If no more characters are available, an end-of-file object
is returned.@footnote{The value returned by a call to @code{peek-char}
is the same as the value that would have been returned by a call to
@code{read-char} on the same port. The only difference is that the very
next call to @code{read-char} or @code{peek-char} on that
@var{port} will return the value returned by the preceding call to
@code{peek-char}. In particular, a call to @code{peek-char} on an
interactive port will hang waiting for input whenever a call to
@code{read-char} would have hung.}
character. If no more characters are available, the
end-of-file object is returned.@footnote{The value returned by
a call to @code{peek-char} is the same as the value that would
have been returned by a call to @code{read-char} on the same
port. The only difference is that the very next call to
@code{read-char} or @code{peek-char} on that @var{port} will
return the value returned by the preceding call to
@code{peek-char}. In particular, a call to @code{peek-char} on
an interactive port will hang waiting for input whenever a call
to @code{read-char} would have hung.}
@end deffn
@c docstring begin (texi-doc-string "guile" "unread-char")
@ -129,10 +130,9 @@ unread characters will be read again in last-in first-out order. If
@c docstring begin (texi-doc-string "guile" "drain-input")
@deffn primitive drain-input port
Drain @var{port}'s read buffers (including any pushed-back
characters) and returns the content as a single string.
characters) and return the content as a single string.
@end deffn
@c ARGFIXME port/input-port
@c docstring begin (texi-doc-string "guile" "port-column")
@c docstring begin (texi-doc-string "guile" "port-line")
@deffn primitive port-column port
@ -147,7 +147,6 @@ because lines and column numbers traditionally start with 1, and that is
what non-programmers will find most natural.)
@end deffn
@c ARGFIXME port/input-port
@c docstring begin (texi-doc-string "guile" "set-port-column!")
@c docstring begin (texi-doc-string "guile" "set-port-line!")
@deffn primitive set-port-column! port column
@ -267,12 +266,12 @@ all open output ports. The return value is unspecified.
@c docstring begin (texi-doc-string "guile" "close-port")
@deffn primitive close-port port
Close the specified port object. Returns @code{#t} if it successfully
closes a port or @code{#f} if it was already
closed. An exception may be raised if an error occurs, for example
when flushing buffered output.
See also @ref{Ports and File Descriptors, close}, for a procedure
which can close file descriptors.
Close the specified port object. Return @code{#t} if it
successfully closes a port or @code{#f} if it was already
closed. An exception may be raised if an error occurs, for
example when flushing buffered output. See also @ref{Ports and
File Descriptors, close}, for a procedure which can close file
descriptors.
@end deffn
@r5index close-input-port
@ -299,21 +298,21 @@ which can close file descriptors.
@c docstring begin (texi-doc-string "guile" "port-closed?")
@deffn primitive port-closed? port
Returns @code{#t} if @var{port} is closed or @code{#f} if it is open.
Return @code{#t} if @var{port} is closed or @code{#f} if it is
open.
@end deffn
@node Random Access
@section Random Access
@c ARGFIXME object/fd/port
@c docstring begin (texi-doc-string "guile" "seek")
@deffn primitive seek object offset whence
Sets the current position of @var{fd/port} to the integer @var{offset},
which is interpreted according to the value of @var{whence}.
One of the following variables should be supplied
for @var{whence}:
@deffn primitive seek fd_port offset whence
Sets the current position of @var{fd/port} to the integer
@var{offset}, which is interpreted according to the value of
@var{whence}.
One of the following variables should be supplied for
@var{whence}:
@defvar SEEK_SET
Seek from the beginning of the file.
@end defvar
@ -323,46 +322,40 @@ Seek from the current position.
@defvar SEEK_END
Seek from the end of the file.
@end defvar
If @var{fd/port} is a file descriptor, the underlying system call is
@code{lseek}. @var{port} may be a string port.
The value returned is the new position in the file. This means that
the current position of a port can be obtained using:
@smalllisp
If @var{fd/port} is a file descriptor, the underlying system
call is @code{lseek}. @var{port} may be a string port.
The value returned is the new position in the file. This means
that the current position of a port can be obtained using:
@lisp
(seek port 0 SEEK_CUR)
@end smalllisp
@end lisp
@end deffn
@c ARGFIXME object/fd/port
@c docstring begin (texi-doc-string "guile" "fseek")
@deffn primitive fseek object offset whence
Obsolete. Almost the same as seek, above, but the return value is
unspecified.
@deffn primitive fseek fd_port offset whence
Obsolete. Almost the same as @code{seek}, but the return value
is unspecified.
@end deffn
@c ARGFIXME object/fd/port
@c docstring begin (texi-doc-string "guile" "ftell")
@deffn primitive ftell object
Returns an integer representing the current position of @var{fd/port},
measured from the beginning. Equivalent to:
@smalllisp
@deffn primitive ftell fd_port
Return an integer representing the current position of
@var{fd/port}, measured from the beginning. Equivalent to:
@lisp
(seek port 0 SEEK_CUR)
@end smalllisp
@end lisp
@end deffn
@findex truncate
@findex ftruncate
@c ARGFIXME obj/object size/length
@c docstring begin (texi-doc-string "guile" "truncate-file")
@deffn primitive truncate-file object [length]
Truncates the object referred to by @var{obj} to at most @var{size} bytes.
@var{obj} can be a string containing a file name or an integer file
descriptor or a port. @var{size} may be omitted if @var{obj} is not
a file name, in which case the truncation occurs at the current port.
position.
The return value is unspecified.
Truncates the object referred to by @var{object} to at most
@var{length} bytes. @var{object} can be a string containing a
file name or an integer file descriptor or a port.
@var{length} may be omitted if @var{object} is not a file name,
in which case the truncation occurs at the current port.
position. The return value is unspecified.
@end deffn
@ -444,21 +437,19 @@ char-set, not a string.
@c docstring begin (texi-doc-string "guile" "write-line")
@deffn primitive write-line obj [port]
Display @var{obj} and a newline character to @var{port}. If @var{port}
is not specified, @code{(current-output-port)} is used. This function
is equivalent to:
@smalllisp
Display @var{obj} and a newline character to @var{port}. If
@var{port} is not specified, @code{(current-output-port)} is
used. This function is equivalent to:
@lisp
(display obj [port])
(newline [port])
@end smalllisp
@end lisp
@end deffn
Some of the abovementioned I/O functions rely on the following C
primitives. These will mainly be of interest to people hacking Guile
internals.
@c ARGFIXME gobble/gobble?
@c docstring begin (texi-doc-string "guile" "%read-delimited!")
@deffn primitive %read-delimited! delims str gobble [port [start [end]]]
Read characters from @var{port} into @var{str} until one of the
@ -567,16 +558,13 @@ The following procedures are used to open file ports.
See also @ref{Ports and File Descriptors, open}, for an interface
to the Unix @code{open} system call.
@c ARGFIXME string/filename mode/modes
@c docstring begin (texi-doc-string "guile" "open-file")
@deffn primitive open-file filename modes
Open the file whose name is @var{string}, and return a port
@deffn primitive open-file filename mode
Open the file whose name is @var{filename}, and return a port
representing that file. The attributes of the port are
determined by the @var{mode} string. The way in
which this is interpreted is similar to C stdio:
The first character must be one of the following:
determined by the @var{mode} string. The way in which this is
interpreted is similar to C stdio. The first character must be
one of the following:
@table @samp
@item r
Open an existing file for input.
@ -584,34 +572,31 @@ Open an existing file for input.
Open a file for output, creating it if it doesn't already exist
or removing its contents if it does.
@item a
Open a file for output, creating it if it doesn't already exist.
All writes to the port will go to the end of the file.
Open a file for output, creating it if it doesn't already
exist. All writes to the port will go to the end of the file.
The "append mode" can be turned off while the port is in use
@pxref{Ports and File Descriptors, fcntl}
@end table
The following additional characters can be appended:
@table @samp
@item +
Open the port for both input and output. E.g., @code{r+}: open
an existing file for both input and output.
@item 0
Create an "unbuffered" port. In this case input and output operations
are passed directly to the underlying port implementation without
additional buffering. This is likely to slow down I/O operations.
The buffering mode can be changed while a port is in use
@pxref{Ports and File Descriptors, setvbuf}
Create an "unbuffered" port. In this case input and output
operations are passed directly to the underlying port
implementation without additional buffering. This is likely to
slow down I/O operations. The buffering mode can be changed
while a port is in use @pxref{Ports and File Descriptors,
setvbuf}
@item l
Add line-buffering to the port. The port output buffer will be
automatically flushed whenever a newline character is written.
@end table
In theory we could create read/write ports which were buffered in one
direction only. However this isn't included in the current interfaces.
If a file cannot be opened with the access requested,
@code{open-file} throws an exception.
In theory we could create read/write ports which were buffered
in one direction only. However this isn't included in the
current interfaces. If a file cannot be opened with the access
requested, @code{open-file} throws an exception.
@end deffn
@r5index open-input-file
@ -742,12 +727,11 @@ port. When the function returns, the string composed of the characters
written into the port is returned.
@end deffn
@c ARGFIXME str/string
@c docstring begin (texi-doc-string "guile" "call-with-input-string")
@deffn primitive call-with-input-string str proc
Calls the one-argument procedure @var{proc} with a newly created input
port from which @var{string}'s contents may be read. The value yielded
by the @var{proc} is returned.
@deffn primitive call-with-input-string string proc
Calls the one-argument procedure @var{proc} with a newly
created input port from which @var{string}'s contents may be
read. The value yielded by the @var{proc} is returned.
@end deffn
@c begin (scm-doc-string "r4rs.scm" "with-output-to-string")
@ -766,15 +750,15 @@ port set temporarily to a string port opened on the specified
@c docstring begin (texi-doc-string "guile" "open-input-string")
@deffn primitive open-input-string str
Takes a string and returns an input port that delivers
characters from the string. The port can be closed by
Take a string and return an input port that delivers characters
from the string. The port can be closed by
@code{close-input-port}, though its storage will be reclaimed
by the garbage collector if it becomes inaccessible.
@end deffn
@c docstring begin (texi-doc-string "guile" "open-output-string")
@deffn primitive open-output-string
Returns an output port that will accumulate characters for
Return an output port that will accumulate characters for
retrieval by @code{get-output-string}. The port can be closed
by the procedure @code{close-output-port}, though its storage
will be reclaimed by the garbage collector if it becomes
@ -784,7 +768,7 @@ inaccessible.
@c docstring begin (texi-doc-string "guile" "get-output-string")
@deffn primitive get-output-string port
Given an output port created by @code{open-output-string},
returns a string consisting of the characters that have been
return a string consisting of the characters that have been
output to the port so far.
@end deffn
@ -800,14 +784,12 @@ but trying to extract the file descriptor number will fail.
A @dfn{soft-port} is a port based on a vector of procedures capable of
accepting or delivering characters. It allows emulation of I/O ports.
@c ARGFIXME pv/vector
@c docstring begin (texi-doc-string "guile" "make-soft-port")
@deffn primitive make-soft-port pv modes
Returns a port capable of receiving or delivering characters as
Return a port capable of receiving or delivering characters as
specified by the @var{modes} string (@pxref{File Ports,
open-file}). @var{vector} must be a vector of length 6. Its components
are as follows:
open-file}). @var{pv} must be a vector of length 5. Its
components are as follows:
@enumerate 0
@item
procedure accepting one character for output
@ -820,17 +802,15 @@ thunk for getting one character
@item
thunk for closing port (not by garbage collection)
@end enumerate
For an output-only port only elements 0, 1, 2, and 4 need be
procedures. For an input-only port only elements 3 and 4 need be
procedures. Thunks 2 and 4 can instead be @code{#f} if there is no useful
operation for them to perform.
If thunk 3 returns @code{#f} or an @code{eof-object} (@pxref{Input,
eof-object?, ,r4rs, The Revised^4 Report on Scheme}) it indicates that
the port has reached end-of-file. For example:
@example
procedures. For an input-only port only elements 3 and 4 need
be procedures. Thunks 2 and 4 can instead be @code{#f} if
there is no useful operation for them to perform.
If thunk 3 returns @code{#f} or an @code{eof-object}
(@pxref{Input, eof-object?, ,r4rs, The Revised^4 Report on
Scheme}) it indicates that the port has reached end-of-file.
For example:
@lisp
(define stdout (current-output-port))
(define p (make-soft-port
(vector
@ -840,9 +820,8 @@ the port has reached end-of-file. For example:
(lambda () (char-upcase (read-char)))
(lambda () (display "@@" stdout)))
"rw"))
(write p p) @result{} #<input-output: soft 8081e20>
@end example
@end lisp
@end deffn

39
doc/scheme-memory.texi
View file

@ -23,7 +23,8 @@ no longer accessible.
@c docstring begin (texi-doc-string "guile" "gc-stats")
@deffn primitive gc-stats
Returns an association list of statistics about Guile's current use of storage.
Return an association list of statistics about Guile's current
use of storage.
@end deffn
@c docstring begin (texi-doc-string "guile" "object-address")
@ -87,21 +88,19 @@ they constitute a doubly-weak table has to be used.
@node Weak key hashes
@subsection Weak key hashes
@c ARGFIXME k/size
@c docstring begin (texi-doc-string "guile" "make-weak-key-hash-table")
@deffn primitive make-weak-key-hash-table k
@deffn primitive make-weak-key-hash-table size
@deffnx primitive make-weak-value-hash-table size
@deffnx primitive make-doubly-weak-hash-table size
Return a weak hash table with @var{size} buckets. As with any hash
table, choosing a good size for the table requires some caution.
You can modify weak hash tables in exactly the same way you would modify
regular hash tables. (@pxref{Hash Tables})
Return a weak hash table with @var{size} buckets. As with any
hash table, choosing a good size for the table requires some
caution.
You can modify weak hash tables in exactly the same way you
would modify regular hash tables. (@pxref{Hash Tables})
@end deffn
@c ARGFIXME x/obj
@c docstring begin (texi-doc-string "guile" "weak-key-hash-table?")
@deffn primitive weak-key-hash-table? x
@deffn primitive weak-key-hash-table? obj
@deffnx primitive weak-value-hash-table? obj
@deffnx primitive doubly-weak-hash-table? obj
Return @code{#t} if @var{obj} is the specified weak hash
@ -132,28 +131,26 @@ nor a weak value hash table.
Weak vectors are mainly useful in Guile's implementation of weak hash
tables.
@c ARGFIXME k/size
@c docstring begin (texi-doc-string "guile" "make-weak-vector")
@deffn primitive make-weak-vector k [fill]
@deffn primitive make-weak-vector size [fill]
Return a weak vector with @var{size} elements. If the optional
argument @var{fill} is given, all entries in the vector will be set to
@var{fill}. The default value for @var{fill} is the empty list.
argument @var{fill} is given, all entries in the vector will be
set to @var{fill}. The default value for @var{fill} is the
empty list.
@end deffn
@c NJFIXME should vector->list here be list->vector ?
@c docstring begin (texi-doc-string "guile" "weak-vector")
@c docstring begin (texi-doc-string "guile" "list->weak-vector")
@deffn primitive weak-vector . l
@deffnx primitive list->weak-vector l
Construct a weak vector from a list: @code{weak-vector} uses the list of
its arguments while @code{list->weak-vector} uses its only argument
@var{l} (a list) to construct a weak vector the same way
@code{vector->list} would.
Construct a weak vector from a list: @code{weak-vector} uses
the list of its arguments while @code{list->weak-vector} uses
its only argument @var{l} (a list) to construct a weak vector
the same way @code{list->vector} would.
@end deffn
@c ARGFIXME x/obj
@c docstring begin (texi-doc-string "guile" "weak-vector?")
@deffn primitive weak-vector? x
@deffn primitive weak-vector? obj
Return @code{#t} if @var{obj} is a weak vector. Note that all
weak hashes are also weak vectors.
@end deffn

68
doc/scheme-modules.texi
View file

@ -182,12 +182,12 @@ written properly.
Guile's dynamic linking functions make it relatively easy to write a
module that incorporates code from third-party object code libraries.
@c ARGFIXME fname/library-file
@c docstring begin (texi-doc-string "guile" "dynamic-link")
@deffn primitive dynamic-link fname
Open the dynamic library @var{library-file}. A library handle
representing the opened library is returned; this handle should be used
as the @var{lib} argument to the following functions.
@deffn primitive dynamic-link filename
Open the dynamic library called @var{filename}. A library
handle representing the opened library is returned; this handle
should be used as the @var{dobj} argument to the following
functions.
@end deffn
@c docstring begin (texi-doc-string "guile" "dynamic-object?")
@ -196,19 +196,14 @@ Return @code{#t} if @var{obj} is a dynamic library handle, or @code{#f}
otherwise.
@end deffn
@c ARGFIXME dobj/dynobj/library-handle
@c docstring begin (texi-doc-string "guile" "dynamic-unlink")
@deffn primitive dynamic-unlink dobj
Unlink the library represented by @var{library-handle},
and remove any imported symbols from the address space.
GJB:FIXME:DOC: 2nd version below:
Unlink the indicated object file from the application. The
argument @var{dynobj} must have been obtained by a call to
argument @var{dobj} must have been obtained by a call to
@code{dynamic-link}. After @code{dynamic-unlink} has been
called on @var{dynobj}, its content is no longer accessible.
called on @var{dobj}, its content is no longer accessible.
@end deffn
@c ARGFIXME symb/func/function dobj/lib/dynobj
@c docstring begin (texi-doc-string "guile" "dynamic-func")
@deffn primitive dynamic-func name dobj
Search the dynamic object @var{dobj} for the C function
@ -222,54 +217,37 @@ underscore in @var{function}. Guile knows whether the underscore is
needed or not and will add it when necessary.
@end deffn
@c ARGFIXME lib-thunk/func/function lib/dobj/dynobj
@c docstring begin (texi-doc-string "guile" "dynamic-call")
@deffn primitive dynamic-call func dobj
Call @var{lib-thunk}, a procedure of no arguments. If @var{lib-thunk}
is a string, it is assumed to be a symbol found in the dynamic library
@var{lib} and is fetched with @code{dynamic-func}. Otherwise, it should
be a function handle returned by a previous call to @code{dynamic-func}.
The return value is unspecified.
GJB:FIXME:DOC 2nd version below
Call the C function indicated by @var{function} and @var{dynobj}. The
function is passed no arguments and its return value is ignored. When
@var{function} is something returned by @code{dynamic-func}, call that
function and ignore @var{dynobj}. When @var{function} is a string (or
symbol, etc.), look it up in @var{dynobj}; this is equivalent to
Call the C function indicated by @var{func} and @var{dobj}.
The function is passed no arguments and its return value is
ignored. When @var{function} is something returned by
@code{dynamic-func}, call that function and ignore @var{dobj}.
When @var{func} is a string , look it up in @var{dynobj}; this
is equivalent to
@smallexample
(dynamic-call (dynamic-func @var{function} @var{dynobj} #f))
(dynamic-call (dynamic-func @var{func} @var{dobj} #f))
@end smallexample
Interrupts are deferred while the C function is executing (with
@code{SCM_DEFER_INTS}/@code{SCM_ALLOW_INTS}).
@end deffn
@c ARGFIXME func/proc/function dobj/dynobj
@c docstring begin (texi-doc-string "guile" "dynamic-args-call")
@deffn primitive dynamic-args-call func dobj args
Call @var{proc}, a dynamically loaded function, passing it the argument
list @var{args} (a list of strings). As with @code{dynamic-call},
@var{proc} should be either a function handle or a string, in which case
it is first fetched from @var{lib} with @code{dynamic-func}.
@var{proc} is assumed to return an integer, which is used as the return
value from @code{dynamic-args-call}.
GJB:FIXME:DOC 2nd version below
Call the C function indicated by @var{function} and @var{dynobj}, just
like @code{dynamic-call}, but pass it some arguments and return its
return value. The C function is expected to take two arguments and
return an @code{int}, just like @code{main}:
Call the C function indicated by @var{func} and @var{dobj},
just like @code{dynamic-call}, but pass it some arguments and
return its return value. The C function is expected to take
two arguments and return an @code{int}, just like @code{main}:
@smallexample
int c_func (int argc, char **argv);
@end smallexample
The parameter @var{args} must be a list of strings and is converted into
an array of @code{char *}. The array is passed in @var{argv} and its
size in @var{argc}. The return value is converted to a Scheme number
and returned from the call to @code{dynamic-args-call}.
The parameter @var{args} must be a list of strings and is
converted into an array of @code{char *}. The array is passed
in @var{argv} and its size in @var{argc}. The return value is
converted to a Scheme number and returned from the call to
@code{dynamic-args-call}.
@end deffn
@c docstring begin (texi-doc-string "guile" "c-registered-modules")

4
doc/scheme-options.texi
View file

@ -284,11 +284,11 @@ Guile's configuration at run time.
Return a string describing Guile's version number, or its major or minor
version numbers, respectively.
@example
@lisp
(version) @result{} "1.3a"
(major-version) @result{} "1"
(minor-version) @result{} "3a"
@end example
@end lisp
@end deffn
@c NJFIXME not in libguile!

51
doc/scheme-procedures.texi
View file

@ -128,45 +128,44 @@ or Aubrey for help. -twp]
@c docstring begin (texi-doc-string "guile" "procedure->syntax")
@deffn primitive procedure->syntax code
Returns a @dfn{macro} which, when a symbol defined to this value
appears as the first symbol in an expression, returns the result
of applying @var{code} to the expression and the environment.
Return a @dfn{macro} which, when a symbol defined to this value
appears as the first symbol in an expression, returns the
result of applying @var{code} to the expression and the
environment.
@end deffn
@c docstring begin (texi-doc-string "guile" "procedure->macro")
@deffn primitive procedure->macro code
Returns a @dfn{macro} which, when a symbol defined to this value
appears as the first symbol in an expression, evaluates the result
of applying @var{code} to the expression and the environment.
The value returned from @var{code} which has been passed to
@code{procedure->memoizing-macro} replaces the form passed to
@var{code}. For example:
@example
Return a @dfn{macro} which, when a symbol defined to this value
appears as the first symbol in an expression, evaluates the
result of applying @var{code} to the expression and the
environment. The value returned from @var{code} which has been
passed to @code{procedure->memoizing-macro} replaces the form
passed to @var{code}. For example:
@lisp
(define trace
(procedure->macro
(lambda (x env) `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x))))))
(trace @i{foo}) @equiv{} (set! @i{foo} (tracef @i{foo} '@i{foo})).
@end example
@end lisp
@end deffn
@c docstring begin (texi-doc-string "guile" "procedure->memoizing-macro")
@deffn primitive procedure->memoizing-macro code
Returns a @dfn{macro} which, when a symbol defined to this value
appears as the first symbol in an expression, evaluates the result
of applying @var{proc} to the expression and the environment.
The value returned from @var{proc} which has been passed to
@code{procedure->memoizing-macro} replaces the form passed to
@var{proc}. For example:
@example
Return a @dfn{macro} which, when a symbol defined to this value
appears as the first symbol in an expression, evaluates the
result of applying @var{proc} to the expression and the
environment. The value returned from @var{proc} which has been
passed to @code{procedure->memoizing-macro} replaces the form
passed to @var{proc}. For example:
@lisp
(define trace
(procedure->macro
(lambda (x env) `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x))))))
(trace @i{foo}) @equiv{} (set! @i{foo} (tracef @i{foo} '@i{foo})).
@end example
@end lisp
@end deffn
@c docstring begin (texi-doc-string "guile" "macro?")
@ -175,13 +174,13 @@ Return @code{#t} if @var{obj} is a regular macro, a memoizing macro or a
syntax transformer.
@end deffn
@c ARGFIXME m/obj
@c docstring begin (texi-doc-string "guile" "macro-type")
@deffn primitive macro-type m
Return one of the symbols @code{syntax}, @code{macro} or @code{macro!},
depending on whether @var{obj} is a syntax tranformer, a regular macro,
or a memoizing macro, respectively. If @var{obj} is not a macro,
@code{#f} is returned.
Return one of the symbols @code{syntax}, @code{macro} or
@code{macro!}, depending on whether @var{m} is a syntax
tranformer, a regular macro, or a memoizing macro,
respectively. If @var{m} is not a macro, @code{#f} is
returned.
@end deffn
@c docstring begin (texi-doc-string "guile" "macro-name")

12
doc/scheme-scheduling.texi
View file

@ -123,7 +123,7 @@ Before calling @var{thunk}, the dynamic-wind chain is un-wound back to
the root and a new chain started for @var{thunk}. Therefore, this call
may not do what you expect:
@example
@lisp
;; Almost certainly a bug:
(with-output-to-port
some-port
@ -134,7 +134,7 @@ may not do what you expect:
(display 'fnord)
(newline))
(lambda (errcode) errcode))))
@end example
@end lisp
The problem is, on what port will @samp{fnord} be displayed? You
might expect that because of the @code{with-output-to-port} that
@ -353,13 +353,15 @@ in its own dynamic root, you can use fluids for thread local storage.
@c docstring begin (texi-doc-string "guile" "fluid?")
@deffn primitive fluid? obj
Return #t iff @var{obj} is a fluid; otherwise, return #f.
Return @code{#t} iff @var{obj} is a fluid; otherwise, return
@code{#f}.
@end deffn
@c docstring begin (texi-doc-string "guile" "fluid-ref")
@deffn primitive fluid-ref fluid
Return the value associated with @var{fluid} in the current dynamic root.
If @var{fluid} has not been set, then this returns #f.
Return the value associated with @var{fluid} in the current
dynamic root. If @var{fluid} has not been set, then return
@code{#f}.
@end deffn
@c docstring begin (texi-doc-string "guile" "fluid-set!")

10
doc/scheme-utility.texi
View file

@ -66,9 +66,8 @@ a property list associated with a procedure object, use the
Return @var{obj}'s property list.
@end deffn
@c ARGFIXME alist/plist
@c docstring begin (texi-doc-string "guile" "set-object-properties!")
@deffn primitive set-object-properties! obj plist
@deffn primitive set-object-properties! obj alist
@deffnx primitive set-procedure-properties! obj alist
Set @var{obj}'s property list to @var{alist}.
@end deffn
@ -79,12 +78,11 @@ Set @var{obj}'s property list to @var{alist}.
Return the property of @var{obj} with name @var{key}.
@end deffn
@c ARGFIXME val/value
@c docstring begin (texi-doc-string "guile" "set-object-property!")
@deffn primitive set-object-property! obj key val
@deffn primitive set-object-property! obj key value
@deffnx primitive set-procedure-property! obj key value
In @var{obj}'s property list, set the property named @var{key} to
@var{value}.
In @var{obj}'s property list, set the property named @var{key}
to @var{value}.
@end deffn
[Interface bug: there should be a second level of interface in which