summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMartin Grabmüller <mgrabmue@cs.tu-berlin.de>2001-04-17 15:34:33 +0000
committerMartin Grabmüller <mgrabmue@cs.tu-berlin.de>2001-04-17 15:34:33 +0000
commit239d2912a28f924a6b03463c4307bc3125705e7d (patch)
tree9ce827f9fd7bd1d756d9ceda1811ce5f758d1819
parent216eedfcae5e85c8bad8b1138d6e947ab1c67fa1 (diff)
downloadguile-239d2912a28f924a6b03463c4307bc3125705e7d.tar.gz
* scheme-utility.texi (General Conversion): New node, added
`object->string'. (Equality): Added definition and explanation of `sameness'. * posix.texi (System Identification): Added `gethostname' and `sethostname'. (Processes): Added `setpriority' and `getpriority'. (User Information): Added `cuserid' and `getlogin'. (Ports and File Descriptors): Added `flock'. (Processes): Added `chroot'. (File System): Added `mkstemp!'. (Encryption): New node, added `crypt' and `getpass'. * new-docstrings.texi: Moved several docstrings over to the reference manual (see above which). * scheme-data.texi (Data Types), (Numerical Tower): Add explicit @bullet to @itemize to satisfy older `makeinfo'.
-rw-r--r--doc/ChangeLog21
-rw-r--r--doc/new-docstrings.texi108
-rw-r--r--doc/posix.texi147
-rwxr-xr-xdoc/scheme-data.texi22
-rw-r--r--doc/scheme-utility.texi153
5 files changed, 297 insertions, 154 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog
index 2ff22399d..c9efb339c 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,24 @@
+2001-04-17 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
+
+ * scheme-utility.texi (General Conversion): New node, added
+ `object->string'.
+ (Equality): Added definition and explanation of `sameness'.
+
+ * posix.texi (System Identification): Added `gethostname' and
+ `sethostname'.
+ (Processes): Added `setpriority' and `getpriority'.
+ (User Information): Added `cuserid' and `getlogin'.
+ (Ports and File Descriptors): Added `flock'.
+ (Processes): Added `chroot'.
+ (File System): Added `mkstemp!'.
+ (Encryption): New node, added `crypt' and `getpass'.
+
+ * new-docstrings.texi: Moved several docstrings over to the
+ reference manual (see above which).
+
+ * scheme-data.texi (Data Types), (Numerical Tower): Add explicit
+ @bullet to @itemize to satisfy older `makeinfo'.
+
2001-04-16 Neil Jerram <neil@ossau.uklinux.net>
* data-rep.texi (Signalling Type Errors): Update SCM_ASSERT doc
diff --git a/doc/new-docstrings.texi b/doc/new-docstrings.texi
index 778b3b45d..21e979221 100644
--- a/doc/new-docstrings.texi
+++ b/doc/new-docstrings.texi
@@ -485,114 +485,6 @@ Create and return a copy of the global symbol table, removing all
unbound symbols.
@end deffn
-@deffn primitive object->string obj [printer]
-Return a Scheme string obtained by printing @var{obj}.
-Printing function can be specified by the optional second
-argument @var{printer} (default: @code{write}).
-@end deffn
-
-@deffn primitive gethostname
-Return the host name of the current processor.
-@end deffn
-
-@deffn primitive sethostname name
-Set the host name of the current processor to @var{name}. May
-only be used by the superuser. The return value is not
-specified.
-@end deffn
-
-@deffn primitive flock file operation
-Apply or remove an advisory lock on an open file.
-@var{operation} specifies the action to be done:
-@table @code
-@item LOCK_SH
-Shared lock. More than one process may hold a shared lock
-for a given file at a given time.
-@item LOCK_EX
-Exclusive lock. Only one process may hold an exclusive lock
-for a given file at a given time.
-@item LOCK_UN
-Unlock the file.
-@item LOCK_NB
-Don't block when locking. May be specified by bitwise OR'ing
-it to one of the other operations.
-@end table
-The return value is not specified. @var{file} may be an open
-file descriptor or an open file descriptior port.
-@end deffn
-
-@deffn primitive getpass prompt
-Display @var{prompt} to the standard error output and read
-a password from @file{/dev/tty}. If this file is not
-accessible, it reads from standard input. The password may be
-up to 127 characters in length. Additional characters and the
-terminating newline character are discarded. While reading
-the password, echoing and the generation of signals by special
-characters is disabled.
-@end deffn
-
-@deffn primitive setpriority which who prio
-Set 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
-@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}
-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.
-@end deffn
-
-@deffn primitive getpriority which who
-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
-@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}
-denotes the current process, process group, or user. Return
-the highest priority (lowest numerical value) of any of the
-specified processes.
-@end deffn
-
-@deffn primitive cuserid
-Return a string containing a user name associated with the
-effective user id of the process. Return @code{#f} if this
-information cannot be obtained.
-@end deffn
-
-@deffn primitive getlogin
-Return a string containing the name of the user logged in on
-the controlling terminal of the process, or @code{#f} if this
-information cannot be obtained.
-@end deffn
-
-@deffn primitive chroot path
-Change the root directory to that specified in @var{path}.
-This directory will be used for path names beginning with
-@file{/}. The root directory is inherited by all children
-of the current process. Only the superuser may change the
-root directory.
-@end deffn
-
-@deffn primitive crypt key salt
-Encrypt @var{key} using @var{salt} as the salt value to the
-crypt(3) library call
-@end deffn
-
-@deffn primitive mkstemp! tmpl
-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
Internal GOOPS magic---don't use this function!
@end deffn
diff --git a/doc/posix.texi b/doc/posix.texi
index b6c72d22f..f6fbc0994 100644
--- a/doc/posix.texi
+++ b/doc/posix.texi
@@ -3,19 +3,20 @@
@menu
* Conventions:: Conventions employed by the POSIX interface.
-* Ports and File Descriptors:: Scheme ``ports'' and Unix file descriptors
+* Ports and File Descriptors:: Scheme ``ports'' and Unix file descriptors
have different representations.
-* File System:: stat, chown, chmod, etc.
-* User Information:: Retrieving a user's GECOS (/etc/passwd) entry.
-* Time:: gettimeofday, localtime, strftime, etc.
+* File System:: stat, chown, chmod, etc.
+* User Information:: Retrieving a user's GECOS (/etc/passwd) entry.
+* Time:: gettimeofday, localtime, strftime, etc.
* Runtime Environment:: Accessing and modifying Guile's environment.
-* Processes:: getuid, getpid, etc.
+* Processes:: getuid, getpid, etc.
* Signals:: sigaction, kill, pause, alarm, etc.
-* Terminals and Ptys:: ttyname, tcsetpgrp, etc.
-* Pipes:: Communicating data between processes.
-* Networking:: gethostbyaddr, getnetent, socket, bind, listen.
-* System Identification:: `uname' and getting info about this machine.
+* Terminals and Ptys:: ttyname, tcsetpgrp, etc.
+* Pipes:: Communicating data between processes.
+* Networking:: gethostbyaddr, getnetent, socket, bind, listen.
+* System Identification:: Obtaining information about the system.
* Locales:: setlocale, etc.
+* Encryption::
@end menu
@node Conventions
@@ -442,6 +443,26 @@ The value used to indicate the "close on exec" flag with @code{F_GETFL} or
@end table
@end deffn
+@deffn primitive flock file operation
+Apply or remove an advisory lock on an open file.
+@var{operation} specifies the action to be done:
+@table @code
+@item LOCK_SH
+Shared lock. More than one process may hold a shared lock
+for a given file at a given time.
+@item LOCK_EX
+Exclusive lock. Only one process may hold an exclusive lock
+for a given file at a given time.
+@item LOCK_UN
+Unlock the file.
+@item LOCK_NB
+Don't block when locking. May be specified by bitwise OR'ing
+it to one of the other operations.
+@end table
+The return value is not specified. @var{file} may be an open
+file descriptor or an open file descriptior port.
+@end deffn
+
@deffn primitive select reads writes excepts [secs [usecs]]
This procedure has a variety of uses: waiting for the ability
to provide input, accept output, or the existance of
@@ -712,6 +733,14 @@ Care should be taken if opening the file, e.g., use the
@code{O_EXCL} open flag or use @code{mkstemp!} instead.
@end deffn
+@deffn primitive mkstemp! tmpl
+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 dirname filename
Return the directory name component of the file name
@var{filename}. If @var{filename} does not contain a directory
@@ -838,6 +867,22 @@ a string, or omitted, giving the behaviour of getgrgid, getgrnam
or getgrent respectively.
@end deffn
+In addition to the accessor procedures for the user database, the
+following shortcut procedures are also available.
+
+@deffn primitive cuserid
+Return a string containing a user name associated with the
+effective user id of the process. Return @code{#f} if this
+information cannot be obtained.
+@end deffn
+
+@deffn primitive getlogin
+Return a string containing the name of the user logged in on
+the controlling terminal of the process, or @code{#f} if this
+information cannot be obtained.
+@end deffn
+
+
@node Time
@section Time
@@ -1055,6 +1100,14 @@ file creation mask. Otherwise the file creation mask is set to
E.g., @code{(umask #o022)} sets the mask to octal 22, decimal 18.
@end deffn
+@deffn primitive chroot path
+Change the root directory to that specified in @var{path}.
+This directory will be used for path names beginning with
+@file{/}. The root directory is inherited by all children
+of the current process. Only the superuser may change the
+root directory.
+@end deffn
+
@deffn primitive getpid
Return an integer representing the current process ID.
@end deffn
@@ -1267,6 +1320,36 @@ priority value means that the process runs less often.
The return value is unspecified.
@end deffn
+@deffn primitive setpriority which who prio
+Set 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
+@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}
+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.
+@end deffn
+
+@deffn primitive getpriority which who
+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
+@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}
+denotes the current process, process group, or user. Return
+the highest priority (lowest numerical value) of any of the
+specified processes.
+@end deffn
+
+
@node Signals
@section Signals
@@ -1449,8 +1532,8 @@ close a pipe, but doesn't return the status.
@section Networking
@menu
-* Network Databases and Address Conversion::
-* Network Sockets and Communication::
+* Network Databases and Address Conversion::
+* Network Sockets and Communication::
@end menu
@node Network Databases and Address Conversion
@@ -2044,6 +2127,9 @@ These procedures are inconvenient to use at present, but consider:
@node System Identification
@section System Identification
+This section lists the various procedures Guile provides for accessing
+information about the system it runs on.
+
@deffn primitive uname
Return an object with some information about the computer
system the program is running on.
@@ -2065,6 +2151,17 @@ The current version level within the release of the operating system.
A description of the hardware.
@end table
+@deffn primitive gethostname
+Return the host name of the current processor.
+@end deffn
+
+@deffn primitive sethostname name
+Set the host name of the current processor to @var{name}. May
+only be used by the superuser. The return value is not
+specified.
+@end deffn
+
+@c FIXME::martin: Not in libguile!
@deffn primitive 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,
@@ -2091,3 +2188,31 @@ Otherwise the specified locale category is set to the string
system-dependent string. If @var{locale} is an empty string,
the locale will be set using envirionment variables.
@end deffn
+
+@node Encryption
+@section Encryption
+
+Please note that the procedures in this section are not suited for
+strong encryption, they are only interfaces to the well--known and
+common system library functions of the same name. They are just as good
+(or bad) as the underlying functions, so you should refer to your system
+documentation before using them.
+
+@deffn primitive crypt key salt
+Encrypt @var{key} using @var{salt} as the salt value to the
+crypt(3) library call
+@end deffn
+
+@code{getpass} is no encryption procedure at all, but it is often used
+in compination with @code{crypt}, that is why it appears in this
+section.
+
+@deffn primitive getpass prompt
+Display @var{prompt} to the standard error output and read
+a password from @file{/dev/tty}. If this file is not
+accessible, it reads from standard input. The password may be
+up to 127 characters in length. Additional characters and the
+terminating newline character are discarded. While reading
+the password, echoing and the generation of signals by special
+characters is disabled.
+@end deffn
diff --git a/doc/scheme-data.texi b/doc/scheme-data.texi
index a332dace7..92f333c59 100755
--- a/doc/scheme-data.texi
+++ b/doc/scheme-data.texi
@@ -9,7 +9,7 @@ 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
-@itemize
+@itemize @bullet
@item
either in a ``data-centric'' way, as the behaviour and properties of the
``dynamically linked object'' data type, and the operations that may be
@@ -172,7 +172,7 @@ in Scheme, which is particularly clear and accessible: see
Scheme's numerical ``tower'' consists of the following categories of
numbers:
-@itemize
+@itemize @bullet
@item
integers (whole numbers)
@@ -2295,9 +2295,14 @@ to write a symbol containing characters not mentioned above, you write
symbols as follows:
@itemize @bullet
-@item Begin the symbol with the two character @code{#@{},
-@item write the characters of the symbol and
-@item finish the symbol with the characters @code{@}#}.
+@item
+Begin the symbol with the two character @code{#@{},
+
+@item
+write the characters of the symbol and
+
+@item
+finish the symbol with the characters @code{@}#}.
@end itemize
Here are a few examples of this form of read syntax; the first
@@ -2859,8 +2864,11 @@ of pairs which looks like a list.}
This is the short definition of what a list is:
@itemize @bullet
-@item Either the empty list @code{()},
-@item or a pair which has a list in its cdr.
+@item
+Either the empty list @code{()},
+
+@item
+or a pair which has a list in its cdr.
@end itemize
@c FIXME::martin: Describe the pair chaining in more detail.
diff --git a/doc/scheme-utility.texi b/doc/scheme-utility.texi
index 543a14569..9254ec449 100644
--- a/doc/scheme-utility.texi
+++ b/doc/scheme-utility.texi
@@ -2,18 +2,50 @@
@node Utility Functions
@chapter General Utility Functions
+@c FIXME::martin: Review me!
+
+This chapter contains information about procedures which are not cleanly
+tied to a specific data type. Because of their wide range of
+applications, they are collected in a @dfn{utlity} chapter.
+
@menu
* Equality:: When are two values `the same'?
* Property Lists:: Managing metainformation about Scheme objects.
* Primitive Properties:: A modern low-level interface to object properties.
* Sorting:: Sort utility procedures.
* Copying:: Copying deep structures.
+* General Conversion:: Converting objects to strings.
@end menu
@node Equality
@section Equality
+@c FIXME::martin: Review me!
+
+@cindex sameness
+@cindex equality
+
+Three different kinds of @dfn{sameness} are defined in Scheme.
+
+@itemize @bullet
+@item
+Two values can refer to exactly the same object.
+
+@item
+Two objects can have the same @dfn{value}.
+
+@item
+Two objects can be structurally equivalent.
+@end itemize
+
+The differentiation between these three kinds is important, because
+determining whether two values are the same objects is very efficient,
+while determining structural equivalence can be quite expensive
+(consider comparing two very long lists). Therefore, three different
+procedures for testing for equality are provided, which correspond to
+the three kinds of @dfn{sameness} defined above.
+
@rnindex eq?
@deffn primitive eq? x y
Return @code{#t} iff @var{x} references the same object as @var{y}.
@@ -114,6 +146,29 @@ Remove any value associated with @var{prop} and @var{obj}.
@node Sorting
@section Sorting
+@c FIXME::martin: Review me!
+
+@cindex sorting
+@cindex sorting lists
+@cindex sorting vectors
+
+Sorting is very important in computer programs. Therefore, Guile comes
+with several sorting procedures built--in. As always, procedures with
+names ending in @code{!} are side--effecting, that means that they may
+modify their parameters in order to produce their results.
+
+The first group of procedures can be used to merge two lists (which must
+be already sorted on their own) and produce sorted lists containing
+all elements of the input lists.
+
+@deffn primitive merge alist blist less
+Take two lists @var{alist} and @var{blist} such that
+@code{(sorted? alist less?)} and @code{(sorted? blist less?)} and
+returns a new list in which the elements of @var{alist} and
+@var{blist} have been stably interleaved so that
+@code{(sorted? (merge alist blist less?) less?)}.
+@end deffn
+
@deffn primitive merge! alist blist less
Takes two lists @var{alist} and @var{blist} such that
@code{(sorted? alist less?)} and @code{(sorted? blist less?)} and
@@ -124,14 +179,26 @@ This is the destructive variant of @code{merge}
Note: this does _not_ accept vectors.
@end deffn
-@deffn primitive merge alist blist less
+The following procedures can operate on sequences which are either
+vectors or list. According to the given arguments, they return sorted
+vectors or lists, respectively. The first of the following procedures
+determines whether a sequence is already sorted, the other sort a given
+sequence. The variants with names starting with @code{stable-} are
+special in that they maintain a special property of the input sequences:
+If two or more elements are the same according to the comparison
+predicate, they are left in the same order as they appeared in the
+input.
+
+@deffn primitive sorted? items less
+Return @code{#t} iff @var{items} is a list or a vector such that
+for all 1 <= i <= m, the predicate @var{less} returns true when
+applied to all elements i - 1 and i
@end deffn
-@deffn primitive restricted-vector-sort! vec less startpos endpos
-Sort the vector @var{vec}, using @var{less} for comparing
-the vector elements. @var{startpos} and @var{endpos} delimit
-the range of the vector which gets sorted. The return value
-is not specified.
+@deffn primitive sort items less
+Sort the sequence @var{items}, which may be a list or a
+vector. @var{less} is used for comparing the sequence
+elements. This is not a stable sort.
@end deffn
@deffn primitive sort! items less
@@ -142,48 +209,54 @@ input sequence is modified to produce the sorted result.
This is not a stable sort.
@end deffn
-@deffn primitive sort items less
+@deffn primitive stable-sort items less
Sort the sequence @var{items}, which may be a list or a
-vector. @var{less} is used for comparing the sequence
-elements. This is not a stable sort.
+vector. @var{less} is used for comparing the sequence elements.
+This is a stable sort.
@end deffn
-@deffn primitive sort-list! items less
-Sort the list @var{items}, using @var{less} for comparing the
-list elements. The sorting is destructive, that means that the
-input list is modified to produce the sorted result.
+@deffn primitive stable-sort! items less
+Sort the sequence @var{items}, which may be a list or a
+vector. @var{less} is used for comparing the sequence elements.
+The sorting is destructive, that means that the input sequence
+is modified to produce the sorted result.
This is a stable sort.
@end deffn
+The procedures in the last group only accept lists or vectors as input,
+as their names indicate.
+
@deffn primitive sort-list items less
Sort the list @var{items}, using @var{less} for comparing the
list elements. This is a stable sort.
@end deffn
-@deffn primitive sorted? items less
-Return @code{#t} iff @var{items} is a list or a vector such that
-for all 1 <= i <= m, the predicate @var{less} returns true when
-applied to all elements i - 1 and i
-@end deffn
-
-@deffn primitive stable-sort! items less
-Sort the sequence @var{items}, which may be a list or a
-vector. @var{less} is used for comparing the sequence elements.
-The sorting is destructive, that means that the input sequence
-is modified to produce the sorted result.
+@deffn primitive sort-list! items less
+Sort the list @var{items}, using @var{less} for comparing the
+list elements. The sorting is destructive, that means that the
+input list is modified to produce the sorted result.
This is a stable sort.
@end deffn
-@deffn primitive stable-sort items less
-Sort the sequence @var{items}, which may be a list or a
-vector. @var{less} is used for comparing the sequence elements.
-This is a stable sort.
+@deffn primitive restricted-vector-sort! vec less startpos endpos
+Sort the vector @var{vec}, using @var{less} for comparing
+the vector elements. @var{startpos} and @var{endpos} delimit
+the range of the vector which gets sorted. The return value
+is not specified.
@end deffn
@node Copying
@section Copying Deep Structures
+@c FIXME::martin: Review me!
+
+The procedures for copying lists (@pxref{Lists}) only produce a flat
+copy of the input list, and currently Guile does not even contain
+procedures for copying vectors. @code{copy-tree} can be used for these
+application, as it does not only copy the spine of a list, but also
+copies any pairs in the cars of the input lists.
+
@deffn primitive copy-tree obj
Recursively copy the data tree that is bound to @var{obj}, and return a
pointer to the new data structure. @code{copy-tree} recurses down the
@@ -193,6 +266,30 @@ any other object.
@end deffn
+@node General Conversion
+@section General String Conversion
+
+@c FIXME::martin: Review me!
+
+When debugging Scheme programs, but also for providing a human--friendly
+interface, a procedure for converting any Scheme object into string
+format is very useful. Conversion from/to strings can of course be done
+with specialized procedures when the data type of the object to convert
+is known, but with this procedure, it is often more comfortable.
+
+@code{object->string} converts an object by using a print procedure for
+writing to a string port, and then returning the resulting string.
+Converting an object back from the string is only possible if the object
+type has a read syntax and the read syntax is preserved by the printing
+procedure.
+
+@deffn primitive object->string obj [printer]
+Return a Scheme string obtained by printing @var{obj}.
+Printing function can be specified by the optional second
+argument @var{printer} (default: @code{write}).
+@end deffn
+
+
@c Local Variables:
@c TeX-master: "guile.texi"
@c End: