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

* scheme-utility.texi (General Conversion): New node, added

Browse source 
`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'.
This commit is contained in:
Martin Grabmüller 2001-04-17 15:34:33 +00:00
parent 216eedfcae
commit 239d2912a2
5 changed files with 298 additions and 155 deletions
Download patch file Download diff file Expand all files Collapse all files

21
doc/ChangeLog
View file

@ -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

108
doc/new-docstrings.texi
View file

@ -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

147
doc/posix.texi
View file

@ -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

22
doc/scheme-data.texi
View file

@ -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.

155
doc/scheme-utility.texi
View file

@ -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: