2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
8 @section @acronym{POSIX} System Calls and Networking
11 * Conventions:: Conventions employed by the POSIX interface.
12 * Ports and File Descriptors:: Scheme ``ports'' and Unix file descriptors
13 have different representations.
14 * File System:: stat, chown, chmod, etc.
15 * User Information:: Retrieving a user's GECOS (/etc/passwd) entry.
16 * Time:: gettimeofday, localtime, strftime, etc.
17 * Runtime Environment:: Accessing and modifying Guile's environment.
18 * Processes:: getuid, getpid, etc.
19 * Signals:: sigaction, kill, pause, alarm, setitimer, etc.
20 * Terminals and Ptys:: ttyname, tcsetpgrp, etc.
21 * Pipes:: Communicating data between processes.
22 * Networking:: gethostbyaddr, getnetent, socket, bind, listen.
23 * System Identification:: Obtaining information about the system.
24 * Locales:: setlocale, etc.
29 @subsection @acronym{POSIX} Interface Conventions
31 These interfaces provide access to operating system facilities.
32 They provide a simple wrapping around the underlying C interfaces
33 to make usage from Scheme more convenient. They are also used
34 to implement the Guile port of scsh (@pxref{The Scheme shell (scsh)}).
36 Generally there is a single procedure for each corresponding Unix
37 facility. There are some exceptions, such as procedures implemented for
38 speed and convenience in Scheme with no primitive Unix equivalent,
39 e.g.@: @code{copy-file}.
41 The interfaces are intended as far as possible to be portable across
42 different versions of Unix. In some cases procedures which can't be
43 implemented on particular systems may become no-ops, or perform limited
44 actions. In other cases they may throw errors.
46 General naming conventions are as follows:
50 The Scheme name is often identical to the name of the underlying Unix
53 Underscores in Unix procedure names are converted to hyphens.
55 Procedures which destructively modify Scheme data have exclamation
56 marks appended, e.g., @code{recv!}.
58 Predicates (returning only @code{#t} or @code{#f}) have question marks
59 appended, e.g., @code{access?}.
61 Some names are changed to avoid conflict with dissimilar interfaces
62 defined by scsh, e.g., @code{primitive-fork}.
64 Unix preprocessor names such as @code{EPERM} or @code{R_OK} are converted
65 to Scheme variables of the same name (underscores are not replaced
69 Unexpected conditions are generally handled by raising exceptions.
70 There are a few procedures which return a special value if they don't
71 succeed, e.g., @code{getenv} returns @code{#f} if it the requested
72 string is not found in the environment. These cases are noted in
75 For ways to deal with exceptions, see @ref{Exceptions}.
77 Errors which the C library would report by returning a null pointer or
78 through some other means are reported by raising a @code{system-error}
79 exception with @code{scm-error} (@pxref{Error Reporting}). The
80 @var{data} parameter is a list containing the Unix @code{errno} value
81 (an integer). For example,
84 (define (my-handler key func fmt fmtargs data)
85 (display key) (newline)
86 (display func) (newline)
87 (apply format #t fmt fmtargs) (newline)
88 (display data) (newline))
91 (lambda () (dup2 -123 -456))
103 @defun system-error-errno arglist
104 Return the @code{errno} value from a list which is the arguments to an
105 exception handler. If the exception is not a @code{system-error},
106 then the return is @code{#f}. For example,
112 (mkdir "/this-ought-to-fail-if-I'm-not-root"))
114 (let ((errno (system-error-errno stuff)))
117 (display "You're not allowed to do that."))
119 (display "Already exists."))
121 (display (strerror errno))))
127 @node Ports and File Descriptors
128 @subsection Ports and File Descriptors
130 Conventions generally follow those of scsh, @ref{The Scheme shell (scsh)}.
132 File ports are implemented using low-level operating system I/O
133 facilities, with optional buffering to improve efficiency; see
136 Note that some procedures (e.g., @code{recv!}) will accept ports as
137 arguments, but will actually operate directly on the file descriptor
138 underlying the port. Any port buffering is ignored, including the
139 buffer which implements @code{peek-char} and @code{unread-char}.
141 The @code{force-output} and @code{drain-input} procedures can be used
142 to clear the buffers.
144 Each open file port has an associated operating system file descriptor.
145 File descriptors are generally not useful in Scheme programs; however
146 they may be needed when interfacing with foreign code and the Unix
149 A file descriptor can be extracted from a port and a new port can be
150 created from a file descriptor. However a file descriptor is just an
151 integer and the garbage collector doesn't recognize it as a reference
152 to the port. If all other references to the port were dropped, then
153 it's likely that the garbage collector would free the port, with the
154 side-effect of closing the file descriptor prematurely.
156 To assist the programmer in avoiding this problem, each port has an
157 associated @dfn{revealed count} which can be used to keep track of how many
158 times the underlying file descriptor has been stored in other places.
159 If a port's revealed count is greater than zero, the file descriptor
160 will not be closed when the port is garbage collected. A programmer
161 can therefore ensure that the revealed count will be greater than
162 zero if the file descriptor is needed elsewhere.
164 For the simple case where a file descriptor is ``imported'' once to become
165 a port, it does not matter if the file descriptor is closed when the
166 port is garbage collected. There is no need to maintain a revealed
167 count. Likewise when ``exporting'' a file descriptor to the external
168 environment, setting the revealed count is not required provided the
169 port is kept open (i.e., is pointed to by a live Scheme binding) while
170 the file descriptor is in use.
172 To correspond with traditional Unix behaviour, three file descriptors
173 (0, 1, and 2) are automatically imported when a program starts up and
174 assigned to the initial values of the current/standard input, output,
175 and error ports, respectively. The revealed count for each is
176 initially set to one, so that dropping references to one of these
177 ports will not result in its garbage collection: it could be retrieved
178 with @code{fdopen} or @code{fdes->ports}.
180 @deffn {Scheme Procedure} port-revealed port
181 @deffnx {C Function} scm_port_revealed (port)
182 Return the revealed count for @var{port}.
185 @deffn {Scheme Procedure} set-port-revealed! port rcount
186 @deffnx {C Function} scm_set_port_revealed_x (port, rcount)
187 Sets the revealed count for a @var{port} to @var{rcount}.
188 The return value is unspecified.
191 @deffn {Scheme Procedure} fileno port
192 @deffnx {C Function} scm_fileno (port)
193 Return the integer file descriptor underlying @var{port}. Does
194 not change its revealed count.
197 @deffn {Scheme Procedure} port->fdes port
198 Returns the integer file descriptor underlying @var{port}. As a
199 side effect the revealed count of @var{port} is incremented.
202 @deffn {Scheme Procedure} fdopen fdes modes
203 @deffnx {C Function} scm_fdopen (fdes, modes)
204 Return a new port based on the file descriptor @var{fdes}. Modes are
205 given by the string @var{modes}. The revealed count of the port is
206 initialized to zero. The @var{modes} string is the same as that
207 accepted by @code{open-file} (@pxref{File Ports, open-file}).
210 @deffn {Scheme Procedure} fdes->ports fd
211 @deffnx {C Function} scm_fdes_to_ports (fd)
212 Return a list of existing ports which have @var{fdes} as an
213 underlying file descriptor, without changing their revealed
217 @deffn {Scheme Procedure} fdes->inport fdes
218 Returns an existing input port which has @var{fdes} as its underlying file
219 descriptor, if one exists, and increments its revealed count.
220 Otherwise, returns a new input port with a revealed count of 1.
223 @deffn {Scheme Procedure} fdes->outport fdes
224 Returns an existing output port which has @var{fdes} as its underlying file
225 descriptor, if one exists, and increments its revealed count.
226 Otherwise, returns a new output port with a revealed count of 1.
229 @deffn {Scheme Procedure} primitive-move->fdes port fd
230 @deffnx {C Function} scm_primitive_move_to_fdes (port, fd)
231 Moves the underlying file descriptor for @var{port} to the integer
232 value @var{fdes} without changing the revealed count of @var{port}.
233 Any other ports already using this descriptor will be automatically
234 shifted to new descriptors and their revealed counts reset to zero.
235 The return value is @code{#f} if the file descriptor already had the
236 required value or @code{#t} if it was moved.
239 @deffn {Scheme Procedure} move->fdes port fdes
240 Moves the underlying file descriptor for @var{port} to the integer
241 value @var{fdes} and sets its revealed count to one. Any other ports
242 already using this descriptor will be automatically
243 shifted to new descriptors and their revealed counts reset to zero.
244 The return value is unspecified.
247 @deffn {Scheme Procedure} release-port-handle port
248 Decrements the revealed count for a port.
251 @deffn {Scheme Procedure} fsync object
252 @deffnx {C Function} scm_fsync (object)
253 Copies any unwritten data for the specified output file descriptor to disk.
254 If @var{port/fd} is a port, its buffer is flushed before the underlying
255 file descriptor is fsync'd.
256 The return value is unspecified.
259 @deffn {Scheme Procedure} open path flags [mode]
260 @deffnx {C Function} scm_open (path, flags, mode)
261 Open the file named by @var{path} for reading and/or writing.
262 @var{flags} is an integer specifying how the file should be opened.
263 @var{mode} is an integer specifying the permission bits of the file,
264 if it needs to be created, before the umask (@pxref{Processes}) is
265 applied. The default is 666 (Unix itself has no default).
267 @var{flags} can be constructed by combining variables using @code{logior}.
271 Open the file read-only.
274 Open the file write-only.
277 Open the file read/write.
280 Append to the file instead of truncating.
283 Create the file if it does not already exist.
286 @xref{File Status Flags,,,libc,The GNU C Library Reference Manual},
287 for additional flags.
290 @deffn {Scheme Procedure} open-fdes path flags [mode]
291 @deffnx {C Function} scm_open_fdes (path, flags, mode)
292 Similar to @code{open} but return a file descriptor instead of
296 @deffn {Scheme Procedure} close fd_or_port
297 @deffnx {C Function} scm_close (fd_or_port)
298 Similar to @code{close-port} (@pxref{Closing, close-port}),
299 but also works on file descriptors. A side
300 effect of closing a file descriptor is that any ports using that file
301 descriptor are moved to a different file descriptor and have
302 their revealed counts set to zero.
305 @deffn {Scheme Procedure} close-fdes fd
306 @deffnx {C Function} scm_close_fdes (fd)
307 A simple wrapper for the @code{close} system call. Close file
308 descriptor @var{fd}, which must be an integer. Unlike @code{close},
309 the file descriptor will be closed even if a port is using it. The
310 return value is unspecified.
313 @deffn {Scheme Procedure} unread-char char [port]
314 @deffnx {C Function} scm_unread_char (char, port)
315 Place @var{char} in @var{port} so that it will be read by the next
316 read operation on that port. If called multiple times, the unread
317 characters will be read again in ``last-in, first-out'' order (i.e.@:
318 a stack). If @var{port} is not supplied, the current input port is
322 @deffn {Scheme Procedure} unread-string str port
323 Place the string @var{str} in @var{port} so that its characters will be
324 read in subsequent read operations. If called multiple times, the
325 unread characters will be read again in last-in first-out order. If
326 @var{port} is not supplied, the current-input-port is used.
329 @deffn {Scheme Procedure} pipe
330 @deffnx {C Function} scm_pipe ()
331 Return a newly created pipe: a pair of ports which are linked
332 together on the local machine. The @acronym{CAR} is the input
333 port and the @acronym{CDR} is the output port. Data written (and
334 flushed) to the output port can be read from the input port.
335 Pipes are commonly used for communication with a newly forked
336 child process. The need to flush the output port can be
337 avoided by making it unbuffered using @code{setvbuf}.
340 A write of up to @code{PIPE_BUF} many bytes to a pipe is atomic,
341 meaning when done it goes into the pipe instantaneously and as a
342 contiguous block (@pxref{Pipe Atomicity,, Atomicity of Pipe I/O, libc,
343 The GNU C Library Reference Manual}).
346 Note that the output port is likely to block if too much data has been
347 written but not yet read from the input port. Typically the capacity
348 is @code{PIPE_BUF} bytes.
351 The next group of procedures perform a @code{dup2}
352 system call, if @var{newfd} (an
353 integer) is supplied, otherwise a @code{dup}. The file descriptor to be
354 duplicated can be supplied as an integer or contained in a port. The
355 type of value returned varies depending on which procedure is used.
357 All procedures also have the side effect when performing @code{dup2} that any
358 ports using @var{newfd} are moved to a different file descriptor and have
359 their revealed counts set to zero.
361 @deffn {Scheme Procedure} dup->fdes fd_or_port [fd]
362 @deffnx {C Function} scm_dup_to_fdes (fd_or_port, fd)
363 Return a new integer file descriptor referring to the open file
364 designated by @var{fd_or_port}, which must be either an open
365 file port or a file descriptor.
368 @deffn {Scheme Procedure} dup->inport port/fd [newfd]
369 Returns a new input port using the new file descriptor.
372 @deffn {Scheme Procedure} dup->outport port/fd [newfd]
373 Returns a new output port using the new file descriptor.
376 @deffn {Scheme Procedure} dup port/fd [newfd]
377 Returns a new port if @var{port/fd} is a port, with the same mode as the
378 supplied port, otherwise returns an integer file descriptor.
381 @deffn {Scheme Procedure} dup->port port/fd mode [newfd]
382 Returns a new port using the new file descriptor. @var{mode} supplies a
383 mode string for the port (@pxref{File Ports, open-file}).
386 @deffn {Scheme Procedure} duplicate-port port modes
387 Returns a new port which is opened on a duplicate of the file
388 descriptor underlying @var{port}, with mode string @var{modes}
389 as for @ref{File Ports, open-file}. The two ports
390 will share a file position and file status flags.
392 Unexpected behaviour can result if both ports are subsequently used
393 and the original and/or duplicate ports are buffered.
394 The mode string can include @code{0} to obtain an unbuffered duplicate
397 This procedure is equivalent to @code{(dup->port @var{port} @var{modes})}.
400 @deffn {Scheme Procedure} redirect-port old new
401 @deffnx {C Function} scm_redirect_port (old, new)
402 This procedure takes two ports and duplicates the underlying file
403 descriptor from @var{old-port} into @var{new-port}. The
404 current file descriptor in @var{new-port} will be closed.
405 After the redirection the two ports will share a file position
406 and file status flags.
408 The return value is unspecified.
410 Unexpected behaviour can result if both ports are subsequently used
411 and the original and/or duplicate ports are buffered.
413 This procedure does not have any side effects on other ports or
417 @deffn {Scheme Procedure} dup2 oldfd newfd
418 @deffnx {C Function} scm_dup2 (oldfd, newfd)
419 A simple wrapper for the @code{dup2} system call.
420 Copies the file descriptor @var{oldfd} to descriptor
421 number @var{newfd}, replacing the previous meaning
422 of @var{newfd}. Both @var{oldfd} and @var{newfd} must
424 Unlike for @code{dup->fdes} or @code{primitive-move->fdes}, no attempt
425 is made to move away ports which are using @var{newfd}.
426 The return value is unspecified.
429 @deffn {Scheme Procedure} port-mode port
430 Return the port modes associated with the open port @var{port}.
431 These will not necessarily be identical to the modes used when
432 the port was opened, since modes such as ``append'' which are
433 used only during port creation are not retained.
436 @deffn {Scheme Procedure} port-for-each proc
437 @deffnx {C Function} scm_port_for_each (SCM proc)
438 @deffnx {C Function} scm_c_port_for_each (void (*proc)(void *, SCM), void *data)
439 Apply @var{proc} to each port in the Guile port table
440 (FIXME: what is the Guile port table?)
441 in turn. The return value is unspecified. More specifically,
442 @var{proc} is applied exactly once to every port that exists in the
443 system at the time @code{port-for-each} is invoked. Changes to the
444 port table while @code{port-for-each} is running have no effect as far
445 as @code{port-for-each} is concerned.
447 The C function @code{scm_port_for_each} takes a Scheme procedure
448 encoded as a @code{SCM} value, while @code{scm_c_port_for_each} takes
449 a pointer to a C function and passes along a arbitrary @var{data}
453 @deffn {Scheme Procedure} setvbuf port mode [size]
454 @deffnx {C Function} scm_setvbuf (port, mode, size)
455 Set the buffering mode for @var{port}. @var{mode} can be:
464 block buffered, using a newly allocated buffer of @var{size} bytes.
465 If @var{size} is omitted, a default size will be used.
469 @deffn {Scheme Procedure} fcntl object cmd [value]
470 @deffnx {C Function} scm_fcntl (object, cmd, value)
471 Apply @var{command} to the specified file descriptor or the underlying
472 file descriptor of the specified port. @var{value} is an optional
475 Values for @var{command} are:
478 Duplicate a file descriptor
481 Get flags associated with the file descriptor.
484 Set flags associated with the file descriptor to @var{value}.
487 Get flags associated with the open file.
490 Set flags associated with the open file to @var{value}
493 Get the process ID of a socket's owner, for @code{SIGIO} signals.
496 Set the process that owns a socket to @var{value}, for @code{SIGIO} signals.
499 The value used to indicate the ``close on exec'' flag with @code{F_GETFL} or
504 @deffn {Scheme Procedure} flock file operation
505 @deffnx {C Function} scm_flock (file, operation)
506 Apply or remove an advisory lock on an open file.
507 @var{operation} specifies the action to be done:
510 Shared lock. More than one process may hold a shared lock
511 for a given file at a given time.
514 Exclusive lock. Only one process may hold an exclusive lock
515 for a given file at a given time.
521 Don't block when locking. May be specified by bitwise OR'ing
522 it to one of the other operations.
525 The return value is not specified. @var{file} may be an open
526 file descriptor or an open file descriptor port.
529 @deffn {Scheme Procedure} select reads writes excepts [secs [usecs]]
530 @deffnx {C Function} scm_select (reads, writes, excepts, secs, usecs)
531 This procedure has a variety of uses: waiting for the ability
532 to provide input, accept output, or the existence of
533 exceptional conditions on a collection of ports or file
534 descriptors, or waiting for a timeout to occur.
535 It also returns if interrupted by a signal.
537 @var{reads}, @var{writes} and @var{excepts} can be lists or
538 vectors, with each member a port or a file descriptor.
539 The value returned is a list of three corresponding
540 lists or vectors containing only the members which meet the
541 specified requirement. The ability of port buffers to
542 provide input or accept output is taken into account.
543 Ordering of the input lists or vectors is not preserved.
545 The optional arguments @var{secs} and @var{usecs} specify the
546 timeout. Either @var{secs} can be specified alone, as
547 either an integer or a real number, or both @var{secs} and
548 @var{usecs} can be specified as integers, in which case
549 @var{usecs} is an additional timeout expressed in
550 microseconds. If @var{secs} is omitted or is @code{#f} then
551 select will wait for as long as it takes for one of the other
552 conditions to be satisfied.
554 The scsh version of @code{select} differs as follows:
555 Only vectors are accepted for the first three arguments.
556 The @var{usecs} argument is not supported.
557 Multiple values are returned instead of a list.
558 Duplicates in the input vectors appear only once in output.
559 An additional @code{select!} interface is provided.
563 @subsection File System
565 These procedures allow querying and setting file system attributes
567 permissions, sizes and types of files); deleting, copying, renaming and
568 linking files; creating and removing directories and querying their
569 contents; syncing the file system and creating special files.
571 @deffn {Scheme Procedure} access? path how
572 @deffnx {C Function} scm_access (path, how)
573 Test accessibility of a file under the real UID and GID of the calling
574 process. The return is @code{#t} if @var{path} exists and the
575 permissions requested by @var{how} are all allowed, or @code{#f} if
578 @var{how} is an integer which is one of the following values, or a
579 bitwise-OR (@code{logior}) of multiple values.
582 Test for read permission.
585 Test for write permission.
588 Test for execute permission.
591 Test for existence of the file. This is implied by each of the other
592 tests, so there's no need to combine it with them.
595 It's important to note that @code{access?} does not simply indicate
596 what will happen on attempting to read or write a file. In normal
597 circumstances it does, but in a set-UID or set-GID program it doesn't
598 because @code{access?} tests the real ID, whereas an open or execute
599 attempt uses the effective ID.
601 A program which will never run set-UID/GID can ignore the difference
602 between real and effective IDs, but for maximum generality, especially
603 in library functions, it's best not to use @code{access?} to predict
604 the result of an open or execute, instead simply attempt that and
607 The main use for @code{access?} is to let a set-UID/GID program
608 determine what the invoking user would have been allowed to do,
609 without the greater (or perhaps lesser) privileges afforded by the
610 effective ID. For more on this, see @ref{Testing File Access,,, libc,
611 The GNU C Library Reference Manual}.
615 @deffn {Scheme Procedure} stat object
616 @deffnx {C Function} scm_stat (object)
617 Return an object containing various information about the file
618 determined by @var{obj}. @var{obj} can be a string containing
619 a file name or a port or integer file descriptor which is open
620 on a file (in which case @code{fstat} is used as the underlying
623 The object returned by @code{stat} can be passed as a single
624 parameter to the following procedures, all of which return
627 @deffn {Scheme Procedure} stat:dev st
628 The device number containing the file.
630 @deffn {Scheme Procedure} stat:ino st
631 The file serial number, which distinguishes this file from all
632 other files on the same device.
634 @deffn {Scheme Procedure} stat:mode st
635 The mode of the file. This is an integer which incorporates file type
636 information and file permission bits. See also @code{stat:type} and
637 @code{stat:perms} below.
639 @deffn {Scheme Procedure} stat:nlink st
640 The number of hard links to the file.
642 @deffn {Scheme Procedure} stat:uid st
643 The user ID of the file's owner.
645 @deffn {Scheme Procedure} stat:gid st
646 The group ID of the file.
648 @deffn {Scheme Procedure} stat:rdev st
649 Device ID; this entry is defined only for character or block special
650 files. On some systems this field is not available at all, in which
651 case @code{stat:rdev} returns @code{#f}.
653 @deffn {Scheme Procedure} stat:size st
654 The size of a regular file in bytes.
656 @deffn {Scheme Procedure} stat:atime st
657 The last access time for the file.
659 @deffn {Scheme Procedure} stat:mtime st
660 The last modification time for the file.
662 @deffn {Scheme Procedure} stat:ctime st
663 The last modification time for the attributes of the file.
665 @deffn {Scheme Procedure} stat:blksize st
666 The optimal block size for reading or writing the file, in bytes. On
667 some systems this field is not available, in which case
668 @code{stat:blksize} returns a sensible suggested block size.
670 @deffn {Scheme Procedure} stat:blocks st
671 The amount of disk space that the file occupies measured in units of
672 512 byte blocks. On some systems this field is not available, in
673 which case @code{stat:blocks} returns @code{#f}.
676 In addition, the following procedures return the information
677 from @code{stat:mode} in a more convenient form:
679 @deffn {Scheme Procedure} stat:type st
680 A symbol representing the type of file. Possible values are
681 @samp{regular}, @samp{directory}, @samp{symlink},
682 @samp{block-special}, @samp{char-special}, @samp{fifo}, @samp{socket},
685 @deffn {Scheme Procedure} stat:perms st
686 An integer representing the access permission bits.
690 @deffn {Scheme Procedure} lstat str
691 @deffnx {C Function} scm_lstat (str)
692 Similar to @code{stat}, but does not follow symbolic links, i.e.,
693 it will return information about a symbolic link itself, not the
694 file it points to. @var{path} must be a string.
697 @deffn {Scheme Procedure} readlink path
698 @deffnx {C Function} scm_readlink (path)
699 Return the value of the symbolic link named by @var{path} (a
700 string), i.e., the file that the link points to.
705 @deffn {Scheme Procedure} chown object owner group
706 @deffnx {C Function} scm_chown (object, owner, group)
707 Change the ownership and group of the file referred to by @var{object}
708 to the integer values @var{owner} and @var{group}. @var{object} can
709 be a string containing a file name or, if the platform supports
710 @code{fchown} (@pxref{File Owner,,,libc,The GNU C Library Reference
711 Manual}), a port or integer file descriptor which is open on the file.
712 The return value is unspecified.
714 If @var{object} is a symbolic link, either the
715 ownership of the link or the ownership of the referenced file will be
716 changed depending on the operating system (lchown is
717 unsupported at present). If @var{owner} or @var{group} is specified
718 as @code{-1}, then that ID is not changed.
722 @deffn {Scheme Procedure} chmod object mode
723 @deffnx {C Function} scm_chmod (object, mode)
724 Changes the permissions of the file referred to by @var{obj}.
725 @var{obj} can be a string containing a file name or a port or integer file
726 descriptor which is open on a file (in which case @code{fchmod} is used
727 as the underlying system call).
729 the new permissions as a decimal number, e.g., @code{(chmod "foo" #o755)}.
730 The return value is unspecified.
733 @deffn {Scheme Procedure} utime pathname [actime [modtime]]
734 @deffnx {C Function} scm_utime (pathname, actime, modtime)
735 @code{utime} sets the access and modification times for the
736 file named by @var{path}. If @var{actime} or @var{modtime} is
737 not supplied, then the current time is used. @var{actime} and
738 @var{modtime} must be integer time values as returned by the
739 @code{current-time} procedure.
741 (utime "foo" (- (current-time) 3600))
743 will set the access time to one hour in the past and the
744 modification time to the current time.
748 @deffn {Scheme Procedure} delete-file str
749 @deffnx {C Function} scm_delete_file (str)
750 Deletes (or ``unlinks'') the file whose path is specified by
754 @deffn {Scheme Procedure} copy-file oldfile newfile
755 @deffnx {C Function} scm_copy_file (oldfile, newfile)
756 Copy the file specified by @var{oldfile} to @var{newfile}.
757 The return value is unspecified.
761 @deffn {Scheme Procedure} rename-file oldname newname
762 @deffnx {C Function} scm_rename (oldname, newname)
763 Renames the file specified by @var{oldname} to @var{newname}.
764 The return value is unspecified.
767 @deffn {Scheme Procedure} link oldpath newpath
768 @deffnx {C Function} scm_link (oldpath, newpath)
769 Creates a new name @var{newpath} in the file system for the
770 file named by @var{oldpath}. If @var{oldpath} is a symbolic
771 link, the link may or may not be followed depending on the
775 @deffn {Scheme Procedure} symlink oldpath newpath
776 @deffnx {C Function} scm_symlink (oldpath, newpath)
777 Create a symbolic link named @var{newpath} with the value (i.e., pointing to)
778 @var{oldpath}. The return value is unspecified.
781 @deffn {Scheme Procedure} mkdir path [mode]
782 @deffnx {C Function} scm_mkdir (path, mode)
783 Create a new directory named by @var{path}. If @var{mode} is omitted
784 then the permissions of the directory file are set using the current
785 umask (@pxref{Processes}). Otherwise they are set to the decimal
786 value specified with @var{mode}. The return value is unspecified.
789 @deffn {Scheme Procedure} rmdir path
790 @deffnx {C Function} scm_rmdir (path)
791 Remove the existing directory named by @var{path}. The directory must
792 be empty for this to succeed. The return value is unspecified.
795 @deffn {Scheme Procedure} opendir dirname
796 @deffnx {C Function} scm_opendir (dirname)
797 Open the directory specified by @var{dirname} and return a directory
801 @deffn {Scheme Procedure} directory-stream? object
802 @deffnx {C Function} scm_directory_stream_p (object)
803 Return a boolean indicating whether @var{object} is a directory
804 stream as returned by @code{opendir}.
807 @deffn {Scheme Procedure} readdir stream
808 @deffnx {C Function} scm_readdir (stream)
809 Return (as a string) the next directory entry from the directory stream
810 @var{stream}. If there is no remaining entry to be read then the
811 end of file object is returned.
814 @deffn {Scheme Procedure} rewinddir stream
815 @deffnx {C Function} scm_rewinddir (stream)
816 Reset the directory port @var{stream} so that the next call to
817 @code{readdir} will return the first directory entry.
820 @deffn {Scheme Procedure} closedir stream
821 @deffnx {C Function} scm_closedir (stream)
822 Close the directory stream @var{stream}.
823 The return value is unspecified.
826 Here is an example showing how to display all the entries in a
830 (define dir (opendir "/usr/lib"))
831 (do ((entry (readdir dir) (readdir dir)))
832 ((eof-object? entry))
833 (display entry)(newline))
837 @deffn {Scheme Procedure} sync
838 @deffnx {C Function} scm_sync ()
839 Flush the operating system disk buffers.
840 The return value is unspecified.
843 @deffn {Scheme Procedure} mknod path type perms dev
844 @deffnx {C Function} scm_mknod (path, type, perms, dev)
845 Creates a new special file, such as a file corresponding to a device.
846 @var{path} specifies the name of the file. @var{type} should be one
847 of the following symbols: @samp{regular}, @samp{directory},
848 @samp{symlink}, @samp{block-special}, @samp{char-special},
849 @samp{fifo}, or @samp{socket}. @var{perms} (an integer) specifies the
850 file permissions. @var{dev} (an integer) specifies which device the
851 special file refers to. Its exact interpretation depends on the kind
852 of special file being created.
856 (mknod "/dev/fd0" 'block-special #o660 (+ (* 2 256) 2))
859 The return value is unspecified.
862 @deffn {Scheme Procedure} tmpnam
863 @deffnx {C Function} scm_tmpnam ()
864 Return a name in the file system that does not match any
865 existing file. However there is no guarantee that another
866 process will not create the file after @code{tmpnam} is called.
867 Care should be taken if opening the file, e.g., use the
868 @code{O_EXCL} open flag or use @code{mkstemp!} instead.
871 @deffn {Scheme Procedure} mkstemp! tmpl
872 @deffnx {C Function} scm_mkstemp (tmpl)
873 Create a new unique file in the file system and returns a new
874 buffered port open for reading and writing to the file.
875 @var{tmpl} is a string specifying where the file should be
876 created: it must end with @samp{XXXXXX} and will be changed in
877 place to return the name of the temporary file.
880 @deffn {Scheme Procedure} dirname filename
881 @deffnx {C Function} scm_dirname (filename)
882 Return the directory name component of the file name
883 @var{filename}. If @var{filename} does not contain a directory
884 component, @code{.} is returned.
887 @deffn {Scheme Procedure} basename filename [suffix]
888 @deffnx {C Function} scm_basename (filename, suffix)
889 Return the base name of the file name @var{filename}. The
890 base name is the file name without any directory components.
891 If @var{suffix} is provided, and is equal to the end of
892 @var{basename}, it is removed also.
895 (basename "/tmp/test.xml" ".xml")
901 @node User Information
902 @subsection User Information
904 The facilities in this section provide an interface to the user and
906 They should be used with care since they are not reentrant.
908 The following functions accept an object representing user information
909 and return a selected component:
911 @deffn {Scheme Procedure} passwd:name pw
912 The name of the userid.
914 @deffn {Scheme Procedure} passwd:passwd pw
915 The encrypted passwd.
917 @deffn {Scheme Procedure} passwd:uid pw
920 @deffn {Scheme Procedure} passwd:gid pw
923 @deffn {Scheme Procedure} passwd:gecos pw
926 @deffn {Scheme Procedure} passwd:dir pw
929 @deffn {Scheme Procedure} passwd:shell pw
934 @deffn {Scheme Procedure} getpwuid uid
935 Look up an integer userid in the user database.
938 @deffn {Scheme Procedure} getpwnam name
939 Look up a user name string in the user database.
942 @deffn {Scheme Procedure} setpwent
943 Initializes a stream used by @code{getpwent} to read from the user database.
944 The next use of @code{getpwent} will return the first entry. The
945 return value is unspecified.
948 @deffn {Scheme Procedure} getpwent
949 Return the next entry in the user database, using the stream set by
953 @deffn {Scheme Procedure} endpwent
954 Closes the stream used by @code{getpwent}. The return value is unspecified.
957 @deffn {Scheme Procedure} setpw [arg]
958 @deffnx {C Function} scm_setpwent (arg)
959 If called with a true argument, initialize or reset the password data
960 stream. Otherwise, close the stream. The @code{setpwent} and
961 @code{endpwent} procedures are implemented on top of this.
964 @deffn {Scheme Procedure} getpw [user]
965 @deffnx {C Function} scm_getpwuid (user)
966 Look up an entry in the user database. @var{obj} can be an integer,
967 a string, or omitted, giving the behaviour of getpwuid, getpwnam
968 or getpwent respectively.
971 The following functions accept an object representing group information
972 and return a selected component:
974 @deffn {Scheme Procedure} group:name gr
977 @deffn {Scheme Procedure} group:passwd gr
978 The encrypted group password.
980 @deffn {Scheme Procedure} group:gid gr
983 @deffn {Scheme Procedure} group:mem gr
984 A list of userids which have this group as a supplementary group.
988 @deffn {Scheme Procedure} getgrgid gid
989 Look up an integer group id in the group database.
992 @deffn {Scheme Procedure} getgrnam name
993 Look up a group name in the group database.
996 @deffn {Scheme Procedure} setgrent
997 Initializes a stream used by @code{getgrent} to read from the group database.
998 The next use of @code{getgrent} will return the first entry.
999 The return value is unspecified.
1002 @deffn {Scheme Procedure} getgrent
1003 Return the next entry in the group database, using the stream set by
1007 @deffn {Scheme Procedure} endgrent
1008 Closes the stream used by @code{getgrent}.
1009 The return value is unspecified.
1012 @deffn {Scheme Procedure} setgr [arg]
1013 @deffnx {C Function} scm_setgrent (arg)
1014 If called with a true argument, initialize or reset the group data
1015 stream. Otherwise, close the stream. The @code{setgrent} and
1016 @code{endgrent} procedures are implemented on top of this.
1019 @deffn {Scheme Procedure} getgr [name]
1020 @deffnx {C Function} scm_getgrgid (name)
1021 Look up an entry in the group database. @var{obj} can be an integer,
1022 a string, or omitted, giving the behaviour of getgrgid, getgrnam
1023 or getgrent respectively.
1026 In addition to the accessor procedures for the user database, the
1027 following shortcut procedures are also available.
1029 @deffn {Scheme Procedure} cuserid
1030 @deffnx {C Function} scm_cuserid ()
1031 Return a string containing a user name associated with the
1032 effective user id of the process. Return @code{#f} if this
1033 information cannot be obtained.
1036 @deffn {Scheme Procedure} getlogin
1037 @deffnx {C Function} scm_getlogin ()
1038 Return a string containing the name of the user logged in on
1039 the controlling terminal of the process, or @code{#f} if this
1040 information cannot be obtained.
1047 @deffn {Scheme Procedure} current-time
1048 @deffnx {C Function} scm_current_time ()
1049 Return the number of seconds since 1970-01-01 00:00:00 @acronym{UTC},
1050 excluding leap seconds.
1053 @deffn {Scheme Procedure} gettimeofday
1054 @deffnx {C Function} scm_gettimeofday ()
1055 Return a pair containing the number of seconds and microseconds
1056 since 1970-01-01 00:00:00 @acronym{UTC}, excluding leap seconds. Note:
1057 whether true microsecond resolution is available depends on the
1061 The following procedures either accept an object representing a broken down
1062 time and return a selected component, or accept an object representing
1063 a broken down time and a value and set the component to the value.
1064 The numbers in parentheses give the usual range.
1066 @deffn {Scheme Procedure} tm:sec tm
1067 @deffnx {Scheme Procedure} set-tm:sec tm val
1070 @deffn {Scheme Procedure} tm:min tm
1071 @deffnx {Scheme Procedure} set-tm:min tm val
1074 @deffn {Scheme Procedure} tm:hour tm
1075 @deffnx {Scheme Procedure} set-tm:hour tm val
1078 @deffn {Scheme Procedure} tm:mday tm
1079 @deffnx {Scheme Procedure} set-tm:mday tm val
1080 Day of the month (1-31).
1082 @deffn {Scheme Procedure} tm:mon tm
1083 @deffnx {Scheme Procedure} set-tm:mon tm val
1086 @deffn {Scheme Procedure} tm:year tm
1087 @deffnx {Scheme Procedure} set-tm:year tm val
1088 Year (70-), the year minus 1900.
1090 @deffn {Scheme Procedure} tm:wday tm
1091 @deffnx {Scheme Procedure} set-tm:wday tm val
1092 Day of the week (0-6) with Sunday represented as 0.
1094 @deffn {Scheme Procedure} tm:yday tm
1095 @deffnx {Scheme Procedure} set-tm:yday tm val
1096 Day of the year (0-364, 365 in leap years).
1098 @deffn {Scheme Procedure} tm:isdst tm
1099 @deffnx {Scheme Procedure} set-tm:isdst tm val
1100 Daylight saving indicator (0 for ``no'', greater than 0 for ``yes'', less than
1103 @deffn {Scheme Procedure} tm:gmtoff tm
1104 @deffnx {Scheme Procedure} set-tm:gmtoff tm val
1105 Time zone offset in seconds west of @acronym{UTC} (-46800 to 43200).
1107 @deffn {Scheme Procedure} tm:zone tm
1108 @deffnx {Scheme Procedure} set-tm:zone tm val
1109 Time zone label (a string), not necessarily unique.
1113 @deffn {Scheme Procedure} localtime time [zone]
1114 @deffnx {C Function} scm_localtime (time, zone)
1115 Return an object representing the broken down components of
1116 @var{time}, an integer like the one returned by
1117 @code{current-time}. The time zone for the calculation is
1118 optionally specified by @var{zone} (a string), otherwise the
1119 @env{TZ} environment variable or the system default is used.
1122 @deffn {Scheme Procedure} gmtime time
1123 @deffnx {C Function} scm_gmtime (time)
1124 Return an object representing the broken down components of
1125 @var{time}, an integer like the one returned by
1126 @code{current-time}. The values are calculated for @acronym{UTC}.
1129 @deffn {Scheme Procedure} mktime sbd-time [zone]
1130 @deffnx {C Function} scm_mktime (sbd_time, zone)
1131 @var{sbd-time} is an object representing broken down time and
1132 @code{zone} is an optional time zone specifier (otherwise the @env{TZ}
1133 environment variable or the system default is used).
1135 Returns a pair: the @acronym{CAR} is a corresponding integer time
1136 value like that returned by @code{current-time}; the @acronym{CDR} is
1137 a broken down time object, similar to @var{sbd-time} but with
1138 normalized values; i.e.@: with corrected @code{tm:wday} and
1139 @code{tm:yday} fields.
1142 @deffn {Scheme Procedure} tzset
1143 @deffnx {C Function} scm_tzset ()
1144 Initialize the timezone from the @env{TZ} environment variable
1145 or the system default. It's not usually necessary to call this procedure
1146 since it's done automatically by other procedures that depend on the
1150 @deffn {Scheme Procedure} strftime format stime
1151 @deffnx {C Function} scm_strftime (format, stime)
1152 Formats a time specification @var{time} using @var{template}. @var{time}
1153 is an object with time components in the form returned by @code{localtime}
1154 or @code{gmtime}. @var{template} is a string which can include formatting
1155 specifications introduced by a @samp{%} character. The formatting of
1156 month and day names is dependent on the current locale. The value returned
1157 is the formatted string.
1158 @xref{Formatting Calendar Time, , , libc, The GNU C Library Reference Manual}.
1161 (strftime "%c" (localtime (current-time)))
1162 @result{} "Mon Mar 11 20:17:43 2002"
1166 @deffn {Scheme Procedure} strptime format string
1167 @deffnx {C Function} scm_strptime (format, string)
1168 Performs the reverse action to @code{strftime}, parsing
1169 @var{string} according to the specification supplied in
1170 @var{template}. The interpretation of month and day names is
1171 dependent on the current locale. The value returned is a pair.
1172 The @acronym{CAR} has an object with time components
1173 in the form returned by @code{localtime} or @code{gmtime},
1174 but the time zone components
1175 are not usefully set.
1176 The @acronym{CDR} reports the number of characters from @var{string}
1177 which were used for the conversion.
1180 @defvar internal-time-units-per-second
1181 The value of this variable is the number of time units per second
1182 reported by the following procedures.
1185 @deffn {Scheme Procedure} times
1186 @deffnx {C Function} scm_times ()
1187 Return an object with information about real and processor
1188 time. The following procedures accept such an object as an
1189 argument and return a selected component:
1191 @deffn {Scheme Procedure} tms:clock tms
1192 The current real time, expressed as time units relative to an
1195 @deffn {Scheme Procedure} tms:utime tms
1196 The CPU time units used by the calling process.
1198 @deffn {Scheme Procedure} tms:stime tms
1199 The CPU time units used by the system on behalf of the calling
1202 @deffn {Scheme Procedure} tms:cutime tms
1203 The CPU time units used by terminated child processes of the
1204 calling process, whose status has been collected (e.g., using
1207 @deffn {Scheme Procedure} tms:cstime tms
1208 Similarly, the CPU times units used by the system on behalf of
1209 terminated child processes.
1213 @deffn {Scheme Procedure} get-internal-real-time
1214 @deffnx {C Function} scm_get_internal_real_time ()
1215 Return the number of time units since the interpreter was
1219 @deffn {Scheme Procedure} get-internal-run-time
1220 @deffnx {C Function} scm_get_internal_run_time ()
1221 Return the number of time units of processor time used by the
1222 interpreter. Both @emph{system} and @emph{user} time are
1223 included but subprocesses are not.
1226 @node Runtime Environment
1227 @subsection Runtime Environment
1229 @deffn {Scheme Procedure} program-arguments
1230 @deffnx {Scheme Procedure} command-line
1231 @deffnx {C Function} scm_program_arguments ()
1232 Return the list of command line arguments passed to Guile, as a list of
1233 strings. The list includes the invoked program name, which is usually
1234 @code{"guile"}, but excludes switches and parameters for command line
1235 options like @code{-e} and @code{-l}.
1238 @deffn {Scheme Procedure} getenv nam
1239 @deffnx {C Function} scm_getenv (nam)
1240 Looks up the string @var{name} in the current environment. The return
1241 value is @code{#f} unless a string of the form @code{NAME=VALUE} is
1242 found, in which case the string @code{VALUE} is returned.
1245 @deffn {Scheme Procedure} setenv name value
1246 Modifies the environment of the current process, which is
1247 also the default environment inherited by child processes.
1249 If @var{value} is @code{#f}, then @var{name} is removed from the
1250 environment. Otherwise, the string @var{name}=@var{value} is added
1251 to the environment, replacing any existing string with name matching
1254 The return value is unspecified.
1257 @deffn {Scheme Procedure} unsetenv name
1258 Remove variable @var{name} from the environment. The
1259 name can not contain a @samp{=} character.
1262 @deffn {Scheme Procedure} environ [env]
1263 @deffnx {C Function} scm_environ (env)
1264 If @var{env} is omitted, return the current environment (in the
1265 Unix sense) as a list of strings. Otherwise set the current
1266 environment, which is also the default environment for child
1267 processes, to the supplied list of strings. Each member of
1268 @var{env} should be of the form @var{NAME}=@var{VALUE} and values of
1269 @var{NAME} should not be duplicated. If @var{env} is supplied
1270 then the return value is unspecified.
1273 @deffn {Scheme Procedure} putenv str
1274 @deffnx {C Function} scm_putenv (str)
1275 Modifies the environment of the current process, which is
1276 also the default environment inherited by child processes.
1278 If @var{string} is of the form @code{NAME=VALUE} then it will be written
1279 directly into the environment, replacing any existing environment string
1281 name matching @code{NAME}. If @var{string} does not contain an equal
1282 sign, then any existing string with name matching @var{string} will
1285 The return value is unspecified.
1290 @subsection Processes
1293 @deffn {Scheme Procedure} chdir str
1294 @deffnx {C Function} scm_chdir (str)
1295 Change the current working directory to @var{path}.
1296 The return value is unspecified.
1300 @deffn {Scheme Procedure} getcwd
1301 @deffnx {C Function} scm_getcwd ()
1302 Return the name of the current working directory.
1305 @deffn {Scheme Procedure} umask [mode]
1306 @deffnx {C Function} scm_umask (mode)
1307 If @var{mode} is omitted, returns a decimal number representing the
1308 current file creation mask. Otherwise the file creation mask is set
1309 to @var{mode} and the previous value is returned. @xref{Setting
1310 Permissions,,Assigning File Permissions,libc,The GNU C Library
1311 Reference Manual}, for more on how to use umasks.
1313 E.g., @code{(umask #o022)} sets the mask to octal 22/decimal 18.
1316 @deffn {Scheme Procedure} chroot path
1317 @deffnx {C Function} scm_chroot (path)
1318 Change the root directory to that specified in @var{path}.
1319 This directory will be used for path names beginning with
1320 @file{/}. The root directory is inherited by all children
1321 of the current process. Only the superuser may change the
1325 @deffn {Scheme Procedure} getpid
1326 @deffnx {C Function} scm_getpid ()
1327 Return an integer representing the current process ID.
1330 @deffn {Scheme Procedure} getgroups
1331 @deffnx {C Function} scm_getgroups ()
1332 Return a vector of integers representing the current
1333 supplementary group IDs.
1336 @deffn {Scheme Procedure} getppid
1337 @deffnx {C Function} scm_getppid ()
1338 Return an integer representing the process ID of the parent
1342 @deffn {Scheme Procedure} getuid
1343 @deffnx {C Function} scm_getuid ()
1344 Return an integer representing the current real user ID.
1347 @deffn {Scheme Procedure} getgid
1348 @deffnx {C Function} scm_getgid ()
1349 Return an integer representing the current real group ID.
1352 @deffn {Scheme Procedure} geteuid
1353 @deffnx {C Function} scm_geteuid ()
1354 Return an integer representing the current effective user ID.
1355 If the system does not support effective IDs, then the real ID
1356 is returned. @code{(provided? 'EIDs)} reports whether the
1357 system supports effective IDs.
1360 @deffn {Scheme Procedure} getegid
1361 @deffnx {C Function} scm_getegid ()
1362 Return an integer representing the current effective group ID.
1363 If the system does not support effective IDs, then the real ID
1364 is returned. @code{(provided? 'EIDs)} reports whether the
1365 system supports effective IDs.
1368 @deffn {Scheme Procedure} setgroups vec
1369 @deffnx {C Function} scm_setgroups (vec)
1370 Set the current set of supplementary group IDs to the integers in the
1371 given vector @var{vec}. The return value is unspecified.
1373 Generally only the superuser can set the process group IDs
1374 (@pxref{Setting Groups, Setting the Group IDs,, libc, The GNU C
1375 Library Reference Manual}).
1378 @deffn {Scheme Procedure} setuid id
1379 @deffnx {C Function} scm_setuid (id)
1380 Sets both the real and effective user IDs to the integer @var{id}, provided
1381 the process has appropriate privileges.
1382 The return value is unspecified.
1385 @deffn {Scheme Procedure} setgid id
1386 @deffnx {C Function} scm_setgid (id)
1387 Sets both the real and effective group IDs to the integer @var{id}, provided
1388 the process has appropriate privileges.
1389 The return value is unspecified.
1392 @deffn {Scheme Procedure} seteuid id
1393 @deffnx {C Function} scm_seteuid (id)
1394 Sets the effective user ID to the integer @var{id}, provided the process
1395 has appropriate privileges. If effective IDs are not supported, the
1396 real ID is set instead---@code{(provided? 'EIDs)} reports whether the
1397 system supports effective IDs.
1398 The return value is unspecified.
1401 @deffn {Scheme Procedure} setegid id
1402 @deffnx {C Function} scm_setegid (id)
1403 Sets the effective group ID to the integer @var{id}, provided the process
1404 has appropriate privileges. If effective IDs are not supported, the
1405 real ID is set instead---@code{(provided? 'EIDs)} reports whether the
1406 system supports effective IDs.
1407 The return value is unspecified.
1410 @deffn {Scheme Procedure} getpgrp
1411 @deffnx {C Function} scm_getpgrp ()
1412 Return an integer representing the current process group ID.
1413 This is the @acronym{POSIX} definition, not @acronym{BSD}.
1416 @deffn {Scheme Procedure} setpgid pid pgid
1417 @deffnx {C Function} scm_setpgid (pid, pgid)
1418 Move the process @var{pid} into the process group @var{pgid}. @var{pid} or
1419 @var{pgid} must be integers: they can be zero to indicate the ID of the
1421 Fails on systems that do not support job control.
1422 The return value is unspecified.
1425 @deffn {Scheme Procedure} setsid
1426 @deffnx {C Function} scm_setsid ()
1427 Creates a new session. The current process becomes the session leader
1428 and is put in a new process group. The process will be detached
1429 from its controlling terminal if it has one.
1430 The return value is an integer representing the new process group ID.
1433 @deffn {Scheme Procedure} waitpid pid [options]
1434 @deffnx {C Function} scm_waitpid (pid, options)
1435 This procedure collects status information from a child process which
1436 has terminated or (optionally) stopped. Normally it will
1437 suspend the calling process until this can be done. If more than one
1438 child process is eligible then one will be chosen by the operating system.
1440 The value of @var{pid} determines the behaviour:
1443 @item @var{pid} greater than 0
1444 Request status information from the specified child process.
1445 @item @var{pid} equal to -1 or @code{WAIT_ANY}
1447 Request status information for any child process.
1448 @item @var{pid} equal to 0 or @code{WAIT_MYPGRP}
1450 Request status information for any child process in the current process
1452 @item @var{pid} less than -1
1453 Request status information for any child process whose process group ID
1454 is @minus{}@var{pid}.
1457 The @var{options} argument, if supplied, should be the bitwise OR of the
1458 values of zero or more of the following variables:
1461 Return immediately even if there are no child processes to be collected.
1465 Report status information for stopped processes as well as terminated
1469 The return value is a pair containing:
1473 The process ID of the child process, or 0 if @code{WNOHANG} was
1474 specified and no process was collected.
1476 The integer status value.
1481 functions can be used to decode the process status code returned
1484 @deffn {Scheme Procedure} status:exit-val status
1485 @deffnx {C Function} scm_status_exit_val (status)
1486 Return the exit status value, as would be set if a process
1487 ended normally through a call to @code{exit} or @code{_exit},
1488 if any, otherwise @code{#f}.
1491 @deffn {Scheme Procedure} status:term-sig status
1492 @deffnx {C Function} scm_status_term_sig (status)
1493 Return the signal number which terminated the process, if any,
1494 otherwise @code{#f}.
1497 @deffn {Scheme Procedure} status:stop-sig status
1498 @deffnx {C Function} scm_status_stop_sig (status)
1499 Return the signal number which stopped the process, if any,
1500 otherwise @code{#f}.
1503 @deffn {Scheme Procedure} system [cmd]
1504 @deffnx {C Function} scm_system (cmd)
1505 Execute @var{cmd} using the operating system's ``command
1506 processor''. Under Unix this is usually the default shell
1507 @code{sh}. The value returned is @var{cmd}'s exit status as
1508 returned by @code{waitpid}, which can be interpreted using the
1511 If @code{system} is called without arguments, return a boolean
1512 indicating whether the command processor is available.
1515 @deffn {Scheme Procedure} system* . args
1516 @deffnx {C Function} scm_system_star (args)
1517 Execute the command indicated by @var{args}. The first element must
1518 be a string indicating the command to be executed, and the remaining
1519 items must be strings representing each of the arguments to that
1522 This function returns the exit status of the command as provided by
1523 @code{waitpid}. This value can be handled with @code{status:exit-val}
1524 and the related functions.
1526 @code{system*} is similar to @code{system}, but accepts only one
1527 string per-argument, and performs no shell interpretation. The
1528 command is executed using fork and execlp. Accordingly this function
1529 may be safer than @code{system} in situations where shell
1530 interpretation is not required.
1532 Example: (system* "echo" "foo" "bar")
1535 @deffn {Scheme Procedure} primitive-exit [status]
1536 @deffnx {C Function} scm_primitive_exit (status)
1537 Terminate the current process without unwinding the Scheme stack.
1538 This is would typically be useful after a fork. The exit status
1539 is @var{status} if supplied, otherwise zero.
1542 @deffn {Scheme Procedure} execl filename . args
1543 @deffnx {C Function} scm_execl (filename, args)
1544 Executes the file named by @var{path} as a new process image.
1545 The remaining arguments are supplied to the process; from a C program
1546 they are accessible as the @code{argv} argument to @code{main}.
1547 Conventionally the first @var{arg} is the same as @var{path}.
1548 All arguments must be strings.
1550 If @var{arg} is missing, @var{path} is executed with a null
1551 argument list, which may have system-dependent side-effects.
1553 This procedure is currently implemented using the @code{execv} system
1554 call, but we call it @code{execl} because of its Scheme calling interface.
1557 @deffn {Scheme Procedure} execlp filename . args
1558 @deffnx {C Function} scm_execlp (filename, args)
1559 Similar to @code{execl}, however if
1560 @var{filename} does not contain a slash
1561 then the file to execute will be located by searching the
1562 directories listed in the @code{PATH} environment variable.
1564 This procedure is currently implemented using the @code{execvp} system
1565 call, but we call it @code{execlp} because of its Scheme calling interface.
1568 @deffn {Scheme Procedure} execle filename env . args
1569 @deffnx {C Function} scm_execle (filename, env, args)
1570 Similar to @code{execl}, but the environment of the new process is
1571 specified by @var{env}, which must be a list of strings as returned by the
1572 @code{environ} procedure.
1574 This procedure is currently implemented using the @code{execve} system
1575 call, but we call it @code{execle} because of its Scheme calling interface.
1578 @deffn {Scheme Procedure} primitive-fork
1579 @deffnx {C Function} scm_fork ()
1580 Creates a new ``child'' process by duplicating the current ``parent'' process.
1581 In the child the return value is 0. In the parent the return value is
1582 the integer process ID of the child.
1584 This procedure has been renamed from @code{fork} to avoid a naming conflict
1588 @deffn {Scheme Procedure} nice incr
1589 @deffnx {C Function} scm_nice (incr)
1590 Increment the priority of the current process by @var{incr}. A higher
1591 priority value means that the process runs less often.
1592 The return value is unspecified.
1595 @deffn {Scheme Procedure} setpriority which who prio
1596 @deffnx {C Function} scm_setpriority (which, who, prio)
1597 @vindex PRIO_PROCESS
1600 Set the scheduling priority of the process, process group
1601 or user, as indicated by @var{which} and @var{who}. @var{which}
1602 is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
1603 or @code{PRIO_USER}, and @var{who} is interpreted relative to
1604 @var{which} (a process identifier for @code{PRIO_PROCESS},
1605 process group identifier for @code{PRIO_PGRP}, and a user
1606 identifier for @code{PRIO_USER}. A zero value of @var{who}
1607 denotes the current process, process group, or user.
1608 @var{prio} is a value in the range [@minus{}20,20]. The default
1609 priority is 0; lower priorities (in numerical terms) cause more
1610 favorable scheduling. Sets the priority of all of the specified
1611 processes. Only the super-user may lower priorities. The return
1612 value is not specified.
1615 @deffn {Scheme Procedure} getpriority which who
1616 @deffnx {C Function} scm_getpriority (which, who)
1617 @vindex PRIO_PROCESS
1620 Return the scheduling priority of the process, process group
1621 or user, as indicated by @var{which} and @var{who}. @var{which}
1622 is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
1623 or @code{PRIO_USER}, and @var{who} should be interpreted depending on
1624 @var{which} (a process identifier for @code{PRIO_PROCESS},
1625 process group identifier for @code{PRIO_PGRP}, and a user
1626 identifier for @code{PRIO_USER}). A zero value of @var{who}
1627 denotes the current process, process group, or user. Return
1628 the highest priority (lowest numerical value) of any of the
1629 specified processes.
1636 Procedures to raise, handle and wait for signals.
1638 @deffn {Scheme Procedure} kill pid sig
1639 @deffnx {C Function} scm_kill (pid, sig)
1640 Sends a signal to the specified process or group of processes.
1642 @var{pid} specifies the processes to which the signal is sent:
1645 @item @var{pid} greater than 0
1646 The process whose identifier is @var{pid}.
1647 @item @var{pid} equal to 0
1648 All processes in the current process group.
1649 @item @var{pid} less than -1
1650 The process group whose identifier is -@var{pid}
1651 @item @var{pid} equal to -1
1652 If the process is privileged, all processes except for some special
1653 system processes. Otherwise, all processes with the current effective
1657 @var{sig} should be specified using a variable corresponding to
1658 the Unix symbolic name, e.g.,
1668 A full list of signals on the GNU system may be found in @ref{Standard
1669 Signals,,,libc,The GNU C Library Reference Manual}.
1672 @deffn {Scheme Procedure} raise sig
1673 @deffnx {C Function} scm_raise (sig)
1674 Sends a specified signal @var{sig} to the current process, where
1675 @var{sig} is as described for the @code{kill} procedure.
1678 @deffn {Scheme Procedure} sigaction signum [handler [flags [thread]]]
1679 @deffnx {C Function} scm_sigaction (signum, handler, flags)
1680 @deffnx {C Function} scm_sigaction_for_thread (signum, handler, flags, thread)
1681 Install or report the signal handler for a specified signal.
1683 @var{signum} is the signal number, which can be specified using the value
1684 of variables such as @code{SIGINT}.
1686 If @var{handler} is omitted, @code{sigaction} returns a pair: the
1687 @acronym{CAR} is the current signal hander, which will be either an
1688 integer with the value @code{SIG_DFL} (default action) or
1689 @code{SIG_IGN} (ignore), or the Scheme procedure which handles the
1690 signal, or @code{#f} if a non-Scheme procedure handles the signal.
1691 The @acronym{CDR} contains the current @code{sigaction} flags for the
1694 If @var{handler} is provided, it is installed as the new handler for
1695 @var{signum}. @var{handler} can be a Scheme procedure taking one
1696 argument, or the value of @code{SIG_DFL} (default action) or
1697 @code{SIG_IGN} (ignore), or @code{#f} to restore whatever signal handler
1698 was installed before @code{sigaction} was first used. When a scheme
1699 procedure has been specified, that procedure will run in the given
1700 @var{thread}. When no thread has been given, the thread that made this
1701 call to @code{sigaction} is used.
1703 Flags can optionally be specified for the new handler (@code{SA_RESTART}
1704 will always be added if it's available and the system is using
1705 restartable system calls.) The return value is a pair with information
1706 about the old handler as described above.
1708 This interface does not provide access to the ``signal blocking''
1709 facility. Maybe this is not needed, since the thread support may
1710 provide solutions to the problem of consistent access to data
1714 @deffn {Scheme Procedure} restore-signals
1715 @deffnx {C Function} scm_restore_signals ()
1716 Return all signal handlers to the values they had before any call to
1717 @code{sigaction} was made. The return value is unspecified.
1720 @deffn {Scheme Procedure} alarm i
1721 @deffnx {C Function} scm_alarm (i)
1722 Set a timer to raise a @code{SIGALRM} signal after the specified
1723 number of seconds (an integer). It's advisable to install a signal
1725 @code{SIGALRM} beforehand, since the default action is to terminate
1728 The return value indicates the time remaining for the previous alarm,
1729 if any. The new value replaces the previous alarm. If there was
1730 no previous alarm, the return value is zero.
1733 @deffn {Scheme Procedure} pause
1734 @deffnx {C Function} scm_pause ()
1735 Pause the current process (thread?) until a signal arrives whose
1736 action is to either terminate the current process or invoke a
1737 handler procedure. The return value is unspecified.
1740 @deffn {Scheme Procedure} sleep i
1741 @deffnx {C Function} scm_sleep (i)
1742 Wait for the given number of seconds (an integer) or until a signal
1743 arrives. The return value is zero if the time elapses or the number
1744 of seconds remaining otherwise.
1747 @deffn {Scheme Procedure} usleep i
1748 @deffnx {C Function} scm_usleep (i)
1749 Sleep for @var{i} microseconds. @code{usleep} is not available on
1750 all platforms. [FIXME: so what happens when it isn't?]
1753 @deffn {Scheme Procedure} setitimer which_timer interval_seconds interval_microseconds value_seconds value_microseconds
1754 @deffnx {C Function} scm_setitimer (which_timer, interval_seconds, interval_microseconds, value_seconds, value_microseconds)
1755 Set the timer specified by @var{which_timer} according to the given
1756 @var{interval_seconds}, @var{interval_microseconds},
1757 @var{value_seconds}, and @var{value_microseconds} values.
1759 Return information about the timer's previous setting.
1761 The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
1762 and @code{ITIMER_PROF}.
1764 The return value will be a list of two cons pairs representing the
1765 current state of the given timer. The first pair is the seconds and
1766 microseconds of the timer @code{it_interval}, and the second pair is
1767 the seconds and microseconds of the timer @code{it_value}.
1770 @deffn {Scheme Procedure} getitimer which_timer
1771 @deffnx {C Function} scm_getitimer (which_timer)
1772 Return information about the timer specified by @var{which_timer}.
1774 The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
1775 and @code{ITIMER_PROF}.
1777 The return value will be a list of two cons pairs representing the
1778 current state of the given timer. The first pair is the seconds and
1779 microseconds of the timer @code{it_interval}, and the second pair is
1780 the seconds and microseconds of the timer @code{it_value}.
1784 @node Terminals and Ptys
1785 @subsection Terminals and Ptys
1787 @deffn {Scheme Procedure} isatty? port
1788 @deffnx {C Function} scm_isatty_p (port)
1789 Return @code{#t} if @var{port} is using a serial non--file
1790 device, otherwise @code{#f}.
1793 @deffn {Scheme Procedure} ttyname port
1794 @deffnx {C Function} scm_ttyname (port)
1795 Return a string with the name of the serial terminal device
1796 underlying @var{port}.
1799 @deffn {Scheme Procedure} ctermid
1800 @deffnx {C Function} scm_ctermid ()
1801 Return a string containing the file name of the controlling
1802 terminal for the current process.
1805 @deffn {Scheme Procedure} tcgetpgrp port
1806 @deffnx {C Function} scm_tcgetpgrp (port)
1807 Return the process group ID of the foreground process group
1808 associated with the terminal open on the file descriptor
1809 underlying @var{port}.
1811 If there is no foreground process group, the return value is a
1812 number greater than 1 that does not match the process group ID
1813 of any existing process group. This can happen if all of the
1814 processes in the job that was formerly the foreground job have
1815 terminated, and no other job has yet been moved into the
1819 @deffn {Scheme Procedure} tcsetpgrp port pgid
1820 @deffnx {C Function} scm_tcsetpgrp (port, pgid)
1821 Set the foreground process group ID for the terminal used by the file
1822 descriptor underlying @var{port} to the integer @var{pgid}.
1824 must be a member of the same session as @var{pgid} and must have the same
1825 controlling terminal. The return value is unspecified.
1831 The following procedures provide an interface to the @code{popen} and
1832 @code{pclose} system routines. The code is in a separate ``popen''
1836 (use-modules (ice-9 popen))
1840 @deffn {Scheme Procedure} open-pipe command modes
1841 Executes the shell command @var{command} (a string) in a subprocess.
1842 A pipe to the process is created and returned. @var{modes} specifies
1843 whether an input or output pipe to the process is created: it should
1844 be the value of @code{OPEN_READ} or @code{OPEN_WRITE}.
1847 @deffn {Scheme Procedure} open-input-pipe command
1848 Equivalent to @code{open-pipe} with mode @code{OPEN_READ}.
1851 (read-line (open-input-pipe "date"))
1852 @result{} "Mon Mar 11 20:10:44 GMT 2002"
1855 @result{} (24160 . 0)
1859 @deffn {Scheme Procedure} open-output-pipe command
1860 Equivalent to @code{open-pipe} with mode @code{OPEN_WRITE}.
1864 @deffn {Scheme Procedure} close-pipe port
1865 Closes the pipe created by @code{open-pipe}, then waits for the process
1866 to terminate and returns its status value, @xref{Processes, waitpid}, for
1867 information on how to interpret this value.
1869 @code{close-port} (@pxref{Closing, close-port}) can also be used to
1870 close a pipe, but doesn't return the status.
1874 @subsection Networking
1877 * Network Address Conversion::
1878 * Network Databases::
1879 * Network Sockets and Communication::
1880 * Internet Socket Examples::
1883 @node Network Address Conversion
1884 @subsubsection Network Address Conversion
1886 This section describes procedures which convert internet addresses
1887 between numeric and string formats.
1889 @subsubheading IPv4 Address Conversion
1891 An IPv4 Internet address is a 4-byte value, represented in Guile as an
1892 integer in network byte order (meaning the first byte is the most
1893 significant in the number).
1895 @defvar INADDR_LOOPBACK
1896 The address of the local host using the loopback device, ie.@:
1900 @defvar INADDR_BROADCAST
1901 The broadcast address on the local network.
1904 @c INADDR_NONE is defined in the code, but serves no purpose.
1905 @c inet_addr() returns it as an error indication, but that function
1906 @c isn't provided, for the good reason that inet_aton() does the same
1907 @c job and gives an unambiguous error indication. (INADDR_NONE is a
1908 @c valid 4-byte value, in glibc it's the same as INADDR_BROADCAST.)
1910 @c @defvar INADDR_NONE
1914 @deffn {Scheme Procedure} inet-aton address
1915 @deffnx {C Function} scm_inet_aton (address)
1916 Convert an IPv4 Internet address from printable string
1917 (dotted decimal notation) to an integer. E.g.,
1920 (inet-aton "127.0.0.1") @result{} 2130706433
1924 @deffn {Scheme Procedure} inet-ntoa inetid
1925 @deffnx {C Function} scm_inet_ntoa (inetid)
1926 Convert an IPv4 Internet address to a printable
1927 (dotted decimal notation) string. E.g.,
1930 (inet-ntoa 2130706433) @result{} "127.0.0.1"
1934 @deffn {Scheme Procedure} inet-netof address
1935 @deffnx {C Function} scm_inet_netof (address)
1936 Return the network number part of the given IPv4
1937 Internet address. E.g.,
1940 (inet-netof 2130706433) @result{} 127
1944 @deffn {Scheme Procedure} inet-lnaof address
1945 @deffnx {C Function} scm_lnaof (address)
1946 Return the local-address-with-network part of the given
1947 IPv4 Internet address, using the obsolete class A/B/C system.
1951 (inet-lnaof 2130706433) @result{} 1
1955 @deffn {Scheme Procedure} inet-makeaddr net lna
1956 @deffnx {C Function} scm_inet_makeaddr (net, lna)
1957 Make an IPv4 Internet address by combining the network number
1958 @var{net} with the local-address-within-network number
1962 (inet-makeaddr 127 1) @result{} 2130706433
1966 @subsubheading IPv6 Address Conversion
1968 @deffn {Scheme Procedure} inet-ntop family address
1969 @deffnx {C Function} scm_inet_ntop (family, address)
1970 Convert a network address into a printable string.
1971 Note that unlike the C version of this function,
1972 the input is an integer with normal host byte ordering.
1973 @var{family} can be @code{AF_INET} or @code{AF_INET6}. E.g.,
1976 (inet-ntop AF_INET 2130706433) @result{} "127.0.0.1"
1977 (inet-ntop AF_INET6 (- (expt 2 128) 1)) @result{}
1978 ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
1982 @deffn {Scheme Procedure} inet-pton family address
1983 @deffnx {C Function} scm_inet_pton (family, address)
1984 Convert a string containing a printable network address to
1985 an integer address. Note that unlike the C version of this
1987 the result is an integer with normal host byte ordering.
1988 @var{family} can be @code{AF_INET} or @code{AF_INET6}. E.g.,
1991 (inet-pton AF_INET "127.0.0.1") @result{} 2130706433
1992 (inet-pton AF_INET6 "::1") @result{} 1
1997 @node Network Databases
1998 @subsubsection Network Databases
2000 This section describes procedures which query various network databases.
2001 Care should be taken when using the database routines since they are not
2004 @subsubheading The Host Database
2006 A @dfn{host object} is a structure that represents what is known about a
2007 network host, and is the usual way of representing a system's network
2008 identity inside software.
2010 The following functions accept a host object and return a selected
2013 @deffn {Scheme Procedure} hostent:name host
2014 The ``official'' hostname for @var{host}.
2016 @deffn {Scheme Procedure} hostent:aliases host
2017 A list of aliases for @var{host}.
2019 @deffn {Scheme Procedure} hostent:addrtype host
2020 The host address type. For hosts with Internet addresses, this will
2021 return @code{AF_INET}.
2023 @deffn {Scheme Procedure} hostent:length host
2024 The length of each address for @var{host}, in bytes.
2026 @deffn {Scheme Procedure} hostent:addr-list host
2027 The list of network addresses associated with @var{host}.
2030 The following procedures are used to search the host database:
2032 @deffn {Scheme Procedure} gethost [host]
2033 @deffnx {Scheme Procedure} gethostbyname hostname
2034 @deffnx {Scheme Procedure} gethostbyaddr address
2035 @deffnx {C Function} scm_gethost (host)
2036 Look up a host by name or address, returning a host object. The
2037 @code{gethost} procedure will accept either a string name or an integer
2038 address; if given no arguments, it behaves like @code{gethostent} (see
2039 below). If a name or address is supplied but the address can not be
2040 found, an error will be thrown to one of the keys:
2041 @code{host-not-found}, @code{try-again}, @code{no-recovery} or
2042 @code{no-data}, corresponding to the equivalent @code{h_error} values.
2043 Unusual conditions may result in errors thrown to the
2044 @code{system-error} or @code{misc_error} keys.
2047 (gethost "www.gnu.org")
2048 @result{} #("www.gnu.org" () 2 4 (3353880842))
2050 (gethostbyname "www.emacs.org")
2051 @result{} #("emacs.org" ("www.emacs.org") 2 4 (1073448978))
2055 The following procedures may be used to step through the host
2056 database from beginning to end.
2058 @deffn {Scheme Procedure} sethostent [stayopen]
2059 Initialize an internal stream from which host objects may be read. This
2060 procedure must be called before any calls to @code{gethostent}, and may
2061 also be called afterward to reset the host entry stream. If
2062 @var{stayopen} is supplied and is not @code{#f}, the database is not
2063 closed by subsequent @code{gethostbyname} or @code{gethostbyaddr} calls,
2064 possibly giving an efficiency gain.
2067 @deffn {Scheme Procedure} gethostent
2068 Return the next host object from the host database, or @code{#f} if
2069 there are no more hosts to be found (or an error has been encountered).
2070 This procedure may not be used before @code{sethostent} has been called.
2073 @deffn {Scheme Procedure} endhostent
2074 Close the stream used by @code{gethostent}. The return value is unspecified.
2077 @deffn {Scheme Procedure} sethost [stayopen]
2078 @deffnx {C Function} scm_sethost (stayopen)
2079 If @var{stayopen} is omitted, this is equivalent to @code{endhostent}.
2080 Otherwise it is equivalent to @code{sethostent stayopen}.
2083 @subsubheading The Network Database
2085 The following functions accept an object representing a network
2086 and return a selected component:
2088 @deffn {Scheme Procedure} netent:name net
2089 The ``official'' network name.
2091 @deffn {Scheme Procedure} netent:aliases net
2092 A list of aliases for the network.
2094 @deffn {Scheme Procedure} netent:addrtype net
2095 The type of the network number. Currently, this returns only
2098 @deffn {Scheme Procedure} netent:net net
2102 The following procedures are used to search the network database:
2104 @deffn {Scheme Procedure} getnet [net]
2105 @deffnx {Scheme Procedure} getnetbyname net-name
2106 @deffnx {Scheme Procedure} getnetbyaddr net-number
2107 @deffnx {C Function} scm_getnet (net)
2108 Look up a network by name or net number in the network database. The
2109 @var{net-name} argument must be a string, and the @var{net-number}
2110 argument must be an integer. @code{getnet} will accept either type of
2111 argument, behaving like @code{getnetent} (see below) if no arguments are
2115 The following procedures may be used to step through the network
2116 database from beginning to end.
2118 @deffn {Scheme Procedure} setnetent [stayopen]
2119 Initialize an internal stream from which network objects may be read. This
2120 procedure must be called before any calls to @code{getnetent}, and may
2121 also be called afterward to reset the net entry stream. If
2122 @var{stayopen} is supplied and is not @code{#f}, the database is not
2123 closed by subsequent @code{getnetbyname} or @code{getnetbyaddr} calls,
2124 possibly giving an efficiency gain.
2127 @deffn {Scheme Procedure} getnetent
2128 Return the next entry from the network database.
2131 @deffn {Scheme Procedure} endnetent
2132 Close the stream used by @code{getnetent}. The return value is unspecified.
2135 @deffn {Scheme Procedure} setnet [stayopen]
2136 @deffnx {C Function} scm_setnet (stayopen)
2137 If @var{stayopen} is omitted, this is equivalent to @code{endnetent}.
2138 Otherwise it is equivalent to @code{setnetent stayopen}.
2141 @subsubheading The Protocol Database
2143 The following functions accept an object representing a protocol
2144 and return a selected component:
2146 @deffn {Scheme Procedure} protoent:name protocol
2147 The ``official'' protocol name.
2149 @deffn {Scheme Procedure} protoent:aliases protocol
2150 A list of aliases for the protocol.
2152 @deffn {Scheme Procedure} protoent:proto protocol
2153 The protocol number.
2156 The following procedures are used to search the protocol database:
2158 @deffn {Scheme Procedure} getproto [protocol]
2159 @deffnx {Scheme Procedure} getprotobyname name
2160 @deffnx {Scheme Procedure} getprotobynumber number
2161 @deffnx {C Function} scm_getproto (protocol)
2162 Look up a network protocol by name or by number. @code{getprotobyname}
2163 takes a string argument, and @code{getprotobynumber} takes an integer
2164 argument. @code{getproto} will accept either type, behaving like
2165 @code{getprotoent} (see below) if no arguments are supplied.
2168 The following procedures may be used to step through the protocol
2169 database from beginning to end.
2171 @deffn {Scheme Procedure} setprotoent [stayopen]
2172 Initialize an internal stream from which protocol objects may be read. This
2173 procedure must be called before any calls to @code{getprotoent}, and may
2174 also be called afterward to reset the protocol entry stream. If
2175 @var{stayopen} is supplied and is not @code{#f}, the database is not
2176 closed by subsequent @code{getprotobyname} or @code{getprotobynumber} calls,
2177 possibly giving an efficiency gain.
2180 @deffn {Scheme Procedure} getprotoent
2181 Return the next entry from the protocol database.
2184 @deffn {Scheme Procedure} endprotoent
2185 Close the stream used by @code{getprotoent}. The return value is unspecified.
2188 @deffn {Scheme Procedure} setproto [stayopen]
2189 @deffnx {C Function} scm_setproto (stayopen)
2190 If @var{stayopen} is omitted, this is equivalent to @code{endprotoent}.
2191 Otherwise it is equivalent to @code{setprotoent stayopen}.
2194 @subsubheading The Service Database
2196 The following functions accept an object representing a service
2197 and return a selected component:
2199 @deffn {Scheme Procedure} servent:name serv
2200 The ``official'' name of the network service.
2202 @deffn {Scheme Procedure} servent:aliases serv
2203 A list of aliases for the network service.
2205 @deffn {Scheme Procedure} servent:port serv
2206 The Internet port used by the service.
2208 @deffn {Scheme Procedure} servent:proto serv
2209 The protocol used by the service. A service may be listed many times
2210 in the database under different protocol names.
2213 The following procedures are used to search the service database:
2215 @deffn {Scheme Procedure} getserv [name [protocol]]
2216 @deffnx {Scheme Procedure} getservbyname name protocol
2217 @deffnx {Scheme Procedure} getservbyport port protocol
2218 @deffnx {C Function} scm_getserv (name, protocol)
2219 Look up a network service by name or by service number, and return a
2220 network service object. The @var{protocol} argument specifies the name
2221 of the desired protocol; if the protocol found in the network service
2222 database does not match this name, a system error is signalled.
2224 The @code{getserv} procedure will take either a service name or number
2225 as its first argument; if given no arguments, it behaves like
2226 @code{getservent} (see below).
2229 (getserv "imap" "tcp")
2230 @result{} #("imap2" ("imap") 143 "tcp")
2232 (getservbyport 88 "udp")
2233 @result{} #("kerberos" ("kerberos5" "krb5") 88 "udp")
2237 The following procedures may be used to step through the service
2238 database from beginning to end.
2240 @deffn {Scheme Procedure} setservent [stayopen]
2241 Initialize an internal stream from which service objects may be read. This
2242 procedure must be called before any calls to @code{getservent}, and may
2243 also be called afterward to reset the service entry stream. If
2244 @var{stayopen} is supplied and is not @code{#f}, the database is not
2245 closed by subsequent @code{getservbyname} or @code{getservbyport} calls,
2246 possibly giving an efficiency gain.
2249 @deffn {Scheme Procedure} getservent
2250 Return the next entry from the services database.
2253 @deffn {Scheme Procedure} endservent
2254 Close the stream used by @code{getservent}. The return value is unspecified.
2257 @deffn {Scheme Procedure} setserv [stayopen]
2258 @deffnx {C Function} scm_setserv (stayopen)
2259 If @var{stayopen} is omitted, this is equivalent to @code{endservent}.
2260 Otherwise it is equivalent to @code{setservent stayopen}.
2263 @node Network Sockets and Communication
2264 @subsubsection Network Sockets and Communication
2266 Socket ports can be created using @code{socket} and @code{socketpair}.
2267 The ports are initially unbuffered, to make reading and writing to the
2268 same port more reliable. A buffer can be added to the port using
2269 @code{setvbuf}; see @ref{Ports and File Descriptors}.
2271 Most systems have limits on how many files and sockets can be open, so
2272 it's strongly recommended that socket ports be closed explicitly when
2273 no longer required (@pxref{Ports}).
2275 The convention used for ``host'' vs.@: ``network'' addresses is that
2276 addresses are always held in host order at the Scheme level. The
2277 procedures in this section automatically convert between host and
2278 network order when required. The arguments and return values are thus
2281 @deffn {Scheme Procedure} socket family style proto
2282 @deffnx {C Function} scm_socket (family, style, proto)
2283 Return a new socket port of the type specified by @var{family},
2284 @var{style} and @var{proto}. All three parameters are integers. The
2285 possible values for @var{family} are as follows, where supported by
2293 The possible values for @var{style} are as follows, again where
2294 supported by the system,
2300 @defvarx SOCK_SEQPACKET
2303 @var{proto} can be obtained from a protocol name using
2304 @code{getprotobyname} (@pxref{Network Databases}). A value of zero
2305 means the default protocol, which is usually right.
2307 A socket cannot by used for communication until it has been connected
2308 somewhere, usually with either @code{connect} or @code{accept} below.
2311 @deffn {Scheme Procedure} socketpair family style proto
2312 @deffnx {C Function} scm_socketpair (family, style, proto)
2313 Return a pair, the @code{car} and @code{cdr} of which are two unnamed
2314 socket ports connected to each other. The connection is full-duplex,
2315 so data can be transferred in either direction between the two.
2317 @var{family}, @var{style} and @var{proto} are as per @code{socket}
2318 above. But many systems only support socket pairs in the
2319 @code{PF_UNIX} family. Zero is likely to be the only meaningful value
2323 @deffn {Scheme Procedure} getsockopt sock level optname
2324 @deffnx {C Function} scm_getsockopt (sock, level, optname)
2325 Return the value of a particular socket option for the socket
2326 port @var{sock}. @var{level} is an integer code for type of
2327 option being requested, e.g., @code{SOL_SOCKET} for
2328 socket-level options. @var{optname} is an integer code for the
2329 option required and should be specified using one of the
2330 symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc.
2332 The returned value is typically an integer but @code{SO_LINGER}
2333 returns a pair of integers.
2336 @deffn {Scheme Procedure} setsockopt sock level optname value
2337 @deffnx {C Function} scm_setsockopt (sock, level, optname, value)
2338 Set the value of a particular socket option for the socket
2339 port @var{sock}. @var{level} is an integer code for type of option
2340 being set, e.g., @code{SOL_SOCKET} for socket-level options.
2342 integer code for the option to set and should be specified using one of
2343 the symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc.
2344 @var{value} is the value to which the option should be set. For
2345 most options this must be an integer, but for @code{SO_LINGER} it must
2348 The return value is unspecified.
2351 @deffn {Scheme Procedure} shutdown sock how
2352 @deffnx {C Function} scm_shutdown (sock, how)
2353 Sockets can be closed simply by using @code{close-port}. The
2354 @code{shutdown} procedure allows reception or transmission on a
2355 connection to be shut down individually, according to the parameter
2360 Stop receiving data for this socket. If further data arrives, reject it.
2362 Stop trying to transmit data from this socket. Discard any
2363 data waiting to be sent. Stop looking for acknowledgement of
2364 data already sent; don't retransmit it if it is lost.
2366 Stop both reception and transmission.
2369 The return value is unspecified.
2372 @deffn {Scheme Procedure} connect sock fam address . args
2373 @deffnx {C Function} scm_connect (sock, fam, address, args)
2374 Initiate a connection from a socket using a specified address
2375 family to the address
2376 specified by @var{address} and possibly @var{args}.
2377 The format required for @var{address}
2378 and @var{args} depends on the family of the socket.
2380 For a socket of family @code{AF_UNIX},
2381 only @var{address} is specified and must be a string with the
2382 filename where the socket is to be created.
2384 For a socket of family @code{AF_INET},
2385 @var{address} must be an integer IPv4 host address and
2386 @var{args} must be a single integer port number.
2388 For a socket of family @code{AF_INET6},
2389 @var{address} must be an integer IPv6 host address and
2390 @var{args} may be up to three integers:
2391 port [flowinfo] [scope_id],
2392 where flowinfo and scope_id default to zero.
2394 The return value is unspecified.
2397 @deffn {Scheme Procedure} bind sock fam address . args
2398 @deffnx {C Function} scm_bind (sock, fam, address, args)
2399 Assign an address to the socket port @var{sock}.
2400 Generally this only needs to be done for server sockets,
2401 so they know where to look for incoming connections. A socket
2402 without an address will be assigned one automatically when it
2403 starts communicating.
2405 The format of @var{address} and @var{args} depends
2406 on the family of the socket.
2408 For a socket of family @code{AF_UNIX}, only @var{address}
2409 is specified and must be a string with the filename where
2410 the socket is to be created.
2412 For a socket of family @code{AF_INET}, @var{address}
2413 must be an integer IPv4 address and @var{args}
2414 must be a single integer port number.
2416 The values of the following variables can also be used for
2420 Allow connections from any address.
2423 @defvar INADDR_LOOPBACK
2424 The address of the local host using the loopback device.
2427 @defvar INADDR_BROADCAST
2428 The broadcast address on the local network.
2435 For a socket of family @code{AF_INET6}, @var{address}
2436 must be an integer IPv6 address and @var{args}
2437 may be up to three integers:
2438 port [flowinfo] [scope_id],
2439 where flowinfo and scope_id default to zero.
2441 The return value is unspecified.
2444 @deffn {Scheme Procedure} listen sock backlog
2445 @deffnx {C Function} scm_listen (sock, backlog)
2446 Enable @var{sock} to accept connection
2447 requests. @var{backlog} is an integer specifying
2448 the maximum length of the queue for pending connections.
2449 If the queue fills, new clients will fail to connect until
2450 the server calls @code{accept} to accept a connection from
2453 The return value is unspecified.
2456 @deffn {Scheme Procedure} accept sock
2457 @deffnx {C Function} scm_accept (sock)
2458 Accept a connection on a bound, listening socket.
2460 are no pending connections in the queue, wait until
2461 one is available unless the non-blocking option has been
2464 The return value is a
2465 pair in which the @acronym{CAR} is a new socket port for the
2467 the @acronym{CDR} is an object with address information about the
2468 client which initiated the connection.
2470 @var{sock} does not become part of the
2471 connection and will continue to accept new requests.
2474 The following functions take a socket address object, as returned
2475 by @code{accept} and other procedures, and return a selected component.
2477 @deffn {Scheme Procedure} sockaddr:fam sa
2478 The socket family, typically equal to the value of @code{AF_UNIX} or
2481 @deffn {Scheme Procedure} sockaddr:path sa
2482 If the socket family is @code{AF_UNIX}, returns the path of the
2483 filename the socket is based on.
2485 @deffn {Scheme Procedure} sockaddr:addr sa
2486 If the socket family is @code{AF_INET}, returns the Internet host
2489 @deffn {Scheme Procedure} sockaddr:port sa
2490 If the socket family is @code{AF_INET}, returns the Internet port
2494 @deffn {Scheme Procedure} getsockname sock
2495 @deffnx {C Function} scm_getsockname (sock)
2496 Return the address of @var{sock}, in the same form as the
2497 object returned by @code{accept}. On many systems the address
2498 of a socket in the @code{AF_FILE} namespace cannot be read.
2501 @deffn {Scheme Procedure} getpeername sock
2502 @deffnx {C Function} scm_getpeername (sock)
2503 Return the address that @var{sock}
2504 is connected to, in the same form as the object returned by
2505 @code{accept}. On many systems the address of a socket in the
2506 @code{AF_FILE} namespace cannot be read.
2509 @deffn {Scheme Procedure} recv! sock buf [flags]
2510 @deffnx {C Function} scm_recv (sock, buf, flags)
2511 Receive data from a socket port.
2512 @var{sock} must already
2513 be bound to the address from which data is to be received.
2514 @var{buf} is a string into which
2515 the data will be written. The size of @var{buf} limits
2517 data which can be received: in the case of packet
2518 protocols, if a packet larger than this limit is encountered
2520 will be irrevocably lost.
2524 @vindex MSG_DONTROUTE
2525 The optional @var{flags} argument is a value or bitwise OR of
2526 @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
2528 The value returned is the number of bytes read from the
2531 Note that the data is read directly from the socket file
2533 any unread buffered port data is ignored.
2536 @deffn {Scheme Procedure} send sock message [flags]
2537 @deffnx {C Function} scm_send (sock, message, flags)
2540 @vindex MSG_DONTROUTE
2541 Transmit the string @var{message} on a socket port @var{sock}.
2542 @var{sock} must already be bound to a destination address. The value
2543 returned is the number of bytes transmitted---it's possible for this
2544 to be less than the length of @var{message} if the socket is set to be
2545 non-blocking. The optional @var{flags} argument is a value or bitwise
2546 OR of @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
2548 Note that the data is written directly to the socket
2550 any unflushed buffered port data is ignored.
2553 @deffn {Scheme Procedure} recvfrom! sock str [flags [start [end]]]
2554 @deffnx {C Function} scm_recvfrom (sock, str, flags, start, end)
2555 Return data from the socket port @var{sock} and also
2556 information about where the data was received from.
2557 @var{sock} must already be bound to the address from which
2558 data is to be received. @code{str}, is a string into which the
2559 data will be written. The size of @var{str} limits the amount
2560 of data which can be received: in the case of packet protocols,
2561 if a packet larger than this limit is encountered then some
2562 data will be irrevocably lost.
2566 @vindex MSG_DONTROUTE
2567 The optional @var{flags} argument is a value or bitwise OR of
2568 @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
2570 The value returned is a pair: the @acronym{CAR} is the number of
2571 bytes read from the socket and the @acronym{CDR} an address object
2572 in the same form as returned by @code{accept}. The address
2573 will given as @code{#f} if not available, as is usually the
2574 case for stream sockets.
2576 The @var{start} and @var{end} arguments specify a substring of
2577 @var{str} to which the data should be written.
2579 Note that the data is read directly from the socket file
2580 descriptor: any unread buffered port data is ignored.
2583 @deffn {Scheme Procedure} sendto sock message fam address . args_and_flags
2584 @deffnx {C Function} scm_sendto (sock, message, fam, address, args_and_flags)
2585 Transmit the string @var{message} on the socket port
2587 destination address is specified using the @var{fam},
2589 @var{args_and_flags} arguments, in a similar way to the
2590 @code{connect} procedure. @var{args_and_flags} contains
2591 the usual connection arguments optionally followed by
2592 a flags argument, which is a value or
2593 bitwise OR of @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
2595 The value returned is the number of bytes transmitted --
2597 this to be less than the length of @var{message} if the
2599 set to be non-blocking.
2600 Note that the data is written directly to the socket
2602 any unflushed buffered port data is ignored.
2605 The following functions can be used to convert short and long integers
2606 between ``host'' and ``network'' order. Although the procedures above do
2607 this automatically for addresses, the conversion will still need to
2608 be done when sending or receiving encoded integer data from the network.
2610 @deffn {Scheme Procedure} htons value
2611 @deffnx {C Function} scm_htons (value)
2612 Convert a 16 bit quantity from host to network byte ordering.
2613 @var{value} is packed into 2 bytes, which are then converted
2614 and returned as a new integer.
2617 @deffn {Scheme Procedure} ntohs value
2618 @deffnx {C Function} scm_ntohs (value)
2619 Convert a 16 bit quantity from network to host byte ordering.
2620 @var{value} is packed into 2 bytes, which are then converted
2621 and returned as a new integer.
2624 @deffn {Scheme Procedure} htonl value
2625 @deffnx {C Function} scm_htonl (value)
2626 Convert a 32 bit quantity from host to network byte ordering.
2627 @var{value} is packed into 4 bytes, which are then converted
2628 and returned as a new integer.
2631 @deffn {Scheme Procedure} ntohl value
2632 @deffnx {C Function} scm_ntohl (value)
2633 Convert a 32 bit quantity from network to host byte ordering.
2634 @var{value} is packed into 4 bytes, which are then converted
2635 and returned as a new integer.
2638 These procedures are inconvenient to use at present, but consider:
2641 (define write-network-long
2642 (lambda (value port)
2643 (let ((v (make-uniform-vector 1 1 0)))
2644 (uniform-vector-set! v 0 (htonl value))
2645 (uniform-vector-write v port))))
2647 (define read-network-long
2649 (let ((v (make-uniform-vector 1 1 0)))
2650 (uniform-vector-read! v port)
2651 (ntohl (uniform-vector-ref v 0)))))
2655 @node Internet Socket Examples
2656 @subsubsection Network Socket Examples
2658 The following give examples of how to use network sockets.
2660 @subsubheading Internet Socket Client Example
2662 @cindex socket client example
2663 The following example demonstrates an Internet socket client.
2664 It connects to the HTTP daemon running on the local machine and
2665 returns the contents of the root index URL.
2668 (let ((s (socket PF_INET SOCK_STREAM 0)))
2669 (connect s AF_INET (inet-aton "127.0.0.1") 80)
2670 (display "GET / HTTP/1.0\r\n\r\n" s)
2672 (do ((line (read-line s) (read-line s)))
2673 ((eof-object? line))
2679 @subsubheading Internet Socket Server Example
2681 @cindex socket server example
2682 The following example shows a simple Internet server which listens on
2683 port 2904 for incoming connections and sends a greeting back to the
2687 (let ((s (socket PF_INET SOCK_STREAM 0)))
2688 (setsockopt s SOL_SOCKET SO_REUSEADDR 1)
2689 ;; @r{Specific address?}
2690 ;; @r{(bind s AF_INET (inet-aton "127.0.0.1") 2904)}
2691 (bind s AF_INET INADDR_ANY 2904)
2694 (simple-format #t "Listening for clients in pid: ~S" (getpid))
2698 (let* ((client-connection (accept s))
2699 (client-details (cdr client-connection))
2700 (client (car client-connection)))
2701 (simple-format #t "Got new client connection: ~S"
2704 (simple-format #t "Client address: ~S"
2706 (sockaddr:addr client-details)))
2708 ;; @r{Send back the greeting to the client port}
2709 (display "Hello client\r\n" client)
2714 @node System Identification
2715 @subsection System Identification
2717 This section lists the various procedures Guile provides for accessing
2718 information about the system it runs on.
2720 @deffn {Scheme Procedure} uname
2721 @deffnx {C Function} scm_uname ()
2722 Return an object with some information about the computer
2723 system the program is running on.
2725 The following procedures accept an object as returned by @code{uname}
2726 and return a selected component.
2728 @deffn {Scheme Procedure} utsname:sysname un
2729 The name of the operating system.
2731 @deffn {Scheme Procedure} utsname:nodename un
2732 The network name of the computer.
2734 @deffn {Scheme Procedure} utsname:release un
2735 The current release level of the operating system implementation.
2737 @deffn {Scheme Procedure} utsname:version un
2738 The current version level within the release of the operating system.
2740 @deffn {Scheme Procedure} utsname:machine un
2741 A description of the hardware.
2745 @deffn {Scheme Procedure} gethostname
2746 @deffnx {C Function} scm_gethostname ()
2747 Return the host name of the current processor.
2750 @deffn {Scheme Procedure} sethostname name
2751 @deffnx {C Function} scm_sethostname (name)
2752 Set the host name of the current processor to @var{name}. May
2753 only be used by the superuser. The return value is not
2757 @c FIXME::martin: Not in libguile!
2758 @deffn {Scheme Procedure} software-type
2759 Return a symbol describing the current platform's operating system.
2760 This may be one of @samp{AIX}, @samp{VMS}, @samp{UNIX},
2761 @samp{COHERENT}, @samp{WINDOWS}, @samp{MS-DOS}, @samp{OS/2},
2762 @samp{THINKC}, @samp{AMIGA}, @samp{ATARIST}, @samp{MACH}, or
2765 Note that most varieties of Unix are considered to be simply @samp{UNIX}.
2766 That is because when a program depends on features that are not present
2767 on every operating system, it is usually better to test for the presence
2768 or absence of that specific feature. The return value of
2769 @code{software-type} should only be used for this purpose when there is
2770 no other easy or unambiguous way of detecting such features.
2776 @deffn {Scheme Procedure} setlocale category [locale]
2777 @deffnx {C Function} scm_setlocale (category, locale)
2778 Get or set the current locale, used for various internationalizations.
2779 Locales are strings, such as @samp{sv_SE}.
2781 If @var{locale} is given then the locale for the given @var{category} is set
2782 and the new value returned. If @var{locale} is not given then the
2783 current value is returned. @var{category} should be one of the
2789 @defvarx LC_MESSAGES
2790 @defvarx LC_MONETARY
2795 A common usage is @samp{(setlocale LC_ALL "")}, which initializes all
2796 categories based on standard environment variables (@code{LANG} etc).
2797 For full details on categories and locale names @pxref{Locales,,
2798 Locales and Internationalization, libc, The GNU C Library Reference
2803 @subsection Encryption
2805 Please note that the procedures in this section are not suited for
2806 strong encryption, they are only interfaces to the well-known and
2807 common system library functions of the same name. They are just as good
2808 (or bad) as the underlying functions, so you should refer to your system
2809 documentation before using them.
2811 @deffn {Scheme Procedure} crypt key salt
2812 @deffnx {C Function} scm_crypt (key, salt)
2813 Encrypt @var{key} using @var{salt} as the salt value to the
2814 crypt(3) library call.
2817 Although @code{getpass} is not an encryption procedure per se, it
2818 appears here because it is often used in combination with @code{crypt}:
2820 @deffn {Scheme Procedure} getpass prompt
2821 @deffnx {C Function} scm_getpass (prompt)
2822 Display @var{prompt} to the standard error output and read
2823 a password from @file{/dev/tty}. If this file is not
2824 accessible, it reads from standard input. The password may be
2825 up to 127 characters in length. Additional characters and the
2826 terminating newline character are discarded. While reading
2827 the password, echoing and the generation of signals by special
2828 characters is disabled.
2833 @c TeX-master: "guile.texi"