@node POSIX
@section @acronym{POSIX} System Calls and Networking
+@cindex POSIX
@menu
* Conventions:: Conventions employed by the POSIX interface.
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 with @code{scm-error} (@pxref{Error Reporting}). The
@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,
@node 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:
@node File System
@subsection File System
+@cindex file system
These procedures allow querying and setting file system attributes
(such as owner,
@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
@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
@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
@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
@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
@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
@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
@subsection Signals
+@cindex signal
Procedures to raise, handle and wait for signals.
@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
@node 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
@subsection Networking
+@cindex network
@menu
* Network Address Conversion::
@node Network Address Conversion
@subsubsection Network Address Conversion
+@cindex network address
This section describes procedures which convert internet addresses
between numeric and string formats.
@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
@end deffn
@subsubheading IPv6 Address Conversion
+@cindex IPv6
@deffn {Scheme Procedure} inet-ntop family address
@deffnx {C Function} scm_inet_ntop (family, address)
@node 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.
@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
@end deffn
@subsubheading The Network Database
+@cindex network database
The following functions accept an object representing a network
and return a selected component:
@end deffn
@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:
@end deffn
@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:
@node 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
@node Internet Socket Examples
@subsubsection Network Socket Examples
+@cindex network examples
+@cindex socket examples
The following give examples of how to use network sockets.
@node 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
@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,,
@node 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