2 @chapter @acronym{POSIX} System Calls and Networking
5 * Conventions:: Conventions employed by the POSIX interface.
6 * Ports and File Descriptors:: Scheme ``ports'' and Unix file descriptors
7 have different representations.
8 * File System:: stat, chown, chmod, etc.
9 * User Information:: Retrieving a user's GECOS (/etc/passwd) entry.
10 * Time:: gettimeofday, localtime, strftime, etc.
11 * Runtime Environment:: Accessing and modifying Guile's environment.
12 * Processes:: getuid, getpid, etc.
13 * Signals:: sigaction, kill, pause, alarm, setitimer, etc.
14 * Terminals and Ptys:: ttyname, tcsetpgrp, etc.
15 * Pipes:: Communicating data between processes.
16 * Networking:: gethostbyaddr, getnetent, socket, bind, listen.
17 * System Identification:: Obtaining information about the system.
18 * Locales:: setlocale, etc.
23 @section @acronym{POSIX} Interface Conventions
25 These interfaces provide access to operating system facilities.
26 They provide a simple wrapping around the underlying C interfaces
27 to make usage from Scheme more convenient. They are also used
28 to implement the Guile port of scsh (@pxref{The Scheme shell (scsh)}).
30 Generally there is a single procedure for each corresponding Unix
31 facility. There are some exceptions, such as procedures implemented for
32 speed and convenience in Scheme with no primitive Unix equivalent,
33 e.g.@: @code{copy-file}.
35 The interfaces are intended as far as possible to be portable across
36 different versions of Unix. In some cases procedures which can't be
37 implemented on particular systems may become no-ops, or perform limited
38 actions. In other cases they may throw errors.
40 General naming conventions are as follows:
44 The Scheme name is often identical to the name of the underlying Unix
47 Underscores in Unix procedure names are converted to hyphens.
49 Procedures which destructively modify Scheme data have exclamation
50 marks appended, e.g., @code{recv!}.
52 Predicates (returning only @code{#t} or @code{#f}) have question marks
53 appended, e.g., @code{access?}.
55 Some names are changed to avoid conflict with dissimilar interfaces
56 defined by scsh, e.g., @code{primitive-fork}.
58 Unix preprocessor names such as @code{EPERM} or @code{R_OK} are converted
59 to Scheme variables of the same name (underscores are not replaced
63 Unexpected conditions are generally handled by raising exceptions.
64 There are a few procedures which return a special value if they don't
65 succeed, e.g., @code{getenv} returns @code{#f} if it the requested
66 string is not found in the environment. These cases are noted in
69 For ways to deal with exceptions, see @ref{Exceptions}.
71 Errors which the C library would report by returning a null pointer or
72 through some other means are reported by raising a @code{system-error}
73 exception. The value of the Unix @code{errno} variable is available
74 in the data passed by the exception.
76 It can be extracted with the function @code{system-error-errno}:
82 (mkdir "/this-ought-to-fail-if-I'm-not-root"))
84 (let ((errno (system-error-errno stuff)))
87 (display "You're not allowed to do that."))
89 (display "Already exists."))
91 (display (strerror errno))))
95 @node Ports and File Descriptors
96 @section Ports and File Descriptors
98 Conventions generally follow those of scsh, @ref{The Scheme shell (scsh)}.
100 File ports are implemented using low-level operating system I/O
101 facilities, with optional buffering to improve efficiency; see
104 Note that some procedures (e.g., @code{recv!}) will accept ports as
105 arguments, but will actually operate directly on the file descriptor
106 underlying the port. Any port buffering is ignored, including the
107 buffer which implements @code{peek-char} and @code{unread-char}.
109 The @code{force-output} and @code{drain-input} procedures can be used
110 to clear the buffers.
112 Each open file port has an associated operating system file descriptor.
113 File descriptors are generally not useful in Scheme programs; however
114 they may be needed when interfacing with foreign code and the Unix
117 A file descriptor can be extracted from a port and a new port can be
118 created from a file descriptor. However a file descriptor is just an
119 integer and the garbage collector doesn't recognize it as a reference
120 to the port. If all other references to the port were dropped, then
121 it's likely that the garbage collector would free the port, with the
122 side-effect of closing the file descriptor prematurely.
124 To assist the programmer in avoiding this problem, each port has an
125 associated @dfn{revealed count} which can be used to keep track of how many
126 times the underlying file descriptor has been stored in other places.
127 If a port's revealed count is greater than zero, the file descriptor
128 will not be closed when the port is garbage collected. A programmer
129 can therefore ensure that the revealed count will be greater than
130 zero if the file descriptor is needed elsewhere.
132 For the simple case where a file descriptor is ``imported'' once to become
133 a port, it does not matter if the file descriptor is closed when the
134 port is garbage collected. There is no need to maintain a revealed
135 count. Likewise when ``exporting'' a file descriptor to the external
136 environment, setting the revealed count is not required provided the
137 port is kept open (i.e., is pointed to by a live Scheme binding) while
138 the file descriptor is in use.
140 To correspond with traditional Unix behaviour, three file descriptors
141 (0, 1, and 2) are automatically imported when a program starts up and
142 assigned to the initial values of the current/standard input, output,
143 and error ports, respectively. The revealed count for each is
144 initially set to one, so that dropping references to one of these
145 ports will not result in its garbage collection: it could be retrieved
146 with @code{fdopen} or @code{fdes->ports}.
148 @deffn {Scheme Procedure} port-revealed port
149 @deffnx {C Function} scm_port_revealed (port)
150 Return the revealed count for @var{port}.
153 @deffn {Scheme Procedure} set-port-revealed! port rcount
154 @deffnx {C Function} scm_set_port_revealed_x (port, rcount)
155 Sets the revealed count for a @var{port} to @var{rcount}.
156 The return value is unspecified.
159 @deffn {Scheme Procedure} fileno port
160 @deffnx {C Function} scm_fileno (port)
161 Return the integer file descriptor underlying @var{port}. Does
162 not change its revealed count.
165 @deffn {Scheme Procedure} port->fdes port
166 Returns the integer file descriptor underlying @var{port}. As a
167 side effect the revealed count of @var{port} is incremented.
170 @deffn {Scheme Procedure} fdopen fdes modes
171 @deffnx {C Function} scm_fdopen (fdes, modes)
172 Return a new port based on the file descriptor @var{fdes}. Modes are
173 given by the string @var{modes}. The revealed count of the port is
174 initialized to zero. The @var{modes} string is the same as that
175 accepted by @code{open-file} (@pxref{File Ports, open-file}).
178 @deffn {Scheme Procedure} fdes->ports fd
179 @deffnx {C Function} scm_fdes_to_ports (fd)
180 Return a list of existing ports which have @var{fdes} as an
181 underlying file descriptor, without changing their revealed
185 @deffn {Scheme Procedure} fdes->inport fdes
186 Returns an existing input port which has @var{fdes} as its underlying file
187 descriptor, if one exists, and increments its revealed count.
188 Otherwise, returns a new input port with a revealed count of 1.
191 @deffn {Scheme Procedure} fdes->outport fdes
192 Returns an existing output port which has @var{fdes} as its underlying file
193 descriptor, if one exists, and increments its revealed count.
194 Otherwise, returns a new output port with a revealed count of 1.
197 @deffn {Scheme Procedure} primitive-move->fdes port fd
198 @deffnx {C Function} scm_primitive_move_to_fdes (port, fd)
199 Moves the underlying file descriptor for @var{port} to the integer
200 value @var{fdes} without changing the revealed count of @var{port}.
201 Any other ports already using this descriptor will be automatically
202 shifted to new descriptors and their revealed counts reset to zero.
203 The return value is @code{#f} if the file descriptor already had the
204 required value or @code{#t} if it was moved.
207 @deffn {Scheme Procedure} move->fdes port fdes
208 Moves the underlying file descriptor for @var{port} to the integer
209 value @var{fdes} and sets its revealed count to one. Any other ports
210 already using this descriptor will be automatically
211 shifted to new descriptors and their revealed counts reset to zero.
212 The return value is unspecified.
215 @deffn {Scheme Procedure} release-port-handle port
216 Decrements the revealed count for a port.
219 @deffn {Scheme Procedure} fsync object
220 @deffnx {C Function} scm_fsync (object)
221 Copies any unwritten data for the specified output file descriptor to disk.
222 If @var{port/fd} is a port, its buffer is flushed before the underlying
223 file descriptor is fsync'd.
224 The return value is unspecified.
227 @deffn {Scheme Procedure} open path flags [mode]
228 @deffnx {C Function} scm_open (path, flags, mode)
229 Open the file named by @var{path} for reading and/or writing.
230 @var{flags} is an integer specifying how the file should be opened.
231 @var{mode} is an integer specifying the permission bits of the file,
232 if it needs to be created, before the umask (@pxref{Processes}) is
233 applied. The default is 666 (Unix itself has no default).
235 @var{flags} can be constructed by combining variables using @code{logior}.
239 Open the file read-only.
242 Open the file write-only.
245 Open the file read/write.
248 Append to the file instead of truncating.
251 Create the file if it does not already exist.
254 @xref{File Status Flags,,,libc,The GNU C Library Reference Manual},
255 for additional flags.
258 @deffn {Scheme Procedure} open-fdes path flags [mode]
259 @deffnx {C Function} scm_open_fdes (path, flags, mode)
260 Similar to @code{open} but return a file descriptor instead of
264 @deffn {Scheme Procedure} close fd_or_port
265 @deffnx {C Function} scm_close (fd_or_port)
266 Similar to @code{close-port} (@pxref{Closing, close-port}),
267 but also works on file descriptors. A side
268 effect of closing a file descriptor is that any ports using that file
269 descriptor are moved to a different file descriptor and have
270 their revealed counts set to zero.
273 @deffn {Scheme Procedure} close-fdes fd
274 @deffnx {C Function} scm_close_fdes (fd)
275 A simple wrapper for the @code{close} system call. Close file
276 descriptor @var{fd}, which must be an integer. Unlike @code{close},
277 the file descriptor will be closed even if a port is using it. The
278 return value is unspecified.
281 @deffn {Scheme Procedure} unread-char char [port]
282 @deffnx {C Function} scm_unread_char (char, port)
283 Place @var{char} in @var{port} so that it will be read by the next
284 read operation on that port. If called multiple times, the unread
285 characters will be read again in ``last-in, first-out'' order (i.e.@:
286 a stack). If @var{port} is not supplied, the current input port is
290 @deffn {Scheme Procedure} unread-string str port
291 Place the string @var{str} in @var{port} so that its characters will be
292 read in subsequent read operations. If called multiple times, the
293 unread characters will be read again in last-in first-out order. If
294 @var{port} is not supplied, the current-input-port is used.
297 @deffn {Scheme Procedure} pipe
298 @deffnx {C Function} scm_pipe ()
299 Return a newly created pipe: a pair of ports which are linked
300 together on the local machine. The @acronym{CAR} is the input
301 port and the @acronym{CDR} is the output port. Data written (and
302 flushed) to the output port can be read from the input port.
303 Pipes are commonly used for communication with a newly forked
304 child process. The need to flush the output port can be
305 avoided by making it unbuffered using @code{setvbuf}.
308 A write of up to @code{PIPE_BUF} many bytes to a pipe is atomic,
309 meaning when done it goes into the pipe instantaneously and as a
310 contiguous block (@pxref{Pipe Atomicity,, Atomicity of Pipe I/O, libc,
311 The GNU C Library Reference Manual}).
314 Note that the output port is likely to block if too much data has been
315 written but not yet read from the input port. Typically the capacity
316 is @code{PIPE_BUF} bytes.
319 The next group of procedures perform a @code{dup2}
320 system call, if @var{newfd} (an
321 integer) is supplied, otherwise a @code{dup}. The file descriptor to be
322 duplicated can be supplied as an integer or contained in a port. The
323 type of value returned varies depending on which procedure is used.
325 All procedures also have the side effect when performing @code{dup2} that any
326 ports using @var{newfd} are moved to a different file descriptor and have
327 their revealed counts set to zero.
329 @deffn {Scheme Procedure} dup->fdes fd_or_port [fd]
330 @deffnx {C Function} scm_dup_to_fdes (fd_or_port, fd)
331 Return a new integer file descriptor referring to the open file
332 designated by @var{fd_or_port}, which must be either an open
333 file port or a file descriptor.
336 @deffn {Scheme Procedure} dup->inport port/fd [newfd]
337 Returns a new input port using the new file descriptor.
340 @deffn {Scheme Procedure} dup->outport port/fd [newfd]
341 Returns a new output port using the new file descriptor.
344 @deffn {Scheme Procedure} dup port/fd [newfd]
345 Returns a new port if @var{port/fd} is a port, with the same mode as the
346 supplied port, otherwise returns an integer file descriptor.
349 @deffn {Scheme Procedure} dup->port port/fd mode [newfd]
350 Returns a new port using the new file descriptor. @var{mode} supplies a
351 mode string for the port (@pxref{File Ports, open-file}).
354 @deffn {Scheme Procedure} duplicate-port port modes
355 Returns a new port which is opened on a duplicate of the file
356 descriptor underlying @var{port}, with mode string @var{modes}
357 as for @ref{File Ports, open-file}. The two ports
358 will share a file position and file status flags.
360 Unexpected behaviour can result if both ports are subsequently used
361 and the original and/or duplicate ports are buffered.
362 The mode string can include @code{0} to obtain an unbuffered duplicate
365 This procedure is equivalent to @code{(dup->port @var{port} @var{modes})}.
368 @deffn {Scheme Procedure} redirect-port old new
369 @deffnx {C Function} scm_redirect_port (old, new)
370 This procedure takes two ports and duplicates the underlying file
371 descriptor from @var{old-port} into @var{new-port}. The
372 current file descriptor in @var{new-port} will be closed.
373 After the redirection the two ports will share a file position
374 and file status flags.
376 The return value is unspecified.
378 Unexpected behaviour can result if both ports are subsequently used
379 and the original and/or duplicate ports are buffered.
381 This procedure does not have any side effects on other ports or
385 @deffn {Scheme Procedure} dup2 oldfd newfd
386 @deffnx {C Function} scm_dup2 (oldfd, newfd)
387 A simple wrapper for the @code{dup2} system call.
388 Copies the file descriptor @var{oldfd} to descriptor
389 number @var{newfd}, replacing the previous meaning
390 of @var{newfd}. Both @var{oldfd} and @var{newfd} must
392 Unlike for @code{dup->fdes} or @code{primitive-move->fdes}, no attempt
393 is made to move away ports which are using @var{newfd}.
394 The return value is unspecified.
397 @deffn {Scheme Procedure} port-mode port
398 Return the port modes associated with the open port @var{port}.
399 These will not necessarily be identical to the modes used when
400 the port was opened, since modes such as ``append'' which are
401 used only during port creation are not retained.
404 @deffn {Scheme Procedure} port-for-each proc
405 @deffnx {C Function} scm_port_for_each (SCM proc)
406 @deffnx {C Function} scm_c_port_for_each (void (*proc)(void *, SCM), void *data)
407 Apply @var{proc} to each port in the Guile port table
408 (FIXME: what is the Guile port table?)
409 in turn. The return value is unspecified. More specifically,
410 @var{proc} is applied exactly once to every port that exists in the
411 system at the time @code{port-for-each} is invoked. Changes to the
412 port table while @code{port-for-each} is running have no effect as far
413 as @code{port-for-each} is concerned.
415 The C function @code{scm_port_for_each} takes a Scheme procedure
416 encoded as a @code{SCM} value, while @code{scm_c_port_for_each} takes
417 a pointer to a C function and passes along a arbitrary @var{data}
421 @deffn {Scheme Procedure} setvbuf port mode [size]
422 @deffnx {C Function} scm_setvbuf (port, mode, size)
423 Set the buffering mode for @var{port}. @var{mode} can be:
432 block buffered, using a newly allocated buffer of @var{size} bytes.
433 If @var{size} is omitted, a default size will be used.
437 @deffn {Scheme Procedure} fcntl object cmd [value]
438 @deffnx {C Function} scm_fcntl (object, cmd, value)
439 Apply @var{command} to the specified file descriptor or the underlying
440 file descriptor of the specified port. @var{value} is an optional
443 Values for @var{command} are:
446 Duplicate a file descriptor
449 Get flags associated with the file descriptor.
452 Set flags associated with the file descriptor to @var{value}.
455 Get flags associated with the open file.
458 Set flags associated with the open file to @var{value}
461 Get the process ID of a socket's owner, for @code{SIGIO} signals.
464 Set the process that owns a socket to @var{value}, for @code{SIGIO} signals.
467 The value used to indicate the ``close on exec'' flag with @code{F_GETFL} or
472 @deffn {Scheme Procedure} flock file operation
473 @deffnx {C Function} scm_flock (file, operation)
474 Apply or remove an advisory lock on an open file.
475 @var{operation} specifies the action to be done:
478 Shared lock. More than one process may hold a shared lock
479 for a given file at a given time.
482 Exclusive lock. Only one process may hold an exclusive lock
483 for a given file at a given time.
489 Don't block when locking. May be specified by bitwise OR'ing
490 it to one of the other operations.
493 The return value is not specified. @var{file} may be an open
494 file descriptor or an open file descriptor port.
497 @deffn {Scheme Procedure} select reads writes excepts [secs [usecs]]
498 @deffnx {C Function} scm_select (reads, writes, excepts, secs, usecs)
499 This procedure has a variety of uses: waiting for the ability
500 to provide input, accept output, or the existence of
501 exceptional conditions on a collection of ports or file
502 descriptors, or waiting for a timeout to occur.
503 It also returns if interrupted by a signal.
505 @var{reads}, @var{writes} and @var{excepts} can be lists or
506 vectors, with each member a port or a file descriptor.
507 The value returned is a list of three corresponding
508 lists or vectors containing only the members which meet the
509 specified requirement. The ability of port buffers to
510 provide input or accept output is taken into account.
511 Ordering of the input lists or vectors is not preserved.
513 The optional arguments @var{secs} and @var{usecs} specify the
514 timeout. Either @var{secs} can be specified alone, as
515 either an integer or a real number, or both @var{secs} and
516 @var{usecs} can be specified as integers, in which case
517 @var{usecs} is an additional timeout expressed in
518 microseconds. If @var{secs} is omitted or is @code{#f} then
519 select will wait for as long as it takes for one of the other
520 conditions to be satisfied.
522 The scsh version of @code{select} differs as follows:
523 Only vectors are accepted for the first three arguments.
524 The @var{usecs} argument is not supported.
525 Multiple values are returned instead of a list.
526 Duplicates in the input vectors appear only once in output.
527 An additional @code{select!} interface is provided.
533 These procedures allow querying and setting file system attributes
535 permissions, sizes and types of files); deleting, copying, renaming and
536 linking files; creating and removing directories and querying their
537 contents; syncing the file system and creating special files.
539 @deffn {Scheme Procedure} access? path how
540 @deffnx {C Function} scm_access (path, how)
541 Return @code{#t} if @var{path} corresponds to an existing file
542 and the current process has the type of access specified by
543 @var{how}, otherwise @code{#f}. @var{how} should be specified
544 using the values of the variables listed below. Multiple
545 values can be combined using a bitwise or, in which case
546 @code{#t} will only be returned if all accesses are granted.
548 Permissions are checked using the real id of the current
549 process, not the effective id, although it's the effective id
550 which determines whether the access would actually be granted.
553 test for read permission.
556 test for write permission.
559 test for execute permission.
562 test for existence of the file.
567 @deffn {Scheme Procedure} stat object
568 @deffnx {C Function} scm_stat (object)
569 Return an object containing various information about the file
570 determined by @var{obj}. @var{obj} can be a string containing
571 a file name or a port or integer file descriptor which is open
572 on a file (in which case @code{fstat} is used as the underlying
575 The object returned by @code{stat} can be passed as a single
576 parameter to the following procedures, all of which return
579 @deffn {Scheme Procedure} stat:dev st
580 The device containing the file.
582 @deffn {Scheme Procedure} stat:ino st
583 The file serial number, which distinguishes this file from all
584 other files on the same device.
586 @deffn {Scheme Procedure} stat:mode st
587 The mode of the file. This includes file type information and
588 the file permission bits. See @code{stat:type} and
589 @code{stat:perms} below.
591 @deffn {Scheme Procedure} stat:nlink st
592 The number of hard links to the file.
594 @deffn {Scheme Procedure} stat:uid st
595 The user ID of the file's owner.
597 @deffn {Scheme Procedure} stat:gid st
598 The group ID of the file.
600 @deffn {Scheme Procedure} stat:rdev st
601 Device ID; this entry is defined only for character or block special
602 files. On some systems this field is not available at all, in which
603 case @code{stat:rdev} returns @code{#f}.
605 @deffn {Scheme Procedure} stat:size st
606 The size of a regular file in bytes.
608 @deffn {Scheme Procedure} stat:atime st
609 The last access time for the file.
611 @deffn {Scheme Procedure} stat:mtime st
612 The last modification time for the file.
614 @deffn {Scheme Procedure} stat:ctime st
615 The last modification time for the attributes of the file.
617 @deffn {Scheme Procedure} stat:blksize st
618 The optimal block size for reading or writing the file, in bytes. On
619 some systems this field is not available, in which case
620 @code{stat:blksize} returns a sensible suggested block size.
622 @deffn {Scheme Procedure} stat:blocks st
623 The amount of disk space that the file occupies measured in units of
624 512 byte blocks. On some systems this field is not available, in
625 which case @code{stat:blocks} returns @code{#f}.
628 In addition, the following procedures return the information
629 from stat:mode in a more convenient form:
631 @deffn {Scheme Procedure} stat:type st
632 A symbol representing the type of file. Possible values are
633 @samp{regular}, @samp{directory}, @samp{symlink},
634 @samp{block-special}, @samp{char-special}, @samp{fifo}, @samp{socket},
637 @deffn {Scheme Procedure} stat:perms st
638 An integer representing the access permission bits.
642 @deffn {Scheme Procedure} lstat str
643 @deffnx {C Function} scm_lstat (str)
644 Similar to @code{stat}, but does not follow symbolic links, i.e.,
645 it will return information about a symbolic link itself, not the
646 file it points to. @var{path} must be a string.
649 @deffn {Scheme Procedure} readlink path
650 @deffnx {C Function} scm_readlink (path)
651 Return the value of the symbolic link named by @var{path} (a
652 string), i.e., the file that the link points to.
657 @deffn {Scheme Procedure} chown object owner group
658 @deffnx {C Function} scm_chown (object, owner, group)
659 Change the ownership and group of the file referred to by @var{object}
660 to the integer values @var{owner} and @var{group}. @var{object} can
661 be a string containing a file name or, if the platform supports
662 @code{fchown} (@pxref{File Owner,,,libc,The GNU C Library Reference
663 Manual}), a port or integer file descriptor which is open on the file.
664 The return value is unspecified.
666 If @var{object} is a symbolic link, either the
667 ownership of the link or the ownership of the referenced file will be
668 changed depending on the operating system (lchown is
669 unsupported at present). If @var{owner} or @var{group} is specified
670 as @code{-1}, then that ID is not changed.
674 @deffn {Scheme Procedure} chmod object mode
675 @deffnx {C Function} scm_chmod (object, mode)
676 Changes the permissions of the file referred to by @var{obj}.
677 @var{obj} can be a string containing a file name or a port or integer file
678 descriptor which is open on a file (in which case @code{fchmod} is used
679 as the underlying system call).
681 the new permissions as a decimal number, e.g., @code{(chmod "foo" #o755)}.
682 The return value is unspecified.
685 @deffn {Scheme Procedure} utime pathname [actime [modtime]]
686 @deffnx {C Function} scm_utime (pathname, actime, modtime)
687 @code{utime} sets the access and modification times for the
688 file named by @var{path}. If @var{actime} or @var{modtime} is
689 not supplied, then the current time is used. @var{actime} and
690 @var{modtime} must be integer time values as returned by the
691 @code{current-time} procedure.
693 (utime "foo" (- (current-time) 3600))
695 will set the access time to one hour in the past and the
696 modification time to the current time.
700 @deffn {Scheme Procedure} delete-file str
701 @deffnx {C Function} scm_delete_file (str)
702 Deletes (or ``unlinks'') the file whose path is specified by
706 @deffn {Scheme Procedure} copy-file oldfile newfile
707 @deffnx {C Function} scm_copy_file (oldfile, newfile)
708 Copy the file specified by @var{oldfile} to @var{newfile}.
709 The return value is unspecified.
713 @deffn {Scheme Procedure} rename-file oldname newname
714 @deffnx {C Function} scm_rename (oldname, newname)
715 Renames the file specified by @var{oldname} to @var{newname}.
716 The return value is unspecified.
719 @deffn {Scheme Procedure} link oldpath newpath
720 @deffnx {C Function} scm_link (oldpath, newpath)
721 Creates a new name @var{newpath} in the file system for the
722 file named by @var{oldpath}. If @var{oldpath} is a symbolic
723 link, the link may or may not be followed depending on the
727 @deffn {Scheme Procedure} symlink oldpath newpath
728 @deffnx {C Function} scm_symlink (oldpath, newpath)
729 Create a symbolic link named @var{newpath} with the value (i.e., pointing to)
730 @var{oldpath}. The return value is unspecified.
733 @deffn {Scheme Procedure} mkdir path [mode]
734 @deffnx {C Function} scm_mkdir (path, mode)
735 Create a new directory named by @var{path}. If @var{mode} is omitted
736 then the permissions of the directory file are set using the current
737 umask (@pxref{Processes}). Otherwise they are set to the decimal
738 value specified with @var{mode}. The return value is unspecified.
741 @deffn {Scheme Procedure} rmdir path
742 @deffnx {C Function} scm_rmdir (path)
743 Remove the existing directory named by @var{path}. The directory must
744 be empty for this to succeed. The return value is unspecified.
747 @deffn {Scheme Procedure} opendir dirname
748 @deffnx {C Function} scm_opendir (dirname)
749 Open the directory specified by @var{dirname} and return a directory
753 @deffn {Scheme Procedure} directory-stream? object
754 @deffnx {C Function} scm_directory_stream_p (object)
755 Return a boolean indicating whether @var{object} is a directory
756 stream as returned by @code{opendir}.
759 @deffn {Scheme Procedure} readdir stream
760 @deffnx {C Function} scm_readdir (stream)
761 Return (as a string) the next directory entry from the directory stream
762 @var{stream}. If there is no remaining entry to be read then the
763 end of file object is returned.
766 @deffn {Scheme Procedure} rewinddir stream
767 @deffnx {C Function} scm_rewinddir (stream)
768 Reset the directory port @var{stream} so that the next call to
769 @code{readdir} will return the first directory entry.
772 @deffn {Scheme Procedure} closedir stream
773 @deffnx {C Function} scm_closedir (stream)
774 Close the directory stream @var{stream}.
775 The return value is unspecified.
778 Here is an example showing how to display all the entries in a
782 (define dir (opendir "/usr/lib"))
783 (do ((entry (readdir dir) (readdir dir)))
784 ((eof-object? entry))
785 (display entry)(newline))
789 @deffn {Scheme Procedure} sync
790 @deffnx {C Function} scm_sync ()
791 Flush the operating system disk buffers.
792 The return value is unspecified.
795 @deffn {Scheme Procedure} mknod path type perms dev
796 @deffnx {C Function} scm_mknod (path, type, perms, dev)
797 Creates a new special file, such as a file corresponding to a device.
798 @var{path} specifies the name of the file. @var{type} should be one
799 of the following symbols: @samp{regular}, @samp{directory},
800 @samp{symlink}, @samp{block-special}, @samp{char-special},
801 @samp{fifo}, or @samp{socket}. @var{perms} (an integer) specifies the
802 file permissions. @var{dev} (an integer) specifies which device the
803 special file refers to. Its exact interpretation depends on the kind
804 of special file being created.
808 (mknod "/dev/fd0" 'block-special #o660 (+ (* 2 256) 2))
811 The return value is unspecified.
814 @deffn {Scheme Procedure} tmpnam
815 @deffnx {C Function} scm_tmpnam ()
816 Return a name in the file system that does not match any
817 existing file. However there is no guarantee that another
818 process will not create the file after @code{tmpnam} is called.
819 Care should be taken if opening the file, e.g., use the
820 @code{O_EXCL} open flag or use @code{mkstemp!} instead.
823 @deffn {Scheme Procedure} mkstemp! tmpl
824 @deffnx {C Function} scm_mkstemp (tmpl)
825 Create a new unique file in the file system and returns a new
826 buffered port open for reading and writing to the file.
827 @var{tmpl} is a string specifying where the file should be
828 created: it must end with @samp{XXXXXX} and will be changed in
829 place to return the name of the temporary file.
832 @deffn {Scheme Procedure} dirname filename
833 @deffnx {C Function} scm_dirname (filename)
834 Return the directory name component of the file name
835 @var{filename}. If @var{filename} does not contain a directory
836 component, @code{.} is returned.
839 @deffn {Scheme Procedure} basename filename [suffix]
840 @deffnx {C Function} scm_basename (filename, suffix)
841 Return the base name of the file name @var{filename}. The
842 base name is the file name without any directory components.
843 If @var{suffix} is provided, and is equal to the end of
844 @var{basename}, it is removed also.
847 (basename "/tmp/test.xml" ".xml")
853 @node User Information
854 @section User Information
856 The facilities in this section provide an interface to the user and
858 They should be used with care since they are not reentrant.
860 The following functions accept an object representing user information
861 and return a selected component:
863 @deffn {Scheme Procedure} passwd:name pw
864 The name of the userid.
866 @deffn {Scheme Procedure} passwd:passwd pw
867 The encrypted passwd.
869 @deffn {Scheme Procedure} passwd:uid pw
872 @deffn {Scheme Procedure} passwd:gid pw
875 @deffn {Scheme Procedure} passwd:gecos pw
878 @deffn {Scheme Procedure} passwd:dir pw
881 @deffn {Scheme Procedure} passwd:shell pw
886 @deffn {Scheme Procedure} getpwuid uid
887 Look up an integer userid in the user database.
890 @deffn {Scheme Procedure} getpwnam name
891 Look up a user name string in the user database.
894 @deffn {Scheme Procedure} setpwent
895 Initializes a stream used by @code{getpwent} to read from the user database.
896 The next use of @code{getpwent} will return the first entry. The
897 return value is unspecified.
900 @deffn {Scheme Procedure} getpwent
901 Return the next entry in the user database, using the stream set by
905 @deffn {Scheme Procedure} endpwent
906 Closes the stream used by @code{getpwent}. The return value is unspecified.
909 @deffn {Scheme Procedure} setpw [arg]
910 @deffnx {C Function} scm_setpwent (arg)
911 If called with a true argument, initialize or reset the password data
912 stream. Otherwise, close the stream. The @code{setpwent} and
913 @code{endpwent} procedures are implemented on top of this.
916 @deffn {Scheme Procedure} getpw [user]
917 @deffnx {C Function} scm_getpwuid (user)
918 Look up an entry in the user database. @var{obj} can be an integer,
919 a string, or omitted, giving the behaviour of getpwuid, getpwnam
920 or getpwent respectively.
923 The following functions accept an object representing group information
924 and return a selected component:
926 @deffn {Scheme Procedure} group:name gr
929 @deffn {Scheme Procedure} group:passwd gr
930 The encrypted group password.
932 @deffn {Scheme Procedure} group:gid gr
935 @deffn {Scheme Procedure} group:mem gr
936 A list of userids which have this group as a supplementary group.
940 @deffn {Scheme Procedure} getgrgid gid
941 Look up an integer group id in the group database.
944 @deffn {Scheme Procedure} getgrnam name
945 Look up a group name in the group database.
948 @deffn {Scheme Procedure} setgrent
949 Initializes a stream used by @code{getgrent} to read from the group database.
950 The next use of @code{getgrent} will return the first entry.
951 The return value is unspecified.
954 @deffn {Scheme Procedure} getgrent
955 Return the next entry in the group database, using the stream set by
959 @deffn {Scheme Procedure} endgrent
960 Closes the stream used by @code{getgrent}.
961 The return value is unspecified.
964 @deffn {Scheme Procedure} setgr [arg]
965 @deffnx {C Function} scm_setgrent (arg)
966 If called with a true argument, initialize or reset the group data
967 stream. Otherwise, close the stream. The @code{setgrent} and
968 @code{endgrent} procedures are implemented on top of this.
971 @deffn {Scheme Procedure} getgr [name]
972 @deffnx {C Function} scm_getgrgid (name)
973 Look up an entry in the group database. @var{obj} can be an integer,
974 a string, or omitted, giving the behaviour of getgrgid, getgrnam
975 or getgrent respectively.
978 In addition to the accessor procedures for the user database, the
979 following shortcut procedures are also available.
981 @deffn {Scheme Procedure} cuserid
982 @deffnx {C Function} scm_cuserid ()
983 Return a string containing a user name associated with the
984 effective user id of the process. Return @code{#f} if this
985 information cannot be obtained.
988 @deffn {Scheme Procedure} getlogin
989 @deffnx {C Function} scm_getlogin ()
990 Return a string containing the name of the user logged in on
991 the controlling terminal of the process, or @code{#f} if this
992 information cannot be obtained.
999 @deffn {Scheme Procedure} current-time
1000 @deffnx {C Function} scm_current_time ()
1001 Return the number of seconds since 1970-01-01 00:00:00 @acronym{UTC},
1002 excluding leap seconds.
1005 @deffn {Scheme Procedure} gettimeofday
1006 @deffnx {C Function} scm_gettimeofday ()
1007 Return a pair containing the number of seconds and microseconds
1008 since 1970-01-01 00:00:00 @acronym{UTC}, excluding leap seconds. Note:
1009 whether true microsecond resolution is available depends on the
1013 The following procedures either accept an object representing a broken down
1014 time and return a selected component, or accept an object representing
1015 a broken down time and a value and set the component to the value.
1016 The numbers in parentheses give the usual range.
1018 @deffn {Scheme Procedure} tm:sec tm
1019 @deffnx {Scheme Procedure} set-tm:sec tm val
1022 @deffn {Scheme Procedure} tm:min tm
1023 @deffnx {Scheme Procedure} set-tm:min tm val
1026 @deffn {Scheme Procedure} tm:hour tm
1027 @deffnx {Scheme Procedure} set-tm:hour tm val
1030 @deffn {Scheme Procedure} tm:mday tm
1031 @deffnx {Scheme Procedure} set-tm:mday tm val
1032 Day of the month (1-31).
1034 @deffn {Scheme Procedure} tm:mon tm
1035 @deffnx {Scheme Procedure} set-tm:mon tm val
1038 @deffn {Scheme Procedure} tm:year tm
1039 @deffnx {Scheme Procedure} set-tm:year tm val
1040 Year (70-), the year minus 1900.
1042 @deffn {Scheme Procedure} tm:wday tm
1043 @deffnx {Scheme Procedure} set-tm:wday tm val
1044 Day of the week (0-6) with Sunday represented as 0.
1046 @deffn {Scheme Procedure} tm:yday tm
1047 @deffnx {Scheme Procedure} set-tm:yday tm val
1048 Day of the year (0-364, 365 in leap years).
1050 @deffn {Scheme Procedure} tm:isdst tm
1051 @deffnx {Scheme Procedure} set-tm:isdst tm val
1052 Daylight saving indicator (0 for ``no'', greater than 0 for ``yes'', less than
1055 @deffn {Scheme Procedure} tm:gmtoff tm
1056 @deffnx {Scheme Procedure} set-tm:gmtoff tm val
1057 Time zone offset in seconds west of @acronym{UTC} (-46800 to 43200).
1059 @deffn {Scheme Procedure} tm:zone tm
1060 @deffnx {Scheme Procedure} set-tm:zone tm val
1061 Time zone label (a string), not necessarily unique.
1065 @deffn {Scheme Procedure} localtime time [zone]
1066 @deffnx {C Function} scm_localtime (time, zone)
1067 Return an object representing the broken down components of
1068 @var{time}, an integer like the one returned by
1069 @code{current-time}. The time zone for the calculation is
1070 optionally specified by @var{zone} (a string), otherwise the
1071 @env{TZ} environment variable or the system default is used.
1074 @deffn {Scheme Procedure} gmtime time
1075 @deffnx {C Function} scm_gmtime (time)
1076 Return an object representing the broken down components of
1077 @var{time}, an integer like the one returned by
1078 @code{current-time}. The values are calculated for @acronym{UTC}.
1081 @deffn {Scheme Procedure} mktime sbd-time [zone]
1082 @deffnx {C Function} scm_mktime (sbd_time, zone)
1083 @var{sbd-time} is an object representing broken down time and
1084 @code{zone} is an optional time zone specifier (otherwise the @env{TZ}
1085 environment variable or the system default is used).
1087 Returns a pair: the @acronym{CAR} is a corresponding integer time
1088 value like that returned by @code{current-time}; the @acronym{CDR} is
1089 a broken down time object, similar to @var{sbd-time} but with
1090 normalized values; i.e.@: with corrected @code{tm:wday} and
1091 @code{tm:yday} fields.
1094 @deffn {Scheme Procedure} tzset
1095 @deffnx {C Function} scm_tzset ()
1096 Initialize the timezone from the @env{TZ} environment variable
1097 or the system default. It's not usually necessary to call this procedure
1098 since it's done automatically by other procedures that depend on the
1102 @deffn {Scheme Procedure} strftime format stime
1103 @deffnx {C Function} scm_strftime (format, stime)
1104 Formats a time specification @var{time} using @var{template}. @var{time}
1105 is an object with time components in the form returned by @code{localtime}
1106 or @code{gmtime}. @var{template} is a string which can include formatting
1107 specifications introduced by a @samp{%} character. The formatting of
1108 month and day names is dependent on the current locale. The value returned
1109 is the formatted string.
1110 @xref{Formatting Date and Time, , , libc, The GNU C Library Reference Manual}.
1113 (strftime "%c" (localtime (current-time)))
1114 @result{} "Mon Mar 11 20:17:43 2002"
1118 @deffn {Scheme Procedure} strptime format string
1119 @deffnx {C Function} scm_strptime (format, string)
1120 Performs the reverse action to @code{strftime}, parsing
1121 @var{string} according to the specification supplied in
1122 @var{template}. The interpretation of month and day names is
1123 dependent on the current locale. The value returned is a pair.
1124 The @acronym{CAR} has an object with time components
1125 in the form returned by @code{localtime} or @code{gmtime},
1126 but the time zone components
1127 are not usefully set.
1128 The @acronym{CDR} reports the number of characters from @var{string}
1129 which were used for the conversion.
1132 @defvar internal-time-units-per-second
1133 The value of this variable is the number of time units per second
1134 reported by the following procedures.
1137 @deffn {Scheme Procedure} times
1138 @deffnx {C Function} scm_times ()
1139 Return an object with information about real and processor
1140 time. The following procedures accept such an object as an
1141 argument and return a selected component:
1143 @deffn {Scheme Procedure} tms:clock tms
1144 The current real time, expressed as time units relative to an
1147 @deffn {Scheme Procedure} tms:utime tms
1148 The CPU time units used by the calling process.
1150 @deffn {Scheme Procedure} tms:stime tms
1151 The CPU time units used by the system on behalf of the calling
1154 @deffn {Scheme Procedure} tms:cutime tms
1155 The CPU time units used by terminated child processes of the
1156 calling process, whose status has been collected (e.g., using
1159 @deffn {Scheme Procedure} tms:cstime tms
1160 Similarly, the CPU times units used by the system on behalf of
1161 terminated child processes.
1165 @deffn {Scheme Procedure} get-internal-real-time
1166 @deffnx {C Function} scm_get_internal_real_time ()
1167 Return the number of time units since the interpreter was
1171 @deffn {Scheme Procedure} get-internal-run-time
1172 @deffnx {C Function} scm_get_internal_run_time ()
1173 Return the number of time units of processor time used by the
1174 interpreter. Both @emph{system} and @emph{user} time are
1175 included but subprocesses are not.
1178 @node Runtime Environment
1179 @section Runtime Environment
1181 @deffn {Scheme Procedure} program-arguments
1182 @deffnx {Scheme Procedure} command-line
1183 @deffnx {C Function} scm_program_arguments ()
1184 Return the list of command line arguments passed to Guile, as a list of
1185 strings. The list includes the invoked program name, which is usually
1186 @code{"guile"}, but excludes switches and parameters for command line
1187 options like @code{-e} and @code{-l}.
1190 @deffn {Scheme Procedure} getenv nam
1191 @deffnx {C Function} scm_getenv (nam)
1192 Looks up the string @var{name} in the current environment. The return
1193 value is @code{#f} unless a string of the form @code{NAME=VALUE} is
1194 found, in which case the string @code{VALUE} is returned.
1197 @deffn {Scheme Procedure} setenv name value
1198 Modifies the environment of the current process, which is
1199 also the default environment inherited by child processes.
1201 If @var{value} is @code{#f}, then @var{name} is removed from the
1202 environment. Otherwise, the string @var{name}=@var{value} is added
1203 to the environment, replacing any existing string with name matching
1206 The return value is unspecified.
1209 @deffn {Scheme Procedure} unsetenv name
1210 Remove variable @var{name} from the environment. The
1211 name can not contain a @samp{=} character.
1214 @deffn {Scheme Procedure} environ [env]
1215 @deffnx {C Function} scm_environ (env)
1216 If @var{env} is omitted, return the current environment (in the
1217 Unix sense) as a list of strings. Otherwise set the current
1218 environment, which is also the default environment for child
1219 processes, to the supplied list of strings. Each member of
1220 @var{env} should be of the form @var{NAME}=@var{VALUE} and values of
1221 @var{NAME} should not be duplicated. If @var{env} is supplied
1222 then the return value is unspecified.
1225 @deffn {Scheme Procedure} putenv str
1226 @deffnx {C Function} scm_putenv (str)
1227 Modifies the environment of the current process, which is
1228 also the default environment inherited by child processes.
1230 If @var{string} is of the form @code{NAME=VALUE} then it will be written
1231 directly into the environment, replacing any existing environment string
1233 name matching @code{NAME}. If @var{string} does not contain an equal
1234 sign, then any existing string with name matching @var{string} will
1237 The return value is unspecified.
1245 @deffn {Scheme Procedure} chdir str
1246 @deffnx {C Function} scm_chdir (str)
1247 Change the current working directory to @var{path}.
1248 The return value is unspecified.
1252 @deffn {Scheme Procedure} getcwd
1253 @deffnx {C Function} scm_getcwd ()
1254 Return the name of the current working directory.
1257 @deffn {Scheme Procedure} umask [mode]
1258 @deffnx {C Function} scm_umask (mode)
1259 If @var{mode} is omitted, returns a decimal number representing the
1260 current file creation mask. Otherwise the file creation mask is set
1261 to @var{mode} and the previous value is returned. @xref{Setting
1262 Permissions,,Assigning File Permissions,libc,The GNU C Library
1263 Reference Manual}, for more on how to use umasks.
1265 E.g., @code{(umask #o022)} sets the mask to octal 22/decimal 18.
1268 @deffn {Scheme Procedure} chroot path
1269 @deffnx {C Function} scm_chroot (path)
1270 Change the root directory to that specified in @var{path}.
1271 This directory will be used for path names beginning with
1272 @file{/}. The root directory is inherited by all children
1273 of the current process. Only the superuser may change the
1277 @deffn {Scheme Procedure} getpid
1278 @deffnx {C Function} scm_getpid ()
1279 Return an integer representing the current process ID.
1282 @deffn {Scheme Procedure} getgroups
1283 @deffnx {C Function} scm_getgroups ()
1284 Return a vector of integers representing the current
1285 supplementary group IDs.
1288 @deffn {Scheme Procedure} getppid
1289 @deffnx {C Function} scm_getppid ()
1290 Return an integer representing the process ID of the parent
1294 @deffn {Scheme Procedure} getuid
1295 @deffnx {C Function} scm_getuid ()
1296 Return an integer representing the current real user ID.
1299 @deffn {Scheme Procedure} getgid
1300 @deffnx {C Function} scm_getgid ()
1301 Return an integer representing the current real group ID.
1304 @deffn {Scheme Procedure} geteuid
1305 @deffnx {C Function} scm_geteuid ()
1306 Return an integer representing the current effective user ID.
1307 If the system does not support effective IDs, then the real ID
1308 is returned. @code{(provided? 'EIDs)} reports whether the
1309 system supports effective IDs.
1312 @deffn {Scheme Procedure} getegid
1313 @deffnx {C Function} scm_getegid ()
1314 Return an integer representing the current effective group ID.
1315 If the system does not support effective IDs, then the real ID
1316 is returned. @code{(provided? 'EIDs)} reports whether the
1317 system supports effective IDs.
1320 @deffn {Scheme Procedure} setuid id
1321 @deffnx {C Function} scm_setuid (id)
1322 Sets both the real and effective user IDs to the integer @var{id}, provided
1323 the process has appropriate privileges.
1324 The return value is unspecified.
1327 @deffn {Scheme Procedure} setgid id
1328 @deffnx {C Function} scm_setgid (id)
1329 Sets both the real and effective group IDs to the integer @var{id}, provided
1330 the process has appropriate privileges.
1331 The return value is unspecified.
1334 @deffn {Scheme Procedure} seteuid id
1335 @deffnx {C Function} scm_seteuid (id)
1336 Sets the effective user ID to the integer @var{id}, provided the process
1337 has appropriate privileges. If effective IDs are not supported, the
1338 real ID is set instead---@code{(provided? 'EIDs)} reports whether the
1339 system supports effective IDs.
1340 The return value is unspecified.
1343 @deffn {Scheme Procedure} setegid id
1344 @deffnx {C Function} scm_setegid (id)
1345 Sets the effective group ID to the integer @var{id}, provided the process
1346 has appropriate privileges. If effective IDs are not supported, the
1347 real ID is set instead---@code{(provided? 'EIDs)} reports whether the
1348 system supports effective IDs.
1349 The return value is unspecified.
1352 @deffn {Scheme Procedure} getpgrp
1353 @deffnx {C Function} scm_getpgrp ()
1354 Return an integer representing the current process group ID.
1355 This is the @acronym{POSIX} definition, not @acronym{BSD}.
1358 @deffn {Scheme Procedure} setpgid pid pgid
1359 @deffnx {C Function} scm_setpgid (pid, pgid)
1360 Move the process @var{pid} into the process group @var{pgid}. @var{pid} or
1361 @var{pgid} must be integers: they can be zero to indicate the ID of the
1363 Fails on systems that do not support job control.
1364 The return value is unspecified.
1367 @deffn {Scheme Procedure} setsid
1368 @deffnx {C Function} scm_setsid ()
1369 Creates a new session. The current process becomes the session leader
1370 and is put in a new process group. The process will be detached
1371 from its controlling terminal if it has one.
1372 The return value is an integer representing the new process group ID.
1375 @deffn {Scheme Procedure} waitpid pid [options]
1376 @deffnx {C Function} scm_waitpid (pid, options)
1377 This procedure collects status information from a child process which
1378 has terminated or (optionally) stopped. Normally it will
1379 suspend the calling process until this can be done. If more than one
1380 child process is eligible then one will be chosen by the operating system.
1382 The value of @var{pid} determines the behaviour:
1385 @item @var{pid} greater than 0
1386 Request status information from the specified child process.
1387 @item @var{pid} equal to -1 or @code{WAIT_ANY}
1389 Request status information for any child process.
1390 @item @var{pid} equal to 0 or @code{WAIT_MYPGRP}
1392 Request status information for any child process in the current process
1394 @item @var{pid} less than -1
1395 Request status information for any child process whose process group ID
1396 is @minus{}@var{pid}.
1399 The @var{options} argument, if supplied, should be the bitwise OR of the
1400 values of zero or more of the following variables:
1403 Return immediately even if there are no child processes to be collected.
1407 Report status information for stopped processes as well as terminated
1411 The return value is a pair containing:
1415 The process ID of the child process, or 0 if @code{WNOHANG} was
1416 specified and no process was collected.
1418 The integer status value.
1423 functions can be used to decode the process status code returned
1426 @deffn {Scheme Procedure} status:exit-val status
1427 @deffnx {C Function} scm_status_exit_val (status)
1428 Return the exit status value, as would be set if a process
1429 ended normally through a call to @code{exit} or @code{_exit},
1430 if any, otherwise @code{#f}.
1433 @deffn {Scheme Procedure} status:term-sig status
1434 @deffnx {C Function} scm_status_term_sig (status)
1435 Return the signal number which terminated the process, if any,
1436 otherwise @code{#f}.
1439 @deffn {Scheme Procedure} status:stop-sig status
1440 @deffnx {C Function} scm_status_stop_sig (status)
1441 Return the signal number which stopped the process, if any,
1442 otherwise @code{#f}.
1445 @deffn {Scheme Procedure} system [cmd]
1446 @deffnx {C Function} scm_system (cmd)
1447 Execute @var{cmd} using the operating system's ``command
1448 processor''. Under Unix this is usually the default shell
1449 @code{sh}. The value returned is @var{cmd}'s exit status as
1450 returned by @code{waitpid}, which can be interpreted using the
1453 If @code{system} is called without arguments, return a boolean
1454 indicating whether the command processor is available.
1457 @deffn {Scheme Procedure} primitive-exit [status]
1458 @deffnx {C Function} scm_primitive_exit (status)
1459 Terminate the current process without unwinding the Scheme stack.
1460 This is would typically be useful after a fork. The exit status
1461 is @var{status} if supplied, otherwise zero.
1464 @deffn {Scheme Procedure} execl filename . args
1465 @deffnx {C Function} scm_execl (filename, args)
1466 Executes the file named by @var{path} as a new process image.
1467 The remaining arguments are supplied to the process; from a C program
1468 they are accessible as the @code{argv} argument to @code{main}.
1469 Conventionally the first @var{arg} is the same as @var{path}.
1470 All arguments must be strings.
1472 If @var{arg} is missing, @var{path} is executed with a null
1473 argument list, which may have system-dependent side-effects.
1475 This procedure is currently implemented using the @code{execv} system
1476 call, but we call it @code{execl} because of its Scheme calling interface.
1479 @deffn {Scheme Procedure} execlp filename . args
1480 @deffnx {C Function} scm_execlp (filename, args)
1481 Similar to @code{execl}, however if
1482 @var{filename} does not contain a slash
1483 then the file to execute will be located by searching the
1484 directories listed in the @code{PATH} environment variable.
1486 This procedure is currently implemented using the @code{execvp} system
1487 call, but we call it @code{execlp} because of its Scheme calling interface.
1490 @deffn {Scheme Procedure} execle filename env . args
1491 @deffnx {C Function} scm_execle (filename, env, args)
1492 Similar to @code{execl}, but the environment of the new process is
1493 specified by @var{env}, which must be a list of strings as returned by the
1494 @code{environ} procedure.
1496 This procedure is currently implemented using the @code{execve} system
1497 call, but we call it @code{execle} because of its Scheme calling interface.
1500 @deffn {Scheme Procedure} primitive-fork
1501 @deffnx {C Function} scm_fork ()
1502 Creates a new ``child'' process by duplicating the current ``parent'' process.
1503 In the child the return value is 0. In the parent the return value is
1504 the integer process ID of the child.
1506 This procedure has been renamed from @code{fork} to avoid a naming conflict
1510 @deffn {Scheme Procedure} nice incr
1511 @deffnx {C Function} scm_nice (incr)
1512 Increment the priority of the current process by @var{incr}. A higher
1513 priority value means that the process runs less often.
1514 The return value is unspecified.
1517 @deffn {Scheme Procedure} setpriority which who prio
1518 @deffnx {C Function} scm_setpriority (which, who, prio)
1519 @vindex PRIO_PROCESS
1522 Set the scheduling priority of the process, process group
1523 or user, as indicated by @var{which} and @var{who}. @var{which}
1524 is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
1525 or @code{PRIO_USER}, and @var{who} is interpreted relative to
1526 @var{which} (a process identifier for @code{PRIO_PROCESS},
1527 process group identifier for @code{PRIO_PGRP}, and a user
1528 identifier for @code{PRIO_USER}. A zero value of @var{who}
1529 denotes the current process, process group, or user.
1530 @var{prio} is a value in the range [@minus{}20,20]. The default
1531 priority is 0; lower priorities (in numerical terms) cause more
1532 favorable scheduling. Sets the priority of all of the specified
1533 processes. Only the super-user may lower priorities. The return
1534 value is not specified.
1537 @deffn {Scheme Procedure} getpriority which who
1538 @deffnx {C Function} scm_getpriority (which, who)
1539 @vindex PRIO_PROCESS
1542 Return the scheduling priority of the process, process group
1543 or user, as indicated by @var{which} and @var{who}. @var{which}
1544 is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
1545 or @code{PRIO_USER}, and @var{who} should be interpreted depending on
1546 @var{which} (a process identifier for @code{PRIO_PROCESS},
1547 process group identifier for @code{PRIO_PGRP}, and a user
1548 identifier for @code{PRIO_USER}). A zero value of @var{who}
1549 denotes the current process, process group, or user. Return
1550 the highest priority (lowest numerical value) of any of the
1551 specified processes.
1558 Procedures to raise, handle and wait for signals.
1560 @deffn {Scheme Procedure} kill pid sig
1561 @deffnx {C Function} scm_kill (pid, sig)
1562 Sends a signal to the specified process or group of processes.
1564 @var{pid} specifies the processes to which the signal is sent:
1567 @item @var{pid} greater than 0
1568 The process whose identifier is @var{pid}.
1569 @item @var{pid} equal to 0
1570 All processes in the current process group.
1571 @item @var{pid} less than -1
1572 The process group whose identifier is -@var{pid}
1573 @item @var{pid} equal to -1
1574 If the process is privileged, all processes except for some special
1575 system processes. Otherwise, all processes with the current effective
1579 @var{sig} should be specified using a variable corresponding to
1580 the Unix symbolic name, e.g.,
1590 A full list of signals on the GNU system may be found in @ref{Standard
1591 Signals,,,libc,The GNU C Library Reference Manual}.
1594 @deffn {Scheme Procedure} raise sig
1595 @deffnx {C Function} scm_raise (sig)
1596 Sends a specified signal @var{sig} to the current process, where
1597 @var{sig} is as described for the @code{kill} procedure.
1600 @deffn {Scheme Procedure} sigaction signum [handler [flags [thread]]]
1601 @deffnx {C Function} scm_sigaction (signum, handler, flags)
1602 @deffnx {C Function} scm_sigaction_for_thread (signum, handler, flags, thread)
1603 Install or report the signal handler for a specified signal.
1605 @var{signum} is the signal number, which can be specified using the value
1606 of variables such as @code{SIGINT}.
1608 If @var{handler} is omitted, @code{sigaction} returns a pair: the
1609 @acronym{CAR} is the current signal hander, which will be either an
1610 integer with the value @code{SIG_DFL} (default action) or
1611 @code{SIG_IGN} (ignore), or the Scheme procedure which handles the
1612 signal, or @code{#f} if a non-Scheme procedure handles the signal.
1613 The @acronym{CDR} contains the current @code{sigaction} flags for the
1616 If @var{handler} is provided, it is installed as the new handler for
1617 @var{signum}. @var{handler} can be a Scheme procedure taking one
1618 argument, or the value of @code{SIG_DFL} (default action) or
1619 @code{SIG_IGN} (ignore), or @code{#f} to restore whatever signal handler
1620 was installed before @code{sigaction} was first used. When a scheme
1621 procedure has been specified, that procedure will run in the given
1622 @var{thread}. When no thread has been given, the thread that made this
1623 call to @code{sigaction} is used.
1625 Flags can optionally be specified for the new handler (@code{SA_RESTART}
1626 will always be added if it's available and the system is using
1627 restartable system calls.) The return value is a pair with information
1628 about the old handler as described above.
1630 This interface does not provide access to the ``signal blocking''
1631 facility. Maybe this is not needed, since the thread support may
1632 provide solutions to the problem of consistent access to data
1636 @deffn {Scheme Procedure} restore-signals
1637 @deffnx {C Function} scm_restore_signals ()
1638 Return all signal handlers to the values they had before any call to
1639 @code{sigaction} was made. The return value is unspecified.
1642 @deffn {Scheme Procedure} alarm i
1643 @deffnx {C Function} scm_alarm (i)
1644 Set a timer to raise a @code{SIGALRM} signal after the specified
1645 number of seconds (an integer). It's advisable to install a signal
1647 @code{SIGALRM} beforehand, since the default action is to terminate
1650 The return value indicates the time remaining for the previous alarm,
1651 if any. The new value replaces the previous alarm. If there was
1652 no previous alarm, the return value is zero.
1655 @deffn {Scheme Procedure} pause
1656 @deffnx {C Function} scm_pause ()
1657 Pause the current process (thread?) until a signal arrives whose
1658 action is to either terminate the current process or invoke a
1659 handler procedure. The return value is unspecified.
1662 @deffn {Scheme Procedure} sleep i
1663 @deffnx {C Function} scm_sleep (i)
1664 Wait for the given number of seconds (an integer) or until a signal
1665 arrives. The return value is zero if the time elapses or the number
1666 of seconds remaining otherwise.
1669 @deffn {Scheme Procedure} usleep i
1670 @deffnx {C Function} scm_usleep (i)
1671 Sleep for @var{i} microseconds. @code{usleep} is not available on
1672 all platforms. [FIXME: so what happens when it isn't?]
1675 @deffn {Scheme Procedure} setitimer which_timer interval_seconds interval_microseconds value_seconds value_microseconds
1676 @deffnx {C Function} scm_setitimer (which_timer, interval_seconds, interval_microseconds, value_seconds, value_microseconds)
1677 Set the timer specified by @var{which_timer} according to the given
1678 @var{interval_seconds}, @var{interval_microseconds},
1679 @var{value_seconds}, and @var{value_microseconds} values.
1681 Return information about the timer's previous setting.
1683 The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
1684 and @code{ITIMER_PROF}.
1686 The return value will be a list of two cons pairs representing the
1687 current state of the given timer. The first pair is the seconds and
1688 microseconds of the timer @code{it_interval}, and the second pair is
1689 the seconds and microseconds of the timer @code{it_value}.
1692 @deffn {Scheme Procedure} getitimer which_timer
1693 @deffnx {C Function} scm_getitimer (which_timer)
1694 Return information about the timer specified by @var{which_timer}.
1696 The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
1697 and @code{ITIMER_PROF}.
1699 The return value will be a list of two cons pairs representing the
1700 current state of the given timer. The first pair is the seconds and
1701 microseconds of the timer @code{it_interval}, and the second pair is
1702 the seconds and microseconds of the timer @code{it_value}.
1706 @node Terminals and Ptys
1707 @section Terminals and Ptys
1709 @deffn {Scheme Procedure} isatty? port
1710 @deffnx {C Function} scm_isatty_p (port)
1711 Return @code{#t} if @var{port} is using a serial non--file
1712 device, otherwise @code{#f}.
1715 @deffn {Scheme Procedure} ttyname port
1716 @deffnx {C Function} scm_ttyname (port)
1717 Return a string with the name of the serial terminal device
1718 underlying @var{port}.
1721 @deffn {Scheme Procedure} ctermid
1722 @deffnx {C Function} scm_ctermid ()
1723 Return a string containing the file name of the controlling
1724 terminal for the current process.
1727 @deffn {Scheme Procedure} tcgetpgrp port
1728 @deffnx {C Function} scm_tcgetpgrp (port)
1729 Return the process group ID of the foreground process group
1730 associated with the terminal open on the file descriptor
1731 underlying @var{port}.
1733 If there is no foreground process group, the return value is a
1734 number greater than 1 that does not match the process group ID
1735 of any existing process group. This can happen if all of the
1736 processes in the job that was formerly the foreground job have
1737 terminated, and no other job has yet been moved into the
1741 @deffn {Scheme Procedure} tcsetpgrp port pgid
1742 @deffnx {C Function} scm_tcsetpgrp (port, pgid)
1743 Set the foreground process group ID for the terminal used by the file
1744 descriptor underlying @var{port} to the integer @var{pgid}.
1746 must be a member of the same session as @var{pgid} and must have the same
1747 controlling terminal. The return value is unspecified.
1753 The following procedures provide an interface to the @code{popen} and
1754 @code{pclose} system routines. The code is in a separate ``popen''
1758 (use-modules (ice-9 popen))
1762 @deffn {Scheme Procedure} open-pipe command modes
1763 Executes the shell command @var{command} (a string) in a subprocess.
1764 A pipe to the process is created and returned. @var{modes} specifies
1765 whether an input or output pipe to the process is created: it should
1766 be the value of @code{OPEN_READ} or @code{OPEN_WRITE}.
1769 @deffn {Scheme Procedure} open-input-pipe command
1770 Equivalent to @code{open-pipe} with mode @code{OPEN_READ}.
1773 (read-line (open-input-pipe "date"))
1774 @result{} "Mon Mar 11 20:10:44 GMT 2002"
1777 @result{} (24160 . 0)
1781 @deffn {Scheme Procedure} open-output-pipe command
1782 Equivalent to @code{open-pipe} with mode @code{OPEN_WRITE}.
1786 @deffn {Scheme Procedure} close-pipe port
1787 Closes the pipe created by @code{open-pipe}, then waits for the process
1788 to terminate and returns its status value, @xref{Processes, waitpid}, for
1789 information on how to interpret this value.
1791 @code{close-port} (@pxref{Closing, close-port}) can also be used to
1792 close a pipe, but doesn't return the status.
1799 * Network Address Conversion::
1800 * Network Databases::
1801 * Network Sockets and Communication::
1802 * Internet Socket Examples::
1805 @node Network Address Conversion
1806 @subsection Network Address Conversion
1808 This section describes procedures which convert internet addresses
1809 between numeric and string formats.
1811 @subsubsection IPv4 Address Conversion
1813 @deffn {Scheme Procedure} inet-aton address
1814 @deffnx {C Function} scm_inet_aton (address)
1815 Convert an IPv4 Internet address from printable string
1816 (dotted decimal notation) to an integer. E.g.,
1819 (inet-aton "127.0.0.1") @result{} 2130706433
1823 @deffn {Scheme Procedure} inet-ntoa inetid
1824 @deffnx {C Function} scm_inet_ntoa (inetid)
1825 Convert an IPv4 Internet address to a printable
1826 (dotted decimal notation) string. E.g.,
1829 (inet-ntoa 2130706433) @result{} "127.0.0.1"
1833 @deffn {Scheme Procedure} inet-netof address
1834 @deffnx {C Function} scm_inet_netof (address)
1835 Return the network number part of the given IPv4
1836 Internet address. E.g.,
1839 (inet-netof 2130706433) @result{} 127
1843 @deffn {Scheme Procedure} inet-lnaof address
1844 @deffnx {C Function} scm_lnaof (address)
1845 Return the local-address-with-network part of the given
1846 IPv4 Internet address, using the obsolete class A/B/C system.
1850 (inet-lnaof 2130706433) @result{} 1
1854 @deffn {Scheme Procedure} inet-makeaddr net lna
1855 @deffnx {C Function} scm_inet_makeaddr (net, lna)
1856 Make an IPv4 Internet address by combining the network number
1857 @var{net} with the local-address-within-network number
1861 (inet-makeaddr 127 1) @result{} 2130706433
1865 @subsubsection IPv6 Address Conversion
1867 @deffn {Scheme Procedure} inet-ntop family address
1868 @deffnx {C Function} scm_inet_ntop (family, address)
1869 Convert a network address into a printable string.
1870 Note that unlike the C version of this function,
1871 the input is an integer with normal host byte ordering.
1872 @var{family} can be @code{AF_INET} or @code{AF_INET6}. E.g.,
1875 (inet-ntop AF_INET 2130706433) @result{} "127.0.0.1"
1876 (inet-ntop AF_INET6 (- (expt 2 128) 1)) @result{}
1877 ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
1881 @deffn {Scheme Procedure} inet-pton family address
1882 @deffnx {C Function} scm_inet_pton (family, address)
1883 Convert a string containing a printable network address to
1884 an integer address. Note that unlike the C version of this
1886 the result is an integer with normal host byte ordering.
1887 @var{family} can be @code{AF_INET} or @code{AF_INET6}. E.g.,
1890 (inet-pton AF_INET "127.0.0.1") @result{} 2130706433
1891 (inet-pton AF_INET6 "::1") @result{} 1
1896 @node Network Databases
1897 @subsection Network Databases
1899 This section describes procedures which query various network databases.
1900 Care should be taken when using the database routines since they are not
1903 @subsubsection The Host Database
1905 A @dfn{host object} is a structure that represents what is known about a
1906 network host, and is the usual way of representing a system's network
1907 identity inside software.
1909 The following functions accept a host object and return a selected
1912 @deffn {Scheme Procedure} hostent:name host
1913 The ``official'' hostname for @var{host}.
1915 @deffn {Scheme Procedure} hostent:aliases host
1916 A list of aliases for @var{host}.
1918 @deffn {Scheme Procedure} hostent:addrtype host
1919 The host address type. For hosts with Internet addresses, this will
1920 return @code{AF_INET}.
1922 @deffn {Scheme Procedure} hostent:length host
1923 The length of each address for @var{host}, in bytes.
1925 @deffn {Scheme Procedure} hostent:addr-list host
1926 The list of network addresses associated with @var{host}.
1929 The following procedures are used to search the host database:
1931 @deffn {Scheme Procedure} gethost [host]
1932 @deffnx {Scheme Procedure} gethostbyname hostname
1933 @deffnx {Scheme Procedure} gethostbyaddr address
1934 @deffnx {C Function} scm_gethost (host)
1935 Look up a host by name or address, returning a host object. The
1936 @code{gethost} procedure will accept either a string name or an integer
1937 address; if given no arguments, it behaves like @code{gethostent} (see
1938 below). If a name or address is supplied but the address can not be
1939 found, an error will be thrown to one of the keys:
1940 @code{host-not-found}, @code{try-again}, @code{no-recovery} or
1941 @code{no-data}, corresponding to the equivalent @code{h_error} values.
1942 Unusual conditions may result in errors thrown to the
1943 @code{system-error} or @code{misc_error} keys.
1946 (gethost "www.gnu.org")
1947 @result{} #("www.gnu.org" () 2 4 (3353880842))
1949 (gethostbyname "www.emacs.org")
1950 @result{} #("emacs.org" ("www.emacs.org") 2 4 (1073448978))
1954 The following procedures may be used to step through the host
1955 database from beginning to end.
1957 @deffn {Scheme Procedure} sethostent [stayopen]
1958 Initialize an internal stream from which host objects may be read. This
1959 procedure must be called before any calls to @code{gethostent}, and may
1960 also be called afterward to reset the host entry stream. If
1961 @var{stayopen} is supplied and is not @code{#f}, the database is not
1962 closed by subsequent @code{gethostbyname} or @code{gethostbyaddr} calls,
1963 possibly giving an efficiency gain.
1966 @deffn {Scheme Procedure} gethostent
1967 Return the next host object from the host database, or @code{#f} if
1968 there are no more hosts to be found (or an error has been encountered).
1969 This procedure may not be used before @code{sethostent} has been called.
1972 @deffn {Scheme Procedure} endhostent
1973 Close the stream used by @code{gethostent}. The return value is unspecified.
1976 @deffn {Scheme Procedure} sethost [stayopen]
1977 @deffnx {C Function} scm_sethost (stayopen)
1978 If @var{stayopen} is omitted, this is equivalent to @code{endhostent}.
1979 Otherwise it is equivalent to @code{sethostent stayopen}.
1981 @subsubsection The Network Database
1983 The following functions accept an object representing a network
1984 and return a selected component:
1986 @deffn {Scheme Procedure} netent:name net
1987 The ``official'' network name.
1989 @deffn {Scheme Procedure} netent:aliases net
1990 A list of aliases for the network.
1992 @deffn {Scheme Procedure} netent:addrtype net
1993 The type of the network number. Currently, this returns only
1996 @deffn {Scheme Procedure} netent:net net
2000 The following procedures are used to search the network database:
2002 @deffn {Scheme Procedure} getnet [net]
2003 @deffnx {Scheme Procedure} getnetbyname net-name
2004 @deffnx {Scheme Procedure} getnetbyaddr net-number
2005 @deffnx {C Function} scm_getnet (net)
2006 Look up a network by name or net number in the network database. The
2007 @var{net-name} argument must be a string, and the @var{net-number}
2008 argument must be an integer. @code{getnet} will accept either type of
2009 argument, behaving like @code{getnetent} (see below) if no arguments are
2013 The following procedures may be used to step through the network
2014 database from beginning to end.
2016 @deffn {Scheme Procedure} setnetent [stayopen]
2017 Initialize an internal stream from which network objects may be read. This
2018 procedure must be called before any calls to @code{getnetent}, and may
2019 also be called afterward to reset the net entry stream. If
2020 @var{stayopen} is supplied and is not @code{#f}, the database is not
2021 closed by subsequent @code{getnetbyname} or @code{getnetbyaddr} calls,
2022 possibly giving an efficiency gain.
2025 @deffn {Scheme Procedure} getnetent
2026 Return the next entry from the network database.
2029 @deffn {Scheme Procedure} endnetent
2030 Close the stream used by @code{getnetent}. The return value is unspecified.
2033 @deffn {Scheme Procedure} setnet [stayopen]
2034 @deffnx {C Function} scm_setnet (stayopen)
2035 If @var{stayopen} is omitted, this is equivalent to @code{endnetent}.
2036 Otherwise it is equivalent to @code{setnetent stayopen}.
2039 @subsubsection The Protocol Database
2041 The following functions accept an object representing a protocol
2042 and return a selected component:
2044 @deffn {Scheme Procedure} protoent:name protocol
2045 The ``official'' protocol name.
2047 @deffn {Scheme Procedure} protoent:aliases protocol
2048 A list of aliases for the protocol.
2050 @deffn {Scheme Procedure} protoent:proto protocol
2051 The protocol number.
2054 The following procedures are used to search the protocol database:
2056 @deffn {Scheme Procedure} getproto [protocol]
2057 @deffnx {Scheme Procedure} getprotobyname name
2058 @deffnx {Scheme Procedure} getprotobynumber number
2059 @deffnx {C Function} scm_getproto (protocol)
2060 Look up a network protocol by name or by number. @code{getprotobyname}
2061 takes a string argument, and @code{getprotobynumber} takes an integer
2062 argument. @code{getproto} will accept either type, behaving like
2063 @code{getprotoent} (see below) if no arguments are supplied.
2066 The following procedures may be used to step through the protocol
2067 database from beginning to end.
2069 @deffn {Scheme Procedure} setprotoent [stayopen]
2070 Initialize an internal stream from which protocol objects may be read. This
2071 procedure must be called before any calls to @code{getprotoent}, and may
2072 also be called afterward to reset the protocol entry stream. If
2073 @var{stayopen} is supplied and is not @code{#f}, the database is not
2074 closed by subsequent @code{getprotobyname} or @code{getprotobynumber} calls,
2075 possibly giving an efficiency gain.
2078 @deffn {Scheme Procedure} getprotoent
2079 Return the next entry from the protocol database.
2082 @deffn {Scheme Procedure} endprotoent
2083 Close the stream used by @code{getprotoent}. The return value is unspecified.
2086 @deffn {Scheme Procedure} setproto [stayopen]
2087 @deffnx {C Function} scm_setproto (stayopen)
2088 If @var{stayopen} is omitted, this is equivalent to @code{endprotoent}.
2089 Otherwise it is equivalent to @code{setprotoent stayopen}.
2092 @subsubsection The Service Database
2094 The following functions accept an object representing a service
2095 and return a selected component:
2097 @deffn {Scheme Procedure} servent:name serv
2098 The ``official'' name of the network service.
2100 @deffn {Scheme Procedure} servent:aliases serv
2101 A list of aliases for the network service.
2103 @deffn {Scheme Procedure} servent:port serv
2104 The Internet port used by the service.
2106 @deffn {Scheme Procedure} servent:proto serv
2107 The protocol used by the service. A service may be listed many times
2108 in the database under different protocol names.
2111 The following procedures are used to search the service database:
2113 @deffn {Scheme Procedure} getserv [name [protocol]]
2114 @deffnx {Scheme Procedure} getservbyname name protocol
2115 @deffnx {Scheme Procedure} getservbyport port protocol
2116 @deffnx {C Function} scm_getserv (name, protocol)
2117 Look up a network service by name or by service number, and return a
2118 network service object. The @var{protocol} argument specifies the name
2119 of the desired protocol; if the protocol found in the network service
2120 database does not match this name, a system error is signalled.
2122 The @code{getserv} procedure will take either a service name or number
2123 as its first argument; if given no arguments, it behaves like
2124 @code{getservent} (see below).
2127 (getserv "imap" "tcp")
2128 @result{} #("imap2" ("imap") 143 "tcp")
2130 (getservbyport 88 "udp")
2131 @result{} #("kerberos" ("kerberos5" "krb5") 88 "udp")
2135 The following procedures may be used to step through the service
2136 database from beginning to end.
2138 @deffn {Scheme Procedure} setservent [stayopen]
2139 Initialize an internal stream from which service objects may be read. This
2140 procedure must be called before any calls to @code{getservent}, and may
2141 also be called afterward to reset the service entry stream. If
2142 @var{stayopen} is supplied and is not @code{#f}, the database is not
2143 closed by subsequent @code{getservbyname} or @code{getservbyport} calls,
2144 possibly giving an efficiency gain.
2147 @deffn {Scheme Procedure} getservent
2148 Return the next entry from the services database.
2151 @deffn {Scheme Procedure} endservent
2152 Close the stream used by @code{getservent}. The return value is unspecified.
2155 @deffn {Scheme Procedure} setserv [stayopen]
2156 @deffnx {C Function} scm_setserv (stayopen)
2157 If @var{stayopen} is omitted, this is equivalent to @code{endservent}.
2158 Otherwise it is equivalent to @code{setservent stayopen}.
2161 @node Network Sockets and Communication
2162 @subsection Network Sockets and Communication
2164 Socket ports can be created using @code{socket} and @code{socketpair}.
2165 The ports are initially unbuffered, to make reading and writing to the
2166 same port more reliable. A buffer can be added to the port using
2167 @code{setvbuf}; see @ref{Ports and File Descriptors}.
2169 Most systems have limits on how many files and sockets can be open, so
2170 it's strongly recommended that socket ports be closed explicitly when
2171 no longer required (@pxref{Ports}).
2173 The convention used for ``host'' vs.@: ``network'' addresses is that
2174 addresses are always held in host order at the Scheme level. The
2175 procedures in this section automatically convert between host and
2176 network order when required. The arguments and return values are thus
2179 @deffn {Scheme Procedure} socket family style proto
2180 @deffnx {C Function} scm_socket (family, style, proto)
2181 Return a new socket port of the type specified by @var{family},
2182 @var{style} and @var{proto}. All three parameters are integers. The
2183 possible values for @var{family} are as follows, where supported by
2191 The possible values for @var{style} are as follows, again where
2192 supported by the system,
2199 @var{proto} can be obtained from a protocol name using
2200 @code{getprotobyname} (@pxref{Network Databases}). A value of zero
2201 means the default protocol, which is usually right.
2203 A socket cannot by used for communication until it has been connected
2204 somewhere, usually with either @code{connect} or @code{accept} below.
2207 @deffn {Scheme Procedure} socketpair family style proto
2208 @deffnx {C Function} scm_socketpair (family, style, proto)
2209 Return a pair, the @code{car} and @code{cdr} of which are two unnamed
2210 socket ports connected to each other. The connection is full-duplex,
2211 so data can be transferred in either direction between the two.
2213 @var{family}, @var{style} and @var{proto} are as per @code{socket}
2214 above. But many systems only support socket pairs in the
2215 @code{PF_UNIX} family. Zero is likely to be the only meaningful value
2219 @deffn {Scheme Procedure} getsockopt sock level optname
2220 @deffnx {C Function} scm_getsockopt (sock, level, optname)
2221 Return the value of a particular socket option for the socket
2222 port @var{sock}. @var{level} is an integer code for type of
2223 option being requested, e.g., @code{SOL_SOCKET} for
2224 socket-level options. @var{optname} is an integer code for the
2225 option required and should be specified using one of the
2226 symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc.
2228 The returned value is typically an integer but @code{SO_LINGER}
2229 returns a pair of integers.
2232 @deffn {Scheme Procedure} setsockopt sock level optname value
2233 @deffnx {C Function} scm_setsockopt (sock, level, optname, value)
2234 Set the value of a particular socket option for the socket
2235 port @var{sock}. @var{level} is an integer code for type of option
2236 being set, e.g., @code{SOL_SOCKET} for socket-level options.
2238 integer code for the option to set and should be specified using one of
2239 the symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc.
2240 @var{value} is the value to which the option should be set. For
2241 most options this must be an integer, but for @code{SO_LINGER} it must
2244 The return value is unspecified.
2247 @deffn {Scheme Procedure} shutdown sock how
2248 @deffnx {C Function} scm_shutdown (sock, how)
2249 Sockets can be closed simply by using @code{close-port}. The
2250 @code{shutdown} procedure allows reception or transmission on a
2251 connection to be shut down individually, according to the parameter
2256 Stop receiving data for this socket. If further data arrives, reject it.
2258 Stop trying to transmit data from this socket. Discard any
2259 data waiting to be sent. Stop looking for acknowledgement of
2260 data already sent; don't retransmit it if it is lost.
2262 Stop both reception and transmission.
2265 The return value is unspecified.
2268 @deffn {Scheme Procedure} connect sock fam address . args
2269 @deffnx {C Function} scm_connect (sock, fam, address, args)
2270 Initiate a connection from a socket using a specified address
2271 family to the address
2272 specified by @var{address} and possibly @var{args}.
2273 The format required for @var{address}
2274 and @var{args} depends on the family of the socket.
2276 For a socket of family @code{AF_UNIX},
2277 only @var{address} is specified and must be a string with the
2278 filename where the socket is to be created.
2280 For a socket of family @code{AF_INET},
2281 @var{address} must be an integer IPv4 host address and
2282 @var{args} must be a single integer port number.
2284 For a socket of family @code{AF_INET6},
2285 @var{address} must be an integer IPv6 host address and
2286 @var{args} may be up to three integers:
2287 port [flowinfo] [scope_id],
2288 where flowinfo and scope_id default to zero.
2290 The return value is unspecified.
2293 @deffn {Scheme Procedure} bind sock fam address . args
2294 @deffnx {C Function} scm_bind (sock, fam, address, args)
2295 Assign an address to the socket port @var{sock}.
2296 Generally this only needs to be done for server sockets,
2297 so they know where to look for incoming connections. A socket
2298 without an address will be assigned one automatically when it
2299 starts communicating.
2301 The format of @var{address} and @var{args} depends
2302 on the family of the socket.
2304 For a socket of family @code{AF_UNIX}, only @var{address}
2305 is specified and must be a string with the filename where
2306 the socket is to be created.
2308 For a socket of family @code{AF_INET}, @var{address}
2309 must be an integer IPv4 address and @var{args}
2310 must be a single integer port number.
2312 The values of the following variables can also be used for
2316 Allow connections from any address.
2319 @defvar INADDR_LOOPBACK
2320 The address of the local host using the loopback device.
2323 @defvar INADDR_BROADCAST
2324 The broadcast address on the local network.
2331 For a socket of family @code{AF_INET6}, @var{address}
2332 must be an integer IPv6 address and @var{args}
2333 may be up to three integers:
2334 port [flowinfo] [scope_id],
2335 where flowinfo and scope_id default to zero.
2337 The return value is unspecified.
2340 @deffn {Scheme Procedure} listen sock backlog
2341 @deffnx {C Function} scm_listen (sock, backlog)
2342 Enable @var{sock} to accept connection
2343 requests. @var{backlog} is an integer specifying
2344 the maximum length of the queue for pending connections.
2345 If the queue fills, new clients will fail to connect until
2346 the server calls @code{accept} to accept a connection from
2349 The return value is unspecified.
2352 @deffn {Scheme Procedure} accept sock
2353 @deffnx {C Function} scm_accept (sock)
2354 Accept a connection on a bound, listening socket.
2356 are no pending connections in the queue, wait until
2357 one is available unless the non-blocking option has been
2360 The return value is a
2361 pair in which the @acronym{CAR} is a new socket port for the
2363 the @acronym{CDR} is an object with address information about the
2364 client which initiated the connection.
2366 @var{sock} does not become part of the
2367 connection and will continue to accept new requests.
2370 The following functions take a socket address object, as returned
2371 by @code{accept} and other procedures, and return a selected component.
2373 @deffn {Scheme Procedure} sockaddr:fam sa
2374 The socket family, typically equal to the value of @code{AF_UNIX} or
2377 @deffn {Scheme Procedure} sockaddr:path sa
2378 If the socket family is @code{AF_UNIX}, returns the path of the
2379 filename the socket is based on.
2381 @deffn {Scheme Procedure} sockaddr:addr sa
2382 If the socket family is @code{AF_INET}, returns the Internet host
2385 @deffn {Scheme Procedure} sockaddr:port sa
2386 If the socket family is @code{AF_INET}, returns the Internet port
2390 @deffn {Scheme Procedure} getsockname sock
2391 @deffnx {C Function} scm_getsockname (sock)
2392 Return the address of @var{sock}, in the same form as the
2393 object returned by @code{accept}. On many systems the address
2394 of a socket in the @code{AF_FILE} namespace cannot be read.
2397 @deffn {Scheme Procedure} getpeername sock
2398 @deffnx {C Function} scm_getpeername (sock)
2399 Return the address that @var{sock}
2400 is connected to, in the same form as the object returned by
2401 @code{accept}. On many systems the address of a socket in the
2402 @code{AF_FILE} namespace cannot be read.
2405 @deffn {Scheme Procedure} recv! sock buf [flags]
2406 @deffnx {C Function} scm_recv (sock, buf, flags)
2407 Receive data from a socket port.
2408 @var{sock} must already
2409 be bound to the address from which data is to be received.
2410 @var{buf} is a string into which
2411 the data will be written. The size of @var{buf} limits
2413 data which can be received: in the case of packet
2414 protocols, if a packet larger than this limit is encountered
2416 will be irrevocably lost.
2420 @vindex MSG_DONTROUTE
2421 The optional @var{flags} argument is a value or bitwise OR of
2422 @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
2424 The value returned is the number of bytes read from the
2427 Note that the data is read directly from the socket file
2429 any unread buffered port data is ignored.
2432 @deffn {Scheme Procedure} send sock message [flags]
2433 @deffnx {C Function} scm_send (sock, message, flags)
2436 @vindex MSG_DONTROUTE
2437 Transmit the string @var{message} on a socket port @var{sock}.
2438 @var{sock} must already be bound to a destination address. The value
2439 returned is the number of bytes transmitted---it's possible for this
2440 to be less than the length of @var{message} if the socket is set to be
2441 non-blocking. The optional @var{flags} argument is a value or bitwise
2442 OR of @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
2444 Note that the data is written directly to the socket
2446 any unflushed buffered port data is ignored.
2449 @deffn {Scheme Procedure} recvfrom! sock str [flags [start [end]]]
2450 @deffnx {C Function} scm_recvfrom (sock, str, flags, start, end)
2451 Return data from the socket port @var{sock} and also
2452 information about where the data was received from.
2453 @var{sock} must already be bound to the address from which
2454 data is to be received. @code{str}, is a string into which the
2455 data will be written. The size of @var{str} limits the amount
2456 of data which can be received: in the case of packet protocols,
2457 if a packet larger than this limit is encountered then some
2458 data will be irrevocably lost.
2462 @vindex MSG_DONTROUTE
2463 The optional @var{flags} argument is a value or bitwise OR of
2464 @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
2466 The value returned is a pair: the @acronym{CAR} is the number of
2467 bytes read from the socket and the @acronym{CDR} an address object
2468 in the same form as returned by @code{accept}. The address
2469 will given as @code{#f} if not available, as is usually the
2470 case for stream sockets.
2472 The @var{start} and @var{end} arguments specify a substring of
2473 @var{str} to which the data should be written.
2475 Note that the data is read directly from the socket file
2476 descriptor: any unread buffered port data is ignored.
2479 @deffn {Scheme Procedure} sendto sock message fam address . args_and_flags
2480 @deffnx {C Function} scm_sendto (sock, message, fam, address, args_and_flags)
2481 Transmit the string @var{message} on the socket port
2483 destination address is specified using the @var{fam},
2485 @var{args_and_flags} arguments, in a similar way to the
2486 @code{connect} procedure. @var{args_and_flags} contains
2487 the usual connection arguments optionally followed by
2488 a flags argument, which is a value or
2489 bitwise OR of @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
2491 The value returned is the number of bytes transmitted --
2493 this to be less than the length of @var{message} if the
2495 set to be non-blocking.
2496 Note that the data is written directly to the socket
2498 any unflushed buffered port data is ignored.
2501 The following functions can be used to convert short and long integers
2502 between ``host'' and ``network'' order. Although the procedures above do
2503 this automatically for addresses, the conversion will still need to
2504 be done when sending or receiving encoded integer data from the network.
2506 @deffn {Scheme Procedure} htons value
2507 @deffnx {C Function} scm_htons (value)
2508 Convert a 16 bit quantity from host to network byte ordering.
2509 @var{value} is packed into 2 bytes, which are then converted
2510 and returned as a new integer.
2513 @deffn {Scheme Procedure} ntohs value
2514 @deffnx {C Function} scm_ntohs (value)
2515 Convert a 16 bit quantity from network to host byte ordering.
2516 @var{value} is packed into 2 bytes, which are then converted
2517 and returned as a new integer.
2520 @deffn {Scheme Procedure} htonl value
2521 @deffnx {C Function} scm_htonl (value)
2522 Convert a 32 bit quantity from host to network byte ordering.
2523 @var{value} is packed into 4 bytes, which are then converted
2524 and returned as a new integer.
2527 @deffn {Scheme Procedure} ntohl value
2528 @deffnx {C Function} scm_ntohl (value)
2529 Convert a 32 bit quantity from network to host byte ordering.
2530 @var{value} is packed into 4 bytes, which are then converted
2531 and returned as a new integer.
2534 These procedures are inconvenient to use at present, but consider:
2537 (define write-network-long
2538 (lambda (value port)
2539 (let ((v (make-uniform-vector 1 1 0)))
2540 (uniform-vector-set! v 0 (htonl value))
2541 (uniform-vector-write v port))))
2543 (define read-network-long
2545 (let ((v (make-uniform-vector 1 1 0)))
2546 (uniform-vector-read! v port)
2547 (ntohl (uniform-vector-ref v 0)))))
2551 @node Internet Socket Examples
2552 @subsection Network Socket Examples
2554 The following sections give examples of how to use network sockets.
2557 * Internet Socket Client::
2558 * Internet Socket Server::
2562 @node Internet Socket Client
2563 @subsubsection Internet Socket Client Example
2565 @cindex socket client example
2566 The following example demonstrates an Internet socket client.
2567 It connects to the HTTP daemon running on the local machine and
2568 returns the contents of the root index URL.
2571 (let ((s (socket AF_INET SOCK_STREAM 0)))
2572 (connect s AF_INET (inet-aton "127.0.0.1") 80)
2573 (display "GET / HTTP/1.0\r\n\r\n" s)
2575 (do ((line (read-line s) (read-line s)))
2576 ((eof-object? line))
2582 @node Internet Socket Server
2583 @subsubsection Internet Socket Server Example
2585 @cindex socket server example
2586 The following example shows a simple Internet server which listens on
2587 port 2904 for incoming connections and sends a greeting back to the
2591 (let ((s (socket AF_INET SOCK_STREAM 0)))
2592 (setsockopt s SOL_SOCKET SO_REUSEADDR 1)
2593 ;; @r{Specific address?}
2594 ;; @r{(bind s AF_INET (inet-aton "127.0.0.1") 2904)}
2595 (bind s AF_INET INADDR_ANY 2904)
2598 (simple-format #t "Listening for clients in pid: ~S" (getpid))
2602 (let* ((client-connection (accept s))
2603 (client-details (cdr client-connection))
2604 (client (car client-connection)))
2605 (simple-format #t "Got new client connection: ~S"
2608 (simple-format #t "Client address: ~S"
2610 (sockaddr:addr client-details)))
2612 ;; @r{Send back the greeting to the client port}
2613 (display "Hello client\r\n" client)
2618 @node System Identification
2619 @section System Identification
2621 This section lists the various procedures Guile provides for accessing
2622 information about the system it runs on.
2624 @deffn {Scheme Procedure} uname
2625 @deffnx {C Function} scm_uname ()
2626 Return an object with some information about the computer
2627 system the program is running on.
2629 The following procedures accept an object as returned by @code{uname}
2630 and return a selected component.
2632 @deffn {Scheme Procedure} utsname:sysname un
2633 The name of the operating system.
2635 @deffn {Scheme Procedure} utsname:nodename un
2636 The network name of the computer.
2638 @deffn {Scheme Procedure} utsname:release un
2639 The current release level of the operating system implementation.
2641 @deffn {Scheme Procedure} utsname:version un
2642 The current version level within the release of the operating system.
2644 @deffn {Scheme Procedure} utsname:machine un
2645 A description of the hardware.
2649 @deffn {Scheme Procedure} gethostname
2650 @deffnx {C Function} scm_gethostname ()
2651 Return the host name of the current processor.
2654 @deffn {Scheme Procedure} sethostname name
2655 @deffnx {C Function} scm_sethostname (name)
2656 Set the host name of the current processor to @var{name}. May
2657 only be used by the superuser. The return value is not
2661 @c FIXME::martin: Not in libguile!
2662 @deffn {Scheme Procedure} software-type
2663 Return a symbol describing the current platform's operating system.
2664 This may be one of @samp{AIX}, @samp{VMS}, @samp{UNIX},
2665 @samp{COHERENT}, @samp{WINDOWS}, @samp{MS-DOS}, @samp{OS/2},
2666 @samp{THINKC}, @samp{AMIGA}, @samp{ATARIST}, @samp{MACH}, or
2669 Note that most varieties of Unix are considered to be simply @samp{UNIX}.
2670 That is because when a program depends on features that are not present
2671 on every operating system, it is usually better to test for the presence
2672 or absence of that specific feature. The return value of
2673 @code{software-type} should only be used for this purpose when there is
2674 no other easy or unambiguous way of detecting such features.
2680 @deffn {Scheme Procedure} setlocale category [locale]
2681 @deffnx {C Function} scm_setlocale (category, locale)
2682 Get or set the current locale, used for various internationalizations.
2683 Locales are strings, such as @samp{sv_SE}.
2685 If @var{locale} is given then the locale for the given category is set
2686 and the new value returned. If @var{locale} is not given then the
2687 current value is returned. @var{category} should be one of the
2693 @defvarx LC_MESSAGES
2694 @defvarx LC_MONETARY
2699 A common usage is @samp{(setlocale LC_ALL "")}, which initializes all
2700 categories based on standard environment variables (@code{LANG} etc).
2701 For full details on categories and locale names @pxref{Locales,,
2702 Locales and Internationalization, libc, The GNU C Library Reference
2709 Please note that the procedures in this section are not suited for
2710 strong encryption, they are only interfaces to the well-known and
2711 common system library functions of the same name. They are just as good
2712 (or bad) as the underlying functions, so you should refer to your system
2713 documentation before using them.
2715 @deffn {Scheme Procedure} crypt key salt
2716 @deffnx {C Function} scm_crypt (key, salt)
2717 Encrypt @var{key} using @var{salt} as the salt value to the
2718 crypt(3) library call.
2721 Although @code{getpass} is not an encryption procedure per se, it
2722 appears here because it is often used in combination with @code{crypt}:
2724 @deffn {Scheme Procedure} getpass prompt
2725 @deffnx {C Function} scm_getpass (prompt)
2726 Display @var{prompt} to the standard error output and read
2727 a password from @file{/dev/tty}. If this file is not
2728 accessible, it reads from standard input. The password may be
2729 up to 127 characters in length. Additional characters and the
2730 terminating newline character are discarded. While reading
2731 the password, echoing and the generation of signals by special
2732 characters is disabled.