summaryrefslogtreecommitdiff
path: root/doc/sources/unix.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/sources/unix.texi')
-rw-r--r--doc/sources/unix.texi622
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.
-