From 239d2912a28f924a6b03463c4307bc3125705e7d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20Grabm=C3=BCller?= Date: Tue, 17 Apr 2001 15:34:33 +0000 Subject: [PATCH] * 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'. --- doc/ChangeLog | 21 ++++++ doc/new-docstrings.texi | 108 ---------------------------- doc/posix.texi | 147 ++++++++++++++++++++++++++++++++++--- doc/scheme-data.texi | 22 ++++-- doc/scheme-utility.texi | 155 ++++++++++++++++++++++++++++++++-------- 5 files changed, 298 insertions(+), 155 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 + + * 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 * 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,30 +209,12 @@ 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. -@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. +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. 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. @@ -174,16 +223,40 @@ 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. +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 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 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: