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 @chapter @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 @section @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. The value of the Unix @code{errno} variable is available
80 in the data passed by the exception.
82 It can be extracted with the function @code{system-error-errno}:
88 (mkdir "/this-ought-to-fail-if-I'm-not-root"))
90 (let ((errno (system-error-errno stuff)))
93 (display "You're not allowed to do that."))
95 (display "Already exists."))
97 (display (strerror errno))))
101 @node Ports and File Descriptors
102 @section Ports and File Descriptors
104 Conventions generally follow those of scsh, @ref{The Scheme shell (scsh)}.
106 File ports are implemented using low-level operating system I/O
107 facilities, with optional buffering to improve efficiency; see
110 Note that some procedures (e.g., @code{recv!}) will accept ports as
111 arguments, but will actually operate directly on the file descriptor
112 underlying the port. Any port buffering is ignored, including the
113 buffer which implements @code{peek-char} and @code{unread-char}.
115 The @code{force-output} and @code{drain-input} procedures can be used
116 to clear the buffers.
118 Each open file port has an associated operating system file descriptor.
119 File descriptors are generally not useful in Scheme programs; however
120 they may be needed when interfacing with foreign code and the Unix
123 A file descriptor can be extracted from a port and a new port can be
124 created from a file descriptor. However a file descriptor is just an
125 integer and the garbage collector doesn't recognize it as a reference
126 to the port. If all other references to the port were dropped, then
127 it's likely that the garbage collector would free the port, with the
128 side-effect of closing the file descriptor prematurely.
130 To assist the programmer in avoiding this problem, each port has an
131 associated @dfn{revealed count} which can be used to keep track of how many
132 times the underlying file descriptor has been stored in other places.
133 If a port's revealed count is greater than zero, the file descriptor
134 will not be closed when the port is garbage collected. A programmer
135 can therefore ensure that the revealed count will be greater than
136 zero if the file descriptor is needed elsewhere.
138 For the simple case where a file descriptor is ``imported'' once to become
139 a port, it does not matter if the file descriptor is closed when the
140 port is garbage collected. There is no need to maintain a revealed
141 count. Likewise when ``exporting'' a file descriptor to the external
142 environment, setting the revealed count is not required provided the
143 port is kept open (i.e., is pointed to by a live Scheme binding) while
144 the file descriptor is in use.
146 To correspond with traditional Unix behaviour, three file descriptors
147 (0, 1, and 2) are automatically imported when a program starts up and
148 assigned to the initial values of the current/standard input, output,
149 and error ports, respectively. The revealed count for each is
150 initially set to one, so that dropping references to one of these
151 ports will not result in its garbage collection: it could be retrieved
152 with @code{fdopen} or @code{fdes->ports}.
154 @deffn {Scheme Procedure} port-revealed port
155 @deffnx {C Function} scm_port_revealed (port)
156 Return the revealed count for @var{port}.
159 @deffn {Scheme Procedure} set-port-revealed! port rcount
160 @deffnx {C Function} scm_set_port_revealed_x (port, rcount)
161 Sets the revealed count for a @var{port} to @var{rcount}.
162 The return value is unspecified.
165 @deffn {Scheme Procedure} fileno port
166 @deffnx {C Function} scm_fileno (port)
167 Return the integer file descriptor underlying @var{port}. Does
168 not change its revealed count.
171 @deffn {Scheme Procedure} port->fdes port
172 Returns the integer file descriptor underlying @var{port}. As a
173 side effect the revealed count of @var{port} is incremented.
176 @deffn {Scheme Procedure} fdopen fdes modes
177 @deffnx {C Function} scm_fdopen (fdes, modes)
178 Return a new port based on the file descriptor @var{fdes}. Modes are
179 given by the string @var{modes}. The revealed count of the port is
180 initialized to zero. The @var{modes} string is the same as that
181 accepted by @code{open-file} (@pxref{File Ports, open-file}).
184 @deffn {Scheme Procedure} fdes->ports fd
185 @deffnx {C Function} scm_fdes_to_ports (fd)
186 Return a list of existing ports which have @var{fdes} as an
187 underlying file descriptor, without changing their revealed
191 @deffn {Scheme Procedure} fdes->inport fdes
192 Returns an existing input port which has @var{fdes} as its underlying file
193 descriptor, if one exists, and increments its revealed count.
194 Otherwise, returns a new input port with a revealed count of 1.
197 @deffn {Scheme Procedure} fdes->outport fdes
198 Returns an existing output port which has @var{fdes} as its underlying file
199 descriptor, if one exists, and increments its revealed count.
200 Otherwise, returns a new output port with a revealed count of 1.
203 @deffn {Scheme Procedure} primitive-move->fdes port fd
204 @deffnx {C Function} scm_primitive_move_to_fdes (port, fd)
205 Moves the underlying file descriptor for @var{port} to the integer
206 value @var{fdes} without changing the revealed count of @var{port}.
207 Any other ports already using this descriptor will be automatically
208 shifted to new descriptors and their revealed counts reset to zero.
209 The return value is @code{#f} if the file descriptor already had the
210 required value or @code{#t} if it was moved.
213 @deffn {Scheme Procedure} move->fdes port fdes
214 Moves the underlying file descriptor for @var{port} to the integer
215 value @var{fdes} and sets its revealed count to one. Any other ports
216 already using this descriptor will be automatically
217 shifted to new descriptors and their revealed counts reset to zero.
218 The return value is unspecified.
221 @deffn {Scheme Procedure} release-port-handle port
222 Decrements the revealed count for a port.
225 @deffn {Scheme Procedure} fsync object
226 @deffnx {C Function} scm_fsync (object)
227 Copies any unwritten data for the specified output file descriptor to disk.
228 If @var{port/fd} is a port, its buffer is flushed before the underlying
229 file descriptor is fsync'd.
230 The return value is unspecified.
233 @deffn {Scheme Procedure} open path flags [mode]
234 @deffnx {C Function} scm_open (path, flags, mode)
235 Open the file named by @var{path} for reading and/or writing.
236 @var{flags} is an integer specifying how the file should be opened.
237 @var{mode} is an integer specifying the permission bits of the file,
238 if it needs to be created, before the umask (@pxref{Processes}) is
239 applied. The default is 666 (Unix itself has no default).
241 @var{flags} can be constructed by combining variables using @code{logior}.
245 Open the file read-only.
248 Open the file write-only.
251 Open the file read/write.
254 Append to the file instead of truncating.
257 Create the file if it does not already exist.
260 @xref{File Status Flags,,,libc,The GNU C Library Reference Manual},
261 for additional flags.
264 @deffn {Scheme Procedure} open-fdes path flags [mode]
265 @deffnx {C Function} scm_open_fdes (path, flags, mode)
266 Similar to @code{open} but return a file descriptor instead of
270 @deffn {Scheme Procedure} close fd_or_port
271 @deffnx {C Function} scm_close (fd_or_port)
272 Similar to @code{close-port} (@pxref{Closing, close-port}),
273 but also works on file descriptors. A side
274 effect of closing a file descriptor is that any ports using that file
275 descriptor are moved to a different file descriptor and have
276 their revealed counts set to zero.
279 @deffn {Scheme Procedure} close-fdes fd
280 @deffnx {C Function} scm_close_fdes (fd)
281 A simple wrapper for the @code{close} system call. Close file
282 descriptor @var{fd}, which must be an integer. Unlike @code{close},
283 the file descriptor will be closed even if a port is using it. The
284 return value is unspecified.
287 @deffn {Scheme Procedure} unread-char char [port]
288 @deffnx {C Function} scm_unread_char (char, port)
289 Place @var{char} in @var{port} so that it will be read by the next
290 read operation on that port. If called multiple times, the unread
291 characters will be read again in ``last-in, first-out'' order (i.e.@:
292 a stack). If @var{port} is not supplied, the current input port is
296 @deffn {Scheme Procedure} unread-string str port
297 Place the string @var{str} in @var{port} so that its characters will be
298 read in subsequent read operations. If called multiple times, the
299 unread characters will be read again in last-in first-out order. If
300 @var{port} is not supplied, the current-input-port is used.
303 @deffn {Scheme Procedure} pipe
304 @deffnx {C Function} scm_pipe ()
305 Return a newly created pipe: a pair of ports which are linked
306 together on the local machine. The @acronym{CAR} is the input
307 port and the @acronym{CDR} is the output port. Data written (and
308 flushed) to the output port can be read from the input port.
309 Pipes are commonly used for communication with a newly forked
310 child process. The need to flush the output port can be
311 avoided by making it unbuffered using @code{setvbuf}.
314 A write of up to @code{PIPE_BUF} many bytes to a pipe is atomic,
315 meaning when done it goes into the pipe instantaneously and as a
316 contiguous block (@pxref{Pipe Atomicity,, Atomicity of Pipe I/O, libc,
317 The GNU C Library Reference Manual}).
320 Note that the output port is likely to block if too much data has been
321 written but not yet read from the input port. Typically the capacity
322 is @code{PIPE_BUF} bytes.
325 The next group of procedures perform a @code{dup2}
326 system call, if @var{newfd} (an
327 integer) is supplied, otherwise a @code{dup}. The file descriptor to be
328 duplicated can be supplied as an integer or contained in a port. The
329 type of value returned varies depending on which procedure is used.
331 All procedures also have the side effect when performing @code{dup2} that any
332 ports using @var{newfd} are moved to a different file descriptor and have
333 their revealed counts set to zero.
335 @deffn {Scheme Procedure} dup->fdes fd_or_port [fd]
336 @deffnx {C Function} scm_dup_to_fdes (fd_or_port, fd)
337 Return a new integer file descriptor referring to the open file
338 designated by @var{fd_or_port}, which must be either an open
339 file port or a file descriptor.
342 @deffn {Scheme Procedure} dup->inport port/fd [newfd]
343 Returns a new input port using the new file descriptor.
346 @deffn {Scheme Procedure} dup->outport port/fd [newfd]
347 Returns a new output port using the new file descriptor.
350 @deffn {Scheme Procedure} dup port/fd [newfd]
351 Returns a new port if @var{port/fd} is a port, with the same mode as the
352 supplied port, otherwise returns an integer file descriptor.
355 @deffn {Scheme Procedure} dup->port port/fd mode [newfd]
356 Returns a new port using the new file descriptor. @var{mode} supplies a
357 mode string for the port (@pxref{File Ports, open-file}).
360 @deffn {Scheme Procedure} duplicate-port port modes
361 Returns a new port which is opened on a duplicate of the file
362 descriptor underlying @var{port}, with mode string @var{modes}
363 as for @ref{File Ports, open-file}. The two ports
364 will share a file position and file status flags.
366 Unexpected behaviour can result if both ports are subsequently used
367 and the original and/or duplicate ports are buffered.
368 The mode string can include @code{0} to obtain an unbuffered duplicate
371 This procedure is equivalent to @code{(dup->port @var{port} @var{modes})}.
374 @deffn {Scheme Procedure} redirect-port old new
375 @deffnx {C Function} scm_redirect_port (old, new)
376 This procedure takes two ports and duplicates the underlying file
377 descriptor from @var{old-port} into @var{new-port}. The
378 current file descriptor in @var{new-port} will be closed.
379 After the redirection the two ports will share a file position
380 and file status flags.
382 The return value is unspecified.
384 Unexpected behaviour can result if both ports are subsequently used
385 and the original and/or duplicate ports are buffered.
387 This procedure does not have any side effects on other ports or
391 @deffn {Scheme Procedure} dup2 oldfd newfd
392 @deffnx {C Function} scm_dup2 (oldfd, newfd)
393 A simple wrapper for the @code{dup2} system call.
394 Copies the file descriptor @var{oldfd} to descriptor
395 number @var{newfd}, replacing the previous meaning
396 of @var{newfd}. Both @var{oldfd} and @var{newfd} must
398 Unlike for @code{dup->fdes} or @code{primitive-move->fdes}, no attempt
399 is made to move away ports which are using @var{newfd}.
400 The return value is unspecified.
403 @deffn {Scheme Procedure} port-mode port
404 Return the port modes associated with the open port @var{port}.
405 These will not necessarily be identical to the modes used when
406 the port was opened, since modes such as ``append'' which are
407 used only during port creation are not retained.
410 @deffn {Scheme Procedure} port-for-each proc
411 @deffnx {C Function} scm_port_for_each (SCM proc)
412 @deffnx {C Function} scm_c_port_for_each (void (*proc)(void *, SCM), void *data)
413 Apply @var{proc} to each port in the Guile port table
414 (FIXME: what is the Guile port table?)
415 in turn. The return value is unspecified. More specifically,
416 @var{proc} is applied exactly once to every port that exists in the
417 system at the time @code{port-for-each} is invoked. Changes to the
418 port table while @code{port-for-each} is running have no effect as far
419 as @code{port-for-each} is concerned.
421 The C function @code{scm_port_for_each} takes a Scheme procedure
422 encoded as a @code{SCM} value, while @code{scm_c_port_for_each} takes
423 a pointer to a C function and passes along a arbitrary @var{data}
427 @deffn {Scheme Procedure} setvbuf port mode [size]
428 @deffnx {C Function} scm_setvbuf (port, mode, size)
429 Set the buffering mode for @var{port}. @var{mode} can be:
438 block buffered, using a newly allocated buffer of @var{size} bytes.
439 If @var{size} is omitted, a default size will be used.
443 @deffn {Scheme Procedure} fcntl object cmd [value]
444 @deffnx {C Function} scm_fcntl (object, cmd, value)
445 Apply @var{command} to the specified file descriptor or the underlying
446 file descriptor of the specified port. @var{value} is an optional
449 Values for @var{command} are:
452 Duplicate a file descriptor
455 Get flags associated with the file descriptor.
458 Set flags associated with the file descriptor to @var{value}.
461 Get flags associated with the open file.
464 Set flags associated with the open file to @var{value}
467 Get the process ID of a socket's owner, for @code{SIGIO} signals.
470 Set the process that owns a socket to @var{value}, for @code{SIGIO} signals.
473 The value used to indicate the ``close on exec'' flag with @code{F_GETFL} or
478 @deffn {Scheme Procedure} flock file operation
479 @deffnx {C Function} scm_flock (file, operation)
480 Apply or remove an advisory lock on an open file.
481 @var{operation} specifies the action to be done:
484 Shared lock. More than one process may hold a shared lock
485 for a given file at a given time.
488 Exclusive lock. Only one process may hold an exclusive lock
489 for a given file at a given time.
495 Don't block when locking. May be specified by bitwise OR'ing
496 it to one of the other operations.
499 The return value is not specified. @var{file} may be an open
500 file descriptor or an open file descriptor port.
503 @deffn {Scheme Procedure} select reads writes excepts [secs [usecs]]
504 @deffnx {C Function} scm_select (reads, writes, excepts, secs, usecs)
505 This procedure has a variety of uses: waiting for the ability
506 to provide input, accept output, or the existence of
507 exceptional conditions on a collection of ports or file
508 descriptors, or waiting for a timeout to occur.
509 It also returns if interrupted by a signal.
511 @var{reads}, @var{writes} and @var{excepts} can be lists or
512 vectors, with each member a port or a file descriptor.
513 The value returned is a list of three corresponding
514 lists or vectors containing only the members which meet the
515 specified requirement. The ability of port buffers to
516 provide input or accept output is taken into account.
517 Ordering of the input lists or vectors is not preserved.
519 The optional arguments @var{secs} and @var{usecs} specify the
520 timeout. Either @var{secs} can be specified alone, as
521 either an integer or a real number, or both @var{secs} and
522 @var{usecs} can be specified as integers, in which case
523 @var{usecs} is an additional timeout expressed in
524 microseconds. If @var{secs} is omitted or is @code{#f} then
525 select will wait for as long as it takes for one of the other
526 conditions to be satisfied.
528 The scsh version of @code{select} differs as follows:
529 Only vectors are accepted for the first three arguments.
530 The @var{usecs} argument is not supported.
531 Multiple values are returned instead of a list.
532 Duplicates in the input vectors appear only once in output.
533 An additional @code{select!} interface is provided.
539 These procedures allow querying and setting file system attributes
541 permissions, sizes and types of files); deleting, copying, renaming and
542 linking files; creating and removing directories and querying their
543 contents; syncing the file system and creating special files.
545 @deffn {Scheme Procedure} access? path how
546 @deffnx {C Function} scm_access (path, how)
547 Test accessibility of a file under the real UID and GID of the calling
548 process. The return is @code{#t} if @var{path} exists and the
549 permissions requested by @var{how} are all allowed, or @code{#f} if
552 @var{how} is an integer which is one of the following values, or a
553 bitwise-OR (@code{logior}) of multiple values.
556 Test for read permission.
559 Test for write permission.
562 Test for execute permission.
565 Test for existence of the file. This is implied by each of the other
566 tests, so there's no need to combine it with them.
569 It's important to note that @code{access?} does not simply indicate
570 what will happen on attempting to read or write a file. In normal
571 circumstances it does, but in a set-UID or set-GID program it doesn't
572 because @code{access?} tests the real ID, whereas an open or execute
573 attempt uses the effective ID.
575 A program which will never run set-UID/GID can ignore the difference
576 between real and effective IDs, but for maximum generality, especially
577 in library functions, it's best not to use @code{access?} to predict
578 the result of an open or execute, instead simply attempt that and
581 The main use for @code{access?} is to let a set-UID/GID program
582 determine what the invoking user would have been allowed to do,
583 without the greater (or perhaps lesser) privileges afforded by the
584 effective ID. For more on this, see @ref{Testing File Access,,, libc,
585 The GNU C Library Reference Manual}.
589 @deffn {Scheme Procedure} stat object
590 @deffnx {C Function} scm_stat (object)
591 Return an object containing various information about the file
592 determined by @var{obj}. @var{obj} can be a string containing
593 a file name or a port or integer file descriptor which is open
594 on a file (in which case @code{fstat} is used as the underlying
597 The object returned by @code{stat} can be passed as a single
598 parameter to the following procedures, all of which return
601 @deffn {Scheme Procedure} stat:dev st
602 The device number containing the file.
604 @deffn {Scheme Procedure} stat:ino st
605 The file serial number, which distinguishes this file from all
606 other files on the same device.
608 @deffn {Scheme Procedure} stat:mode st
609 The mode of the file. This is an integer which incorporates file type
610 information and file permission bits. See also @code{stat:type} and
611 @code{stat:perms} below.
613 @deffn {Scheme Procedure} stat:nlink st
614 The number of hard links to the file.
616 @deffn {Scheme Procedure} stat:uid st
617 The user ID of the file's owner.
619 @deffn {Scheme Procedure} stat:gid st
620 The group ID of the file.
622 @deffn {Scheme Procedure} stat:rdev st
623 Device ID; this entry is defined only for character or block special
624 files. On some systems this field is not available at all, in which
625 case @code{stat:rdev} returns @code{#f}.
627 @deffn {Scheme Procedure} stat:size st
628 The size of a regular file in bytes.
630 @deffn {Scheme Procedure} stat:atime st
631 The last access time for the file.
633 @deffn {Scheme Procedure} stat:mtime st
634 The last modification time for the file.
636 @deffn {Scheme Procedure} stat:ctime st
637 The last modification time for the attributes of the file.
639 @deffn {Scheme Procedure} stat:blksize st
640 The optimal block size for reading or writing the file, in bytes. On
641 some systems this field is not available, in which case
642 @code{stat:blksize} returns a sensible suggested block size.
644 @deffn {Scheme Procedure} stat:blocks st
645 The amount of disk space that the file occupies measured in units of
646 512 byte blocks. On some systems this field is not available, in
647 which case @code{stat:blocks} returns @code{#f}.
650 In addition, the following procedures return the information
651 from @code{stat:mode} in a more convenient form:
653 @deffn {Scheme Procedure} stat:type st
654 A symbol representing the type of file. Possible values are
655 @samp{regular}, @samp{directory}, @samp{symlink},
656 @samp{block-special}, @samp{char-special}, @samp{fifo}, @samp{socket},
659 @deffn {Scheme Procedure} stat:perms st
660 An integer representing the access permission bits.
664 @deffn {Scheme Procedure} lstat str
665 @deffnx {C Function} scm_lstat (str)
666 Similar to @code{stat}, but does not follow symbolic links, i.e.,
667 it will return information about a symbolic link itself, not the
668 file it points to. @var{path} must be a string.
671 @deffn {Scheme Procedure} readlink path
672 @deffnx {C Function} scm_readlink (path)
673 Return the value of the symbolic link named by @var{path} (a
674 string), i.e., the file that the link points to.
679 @deffn {Scheme Procedure} chown object owner group
680 @deffnx {C Function} scm_chown (object, owner, group)
681 Change the ownership and group of the file referred to by @var{object}
682 to the integer values @var{owner} and @var{group}. @var{object} can
683 be a string containing a file name or, if the platform supports
684 @code{fchown} (@pxref{File Owner,,,libc,The GNU C Library Reference
685 Manual}), a port or integer file descriptor which is open on the file.
686 The return value is unspecified.
688 If @var{object} is a symbolic link, either the
689 ownership of the link or the ownership of the referenced file will be
690 changed depending on the operating system (lchown is
691 unsupported at present). If @var{owner} or @var{group} is specified
692 as @code{-1}, then that ID is not changed.
696 @deffn {Scheme Procedure} chmod object mode
697 @deffnx {C Function} scm_chmod (object, mode)
698 Changes the permissions of the file referred to by @var{obj}.
699 @var{obj} can be a string containing a file name or a port or integer file
700 descriptor which is open on a file (in which case @code{fchmod} is used
701 as the underlying system call).
703 the new permissions as a decimal number, e.g., @code{(chmod "foo" #o755)}.
704 The return value is unspecified.
707 @deffn {Scheme Procedure} utime pathname [actime [modtime]]
708 @deffnx {C Function} scm_utime (pathname, actime, modtime)
709 @code{utime} sets the access and modification times for the
710 file named by @var{path}. If @var{actime} or @var{modtime} is
711 not supplied, then the current time is used. @var{actime} and
712 @var{modtime} must be integer time values as returned by the
713 @code{current-time} procedure.
715 (utime "foo" (- (current-time) 3600))
717 will set the access time to one hour in the past and the
718 modification time to the current time.
722 @deffn {Scheme Procedure} delete-file str
723 @deffnx {C Function} scm_delete_file (str)
724 Deletes (or ``unlinks'') the file whose path is specified by
728 @deffn {Scheme Procedure} copy-file oldfile newfile
729 @deffnx {C Function} scm_copy_file (oldfile, newfile)
730 Copy the file specified by @var{oldfile} to @var{newfile}.
731 The return value is unspecified.
735 @deffn {Scheme Procedure} rename-file oldname newname
736 @deffnx {C Function} scm_rename (oldname, newname)
737 Renames the file specified by @var{oldname} to @var{newname}.
738 The return value is unspecified.
741 @deffn {Scheme Procedure} link oldpath newpath
742 @deffnx {C Function} scm_link (oldpath, newpath)
743 Creates a new name @var{newpath} in the file system for the
744 file named by @var{oldpath}. If @var{oldpath} is a symbolic
745 link, the link may or may not be followed depending on the
749 @deffn {Scheme Procedure} symlink oldpath newpath
750 @deffnx {C Function} scm_symlink (oldpath, newpath)
751 Create a symbolic link named @var{newpath} with the value (i.e., pointing to)
752 @var{oldpath}. The return value is unspecified.
755 @deffn {Scheme Procedure} mkdir path [mode]
756 @deffnx {C Function} scm_mkdir (path, mode)
757 Create a new directory named by @var{path}. If @var{mode} is omitted
758 then the permissions of the directory file are set using the current
759 umask (@pxref{Processes}). Otherwise they are set to the decimal
760 value specified with @var{mode}. The return value is unspecified.
763 @deffn {Scheme Procedure} rmdir path
764 @deffnx {C Function} scm_rmdir (path)
765 Remove the existing directory named by @var{path}. The directory must
766 be empty for this to succeed. The return value is unspecified.
769 @deffn {Scheme Procedure} opendir dirname
770 @deffnx {C Function} scm_opendir (dirname)
771 Open the directory specified by @var{dirname} and return a directory
775 @deffn {Scheme Procedure} directory-stream? object
776 @deffnx {C Function} scm_directory_stream_p (object)
777 Return a boolean indicating whether @var{object} is a directory
778 stream as returned by @code{opendir}.
781 @deffn {Scheme Procedure} readdir stream
782 @deffnx {C Function} scm_readdir (stream)
783 Return (as a string) the next directory entry from the directory stream
784 @var{stream}. If there is no remaining entry to be read then the
785 end of file object is returned.
788 @deffn {Scheme Procedure} rewinddir stream
789 @deffnx {C Function} scm_rewinddir (stream)
790 Reset the directory port @var{stream} so that the next call to
791 @code{readdir} will return the first directory entry.
794 @deffn {Scheme Procedure} closedir stream
795 @deffnx {C Function} scm_closedir (stream)
796 Close the directory stream @var{stream}.
797 The return value is unspecified.
800 Here is an example showing how to display all the entries in a
804 (define dir (opendir "/usr/lib"))
805 (do ((entry (readdir dir) (readdir dir)))
806 ((eof-object? entry))
807 (display entry)(newline))
811 @deffn {Scheme Procedure} sync
812 @deffnx {C Function} scm_sync ()
813 Flush the operating system disk buffers.
814 The return value is unspecified.
817 @deffn {Scheme Procedure} mknod path type perms dev
818 @deffnx {C Function} scm_mknod (path, type, perms, dev)
819 Creates a new special file, such as a file corresponding to a device.
820 @var{path} specifies the name of the file. @var{type} should be one
821 of the following symbols: @samp{regular}, @samp{directory},
822 @samp{symlink}, @samp{block-special}, @samp{char-special},
823 @samp{fifo}, or @samp{socket}. @var{perms} (an integer) specifies the
824 file permissions. @var{dev} (an integer) specifies which device the
825 special file refers to. Its exact interpretation depends on the kind
826 of special file being created.
830 (mknod "/dev/fd0" 'block-special #o660 (+ (* 2 256) 2))
833 The return value is unspecified.
836 @deffn {Scheme Procedure} tmpnam
837 @deffnx {C Function} scm_tmpnam ()
838 Return a name in the file system that does not match any
839 existing file. However there is no guarantee that another
840 process will not create the file after @code{tmpnam} is called.
841 Care should be taken if opening the file, e.g., use the
842 @code{O_EXCL} open flag or use @code{mkstemp!} instead.
845 @deffn {Scheme Procedure} mkstemp! tmpl
846 @deffnx {C Function} scm_mkstemp (tmpl)
847 Create a new unique file in the file system and returns a new
848 buffered port open for reading and writing to the file.
849 @var{tmpl} is a string specifying where the file should be
850 created: it must end with @samp{XXXXXX} and will be changed in
851 place to return the name of the temporary file.
854 @deffn {Scheme Procedure} dirname filename
855 @deffnx {C Function} scm_dirname (filename)
856 Return the directory name component of the file name
857 @var{filename}. If @var{filename} does not contain a directory
858 component, @code{.} is returned.
861 @deffn {Scheme Procedure} basename filename [suffix]
862 @deffnx {C Function} scm_basename (filename, suffix)
863 Return the base name of the file name @var{filename}. The
864 base name is the file name without any directory components.
865 If @var{suffix} is provided, and is equal to the end of
866 @var{basename}, it is removed also.
869 (basename "/tmp/test.xml" ".xml")
875 @node User Information
876 @section User Information
878 The facilities in this section provide an interface to the user and
880 They should be used with care since they are not reentrant.
882 The following functions accept an object representing user information
883 and return a selected component:
885 @deffn {Scheme Procedure} passwd:name pw
886 The name of the userid.
888 @deffn {Scheme Procedure} passwd:passwd pw
889 The encrypted passwd.
891 @deffn {Scheme Procedure} passwd:uid pw
894 @deffn {Scheme Procedure} passwd:gid pw
897 @deffn {Scheme Procedure} passwd:gecos pw
900 @deffn {Scheme Procedure} passwd:dir pw
903 @deffn {Scheme Procedure} passwd:shell pw
908 @deffn {Scheme Procedure} getpwuid uid
909 Look up an integer userid in the user database.
912 @deffn {Scheme Procedure} getpwnam name
913 Look up a user name string in the user database.
916 @deffn {Scheme Procedure} setpwent
917 Initializes a stream used by @code{getpwent} to read from the user database.
918 The next use of @code{getpwent} will return the first entry. The
919 return value is unspecified.
922 @deffn {Scheme Procedure} getpwent
923 Return the next entry in the user database, using the stream set by
927 @deffn {Scheme Procedure} endpwent
928 Closes the stream used by @code{getpwent}. The return value is unspecified.
931 @deffn {Scheme Procedure} setpw [arg]
932 @deffnx {C Function} scm_setpwent (arg)
933 If called with a true argument, initialize or reset the password data
934 stream. Otherwise, close the stream. The @code{setpwent} and
935 @code{endpwent} procedures are implemented on top of this.
938 @deffn {Scheme Procedure} getpw [user]
939 @deffnx {C Function} scm_getpwuid (user)
940 Look up an entry in the user database. @var{obj} can be an integer,
941 a string, or omitted, giving the behaviour of getpwuid, getpwnam
942 or getpwent respectively.
945 The following functions accept an object representing group information
946 and return a selected component:
948 @deffn {Scheme Procedure} group:name gr
951 @deffn {Scheme Procedure} group:passwd gr
952 The encrypted group password.
954 @deffn {Scheme Procedure} group:gid gr
957 @deffn {Scheme Procedure} group:mem gr
958 A list of userids which have this group as a supplementary group.
962 @deffn {Scheme Procedure} getgrgid gid
963 Look up an integer group id in the group database.
966 @deffn {Scheme Procedure} getgrnam name
967 Look up a group name in the group database.
970 @deffn {Scheme Procedure} setgrent
971 Initializes a stream used by @code{getgrent} to read from the group database.
972 The next use of @code{getgrent} will return the first entry.
973 The return value is unspecified.
976 @deffn {Scheme Procedure} getgrent
977 Return the next entry in the group database, using the stream set by
981 @deffn {Scheme Procedure} endgrent
982 Closes the stream used by @code{getgrent}.
983 The return value is unspecified.
986 @deffn {Scheme Procedure} setgr [arg]
987 @deffnx {C Function} scm_setgrent (arg)
988 If called with a true argument, initialize or reset the group data
989 stream. Otherwise, close the stream. The @code{setgrent} and
990 @code{endgrent} procedures are implemented on top of this.
993 @deffn {Scheme Procedure} getgr [name]
994 @deffnx {C Function} scm_getgrgid (name)
995 Look up an entry in the group database. @var{obj} can be an integer,
996 a string, or omitted, giving the behaviour of getgrgid, getgrnam
997 or getgrent respectively.
1000 In addition to the accessor procedures for the user database, the
1001 following shortcut procedures are also available.
1003 @deffn {Scheme Procedure} cuserid
1004 @deffnx {C Function} scm_cuserid ()
1005 Return a string containing a user name associated with the
1006 effective user id of the process. Return @code{#f} if this
1007 information cannot be obtained.
1010 @deffn {Scheme Procedure} getlogin
1011 @deffnx {C Function} scm_getlogin ()
1012 Return a string containing the name of the user logged in on
1013 the controlling terminal of the process, or @code{#f} if this
1014 information cannot be obtained.
1021 @deffn {Scheme Procedure} current-time
1022 @deffnx {C Function} scm_current_time ()
1023 Return the number of seconds since 1970-01-01 00:00:00 @acronym{UTC},
1024 excluding leap seconds.
1027 @deffn {Scheme Procedure} gettimeofday
1028 @deffnx {C Function} scm_gettimeofday ()
1029 Return a pair containing the number of seconds and microseconds
1030 since 1970-01-01 00:00:00 @acronym{UTC}, excluding leap seconds. Note:
1031 whether true microsecond resolution is available depends on the
1035 The following procedures either accept an object representing a broken down
1036 time and return a selected component, or accept an object representing
1037 a broken down time and a value and set the component to the value.
1038 The numbers in parentheses give the usual range.
1040 @deffn {Scheme Procedure} tm:sec tm
1041 @deffnx {Scheme Procedure} set-tm:sec tm val
1044 @deffn {Scheme Procedure} tm:min tm
1045 @deffnx {Scheme Procedure} set-tm:min tm val
1048 @deffn {Scheme Procedure} tm:hour tm
1049 @deffnx {Scheme Procedure} set-tm:hour tm val
1052 @deffn {Scheme Procedure} tm:mday tm
1053 @deffnx {Scheme Procedure} set-tm:mday tm val
1054 Day of the month (1-31).
1056 @deffn {Scheme Procedure} tm:mon tm
1057 @deffnx {Scheme Procedure} set-tm:mon tm val
1060 @deffn {Scheme Procedure} tm:year tm
1061 @deffnx {Scheme Procedure} set-tm:year tm val
1062 Year (70-), the year minus 1900.
1064 @deffn {Scheme Procedure} tm:wday tm
1065 @deffnx {Scheme Procedure} set-tm:wday tm val
1066 Day of the week (0-6) with Sunday represented as 0.
1068 @deffn {Scheme Procedure} tm:yday tm
1069 @deffnx {Scheme Procedure} set-tm:yday tm val
1070 Day of the year (0-364, 365 in leap years).
1072 @deffn {Scheme Procedure} tm:isdst tm
1073 @deffnx {Scheme Procedure} set-tm:isdst tm val
1074 Daylight saving indicator (0 for ``no'', greater than 0 for ``yes'', less than
1077 @deffn {Scheme Procedure} tm:gmtoff tm
1078 @deffnx {Scheme Procedure} set-tm:gmtoff tm val
1079 Time zone offset in seconds west of @acronym{UTC} (-46800 to 43200).
1081 @deffn {Scheme Procedure} tm:zone tm
1082 @deffnx {Scheme Procedure} set-tm:zone tm val
1083 Time zone label (a string), not necessarily unique.
1087 @deffn {Scheme Procedure} localtime time [zone]
1088 @deffnx {C Function} scm_localtime (time, zone)
1089 Return an object representing the broken down components of
1090 @var{time}, an integer like the one returned by
1091 @code{current-time}. The time zone for the calculation is
1092 optionally specified by @var{zone} (a string), otherwise the
1093 @env{TZ} environment variable or the system default is used.
1096 @deffn {Scheme Procedure} gmtime time
1097 @deffnx {C Function} scm_gmtime (time)
1098 Return an object representing the broken down components of
1099 @var{time}, an integer like the one returned by
1100 @code{current-time}. The values are calculated for @acronym{UTC}.
1103 @deffn {Scheme Procedure} mktime sbd-time [zone]
1104 @deffnx {C Function} scm_mktime (sbd_time, zone)
1105 @var{sbd-time} is an object representing broken down time and
1106 @code{zone} is an optional time zone specifier (otherwise the @env{TZ}
1107 environment variable or the system default is used).
1109 Returns a pair: the @acronym{CAR} is a corresponding integer time
1110 value like that returned by @code{current-time}; the @acronym{CDR} is
1111 a broken down time object, similar to @var{sbd-time} but with
1112 normalized values; i.e.@: with corrected @code{tm:wday} and
1113 @code{tm:yday} fields.
1116 @deffn {Scheme Procedure} tzset
1117 @deffnx {C Function} scm_tzset ()
1118 Initialize the timezone from the @env{TZ} environment variable
1119 or the system default. It's not usually necessary to call this procedure
1120 since it's done automatically by other procedures that depend on the
1124 @deffn {Scheme Procedure} strftime format stime
1125 @deffnx {C Function} scm_strftime (format, stime)
1126 Formats a time specification @var{time} using @var{template}. @var{time}
1127 is an object with time components in the form returned by @code{localtime}
1128 or @code{gmtime}. @var{template} is a string which can include formatting
1129 specifications introduced by a @samp{%} character. The formatting of
1130 month and day names is dependent on the current locale. The value returned
1131 is the formatted string.
1132 @xref{Formatting Calendar Time, , , libc, The GNU C Library Reference Manual}.
1135 (strftime "%c" (localtime (current-time)))
1136 @result{} "Mon Mar 11 20:17:43 2002"
1140 @deffn {Scheme Procedure} strptime format string
1141 @deffnx {C Function} scm_strptime (format, string)
1142 Performs the reverse action to @code{strftime}, parsing
1143 @var{string} according to the specification supplied in
1144 @var{template}. The interpretation of month and day names is
1145 dependent on the current locale. The value returned is a pair.
1146 The @acronym{CAR} has an object with time components
1147 in the form returned by @code{localtime} or @code{gmtime},
1148 but the time zone components
1149 are not usefully set.
1150 The @acronym{CDR} reports the number of characters from @var{string}
1151 which were used for the conversion.
1154 @defvar internal-time-units-per-second
1155 The value of this variable is the number of time units per second
1156 reported by the following procedures.
1159 @deffn {Scheme Procedure} times
1160 @deffnx {C Function} scm_times ()
1161 Return an object with information about real and processor
1162 time. The following procedures accept such an object as an
1163 argument and return a selected component:
1165 @deffn {Scheme Procedure} tms:clock tms
1166 The current real time, expressed as time units relative to an
1169 @deffn {Scheme Procedure} tms:utime tms
1170 The CPU time units used by the calling process.
1172 @deffn {Scheme Procedure} tms:stime tms
1173 The CPU time units used by the system on behalf of the calling
1176 @deffn {Scheme Procedure} tms:cutime tms
1177 The CPU time units used by terminated child processes of the
1178 calling process, whose status has been collected (e.g., using
1181 @deffn {Scheme Procedure} tms:cstime tms
1182 Similarly, the CPU times units used by the system on behalf of
1183 terminated child processes.
1187 @deffn {Scheme Procedure} get-internal-real-time
1188 @deffnx {C Function} scm_get_internal_real_time ()
1189 Return the number of time units since the interpreter was
1193 @deffn {Scheme Procedure} get-internal-run-time
1194 @deffnx {C Function} scm_get_internal_run_time ()
1195 Return the number of time units of processor time used by the
1196 interpreter. Both @emph{system} and @emph{user} time are
1197 included but subprocesses are not.
1200 @node Runtime Environment
1201 @section Runtime Environment
1203 @deffn {Scheme Procedure} program-arguments
1204 @deffnx {Scheme Procedure} command-line
1205 @deffnx {C Function} scm_program_arguments ()
1206 Return the list of command line arguments passed to Guile, as a list of
1207 strings. The list includes the invoked program name, which is usually
1208 @code{"guile"}, but excludes switches and parameters for command line
1209 options like @code{-e} and @code{-l}.
1212 @deffn {Scheme Procedure} getenv nam
1213 @deffnx {C Function} scm_getenv (nam)
1214 Looks up the string @var{name} in the current environment. The return
1215 value is @code{#f} unless a string of the form @code{NAME=VALUE} is
1216 found, in which case the string @code{VALUE} is returned.
1219 @deffn {Scheme Procedure} setenv name value
1220 Modifies the environment of the current process, which is
1221 also the default environment inherited by child processes.
1223 If @var{value} is @code{#f}, then @var{name} is removed from the
1224 environment. Otherwise, the string @var{name}=@var{value} is added
1225 to the environment, replacing any existing string with name matching
1228 The return value is unspecified.
1231 @deffn {Scheme Procedure} unsetenv name
1232 Remove variable @var{name} from the environment. The
1233 name can not contain a @samp{=} character.
1236 @deffn {Scheme Procedure} environ [env]
1237 @deffnx {C Function} scm_environ (env)
1238 If @var{env} is omitted, return the current environment (in the
1239 Unix sense) as a list of strings. Otherwise set the current
1240 environment, which is also the default environment for child
1241 processes, to the supplied list of strings. Each member of
1242 @var{env} should be of the form @var{NAME}=@var{VALUE} and values of
1243 @var{NAME} should not be duplicated. If @var{env} is supplied
1244 then the return value is unspecified.
1247 @deffn {Scheme Procedure} putenv str
1248 @deffnx {C Function} scm_putenv (str)
1249 Modifies the environment of the current process, which is
1250 also the default environment inherited by child processes.
1252 If @var{string} is of the form @code{NAME=VALUE} then it will be written
1253 directly into the environment, replacing any existing environment string
1255 name matching @code{NAME}. If @var{string} does not contain an equal
1256 sign, then any existing string with name matching @var{string} will
1259 The return value is unspecified.
1267 @deffn {Scheme Procedure} chdir str
1268 @deffnx {C Function} scm_chdir (str)
1269 Change the current working directory to @var{path}.
1270 The return value is unspecified.
1274 @deffn {Scheme Procedure} getcwd
1275 @deffnx {C Function} scm_getcwd ()
1276 Return the name of the current working directory.
1279 @deffn {Scheme Procedure} umask [mode]
1280 @deffnx {C Function} scm_umask (mode)
1281 If @var{mode} is omitted, returns a decimal number representing the
1282 current file creation mask. Otherwise the file creation mask is set
1283 to @var{mode} and the previous value is returned. @xref{Setting
1284 Permissions,,Assigning File Permissions,libc,The GNU C Library
1285 Reference Manual}, for more on how to use umasks.
1287 E.g., @code{(umask #o022)} sets the mask to octal 22/decimal 18.
1290 @deffn {Scheme Procedure} chroot path
1291 @deffnx {C Function} scm_chroot (path)
1292 Change the root directory to that specified in @var{path}.
1293 This directory will be used for path names beginning with
1294 @file{/}. The root directory is inherited by all children
1295 of the current process. Only the superuser may change the
1299 @deffn {Scheme Procedure} getpid
1300 @deffnx {C Function} scm_getpid ()
1301 Return an integer representing the current process ID.
1304 @deffn {Scheme Procedure} getgroups
1305 @deffnx {C Function} scm_getgroups ()
1306 Return a vector of integers representing the current
1307 supplementary group IDs.
1310 @deffn {Scheme Procedure} getppid
1311 @deffnx {C Function} scm_getppid ()
1312 Return an integer representing the process ID of the parent
1316 @deffn {Scheme Procedure} getuid
1317 @deffnx {C Function} scm_getuid ()
1318 Return an integer representing the current real user ID.
1321 @deffn {Scheme Procedure} getgid
1322 @deffnx {C Function} scm_getgid ()
1323 Return an integer representing the current real group ID.
1326 @deffn {Scheme Procedure} geteuid
1327 @deffnx {C Function} scm_geteuid ()
1328 Return an integer representing the current effective user ID.
1329 If the system does not support effective IDs, then the real ID
1330 is returned. @code{(provided? 'EIDs)} reports whether the
1331 system supports effective IDs.
1334 @deffn {Scheme Procedure} getegid
1335 @deffnx {C Function} scm_getegid ()
1336 Return an integer representing the current effective group ID.
1337 If the system does not support effective IDs, then the real ID
1338 is returned. @code{(provided? 'EIDs)} reports whether the
1339 system supports effective IDs.
1342 @deffn {Scheme Procedure} setuid id
1343 @deffnx {C Function} scm_setuid (id)
1344 Sets both the real and effective user IDs to the integer @var{id}, provided
1345 the process has appropriate privileges.
1346 The return value is unspecified.
1349 @deffn {Scheme Procedure} setgid id
1350 @deffnx {C Function} scm_setgid (id)
1351 Sets both the real and effective group IDs to the integer @var{id}, provided
1352 the process has appropriate privileges.
1353 The return value is unspecified.
1356 @deffn {Scheme Procedure} seteuid id
1357 @deffnx {C Function} scm_seteuid (id)
1358 Sets the effective user ID to the integer @var{id}, provided the process
1359 has appropriate privileges. If effective IDs are not supported, the
1360 real ID is set instead---@code{(provided? 'EIDs)} reports whether the
1361 system supports effective IDs.
1362 The return value is unspecified.
1365 @deffn {Scheme Procedure} setegid id
1366 @deffnx {C Function} scm_setegid (id)
1367 Sets the effective group ID to the integer @var{id}, provided the process
1368 has appropriate privileges. If effective IDs are not supported, the
1369 real ID is set instead---@code{(provided? 'EIDs)} reports whether the
1370 system supports effective IDs.
1371 The return value is unspecified.
1374 @deffn {Scheme Procedure} getpgrp
1375 @deffnx {C Function} scm_getpgrp ()
1376 Return an integer representing the current process group ID.
1377 This is the @acronym{POSIX} definition, not @acronym{BSD}.
1380 @deffn {Scheme Procedure} setpgid pid pgid
1381 @deffnx {C Function} scm_setpgid (pid, pgid)
1382 Move the process @var{pid} into the process group @var{pgid}. @var{pid} or
1383 @var{pgid} must be integers: they can be zero to indicate the ID of the
1385 Fails on systems that do not support job control.
1386 The return value is unspecified.
1389 @deffn {Scheme Procedure} setsid
1390 @deffnx {C Function} scm_setsid ()
1391 Creates a new session. The current process becomes the session leader
1392 and is put in a new process group. The process will be detached
1393 from its controlling terminal if it has one.
1394 The return value is an integer representing the new process group ID.
1397 @deffn {Scheme Procedure} waitpid pid [options]
1398 @deffnx {C Function} scm_waitpid (pid, options)
1399 This procedure collects status information from a child process which
1400 has terminated or (optionally) stopped. Normally it will
1401 suspend the calling process until this can be done. If more than one
1402 child process is eligible then one will be chosen by the operating system.
1404 The value of @var{pid} determines the behaviour:
1407 @item @var{pid} greater than 0
1408 Request status information from the specified child process.
1409 @item @var{pid} equal to -1 or @code{WAIT_ANY}
1411 Request status information for any child process.
1412 @item @var{pid} equal to 0 or @code{WAIT_MYPGRP}
1414 Request status information for any child process in the current process
1416 @item @var{pid} less than -1
1417 Request status information for any child process whose process group ID
1418 is @minus{}@var{pid}.
1421 The @var{options} argument, if supplied, should be the bitwise OR of the
1422 values of zero or more of the following variables:
1425 Return immediately even if there are no child processes to be collected.
1429 Report status information for stopped processes as well as terminated
1433 The return value is a pair containing:
1437 The process ID of the child process, or 0 if @code{WNOHANG} was
1438 specified and no process was collected.
1440 The integer status value.
1445 functions can be used to decode the process status code returned
1448 @deffn {Scheme Procedure} status:exit-val status
1449 @deffnx {C Function} scm_status_exit_val (status)
1450 Return the exit status value, as would be set if a process
1451 ended normally through a call to @code{exit} or @code{_exit},
1452 if any, otherwise @code{#f}.
1455 @deffn {Scheme Procedure} status:term-sig status
1456 @deffnx {C Function} scm_status_term_sig (status)
1457 Return the signal number which terminated the process, if any,
1458 otherwise @code{#f}.
1461 @deffn {Scheme Procedure} status:stop-sig status
1462 @deffnx {C Function} scm_status_stop_sig (status)
1463 Return the signal number which stopped the process, if any,
1464 otherwise @code{#f}.
1467 @deffn {Scheme Procedure} system [cmd]
1468 @deffnx {C Function} scm_system (cmd)
1469 Execute @var{cmd} using the operating system's ``command
1470 processor''. Under Unix this is usually the default shell
1471 @code{sh}. The value returned is @var{cmd}'s exit status as
1472 returned by @code{waitpid}, which can be interpreted using the
1475 If @code{system} is called without arguments, return a boolean
1476 indicating whether the command processor is available.
1479 @deffn {Scheme Procedure} system* . args
1480 @deffnx {C Function} scm_system_star (args)
1481 Execute the command indicated by @var{args}. The first element must
1482 be a string indicating the command to be executed, and the remaining
1483 items must be strings representing each of the arguments to that
1486 This function returns the exit status of the command as provided by
1487 @code{waitpid}. This value can be handled with @code{status:exit-val}
1488 and the related functions.
1490 @code{system*} is similar to @code{system}, but accepts only one
1491 string per-argument, and performs no shell interpretation. The
1492 command is executed using fork and execlp. Accordingly this function
1493 may be safer than @code{system} in situations where shell
1494 interpretation is not required.
1496 Example: (system* "echo" "foo" "bar")
1499 @deffn {Scheme Procedure} primitive-exit [status]
1500 @deffnx {C Function} scm_primitive_exit (status)
1501 Terminate the current process without unwinding the Scheme stack.
1502 This is would typically be useful after a fork. The exit status
1503 is @var{status} if supplied, otherwise zero.
1506 @deffn {Scheme Procedure} execl filename . args
1507 @deffnx {C Function} scm_execl (filename, args)
1508 Executes the file named by @var{path} as a new process image.
1509 The remaining arguments are supplied to the process; from a C program
1510 they are accessible as the @code{argv} argument to @code{main}.
1511 Conventionally the first @var{arg} is the same as @var{path}.
1512 All arguments must be strings.
1514 If @var{arg} is missing, @var{path} is executed with a null
1515 argument list, which may have system-dependent side-effects.
1517 This procedure is currently implemented using the @code{execv} system
1518 call, but we call it @code{execl} because of its Scheme calling interface.
1521 @deffn {Scheme Procedure} execlp filename . args
1522 @deffnx {C Function} scm_execlp (filename, args)
1523 Similar to @code{execl}, however if
1524 @var{filename} does not contain a slash
1525 then the file to execute will be located by searching the
1526 directories listed in the @code{PATH} environment variable.
1528 This procedure is currently implemented using the @code{execvp} system
1529 call, but we call it @code{execlp} because of its Scheme calling interface.
1532 @deffn {Scheme Procedure} execle filename env . args
1533 @deffnx {C Function} scm_execle (filename, env, args)
1534 Similar to @code{execl}, but the environment of the new process is
1535 specified by @var{env}, which must be a list of strings as returned by the
1536 @code{environ} procedure.
1538 This procedure is currently implemented using the @code{execve} system
1539 call, but we call it @code{execle} because of its Scheme calling interface.
1542 @deffn {Scheme Procedure} primitive-fork
1543 @deffnx {C Function} scm_fork ()
1544 Creates a new ``child'' process by duplicating the current ``parent'' process.
1545 In the child the return value is 0. In the parent the return value is
1546 the integer process ID of the child.
1548 This procedure has been renamed from @code{fork} to avoid a naming conflict
1552 @deffn {Scheme Procedure} nice incr
1553 @deffnx {C Function} scm_nice (incr)
1554 Increment the priority of the current process by @var{incr}. A higher
1555 priority value means that the process runs less often.
1556 The return value is unspecified.
1559 @deffn {Scheme Procedure} setpriority which who prio
1560 @deffnx {C Function} scm_setpriority (which, who, prio)
1561 @vindex PRIO_PROCESS
1564 Set the scheduling priority of the process, process group
1565 or user, as indicated by @var{which} and @var{who}. @var{which}
1566 is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
1567 or @code{PRIO_USER}, and @var{who} is interpreted relative to
1568 @var{which} (a process identifier for @code{PRIO_PROCESS},
1569 process group identifier for @code{PRIO_PGRP}, and a user
1570 identifier for @code{PRIO_USER}. A zero value of @var{who}
1571 denotes the current process, process group, or user.
1572 @var{prio} is a value in the range [@minus{}20,20]. The default
1573 priority is 0; lower priorities (in numerical terms) cause more
1574 favorable scheduling. Sets the priority of all of the specified
1575 processes. Only the super-user may lower priorities. The return
1576 value is not specified.
1579 @deffn {Scheme Procedure} getpriority which who
1580 @deffnx {C Function} scm_getpriority (which, who)
1581 @vindex PRIO_PROCESS
1584 Return the scheduling priority of the process, process group
1585 or user, as indicated by @var{which} and @var{who}. @var{which}
1586 is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
1587 or @code{PRIO_USER}, and @var{who} should be interpreted depending on
1588 @var{which} (a process identifier for @code{PRIO_PROCESS},
1589 process group identifier for @code{PRIO_PGRP}, and a user
1590 identifier for @code{PRIO_USER}). A zero value of @var{who}
1591 denotes the current process, process group, or user. Return
1592 the highest priority (lowest numerical value) of any of the
1593 specified processes.
1600 Procedures to raise, handle and wait for signals.
1602 @deffn {Scheme Procedure} kill pid sig
1603 @deffnx {C Function} scm_kill (pid, sig)
1604 Sends a signal to the specified process or group of processes.
1606 @var{pid} specifies the processes to which the signal is sent:
1609 @item @var{pid} greater than 0
1610 The process whose identifier is @var{pid}.
1611 @item @var{pid} equal to 0
1612 All processes in the current process group.
1613 @item @var{pid} less than -1
1614 The process group whose identifier is -@var{pid}
1615 @item @var{pid} equal to -1
1616 If the process is privileged, all processes except for some special
1617 system processes. Otherwise, all processes with the current effective
1621 @var{sig} should be specified using a variable corresponding to
1622 the Unix symbolic name, e.g.,
1632 A full list of signals on the GNU system may be found in @ref{Standard
1633 Signals,,,libc,The GNU C Library Reference Manual}.
1636 @deffn {Scheme Procedure} raise sig
1637 @deffnx {C Function} scm_raise (sig)
1638 Sends a specified signal @var{sig} to the current process, where
1639 @var{sig} is as described for the @code{kill} procedure.
1642 @deffn {Scheme Procedure} sigaction signum [handler [flags [thread]]]
1643 @deffnx {C Function} scm_sigaction (signum, handler, flags)
1644 @deffnx {C Function} scm_sigaction_for_thread (signum, handler, flags, thread)
1645 Install or report the signal handler for a specified signal.
1647 @var{signum} is the signal number, which can be specified using the value
1648 of variables such as @code{SIGINT}.
1650 If @var{handler} is omitted, @code{sigaction} returns a pair: the
1651 @acronym{CAR} is the current signal hander, which will be either an
1652 integer with the value @code{SIG_DFL} (default action) or
1653 @code{SIG_IGN} (ignore), or the Scheme procedure which handles the
1654 signal, or @code{#f} if a non-Scheme procedure handles the signal.
1655 The @acronym{CDR} contains the current @code{sigaction} flags for the
1658 If @var{handler} is provided, it is installed as the new handler for
1659 @var{signum}. @var{handler} can be a Scheme procedure taking one
1660 argument, or the value of @code{SIG_DFL} (default action) or
1661 @code{SIG_IGN} (ignore), or @code{#f} to restore whatever signal handler
1662 was installed before @code{sigaction} was first used. When a scheme
1663 procedure has been specified, that procedure will run in the given
1664 @var{thread}. When no thread has been given, the thread that made this
1665 call to @code{sigaction} is used.
1667 Flags can optionally be specified for the new handler (@code{SA_RESTART}
1668 will always be added if it's available and the system is using
1669 restartable system calls.) The return value is a pair with information
1670 about the old handler as described above.
1672 This interface does not provide access to the ``signal blocking''
1673 facility. Maybe this is not needed, since the thread support may
1674 provide solutions to the problem of consistent access to data
1678 @deffn {Scheme Procedure} restore-signals
1679 @deffnx {C Function} scm_restore_signals ()
1680 Return all signal handlers to the values they had before any call to
1681 @code{sigaction} was made. The return value is unspecified.
1684 @deffn {Scheme Procedure} alarm i
1685 @deffnx {C Function} scm_alarm (i)
1686 Set a timer to raise a @code{SIGALRM} signal after the specified
1687 number of seconds (an integer). It's advisable to install a signal
1689 @code{SIGALRM} beforehand, since the default action is to terminate
1692 The return value indicates the time remaining for the previous alarm,
1693 if any. The new value replaces the previous alarm. If there was
1694 no previous alarm, the return value is zero.
1697 @deffn {Scheme Procedure} pause
1698 @deffnx {C Function} scm_pause ()
1699 Pause the current process (thread?) until a signal arrives whose
1700 action is to either terminate the current process or invoke a
1701 handler procedure. The return value is unspecified.
1704 @deffn {Scheme Procedure} sleep i
1705 @deffnx {C Function} scm_sleep (i)
1706 Wait for the given number of seconds (an integer) or until a signal
1707 arrives. The return value is zero if the time elapses or the number
1708 of seconds remaining otherwise.
1711 @deffn {Scheme Procedure} usleep i
1712 @deffnx {C Function} scm_usleep (i)
1713 Sleep for @var{i} microseconds. @code{usleep} is not available on
1714 all platforms. [FIXME: so what happens when it isn't?]
1717 @deffn {Scheme Procedure} setitimer which_timer interval_seconds interval_microseconds value_seconds value_microseconds
1718 @deffnx {C Function} scm_setitimer (which_timer, interval_seconds, interval_microseconds, value_seconds, value_microseconds)
1719 Set the timer specified by @var{which_timer} according to the given
1720 @var{interval_seconds}, @var{interval_microseconds},
1721 @var{value_seconds}, and @var{value_microseconds} values.
1723 Return information about the timer's previous setting.
1725 The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
1726 and @code{ITIMER_PROF}.
1728 The return value will be a list of two cons pairs representing the
1729 current state of the given timer. The first pair is the seconds and
1730 microseconds of the timer @code{it_interval}, and the second pair is
1731 the seconds and microseconds of the timer @code{it_value}.
1734 @deffn {Scheme Procedure} getitimer which_timer
1735 @deffnx {C Function} scm_getitimer (which_timer)
1736 Return information about the timer specified by @var{which_timer}.
1738 The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
1739 and @code{ITIMER_PROF}.
1741 The return value will be a list of two cons pairs representing the
1742 current state of the given timer. The first pair is the seconds and
1743 microseconds of the timer @code{it_interval}, and the second pair is
1744 the seconds and microseconds of the timer @code{it_value}.
1748 @node Terminals and Ptys
1749 @section Terminals and Ptys
1751 @deffn {Scheme Procedure} isatty? port
1752 @deffnx {C Function} scm_isatty_p (port)
1753 Return @code{#t} if @var{port} is using a serial non--file
1754 device, otherwise @code{#f}.
1757 @deffn {Scheme Procedure} ttyname port
1758 @deffnx {C Function} scm_ttyname (port)
1759 Return a string with the name of the serial terminal device
1760 underlying @var{port}.
1763 @deffn {Scheme Procedure} ctermid
1764 @deffnx {C Function} scm_ctermid ()
1765 Return a string containing the file name of the controlling
1766 terminal for the current process.
1769 @deffn {Scheme Procedure} tcgetpgrp port
1770 @deffnx {C Function} scm_tcgetpgrp (port)
1771 Return the process group ID of the foreground process group
1772 associated with the terminal open on the file descriptor
1773 underlying @var{port}.
1775 If there is no foreground process group, the return value is a
1776 number greater than 1 that does not match the process group ID
1777 of any existing process group. This can happen if all of the
1778 processes in the job that was formerly the foreground job have
1779 terminated, and no other job has yet been moved into the
1783 @deffn {Scheme Procedure} tcsetpgrp port pgid
1784 @deffnx {C Function} scm_tcsetpgrp (port, pgid)
1785 Set the foreground process group ID for the terminal used by the file
1786 descriptor underlying @var{port} to the integer @var{pgid}.
1788 must be a member of the same session as @var{pgid} and must have the same
1789 controlling terminal. The return value is unspecified.
1795 The following procedures provide an interface to the @code{popen} and
1796 @code{pclose} system routines. The code is in a separate ``popen''
1800 (use-modules (ice-9 popen))
1804 @deffn {Scheme Procedure} open-pipe command modes
1805 Executes the shell command @var{command} (a string) in a subprocess.
1806 A pipe to the process is created and returned. @var{modes} specifies
1807 whether an input or output pipe to the process is created: it should
1808 be the value of @code{OPEN_READ} or @code{OPEN_WRITE}.
1811 @deffn {Scheme Procedure} open-input-pipe command
1812 Equivalent to @code{open-pipe} with mode @code{OPEN_READ}.
1815 (read-line (open-input-pipe "date"))
1816 @result{} "Mon Mar 11 20:10:44 GMT 2002"
1819 @result{} (24160 . 0)
1823 @deffn {Scheme Procedure} open-output-pipe command
1824 Equivalent to @code{open-pipe} with mode @code{OPEN_WRITE}.
1828 @deffn {Scheme Procedure} close-pipe port
1829 Closes the pipe created by @code{open-pipe}, then waits for the process
1830 to terminate and returns its status value, @xref{Processes, waitpid}, for
1831 information on how to interpret this value.
1833 @code{close-port} (@pxref{Closing, close-port}) can also be used to
1834 close a pipe, but doesn't return the status.
1841 * Network Address Conversion::
1842 * Network Databases::
1843 * Network Sockets and Communication::
1844 * Internet Socket Examples::
1847 @node Network Address Conversion
1848 @subsection Network Address Conversion
1850 This section describes procedures which convert internet addresses
1851 between numeric and string formats.
1853 @subsubsection IPv4 Address Conversion
1855 An IPv4 Internet address is a 4-byte value, represented in Guile as an
1856 integer in network byte order (meaning the first byte is the most
1857 significant in the number).
1859 @defvar INADDR_LOOPBACK
1860 The address of the local host using the loopback device, ie.@:
1864 @defvar INADDR_BROADCAST
1865 The broadcast address on the local network.
1868 @c INADDR_NONE is defined in the code, but serves no purpose.
1869 @c inet_addr() returns it as an error indication, but that function
1870 @c isn't provided, for the good reason that inet_aton() does the same
1871 @c job and gives an unambiguous error indication. (INADDR_NONE is a
1872 @c valid 4-byte value, in glibc it's the same as INADDR_BROADCAST.)
1874 @c @defvar INADDR_NONE
1878 @deffn {Scheme Procedure} inet-aton address
1879 @deffnx {C Function} scm_inet_aton (address)
1880 Convert an IPv4 Internet address from printable string
1881 (dotted decimal notation) to an integer. E.g.,
1884 (inet-aton "127.0.0.1") @result{} 2130706433
1888 @deffn {Scheme Procedure} inet-ntoa inetid
1889 @deffnx {C Function} scm_inet_ntoa (inetid)
1890 Convert an IPv4 Internet address to a printable
1891 (dotted decimal notation) string. E.g.,
1894 (inet-ntoa 2130706433) @result{} "127.0.0.1"
1898 @deffn {Scheme Procedure} inet-netof address
1899 @deffnx {C Function} scm_inet_netof (address)
1900 Return the network number part of the given IPv4
1901 Internet address. E.g.,
1904 (inet-netof 2130706433) @result{} 127
1908 @deffn {Scheme Procedure} inet-lnaof address
1909 @deffnx {C Function} scm_lnaof (address)
1910 Return the local-address-with-network part of the given
1911 IPv4 Internet address, using the obsolete class A/B/C system.
1915 (inet-lnaof 2130706433) @result{} 1
1919 @deffn {Scheme Procedure} inet-makeaddr net lna
1920 @deffnx {C Function} scm_inet_makeaddr (net, lna)
1921 Make an IPv4 Internet address by combining the network number
1922 @var{net} with the local-address-within-network number
1926 (inet-makeaddr 127 1) @result{} 2130706433
1930 @subsubsection IPv6 Address Conversion
1932 @deffn {Scheme Procedure} inet-ntop family address
1933 @deffnx {C Function} scm_inet_ntop (family, address)
1934 Convert a network address into a printable string.
1935 Note that unlike the C version of this function,
1936 the input is an integer with normal host byte ordering.
1937 @var{family} can be @code{AF_INET} or @code{AF_INET6}. E.g.,
1940 (inet-ntop AF_INET 2130706433) @result{} "127.0.0.1"
1941 (inet-ntop AF_INET6 (- (expt 2 128) 1)) @result{}
1942 ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
1946 @deffn {Scheme Procedure} inet-pton family address
1947 @deffnx {C Function} scm_inet_pton (family, address)
1948 Convert a string containing a printable network address to
1949 an integer address. Note that unlike the C version of this
1951 the result is an integer with normal host byte ordering.
1952 @var{family} can be @code{AF_INET} or @code{AF_INET6}. E.g.,
1955 (inet-pton AF_INET "127.0.0.1") @result{} 2130706433
1956 (inet-pton AF_INET6 "::1") @result{} 1
1961 @node Network Databases
1962 @subsection Network Databases
1964 This section describes procedures which query various network databases.
1965 Care should be taken when using the database routines since they are not
1968 @subsubsection The Host Database
1970 A @dfn{host object} is a structure that represents what is known about a
1971 network host, and is the usual way of representing a system's network
1972 identity inside software.
1974 The following functions accept a host object and return a selected
1977 @deffn {Scheme Procedure} hostent:name host
1978 The ``official'' hostname for @var{host}.
1980 @deffn {Scheme Procedure} hostent:aliases host
1981 A list of aliases for @var{host}.
1983 @deffn {Scheme Procedure} hostent:addrtype host
1984 The host address type. For hosts with Internet addresses, this will
1985 return @code{AF_INET}.
1987 @deffn {Scheme Procedure} hostent:length host
1988 The length of each address for @var{host}, in bytes.
1990 @deffn {Scheme Procedure} hostent:addr-list host
1991 The list of network addresses associated with @var{host}.
1994 The following procedures are used to search the host database:
1996 @deffn {Scheme Procedure} gethost [host]
1997 @deffnx {Scheme Procedure} gethostbyname hostname
1998 @deffnx {Scheme Procedure} gethostbyaddr address
1999 @deffnx {C Function} scm_gethost (host)
2000 Look up a host by name or address, returning a host object. The
2001 @code{gethost} procedure will accept either a string name or an integer
2002 address; if given no arguments, it behaves like @code{gethostent} (see
2003 below). If a name or address is supplied but the address can not be
2004 found, an error will be thrown to one of the keys:
2005 @code{host-not-found}, @code{try-again}, @code{no-recovery} or
2006 @code{no-data}, corresponding to the equivalent @code{h_error} values.
2007 Unusual conditions may result in errors thrown to the
2008 @code{system-error} or @code{misc_error} keys.
2011 (gethost "www.gnu.org")
2012 @result{} #("www.gnu.org" () 2 4 (3353880842))
2014 (gethostbyname "www.emacs.org")
2015 @result{} #("emacs.org" ("www.emacs.org") 2 4 (1073448978))
2019 The following procedures may be used to step through the host
2020 database from beginning to end.
2022 @deffn {Scheme Procedure} sethostent [stayopen]
2023 Initialize an internal stream from which host objects may be read. This
2024 procedure must be called before any calls to @code{gethostent}, and may
2025 also be called afterward to reset the host entry stream. If
2026 @var{stayopen} is supplied and is not @code{#f}, the database is not
2027 closed by subsequent @code{gethostbyname} or @code{gethostbyaddr} calls,
2028 possibly giving an efficiency gain.
2031 @deffn {Scheme Procedure} gethostent
2032 Return the next host object from the host database, or @code{#f} if
2033 there are no more hosts to be found (or an error has been encountered).
2034 This procedure may not be used before @code{sethostent} has been called.
2037 @deffn {Scheme Procedure} endhostent
2038 Close the stream used by @code{gethostent}. The return value is unspecified.
2041 @deffn {Scheme Procedure} sethost [stayopen]
2042 @deffnx {C Function} scm_sethost (stayopen)
2043 If @var{stayopen} is omitted, this is equivalent to @code{endhostent}.
2044 Otherwise it is equivalent to @code{sethostent stayopen}.
2046 @subsubsection The Network Database
2048 The following functions accept an object representing a network
2049 and return a selected component:
2051 @deffn {Scheme Procedure} netent:name net
2052 The ``official'' network name.
2054 @deffn {Scheme Procedure} netent:aliases net
2055 A list of aliases for the network.
2057 @deffn {Scheme Procedure} netent:addrtype net
2058 The type of the network number. Currently, this returns only
2061 @deffn {Scheme Procedure} netent:net net
2065 The following procedures are used to search the network database:
2067 @deffn {Scheme Procedure} getnet [net]
2068 @deffnx {Scheme Procedure} getnetbyname net-name
2069 @deffnx {Scheme Procedure} getnetbyaddr net-number
2070 @deffnx {C Function} scm_getnet (net)
2071 Look up a network by name or net number in the network database. The
2072 @var{net-name} argument must be a string, and the @var{net-number}
2073 argument must be an integer. @code{getnet} will accept either type of
2074 argument, behaving like @code{getnetent} (see below) if no arguments are
2078 The following procedures may be used to step through the network
2079 database from beginning to end.
2081 @deffn {Scheme Procedure} setnetent [stayopen]
2082 Initialize an internal stream from which network objects may be read. This
2083 procedure must be called before any calls to @code{getnetent}, and may
2084 also be called afterward to reset the net entry stream. If
2085 @var{stayopen} is supplied and is not @code{#f}, the database is not
2086 closed by subsequent @code{getnetbyname} or @code{getnetbyaddr} calls,
2087 possibly giving an efficiency gain.
2090 @deffn {Scheme Procedure} getnetent
2091 Return the next entry from the network database.
2094 @deffn {Scheme Procedure} endnetent
2095 Close the stream used by @code{getnetent}. The return value is unspecified.
2098 @deffn {Scheme Procedure} setnet [stayopen]
2099 @deffnx {C Function} scm_setnet (stayopen)
2100 If @var{stayopen} is omitted, this is equivalent to @code{endnetent}.
2101 Otherwise it is equivalent to @code{setnetent stayopen}.
2104 @subsubsection The Protocol Database
2106 The following functions accept an object representing a protocol
2107 and return a selected component:
2109 @deffn {Scheme Procedure} protoent:name protocol
2110 The ``official'' protocol name.
2112 @deffn {Scheme Procedure} protoent:aliases protocol
2113 A list of aliases for the protocol.
2115 @deffn {Scheme Procedure} protoent:proto protocol
2116 The protocol number.
2119 The following procedures are used to search the protocol database:
2121 @deffn {Scheme Procedure} getproto [protocol]
2122 @deffnx {Scheme Procedure} getprotobyname name
2123 @deffnx {Scheme Procedure} getprotobynumber number
2124 @deffnx {C Function} scm_getproto (protocol)
2125 Look up a network protocol by name or by number. @code{getprotobyname}
2126 takes a string argument, and @code{getprotobynumber} takes an integer
2127 argument. @code{getproto} will accept either type, behaving like
2128 @code{getprotoent} (see below) if no arguments are supplied.
2131 The following procedures may be used to step through the protocol
2132 database from beginning to end.
2134 @deffn {Scheme Procedure} setprotoent [stayopen]
2135 Initialize an internal stream from which protocol objects may be read. This
2136 procedure must be called before any calls to @code{getprotoent}, and may
2137 also be called afterward to reset the protocol entry stream. If
2138 @var{stayopen} is supplied and is not @code{#f}, the database is not
2139 closed by subsequent @code{getprotobyname} or @code{getprotobynumber} calls,
2140 possibly giving an efficiency gain.
2143 @deffn {Scheme Procedure} getprotoent
2144 Return the next entry from the protocol database.
2147 @deffn {Scheme Procedure} endprotoent
2148 Close the stream used by @code{getprotoent}. The return value is unspecified.
2151 @deffn {Scheme Procedure} setproto [stayopen]
2152 @deffnx {C Function} scm_setproto (stayopen)
2153 If @var{stayopen} is omitted, this is equivalent to @code{endprotoent}.
2154 Otherwise it is equivalent to @code{setprotoent stayopen}.
2157 @subsubsection The Service Database
2159 The following functions accept an object representing a service
2160 and return a selected component:
2162 @deffn {Scheme Procedure} servent:name serv
2163 The ``official'' name of the network service.
2165 @deffn {Scheme Procedure} servent:aliases serv
2166 A list of aliases for the network service.
2168 @deffn {Scheme Procedure} servent:port serv
2169 The Internet port used by the service.
2171 @deffn {Scheme Procedure} servent:proto serv
2172 The protocol used by the service. A service may be listed many times
2173 in the database under different protocol names.
2176 The following procedures are used to search the service database:
2178 @deffn {Scheme Procedure} getserv [name [protocol]]
2179 @deffnx {Scheme Procedure} getservbyname name protocol
2180 @deffnx {Scheme Procedure} getservbyport port protocol
2181 @deffnx {C Function} scm_getserv (name, protocol)
2182 Look up a network service by name or by service number, and return a
2183 network service object. The @var{protocol} argument specifies the name
2184 of the desired protocol; if the protocol found in the network service
2185 database does not match this name, a system error is signalled.
2187 The @code{getserv} procedure will take either a service name or number
2188 as its first argument; if given no arguments, it behaves like
2189 @code{getservent} (see below).
2192 (getserv "imap" "tcp")
2193 @result{} #("imap2" ("imap") 143 "tcp")
2195 (getservbyport 88 "udp")
2196 @result{} #("kerberos" ("kerberos5" "krb5") 88 "udp")
2200 The following procedures may be used to step through the service
2201 database from beginning to end.
2203 @deffn {Scheme Procedure} setservent [stayopen]
2204 Initialize an internal stream from which service objects may be read. This
2205 procedure must be called before any calls to @code{getservent}, and may
2206 also be called afterward to reset the service entry stream. If
2207 @var{stayopen} is supplied and is not @code{#f}, the database is not
2208 closed by subsequent @code{getservbyname} or @code{getservbyport} calls,
2209 possibly giving an efficiency gain.
2212 @deffn {Scheme Procedure} getservent
2213 Return the next entry from the services database.
2216 @deffn {Scheme Procedure} endservent
2217 Close the stream used by @code{getservent}. The return value is unspecified.
2220 @deffn {Scheme Procedure} setserv [stayopen]
2221 @deffnx {C Function} scm_setserv (stayopen)
2222 If @var{stayopen} is omitted, this is equivalent to @code{endservent}.
2223 Otherwise it is equivalent to @code{setservent stayopen}.
2226 @node Network Sockets and Communication
2227 @subsection Network Sockets and Communication
2229 Socket ports can be created using @code{socket} and @code{socketpair}.
2230 The ports are initially unbuffered, to make reading and writing to the
2231 same port more reliable. A buffer can be added to the port using
2232 @code{setvbuf}; see @ref{Ports and File Descriptors}.
2234 Most systems have limits on how many files and sockets can be open, so
2235 it's strongly recommended that socket ports be closed explicitly when
2236 no longer required (@pxref{Ports}).
2238 The convention used for ``host'' vs.@: ``network'' addresses is that
2239 addresses are always held in host order at the Scheme level. The
2240 procedures in this section automatically convert between host and
2241 network order when required. The arguments and return values are thus
2244 @deffn {Scheme Procedure} socket family style proto
2245 @deffnx {C Function} scm_socket (family, style, proto)
2246 Return a new socket port of the type specified by @var{family},
2247 @var{style} and @var{proto}. All three parameters are integers. The
2248 possible values for @var{family} are as follows, where supported by
2256 The possible values for @var{style} are as follows, again where
2257 supported by the system,
2264 @var{proto} can be obtained from a protocol name using
2265 @code{getprotobyname} (@pxref{Network Databases}). A value of zero
2266 means the default protocol, which is usually right.
2268 A socket cannot by used for communication until it has been connected
2269 somewhere, usually with either @code{connect} or @code{accept} below.
2272 @deffn {Scheme Procedure} socketpair family style proto
2273 @deffnx {C Function} scm_socketpair (family, style, proto)
2274 Return a pair, the @code{car} and @code{cdr} of which are two unnamed
2275 socket ports connected to each other. The connection is full-duplex,
2276 so data can be transferred in either direction between the two.
2278 @var{family}, @var{style} and @var{proto} are as per @code{socket}
2279 above. But many systems only support socket pairs in the
2280 @code{PF_UNIX} family. Zero is likely to be the only meaningful value
2284 @deffn {Scheme Procedure} getsockopt sock level optname
2285 @deffnx {C Function} scm_getsockopt (sock, level, optname)
2286 Return the value of a particular socket option for the socket
2287 port @var{sock}. @var{level} is an integer code for type of
2288 option being requested, e.g., @code{SOL_SOCKET} for
2289 socket-level options. @var{optname} is an integer code for the
2290 option required and should be specified using one of the
2291 symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc.
2293 The returned value is typically an integer but @code{SO_LINGER}
2294 returns a pair of integers.
2297 @deffn {Scheme Procedure} setsockopt sock level optname value
2298 @deffnx {C Function} scm_setsockopt (sock, level, optname, value)
2299 Set the value of a particular socket option for the socket
2300 port @var{sock}. @var{level} is an integer code for type of option
2301 being set, e.g., @code{SOL_SOCKET} for socket-level options.
2303 integer code for the option to set and should be specified using one of
2304 the symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc.
2305 @var{value} is the value to which the option should be set. For
2306 most options this must be an integer, but for @code{SO_LINGER} it must
2309 The return value is unspecified.
2312 @deffn {Scheme Procedure} shutdown sock how
2313 @deffnx {C Function} scm_shutdown (sock, how)
2314 Sockets can be closed simply by using @code{close-port}. The
2315 @code{shutdown} procedure allows reception or transmission on a
2316 connection to be shut down individually, according to the parameter
2321 Stop receiving data for this socket. If further data arrives, reject it.
2323 Stop trying to transmit data from this socket. Discard any
2324 data waiting to be sent. Stop looking for acknowledgement of
2325 data already sent; don't retransmit it if it is lost.
2327 Stop both reception and transmission.
2330 The return value is unspecified.
2333 @deffn {Scheme Procedure} connect sock fam address . args
2334 @deffnx {C Function} scm_connect (sock, fam, address, args)
2335 Initiate a connection from a socket using a specified address
2336 family to the address
2337 specified by @var{address} and possibly @var{args}.
2338 The format required for @var{address}
2339 and @var{args} depends on the family of the socket.
2341 For a socket of family @code{AF_UNIX},
2342 only @var{address} is specified and must be a string with the
2343 filename where the socket is to be created.
2345 For a socket of family @code{AF_INET},
2346 @var{address} must be an integer IPv4 host address and
2347 @var{args} must be a single integer port number.
2349 For a socket of family @code{AF_INET6},
2350 @var{address} must be an integer IPv6 host address and
2351 @var{args} may be up to three integers:
2352 port [flowinfo] [scope_id],
2353 where flowinfo and scope_id default to zero.
2355 The return value is unspecified.
2358 @deffn {Scheme Procedure} bind sock fam address . args
2359 @deffnx {C Function} scm_bind (sock, fam, address, args)
2360 Assign an address to the socket port @var{sock}.
2361 Generally this only needs to be done for server sockets,
2362 so they know where to look for incoming connections. A socket
2363 without an address will be assigned one automatically when it
2364 starts communicating.
2366 The format of @var{address} and @var{args} depends
2367 on the family of the socket.
2369 For a socket of family @code{AF_UNIX}, only @var{address}
2370 is specified and must be a string with the filename where
2371 the socket is to be created.
2373 For a socket of family @code{AF_INET}, @var{address}
2374 must be an integer IPv4 address and @var{args}
2375 must be a single integer port number.
2377 The values of the following variables can also be used for
2381 Allow connections from any address.
2384 @defvar INADDR_LOOPBACK
2385 The address of the local host using the loopback device.
2388 @defvar INADDR_BROADCAST
2389 The broadcast address on the local network.
2396 For a socket of family @code{AF_INET6}, @var{address}
2397 must be an integer IPv6 address and @var{args}
2398 may be up to three integers:
2399 port [flowinfo] [scope_id],
2400 where flowinfo and scope_id default to zero.
2402 The return value is unspecified.
2405 @deffn {Scheme Procedure} listen sock backlog
2406 @deffnx {C Function} scm_listen (sock, backlog)
2407 Enable @var{sock} to accept connection
2408 requests. @var{backlog} is an integer specifying
2409 the maximum length of the queue for pending connections.
2410 If the queue fills, new clients will fail to connect until
2411 the server calls @code{accept} to accept a connection from
2414 The return value is unspecified.
2417 @deffn {Scheme Procedure} accept sock
2418 @deffnx {C Function} scm_accept (sock)
2419 Accept a connection on a bound, listening socket.
2421 are no pending connections in the queue, wait until
2422 one is available unless the non-blocking option has been
2425 The return value is a
2426 pair in which the @acronym{CAR} is a new socket port for the
2428 the @acronym{CDR} is an object with address information about the
2429 client which initiated the connection.
2431 @var{sock} does not become part of the
2432 connection and will continue to accept new requests.
2435 The following functions take a socket address object, as returned
2436 by @code{accept} and other procedures, and return a selected component.
2438 @deffn {Scheme Procedure} sockaddr:fam sa
2439 The socket family, typically equal to the value of @code{AF_UNIX} or
2442 @deffn {Scheme Procedure} sockaddr:path sa
2443 If the socket family is @code{AF_UNIX}, returns the path of the
2444 filename the socket is based on.
2446 @deffn {Scheme Procedure} sockaddr:addr sa
2447 If the socket family is @code{AF_INET}, returns the Internet host
2450 @deffn {Scheme Procedure} sockaddr:port sa
2451 If the socket family is @code{AF_INET}, returns the Internet port
2455 @deffn {Scheme Procedure} getsockname sock
2456 @deffnx {C Function} scm_getsockname (sock)
2457 Return the address of @var{sock}, in the same form as the
2458 object returned by @code{accept}. On many systems the address
2459 of a socket in the @code{AF_FILE} namespace cannot be read.
2462 @deffn {Scheme Procedure} getpeername sock
2463 @deffnx {C Function} scm_getpeername (sock)
2464 Return the address that @var{sock}
2465 is connected to, in the same form as the object returned by
2466 @code{accept}. On many systems the address of a socket in the
2467 @code{AF_FILE} namespace cannot be read.
2470 @deffn {Scheme Procedure} recv! sock buf [flags]
2471 @deffnx {C Function} scm_recv (sock, buf, flags)
2472 Receive data from a socket port.
2473 @var{sock} must already
2474 be bound to the address from which data is to be received.
2475 @var{buf} is a string into which
2476 the data will be written. The size of @var{buf} limits
2478 data which can be received: in the case of packet
2479 protocols, if a packet larger than this limit is encountered
2481 will be irrevocably lost.
2485 @vindex MSG_DONTROUTE
2486 The optional @var{flags} argument is a value or bitwise OR of
2487 @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
2489 The value returned is the number of bytes read from the
2492 Note that the data is read directly from the socket file
2494 any unread buffered port data is ignored.
2497 @deffn {Scheme Procedure} send sock message [flags]
2498 @deffnx {C Function} scm_send (sock, message, flags)
2501 @vindex MSG_DONTROUTE
2502 Transmit the string @var{message} on a socket port @var{sock}.
2503 @var{sock} must already be bound to a destination address. The value
2504 returned is the number of bytes transmitted---it's possible for this
2505 to be less than the length of @var{message} if the socket is set to be
2506 non-blocking. The optional @var{flags} argument is a value or bitwise
2507 OR of @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
2509 Note that the data is written directly to the socket
2511 any unflushed buffered port data is ignored.
2514 @deffn {Scheme Procedure} recvfrom! sock str [flags [start [end]]]
2515 @deffnx {C Function} scm_recvfrom (sock, str, flags, start, end)
2516 Return data from the socket port @var{sock} and also
2517 information about where the data was received from.
2518 @var{sock} must already be bound to the address from which
2519 data is to be received. @code{str}, is a string into which the
2520 data will be written. The size of @var{str} limits the amount
2521 of data which can be received: in the case of packet protocols,
2522 if a packet larger than this limit is encountered then some
2523 data will be irrevocably lost.
2527 @vindex MSG_DONTROUTE
2528 The optional @var{flags} argument is a value or bitwise OR of
2529 @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
2531 The value returned is a pair: the @acronym{CAR} is the number of
2532 bytes read from the socket and the @acronym{CDR} an address object
2533 in the same form as returned by @code{accept}. The address
2534 will given as @code{#f} if not available, as is usually the
2535 case for stream sockets.
2537 The @var{start} and @var{end} arguments specify a substring of
2538 @var{str} to which the data should be written.
2540 Note that the data is read directly from the socket file
2541 descriptor: any unread buffered port data is ignored.
2544 @deffn {Scheme Procedure} sendto sock message fam address . args_and_flags
2545 @deffnx {C Function} scm_sendto (sock, message, fam, address, args_and_flags)
2546 Transmit the string @var{message} on the socket port
2548 destination address is specified using the @var{fam},
2550 @var{args_and_flags} arguments, in a similar way to the
2551 @code{connect} procedure. @var{args_and_flags} contains
2552 the usual connection arguments optionally followed by
2553 a flags argument, which is a value or
2554 bitwise OR of @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
2556 The value returned is the number of bytes transmitted --
2558 this to be less than the length of @var{message} if the
2560 set to be non-blocking.
2561 Note that the data is written directly to the socket
2563 any unflushed buffered port data is ignored.
2566 The following functions can be used to convert short and long integers
2567 between ``host'' and ``network'' order. Although the procedures above do
2568 this automatically for addresses, the conversion will still need to
2569 be done when sending or receiving encoded integer data from the network.
2571 @deffn {Scheme Procedure} htons value
2572 @deffnx {C Function} scm_htons (value)
2573 Convert a 16 bit quantity from host to network byte ordering.
2574 @var{value} is packed into 2 bytes, which are then converted
2575 and returned as a new integer.
2578 @deffn {Scheme Procedure} ntohs value
2579 @deffnx {C Function} scm_ntohs (value)
2580 Convert a 16 bit quantity from network to host byte ordering.
2581 @var{value} is packed into 2 bytes, which are then converted
2582 and returned as a new integer.
2585 @deffn {Scheme Procedure} htonl value
2586 @deffnx {C Function} scm_htonl (value)
2587 Convert a 32 bit quantity from host to network byte ordering.
2588 @var{value} is packed into 4 bytes, which are then converted
2589 and returned as a new integer.
2592 @deffn {Scheme Procedure} ntohl value
2593 @deffnx {C Function} scm_ntohl (value)
2594 Convert a 32 bit quantity from network to host byte ordering.
2595 @var{value} is packed into 4 bytes, which are then converted
2596 and returned as a new integer.
2599 These procedures are inconvenient to use at present, but consider:
2602 (define write-network-long
2603 (lambda (value port)
2604 (let ((v (make-uniform-vector 1 1 0)))
2605 (uniform-vector-set! v 0 (htonl value))
2606 (uniform-vector-write v port))))
2608 (define read-network-long
2610 (let ((v (make-uniform-vector 1 1 0)))
2611 (uniform-vector-read! v port)
2612 (ntohl (uniform-vector-ref v 0)))))
2616 @node Internet Socket Examples
2617 @subsection Network Socket Examples
2619 The following sections give examples of how to use network sockets.
2622 * Internet Socket Client::
2623 * Internet Socket Server::
2627 @node Internet Socket Client
2628 @subsubsection Internet Socket Client Example
2630 @cindex socket client example
2631 The following example demonstrates an Internet socket client.
2632 It connects to the HTTP daemon running on the local machine and
2633 returns the contents of the root index URL.
2636 (let ((s (socket AF_INET SOCK_STREAM 0)))
2637 (connect s AF_INET (inet-aton "127.0.0.1") 80)
2638 (display "GET / HTTP/1.0\r\n\r\n" s)
2640 (do ((line (read-line s) (read-line s)))
2641 ((eof-object? line))
2647 @node Internet Socket Server
2648 @subsubsection Internet Socket Server Example
2650 @cindex socket server example
2651 The following example shows a simple Internet server which listens on
2652 port 2904 for incoming connections and sends a greeting back to the
2656 (let ((s (socket AF_INET SOCK_STREAM 0)))
2657 (setsockopt s SOL_SOCKET SO_REUSEADDR 1)
2658 ;; @r{Specific address?}
2659 ;; @r{(bind s AF_INET (inet-aton "127.0.0.1") 2904)}
2660 (bind s AF_INET INADDR_ANY 2904)
2663 (simple-format #t "Listening for clients in pid: ~S" (getpid))
2667 (let* ((client-connection (accept s))
2668 (client-details (cdr client-connection))
2669 (client (car client-connection)))
2670 (simple-format #t "Got new client connection: ~S"
2673 (simple-format #t "Client address: ~S"
2675 (sockaddr:addr client-details)))
2677 ;; @r{Send back the greeting to the client port}
2678 (display "Hello client\r\n" client)
2683 @node System Identification
2684 @section System Identification
2686 This section lists the various procedures Guile provides for accessing
2687 information about the system it runs on.
2689 @deffn {Scheme Procedure} uname
2690 @deffnx {C Function} scm_uname ()
2691 Return an object with some information about the computer
2692 system the program is running on.
2694 The following procedures accept an object as returned by @code{uname}
2695 and return a selected component.
2697 @deffn {Scheme Procedure} utsname:sysname un
2698 The name of the operating system.
2700 @deffn {Scheme Procedure} utsname:nodename un
2701 The network name of the computer.
2703 @deffn {Scheme Procedure} utsname:release un
2704 The current release level of the operating system implementation.
2706 @deffn {Scheme Procedure} utsname:version un
2707 The current version level within the release of the operating system.
2709 @deffn {Scheme Procedure} utsname:machine un
2710 A description of the hardware.
2714 @deffn {Scheme Procedure} gethostname
2715 @deffnx {C Function} scm_gethostname ()
2716 Return the host name of the current processor.
2719 @deffn {Scheme Procedure} sethostname name
2720 @deffnx {C Function} scm_sethostname (name)
2721 Set the host name of the current processor to @var{name}. May
2722 only be used by the superuser. The return value is not
2726 @c FIXME::martin: Not in libguile!
2727 @deffn {Scheme Procedure} software-type
2728 Return a symbol describing the current platform's operating system.
2729 This may be one of @samp{AIX}, @samp{VMS}, @samp{UNIX},
2730 @samp{COHERENT}, @samp{WINDOWS}, @samp{MS-DOS}, @samp{OS/2},
2731 @samp{THINKC}, @samp{AMIGA}, @samp{ATARIST}, @samp{MACH}, or
2734 Note that most varieties of Unix are considered to be simply @samp{UNIX}.
2735 That is because when a program depends on features that are not present
2736 on every operating system, it is usually better to test for the presence
2737 or absence of that specific feature. The return value of
2738 @code{software-type} should only be used for this purpose when there is
2739 no other easy or unambiguous way of detecting such features.
2745 @deffn {Scheme Procedure} setlocale category [locale]
2746 @deffnx {C Function} scm_setlocale (category, locale)
2747 Get or set the current locale, used for various internationalizations.
2748 Locales are strings, such as @samp{sv_SE}.
2750 If @var{locale} is given then the locale for the given category is set
2751 and the new value returned. If @var{locale} is not given then the
2752 current value is returned. @var{category} should be one of the
2758 @defvarx LC_MESSAGES
2759 @defvarx LC_MONETARY
2764 A common usage is @samp{(setlocale LC_ALL "")}, which initializes all
2765 categories based on standard environment variables (@code{LANG} etc).
2766 For full details on categories and locale names @pxref{Locales,,
2767 Locales and Internationalization, libc, The GNU C Library Reference
2774 Please note that the procedures in this section are not suited for
2775 strong encryption, they are only interfaces to the well-known and
2776 common system library functions of the same name. They are just as good
2777 (or bad) as the underlying functions, so you should refer to your system
2778 documentation before using them.
2780 @deffn {Scheme Procedure} crypt key salt
2781 @deffnx {C Function} scm_crypt (key, salt)
2782 Encrypt @var{key} using @var{salt} as the salt value to the
2783 crypt(3) library call.
2786 Although @code{getpass} is not an encryption procedure per se, it
2787 appears here because it is often used in combination with @code{crypt}:
2789 @deffn {Scheme Procedure} getpass prompt
2790 @deffnx {C Function} scm_getpass (prompt)
2791 Display @var{prompt} to the standard error output and read
2792 a password from @file{/dev/tty}. If this file is not
2793 accessible, it reads from standard input. The password may be
2794 up to 127 characters in length. Additional characters and the
2795 terminating newline character are discarded. While reading
2796 the password, echoing and the generation of signals by special
2797 characters is disabled.