2 @chapter 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 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 @ref{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, @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
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 "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, the three file
141 descriptors (0, 1 and 2) are automatically imported when a program
142 starts up and assigned to the initial values of the current input,
143 output and error ports. The revealed count for each is initially set to
144 one, so that dropping references to one of these ports will not result
145 in its garbage collection: it could be retrieved with fdopen or
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 port to a given value.
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}.
173 Modes are given by the string @var{modes}. The revealed count
174 of the port is initialized to zero. The modes string is the
175 same as that accepted by @ref{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, if
232 it needs to be created, before the umask is applied. The default is 666
233 (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 See the Unix documentation of the @code{open} system call
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 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.
276 Close file descriptor @var{fd}, which must be an integer.
277 Unlike close (@pxref{Ports and File Descriptors, close}),
278 the file descriptor will be closed even if a port is using it.
279 The return value is unspecified.
282 @deffn {Scheme Procedure} unread-char char [port]
283 @deffnx {C Function} scm_unread_char (char, port)
284 Place @var{char} in @var{port} so that it will be read by the
285 next read operation. If called multiple times, the unread characters
286 will be read again in last-in first-out order. If @var{port} is
287 not supplied, the current input port is used.
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 @emph{car} is the input
301 port and the @emph{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}.
307 Writes occur atomically provided the size of the data in bytes
308 is not greater than the value of @code{PIPE_BUF}. Note that
309 the output port is likely to block if too much data (typically
310 equal to @code{PIPE_BUF}) has been written but not yet read
314 The next group of procedures perform a @code{dup2}
315 system call, if @var{newfd} (an
316 integer) is supplied, otherwise a @code{dup}. The file descriptor to be
317 duplicated can be supplied as an integer or contained in a port. The
318 type of value returned varies depending on which procedure is used.
320 All procedures also have the side effect when performing @code{dup2} that any
321 ports using @var{newfd} are moved to a different file descriptor and have
322 their revealed counts set to zero.
324 @deffn {Scheme Procedure} dup->fdes fd_or_port [fd]
325 @deffnx {C Function} scm_dup_to_fdes (fd_or_port, fd)
326 Return a new integer file descriptor referring to the open file
327 designated by @var{fd_or_port}, which must be either an open
328 file port or a file descriptor.
331 @deffn {Scheme Procedure} dup->inport port/fd [newfd]
332 Returns a new input port using the new file descriptor.
335 @deffn {Scheme Procedure} dup->outport port/fd [newfd]
336 Returns a new output port using the new file descriptor.
339 @deffn {Scheme Procedure} dup port/fd [newfd]
340 Returns a new port if @var{port/fd} is a port, with the same mode as the
341 supplied port, otherwise returns an integer file descriptor.
344 @deffn {Scheme Procedure} dup->port port/fd mode [newfd]
345 Returns a new port using the new file descriptor. @var{mode} supplies a
346 mode string for the port (@pxref{File Ports, open-file}).
349 @deffn {Scheme Procedure} duplicate-port port modes
350 Returns a new port which is opened on a duplicate of the file
351 descriptor underlying @var{port}, with mode string @var{modes}
352 as for @ref{File Ports, open-file}. The two ports
353 will share a file position and file status flags.
355 Unexpected behaviour can result if both ports are subsequently used
356 and the original and/or duplicate ports are buffered.
357 The mode string can include @code{0} to obtain an unbuffered duplicate
360 This procedure is equivalent to @code{(dup->port @var{port} @var{modes})}.
363 @deffn {Scheme Procedure} redirect-port old new
364 @deffnx {C Function} scm_redirect_port (old, new)
365 This procedure takes two ports and duplicates the underlying file
366 descriptor from @var{old-port} into @var{new-port}. The
367 current file descriptor in @var{new-port} will be closed.
368 After the redirection the two ports will share a file position
369 and file status flags.
371 The return value is unspecified.
373 Unexpected behaviour can result if both ports are subsequently used
374 and the original and/or duplicate ports are buffered.
376 This procedure does not have any side effects on other ports or
380 @deffn {Scheme Procedure} dup2 oldfd newfd
381 @deffnx {C Function} scm_dup2 (oldfd, newfd)
382 A simple wrapper for the @code{dup2} system call.
383 Copies the file descriptor @var{oldfd} to descriptor
384 number @var{newfd}, replacing the previous meaning
385 of @var{newfd}. Both @var{oldfd} and @var{newfd} must
387 Unlike for dup->fdes or primitive-move->fdes, no attempt
388 is made to move away ports which are using @var{newfd}.
389 The return value is unspecified.
392 @deffn {Scheme Procedure} port-mode port
393 Return the port modes associated with the open port @var{port}.
394 These will not necessarily be identical to the modes used when
395 the port was opened, since modes such as "append" which are
396 used only during port creation are not retained.
399 @deffn {Scheme Procedure} port-for-each proc
400 @deffnx {C Function} scm_port_for_each (proc)
401 Apply @var{proc} to each port in the Guile port table
402 in turn. The return value is unspecified. More specifically,
403 @var{proc} is applied exactly once to every port that exists
404 in the system at the time @var{port-for-each} is invoked.
405 Changes to the port table while @var{port-for-each} is running
406 have no effect as far as @var{port-for-each} is concerned.
409 @deffn {Scheme Procedure} setvbuf port mode [size]
410 @deffnx {C Function} scm_setvbuf (port, mode, size)
411 Set the buffering mode for @var{port}. @var{mode} can be:
418 block buffered, using a newly allocated buffer of @var{size} bytes.
419 If @var{size} is omitted, a default size will be used.
423 @deffn {Scheme Procedure} fcntl object cmd [value]
424 @deffnx {C Function} scm_fcntl (object, cmd, value)
425 Apply @var{command} to the specified file descriptor or the underlying
426 file descriptor of the specified port. @var{value} is an optional
429 Values for @var{command} are:
433 Duplicate a file descriptor
435 Get flags associated with the file descriptor.
437 Set flags associated with the file descriptor to @var{value}.
439 Get flags associated with the open file.
441 Set flags associated with the open file to @var{value}
443 Get the process ID of a socket's owner, for @code{SIGIO} signals.
445 Set the process that owns a socket to @var{value}, for @code{SIGIO} signals.
447 The value used to indicate the "close on exec" flag with @code{F_GETFL} or
452 @deffn {Scheme Procedure} flock file operation
453 @deffnx {C Function} scm_flock (file, operation)
454 Apply or remove an advisory lock on an open file.
455 @var{operation} specifies the action to be done:
458 Shared lock. More than one process may hold a shared lock
459 for a given file at a given time.
461 Exclusive lock. Only one process may hold an exclusive lock
462 for a given file at a given time.
466 Don't block when locking. May be specified by bitwise OR'ing
467 it to one of the other operations.
469 The return value is not specified. @var{file} may be an open
470 file descriptor or an open file descriptor port.
473 @deffn {Scheme Procedure} select reads writes excepts [secs [usecs]]
474 @deffnx {C Function} scm_select (reads, writes, excepts, secs, usecs)
475 This procedure has a variety of uses: waiting for the ability
476 to provide input, accept output, or the existence of
477 exceptional conditions on a collection of ports or file
478 descriptors, or waiting for a timeout to occur.
479 It also returns if interrupted by a signal.
481 @var{reads}, @var{writes} and @var{excepts} can be lists or
482 vectors, with each member a port or a file descriptor.
483 The value returned is a list of three corresponding
484 lists or vectors containing only the members which meet the
485 specified requirement. The ability of port buffers to
486 provide input or accept output is taken into account.
487 Ordering of the input lists or vectors is not preserved.
489 The optional arguments @var{secs} and @var{usecs} specify the
490 timeout. Either @var{secs} can be specified alone, as
491 either an integer or a real number, or both @var{secs} and
492 @var{usecs} can be specified as integers, in which case
493 @var{usecs} is an additional timeout expressed in
494 microseconds. If @var{secs} is omitted or is @code{#f} then
495 select will wait for as long as it takes for one of the other
496 conditions to be satisfied.
498 The scsh version of @code{select} differs as follows:
499 Only vectors are accepted for the first three arguments.
500 The @var{usecs} argument is not supported.
501 Multiple values are returned instead of a list.
502 Duplicates in the input vectors appear only once in output.
503 An additional @code{select!} interface is provided.
509 These procedures allow querying and setting file system attributes
511 permissions, sizes and types of files); deleting, copying, renaming and
512 linking files; creating and removing directories and querying their
513 contents; syncing the file system and creating special files.
515 @deffn {Scheme Procedure} access? path how
516 @deffnx {C Function} scm_access (path, how)
517 Return @code{#t} if @var{path} corresponds to an existing file
518 and the current process has the type of access specified by
519 @var{how}, otherwise @code{#f}. @var{how} should be specified
520 using the values of the variables listed below. Multiple
521 values can be combined using a bitwise or, in which case
522 @code{#t} will only be returned if all accesses are granted.
524 Permissions are checked using the real id of the current
525 process, not the effective id, although it's the effective id
526 which determines whether the access would actually be granted.
529 test for read permission.
532 test for write permission.
535 test for execute permission.
538 test for existence of the file.
543 @deffn {Scheme Procedure} stat object
544 @deffnx {C Function} scm_stat (object)
545 Return an object containing various information about the file
546 determined by @var{obj}. @var{obj} can be a string containing
547 a file name or a port or integer file descriptor which is open
548 on a file (in which case @code{fstat} is used as the underlying
551 The object returned by @code{stat} can be passed as a single
552 parameter to the following procedures, all of which return
557 The device containing the file.
559 The file serial number, which distinguishes this file from all
560 other files on the same device.
562 The mode of the file. This includes file type information and
563 the file permission bits. See @code{stat:type} and
564 @code{stat:perms} below.
566 The number of hard links to the file.
568 The user ID of the file's owner.
570 The group ID of the file.
572 Device ID; this entry is defined only for character or block
575 The size of a regular file in bytes.
577 The last access time for the file.
579 The last modification time for the file.
581 The last modification time for the attributes of the file.
583 The optimal block size for reading or writing the file, in
586 The amount of disk space that the file occupies measured in
587 units of 512 byte blocks.
590 In addition, the following procedures return the information
591 from stat:mode in a more convenient form:
595 A symbol representing the type of file. Possible values are
596 regular, directory, symlink, block-special, char-special, fifo,
599 An integer representing the access permission bits.
603 @deffn {Scheme Procedure} lstat str
604 @deffnx {C Function} scm_lstat (str)
605 Similar to @code{stat}, but does not follow symbolic links, i.e.,
606 it will return information about a symbolic link itself, not the
607 file it points to. @var{path} must be a string.
610 @deffn {Scheme Procedure} readlink path
611 @deffnx {C Function} scm_readlink (path)
612 Return the value of the symbolic link named by @var{path} (a
613 string), i.e., the file that the link points to.
618 @deffn {Scheme Procedure} chown object owner group
619 @deffnx {C Function} scm_chown (object, owner, group)
620 Change the ownership and group of the file referred to by @var{object} to
621 the integer values @var{owner} and @var{group}. @var{object} can be
622 a string containing a file name or, if the platform
623 supports fchown, a port or integer file descriptor
624 which is open on the file. The return value
627 If @var{object} is a symbolic link, either the
628 ownership of the link or the ownership of the referenced file will be
629 changed depending on the operating system (lchown is
630 unsupported at present). If @var{owner} or @var{group} is specified
631 as @code{-1}, then that ID is not changed.
635 @deffn {Scheme Procedure} chmod object mode
636 @deffnx {C Function} scm_chmod (object, mode)
637 Changes the permissions of the file referred to by @var{obj}.
638 @var{obj} can be a string containing a file name or a port or integer file
639 descriptor which is open on a file (in which case @code{fchmod} is used
640 as the underlying system call).
642 the new permissions as a decimal number, e.g., @code{(chmod "foo" #o755)}.
643 The return value is unspecified.
646 @deffn {Scheme Procedure} utime pathname [actime [modtime]]
647 @deffnx {C Function} scm_utime (pathname, actime, modtime)
648 @code{utime} sets the access and modification times for the
649 file named by @var{path}. If @var{actime} or @var{modtime} is
650 not supplied, then the current time is used. @var{actime} and
651 @var{modtime} must be integer time values as returned by the
652 @code{current-time} procedure.
654 (utime "foo" (- (current-time) 3600))
656 will set the access time to one hour in the past and the
657 modification time to the current time.
661 @deffn {Scheme Procedure} delete-file str
662 @deffnx {C Function} scm_delete_file (str)
663 Deletes (or "unlinks") the file specified by @var{path}.
666 @deffn {Scheme Procedure} copy-file oldfile newfile
667 @deffnx {C Function} scm_copy_file (oldfile, newfile)
668 Copy the file specified by @var{path-from} to @var{path-to}.
669 The return value is unspecified.
673 @deffn {Scheme Procedure} rename-file oldname newname
674 @deffnx {C Function} scm_rename (oldname, newname)
675 Renames the file specified by @var{oldname} to @var{newname}.
676 The return value is unspecified.
679 @deffn {Scheme Procedure} link oldpath newpath
680 @deffnx {C Function} scm_link (oldpath, newpath)
681 Creates a new name @var{newpath} in the file system for the
682 file named by @var{oldpath}. If @var{oldpath} is a symbolic
683 link, the link may or may not be followed depending on the
687 @deffn {Scheme Procedure} symlink oldpath newpath
688 @deffnx {C Function} scm_symlink (oldpath, newpath)
689 Create a symbolic link named @var{path-to} with the value (i.e., pointing to)
690 @var{path-from}. The return value is unspecified.
693 @deffn {Scheme Procedure} mkdir path [mode]
694 @deffnx {C Function} scm_mkdir (path, mode)
695 Create a new directory named by @var{path}. If @var{mode} is omitted
696 then the permissions of the directory file are set using the current
697 umask. Otherwise they are set to the decimal value specified with
698 @var{mode}. The return value is unspecified.
701 @deffn {Scheme Procedure} rmdir path
702 @deffnx {C Function} scm_rmdir (path)
703 Remove the existing directory named by @var{path}. The directory must
704 be empty for this to succeed. The return value is unspecified.
707 @deffn {Scheme Procedure} opendir dirname
708 @deffnx {C Function} scm_opendir (dirname)
709 Open the directory specified by @var{path} and return a directory
713 @deffn {Scheme Procedure} directory-stream? obj
714 @deffnx {C Function} scm_directory_stream_p (obj)
715 Return a boolean indicating whether @var{object} is a directory
716 stream as returned by @code{opendir}.
719 @deffn {Scheme Procedure} readdir port
720 @deffnx {C Function} scm_readdir (port)
721 Return (as a string) the next directory entry from the directory stream
722 @var{stream}. If there is no remaining entry to be read then the
723 end of file object is returned.
726 @deffn {Scheme Procedure} rewinddir port
727 @deffnx {C Function} scm_rewinddir (port)
728 Reset the directory port @var{stream} so that the next call to
729 @code{readdir} will return the first directory entry.
732 @deffn {Scheme Procedure} closedir port
733 @deffnx {C Function} scm_closedir (port)
734 Close the directory stream @var{stream}.
735 The return value is unspecified.
738 Here is an example showing how to display all the entries in a
742 (define dir (opendir "/usr/lib"))
743 (do ((entry (readdir dir) (readdir dir)))
744 ((eof-object? entry))
745 (display entry)(newline))
749 @deffn {Scheme Procedure} sync
750 @deffnx {C Function} scm_sync ()
751 Flush the operating system disk buffers.
752 The return value is unspecified.
755 @deffn {Scheme Procedure} mknod path type perms dev
756 @deffnx {C Function} scm_mknod (path, type, perms, dev)
757 Creates a new special file, such as a file corresponding to a device.
758 @var{path} specifies the name of the file. @var{type} should
759 be one of the following symbols:
760 regular, directory, symlink, block-special, char-special,
761 fifo, or socket. @var{perms} (an integer) specifies the file permissions.
762 @var{dev} (an integer) specifies which device the special file refers
763 to. Its exact interpretation depends on the kind of special file
768 (mknod "/dev/fd0" 'block-special #o660 (+ (* 2 256) 2))
771 The return value is unspecified.
774 @deffn {Scheme Procedure} tmpnam
775 @deffnx {C Function} scm_tmpnam ()
776 Return a name in the file system that does not match any
777 existing file. However there is no guarantee that another
778 process will not create the file after @code{tmpnam} is called.
779 Care should be taken if opening the file, e.g., use the
780 @code{O_EXCL} open flag or use @code{mkstemp!} instead.
783 @deffn {Scheme Procedure} mkstemp! tmpl
784 @deffnx {C Function} scm_mkstemp (tmpl)
785 Create a new unique file in the file system and returns a new
786 buffered port open for reading and writing to the file.
787 @var{tmpl} is a string specifying where the file should be
788 created: it must end with @code{XXXXXX} and will be changed in
789 place to return the name of the temporary file.
792 @deffn {Scheme Procedure} dirname filename
793 @deffnx {C Function} scm_dirname (filename)
794 Return the directory name component of the file name
795 @var{filename}. If @var{filename} does not contain a directory
796 component, @code{.} is returned.
799 @deffn {Scheme Procedure} basename filename [suffix]
800 @deffnx {C Function} scm_basename (filename, suffix)
801 Return the base name of the file name @var{filename}. The
802 base name is the file name without any directory components.
803 If @var{suffix} is provided, and is equal to the end of
804 @var{basename}, it is removed also.
807 (basename "/tmp/test.xml" ".xml")
813 @node User Information
814 @section User Information
816 The facilities in this section provide an interface to the user and
818 They should be used with care since they are not reentrant.
820 The following functions accept an object representing user information
821 and return a selected component:
825 The name of the userid.
827 The encrypted passwd.
840 @deffn {Scheme Procedure} getpwuid uid
841 Look up an integer userid in the user database.
844 @deffn {Scheme Procedure} getpwnam name
845 Look up a user name string in the user database.
848 @deffn {Scheme Procedure} setpwent
849 Initializes a stream used by @code{getpwent} to read from the user database.
850 The next use of @code{getpwent} will return the first entry. The
851 return value is unspecified.
854 @deffn {Scheme Procedure} getpwent
855 Return the next entry in the user database, using the stream set by
859 @deffn {Scheme Procedure} endpwent
860 Closes the stream used by @code{getpwent}. The return value is unspecified.
863 @deffn {Scheme Procedure} setpw [arg]
864 @deffnx {C Function} scm_setpwent (arg)
865 If called with a true argument, initialize or reset the password data
866 stream. Otherwise, close the stream. The @code{setpwent} and
867 @code{endpwent} procedures are implemented on top of this.
870 @deffn {Scheme Procedure} getpw [user]
871 @deffnx {C Function} scm_getpwuid (user)
872 Look up an entry in the user database. @var{obj} can be an integer,
873 a string, or omitted, giving the behaviour of getpwuid, getpwnam
874 or getpwent respectively.
877 The following functions accept an object representing group information
878 and return a selected component:
884 The encrypted group password.
888 A list of userids which have this group as a supplementary group.
891 @deffn {Scheme Procedure} getgrgid gid
892 Look up an integer group id in the group database.
895 @deffn {Scheme Procedure} getgrnam name
896 Look up a group name in the group database.
899 @deffn {Scheme Procedure} setgrent
900 Initializes a stream used by @code{getgrent} to read from the group database.
901 The next use of @code{getgrent} will return the first entry.
902 The return value is unspecified.
905 @deffn {Scheme Procedure} getgrent
906 Return the next entry in the group database, using the stream set by
910 @deffn {Scheme Procedure} endgrent
911 Closes the stream used by @code{getgrent}.
912 The return value is unspecified.
915 @deffn {Scheme Procedure} setgr [arg]
916 @deffnx {C Function} scm_setgrent (arg)
917 If called with a true argument, initialize or reset the group data
918 stream. Otherwise, close the stream. The @code{setgrent} and
919 @code{endgrent} procedures are implemented on top of this.
922 @deffn {Scheme Procedure} getgr [name]
923 @deffnx {C Function} scm_getgrgid (name)
924 Look up an entry in the group database. @var{obj} can be an integer,
925 a string, or omitted, giving the behaviour of getgrgid, getgrnam
926 or getgrent respectively.
929 In addition to the accessor procedures for the user database, the
930 following shortcut procedures are also available.
932 @deffn {Scheme Procedure} cuserid
933 @deffnx {C Function} scm_cuserid ()
934 Return a string containing a user name associated with the
935 effective user id of the process. Return @code{#f} if this
936 information cannot be obtained.
939 @deffn {Scheme Procedure} getlogin
940 @deffnx {C Function} scm_getlogin ()
941 Return a string containing the name of the user logged in on
942 the controlling terminal of the process, or @code{#f} if this
943 information cannot be obtained.
950 @deffn {Scheme Procedure} current-time
951 @deffnx {C Function} scm_current_time ()
952 Return the number of seconds since 1970-01-01 00:00:00 UTC,
953 excluding leap seconds.
956 @deffn {Scheme Procedure} gettimeofday
957 @deffnx {C Function} scm_gettimeofday ()
958 Return a pair containing the number of seconds and microseconds
959 since 1970-01-01 00:00:00 UTC, excluding leap seconds. Note:
960 whether true microsecond resolution is available depends on the
964 The following procedures either accept an object representing a broken down
965 time and return a selected component, or accept an object representing
966 a broken down time and a value and set the component to the value.
967 The numbers in parentheses give the usual range.
970 @item tm:sec, set-tm:sec
972 @item tm:min, set-tm:min
974 @item tm:hour, set-tm:hour
976 @item tm:mday, set-tm:mday
977 Day of the month (1-31).
978 @item tm:mon, set-tm:mon
980 @item tm:year, set-tm:year
981 Year (70-), the year minus 1900.
982 @item tm:wday, set-tm:wday
983 Day of the week (0-6) with Sunday represented as 0.
984 @item tm:yday, set-tm:yday
985 Day of the year (0-364, 365 in leap years).
986 @item tm:isdst, set-tm:isdst
987 Daylight saving indicator (0 for "no", greater than 0 for "yes", less than
989 @item tm:gmtoff, set-tm:gmtoff
990 Time zone offset in seconds west of UTC (-46800 to 43200).
991 @item tm:zone, set-tm:zone
992 Time zone label (a string), not necessarily unique.
995 @deffn {Scheme Procedure} localtime time [zone]
996 @deffnx {C Function} scm_localtime (time, zone)
997 Return an object representing the broken down components of
998 @var{time}, an integer like the one returned by
999 @code{current-time}. The time zone for the calculation is
1000 optionally specified by @var{zone} (a string), otherwise the
1001 @code{TZ} environment variable or the system default is used.
1004 @deffn {Scheme Procedure} gmtime time
1005 @deffnx {C Function} scm_gmtime (time)
1006 Return an object representing the broken down components of
1007 @var{time}, an integer like the one returned by
1008 @code{current-time}. The values are calculated for UTC.
1011 @deffn {Scheme Procedure} mktime sbd_time [zone]
1012 @deffnx {C Function} scm_mktime (sbd_time, zone)
1013 @var{bd-time} is an object representing broken down time and @code{zone}
1014 is an optional time zone specifier (otherwise the TZ environment variable
1015 or the system default is used).
1017 Returns a pair: the car is a corresponding
1018 integer time value like that returned
1019 by @code{current-time}; the cdr is a broken down time object, similar to
1020 as @var{bd-time} but with normalized values.
1023 @deffn {Scheme Procedure} tzset
1024 @deffnx {C Function} scm_tzset ()
1025 Initialize the timezone from the TZ environment variable
1026 or the system default. It's not usually necessary to call this procedure
1027 since it's done automatically by other procedures that depend on the
1031 @deffn {Scheme Procedure} strftime format stime
1032 @deffnx {C Function} scm_strftime (format, stime)
1033 Formats a time specification @var{time} using @var{template}. @var{time}
1034 is an object with time components in the form returned by @code{localtime}
1035 or @code{gmtime}. @var{template} is a string which can include formatting
1036 specifications introduced by a @code{%} character. The formatting of
1037 month and day names is dependent on the current locale. The value returned
1038 is the formatted string.
1039 @xref{Formatting Date and Time, , , libc, The GNU C Library Reference Manual}.)
1042 (strftime "%c" (localtime (current-time)))
1043 @result{} "Mon Mar 11 20:17:43 2002"
1047 @deffn {Scheme Procedure} strptime format string
1048 @deffnx {C Function} scm_strptime (format, string)
1049 Performs the reverse action to @code{strftime}, parsing
1050 @var{string} according to the specification supplied in
1051 @var{template}. The interpretation of month and day names is
1052 dependent on the current locale. The value returned is a pair.
1053 The car has an object with time components
1054 in the form returned by @code{localtime} or @code{gmtime},
1055 but the time zone components
1056 are not usefully set.
1057 The cdr reports the number of characters from @var{string}
1058 which were used for the conversion.
1061 @defvar internal-time-units-per-second
1062 The value of this variable is the number of time units per second
1063 reported by the following procedures.
1066 @deffn {Scheme Procedure} times
1067 @deffnx {C Function} scm_times ()
1068 Return an object with information about real and processor
1069 time. The following procedures accept such an object as an
1070 argument and return a selected component:
1074 The current real time, expressed as time units relative to an
1077 The CPU time units used by the calling process.
1079 The CPU time units used by the system on behalf of the calling
1082 The CPU time units used by terminated child processes of the
1083 calling process, whose status has been collected (e.g., using
1086 Similarly, the CPU times units used by the system on behalf of
1087 terminated child processes.
1091 @deffn {Scheme Procedure} get-internal-real-time
1092 @deffnx {C Function} scm_get_internal_real_time ()
1093 Return the number of time units since the interpreter was
1097 @deffn {Scheme Procedure} get-internal-run-time
1098 @deffnx {C Function} scm_get_internal_run_time ()
1099 Return the number of time units of processor time used by the
1100 interpreter. Both @emph{system} and @emph{user} time are
1101 included but subprocesses are not.
1104 @node Runtime Environment
1105 @section Runtime Environment
1107 @deffn {Scheme Procedure} program-arguments
1108 @deffnx {Scheme Procedure} command-line
1109 @deffnx {C Function} scm_program_arguments ()
1110 Return the list of command line arguments passed to Guile, as a list of
1111 strings. The list includes the invoked program name, which is usually
1112 @code{"guile"}, but excludes switches and parameters for command line
1113 options like @code{-e} and @code{-l}.
1116 @deffn {Scheme Procedure} getenv nam
1117 @deffnx {C Function} scm_getenv (nam)
1118 Looks up the string @var{name} in the current environment. The return
1119 value is @code{#f} unless a string of the form @code{NAME=VALUE} is
1120 found, in which case the string @code{VALUE} is returned.
1123 @deffn {Scheme Procedure} setenv name value
1124 Modifies the environment of the current process, which is
1125 also the default environment inherited by child processes.
1127 If @var{value} is @code{#f}, then @var{name} is removed from the
1128 environment. Otherwise, the string @var{name}=@var{value} is added
1129 to the environment, replacing any existing string with name matching
1132 The return value is unspecified.
1135 @deffn {Scheme Procedure} unsetenv name
1136 Remove variable @var{name} from the environment. The
1137 name can not contain a @samp{=} character.
1140 @deffn {Scheme Procedure} environ [env]
1141 @deffnx {C Function} scm_environ (env)
1142 If @var{env} is omitted, return the current environment (in the
1143 Unix sense) as a list of strings. Otherwise set the current
1144 environment, which is also the default environment for child
1145 processes, to the supplied list of strings. Each member of
1146 @var{env} should be of the form @code{NAME=VALUE} and values of
1147 @code{NAME} should not be duplicated. If @var{env} is supplied
1148 then the return value is unspecified.
1151 @deffn {Scheme Procedure} putenv str
1152 @deffnx {C Function} scm_putenv (str)
1153 Modifies the environment of the current process, which is
1154 also the default environment inherited by child processes.
1156 If @var{string} is of the form @code{NAME=VALUE} then it will be written
1157 directly into the environment, replacing any existing environment string
1159 name matching @code{NAME}. If @var{string} does not contain an equal
1160 sign, then any existing string with name matching @var{string} will
1163 The return value is unspecified.
1171 @deffn {Scheme Procedure} chdir str
1172 @deffnx {C Function} scm_chdir (str)
1173 Change the current working directory to @var{path}.
1174 The return value is unspecified.
1178 @deffn {Scheme Procedure} getcwd
1179 @deffnx {C Function} scm_getcwd ()
1180 Return the name of the current working directory.
1183 @deffn {Scheme Procedure} umask [mode]
1184 @deffnx {C Function} scm_umask (mode)
1185 If @var{mode} is omitted, returns a decimal number representing the current
1186 file creation mask. Otherwise the file creation mask is set to
1187 @var{mode} and the previous value is returned.
1189 E.g., @code{(umask #o022)} sets the mask to octal 22, decimal 18.
1192 @deffn {Scheme Procedure} chroot path
1193 @deffnx {C Function} scm_chroot (path)
1194 Change the root directory to that specified in @var{path}.
1195 This directory will be used for path names beginning with
1196 @file{/}. The root directory is inherited by all children
1197 of the current process. Only the superuser may change the
1201 @deffn {Scheme Procedure} getpid
1202 @deffnx {C Function} scm_getpid ()
1203 Return an integer representing the current process ID.
1206 @deffn {Scheme Procedure} getgroups
1207 @deffnx {C Function} scm_getgroups ()
1208 Return a vector of integers representing the current
1209 supplementary group IDs.
1212 @deffn {Scheme Procedure} getppid
1213 @deffnx {C Function} scm_getppid ()
1214 Return an integer representing the process ID of the parent
1218 @deffn {Scheme Procedure} getuid
1219 @deffnx {C Function} scm_getuid ()
1220 Return an integer representing the current real user ID.
1223 @deffn {Scheme Procedure} getgid
1224 @deffnx {C Function} scm_getgid ()
1225 Return an integer representing the current real group ID.
1228 @deffn {Scheme Procedure} geteuid
1229 @deffnx {C Function} scm_geteuid ()
1230 Return an integer representing the current effective user ID.
1231 If the system does not support effective IDs, then the real ID
1232 is returned. @code{(provided? 'EIDs)} reports whether the
1233 system supports effective IDs.
1236 @deffn {Scheme Procedure} getegid
1237 @deffnx {C Function} scm_getegid ()
1238 Return an integer representing the current effective group ID.
1239 If the system does not support effective IDs, then the real ID
1240 is returned. @code{(provided? 'EIDs)} reports whether the
1241 system supports effective IDs.
1244 @deffn {Scheme Procedure} setuid id
1245 @deffnx {C Function} scm_setuid (id)
1246 Sets both the real and effective user IDs to the integer @var{id}, provided
1247 the process has appropriate privileges.
1248 The return value is unspecified.
1251 @deffn {Scheme Procedure} setgid id
1252 @deffnx {C Function} scm_setgid (id)
1253 Sets both the real and effective group IDs to the integer @var{id}, provided
1254 the process has appropriate privileges.
1255 The return value is unspecified.
1258 @deffn {Scheme Procedure} seteuid id
1259 @deffnx {C Function} scm_seteuid (id)
1260 Sets the effective user ID to the integer @var{id}, provided the process
1261 has appropriate privileges. If effective IDs are not supported, the
1262 real ID is set instead -- @code{(provided? 'EIDs)} reports whether the
1263 system supports effective IDs.
1264 The return value is unspecified.
1267 @deffn {Scheme Procedure} setegid id
1268 @deffnx {C Function} scm_setegid (id)
1269 Sets the effective group ID to the integer @var{id}, provided the process
1270 has appropriate privileges. If effective IDs are not supported, the
1271 real ID is set instead -- @code{(provided? 'EIDs)} reports whether the
1272 system supports effective IDs.
1273 The return value is unspecified.
1276 @deffn {Scheme Procedure} getpgrp
1277 @deffnx {C Function} scm_getpgrp ()
1278 Return an integer representing the current process group ID.
1279 This is the POSIX definition, not BSD.
1282 @deffn {Scheme Procedure} setpgid pid pgid
1283 @deffnx {C Function} scm_setpgid (pid, pgid)
1284 Move the process @var{pid} into the process group @var{pgid}. @var{pid} or
1285 @var{pgid} must be integers: they can be zero to indicate the ID of the
1287 Fails on systems that do not support job control.
1288 The return value is unspecified.
1291 @deffn {Scheme Procedure} setsid
1292 @deffnx {C Function} scm_setsid ()
1293 Creates a new session. The current process becomes the session leader
1294 and is put in a new process group. The process will be detached
1295 from its controlling terminal if it has one.
1296 The return value is an integer representing the new process group ID.
1299 @deffn {Scheme Procedure} waitpid pid [options]
1300 @deffnx {C Function} scm_waitpid (pid, options)
1301 This procedure collects status information from a child process which
1302 has terminated or (optionally) stopped. Normally it will
1303 suspend the calling process until this can be done. If more than one
1304 child process is eligible then one will be chosen by the operating system.
1306 The value of @var{pid} determines the behaviour:
1309 @item @var{pid} greater than 0
1310 Request status information from the specified child process.
1311 @item @var{pid} equal to -1 or WAIT_ANY
1312 Request status information for any child process.
1313 @item @var{pid} equal to 0 or WAIT_MYPGRP
1314 Request status information for any child process in the current process
1316 @item @var{pid} less than -1
1317 Request status information for any child process whose process group ID
1321 The @var{options} argument, if supplied, should be the bitwise OR of the
1322 values of zero or more of the following variables:
1325 Return immediately even if there are no child processes to be collected.
1329 Report status information for stopped processes as well as terminated
1333 The return value is a pair containing:
1337 The process ID of the child process, or 0 if @code{WNOHANG} was
1338 specified and no process was collected.
1340 The integer status value.
1345 functions can be used to decode the process status code returned
1348 @deffn {Scheme Procedure} status:exit-val status
1349 @deffnx {C Function} scm_status_exit_val (status)
1350 Return the exit status value, as would be set if a process
1351 ended normally through a call to @code{exit} or @code{_exit},
1352 if any, otherwise @code{#f}.
1355 @deffn {Scheme Procedure} status:term-sig status
1356 @deffnx {C Function} scm_status_term_sig (status)
1357 Return the signal number which terminated the process, if any,
1358 otherwise @code{#f}.
1361 @deffn {Scheme Procedure} status:stop-sig status
1362 @deffnx {C Function} scm_status_stop_sig (status)
1363 Return the signal number which stopped the process, if any,
1364 otherwise @code{#f}.
1367 @deffn {Scheme Procedure} system [cmd]
1368 @deffnx {C Function} scm_system (cmd)
1369 Execute @var{cmd} using the operating system's "command
1370 processor". Under Unix this is usually the default shell
1371 @code{sh}. The value returned is @var{cmd}'s exit status as
1372 returned by @code{waitpid}, which can be interpreted using the
1375 If @code{system} is called without arguments, return a boolean
1376 indicating whether the command processor is available.
1379 @deffn {Scheme Procedure} primitive-exit [status]
1380 @deffnx {C Function} scm_primitive_exit (status)
1381 Terminate the current process without unwinding the Scheme stack.
1382 This is would typically be useful after a fork. The exit status
1383 is @var{status} if supplied, otherwise zero.
1386 @deffn {Scheme Procedure} execl filename . args
1387 @deffnx {C Function} scm_execl (filename, args)
1388 Executes the file named by @var{path} as a new process image.
1389 The remaining arguments are supplied to the process; from a C program
1390 they are accessible as the @code{argv} argument to @code{main}.
1391 Conventionally the first @var{arg} is the same as @var{path}.
1392 All arguments must be strings.
1394 If @var{arg} is missing, @var{path} is executed with a null
1395 argument list, which may have system-dependent side-effects.
1397 This procedure is currently implemented using the @code{execv} system
1398 call, but we call it @code{execl} because of its Scheme calling interface.
1401 @deffn {Scheme Procedure} execlp filename . args
1402 @deffnx {C Function} scm_execlp (filename, args)
1403 Similar to @code{execl}, however if
1404 @var{filename} does not contain a slash
1405 then the file to execute will be located by searching the
1406 directories listed in the @code{PATH} environment variable.
1408 This procedure is currently implemented using the @code{execvp} system
1409 call, but we call it @code{execlp} because of its Scheme calling interface.
1412 @deffn {Scheme Procedure} execle filename env . args
1413 @deffnx {C Function} scm_execle (filename, env, args)
1414 Similar to @code{execl}, but the environment of the new process is
1415 specified by @var{env}, which must be a list of strings as returned by the
1416 @code{environ} procedure.
1418 This procedure is currently implemented using the @code{execve} system
1419 call, but we call it @code{execle} because of its Scheme calling interface.
1422 @deffn {Scheme Procedure} primitive-fork
1423 @deffnx {C Function} scm_fork ()
1424 Creates a new "child" process by duplicating the current "parent" process.
1425 In the child the return value is 0. In the parent the return value is
1426 the integer process ID of the child.
1428 This procedure has been renamed from @code{fork} to avoid a naming conflict
1432 @deffn {Scheme Procedure} nice incr
1433 @deffnx {C Function} scm_nice (incr)
1434 Increment the priority of the current process by @var{incr}. A higher
1435 priority value means that the process runs less often.
1436 The return value is unspecified.
1439 @deffn {Scheme Procedure} setpriority which who prio
1440 @deffnx {C Function} scm_setpriority (which, who, prio)
1441 Set the scheduling priority of the process, process group
1442 or user, as indicated by @var{which} and @var{who}. @var{which}
1443 is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
1444 or @code{PRIO_USER}, and @var{who} is interpreted relative to
1445 @var{which} (a process identifier for @code{PRIO_PROCESS},
1446 hhhhprocess group identifier for @code{PRIO_PGRP}, and a user
1447 identifier for @code{PRIO_USER}. A zero value of @var{who}
1448 denotes the current process, process group, or user.
1449 @var{prio} is a value in the range -20 and 20, the default
1450 priority is 0; lower priorities cause more favorable
1451 scheduling. Sets the priority of all of the specified
1452 processes. Only the super-user may lower priorities.
1453 The return value is not specified.
1456 @deffn {Scheme Procedure} getpriority which who
1457 @deffnx {C Function} scm_getpriority (which, who)
1458 Return the scheduling priority of the process, process group
1459 or user, as indicated by @var{which} and @var{who}. @var{which}
1460 is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
1461 or @code{PRIO_USER}, and @var{who} is interpreted relative to
1462 @var{which} (a process identifier for @code{PRIO_PROCESS},
1463 process group identifier for @code{PRIO_PGRP}, and a user
1464 identifier for @code{PRIO_USER}. A zero value of @var{who}
1465 denotes the current process, process group, or user. Return
1466 the highest priority (lowest numerical value) of any of the
1467 specified processes.
1474 Procedures to raise, handle and wait for signals.
1476 @deffn {Scheme Procedure} kill pid sig
1477 @deffnx {C Function} scm_kill (pid, sig)
1478 Sends a signal to the specified process or group of processes.
1480 @var{pid} specifies the processes to which the signal is sent:
1483 @item @var{pid} greater than 0
1484 The process whose identifier is @var{pid}.
1485 @item @var{pid} equal to 0
1486 All processes in the current process group.
1487 @item @var{pid} less than -1
1488 The process group whose identifier is -@var{pid}
1489 @item @var{pid} equal to -1
1490 If the process is privileged, all processes except for some special
1491 system processes. Otherwise, all processes with the current effective
1495 @var{sig} should be specified using a variable corresponding to
1496 the Unix symbolic name, e.g.,
1507 @deffn {Scheme Procedure} raise sig
1508 @deffnx {C Function} scm_raise (sig)
1509 Sends a specified signal @var{sig} to the current process, where
1510 @var{sig} is as described for the kill procedure.
1513 @deffn {Scheme Procedure} sigaction signum [handler [flags [thread]]]
1514 @deffnx {C Function} scm_sigaction (signum, handler, flags)
1515 @deffnx {C Function} scm_sigaction_for_thread (signum, handler, flags, thread)
1516 Install or report the signal handler for a specified signal.
1518 @var{signum} is the signal number, which can be specified using the value
1519 of variables such as @code{SIGINT}.
1521 If @var{handler} is omitted, @code{sigaction} returns a pair: the
1523 signal hander, which will be either an integer with the value @code{SIG_DFL}
1524 (default action) or @code{SIG_IGN} (ignore), or the Scheme procedure which
1525 handles the signal, or @code{#f} if a non-Scheme procedure handles the
1526 signal. The CDR contains the current @code{sigaction} flags for the handler.
1528 If @var{handler} is provided, it is installed as the new handler for
1529 @var{signum}. @var{handler} can be a Scheme procedure taking one
1530 argument, or the value of @code{SIG_DFL} (default action) or
1531 @code{SIG_IGN} (ignore), or @code{#f} to restore whatever signal handler
1532 was installed before @code{sigaction} was first used. When a scheme
1533 procedure has been specified, that procedure will run in the given
1534 @var{thread}. When no thread has been given, the thread that made this
1535 call to @code{sigaction} is used.
1537 Flags can optionally be specified for the new handler (@code{SA_RESTART}
1538 will always be added if it's available and the system is using
1539 restartable system calls.) The return value is a pair with information
1540 about the old handler as described above.
1542 This interface does not provide access to the "signal blocking"
1543 facility. Maybe this is not needed, since the thread support may
1544 provide solutions to the problem of consistent access to data
1548 @deffn {Scheme Procedure} restore-signals
1549 @deffnx {C Function} scm_restore_signals ()
1550 Return all signal handlers to the values they had before any call to
1551 @code{sigaction} was made. The return value is unspecified.
1554 @deffn {Scheme Procedure} alarm i
1555 @deffnx {C Function} scm_alarm (i)
1556 Set a timer to raise a @code{SIGALRM} signal after the specified
1557 number of seconds (an integer). It's advisable to install a signal
1559 @code{SIGALRM} beforehand, since the default action is to terminate
1562 The return value indicates the time remaining for the previous alarm,
1563 if any. The new value replaces the previous alarm. If there was
1564 no previous alarm, the return value is zero.
1567 @deffn {Scheme Procedure} pause
1568 @deffnx {C Function} scm_pause ()
1569 Pause the current process (thread?) until a signal arrives whose
1570 action is to either terminate the current process or invoke a
1571 handler procedure. The return value is unspecified.
1574 @deffn {Scheme Procedure} sleep i
1575 @deffnx {C Function} scm_sleep (i)
1576 Wait for the given number of seconds (an integer) or until a signal
1577 arrives. The return value is zero if the time elapses or the number
1578 of seconds remaining otherwise.
1581 @deffn {Scheme Procedure} usleep i
1582 @deffnx {C Function} scm_usleep (i)
1583 Sleep for I microseconds. @code{usleep} is not available on
1587 @deffn {Scheme Procedure} setitimer which_timer interval_seconds interval_microseconds value_seconds value_microseconds
1588 @deffnx {C Function} scm_setitimer (which_timer, interval_seconds, interval_microseconds, value_seconds, value_microseconds)
1589 Set the timer specified by @var{which_timer} according to the given
1590 @var{interval_seconds}, @var{interval_microseconds},
1591 @var{value_seconds}, and @var{value_microseconds} values.
1593 Return information about the timer's previous setting.
1594 Errors are handled as described in the guile info pages under ``POSIX
1595 Interface Conventions''.
1597 The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
1598 and @code{ITIMER_PROF}.
1600 The return value will be a list of two cons pairs representing the
1601 current state of the given timer. The first pair is the seconds and
1602 microseconds of the timer @code{it_interval}, and the second pair is
1603 the seconds and microseconds of the timer @code{it_value}.
1606 @deffn {Scheme Procedure} getitimer which_timer
1607 @deffnx {C Function} scm_getitimer (which_timer)
1608 Return information about the timer specified by @var{which_timer}
1609 Errors are handled as described in the guile info pages under ``POSIX
1610 Interface Conventions''.
1612 The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
1613 and @code{ITIMER_PROF}.
1615 The return value will be a list of two cons pairs representing the
1616 current state of the given timer. The first pair is the seconds and
1617 microseconds of the timer @code{it_interval}, and the second pair is
1618 the seconds and microseconds of the timer @code{it_value}.
1622 @node Terminals and Ptys
1623 @section Terminals and Ptys
1625 @deffn {Scheme Procedure} isatty? port
1626 @deffnx {C Function} scm_isatty_p (port)
1627 Return @code{#t} if @var{port} is using a serial non--file
1628 device, otherwise @code{#f}.
1631 @deffn {Scheme Procedure} ttyname port
1632 @deffnx {C Function} scm_ttyname (port)
1633 Return a string with the name of the serial terminal device
1634 underlying @var{port}.
1637 @deffn {Scheme Procedure} ctermid
1638 @deffnx {C Function} scm_ctermid ()
1639 Return a string containing the file name of the controlling
1640 terminal for the current process.
1643 @deffn {Scheme Procedure} tcgetpgrp port
1644 @deffnx {C Function} scm_tcgetpgrp (port)
1645 Return the process group ID of the foreground process group
1646 associated with the terminal open on the file descriptor
1647 underlying @var{port}.
1649 If there is no foreground process group, the return value is a
1650 number greater than 1 that does not match the process group ID
1651 of any existing process group. This can happen if all of the
1652 processes in the job that was formerly the foreground job have
1653 terminated, and no other job has yet been moved into the
1657 @deffn {Scheme Procedure} tcsetpgrp port pgid
1658 @deffnx {C Function} scm_tcsetpgrp (port, pgid)
1659 Set the foreground process group ID for the terminal used by the file
1660 descriptor underlying @var{port} to the integer @var{pgid}.
1662 must be a member of the same session as @var{pgid} and must have the same
1663 controlling terminal. The return value is unspecified.
1669 The following procedures provide an interface to the @code{popen} and
1670 @code{pclose} system routines. The code is in a separate "popen"
1674 (use-modules (ice-9 popen))
1678 @deffn {Scheme Procedure} open-pipe command modes
1679 Executes the shell command @var{command} (a string) in a subprocess.
1680 A pipe to the process is created and returned. @var{modes} specifies
1681 whether an input or output pipe to the process is created: it should
1682 be the value of @code{OPEN_READ} or @code{OPEN_WRITE}.
1685 @deffn {Scheme Procedure} open-input-pipe command
1686 Equivalent to @code{open-pipe} with mode @code{OPEN_READ}.
1689 (read-line (open-input-pipe "date"))
1690 @result{} "Mon Mar 11 20:10:44 GMT 2002"
1693 @result{} (24160 . 0)
1697 @deffn {Scheme Procedure} open-output-pipe command
1698 Equivalent to @code{open-pipe} with mode @code{OPEN_WRITE}.
1702 @deffn {Scheme Procedure} close-pipe port
1703 Closes the pipe created by @code{open-pipe}, then waits for the process
1704 to terminate and returns its status value, @xref{Processes, waitpid}, for
1705 information on how to interpret this value.
1707 @code{close-port} (@pxref{Closing, close-port}) can also be used to
1708 close a pipe, but doesn't return the status.
1715 * Network Address Conversion::
1716 * Network Databases::
1717 * Network Sockets and Communication::
1718 * Internet Socket Examples::
1721 @node Network Address Conversion
1722 @subsection Network Address Conversion
1724 This section describes procedures which convert internet addresses
1725 between numeric and string formats.
1727 @subsubsection IPv4 Address Conversion
1729 @deffn {Scheme Procedure} inet-aton address
1730 @deffnx {C Function} scm_inet_aton (address)
1731 Convert an IPv4 Internet address from printable string
1732 (dotted decimal notation) to an integer. E.g.,
1735 (inet-aton "127.0.0.1") @result{} 2130706433
1739 @deffn {Scheme Procedure} inet-ntoa inetid
1740 @deffnx {C Function} scm_inet_ntoa (inetid)
1741 Convert an IPv4 Internet address to a printable
1742 (dotted decimal notation) string. E.g.,
1745 (inet-ntoa 2130706433) @result{} "127.0.0.1"
1749 @deffn {Scheme Procedure} inet-netof address
1750 @deffnx {C Function} scm_inet_netof (address)
1751 Return the network number part of the given IPv4
1752 Internet address. E.g.,
1755 (inet-netof 2130706433) @result{} 127
1759 @deffn {Scheme Procedure} inet-lnaof address
1760 @deffnx {C Function} scm_lnaof (address)
1761 Return the local-address-with-network part of the given
1762 IPv4 Internet address, using the obsolete class A/B/C system.
1766 (inet-lnaof 2130706433) @result{} 1
1770 @deffn {Scheme Procedure} inet-makeaddr net lna
1771 @deffnx {C Function} scm_inet_makeaddr (net, lna)
1772 Make an IPv4 Internet address by combining the network number
1773 @var{net} with the local-address-within-network number
1777 (inet-makeaddr 127 1) @result{} 2130706433
1781 @subsubsection IPv6 Address Conversion
1783 @deffn {Scheme Procedure} inet-ntop family address
1784 @deffnx {C Function} scm_inet_ntop (family, address)
1785 Convert a network address into a printable string.
1786 Note that unlike the C version of this function,
1787 the input is an integer with normal host byte ordering.
1788 @var{family} can be @code{AF_INET} or @code{AF_INET6}. E.g.,
1791 (inet-ntop AF_INET 2130706433) @result{} "127.0.0.1"
1792 (inet-ntop AF_INET6 (- (expt 2 128) 1)) @result{}
1793 ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
1797 @deffn {Scheme Procedure} inet-pton family address
1798 @deffnx {C Function} scm_inet_pton (family, address)
1799 Convert a string containing a printable network address to
1800 an integer address. Note that unlike the C version of this
1802 the result is an integer with normal host byte ordering.
1803 @var{family} can be @code{AF_INET} or @code{AF_INET6}. E.g.,
1806 (inet-pton AF_INET "127.0.0.1") @result{} 2130706433
1807 (inet-pton AF_INET6 "::1") @result{} 1
1812 @node Network Databases
1813 @subsection Network Databases
1815 This section describes procedures which query various network databases.
1816 Care should be taken when using the database routines since they are not
1819 @subsubsection The Host Database
1821 A @dfn{host object} is a structure that represents what is known about a
1822 network host, and is the usual way of representing a system's network
1823 identity inside software.
1825 The following functions accept a host object and return a selected
1828 @deffn {Scheme Procedure} hostent:name host
1829 The "official" hostname for @var{host}.
1831 @deffn {Scheme Procedure} hostent:aliases host
1832 A list of aliases for @var{host}.
1834 @deffn {Scheme Procedure} hostent:addrtype host
1835 The host address type. For hosts with Internet addresses, this will
1836 return @code{AF_INET}.
1838 @deffn {Scheme Procedure} hostent:length host
1839 The length of each address for @var{host}, in bytes.
1841 @deffn {Scheme Procedure} hostent:addr-list host
1842 The list of network addresses associated with @var{host}.
1845 The following procedures are used to search the host database:
1847 @deffn {Scheme Procedure} gethost [host]
1848 @deffnx {Scheme Procedure} gethostbyname hostname
1849 @deffnx {Scheme Procedure} gethostbyaddr address
1850 @deffnx {C Function} scm_gethost (host)
1851 Look up a host by name or address, returning a host object. The
1852 @code{gethost} procedure will accept either a string name or an integer
1853 address; if given no arguments, it behaves like @code{gethostent} (see
1854 below). If a name or address is supplied but the address can not be
1855 found, an error will be thrown to one of the keys:
1856 @code{host-not-found}, @code{try-again}, @code{no-recovery} or
1857 @code{no-data}, corresponding to the equivalent @code{h_error} values.
1858 Unusual conditions may result in errors thrown to the
1859 @code{system-error} or @code{misc_error} keys.
1862 (gethost "www.gnu.org")
1863 @result{} #("www.gnu.org" () 2 4 (3353880842))
1865 (gethostbyname "www.emacs.org")
1866 @result{} #("emacs.org" ("www.emacs.org") 2 4 (1073448978))
1870 The following procedures may be used to step through the host
1871 database from beginning to end.
1873 @deffn {Scheme Procedure} sethostent [stayopen]
1874 Initialize an internal stream from which host objects may be read. This
1875 procedure must be called before any calls to @code{gethostent}, and may
1876 also be called afterward to reset the host entry stream. If
1877 @var{stayopen} is supplied and is not @code{#f}, the database is not
1878 closed by subsequent @code{gethostbyname} or @code{gethostbyaddr} calls,
1879 possibly giving an efficiency gain.
1882 @deffn {Scheme Procedure} gethostent
1883 Return the next host object from the host database, or @code{#f} if
1884 there are no more hosts to be found (or an error has been encountered).
1885 This procedure may not be used before @code{sethostent} has been called.
1888 @deffn {Scheme Procedure} endhostent
1889 Close the stream used by @code{gethostent}. The return value is unspecified.
1892 @deffn {Scheme Procedure} sethost [stayopen]
1893 @deffnx {C Function} scm_sethost (stayopen)
1894 If @var{stayopen} is omitted, this is equivalent to @code{endhostent}.
1895 Otherwise it is equivalent to @code{sethostent stayopen}.
1897 @subsubsection The Network Database
1899 The following functions accept an object representing a network
1900 and return a selected component:
1902 @deffn {Scheme Procedure} netent:name net
1903 The "official" network name.
1905 @deffn {Scheme Procedure} netent:aliases net
1906 A list of aliases for the network.
1908 @deffn {Scheme Procedure} netent:addrtype net
1909 The type of the network number. Currently, this returns only
1912 @deffn {Scheme Procedure} netent:net net
1916 The following procedures are used to search the network database:
1918 @deffn {Scheme Procedure} getnet [net]
1919 @deffnx {Scheme Procedure} getnetbyname net-name
1920 @deffnx {Scheme Procedure} getnetbyaddr net-number
1921 @deffnx {C Function} scm_getnet (net)
1922 Look up a network by name or net number in the network database. The
1923 @var{net-name} argument must be a string, and the @var{net-number}
1924 argument must be an integer. @code{getnet} will accept either type of
1925 argument, behaving like @code{getnetent} (see below) if no arguments are
1929 The following procedures may be used to step through the network
1930 database from beginning to end.
1932 @deffn {Scheme Procedure} setnetent [stayopen]
1933 Initialize an internal stream from which network objects may be read. This
1934 procedure must be called before any calls to @code{getnetent}, and may
1935 also be called afterward to reset the net entry stream. If
1936 @var{stayopen} is supplied and is not @code{#f}, the database is not
1937 closed by subsequent @code{getnetbyname} or @code{getnetbyaddr} calls,
1938 possibly giving an efficiency gain.
1941 @deffn {Scheme Procedure} getnetent
1942 Return the next entry from the network database.
1945 @deffn {Scheme Procedure} endnetent
1946 Close the stream used by @code{getnetent}. The return value is unspecified.
1949 @deffn {Scheme Procedure} setnet [stayopen]
1950 @deffnx {C Function} scm_setnet (stayopen)
1951 If @var{stayopen} is omitted, this is equivalent to @code{endnetent}.
1952 Otherwise it is equivalent to @code{setnetent stayopen}.
1955 @subsubsection The Protocol Database
1957 The following functions accept an object representing a protocol
1958 and return a selected component:
1960 @deffn {Scheme Procedure} protoent:name protocol
1961 The "official" protocol name.
1963 @deffn {Scheme Procedure} protoent:aliases protocol
1964 A list of aliases for the protocol.
1966 @deffn {Scheme Procedure} protoent:proto protocol
1967 The protocol number.
1970 The following procedures are used to search the protocol database:
1972 @deffn {Scheme Procedure} getproto [protocol]
1973 @deffnx {Scheme Procedure} getprotobyname name
1974 @deffnx {Scheme Procedure} getprotobynumber number
1975 @deffnx {C Function} scm_getproto (protocol)
1976 Look up a network protocol by name or by number. @code{getprotobyname}
1977 takes a string argument, and @code{getprotobynumber} takes an integer
1978 argument. @code{getproto} will accept either type, behaving like
1979 @code{getprotoent} (see below) if no arguments are supplied.
1982 The following procedures may be used to step through the protocol
1983 database from beginning to end.
1985 @deffn {Scheme Procedure} setprotoent [stayopen]
1986 Initialize an internal stream from which protocol objects may be read. This
1987 procedure must be called before any calls to @code{getprotoent}, and may
1988 also be called afterward to reset the protocol entry stream. If
1989 @var{stayopen} is supplied and is not @code{#f}, the database is not
1990 closed by subsequent @code{getprotobyname} or @code{getprotobynumber} calls,
1991 possibly giving an efficiency gain.
1994 @deffn {Scheme Procedure} getprotoent
1995 Return the next entry from the protocol database.
1998 @deffn {Scheme Procedure} endprotoent
1999 Close the stream used by @code{getprotoent}. The return value is unspecified.
2002 @deffn {Scheme Procedure} setproto [stayopen]
2003 @deffnx {C Function} scm_setproto (stayopen)
2004 If @var{stayopen} is omitted, this is equivalent to @code{endprotoent}.
2005 Otherwise it is equivalent to @code{setprotoent stayopen}.
2008 @subsubsection The Service Database
2010 The following functions accept an object representing a service
2011 and return a selected component:
2013 @deffn {Scheme Procedure} servent:name serv
2014 The "official" name of the network service.
2016 @deffn {Scheme Procedure} servent:aliases serv
2017 A list of aliases for the network service.
2019 @deffn {Scheme Procedure} servent:port serv
2020 The Internet port used by the service.
2022 @deffn {Scheme Procedure} servent:proto serv
2023 The protocol used by the service. A service may be listed many times
2024 in the database under different protocol names.
2027 The following procedures are used to search the service database:
2029 @deffn {Scheme Procedure} getserv [name [protocol]]
2030 @deffnx {Scheme Procedure} getservbyname name protocol
2031 @deffnx {Scheme Procedure} getservbyport port protocol
2032 @deffnx {C Function} scm_getserv (name, protocol)
2033 Look up a network service by name or by service number, and return a
2034 network service object. The @var{protocol} argument specifies the name
2035 of the desired protocol; if the protocol found in the network service
2036 database does not match this name, a system error is signalled.
2038 The @code{getserv} procedure will take either a service name or number
2039 as its first argument; if given no arguments, it behaves like
2040 @code{getservent} (see below).
2043 (getserv "imap" "tcp")
2044 @result{} #("imap2" ("imap") 143 "tcp")
2046 (getservbyport 88 "udp")
2047 @result{} #("kerberos" ("kerberos5" "krb5") 88 "udp")
2051 The following procedures may be used to step through the service
2052 database from beginning to end.
2054 @deffn {Scheme Procedure} setservent [stayopen]
2055 Initialize an internal stream from which service objects may be read. This
2056 procedure must be called before any calls to @code{getservent}, and may
2057 also be called afterward to reset the service entry stream. If
2058 @var{stayopen} is supplied and is not @code{#f}, the database is not
2059 closed by subsequent @code{getservbyname} or @code{getservbyport} calls,
2060 possibly giving an efficiency gain.
2063 @deffn {Scheme Procedure} getservent
2064 Return the next entry from the services database.
2067 @deffn {Scheme Procedure} endservent
2068 Close the stream used by @code{getservent}. The return value is unspecified.
2071 @deffn {Scheme Procedure} setserv [stayopen]
2072 @deffnx {C Function} scm_setserv (stayopen)
2073 If @var{stayopen} is omitted, this is equivalent to @code{endservent}.
2074 Otherwise it is equivalent to @code{setservent stayopen}.
2077 @node Network Sockets and Communication
2078 @subsection Network Sockets and Communication
2080 Socket ports can be created using @code{socket} and @code{socketpair}.
2081 The ports are initially unbuffered, to make reading and writing to the
2082 same port more reliable. A buffer can be added to the port using
2083 @code{setvbuf}, @xref{Ports and File Descriptors}.
2085 The convention used for "host" vs "network" addresses is that addresses
2086 are always held in host order at the Scheme level. The procedures in
2087 this section automatically convert between host and network order when
2088 required. The arguments and return values are thus in host order.
2090 @deffn {Scheme Procedure} socket family style proto
2091 @deffnx {C Function} scm_socket (family, style, proto)
2092 Return a new socket port of the type specified by @var{family},
2093 @var{style} and @var{proto}. All three parameters are
2094 integers. Supported values for @var{family} are
2095 @code{AF_UNIX}, @code{AF_INET} and @code{AF_INET6}.
2096 Typical values for @var{style} are @code{SOCK_STREAM},
2097 @code{SOCK_DGRAM} and @code{SOCK_RAW}.
2099 @var{proto} can be obtained from a protocol name using
2100 @code{getprotobyname}. A value of zero specifies the default
2101 protocol, which is usually right.
2103 A single socket port cannot by used for communication until it
2104 has been connected to another socket.
2107 @deffn {Scheme Procedure} socketpair family style proto
2108 @deffnx {C Function} scm_socketpair (family, style, proto)
2109 Return a pair of connected (but unnamed) socket ports of the
2110 type specified by @var{family}, @var{style} and @var{proto}.
2111 Many systems support only socket pairs of the @code{AF_UNIX}
2112 family. Zero is likely to be the only meaningful value for
2116 @deffn {Scheme Procedure} getsockopt sock level optname
2117 @deffnx {C Function} scm_getsockopt (sock, level, optname)
2118 Return the value of a particular socket option for the socket
2119 port @var{sock}. @var{level} is an integer code for type of
2120 option being requested, e.g., @code{SOL_SOCKET} for
2121 socket-level options. @var{optname} is an integer code for the
2122 option required and should be specified using one of the
2123 symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc.
2125 The returned value is typically an integer but @code{SO_LINGER}
2126 returns a pair of integers.
2129 @deffn {Scheme Procedure} setsockopt sock level optname value
2130 @deffnx {C Function} scm_setsockopt (sock, level, optname, value)
2131 Set the value of a particular socket option for the socket
2132 port @var{sock}. @var{level} is an integer code for type of option
2133 being set, e.g., @code{SOL_SOCKET} for socket-level options.
2135 integer code for the option to set and should be specified using one of
2136 the symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc.
2137 @var{value} is the value to which the option should be set. For
2138 most options this must be an integer, but for @code{SO_LINGER} it must
2141 The return value is unspecified.
2144 @deffn {Scheme Procedure} shutdown sock how
2145 @deffnx {C Function} scm_shutdown (sock, how)
2146 Sockets can be closed simply by using @code{close-port}. The
2147 @code{shutdown} procedure allows reception or transmission on a
2148 connection to be shut down individually, according to the parameter
2153 Stop receiving data for this socket. If further data arrives, reject it.
2155 Stop trying to transmit data from this socket. Discard any
2156 data waiting to be sent. Stop looking for acknowledgement of
2157 data already sent; don't retransmit it if it is lost.
2159 Stop both reception and transmission.
2162 The return value is unspecified.
2165 @deffn {Scheme Procedure} connect sock fam address . args
2166 @deffnx {C Function} scm_connect (sock, fam, address, args)
2167 Initiate a connection from a socket using a specified address
2168 family to the address
2169 specified by @var{address} and possibly @var{args}.
2170 The format required for @var{address}
2171 and @var{args} depends on the family of the socket.
2173 For a socket of family @code{AF_UNIX},
2174 only @var{address} is specified and must be a string with the
2175 filename where the socket is to be created.
2177 For a socket of family @code{AF_INET},
2178 @var{address} must be an integer IPv4 host address and
2179 @var{args} must be a single integer port number.
2181 For a socket of family @code{AF_INET6},
2182 @var{address} must be an integer IPv6 host address and
2183 @var{args} may be up to three integers:
2184 port [flowinfo] [scope_id],
2185 where flowinfo and scope_id default to zero.
2187 The return value is unspecified.
2190 @deffn {Scheme Procedure} bind sock fam address . args
2191 @deffnx {C Function} scm_bind (sock, fam, address, args)
2192 Assign an address to the socket port @var{sock}.
2193 Generally this only needs to be done for server sockets,
2194 so they know where to look for incoming connections. A socket
2195 without an address will be assigned one automatically when it
2196 starts communicating.
2198 The format of @var{address} and @var{args} depends
2199 on the family of the socket.
2201 For a socket of family @code{AF_UNIX}, only @var{address}
2202 is specified and must be a string with the filename where
2203 the socket is to be created.
2205 For a socket of family @code{AF_INET}, @var{address}
2206 must be an integer IPv4 address and @var{args}
2207 must be a single integer port number.
2209 The values of the following variables can also be used for
2213 Allow connections from any address.
2216 @defvar INADDR_LOOPBACK
2217 The address of the local host using the loopback device.
2220 @defvar INADDR_BROADCAST
2221 The broadcast address on the local network.
2228 For a socket of family @code{AF_INET6}, @var{address}
2229 must be an integer IPv6 address and @var{args}
2230 may be up to three integers:
2231 port [flowinfo] [scope_id],
2232 where flowinfo and scope_id default to zero.
2234 The return value is unspecified.
2237 @deffn {Scheme Procedure} listen sock backlog
2238 @deffnx {C Function} scm_listen (sock, backlog)
2239 Enable @var{sock} to accept connection
2240 requests. @var{backlog} is an integer specifying
2241 the maximum length of the queue for pending connections.
2242 If the queue fills, new clients will fail to connect until
2243 the server calls @code{accept} to accept a connection from
2246 The return value is unspecified.
2249 @deffn {Scheme Procedure} accept sock
2250 @deffnx {C Function} scm_accept (sock)
2251 Accept a connection on a bound, listening socket.
2253 are no pending connections in the queue, wait until
2254 one is available unless the non-blocking option has been
2257 The return value is a
2258 pair in which the @emph{car} is a new socket port for the
2260 the @emph{cdr} is an object with address information about the
2261 client which initiated the connection.
2263 @var{sock} does not become part of the
2264 connection and will continue to accept new requests.
2267 The following functions take a socket address object, as returned
2268 by @code{accept} and other procedures, and return a selected component.
2272 The socket family, typically equal to the value of @code{AF_UNIX} or
2275 If the socket family is @code{AF_UNIX}, returns the path of the
2276 filename the socket is based on.
2278 If the socket family is @code{AF_INET}, returns the Internet host
2281 If the socket family is @code{AF_INET}, returns the Internet port
2285 @deffn {Scheme Procedure} getsockname sock
2286 @deffnx {C Function} scm_getsockname (sock)
2287 Return the address of @var{sock}, in the same form as the
2288 object returned by @code{accept}. On many systems the address
2289 of a socket in the @code{AF_FILE} namespace cannot be read.
2292 @deffn {Scheme Procedure} getpeername sock
2293 @deffnx {C Function} scm_getpeername (sock)
2294 Return the address that @var{sock}
2295 is connected to, in the same form as the object returned by
2296 @code{accept}. On many systems the address of a socket in the
2297 @code{AF_FILE} namespace cannot be read.
2300 @deffn {Scheme Procedure} recv! sock buf [flags]
2301 @deffnx {C Function} scm_recv (sock, buf, flags)
2302 Receive data from a socket port.
2303 @var{sock} must already
2304 be bound to the address from which data is to be received.
2305 @var{buf} is a string into which
2306 the data will be written. The size of @var{buf} limits
2308 data which can be received: in the case of packet
2309 protocols, if a packet larger than this limit is encountered
2311 will be irrevocably lost.
2313 The optional @var{flags} argument is a value or
2314 bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.
2316 The value returned is the number of bytes read from the
2319 Note that the data is read directly from the socket file
2321 any unread buffered port data is ignored.
2324 @deffn {Scheme Procedure} send sock message [flags]
2325 @deffnx {C Function} scm_send (sock, message, flags)
2326 Transmit the string @var{message} on a socket port @var{sock}.
2327 @var{sock} must already be bound to a destination address. The
2328 value returned is the number of bytes transmitted --
2330 this to be less than the length of @var{message}
2332 set to be non-blocking. The optional @var{flags} argument
2334 bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.
2336 Note that the data is written directly to the socket
2338 any unflushed buffered port data is ignored.
2341 @deffn {Scheme Procedure} recvfrom! sock str [flags [start [end]]]
2342 @deffnx {C Function} scm_recvfrom (sock, str, flags, start, end)
2343 Return data from the socket port @var{sock} and also
2344 information about where the data was received from.
2345 @var{sock} must already be bound to the address from which
2346 data is to be received. @code{str}, is a string into which the
2347 data will be written. The size of @var{str} limits the amount
2348 of data which can be received: in the case of packet protocols,
2349 if a packet larger than this limit is encountered then some
2350 data will be irrevocably lost.
2352 The optional @var{flags} argument is a value or bitwise OR of
2353 @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
2355 The value returned is a pair: the @emph{car} is the number of
2356 bytes read from the socket and the @emph{cdr} an address object
2357 in the same form as returned by @code{accept}. The address
2358 will given as @code{#f} if not available, as is usually the
2359 case for stream sockets.
2361 The @var{start} and @var{end} arguments specify a substring of
2362 @var{str} to which the data should be written.
2364 Note that the data is read directly from the socket file
2365 descriptor: any unread buffered port data is ignored.
2368 @deffn {Scheme Procedure} sendto sock message fam address . args_and_flags
2369 @deffnx {C Function} scm_sendto (sock, message, fam, address, args_and_flags)
2370 Transmit the string @var{message} on the socket port
2372 destination address is specified using the @var{fam},
2374 @var{args_and_flags} arguments, in a similar way to the
2375 @code{connect} procedure. @var{args_and_flags} contains
2376 the usual connection arguments optionally followed by
2377 a flags argument, which is a value or
2378 bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.
2380 The value returned is the number of bytes transmitted --
2382 this to be less than the length of @var{message} if the
2384 set to be non-blocking.
2385 Note that the data is written directly to the socket
2387 any unflushed buffered port data is ignored.
2390 The following functions can be used to convert short and long integers
2391 between "host" and "network" order. Although the procedures above do
2392 this automatically for addresses, the conversion will still need to
2393 be done when sending or receiving encoded integer data from the network.
2395 @deffn {Scheme Procedure} htons value
2396 @deffnx {C Function} scm_htons (value)
2397 Convert a 16 bit quantity from host to network byte ordering.
2398 @var{value} is packed into 2 bytes, which are then converted
2399 and returned as a new integer.
2402 @deffn {Scheme Procedure} ntohs value
2403 @deffnx {C Function} scm_ntohs (value)
2404 Convert a 16 bit quantity from network to host byte ordering.
2405 @var{value} is packed into 2 bytes, which are then converted
2406 and returned as a new integer.
2409 @deffn {Scheme Procedure} htonl value
2410 @deffnx {C Function} scm_htonl (value)
2411 Convert a 32 bit quantity from host to network byte ordering.
2412 @var{value} is packed into 4 bytes, which are then converted
2413 and returned as a new integer.
2416 @deffn {Scheme Procedure} ntohl value
2417 @deffnx {C Function} scm_ntohl (value)
2418 Convert a 32 bit quantity from network to host byte ordering.
2419 @var{value} is packed into 4 bytes, which are then converted
2420 and returned as a new integer.
2423 These procedures are inconvenient to use at present, but consider:
2426 (define write-network-long
2427 (lambda (value port)
2428 (let ((v (make-uniform-vector 1 1 0)))
2429 (uniform-vector-set! v 0 (htonl value))
2430 (uniform-vector-write v port))))
2432 (define read-network-long
2434 (let ((v (make-uniform-vector 1 1 0)))
2435 (uniform-vector-read! v port)
2436 (ntohl (uniform-vector-ref v 0)))))
2440 @node Internet Socket Examples
2441 @subsection Network Socket Examples
2443 The following sections give examples of how to use network sockets.
2446 * Internet Socket Client::
2447 * Internet Socket Server::
2451 @node Internet Socket Client
2452 @subsubsection Internet Socket Client Example
2454 @cindex socket client example
2455 The following example demonstrates an Internet socket client.
2456 It connects to the HTTP daemon running on the local machine and
2457 returns the contents of the root index URL.
2460 (let ((s (socket AF_INET SOCK_STREAM 0)))
2461 (connect s AF_INET (inet-aton "127.0.0.1") 80)
2462 (display "GET / HTTP/1.0\r\n\r\n" s)
2464 (do ((line (read-line s) (read-line s)))
2465 ((eof-object? line))
2471 @node Internet Socket Server
2472 @subsubsection Internet Socket Server Example
2474 @cindex socket server example
2475 The following example shows a simple Internet server which listens on
2476 port 2904 for incoming connections and sends a greeting back to the
2480 (let ((s (socket AF_INET SOCK_STREAM 0)))
2481 (setsockopt s SOL_SOCKET SO_REUSEADDR 1)
2482 ;; Specific address?
2483 ;; (bind s AF_INET (inet-aton "127.0.0.1") 2904)
2484 (bind s AF_INET INADDR_ANY 2904)
2487 (simple-format #t "Listening for clients in pid: ~S" (getpid))
2491 (let* ((client-connection (accept s))
2492 (client-details (cdr client-connection))
2493 (client (car client-connection)))
2494 (simple-format #t "Got new client connection: ~S"
2497 (simple-format #t "Client address: ~S"
2499 (sockaddr:addr client-details)))
2501 ;; Send back the greeting to the client port
2502 (display "Hello client\r\n" client)
2507 @node System Identification
2508 @section System Identification
2510 This section lists the various procedures Guile provides for accessing
2511 information about the system it runs on.
2513 @deffn {Scheme Procedure} uname
2514 @deffnx {C Function} scm_uname ()
2515 Return an object with some information about the computer
2516 system the program is running on.
2519 The following procedures accept an object as returned by @code{uname}
2520 and return a selected component.
2523 @item utsname:sysname
2524 The name of the operating system.
2525 @item utsname:nodename
2526 The network name of the computer.
2527 @item utsname:release
2528 The current release level of the operating system implementation.
2529 @item utsname:version
2530 The current version level within the release of the operating system.
2531 @item utsname:machine
2532 A description of the hardware.
2535 @deffn {Scheme Procedure} gethostname
2536 @deffnx {C Function} scm_gethostname ()
2537 Return the host name of the current processor.
2540 @deffn {Scheme Procedure} sethostname name
2541 @deffnx {C Function} scm_sethostname (name)
2542 Set the host name of the current processor to @var{name}. May
2543 only be used by the superuser. The return value is not
2547 @c FIXME::martin: Not in libguile!
2548 @deffn {Scheme Procedure} software-type
2549 Return a symbol describing the current platform's operating system.
2550 This may be one of AIX, VMS, UNIX, COHERENT, WINDOWS, MS-DOS, OS/2,
2551 THINKC, AMIGA, ATARIST, MACH, or ACORN.
2553 Note that most varieties of Unix are considered to be simply "UNIX".
2554 That is because when a program depends on features that are not present
2555 on every operating system, it is usually better to test for the presence
2556 or absence of that specific feature. The return value of
2557 @code{software-type} should only be used for this purpose when there is
2558 no other easy or unambiguous way of detecting such features.
2564 @deffn {Scheme Procedure} setlocale category [locale]
2565 @deffnx {C Function} scm_setlocale (category, locale)
2566 If @var{locale} is omitted, return the current value of the
2567 specified locale category as a system-dependent string.
2568 @var{category} should be specified using the values
2569 @code{LC_COLLATE}, @code{LC_ALL} etc.
2571 Otherwise the specified locale category is set to the string
2572 @var{locale} and the new value is returned as a
2573 system-dependent string. If @var{locale} is an empty string,
2574 the locale will be set using environment variables.
2580 Please note that the procedures in this section are not suited for
2581 strong encryption, they are only interfaces to the well-known and
2582 common system library functions of the same name. They are just as good
2583 (or bad) as the underlying functions, so you should refer to your system
2584 documentation before using them.
2586 @deffn {Scheme Procedure} crypt key salt
2587 @deffnx {C Function} scm_crypt (key, salt)
2588 Encrypt @var{key} using @var{salt} as the salt value to the
2589 crypt(3) library call.
2592 Although @code{getpass} is not an encryption procedure per se, it
2593 appears here because it is often used in combination with @code{crypt}:
2595 @deffn {Scheme Procedure} getpass prompt
2596 @deffnx {C Function} scm_getpass (prompt)
2597 Display @var{prompt} to the standard error output and read
2598 a password from @file{/dev/tty}. If this file is not
2599 accessible, it reads from standard input. The password may be
2600 up to 127 characters in length. Additional characters and the
2601 terminating newline character are discarded. While reading
2602 the password, echoing and the generation of signals by special
2603 characters is disabled.