+@c -*-texinfo-*-
+@c This is part of the GNU Guile Reference Manual.
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
+@c Free Software Foundation, Inc.
+@c See the file guile.texi for copying conditions.
+
@node POSIX
-@chapter @acronym{POSIX} System Calls and Networking
+@section @acronym{POSIX} System Calls and Networking
+@cindex POSIX
@menu
* Conventions:: Conventions employed by the POSIX interface.
@end menu
@node Conventions
-@section @acronym{POSIX} Interface Conventions
+@subsection @acronym{POSIX} Interface Conventions
These interfaces provide access to operating system facilities.
They provide a simple wrapping around the underlying C interfaces
For ways to deal with exceptions, see @ref{Exceptions}.
+@cindex @code{errno}
Errors which the C library would report by returning a null pointer or
through some other means are reported by raising a @code{system-error}
-exception. The value of the Unix @code{errno} variable is available
-in the data passed by the exception.
+exception with @code{scm-error} (@pxref{Error Reporting}). The
+@var{data} parameter is a list containing the Unix @code{errno} value
+(an integer). For example,
+
+@example
+(define (my-handler key func fmt fmtargs data)
+ (display key) (newline)
+ (display func) (newline)
+ (apply format #t fmt fmtargs) (newline)
+ (display data) (newline))
+
+(catch 'system-error
+ (lambda () (dup2 -123 -456))
+ my-handler)
+
+@print{}
+system-error
+dup2
+Bad file descriptor
+(9)
+@end example
-It can be extracted with the function @code{system-error-errno}:
+
+@sp 1
+@defun system-error-errno arglist
+@cindex @code{errno}
+Return the @code{errno} value from a list which is the arguments to an
+exception handler. If the exception is not a @code{system-error},
+then the return is @code{#f}. For example,
@example
(catch
(display (strerror errno))))
(newline))))
@end example
+@end defun
+
@node Ports and File Descriptors
-@section Ports and File Descriptors
+@subsection Ports and File Descriptors
+@cindex file descriptor
Conventions generally follow those of scsh, @ref{The Scheme shell (scsh)}.
@deffn {Scheme Procedure} pipe
@deffnx {C Function} scm_pipe ()
+@cindex pipe
Return a newly created pipe: a pair of ports which are linked
together on the local machine. The @acronym{CAR} is the input
port and the @acronym{CDR} is the output port. Data written (and
@deffn {Scheme Procedure} setvbuf port mode [size]
@deffnx {C Function} scm_setvbuf (port, mode, size)
+@cindex port buffering
Set the buffering mode for @var{port}. @var{mode} can be:
@defvar _IONBF
@deffn {Scheme Procedure} flock file operation
@deffnx {C Function} scm_flock (file, operation)
+@cindex file locking
Apply or remove an advisory lock on an open file.
@var{operation} specifies the action to be done:
@end deffn
@node File System
-@section File System
+@subsection File System
+@cindex file system
These procedures allow querying and setting file system attributes
(such as owner,
@deffn {Scheme Procedure} access? path how
@deffnx {C Function} scm_access (path, how)
-Return @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.
+Test accessibility of a file under the real UID and GID of the calling
+process. The return is @code{#t} if @var{path} exists and the
+permissions requested by @var{how} are all allowed, or @code{#f} if
+not.
-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.
+@var{how} is an integer which is one of the following values, or a
+bitwise-OR (@code{logior}) of multiple values.
@defvar R_OK
-test for read permission.
+Test for read permission.
@end defvar
@defvar W_OK
-test for write permission.
+Test for write permission.
@end defvar
@defvar X_OK
-test for execute permission.
+Test for execute permission.
@end defvar
@defvar F_OK
-test for existence of the file.
+Test for existence of the file. This is implied by each of the other
+tests, so there's no need to combine it with them.
@end defvar
+
+It's important to note that @code{access?} does not simply indicate
+what will happen on attempting to read or write a file. In normal
+circumstances it does, but in a set-UID or set-GID program it doesn't
+because @code{access?} tests the real ID, whereas an open or execute
+attempt uses the effective ID.
+
+A program which will never run set-UID/GID can ignore the difference
+between real and effective IDs, but for maximum generality, especially
+in library functions, it's best not to use @code{access?} to predict
+the result of an open or execute, instead simply attempt that and
+catch any exception.
+
+The main use for @code{access?} is to let a set-UID/GID program
+determine what the invoking user would have been allowed to do,
+without the greater (or perhaps lesser) privileges afforded by the
+effective ID. For more on this, see @ref{Testing File Access,,, libc,
+The GNU C Library Reference Manual}.
@end deffn
@findex fstat
@deffn {Scheme Procedure} utime pathname [actime [modtime]]
@deffnx {C Function} scm_utime (pathname, actime, modtime)
+@cindex file times
@code{utime} sets the access and modification times for the
file named by @var{path}. If @var{actime} or @var{modtime} is
not supplied, then the current time is used. @var{actime} and
@deffn {Scheme Procedure} opendir dirname
@deffnx {C Function} scm_opendir (dirname)
+@cindex directory contents
Open the directory specified by @var{dirname} and return a directory
stream.
@end deffn
@deffn {Scheme Procedure} mknod path type perms dev
@deffnx {C Function} scm_mknod (path, type, perms, dev)
+@cindex device file
Creates a new special file, such as a file corresponding to a device.
@var{path} specifies the name of the file. @var{type} should be one
of the following symbols: @samp{regular}, @samp{directory},
@deffn {Scheme Procedure} tmpnam
@deffnx {C Function} scm_tmpnam ()
+@cindex temporary file
Return a name in the file system that does not match any
existing file. However there is no guarantee that another
process will not create the file after @code{tmpnam} is called.
@deffn {Scheme Procedure} mkstemp! tmpl
@deffnx {C Function} scm_mkstemp (tmpl)
+@cindex temporary file
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 @samp{XXXXXX} and will be changed in
place to return the name of the temporary file.
+
+The file is created with mode @code{0600}, which means read and write
+for the owner only. @code{chmod} can be used to change this.
@end deffn
@deffn {Scheme Procedure} dirname filename
@node User Information
-@section User Information
+@subsection User Information
+@cindex user information
+@cindex password file
+@cindex group file
The facilities in this section provide an interface to the user and
group database.
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.
+
+This function has been removed from the latest POSIX specification,
+Guile provides it only if the system has it. Using @code{(getpwuid
+(geteuid))} may be a better idea.
@end deffn
@deffn {Scheme Procedure} getlogin
@node Time
-@section Time
+@subsection Time
+@cindex time
@deffn {Scheme Procedure} current-time
@deffnx {C Function} scm_current_time ()
@deffn {Scheme Procedure} localtime time [zone]
@deffnx {C Function} scm_localtime (time, zone)
+@cindex local time
Return an object representing the broken down components of
@var{time}, an integer like the one returned by
@code{current-time}. The time zone for the calculation is
@deffn {Scheme Procedure} strftime format stime
@deffnx {C Function} scm_strftime (format, stime)
+@cindex time formatting
Formats a time specification @var{time} using @var{template}. @var{time}
is an object with time components in the form returned by @code{localtime}
or @code{gmtime}. @var{template} is a string which can include formatting
specifications introduced by a @samp{%} character. The formatting of
month and day names is dependent on the current locale. The value returned
is the formatted string.
-@xref{Formatting Date and Time, , , libc, The GNU C Library Reference Manual}.
+@xref{Formatting Calendar Time, , , libc, The GNU C Library Reference Manual}.
@lisp
(strftime "%c" (localtime (current-time)))
@deffn {Scheme Procedure} strptime format string
@deffnx {C Function} scm_strptime (format, string)
+@cindex time parsing
Performs the reverse action to @code{strftime}, parsing
@var{string} according to the specification supplied in
@var{template}. The interpretation of month and day names is
@end deffn
@node Runtime Environment
-@section Runtime Environment
+@subsection Runtime Environment
@deffn {Scheme Procedure} program-arguments
@deffnx {Scheme Procedure} command-line
@deffnx {C Function} scm_program_arguments ()
+@cindex command line
+@cindex program arguments
Return the list of command line arguments passed to Guile, as a list of
strings. The list includes the invoked program name, which is usually
@code{"guile"}, but excludes switches and parameters for command line
@deffn {Scheme Procedure} getenv nam
@deffnx {C Function} scm_getenv (nam)
+@cindex environment
Looks up the string @var{name} in the current environment. The return
value is @code{#f} unless a string of the form @code{NAME=VALUE} is
found, in which case the string @code{VALUE} is returned.
@node Processes
-@section Processes
+@subsection Processes
+@cindex processes
+@cindex child processes
@findex cd
@deffn {Scheme Procedure} chdir str
@deffnx {C Function} scm_chdir (str)
+@cindex current directory
Change the current working directory to @var{path}.
The return value is unspecified.
@end deffn
system supports effective IDs.
@end deffn
+@deffn {Scheme Procedure} setgroups vec
+@deffnx {C Function} scm_setgroups (vec)
+Set the current set of supplementary group IDs to the integers in the
+given vector @var{vec}. The return value is unspecified.
+
+Generally only the superuser can set the process group IDs
+(@pxref{Setting Groups, Setting the Group IDs,, libc, The GNU C
+Library Reference Manual}).
+@end deffn
+
@deffn {Scheme Procedure} setuid id
@deffnx {C Function} scm_setuid (id)
Sets both the real and effective user IDs to the integer @var{id}, provided
indicating whether the command processor is available.
@end deffn
+@deffn {Scheme Procedure} system* . args
+@deffnx {C Function} scm_system_star (args)
+Execute the command indicated by @var{args}. The first element must
+be a string indicating the command to be executed, and the remaining
+items must be strings representing each of the arguments to that
+command.
+
+This function returns the exit status of the command as provided by
+@code{waitpid}. This value can be handled with @code{status:exit-val}
+and the related functions.
+
+@code{system*} is similar to @code{system}, but accepts only one
+string per-argument, and performs no shell interpretation. The
+command is executed using fork and execlp. Accordingly this function
+may be safer than @code{system} in situations where shell
+interpretation is not required.
+
+Example: (system* "echo" "foo" "bar")
+@end deffn
+
@deffn {Scheme Procedure} primitive-exit [status]
@deffnx {C Function} scm_primitive_exit (status)
Terminate the current process without unwinding the Scheme stack.
@deffn {Scheme Procedure} nice incr
@deffnx {C Function} scm_nice (incr)
+@cindex process priority
Increment the priority of the current process by @var{incr}. A higher
priority value means that the process runs less often.
The return value is unspecified.
@node Signals
-@section Signals
+@subsection Signals
+@cindex signal
Procedures to raise, handle and wait for signals.
@node Terminals and Ptys
-@section Terminals and Ptys
+@subsection Terminals and Ptys
@deffn {Scheme Procedure} isatty? port
@deffnx {C Function} scm_isatty_p (port)
+@cindex terminal
Return @code{#t} if @var{port} is using a serial non--file
device, otherwise @code{#f}.
@end deffn
@deffn {Scheme Procedure} ttyname port
@deffnx {C Function} scm_ttyname (port)
+@cindex terminal
Return a string with the name of the serial terminal device
underlying @var{port}.
@end deffn
@deffn {Scheme Procedure} ctermid
@deffnx {C Function} scm_ctermid ()
+@cindex terminal
Return a string containing the file name of the controlling
terminal for the current process.
@end deffn
@deffn {Scheme Procedure} tcgetpgrp port
@deffnx {C Function} scm_tcgetpgrp (port)
+@cindex process group
Return the process group ID of the foreground process group
associated with the terminal open on the file descriptor
underlying @var{port}.
@deffn {Scheme Procedure} tcsetpgrp port pgid
@deffnx {C Function} scm_tcsetpgrp (port, pgid)
+@cindex process group
Set the foreground process group ID for the terminal used by the file
descriptor underlying @var{port} to the integer @var{pgid}.
The calling process
@end deffn
@node Pipes
-@section Pipes
+@subsection Pipes
+@cindex pipe
-The following procedures provide an interface to the @code{popen} and
+The following procedures are similar to the @code{popen} and
@code{pclose} system routines. The code is in a separate ``popen''
module:
@end smalllisp
@findex popen
-@deffn {Scheme Procedure} open-pipe command modes
-Executes the shell command @var{command} (a string) in a subprocess.
-A pipe to the process is created and returned. @var{modes} specifies
-whether an input or output pipe to the process is created: it should
-be the value of @code{OPEN_READ} or @code{OPEN_WRITE}.
+@deffn {Scheme Procedure} open-pipe command mode
+@deffnx {Scheme Procedure} open-pipe* mode prog [args...]
+Execute a command in a subprocess, with a pipe to it or from it, or
+with pipes in both directions.
+
+@code{open-pipe} runs the shell @var{command} using @samp{/bin/sh -c}.
+@code{open-pipe*} executes @var{prog} directly, with the optional
+@var{args} arguments (all strings).
+
+@var{mode} should be one of the following values. @code{OPEN_READ} is
+an input pipe, ie.@: to read from the subprocess. @code{OPEN_WRITE}
+is an output pipe, ie.@: to write to it.
+
+@defvar OPEN_READ
+@defvarx OPEN_WRITE
+@defvarx OPEN_BOTH
+@end defvar
+
+For an input pipe, the child's standard output is the pipe and
+standard input is inherited from @code{current-input-port}. For an
+output pipe, the child's standard input is the pipe and standard
+output is inherited from @code{current-output-port}. In all cases
+cases the child's standard error is inherited from
+@code{current-error-port} (@pxref{Default Ports}).
+
+If those @code{current-X-ports} are not files of some kind, and hence
+don't have file descriptors for the child, then @file{/dev/null} is
+used instead.
+
+Care should be taken with @code{OPEN_BOTH}, a deadlock will occur if
+both parent and child are writing, and waiting until the write
+completes before doing any reading. Each direction has
+@code{PIPE_BUF} bytes of buffering (@pxref{Ports and File
+Descriptors}), which will be enough for small writes, but not for say
+putting a big file through a filter.
@end deffn
@deffn {Scheme Procedure} open-input-pipe command
Equivalent to @code{open-pipe} with mode @code{OPEN_READ}.
@lisp
-(read-line (open-input-pipe "date"))
-@result{} "Mon Mar 11 20:10:44 GMT 2002"
-
-(waitpid WAIT_ANY)
-@result{} (24160 . 0)
+(let* ((port (open-input-pipe "date --utc"))
+ (str (read-line port)))
+ (close-pipe port)
+ str)
+@result{} "Mon Mar 11 20:10:44 UTC 2002"
@end lisp
@end deffn
@deffn {Scheme Procedure} open-output-pipe command
Equivalent to @code{open-pipe} with mode @code{OPEN_WRITE}.
+
+@lisp
+(let ((port (open-output-pipe "lpr")))
+ (display "Something for the line printer.\n" port)
+ (if (not (eqv? 0 (status:exit-val (close-pipe port))))
+ (error "Cannot print")))
+@end lisp
+@end deffn
+
+@deffn {Scheme Procedure} open-input-output-pipe command
+Equivalent to @code{open-pipe} with mode @code{OPEN_BOTH}.
@end deffn
@findex pclose
@deffn {Scheme Procedure} close-pipe port
-Closes the pipe created by @code{open-pipe}, then waits for the process
-to terminate and returns its status value, @xref{Processes, waitpid}, for
-information on how to interpret this value.
-
-@code{close-port} (@pxref{Closing, close-port}) can also be used to
-close a pipe, but doesn't return the status.
+Close a pipe created by @code{open-pipe}, wait for the process to
+terminate, and return the wait status code. The status is as per
+@code{waitpid} and can be decoded with @code{status:exit-val} etc
+(@pxref{Processes})
@end deffn
+@sp 1
+@code{waitpid WAIT_ANY} should not be used when pipes are open, since
+it can reap a pipe's child process, causing an error from a subsequent
+@code{close-pipe}.
+
+@code{close-port} (@pxref{Closing}) can close a pipe, but it doesn't
+reap the child process.
+
+The garbage collector will close a pipe no longer in use, and reap the
+child process with @code{waitpid}. If the child hasn't yet terminated
+the garbage collector doesn't block, but instead checks again in the
+next GC.
+
+Many systems have per-user and system-wide limits on the number of
+processes, and a system-wide limit on the number of pipes, so pipes
+should be closed explicitly when no longer needed, rather than letting
+the garbage collector pick them up at some later time.
+
+
@node Networking
-@section Networking
+@subsection Networking
+@cindex network
@menu
* Network Address Conversion::
@end menu
@node Network Address Conversion
-@subsection Network Address Conversion
+@subsubsection Network Address Conversion
+@cindex network address
This section describes procedures which convert internet addresses
between numeric and string formats.
-@subsubsection IPv4 Address Conversion
+@subsubheading IPv4 Address Conversion
+@cindex IPv4
+
+An IPv4 Internet address is a 4-byte value, represented in Guile as an
+integer in network byte order (meaning the first byte is the most
+significant in the number).
+
+@defvar INADDR_LOOPBACK
+The address of the local host using the loopback device, ie.@:
+@samp{127.0.0.1}.
+@end defvar
+
+@defvar INADDR_BROADCAST
+The broadcast address on the local network.
+@end defvar
+
+@c INADDR_NONE is defined in the code, but serves no purpose.
+@c inet_addr() returns it as an error indication, but that function
+@c isn't provided, for the good reason that inet_aton() does the same
+@c job and gives an unambiguous error indication. (INADDR_NONE is a
+@c valid 4-byte value, in glibc it's the same as INADDR_BROADCAST.)
+@c
+@c @defvar INADDR_NONE
+@c No address.
+@c @end defvar
@deffn {Scheme Procedure} inet-aton address
@deffnx {C Function} scm_inet_aton (address)
@end lisp
@end deffn
-@subsubsection IPv6 Address Conversion
+@subsubheading IPv6 Address Conversion
+@cindex IPv6
@deffn {Scheme Procedure} inet-ntop family address
@deffnx {C Function} scm_inet_ntop (family, address)
@node Network Databases
-@subsection Network Databases
+@subsubsection Network Databases
+@cindex network database
This section describes procedures which query various network databases.
Care should be taken when using the database routines since they are not
reentrant.
-@subsubsection The Host Database
+@subsubheading The Host Database
+@cindex @file{/etc/hosts}
+@cindex network database
A @dfn{host object} is a structure that represents what is known about a
network host, and is the usual way of representing a system's network
If @var{stayopen} is omitted, this is equivalent to @code{endhostent}.
Otherwise it is equivalent to @code{sethostent stayopen}.
@end deffn
-@subsubsection The Network Database
+
+@subsubheading The Network Database
+@cindex network database
The following functions accept an object representing a network
and return a selected component:
Otherwise it is equivalent to @code{setnetent stayopen}.
@end deffn
-@subsubsection The Protocol Database
+@subsubheading The Protocol Database
+@cindex @file{/etc/protocols}
+@cindex protocols
+@cindex network protocols
The following functions accept an object representing a protocol
and return a selected component:
Otherwise it is equivalent to @code{setprotoent stayopen}.
@end deffn
-@subsubsection The Service Database
+@subsubheading The Service Database
+@cindex @file{/etc/services}
+@cindex services
+@cindex network services
The following functions accept an object representing a service
and return a selected component:
@end deffn
@node Network Sockets and Communication
-@subsection Network Sockets and Communication
+@subsubsection Network Sockets and Communication
+@cindex socket
+@cindex network socket
Socket ports can be created using @code{socket} and @code{socketpair}.
The ports are initially unbuffered, to make reading and writing to the
@defvar SOCK_STREAM
@defvarx SOCK_DGRAM
@defvarx SOCK_RAW
+@defvarx SOCK_RDM
+@defvarx SOCK_SEQPACKET
@end defvar
@var{proto} can be obtained from a protocol name using
@node Internet Socket Examples
-@subsection Network Socket Examples
-
-The following sections give examples of how to use network sockets.
-
-@menu
-* Internet Socket Client::
-* Internet Socket Server::
-@end menu
+@subsubsection Network Socket Examples
+@cindex network examples
+@cindex socket examples
+The following give examples of how to use network sockets.
-@node Internet Socket Client
-@subsubsection Internet Socket Client Example
+@subsubheading Internet Socket Client Example
@cindex socket client example
The following example demonstrates an Internet socket client.
returns the contents of the root index URL.
@example
-(let ((s (socket AF_INET SOCK_STREAM 0)))
+(let ((s (socket PF_INET SOCK_STREAM 0)))
(connect s AF_INET (inet-aton "127.0.0.1") 80)
(display "GET / HTTP/1.0\r\n\r\n" s)
@end example
-@node Internet Socket Server
-@subsubsection Internet Socket Server Example
+@subsubheading Internet Socket Server Example
@cindex socket server example
The following example shows a simple Internet server which listens on
client.
@example
-(let ((s (socket AF_INET SOCK_STREAM 0)))
+(let ((s (socket PF_INET SOCK_STREAM 0)))
(setsockopt s SOL_SOCKET SO_REUSEADDR 1)
;; @r{Specific address?}
;; @r{(bind s AF_INET (inet-aton "127.0.0.1") 2904)}
@node System Identification
-@section System Identification
+@subsection System Identification
+@cindex system name
This section lists the various procedures Guile provides for accessing
information about the system it runs on.
@deffn {Scheme Procedure} gethostname
@deffnx {C Function} scm_gethostname ()
+@cindex host name
Return the host name of the current processor.
@end deffn
specified.
@end deffn
-@c FIXME::martin: Not in libguile!
-@deffn {Scheme Procedure} software-type
-Return a symbol describing the current platform's operating system.
-This may be one of @samp{AIX}, @samp{VMS}, @samp{UNIX},
-@samp{COHERENT}, @samp{WINDOWS}, @samp{MS-DOS}, @samp{OS/2},
-@samp{THINKC}, @samp{AMIGA}, @samp{ATARIST}, @samp{MACH}, or
-@samp{ACORN}.
-
-Note that most varieties of Unix are considered to be simply @samp{UNIX}.
-That is because when a program depends on features that are not present
-on every operating system, it is usually better to test for the presence
-or absence of that specific feature. The return value of
-@code{software-type} should only be used for this purpose when there is
-no other easy or unambiguous way of detecting such features.
-@end deffn
-
@node Locales
-@section Locales
+@subsection Locales
+@cindex locale
@deffn {Scheme Procedure} setlocale category [locale]
@deffnx {C Function} scm_setlocale (category, locale)
Get or set the current locale, used for various internationalizations.
Locales are strings, such as @samp{sv_SE}.
-If @var{locale} is given then the locale for the given category is set
+If @var{locale} is given then the locale for the given @var{category} is set
and the new value returned. If @var{locale} is not given then the
current value is returned. @var{category} should be one of the
following values
@defvarx LC_TIME
@end defvar
+@cindex @code{LANG}
A common usage is @samp{(setlocale LC_ALL "")}, which initializes all
categories based on standard environment variables (@code{LANG} etc).
For full details on categories and locale names @pxref{Locales,,
@end deffn
@node Encryption
-@section Encryption
+@subsection Encryption
+@cindex encryption
Please note that the procedures in this section are not suited for
strong encryption, they are only interfaces to the well-known and
@deffn {Scheme Procedure} getpass prompt
@deffnx {C Function} scm_getpass (prompt)
+@cindex password
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
the password, echoing and the generation of signals by special
characters is disabled.
@end deffn
+
+
+@c Local Variables:
+@c TeX-master: "guile.texi"
+@c End:
HCoop / bpt / guile.git / blobdiff