diff options
Diffstat (limited to 'doc/sources/unix.texi')
-rw-r--r-- | doc/sources/unix.texi | 622 |
1 files changed, 0 insertions, 622 deletions
diff --git a/doc/sources/unix.texi b/doc/sources/unix.texi deleted file mode 100644 index e8a189c5b..000000000 --- a/doc/sources/unix.texi +++ /dev/null @@ -1,622 +0,0 @@ -@node Low level Unix -@chapter Low level Unix interfaces - -The low level Unix interfaces are currently available by -default in the Guile top level. However in the future they will probably -be placed in a module and @code{use-modules} or something similar will -be required to make them available. - -@menu -* Unix conventions:: Conventions followed by the low level Unix - interfaces. -* Ports and descriptors:: Ports, file descriptors and how they - interact. -* Extended I/O:: Reading and writing to ports. -* File system:: Working in a hierarchical filesystem. -* User database:: Information about users from system databases. -* Processes:: Information and control of Unix processes. -* Terminals:: Terminals and pseudo-terminals. -* Network databases:: Network address conversion and information - from system databases. -* Network sockets:: An interface to the BSD socket library. -* Miscellaneous Unix:: Miscellaneous Unix interfaces. -@end menu - -@node Unix conventions -@section Low level Unix conventions - -The low-level interfaces are designed to give Scheme programs -access to as much functionality as possible from the underlying -Unix system. They can be used to implement higher level -intefaces such as the Scheme shell @ref{scsh}. - -Generally there is a single procedure for each corresponding Unix -facility. However some of the procedures are implemented for -speed and convenience in Scheme and have no Unix equivalent -(e.g., @code{read-delimited}, @code{copy-file}.) - -This interface is intended as far as possible to be portable across -different versions of Unix, so that Scheme programmers don't need to be -concerned with implementation differences. In some cases procedures -which can't be implemented (or reimplemented) on particular systems may -become no-ops, or perform limited actions. In other cases they may -throw errors. It should be possible to use the feature system to -determine what functionality is available. - -General naming conventions are as follows: - -@itemize @bullet -@item -The Scheme name is often identical to the name of the underlying Unix -facility. -@item -Underscores in Unix names are converted to hyphens. -@item -Procedures which destructively modify Scheme data gain postpended -exclaimation marks, e.g., @code{recv!}. -@item -Predicates are postpended with question marks, e.g., @code{access?}. -@item -Some names are changed to avoid conflict with dissimilar interfaces -defined by scsh. -@item -Unix preprocessor names such as @code{EPERM} or @code{R_OK} are converted -to Scheme variables of the same name (underscores are not replaced -with hyphens) -@end itemize - -Most of the Unix interface procedures can be relied on to return a -well-specified value. Unexpected conditions are handled by raising -exceptions. - -There are a few procedures which return a special -value if they don't succeed, e.g., @code{getenv} returns @code{#f} -if it the requested string is not found in the environment. These -cases will be noted in the documentation. - -For ways to deal with exceptions, @ref{Exceptions}. - -Errors which the C-library would report by returning a NULL -pointer or through some other means cause a @code{system-error} exception -to be raised. The value of the Unix @code{errno} variable is available -in the data passed by the exception, so there is no need to access the -global errno value (doing so would be unreliable in the presence of -continuations or multiple threads). - -@deffn procedure errno [n] -@end deffn -@deffn procedure perror string -@end deffn - -@node Ports and descriptors -@section Ports and file descriptors - -@deffn procedure move->fdes port fd -@end deffn -@deffn procedure release-port-handle port -@end deffn -@deffn procedure set-port-revealed! @var{port} count -@end deffn -@deffn procedure fdes->ports fdes -@end deffn -@deffn procedure fileno port -@end deffn -@deffn procedure fdopen fdes modes -@end deffn -@deffn procedure duplicate-port port modes -@end deffn -@deffn procedure redirect-port into-port from-port -@end deffn -@deffn procedure freopen filename modes port -@end deffn - -@node Extended I/O -@section Extended I/O - -Extended I/O procedures are available which read or write lines of text, -read text delimited by a specified set of characters, or report or -set the current position of a port. - -@findex fwrite -@findex fread -Interfaces to @code{read}/@code{fread} and @code{write}/@code{fwrite} are -also available, as @code{uniform-array-read!} and @code{uniform-array-write!}, -@ref{Uniform arrays}. - -@deffn procedure read-line [port] [handle-delim] -Return a line of text from @var{port} if specified, otherwise from the -value returned by @code{(current-input-port)}. Under Unix, a line of text -is terminated by the first end-of-line character or by end-of-file. - -If @var{handle-delim} is specified, it should be one of the following -symbols: -@table @code -@item trim -Discard the terminating delimiter. This is the default, but it will -be impossible to tell whether the read terminated with a delimiter or -end-of-file. -@item concat -Append the terminating delimiter (if any) to the returned string. -@item peek -Push the terminating delimiter (if any) back on to the port. -@item split -Return a pair containing the string read from the port and the -terminating delimiter or end-of-file object. - -NOTE: if the scsh module is loaded then -multiple values are returned instead of a pair. -@end table -@end deffn -@deffn procedure read-line! buf [port] -Read a line of text into the supplied string @var{buf} and return the -number of characters added to @var{buf}. If @var{buf} is filled, then -@code{#f} is returned. -Read from @var{port} if -specified, otherwise from the value returned by @code{(current-input-port)}. -@end deffn -@deffn procedure read-delimited delims [port] [handle-delim] -Read text until one of the characters in the string @var{delims} is found -or end-of-file is reached. Read from @var{port} if supplied, otherwise -from the value returned by @code{(current-input-port)}. -@var{handle-delim} takes the same values as described for @code{read-line}. - -NOTE: if the scsh module is loaded then @var{delims} must be an scsh -char-set, not a string. -@end deffn -@deffn procedure read-delimited! delims buf [port] [handle-delim] [start] [end] -Read text into the supplied string @var{buf} and return the number of -characters added to @var{buf} (subject to @var{handle-delim}, which takes -the same values specified for @code{read-line}. If @var{buf} is filled, -@code{#f} is returned for both the number of characters read and the -delimiter. Also terminates if one of the characters in the string -@var{delims} is found -or end-of-file is reached. Read from @var{port} if supplied, otherwise -from the value returned by @code{(current-input-port)}. - -NOTE: if the scsh module is loaded then @var{delims} must be an scsh -char-set, not a string. -@end deffn -@deffn procedure write-line obj [port] -Display @var{obj} and a new-line character to @var{port} if specified, -otherwise to the -value returned by @code{(current-output-port)}; equivalent to: - -@smalllisp -(display obj [port]) -(newline [port]) -@end smalllisp -@end deffn -@deffn procedure ftell port -Returns an integer representing the current position of @var{port}, -measured from the beginning. -@end deffn -@deffn procedure fseek port offset whence -Sets the current position of @var{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 -@defvar SEEK_CUR -Seek from the current position. -@end defvar -@defvar SEEK_END -Seek from the end of the file. -@end defvar -@end deffn - -@node File system -@section File system - -These procedures query and set file system attributes (such as owner, -permissions, sizes and types of files); deleting, copying, renaming and -linking files; creating and removing directories and querying their -contents; and the @code{sync} interface. - -@deffn procedure access? path how -Evaluates to @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 -@defvar W_OK -test for write permission. -@end defvar -@defvar X_OK -test for execute permission. -@end defvar -@defvar F_OK -test for existence of the file. -@end defvar -@end deffn -@findex fstat -@deffn procedure stat obj -Evaluates to 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 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 @r -@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. -@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. -@item stat:nlink -The number of hard links to the file. -@item stat:uid -The user ID of the file's owner. -@item stat:gid -The group ID of the file. -@item stat:rdev -Device ID; this entry is defined only for character or block -special files. -@item stat:size -The size of a regular file in bytes. -@item stat:atime -The last access time for the file. -@item stat:mtime -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. -@item stat: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 @r -@item stat:type -A symbol representing the type of file. Possible values are -currently: regular, directory, symlink, block-special, char-special, -fifo, socket, unknown -@item stat:perms -An integer representing the access permission bits. -@end table -@end deffn -@deffn procedure lstat path -Similar to @code{stat}, but does not follow symbolic links, i.e., -it will return information about a symbolic link itself, not the -file it points to. @var{path} must be a string. -@end deffn -@deffn procedure readlink path -@end deffn -@deffn procedure chown path owner group -@end deffn -@deffn procedure chmod port-or-path mode -@end deffn -@deffn procedure utime path [actime] [modtime] -@end deffn -@deffn procedure delete-file path -@end deffn -@deffn procedure copy-file path-from path-to -@end deffn -@deffn procedure rename-file path-from path-to -@end deffn -@deffn procedure link path-from path-to -@end deffn -@deffn procedure symlink path-from path-to -@end deffn -@deffn procedure mkdir path [mode] -@end deffn -@deffn procedure rmdir path -@end deffn -@deffn procedure opendir path -@end deffn -@deffn procedure readdir port -@end deffn -@deffn procedure rewinddir port -@end deffn -@deffn procedure closedir port -@end deffn -@deffn procedure sync -@end deffn - -@node User database -@section User database - -@deffn procedure getpwuid uid -@end deffn -@deffn procedure getpwnam name -@end deffn -@deffn procedure getpwent -@end deffn -@deffn procedure setpwent port -@end deffn -@deffn procedure endpwent -@end deffn -@deffn procedure getgrgid uid -@end deffn -@deffn procedure getgrnam name -@end deffn -@deffn procedure getgrent -@end deffn -@deffn procedure setgrent port -@end deffn -@deffn procedure endgrent -@end deffn - -@node Processes -@section Processes - -@deffn procedure chdir path -@end deffn -@deffn procedure getcwd -@end deffn -@deffn procedure umask [mode] -@end deffn -@deffn procedure getpid -@end deffn -@deffn procedure getgroups -@end deffn -@deffn procedure kill pid sig - -@var{sig} should be specified using a variable corresponding to -the Unix symbolic name, e.g, -@defvar SIGHUP -Hang-up signal. -@end defvar -@defvar SIGINT -Interrupt signal. -@end defvar -@end deffn -@deffn procedure waitpid pid options -@defvar WAIT_ANY -@end defvar -@defvar WAIT_MYPGRP -@end defvar -@defvar WNOHANG -@end defvar -@defvar WUNTRACED -@end defvar -@end deffn -@deffn procedure getppid -@end deffn -@deffn procedure getuid -@end deffn -@deffn procedure getgid -@end deffn -@deffn procedure geteuid -@end deffn -@deffn procedure getegid -@end deffn -@deffn procedure setuid id -@end deffn -@deffn procedure setgid id -@end deffn -@deffn procedure seteuid id -@end deffn -@deffn procedure setegid id -@end deffn -@deffn procedure getpgrp -@end deffn -@deffn procedure setpgid pid pgid -@end deffn -@deffn procedure setsid -@end deffn -@deffn procedure execl arg ... -@end deffn -@deffn procedure execlp arg ... -@end deffn -@deffn procedure primitive-fork -@end deffn -@deffn procedure environ [env] -@end deffn -@deffn procedure putenv string -@end deffn -@deffn procedure nice incr -@end deffn - -@node Terminals -@section Terminals and pseudo-terminals - -@deffn procedure isatty? port -@end deffn -@deffn procedure ttyname port -@end deffn -@deffn procedure ctermid -@end deffn -@deffn procedure tcgetpgrp port -@end deffn -@deffn procedure tcsetpgrp port pgid -@end deffn - -@node Network databases -@section Network address conversion and system databases - -@deffn procedure inet-aton address -@end deffn -@deffn procedure inet-ntoa number -@end deffn -@deffn procedure inet-netof address -@end deffn -@deffn procedure inet-lnaof address -@end deffn -@deffn procedure inet-makeaddr net lna -@end deffn -@deffn procedure gethostbyname name -@end deffn -@deffn procedure gethostbyaddr address -@end deffn -@deffn procedure gethostent -@end deffn -@deffn procedure sethostent port -@end deffn -@deffn procedure endhostent -@end deffn -@deffn procedure getnetbyname name -@end deffn -@deffn procedure getnetbyaddr address -@end deffn -@deffn procedure getnetent -@end deffn -@deffn procedure setnetent port -@end deffn -@deffn procedure endnetent -@end deffn -@deffn procedure getprotobyname name -@end deffn -@deffn procedure getprotobynumber number -@end deffn -@deffn procedure getprotoent -@end deffn -@deffn procedure setprotoent port -@end deffn -@deffn procedure endprotoent -@end deffn -@deffn procedure getservbyname name protocol -@end deffn -@deffn procedure getservbyport port protocol -@end deffn -@deffn procedure getservent -@end deffn -@deffn procedure setservent port -@end deffn -@deffn procedure endservent -@end deffn - -@node Network sockets -@section BSD socket library interface - -@deffn procedure socket family style protocol -@end deffn -@deffn procedure socketpair family style protocol -@end deffn -@deffn procedure getsockopt socket level optname -@end deffn -@deffn procedure setsockopt socket level optname value -@end deffn -@deffn procedure shutdown socket how -@end deffn -@deffn procedure connect socket family address arg ... -@end deffn -@deffn procedure bind socket family address arg ... -@end deffn -@deffn procedure listen socket backlog -@end deffn -@deffn procedure accept socket -@end deffn -@deffn procedure getsockname socket -@end deffn -@deffn procedure getpeername socket -@end deffn -@deffn procedure recv! socket buf [flags] -@end deffn -@deffn procedure send socket message [flags] -@end deffn -@deffn procedure recvfrom! socket buf [flags] [start] [end] -@end deffn -@deffn procedure sendto socket message family address args ... [flags] -@end deffn - -@node Miscellaneous Unix -@section Miscellaneous Unix interfaces - -Things which haven't been classified elsewhere (yet?). - -@deffn procedure open path flags [mode] -@defvar O_RDONLY -@end defvar -@defvar O_WRONLY -@end defvar -@defvar O_RDWR -@end defvar -@defvar O_CREAT -@end defvar -@defvar O_EXCL -@end defvar -@defvar O_NOCTTY -@end defvar -@defvar O_TRUNC -@end defvar -@defvar O_APPEND -@end defvar -@defvar O_NONBLOCK -@end defvar -@defvar O_NDELAY -@end defvar -@defvar O_SYNC -@end defvar -@end deffn -@deffn procedure select reads writes excepts secs msecs -@end deffn -@deffn procedure uname -@end deffn -@deffn procedure pipe -@end deffn -@deffn procedure open-pipe command modes -@end deffn -@deffn procedure open-input-pipe command -@end deffn -@deffn procedure open-output-pipe command -@end deffn -@deffn procedure setlocale category [locale] -@defvar LC_COLLATE -@end defvar -@defvar LC_CTYPE -@end defvar -@defvar LC_MONETARY -@end defvar -@defvar LC_NUMERIC -@end defvar -@defvar LC_TIME -@end defvar -@defvar LC_MESSAGES -@end defvar -@defvar LC_ALL -@end defvar -@end deffn -@deffn procedure strftime format stime -@end deffn -@deffn procedure strptime format string -@end deffn -@deffn procedure mknod -@end deffn - -@node scsh -@chapter The Scheme shell (scsh) - -Guile includes an incomplete port of the Scheme shell (scsh) 0.4.4. - -For information about scsh on the Web see -@url{http://www-swiss.ai.mit.edu/scsh/scsh.html}. -The original scsh is available by ftp from -@url{ftp://swiss-ftp.ai.mit.edu:/pub/su}. - -This port of scsh does not currently use the Guile module system, but -can be initialized using: -@smalllisp -(load-from-path "scsh/init") -@end smalllisp - -Note that SLIB must be installed before scsh can be initialized, see -@ref{SLIB} for details. - -@node Threads -@chapter Programming Threads. - |