2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
8 @section @acronym{POSIX} System Calls and Networking
12 * Conventions:: Conventions employed by the POSIX interface.
13 * Ports and File Descriptors:: Scheme ``ports'' and Unix file descriptors
14 have different representations.
15 * File System:: stat, chown, chmod, etc.
16 * User Information:: Retrieving a user's GECOS (/etc/passwd) entry.
17 * Time:: gettimeofday, localtime, strftime, etc.
18 * Runtime Environment:: Accessing and modifying Guile's environment.
19 * Processes:: getuid, getpid, etc.
20 * Signals:: sigaction, kill, pause, alarm, setitimer, etc.
21 * Terminals and Ptys:: ttyname, tcsetpgrp, etc.
22 * Pipes:: Communicating data between processes.
23 * Networking:: gethostbyaddr, getnetent, socket, bind, listen.
24 * System Identification:: Obtaining information about the system.
25 * Locales:: setlocale, etc.
30 @subsection @acronym{POSIX} Interface Conventions
32 These interfaces provide access to operating system facilities.
33 They provide a simple wrapping around the underlying C interfaces
34 to make usage from Scheme more convenient. They are also used
35 to implement the Guile port of scsh (@pxref{The Scheme shell (scsh)}).
37 Generally there is a single procedure for each corresponding Unix
38 facility. There are some exceptions, such as procedures implemented for
39 speed and convenience in Scheme with no primitive Unix equivalent,
40 e.g.@: @code{copy-file}.
42 The interfaces are intended as far as possible to be portable across
43 different versions of Unix. In some cases procedures which can't be
44 implemented on particular systems may become no-ops, or perform limited
45 actions. In other cases they may throw errors.
47 General naming conventions are as follows:
51 The Scheme name is often identical to the name of the underlying Unix
54 Underscores in Unix procedure names are converted to hyphens.
56 Procedures which destructively modify Scheme data have exclamation
57 marks appended, e.g., @code{recv!}.
59 Predicates (returning only @code{#t} or @code{#f}) have question marks
60 appended, e.g., @code{access?}.
62 Some names are changed to avoid conflict with dissimilar interfaces
63 defined by scsh, e.g., @code{primitive-fork}.
65 Unix preprocessor names such as @code{EPERM} or @code{R_OK} are converted
66 to Scheme variables of the same name (underscores are not replaced
70 Unexpected conditions are generally handled by raising exceptions.
71 There are a few procedures which return a special value if they don't
72 succeed, e.g., @code{getenv} returns @code{#f} if it the requested
73 string is not found in the environment. These cases are noted in
76 For ways to deal with exceptions, see @ref{Exceptions}.
79 Errors which the C library would report by returning a null pointer or
80 through some other means are reported by raising a @code{system-error}
81 exception with @code{scm-error} (@pxref{Error Reporting}). The
82 @var{data} parameter is a list containing the Unix @code{errno} value
83 (an integer). For example,
86 (define (my-handler key func fmt fmtargs data)
87 (display key) (newline)
88 (display func) (newline)
89 (apply format #t fmt fmtargs) (newline)
90 (display data) (newline))
93 (lambda () (dup2 -123 -456))
105 @defun system-error-errno arglist
107 Return the @code{errno} value from a list which is the arguments to an
108 exception handler. If the exception is not a @code{system-error},
109 then the return is @code{#f}. For example,
115 (mkdir "/this-ought-to-fail-if-I'm-not-root"))
117 (let ((errno (system-error-errno stuff)))
120 (display "You're not allowed to do that."))
122 (display "Already exists."))
124 (display (strerror errno))))
130 @node Ports and File Descriptors
131 @subsection Ports and File Descriptors
132 @cindex file descriptor
134 Conventions generally follow those of scsh, @ref{The Scheme shell (scsh)}.
136 File ports are implemented using low-level operating system I/O
137 facilities, with optional buffering to improve efficiency; see
140 Note that some procedures (e.g., @code{recv!}) will accept ports as
141 arguments, but will actually operate directly on the file descriptor
142 underlying the port. Any port buffering is ignored, including the
143 buffer which implements @code{peek-char} and @code{unread-char}.
145 The @code{force-output} and @code{drain-input} procedures can be used
146 to clear the buffers.
148 Each open file port has an associated operating system file descriptor.
149 File descriptors are generally not useful in Scheme programs; however
150 they may be needed when interfacing with foreign code and the Unix
153 A file descriptor can be extracted from a port and a new port can be
154 created from a file descriptor. However a file descriptor is just an
155 integer and the garbage collector doesn't recognize it as a reference
156 to the port. If all other references to the port were dropped, then
157 it's likely that the garbage collector would free the port, with the
158 side-effect of closing the file descriptor prematurely.
160 To assist the programmer in avoiding this problem, each port has an
161 associated @dfn{revealed count} which can be used to keep track of how many
162 times the underlying file descriptor has been stored in other places.
163 If a port's revealed count is greater than zero, the file descriptor
164 will not be closed when the port is garbage collected. A programmer
165 can therefore ensure that the revealed count will be greater than
166 zero if the file descriptor is needed elsewhere.
168 For the simple case where a file descriptor is ``imported'' once to become
169 a port, it does not matter if the file descriptor is closed when the
170 port is garbage collected. There is no need to maintain a revealed
171 count. Likewise when ``exporting'' a file descriptor to the external
172 environment, setting the revealed count is not required provided the
173 port is kept open (i.e., is pointed to by a live Scheme binding) while
174 the file descriptor is in use.
176 To correspond with traditional Unix behaviour, three file descriptors
177 (0, 1, and 2) are automatically imported when a program starts up and
178 assigned to the initial values of the current/standard input, output,
179 and error ports, respectively. The revealed count for each is
180 initially set to one, so that dropping references to one of these
181 ports will not result in its garbage collection: it could be retrieved
182 with @code{fdopen} or @code{fdes->ports}.
184 @deffn {Scheme Procedure} port-revealed port
185 @deffnx {C Function} scm_port_revealed (port)
186 Return the revealed count for @var{port}.
189 @deffn {Scheme Procedure} set-port-revealed! port rcount
190 @deffnx {C Function} scm_set_port_revealed_x (port, rcount)
191 Sets the revealed count for a @var{port} to @var{rcount}.
192 The return value is unspecified.
195 @deffn {Scheme Procedure} fileno port
196 @deffnx {C Function} scm_fileno (port)
197 Return the integer file descriptor underlying @var{port}. Does
198 not change its revealed count.
201 @deffn {Scheme Procedure} port->fdes port
202 Returns the integer file descriptor underlying @var{port}. As a
203 side effect the revealed count of @var{port} is incremented.
206 @deffn {Scheme Procedure} fdopen fdes modes
207 @deffnx {C Function} scm_fdopen (fdes, modes)
208 Return a new port based on the file descriptor @var{fdes}. Modes are
209 given by the string @var{modes}. The revealed count of the port is
210 initialized to zero. The @var{modes} string is the same as that
211 accepted by @code{open-file} (@pxref{File Ports, open-file}).
214 @deffn {Scheme Procedure} fdes->ports fd
215 @deffnx {C Function} scm_fdes_to_ports (fd)
216 Return a list of existing ports which have @var{fdes} as an
217 underlying file descriptor, without changing their revealed
221 @deffn {Scheme Procedure} fdes->inport fdes
222 Returns an existing input port which has @var{fdes} as its underlying file
223 descriptor, if one exists, and increments its revealed count.
224 Otherwise, returns a new input port with a revealed count of 1.
227 @deffn {Scheme Procedure} fdes->outport fdes
228 Returns an existing output port which has @var{fdes} as its underlying file
229 descriptor, if one exists, and increments its revealed count.
230 Otherwise, returns a new output port with a revealed count of 1.
233 @deffn {Scheme Procedure} primitive-move->fdes port fd
234 @deffnx {C Function} scm_primitive_move_to_fdes (port, fd)
235 Moves the underlying file descriptor for @var{port} to the integer
236 value @var{fdes} without changing the revealed count of @var{port}.
237 Any other ports already using this descriptor will be automatically
238 shifted to new descriptors and their revealed counts reset to zero.
239 The return value is @code{#f} if the file descriptor already had the
240 required value or @code{#t} if it was moved.
243 @deffn {Scheme Procedure} move->fdes port fdes
244 Moves the underlying file descriptor for @var{port} to the integer
245 value @var{fdes} and sets its revealed count to one. Any other ports
246 already using this descriptor will be automatically
247 shifted to new descriptors and their revealed counts reset to zero.
248 The return value is unspecified.
251 @deffn {Scheme Procedure} release-port-handle port
252 Decrements the revealed count for a port.
255 @deffn {Scheme Procedure} fsync object
256 @deffnx {C Function} scm_fsync (object)
257 Copies any unwritten data for the specified output file descriptor to disk.
258 If @var{port/fd} is a port, its buffer is flushed before the underlying
259 file descriptor is fsync'd.
260 The return value is unspecified.
263 @deffn {Scheme Procedure} open path flags [mode]
264 @deffnx {C Function} scm_open (path, flags, mode)
265 Open the file named by @var{path} for reading and/or writing.
266 @var{flags} is an integer specifying how the file should be opened.
267 @var{mode} is an integer specifying the permission bits of the file,
268 if it needs to be created, before the umask (@pxref{Processes}) is
269 applied. The default is 666 (Unix itself has no default).
271 @var{flags} can be constructed by combining variables using @code{logior}.
275 Open the file read-only.
278 Open the file write-only.
281 Open the file read/write.
284 Append to the file instead of truncating.
287 Create the file if it does not already exist.
290 @xref{File Status Flags,,,libc,The GNU C Library Reference Manual},
291 for additional flags.
294 @deffn {Scheme Procedure} open-fdes path flags [mode]
295 @deffnx {C Function} scm_open_fdes (path, flags, mode)
296 Similar to @code{open} but return a file descriptor instead of
300 @deffn {Scheme Procedure} close fd_or_port
301 @deffnx {C Function} scm_close (fd_or_port)
302 Similar to @code{close-port} (@pxref{Closing, close-port}),
303 but also works on file descriptors. A side
304 effect of closing a file descriptor is that any ports using that file
305 descriptor are moved to a different file descriptor and have
306 their revealed counts set to zero.
309 @deffn {Scheme Procedure} close-fdes fd
310 @deffnx {C Function} scm_close_fdes (fd)
311 A simple wrapper for the @code{close} system call. Close file
312 descriptor @var{fd}, which must be an integer. Unlike @code{close},
313 the file descriptor will be closed even if a port is using it. The
314 return value is unspecified.
317 @deffn {Scheme Procedure} unread-char char [port]
318 @deffnx {C Function} scm_unread_char (char, port)
319 Place @var{char} in @var{port} so that it will be read by the next
320 read operation on that port. If called multiple times, the unread
321 characters will be read again in ``last-in, first-out'' order (i.e.@:
322 a stack). If @var{port} is not supplied, the current input port is
326 @deffn {Scheme Procedure} unread-string str port
327 Place the string @var{str} in @var{port} so that its characters will be
328 read in subsequent read operations. If called multiple times, the
329 unread characters will be read again in last-in first-out order. If
330 @var{port} is not supplied, the current-input-port is used.
333 @deffn {Scheme Procedure} pipe
334 @deffnx {C Function} scm_pipe ()
336 Return a newly created pipe: a pair of ports which are linked
337 together on the local machine. The @acronym{CAR} is the input
338 port and the @acronym{CDR} is the output port. Data written (and
339 flushed) to the output port can be read from the input port.
340 Pipes are commonly used for communication with a newly forked
341 child process. The need to flush the output port can be
342 avoided by making it unbuffered using @code{setvbuf}.
345 A write of up to @code{PIPE_BUF} many bytes to a pipe is atomic,
346 meaning when done it goes into the pipe instantaneously and as a
347 contiguous block (@pxref{Pipe Atomicity,, Atomicity of Pipe I/O, libc,
348 The GNU C Library Reference Manual}).
351 Note that the output port is likely to block if too much data has been
352 written but not yet read from the input port. Typically the capacity
353 is @code{PIPE_BUF} bytes.
356 The next group of procedures perform a @code{dup2}
357 system call, if @var{newfd} (an
358 integer) is supplied, otherwise a @code{dup}. The file descriptor to be
359 duplicated can be supplied as an integer or contained in a port. The
360 type of value returned varies depending on which procedure is used.
362 All procedures also have the side effect when performing @code{dup2} that any
363 ports using @var{newfd} are moved to a different file descriptor and have
364 their revealed counts set to zero.
366 @deffn {Scheme Procedure} dup->fdes fd_or_port [fd]
367 @deffnx {C Function} scm_dup_to_fdes (fd_or_port, fd)
368 Return a new integer file descriptor referring to the open file
369 designated by @var{fd_or_port}, which must be either an open
370 file port or a file descriptor.
373 @deffn {Scheme Procedure} dup->inport port/fd [newfd]
374 Returns a new input port using the new file descriptor.
377 @deffn {Scheme Procedure} dup->outport port/fd [newfd]
378 Returns a new output port using the new file descriptor.
381 @deffn {Scheme Procedure} dup port/fd [newfd]
382 Returns a new port if @var{port/fd} is a port, with the same mode as the
383 supplied port, otherwise returns an integer file descriptor.
386 @deffn {Scheme Procedure} dup->port port/fd mode [newfd]
387 Returns a new port using the new file descriptor. @var{mode} supplies a
388 mode string for the port (@pxref{File Ports, open-file}).
391 @deffn {Scheme Procedure} duplicate-port port modes
392 Returns a new port which is opened on a duplicate of the file
393 descriptor underlying @var{port}, with mode string @var{modes}
394 as for @ref{File Ports, open-file}. The two ports
395 will share a file position and file status flags.
397 Unexpected behaviour can result if both ports are subsequently used
398 and the original and/or duplicate ports are buffered.
399 The mode string can include @code{0} to obtain an unbuffered duplicate
402 This procedure is equivalent to @code{(dup->port @var{port} @var{modes})}.
405 @deffn {Scheme Procedure} redirect-port old new
406 @deffnx {C Function} scm_redirect_port (old, new)
407 This procedure takes two ports and duplicates the underlying file
408 descriptor from @var{old-port} into @var{new-port}. The
409 current file descriptor in @var{new-port} will be closed.
410 After the redirection the two ports will share a file position
411 and file status flags.
413 The return value is unspecified.
415 Unexpected behaviour can result if both ports are subsequently used
416 and the original and/or duplicate ports are buffered.
418 This procedure does not have any side effects on other ports or
422 @deffn {Scheme Procedure} dup2 oldfd newfd
423 @deffnx {C Function} scm_dup2 (oldfd, newfd)
424 A simple wrapper for the @code{dup2} system call.
425 Copies the file descriptor @var{oldfd} to descriptor
426 number @var{newfd}, replacing the previous meaning
427 of @var{newfd}. Both @var{oldfd} and @var{newfd} must
429 Unlike for @code{dup->fdes} or @code{primitive-move->fdes}, no attempt
430 is made to move away ports which are using @var{newfd}.
431 The return value is unspecified.
434 @deffn {Scheme Procedure} port-mode port
435 Return the port modes associated with the open port @var{port}.
436 These will not necessarily be identical to the modes used when
437 the port was opened, since modes such as ``append'' which are
438 used only during port creation are not retained.
441 @deffn {Scheme Procedure} port-for-each proc
442 @deffnx {C Function} scm_port_for_each (SCM proc)
443 @deffnx {C Function} scm_c_port_for_each (void (*proc)(void *, SCM), void *data)
444 Apply @var{proc} to each port in the Guile port table
445 (FIXME: what is the Guile port table?)
446 in turn. The return value is unspecified. More specifically,
447 @var{proc} is applied exactly once to every port that exists in the
448 system at the time @code{port-for-each} is invoked. Changes to the
449 port table while @code{port-for-each} is running have no effect as far
450 as @code{port-for-each} is concerned.
452 The C function @code{scm_port_for_each} takes a Scheme procedure
453 encoded as a @code{SCM} value, while @code{scm_c_port_for_each} takes
454 a pointer to a C function and passes along a arbitrary @var{data}
458 @deffn {Scheme Procedure} setvbuf port mode [size]
459 @deffnx {C Function} scm_setvbuf (port, mode, size)
460 @cindex port buffering
461 Set the buffering mode for @var{port}. @var{mode} can be:
470 block buffered, using a newly allocated buffer of @var{size} bytes.
471 If @var{size} is omitted, a default size will be used.
475 @deffn {Scheme Procedure} fcntl object cmd [value]
476 @deffnx {C Function} scm_fcntl (object, cmd, value)
477 Apply @var{command} to the specified file descriptor or the underlying
478 file descriptor of the specified port. @var{value} is an optional
481 Values for @var{command} are:
484 Duplicate a file descriptor
487 Get flags associated with the file descriptor.
490 Set flags associated with the file descriptor to @var{value}.
493 Get flags associated with the open file.
496 Set flags associated with the open file to @var{value}
499 Get the process ID of a socket's owner, for @code{SIGIO} signals.
502 Set the process that owns a socket to @var{value}, for @code{SIGIO} signals.
505 The value used to indicate the ``close on exec'' flag with @code{F_GETFL} or
510 @deffn {Scheme Procedure} flock file operation
511 @deffnx {C Function} scm_flock (file, operation)
513 Apply or remove an advisory lock on an open file.
514 @var{operation} specifies the action to be done:
517 Shared lock. More than one process may hold a shared lock
518 for a given file at a given time.
521 Exclusive lock. Only one process may hold an exclusive lock
522 for a given file at a given time.
528 Don't block when locking. This is combined with one of the other
529 operations using @code{logior} (@pxref{Bitwise Operations}). If
530 @code{flock} would block an @code{EWOULDBLOCK} error is thrown
531 (@pxref{Conventions}).
534 The return value is not specified. @var{file} may be an open
535 file descriptor or an open file descriptor port.
537 Note that @code{flock} does not lock files across NFS.
540 @deffn {Scheme Procedure} select reads writes excepts [secs [usecs]]
541 @deffnx {C Function} scm_select (reads, writes, excepts, secs, usecs)
542 This procedure has a variety of uses: waiting for the ability
543 to provide input, accept output, or the existence of
544 exceptional conditions on a collection of ports or file
545 descriptors, or waiting for a timeout to occur.
546 It also returns if interrupted by a signal.
548 @var{reads}, @var{writes} and @var{excepts} can be lists or
549 vectors, with each member a port or a file descriptor.
550 The value returned is a list of three corresponding
551 lists or vectors containing only the members which meet the
552 specified requirement. The ability of port buffers to
553 provide input or accept output is taken into account.
554 Ordering of the input lists or vectors is not preserved.
556 The optional arguments @var{secs} and @var{usecs} specify the
557 timeout. Either @var{secs} can be specified alone, as
558 either an integer or a real number, or both @var{secs} and
559 @var{usecs} can be specified as integers, in which case
560 @var{usecs} is an additional timeout expressed in
561 microseconds. If @var{secs} is omitted or is @code{#f} then
562 select will wait for as long as it takes for one of the other
563 conditions to be satisfied.
565 The scsh version of @code{select} differs as follows:
566 Only vectors are accepted for the first three arguments.
567 The @var{usecs} argument is not supported.
568 Multiple values are returned instead of a list.
569 Duplicates in the input vectors appear only once in output.
570 An additional @code{select!} interface is provided.
574 @subsection File System
577 These procedures allow querying and setting file system attributes
579 permissions, sizes and types of files); deleting, copying, renaming and
580 linking files; creating and removing directories and querying their
581 contents; syncing the file system and creating special files.
583 @deffn {Scheme Procedure} access? path how
584 @deffnx {C Function} scm_access (path, how)
585 Test accessibility of a file under the real UID and GID of the calling
586 process. The return is @code{#t} if @var{path} exists and the
587 permissions requested by @var{how} are all allowed, or @code{#f} if
590 @var{how} is an integer which is one of the following values, or a
591 bitwise-OR (@code{logior}) of multiple values.
594 Test for read permission.
597 Test for write permission.
600 Test for execute permission.
603 Test for existence of the file. This is implied by each of the other
604 tests, so there's no need to combine it with them.
607 It's important to note that @code{access?} does not simply indicate
608 what will happen on attempting to read or write a file. In normal
609 circumstances it does, but in a set-UID or set-GID program it doesn't
610 because @code{access?} tests the real ID, whereas an open or execute
611 attempt uses the effective ID.
613 A program which will never run set-UID/GID can ignore the difference
614 between real and effective IDs, but for maximum generality, especially
615 in library functions, it's best not to use @code{access?} to predict
616 the result of an open or execute, instead simply attempt that and
619 The main use for @code{access?} is to let a set-UID/GID program
620 determine what the invoking user would have been allowed to do,
621 without the greater (or perhaps lesser) privileges afforded by the
622 effective ID. For more on this, see @ref{Testing File Access,,, libc,
623 The GNU C Library Reference Manual}.
627 @deffn {Scheme Procedure} stat object
628 @deffnx {C Function} scm_stat (object)
629 Return an object containing various information about the file
630 determined by @var{obj}. @var{obj} can be a string containing
631 a file name or a port or integer file descriptor which is open
632 on a file (in which case @code{fstat} is used as the underlying
635 The object returned by @code{stat} can be passed as a single
636 parameter to the following procedures, all of which return
639 @deffn {Scheme Procedure} stat:dev st
640 The device number containing the file.
642 @deffn {Scheme Procedure} stat:ino st
643 The file serial number, which distinguishes this file from all
644 other files on the same device.
646 @deffn {Scheme Procedure} stat:mode st
647 The mode of the file. This is an integer which incorporates file type
648 information and file permission bits. See also @code{stat:type} and
649 @code{stat:perms} below.
651 @deffn {Scheme Procedure} stat:nlink st
652 The number of hard links to the file.
654 @deffn {Scheme Procedure} stat:uid st
655 The user ID of the file's owner.
657 @deffn {Scheme Procedure} stat:gid st
658 The group ID of the file.
660 @deffn {Scheme Procedure} stat:rdev st
661 Device ID; this entry is defined only for character or block special
662 files. On some systems this field is not available at all, in which
663 case @code{stat:rdev} returns @code{#f}.
665 @deffn {Scheme Procedure} stat:size st
666 The size of a regular file in bytes.
668 @deffn {Scheme Procedure} stat:atime st
669 The last access time for the file.
671 @deffn {Scheme Procedure} stat:mtime st
672 The last modification time for the file.
674 @deffn {Scheme Procedure} stat:ctime st
675 The last modification time for the attributes of the file.
677 @deffn {Scheme Procedure} stat:blksize st
678 The optimal block size for reading or writing the file, in bytes. On
679 some systems this field is not available, in which case
680 @code{stat:blksize} returns a sensible suggested block size.
682 @deffn {Scheme Procedure} stat:blocks st
683 The amount of disk space that the file occupies measured in units of
684 512 byte blocks. On some systems this field is not available, in
685 which case @code{stat:blocks} returns @code{#f}.
688 In addition, the following procedures return the information
689 from @code{stat:mode} in a more convenient form:
691 @deffn {Scheme Procedure} stat:type st
692 A symbol representing the type of file. Possible values are
693 @samp{regular}, @samp{directory}, @samp{symlink},
694 @samp{block-special}, @samp{char-special}, @samp{fifo}, @samp{socket},
697 @deffn {Scheme Procedure} stat:perms st
698 An integer representing the access permission bits.
702 @deffn {Scheme Procedure} lstat str
703 @deffnx {C Function} scm_lstat (str)
704 Similar to @code{stat}, but does not follow symbolic links, i.e.,
705 it will return information about a symbolic link itself, not the
706 file it points to. @var{path} must be a string.
709 @deffn {Scheme Procedure} readlink path
710 @deffnx {C Function} scm_readlink (path)
711 Return the value of the symbolic link named by @var{path} (a
712 string), i.e., the file that the link points to.
717 @deffn {Scheme Procedure} chown object owner group
718 @deffnx {C Function} scm_chown (object, owner, group)
719 Change the ownership and group of the file referred to by @var{object}
720 to the integer values @var{owner} and @var{group}. @var{object} can
721 be a string containing a file name or, if the platform supports
722 @code{fchown} (@pxref{File Owner,,,libc,The GNU C Library Reference
723 Manual}), a port or integer file descriptor which is open on the file.
724 The return value is unspecified.
726 If @var{object} is a symbolic link, either the
727 ownership of the link or the ownership of the referenced file will be
728 changed depending on the operating system (lchown is
729 unsupported at present). If @var{owner} or @var{group} is specified
730 as @code{-1}, then that ID is not changed.
734 @deffn {Scheme Procedure} chmod object mode
735 @deffnx {C Function} scm_chmod (object, mode)
736 Changes the permissions of the file referred to by @var{obj}.
737 @var{obj} can be a string containing a file name or a port or integer file
738 descriptor which is open on a file (in which case @code{fchmod} is used
739 as the underlying system call).
741 the new permissions as a decimal number, e.g., @code{(chmod "foo" #o755)}.
742 The return value is unspecified.
745 @deffn {Scheme Procedure} utime pathname [actime [modtime]]
746 @deffnx {C Function} scm_utime (pathname, actime, modtime)
748 @code{utime} sets the access and modification times for the
749 file named by @var{path}. If @var{actime} or @var{modtime} is
750 not supplied, then the current time is used. @var{actime} and
751 @var{modtime} must be integer time values as returned by the
752 @code{current-time} procedure.
754 (utime "foo" (- (current-time) 3600))
756 will set the access time to one hour in the past and the
757 modification time to the current time.
761 @deffn {Scheme Procedure} delete-file str
762 @deffnx {C Function} scm_delete_file (str)
763 Deletes (or ``unlinks'') the file whose path is specified by
767 @deffn {Scheme Procedure} copy-file oldfile newfile
768 @deffnx {C Function} scm_copy_file (oldfile, newfile)
769 Copy the file specified by @var{oldfile} to @var{newfile}.
770 The return value is unspecified.
774 @deffn {Scheme Procedure} rename-file oldname newname
775 @deffnx {C Function} scm_rename (oldname, newname)
776 Renames the file specified by @var{oldname} to @var{newname}.
777 The return value is unspecified.
780 @deffn {Scheme Procedure} link oldpath newpath
781 @deffnx {C Function} scm_link (oldpath, newpath)
782 Creates a new name @var{newpath} in the file system for the
783 file named by @var{oldpath}. If @var{oldpath} is a symbolic
784 link, the link may or may not be followed depending on the
788 @deffn {Scheme Procedure} symlink oldpath newpath
789 @deffnx {C Function} scm_symlink (oldpath, newpath)
790 Create a symbolic link named @var{newpath} with the value (i.e., pointing to)
791 @var{oldpath}. The return value is unspecified.
794 @deffn {Scheme Procedure} mkdir path [mode]
795 @deffnx {C Function} scm_mkdir (path, mode)
796 Create a new directory named by @var{path}. If @var{mode} is omitted
797 then the permissions of the directory file are set using the current
798 umask (@pxref{Processes}). Otherwise they are set to the decimal
799 value specified with @var{mode}. The return value is unspecified.
802 @deffn {Scheme Procedure} rmdir path
803 @deffnx {C Function} scm_rmdir (path)
804 Remove the existing directory named by @var{path}. The directory must
805 be empty for this to succeed. The return value is unspecified.
808 @deffn {Scheme Procedure} opendir dirname
809 @deffnx {C Function} scm_opendir (dirname)
810 @cindex directory contents
811 Open the directory specified by @var{dirname} and return a directory
815 @deffn {Scheme Procedure} directory-stream? object
816 @deffnx {C Function} scm_directory_stream_p (object)
817 Return a boolean indicating whether @var{object} is a directory
818 stream as returned by @code{opendir}.
821 @deffn {Scheme Procedure} readdir stream
822 @deffnx {C Function} scm_readdir (stream)
823 Return (as a string) the next directory entry from the directory stream
824 @var{stream}. If there is no remaining entry to be read then the
825 end of file object is returned.
828 @deffn {Scheme Procedure} rewinddir stream
829 @deffnx {C Function} scm_rewinddir (stream)
830 Reset the directory port @var{stream} so that the next call to
831 @code{readdir} will return the first directory entry.
834 @deffn {Scheme Procedure} closedir stream
835 @deffnx {C Function} scm_closedir (stream)
836 Close the directory stream @var{stream}.
837 The return value is unspecified.
840 Here is an example showing how to display all the entries in a
844 (define dir (opendir "/usr/lib"))
845 (do ((entry (readdir dir) (readdir dir)))
846 ((eof-object? entry))
847 (display entry)(newline))
851 @deffn {Scheme Procedure} sync
852 @deffnx {C Function} scm_sync ()
853 Flush the operating system disk buffers.
854 The return value is unspecified.
857 @deffn {Scheme Procedure} mknod path type perms dev
858 @deffnx {C Function} scm_mknod (path, type, perms, dev)
860 Creates a new special file, such as a file corresponding to a device.
861 @var{path} specifies the name of the file. @var{type} should be one
862 of the following symbols: @samp{regular}, @samp{directory},
863 @samp{symlink}, @samp{block-special}, @samp{char-special},
864 @samp{fifo}, or @samp{socket}. @var{perms} (an integer) specifies the
865 file permissions. @var{dev} (an integer) specifies which device the
866 special file refers to. Its exact interpretation depends on the kind
867 of special file being created.
871 (mknod "/dev/fd0" 'block-special #o660 (+ (* 2 256) 2))
874 The return value is unspecified.
877 @deffn {Scheme Procedure} tmpnam
878 @deffnx {C Function} scm_tmpnam ()
879 @cindex temporary file
880 Return an auto-generated name of a temporary file, a file which
881 doesn't already exist. The name includes a path, it's usually in
882 @file{/tmp} but that's system dependent.
884 Care must be taken when using @code{tmpnam}. In between choosing the
885 name and creating the file another program might use that name, or an
886 attacker might even make it a symlink pointing at something important
887 and causing you to overwrite that.
889 The safe way is to create the file using @code{open} with
890 @code{O_EXCL} to avoid any overwriting. A loop can try again with
891 another name if the file exists (error @code{EEXIST}).
892 @code{mkstemp!} below does that.
895 @deffn {Scheme Procedure} mkstemp! tmpl
896 @deffnx {C Function} scm_mkstemp (tmpl)
897 @cindex temporary file
898 Create a new unique file in the file system and return a new buffered
899 port open for reading and writing to the file.
901 @var{tmpl} is a string specifying where the file should be created: it
902 must end with @samp{XXXXXX} and those @samp{X}s will be changed in the
903 string to return the name of the file. (@code{port-filename} on the
904 port also gives the name.)
906 POSIX doesn't specify the permissions mode of the file, on GNU and
907 most systems it's @code{#o600}. An application can use @code{chmod}
908 to relax that if desired. For example @code{#o666} less @code{umask},
909 which is usual for ordinary file creation,
912 (let ((port (mkstemp! (string-copy "/tmp/myfile-XXXXXX"))))
913 (chmod port (logand #o666 (lognot (umask))))
918 @deffn {Scheme Procedure} dirname filename
919 @deffnx {C Function} scm_dirname (filename)
920 Return the directory name component of the file name
921 @var{filename}. If @var{filename} does not contain a directory
922 component, @code{.} is returned.
925 @deffn {Scheme Procedure} basename filename [suffix]
926 @deffnx {C Function} scm_basename (filename, suffix)
927 Return the base name of the file name @var{filename}. The
928 base name is the file name without any directory components.
929 If @var{suffix} is provided, and is equal to the end of
930 @var{basename}, it is removed also.
933 (basename "/tmp/test.xml" ".xml")
939 @node User Information
940 @subsection User Information
941 @cindex user information
942 @cindex password file
945 The facilities in this section provide an interface to the user and
947 They should be used with care since they are not reentrant.
949 The following functions accept an object representing user information
950 and return a selected component:
952 @deffn {Scheme Procedure} passwd:name pw
953 The name of the userid.
955 @deffn {Scheme Procedure} passwd:passwd pw
956 The encrypted passwd.
958 @deffn {Scheme Procedure} passwd:uid pw
961 @deffn {Scheme Procedure} passwd:gid pw
964 @deffn {Scheme Procedure} passwd:gecos pw
967 @deffn {Scheme Procedure} passwd:dir pw
970 @deffn {Scheme Procedure} passwd:shell pw
975 @deffn {Scheme Procedure} getpwuid uid
976 Look up an integer userid in the user database.
979 @deffn {Scheme Procedure} getpwnam name
980 Look up a user name string in the user database.
983 @deffn {Scheme Procedure} setpwent
984 Initializes a stream used by @code{getpwent} to read from the user database.
985 The next use of @code{getpwent} will return the first entry. The
986 return value is unspecified.
989 @deffn {Scheme Procedure} getpwent
990 Return the next entry in the user database, using the stream set by
994 @deffn {Scheme Procedure} endpwent
995 Closes the stream used by @code{getpwent}. The return value is unspecified.
998 @deffn {Scheme Procedure} setpw [arg]
999 @deffnx {C Function} scm_setpwent (arg)
1000 If called with a true argument, initialize or reset the password data
1001 stream. Otherwise, close the stream. The @code{setpwent} and
1002 @code{endpwent} procedures are implemented on top of this.
1005 @deffn {Scheme Procedure} getpw [user]
1006 @deffnx {C Function} scm_getpwuid (user)
1007 Look up an entry in the user database. @var{obj} can be an integer,
1008 a string, or omitted, giving the behaviour of getpwuid, getpwnam
1009 or getpwent respectively.
1012 The following functions accept an object representing group information
1013 and return a selected component:
1015 @deffn {Scheme Procedure} group:name gr
1018 @deffn {Scheme Procedure} group:passwd gr
1019 The encrypted group password.
1021 @deffn {Scheme Procedure} group:gid gr
1022 The group id number.
1024 @deffn {Scheme Procedure} group:mem gr
1025 A list of userids which have this group as a supplementary group.
1029 @deffn {Scheme Procedure} getgrgid gid
1030 Look up an integer group id in the group database.
1033 @deffn {Scheme Procedure} getgrnam name
1034 Look up a group name in the group database.
1037 @deffn {Scheme Procedure} setgrent
1038 Initializes a stream used by @code{getgrent} to read from the group database.
1039 The next use of @code{getgrent} will return the first entry.
1040 The return value is unspecified.
1043 @deffn {Scheme Procedure} getgrent
1044 Return the next entry in the group database, using the stream set by
1048 @deffn {Scheme Procedure} endgrent
1049 Closes the stream used by @code{getgrent}.
1050 The return value is unspecified.
1053 @deffn {Scheme Procedure} setgr [arg]
1054 @deffnx {C Function} scm_setgrent (arg)
1055 If called with a true argument, initialize or reset the group data
1056 stream. Otherwise, close the stream. The @code{setgrent} and
1057 @code{endgrent} procedures are implemented on top of this.
1060 @deffn {Scheme Procedure} getgr [name]
1061 @deffnx {C Function} scm_getgrgid (name)
1062 Look up an entry in the group database. @var{obj} can be an integer,
1063 a string, or omitted, giving the behaviour of getgrgid, getgrnam
1064 or getgrent respectively.
1067 In addition to the accessor procedures for the user database, the
1068 following shortcut procedures are also available.
1070 @deffn {Scheme Procedure} cuserid
1071 @deffnx {C Function} scm_cuserid ()
1072 Return a string containing a user name associated with the
1073 effective user id of the process. Return @code{#f} if this
1074 information cannot be obtained.
1076 This function has been removed from the latest POSIX specification,
1077 Guile provides it only if the system has it. Using @code{(getpwuid
1078 (geteuid))} may be a better idea.
1081 @deffn {Scheme Procedure} getlogin
1082 @deffnx {C Function} scm_getlogin ()
1083 Return a string containing the name of the user logged in on
1084 the controlling terminal of the process, or @code{#f} if this
1085 information cannot be obtained.
1093 @deffn {Scheme Procedure} current-time
1094 @deffnx {C Function} scm_current_time ()
1095 Return the number of seconds since 1970-01-01 00:00:00 @acronym{UTC},
1096 excluding leap seconds.
1099 @deffn {Scheme Procedure} gettimeofday
1100 @deffnx {C Function} scm_gettimeofday ()
1101 Return a pair containing the number of seconds and microseconds
1102 since 1970-01-01 00:00:00 @acronym{UTC}, excluding leap seconds. Note:
1103 whether true microsecond resolution is available depends on the
1107 The following procedures either accept an object representing a broken down
1108 time and return a selected component, or accept an object representing
1109 a broken down time and a value and set the component to the value.
1110 The numbers in parentheses give the usual range.
1112 @deffn {Scheme Procedure} tm:sec tm
1113 @deffnx {Scheme Procedure} set-tm:sec tm val
1116 @deffn {Scheme Procedure} tm:min tm
1117 @deffnx {Scheme Procedure} set-tm:min tm val
1120 @deffn {Scheme Procedure} tm:hour tm
1121 @deffnx {Scheme Procedure} set-tm:hour tm val
1124 @deffn {Scheme Procedure} tm:mday tm
1125 @deffnx {Scheme Procedure} set-tm:mday tm val
1126 Day of the month (1-31).
1128 @deffn {Scheme Procedure} tm:mon tm
1129 @deffnx {Scheme Procedure} set-tm:mon tm val
1132 @deffn {Scheme Procedure} tm:year tm
1133 @deffnx {Scheme Procedure} set-tm:year tm val
1134 Year (70-), the year minus 1900.
1136 @deffn {Scheme Procedure} tm:wday tm
1137 @deffnx {Scheme Procedure} set-tm:wday tm val
1138 Day of the week (0-6) with Sunday represented as 0.
1140 @deffn {Scheme Procedure} tm:yday tm
1141 @deffnx {Scheme Procedure} set-tm:yday tm val
1142 Day of the year (0-364, 365 in leap years).
1144 @deffn {Scheme Procedure} tm:isdst tm
1145 @deffnx {Scheme Procedure} set-tm:isdst tm val
1146 Daylight saving indicator (0 for ``no'', greater than 0 for ``yes'', less than
1149 @deffn {Scheme Procedure} tm:gmtoff tm
1150 @deffnx {Scheme Procedure} set-tm:gmtoff tm val
1151 Time zone offset in seconds west of @acronym{UTC} (-46800 to 43200).
1153 @deffn {Scheme Procedure} tm:zone tm
1154 @deffnx {Scheme Procedure} set-tm:zone tm val
1155 Time zone label (a string), not necessarily unique.
1159 @deffn {Scheme Procedure} localtime time [zone]
1160 @deffnx {C Function} scm_localtime (time, zone)
1162 Return an object representing the broken down components of
1163 @var{time}, an integer like the one returned by
1164 @code{current-time}. The time zone for the calculation is
1165 optionally specified by @var{zone} (a string), otherwise the
1166 @env{TZ} environment variable or the system default is used.
1169 @deffn {Scheme Procedure} gmtime time
1170 @deffnx {C Function} scm_gmtime (time)
1171 Return an object representing the broken down components of
1172 @var{time}, an integer like the one returned by
1173 @code{current-time}. The values are calculated for @acronym{UTC}.
1176 @deffn {Scheme Procedure} mktime sbd-time [zone]
1177 @deffnx {C Function} scm_mktime (sbd_time, zone)
1178 For a broken down time object @var{sbd-time}, return a pair the
1179 @code{car} of which is an integer time like @code{current-time}, and
1180 the @code{cdr} of which is a new broken down time with normalized
1183 @var{zone} is a timezone string, or the default is the @env{TZ}
1184 environment variable or the system default (@pxref{TZ Variable,,
1185 Specifying the Time Zone with @env{TZ}, libc, GNU C Library Reference
1186 Manual}). @var{sbd-time} is taken to be in that @var{zone}.
1188 The following fields of @var{sbd-time} are used: @code{tm:year},
1189 @code{tm:mon}, @code{tm:mday}, @code{tm:hour}, @code{tm:min},
1190 @code{tm:sec}, @code{tm:isdst}. The values can be outside their usual
1191 ranges. For example @code{tm:hour} normally goes up to 23, but a
1192 value say 33 would mean 9 the following day.
1194 @code{tm:isdst} in @var{sbd-time} says whether the time given is with
1195 daylight savings or not. This is ignored if @var{zone} doesn't have
1196 any daylight savings adjustment amount.
1198 The broken down time in the return normalizes the values of
1199 @var{sbd-time} by bringing them into their usual ranges, and using the
1200 actual daylight savings rule for that time in @var{zone} (which may
1201 differ from what @var{sbd-time} had). The easiest way to think of
1202 this is that @var{sbd-time} plus @var{zone} converts to the integer
1203 UTC time, then a @code{localtime} is applied to get the normal
1204 presentation of that time, in @var{zone}.
1207 @deffn {Scheme Procedure} tzset
1208 @deffnx {C Function} scm_tzset ()
1209 Initialize the timezone from the @env{TZ} environment variable
1210 or the system default. It's not usually necessary to call this procedure
1211 since it's done automatically by other procedures that depend on the
1215 @deffn {Scheme Procedure} strftime format stime
1216 @deffnx {C Function} scm_strftime (format, stime)
1217 @cindex time formatting
1218 Formats a time specification @var{time} using @var{template}. @var{time}
1219 is an object with time components in the form returned by @code{localtime}
1220 or @code{gmtime}. @var{template} is a string which can include formatting
1221 specifications introduced by a @samp{%} character. The formatting of
1222 month and day names is dependent on the current locale. The value returned
1223 is the formatted string.
1224 @xref{Formatting Calendar Time, , , libc, The GNU C Library Reference Manual}.
1227 (strftime "%c" (localtime (current-time)))
1228 @result{} "Mon Mar 11 20:17:43 2002"
1232 @deffn {Scheme Procedure} strptime format string
1233 @deffnx {C Function} scm_strptime (format, string)
1234 @cindex time parsing
1235 Performs the reverse action to @code{strftime}, parsing
1236 @var{string} according to the specification supplied in
1237 @var{template}. The interpretation of month and day names is
1238 dependent on the current locale. The value returned is a pair.
1239 The @acronym{CAR} has an object with time components
1240 in the form returned by @code{localtime} or @code{gmtime},
1241 but the time zone components
1242 are not usefully set.
1243 The @acronym{CDR} reports the number of characters from @var{string}
1244 which were used for the conversion.
1247 @defvar internal-time-units-per-second
1248 The value of this variable is the number of time units per second
1249 reported by the following procedures.
1252 @deffn {Scheme Procedure} times
1253 @deffnx {C Function} scm_times ()
1254 Return an object with information about real and processor
1255 time. The following procedures accept such an object as an
1256 argument and return a selected component:
1258 @deffn {Scheme Procedure} tms:clock tms
1259 The current real time, expressed as time units relative to an
1262 @deffn {Scheme Procedure} tms:utime tms
1263 The CPU time units used by the calling process.
1265 @deffn {Scheme Procedure} tms:stime tms
1266 The CPU time units used by the system on behalf of the calling
1269 @deffn {Scheme Procedure} tms:cutime tms
1270 The CPU time units used by terminated child processes of the
1271 calling process, whose status has been collected (e.g., using
1274 @deffn {Scheme Procedure} tms:cstime tms
1275 Similarly, the CPU times units used by the system on behalf of
1276 terminated child processes.
1280 @deffn {Scheme Procedure} get-internal-real-time
1281 @deffnx {C Function} scm_get_internal_real_time ()
1282 Return the number of time units since the interpreter was
1286 @deffn {Scheme Procedure} get-internal-run-time
1287 @deffnx {C Function} scm_get_internal_run_time ()
1288 Return the number of time units of processor time used by the
1289 interpreter. Both @emph{system} and @emph{user} time are
1290 included but subprocesses are not.
1293 @node Runtime Environment
1294 @subsection Runtime Environment
1296 @deffn {Scheme Procedure} program-arguments
1297 @deffnx {Scheme Procedure} command-line
1298 @deffnx {C Function} scm_program_arguments ()
1299 @cindex command line
1300 @cindex program arguments
1301 Return the list of command line arguments passed to Guile, as a list of
1302 strings. The list includes the invoked program name, which is usually
1303 @code{"guile"}, but excludes switches and parameters for command line
1304 options like @code{-e} and @code{-l}.
1307 @deffn {Scheme Procedure} getenv nam
1308 @deffnx {C Function} scm_getenv (nam)
1310 Looks up the string @var{name} in the current environment. The return
1311 value is @code{#f} unless a string of the form @code{NAME=VALUE} is
1312 found, in which case the string @code{VALUE} is returned.
1315 @deffn {Scheme Procedure} setenv name value
1316 Modifies the environment of the current process, which is
1317 also the default environment inherited by child processes.
1319 If @var{value} is @code{#f}, then @var{name} is removed from the
1320 environment. Otherwise, the string @var{name}=@var{value} is added
1321 to the environment, replacing any existing string with name matching
1324 The return value is unspecified.
1327 @deffn {Scheme Procedure} unsetenv name
1328 Remove variable @var{name} from the environment. The
1329 name can not contain a @samp{=} character.
1332 @deffn {Scheme Procedure} environ [env]
1333 @deffnx {C Function} scm_environ (env)
1334 If @var{env} is omitted, return the current environment (in the
1335 Unix sense) as a list of strings. Otherwise set the current
1336 environment, which is also the default environment for child
1337 processes, to the supplied list of strings. Each member of
1338 @var{env} should be of the form @var{NAME}=@var{VALUE} and values of
1339 @var{NAME} should not be duplicated. If @var{env} is supplied
1340 then the return value is unspecified.
1343 @deffn {Scheme Procedure} putenv str
1344 @deffnx {C Function} scm_putenv (str)
1345 Modifies the environment of the current process, which is
1346 also the default environment inherited by child processes.
1348 If @var{string} is of the form @code{NAME=VALUE} then it will be written
1349 directly into the environment, replacing any existing environment string
1351 name matching @code{NAME}. If @var{string} does not contain an equal
1352 sign, then any existing string with name matching @var{string} will
1355 The return value is unspecified.
1360 @subsection Processes
1362 @cindex child processes
1365 @deffn {Scheme Procedure} chdir str
1366 @deffnx {C Function} scm_chdir (str)
1367 @cindex current directory
1368 Change the current working directory to @var{path}.
1369 The return value is unspecified.
1373 @deffn {Scheme Procedure} getcwd
1374 @deffnx {C Function} scm_getcwd ()
1375 Return the name of the current working directory.
1378 @deffn {Scheme Procedure} umask [mode]
1379 @deffnx {C Function} scm_umask (mode)
1380 If @var{mode} is omitted, returns a decimal number representing the
1381 current file creation mask. Otherwise the file creation mask is set
1382 to @var{mode} and the previous value is returned. @xref{Setting
1383 Permissions,,Assigning File Permissions,libc,The GNU C Library
1384 Reference Manual}, for more on how to use umasks.
1386 E.g., @code{(umask #o022)} sets the mask to octal 22/decimal 18.
1389 @deffn {Scheme Procedure} chroot path
1390 @deffnx {C Function} scm_chroot (path)
1391 Change the root directory to that specified in @var{path}.
1392 This directory will be used for path names beginning with
1393 @file{/}. The root directory is inherited by all children
1394 of the current process. Only the superuser may change the
1398 @deffn {Scheme Procedure} getpid
1399 @deffnx {C Function} scm_getpid ()
1400 Return an integer representing the current process ID.
1403 @deffn {Scheme Procedure} getgroups
1404 @deffnx {C Function} scm_getgroups ()
1405 Return a vector of integers representing the current
1406 supplementary group IDs.
1409 @deffn {Scheme Procedure} getppid
1410 @deffnx {C Function} scm_getppid ()
1411 Return an integer representing the process ID of the parent
1415 @deffn {Scheme Procedure} getuid
1416 @deffnx {C Function} scm_getuid ()
1417 Return an integer representing the current real user ID.
1420 @deffn {Scheme Procedure} getgid
1421 @deffnx {C Function} scm_getgid ()
1422 Return an integer representing the current real group ID.
1425 @deffn {Scheme Procedure} geteuid
1426 @deffnx {C Function} scm_geteuid ()
1427 Return an integer representing the current effective user ID.
1428 If the system does not support effective IDs, then the real ID
1429 is returned. @code{(provided? 'EIDs)} reports whether the
1430 system supports effective IDs.
1433 @deffn {Scheme Procedure} getegid
1434 @deffnx {C Function} scm_getegid ()
1435 Return an integer representing the current effective group ID.
1436 If the system does not support effective IDs, then the real ID
1437 is returned. @code{(provided? 'EIDs)} reports whether the
1438 system supports effective IDs.
1441 @deffn {Scheme Procedure} setgroups vec
1442 @deffnx {C Function} scm_setgroups (vec)
1443 Set the current set of supplementary group IDs to the integers in the
1444 given vector @var{vec}. The return value is unspecified.
1446 Generally only the superuser can set the process group IDs
1447 (@pxref{Setting Groups, Setting the Group IDs,, libc, The GNU C
1448 Library Reference Manual}).
1451 @deffn {Scheme Procedure} setuid id
1452 @deffnx {C Function} scm_setuid (id)
1453 Sets both the real and effective user IDs to the integer @var{id}, provided
1454 the process has appropriate privileges.
1455 The return value is unspecified.
1458 @deffn {Scheme Procedure} setgid id
1459 @deffnx {C Function} scm_setgid (id)
1460 Sets both the real and effective group IDs to the integer @var{id}, provided
1461 the process has appropriate privileges.
1462 The return value is unspecified.
1465 @deffn {Scheme Procedure} seteuid id
1466 @deffnx {C Function} scm_seteuid (id)
1467 Sets the effective user ID to the integer @var{id}, provided the process
1468 has appropriate privileges. If effective IDs are not supported, the
1469 real ID is set instead---@code{(provided? 'EIDs)} reports whether the
1470 system supports effective IDs.
1471 The return value is unspecified.
1474 @deffn {Scheme Procedure} setegid id
1475 @deffnx {C Function} scm_setegid (id)
1476 Sets the effective group ID to the integer @var{id}, provided the process
1477 has appropriate privileges. If effective IDs are not supported, the
1478 real ID is set instead---@code{(provided? 'EIDs)} reports whether the
1479 system supports effective IDs.
1480 The return value is unspecified.
1483 @deffn {Scheme Procedure} getpgrp
1484 @deffnx {C Function} scm_getpgrp ()
1485 Return an integer representing the current process group ID.
1486 This is the @acronym{POSIX} definition, not @acronym{BSD}.
1489 @deffn {Scheme Procedure} setpgid pid pgid
1490 @deffnx {C Function} scm_setpgid (pid, pgid)
1491 Move the process @var{pid} into the process group @var{pgid}. @var{pid} or
1492 @var{pgid} must be integers: they can be zero to indicate the ID of the
1494 Fails on systems that do not support job control.
1495 The return value is unspecified.
1498 @deffn {Scheme Procedure} setsid
1499 @deffnx {C Function} scm_setsid ()
1500 Creates a new session. The current process becomes the session leader
1501 and is put in a new process group. The process will be detached
1502 from its controlling terminal if it has one.
1503 The return value is an integer representing the new process group ID.
1506 @deffn {Scheme Procedure} waitpid pid [options]
1507 @deffnx {C Function} scm_waitpid (pid, options)
1508 This procedure collects status information from a child process which
1509 has terminated or (optionally) stopped. Normally it will
1510 suspend the calling process until this can be done. If more than one
1511 child process is eligible then one will be chosen by the operating system.
1513 The value of @var{pid} determines the behaviour:
1516 @item @var{pid} greater than 0
1517 Request status information from the specified child process.
1518 @item @var{pid} equal to -1 or @code{WAIT_ANY}
1520 Request status information for any child process.
1521 @item @var{pid} equal to 0 or @code{WAIT_MYPGRP}
1523 Request status information for any child process in the current process
1525 @item @var{pid} less than -1
1526 Request status information for any child process whose process group ID
1527 is @minus{}@var{pid}.
1530 The @var{options} argument, if supplied, should be the bitwise OR of the
1531 values of zero or more of the following variables:
1534 Return immediately even if there are no child processes to be collected.
1538 Report status information for stopped processes as well as terminated
1542 The return value is a pair containing:
1546 The process ID of the child process, or 0 if @code{WNOHANG} was
1547 specified and no process was collected.
1549 The integer status value.
1554 functions can be used to decode the process status code returned
1557 @deffn {Scheme Procedure} status:exit-val status
1558 @deffnx {C Function} scm_status_exit_val (status)
1559 Return the exit status value, as would be set if a process
1560 ended normally through a call to @code{exit} or @code{_exit},
1561 if any, otherwise @code{#f}.
1564 @deffn {Scheme Procedure} status:term-sig status
1565 @deffnx {C Function} scm_status_term_sig (status)
1566 Return the signal number which terminated the process, if any,
1567 otherwise @code{#f}.
1570 @deffn {Scheme Procedure} status:stop-sig status
1571 @deffnx {C Function} scm_status_stop_sig (status)
1572 Return the signal number which stopped the process, if any,
1573 otherwise @code{#f}.
1576 @deffn {Scheme Procedure} system [cmd]
1577 @deffnx {C Function} scm_system (cmd)
1578 Execute @var{cmd} using the operating system's ``command
1579 processor''. Under Unix this is usually the default shell
1580 @code{sh}. The value returned is @var{cmd}'s exit status as
1581 returned by @code{waitpid}, which can be interpreted using the
1584 If @code{system} is called without arguments, return a boolean
1585 indicating whether the command processor is available.
1588 @deffn {Scheme Procedure} system* . args
1589 @deffnx {C Function} scm_system_star (args)
1590 Execute the command indicated by @var{args}. The first element must
1591 be a string indicating the command to be executed, and the remaining
1592 items must be strings representing each of the arguments to that
1595 This function returns the exit status of the command as provided by
1596 @code{waitpid}. This value can be handled with @code{status:exit-val}
1597 and the related functions.
1599 @code{system*} is similar to @code{system}, but accepts only one
1600 string per-argument, and performs no shell interpretation. The
1601 command is executed using fork and execlp. Accordingly this function
1602 may be safer than @code{system} in situations where shell
1603 interpretation is not required.
1605 Example: (system* "echo" "foo" "bar")
1608 @deffn {Scheme Procedure} primitive-exit [status]
1609 @deffnx {C Function} scm_primitive_exit (status)
1610 Terminate the current process without unwinding the Scheme stack.
1611 This is would typically be useful after a fork. The exit status
1612 is @var{status} if supplied, otherwise zero.
1615 @deffn {Scheme Procedure} execl filename . args
1616 @deffnx {C Function} scm_execl (filename, args)
1617 Executes the file named by @var{path} as a new process image.
1618 The remaining arguments are supplied to the process; from a C program
1619 they are accessible as the @code{argv} argument to @code{main}.
1620 Conventionally the first @var{arg} is the same as @var{path}.
1621 All arguments must be strings.
1623 If @var{arg} is missing, @var{path} is executed with a null
1624 argument list, which may have system-dependent side-effects.
1626 This procedure is currently implemented using the @code{execv} system
1627 call, but we call it @code{execl} because of its Scheme calling interface.
1630 @deffn {Scheme Procedure} execlp filename . args
1631 @deffnx {C Function} scm_execlp (filename, args)
1632 Similar to @code{execl}, however if
1633 @var{filename} does not contain a slash
1634 then the file to execute will be located by searching the
1635 directories listed in the @code{PATH} environment variable.
1637 This procedure is currently implemented using the @code{execvp} system
1638 call, but we call it @code{execlp} because of its Scheme calling interface.
1641 @deffn {Scheme Procedure} execle filename env . args
1642 @deffnx {C Function} scm_execle (filename, env, args)
1643 Similar to @code{execl}, but the environment of the new process is
1644 specified by @var{env}, which must be a list of strings as returned by the
1645 @code{environ} procedure.
1647 This procedure is currently implemented using the @code{execve} system
1648 call, but we call it @code{execle} because of its Scheme calling interface.
1651 @deffn {Scheme Procedure} primitive-fork
1652 @deffnx {C Function} scm_fork ()
1653 Creates a new ``child'' process by duplicating the current ``parent'' process.
1654 In the child the return value is 0. In the parent the return value is
1655 the integer process ID of the child.
1657 This procedure has been renamed from @code{fork} to avoid a naming conflict
1661 @deffn {Scheme Procedure} nice incr
1662 @deffnx {C Function} scm_nice (incr)
1663 @cindex process priority
1664 Increment the priority of the current process by @var{incr}. A higher
1665 priority value means that the process runs less often.
1666 The return value is unspecified.
1669 @deffn {Scheme Procedure} setpriority which who prio
1670 @deffnx {C Function} scm_setpriority (which, who, prio)
1671 @vindex PRIO_PROCESS
1674 Set the scheduling priority of the process, process group
1675 or user, as indicated by @var{which} and @var{who}. @var{which}
1676 is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
1677 or @code{PRIO_USER}, and @var{who} is interpreted relative to
1678 @var{which} (a process identifier for @code{PRIO_PROCESS},
1679 process group identifier for @code{PRIO_PGRP}, and a user
1680 identifier for @code{PRIO_USER}. A zero value of @var{who}
1681 denotes the current process, process group, or user.
1682 @var{prio} is a value in the range [@minus{}20,20]. The default
1683 priority is 0; lower priorities (in numerical terms) cause more
1684 favorable scheduling. Sets the priority of all of the specified
1685 processes. Only the super-user may lower priorities. The return
1686 value is not specified.
1689 @deffn {Scheme Procedure} getpriority which who
1690 @deffnx {C Function} scm_getpriority (which, who)
1691 @vindex PRIO_PROCESS
1694 Return the scheduling priority of the process, process group
1695 or user, as indicated by @var{which} and @var{who}. @var{which}
1696 is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
1697 or @code{PRIO_USER}, and @var{who} should be interpreted depending on
1698 @var{which} (a process identifier for @code{PRIO_PROCESS},
1699 process group identifier for @code{PRIO_PGRP}, and a user
1700 identifier for @code{PRIO_USER}). A zero value of @var{who}
1701 denotes the current process, process group, or user. Return
1702 the highest priority (lowest numerical value) of any of the
1703 specified processes.
1711 Procedures to raise, handle and wait for signals.
1713 @deffn {Scheme Procedure} kill pid sig
1714 @deffnx {C Function} scm_kill (pid, sig)
1715 Sends a signal to the specified process or group of processes.
1717 @var{pid} specifies the processes to which the signal is sent:
1720 @item @var{pid} greater than 0
1721 The process whose identifier is @var{pid}.
1722 @item @var{pid} equal to 0
1723 All processes in the current process group.
1724 @item @var{pid} less than -1
1725 The process group whose identifier is -@var{pid}
1726 @item @var{pid} equal to -1
1727 If the process is privileged, all processes except for some special
1728 system processes. Otherwise, all processes with the current effective
1732 @var{sig} should be specified using a variable corresponding to
1733 the Unix symbolic name, e.g.,
1743 A full list of signals on the GNU system may be found in @ref{Standard
1744 Signals,,,libc,The GNU C Library Reference Manual}.
1747 @deffn {Scheme Procedure} raise sig
1748 @deffnx {C Function} scm_raise (sig)
1749 Sends a specified signal @var{sig} to the current process, where
1750 @var{sig} is as described for the @code{kill} procedure.
1753 @deffn {Scheme Procedure} sigaction signum [handler [flags [thread]]]
1754 @deffnx {C Function} scm_sigaction (signum, handler, flags)
1755 @deffnx {C Function} scm_sigaction_for_thread (signum, handler, flags, thread)
1756 Install or report the signal handler for a specified signal.
1758 @var{signum} is the signal number, which can be specified using the value
1759 of variables such as @code{SIGINT}.
1761 If @var{handler} is omitted, @code{sigaction} returns a pair: the
1762 @acronym{CAR} is the current signal hander, which will be either an
1763 integer with the value @code{SIG_DFL} (default action) or
1764 @code{SIG_IGN} (ignore), or the Scheme procedure which handles the
1765 signal, or @code{#f} if a non-Scheme procedure handles the signal.
1766 The @acronym{CDR} contains the current @code{sigaction} flags for the
1769 If @var{handler} is provided, it is installed as the new handler for
1770 @var{signum}. @var{handler} can be a Scheme procedure taking one
1771 argument, or the value of @code{SIG_DFL} (default action) or
1772 @code{SIG_IGN} (ignore), or @code{#f} to restore whatever signal handler
1773 was installed before @code{sigaction} was first used. When a scheme
1774 procedure has been specified, that procedure will run in the given
1775 @var{thread}. When no thread has been given, the thread that made this
1776 call to @code{sigaction} is used.
1778 @var{flags} is a @code{logior} (@pxref{Bitwise Operations}) of the
1779 following (where provided by the system), or @code{0} for none.
1781 @defvar SA_NOCLDSTOP
1782 By default, @code{SIGCHLD} is signalled when a child process stops
1783 (ie.@: receives @code{SIGSTOP}), and when a child process terminates.
1784 With the @code{SA_NOCLDSTOP} flag, @code{SIGCHLD} is only signalled
1785 for termination, not stopping.
1787 @code{SA_NOCLDSTOP} has no effect on signals other than
1792 If a signal occurs while in a system call, deliver the signal then
1793 restart the system call (as opposed to returning an @code{EINTR} error
1796 Guile always enables this flag where available, no matter what
1797 @var{flags} are specified. This avoids spurious error returns in low
1801 The return value is a pair with information about the old handler as
1804 This interface does not provide access to the ``signal blocking''
1805 facility. Maybe this is not needed, since the thread support may
1806 provide solutions to the problem of consistent access to data
1810 @deffn {Scheme Procedure} restore-signals
1811 @deffnx {C Function} scm_restore_signals ()
1812 Return all signal handlers to the values they had before any call to
1813 @code{sigaction} was made. The return value is unspecified.
1816 @deffn {Scheme Procedure} alarm i
1817 @deffnx {C Function} scm_alarm (i)
1818 Set a timer to raise a @code{SIGALRM} signal after the specified
1819 number of seconds (an integer). It's advisable to install a signal
1821 @code{SIGALRM} beforehand, since the default action is to terminate
1824 The return value indicates the time remaining for the previous alarm,
1825 if any. The new value replaces the previous alarm. If there was
1826 no previous alarm, the return value is zero.
1829 @deffn {Scheme Procedure} pause
1830 @deffnx {C Function} scm_pause ()
1831 Pause the current process (thread?) until a signal arrives whose
1832 action is to either terminate the current process or invoke a
1833 handler procedure. The return value is unspecified.
1836 @deffn {Scheme Procedure} sleep i
1837 @deffnx {C Function} scm_sleep (i)
1838 Wait for the given number of seconds (an integer) or until a signal
1839 arrives. The return value is zero if the time elapses or the number
1840 of seconds remaining otherwise.
1843 @deffn {Scheme Procedure} usleep i
1844 @deffnx {C Function} scm_usleep (i)
1845 Sleep for @var{i} microseconds. @code{usleep} is not available on
1846 all platforms. [FIXME: so what happens when it isn't?]
1849 @deffn {Scheme Procedure} setitimer which_timer interval_seconds interval_microseconds value_seconds value_microseconds
1850 @deffnx {C Function} scm_setitimer (which_timer, interval_seconds, interval_microseconds, value_seconds, value_microseconds)
1851 Set the timer specified by @var{which_timer} according to the given
1852 @var{interval_seconds}, @var{interval_microseconds},
1853 @var{value_seconds}, and @var{value_microseconds} values.
1855 Return information about the timer's previous setting.
1857 The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
1858 and @code{ITIMER_PROF}.
1860 The return value will be a list of two cons pairs representing the
1861 current state of the given timer. The first pair is the seconds and
1862 microseconds of the timer @code{it_interval}, and the second pair is
1863 the seconds and microseconds of the timer @code{it_value}.
1866 @deffn {Scheme Procedure} getitimer which_timer
1867 @deffnx {C Function} scm_getitimer (which_timer)
1868 Return information about the timer specified by @var{which_timer}.
1870 The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
1871 and @code{ITIMER_PROF}.
1873 The return value will be a list of two cons pairs representing the
1874 current state of the given timer. The first pair is the seconds and
1875 microseconds of the timer @code{it_interval}, and the second pair is
1876 the seconds and microseconds of the timer @code{it_value}.
1880 @node Terminals and Ptys
1881 @subsection Terminals and Ptys
1883 @deffn {Scheme Procedure} isatty? port
1884 @deffnx {C Function} scm_isatty_p (port)
1886 Return @code{#t} if @var{port} is using a serial non--file
1887 device, otherwise @code{#f}.
1890 @deffn {Scheme Procedure} ttyname port
1891 @deffnx {C Function} scm_ttyname (port)
1893 Return a string with the name of the serial terminal device
1894 underlying @var{port}.
1897 @deffn {Scheme Procedure} ctermid
1898 @deffnx {C Function} scm_ctermid ()
1900 Return a string containing the file name of the controlling
1901 terminal for the current process.
1904 @deffn {Scheme Procedure} tcgetpgrp port
1905 @deffnx {C Function} scm_tcgetpgrp (port)
1906 @cindex process group
1907 Return the process group ID of the foreground process group
1908 associated with the terminal open on the file descriptor
1909 underlying @var{port}.
1911 If there is no foreground process group, the return value is a
1912 number greater than 1 that does not match the process group ID
1913 of any existing process group. This can happen if all of the
1914 processes in the job that was formerly the foreground job have
1915 terminated, and no other job has yet been moved into the
1919 @deffn {Scheme Procedure} tcsetpgrp port pgid
1920 @deffnx {C Function} scm_tcsetpgrp (port, pgid)
1921 @cindex process group
1922 Set the foreground process group ID for the terminal used by the file
1923 descriptor underlying @var{port} to the integer @var{pgid}.
1925 must be a member of the same session as @var{pgid} and must have the same
1926 controlling terminal. The return value is unspecified.
1933 The following procedures are similar to the @code{popen} and
1934 @code{pclose} system routines. The code is in a separate ``popen''
1938 (use-modules (ice-9 popen))
1942 @deffn {Scheme Procedure} open-pipe command mode
1943 @deffnx {Scheme Procedure} open-pipe* mode prog [args...]
1944 Execute a command in a subprocess, with a pipe to it or from it, or
1945 with pipes in both directions.
1947 @code{open-pipe} runs the shell @var{command} using @samp{/bin/sh -c}.
1948 @code{open-pipe*} executes @var{prog} directly, with the optional
1949 @var{args} arguments (all strings).
1951 @var{mode} should be one of the following values. @code{OPEN_READ} is
1952 an input pipe, ie.@: to read from the subprocess. @code{OPEN_WRITE}
1953 is an output pipe, ie.@: to write to it.
1960 For an input pipe, the child's standard output is the pipe and
1961 standard input is inherited from @code{current-input-port}. For an
1962 output pipe, the child's standard input is the pipe and standard
1963 output is inherited from @code{current-output-port}. In all cases
1964 cases the child's standard error is inherited from
1965 @code{current-error-port} (@pxref{Default Ports}).
1967 If those @code{current-X-ports} are not files of some kind, and hence
1968 don't have file descriptors for the child, then @file{/dev/null} is
1971 Care should be taken with @code{OPEN_BOTH}, a deadlock will occur if
1972 both parent and child are writing, and waiting until the write
1973 completes before doing any reading. Each direction has
1974 @code{PIPE_BUF} bytes of buffering (@pxref{Ports and File
1975 Descriptors}), which will be enough for small writes, but not for say
1976 putting a big file through a filter.
1979 @deffn {Scheme Procedure} open-input-pipe command
1980 Equivalent to @code{open-pipe} with mode @code{OPEN_READ}.
1983 (let* ((port (open-input-pipe "date --utc"))
1984 (str (read-line port)))
1987 @result{} "Mon Mar 11 20:10:44 UTC 2002"
1991 @deffn {Scheme Procedure} open-output-pipe command
1992 Equivalent to @code{open-pipe} with mode @code{OPEN_WRITE}.
1995 (let ((port (open-output-pipe "lpr")))
1996 (display "Something for the line printer.\n" port)
1997 (if (not (eqv? 0 (status:exit-val (close-pipe port))))
1998 (error "Cannot print")))
2002 @deffn {Scheme Procedure} open-input-output-pipe command
2003 Equivalent to @code{open-pipe} with mode @code{OPEN_BOTH}.
2007 @deffn {Scheme Procedure} close-pipe port
2008 Close a pipe created by @code{open-pipe}, wait for the process to
2009 terminate, and return the wait status code. The status is as per
2010 @code{waitpid} and can be decoded with @code{status:exit-val} etc
2015 @code{waitpid WAIT_ANY} should not be used when pipes are open, since
2016 it can reap a pipe's child process, causing an error from a subsequent
2019 @code{close-port} (@pxref{Closing}) can close a pipe, but it doesn't
2020 reap the child process.
2022 The garbage collector will close a pipe no longer in use, and reap the
2023 child process with @code{waitpid}. If the child hasn't yet terminated
2024 the garbage collector doesn't block, but instead checks again in the
2027 Many systems have per-user and system-wide limits on the number of
2028 processes, and a system-wide limit on the number of pipes, so pipes
2029 should be closed explicitly when no longer needed, rather than letting
2030 the garbage collector pick them up at some later time.
2034 @subsection Networking
2038 * Network Address Conversion::
2039 * Network Databases::
2040 * Network Sockets and Communication::
2041 * Internet Socket Examples::
2044 @node Network Address Conversion
2045 @subsubsection Network Address Conversion
2046 @cindex network address
2048 This section describes procedures which convert internet addresses
2049 between numeric and string formats.
2051 @subsubheading IPv4 Address Conversion
2054 An IPv4 Internet address is a 4-byte value, represented in Guile as an
2055 integer in network byte order (meaning the first byte is the most
2056 significant in the number).
2058 @defvar INADDR_LOOPBACK
2059 The address of the local host using the loopback device, ie.@:
2063 @defvar INADDR_BROADCAST
2064 The broadcast address on the local network.
2067 @c INADDR_NONE is defined in the code, but serves no purpose.
2068 @c inet_addr() returns it as an error indication, but that function
2069 @c isn't provided, for the good reason that inet_aton() does the same
2070 @c job and gives an unambiguous error indication. (INADDR_NONE is a
2071 @c valid 4-byte value, in glibc it's the same as INADDR_BROADCAST.)
2073 @c @defvar INADDR_NONE
2077 @deffn {Scheme Procedure} inet-aton address
2078 @deffnx {C Function} scm_inet_aton (address)
2079 Convert an IPv4 Internet address from printable string
2080 (dotted decimal notation) to an integer. E.g.,
2083 (inet-aton "127.0.0.1") @result{} 2130706433
2087 @deffn {Scheme Procedure} inet-ntoa inetid
2088 @deffnx {C Function} scm_inet_ntoa (inetid)
2089 Convert an IPv4 Internet address to a printable
2090 (dotted decimal notation) string. E.g.,
2093 (inet-ntoa 2130706433) @result{} "127.0.0.1"
2097 @deffn {Scheme Procedure} inet-netof address
2098 @deffnx {C Function} scm_inet_netof (address)
2099 Return the network number part of the given IPv4
2100 Internet address. E.g.,
2103 (inet-netof 2130706433) @result{} 127
2107 @deffn {Scheme Procedure} inet-lnaof address
2108 @deffnx {C Function} scm_lnaof (address)
2109 Return the local-address-with-network part of the given
2110 IPv4 Internet address, using the obsolete class A/B/C system.
2114 (inet-lnaof 2130706433) @result{} 1
2118 @deffn {Scheme Procedure} inet-makeaddr net lna
2119 @deffnx {C Function} scm_inet_makeaddr (net, lna)
2120 Make an IPv4 Internet address by combining the network number
2121 @var{net} with the local-address-within-network number
2125 (inet-makeaddr 127 1) @result{} 2130706433
2129 @subsubheading IPv6 Address Conversion
2132 @deffn {Scheme Procedure} inet-ntop family address
2133 @deffnx {C Function} scm_inet_ntop (family, address)
2134 Convert a network address into a printable string.
2135 Note that unlike the C version of this function,
2136 the input is an integer with normal host byte ordering.
2137 @var{family} can be @code{AF_INET} or @code{AF_INET6}. E.g.,
2140 (inet-ntop AF_INET 2130706433) @result{} "127.0.0.1"
2141 (inet-ntop AF_INET6 (- (expt 2 128) 1)) @result{}
2142 ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
2146 @deffn {Scheme Procedure} inet-pton family address
2147 @deffnx {C Function} scm_inet_pton (family, address)
2148 Convert a string containing a printable network address to
2149 an integer address. Note that unlike the C version of this
2151 the result is an integer with normal host byte ordering.
2152 @var{family} can be @code{AF_INET} or @code{AF_INET6}. E.g.,
2155 (inet-pton AF_INET "127.0.0.1") @result{} 2130706433
2156 (inet-pton AF_INET6 "::1") @result{} 1
2161 @node Network Databases
2162 @subsubsection Network Databases
2163 @cindex network database
2165 This section describes procedures which query various network databases.
2166 Care should be taken when using the database routines since they are not
2169 @subsubheading The Host Database
2170 @cindex @file{/etc/hosts}
2171 @cindex network database
2173 A @dfn{host object} is a structure that represents what is known about a
2174 network host, and is the usual way of representing a system's network
2175 identity inside software.
2177 The following functions accept a host object and return a selected
2180 @deffn {Scheme Procedure} hostent:name host
2181 The ``official'' hostname for @var{host}.
2183 @deffn {Scheme Procedure} hostent:aliases host
2184 A list of aliases for @var{host}.
2186 @deffn {Scheme Procedure} hostent:addrtype host
2187 The host address type. For hosts with Internet addresses, this will
2188 return @code{AF_INET}.
2190 @deffn {Scheme Procedure} hostent:length host
2191 The length of each address for @var{host}, in bytes.
2193 @deffn {Scheme Procedure} hostent:addr-list host
2194 The list of network addresses associated with @var{host}.
2197 The following procedures are used to search the host database:
2199 @deffn {Scheme Procedure} gethost [host]
2200 @deffnx {Scheme Procedure} gethostbyname hostname
2201 @deffnx {Scheme Procedure} gethostbyaddr address
2202 @deffnx {C Function} scm_gethost (host)
2203 Look up a host by name or address, returning a host object. The
2204 @code{gethost} procedure will accept either a string name or an integer
2205 address; if given no arguments, it behaves like @code{gethostent} (see
2206 below). If a name or address is supplied but the address can not be
2207 found, an error will be thrown to one of the keys:
2208 @code{host-not-found}, @code{try-again}, @code{no-recovery} or
2209 @code{no-data}, corresponding to the equivalent @code{h_error} values.
2210 Unusual conditions may result in errors thrown to the
2211 @code{system-error} or @code{misc_error} keys.
2214 (gethost "www.gnu.org")
2215 @result{} #("www.gnu.org" () 2 4 (3353880842))
2217 (gethostbyname "www.emacs.org")
2218 @result{} #("emacs.org" ("www.emacs.org") 2 4 (1073448978))
2222 The following procedures may be used to step through the host
2223 database from beginning to end.
2225 @deffn {Scheme Procedure} sethostent [stayopen]
2226 Initialize an internal stream from which host objects may be read. This
2227 procedure must be called before any calls to @code{gethostent}, and may
2228 also be called afterward to reset the host entry stream. If
2229 @var{stayopen} is supplied and is not @code{#f}, the database is not
2230 closed by subsequent @code{gethostbyname} or @code{gethostbyaddr} calls,
2231 possibly giving an efficiency gain.
2234 @deffn {Scheme Procedure} gethostent
2235 Return the next host object from the host database, or @code{#f} if
2236 there are no more hosts to be found (or an error has been encountered).
2237 This procedure may not be used before @code{sethostent} has been called.
2240 @deffn {Scheme Procedure} endhostent
2241 Close the stream used by @code{gethostent}. The return value is unspecified.
2244 @deffn {Scheme Procedure} sethost [stayopen]
2245 @deffnx {C Function} scm_sethost (stayopen)
2246 If @var{stayopen} is omitted, this is equivalent to @code{endhostent}.
2247 Otherwise it is equivalent to @code{sethostent stayopen}.
2250 @subsubheading The Network Database
2251 @cindex network database
2253 The following functions accept an object representing a network
2254 and return a selected component:
2256 @deffn {Scheme Procedure} netent:name net
2257 The ``official'' network name.
2259 @deffn {Scheme Procedure} netent:aliases net
2260 A list of aliases for the network.
2262 @deffn {Scheme Procedure} netent:addrtype net
2263 The type of the network number. Currently, this returns only
2266 @deffn {Scheme Procedure} netent:net net
2270 The following procedures are used to search the network database:
2272 @deffn {Scheme Procedure} getnet [net]
2273 @deffnx {Scheme Procedure} getnetbyname net-name
2274 @deffnx {Scheme Procedure} getnetbyaddr net-number
2275 @deffnx {C Function} scm_getnet (net)
2276 Look up a network by name or net number in the network database. The
2277 @var{net-name} argument must be a string, and the @var{net-number}
2278 argument must be an integer. @code{getnet} will accept either type of
2279 argument, behaving like @code{getnetent} (see below) if no arguments are
2283 The following procedures may be used to step through the network
2284 database from beginning to end.
2286 @deffn {Scheme Procedure} setnetent [stayopen]
2287 Initialize an internal stream from which network objects may be read. This
2288 procedure must be called before any calls to @code{getnetent}, and may
2289 also be called afterward to reset the net entry stream. If
2290 @var{stayopen} is supplied and is not @code{#f}, the database is not
2291 closed by subsequent @code{getnetbyname} or @code{getnetbyaddr} calls,
2292 possibly giving an efficiency gain.
2295 @deffn {Scheme Procedure} getnetent
2296 Return the next entry from the network database.
2299 @deffn {Scheme Procedure} endnetent
2300 Close the stream used by @code{getnetent}. The return value is unspecified.
2303 @deffn {Scheme Procedure} setnet [stayopen]
2304 @deffnx {C Function} scm_setnet (stayopen)
2305 If @var{stayopen} is omitted, this is equivalent to @code{endnetent}.
2306 Otherwise it is equivalent to @code{setnetent stayopen}.
2309 @subsubheading The Protocol Database
2310 @cindex @file{/etc/protocols}
2312 @cindex network protocols
2314 The following functions accept an object representing a protocol
2315 and return a selected component:
2317 @deffn {Scheme Procedure} protoent:name protocol
2318 The ``official'' protocol name.
2320 @deffn {Scheme Procedure} protoent:aliases protocol
2321 A list of aliases for the protocol.
2323 @deffn {Scheme Procedure} protoent:proto protocol
2324 The protocol number.
2327 The following procedures are used to search the protocol database:
2329 @deffn {Scheme Procedure} getproto [protocol]
2330 @deffnx {Scheme Procedure} getprotobyname name
2331 @deffnx {Scheme Procedure} getprotobynumber number
2332 @deffnx {C Function} scm_getproto (protocol)
2333 Look up a network protocol by name or by number. @code{getprotobyname}
2334 takes a string argument, and @code{getprotobynumber} takes an integer
2335 argument. @code{getproto} will accept either type, behaving like
2336 @code{getprotoent} (see below) if no arguments are supplied.
2339 The following procedures may be used to step through the protocol
2340 database from beginning to end.
2342 @deffn {Scheme Procedure} setprotoent [stayopen]
2343 Initialize an internal stream from which protocol objects may be read. This
2344 procedure must be called before any calls to @code{getprotoent}, and may
2345 also be called afterward to reset the protocol entry stream. If
2346 @var{stayopen} is supplied and is not @code{#f}, the database is not
2347 closed by subsequent @code{getprotobyname} or @code{getprotobynumber} calls,
2348 possibly giving an efficiency gain.
2351 @deffn {Scheme Procedure} getprotoent
2352 Return the next entry from the protocol database.
2355 @deffn {Scheme Procedure} endprotoent
2356 Close the stream used by @code{getprotoent}. The return value is unspecified.
2359 @deffn {Scheme Procedure} setproto [stayopen]
2360 @deffnx {C Function} scm_setproto (stayopen)
2361 If @var{stayopen} is omitted, this is equivalent to @code{endprotoent}.
2362 Otherwise it is equivalent to @code{setprotoent stayopen}.
2365 @subsubheading The Service Database
2366 @cindex @file{/etc/services}
2368 @cindex network services
2370 The following functions accept an object representing a service
2371 and return a selected component:
2373 @deffn {Scheme Procedure} servent:name serv
2374 The ``official'' name of the network service.
2376 @deffn {Scheme Procedure} servent:aliases serv
2377 A list of aliases for the network service.
2379 @deffn {Scheme Procedure} servent:port serv
2380 The Internet port used by the service.
2382 @deffn {Scheme Procedure} servent:proto serv
2383 The protocol used by the service. A service may be listed many times
2384 in the database under different protocol names.
2387 The following procedures are used to search the service database:
2389 @deffn {Scheme Procedure} getserv [name [protocol]]
2390 @deffnx {Scheme Procedure} getservbyname name protocol
2391 @deffnx {Scheme Procedure} getservbyport port protocol
2392 @deffnx {C Function} scm_getserv (name, protocol)
2393 Look up a network service by name or by service number, and return a
2394 network service object. The @var{protocol} argument specifies the name
2395 of the desired protocol; if the protocol found in the network service
2396 database does not match this name, a system error is signalled.
2398 The @code{getserv} procedure will take either a service name or number
2399 as its first argument; if given no arguments, it behaves like
2400 @code{getservent} (see below).
2403 (getserv "imap" "tcp")
2404 @result{} #("imap2" ("imap") 143 "tcp")
2406 (getservbyport 88 "udp")
2407 @result{} #("kerberos" ("kerberos5" "krb5") 88 "udp")
2411 The following procedures may be used to step through the service
2412 database from beginning to end.
2414 @deffn {Scheme Procedure} setservent [stayopen]
2415 Initialize an internal stream from which service objects may be read. This
2416 procedure must be called before any calls to @code{getservent}, and may
2417 also be called afterward to reset the service entry stream. If
2418 @var{stayopen} is supplied and is not @code{#f}, the database is not
2419 closed by subsequent @code{getservbyname} or @code{getservbyport} calls,
2420 possibly giving an efficiency gain.
2423 @deffn {Scheme Procedure} getservent
2424 Return the next entry from the services database.
2427 @deffn {Scheme Procedure} endservent
2428 Close the stream used by @code{getservent}. The return value is unspecified.
2431 @deffn {Scheme Procedure} setserv [stayopen]
2432 @deffnx {C Function} scm_setserv (stayopen)
2433 If @var{stayopen} is omitted, this is equivalent to @code{endservent}.
2434 Otherwise it is equivalent to @code{setservent stayopen}.
2437 @node Network Sockets and Communication
2438 @subsubsection Network Sockets and Communication
2440 @cindex network socket
2442 Socket ports can be created using @code{socket} and @code{socketpair}.
2443 The ports are initially unbuffered, to make reading and writing to the
2444 same port more reliable. A buffer can be added to the port using
2445 @code{setvbuf}; see @ref{Ports and File Descriptors}.
2447 Most systems have limits on how many files and sockets can be open, so
2448 it's strongly recommended that socket ports be closed explicitly when
2449 no longer required (@pxref{Ports}).
2451 The convention used for ``host'' vs.@: ``network'' addresses is that
2452 addresses are always held in host order at the Scheme level. The
2453 procedures in this section automatically convert between host and
2454 network order when required. The arguments and return values are thus
2457 @deffn {Scheme Procedure} socket family style proto
2458 @deffnx {C Function} scm_socket (family, style, proto)
2459 Return a new socket port of the type specified by @var{family},
2460 @var{style} and @var{proto}. All three parameters are integers. The
2461 possible values for @var{family} are as follows, where supported by
2469 The possible values for @var{style} are as follows, again where
2470 supported by the system,
2476 @defvarx SOCK_SEQPACKET
2479 @var{proto} can be obtained from a protocol name using
2480 @code{getprotobyname} (@pxref{Network Databases}). A value of zero
2481 means the default protocol, which is usually right.
2483 A socket cannot by used for communication until it has been connected
2484 somewhere, usually with either @code{connect} or @code{accept} below.
2487 @deffn {Scheme Procedure} socketpair family style proto
2488 @deffnx {C Function} scm_socketpair (family, style, proto)
2489 Return a pair, the @code{car} and @code{cdr} of which are two unnamed
2490 socket ports connected to each other. The connection is full-duplex,
2491 so data can be transferred in either direction between the two.
2493 @var{family}, @var{style} and @var{proto} are as per @code{socket}
2494 above. But many systems only support socket pairs in the
2495 @code{PF_UNIX} family. Zero is likely to be the only meaningful value
2499 @deffn {Scheme Procedure} getsockopt sock level optname
2500 @deffnx {Scheme Procedure} setsockopt sock level optname value
2501 @deffnx {C Function} scm_getsockopt (sock, level, optname)
2502 @deffnx {C Function} scm_setsockopt (sock, level, optname, value)
2503 Get or set an option on socket port @var{sock}. @code{getsockopt}
2504 returns the current value. @code{setsockopt} sets a value and the
2505 return is unspecified.
2507 @var{level} is an integer specifying a protocol layer, either
2508 @code{SOL_SOCKET} for socket level options, or a protocol number from
2509 the @code{IPPROTO} constants or @code{getprotoent} (@pxref{Network
2514 @defvarx IPPROTO_TCP
2515 @defvarx IPPROTO_UDP
2518 @var{optname} is an integer specifying an option within the protocol
2521 For @code{SOL_SOCKET} level the following @var{optname}s are defined
2522 (when provided by the system). For their meaning see
2523 @ref{Socket-Level Options,,, libc, The GNU C Library Reference
2524 Manual}, or @command{man 7 socket}.
2527 @defvarx SO_REUSEADDR
2531 @defvarx SO_DONTROUTE
2532 @defvarx SO_BROADCAST
2535 @defvarx SO_KEEPALIVE
2536 @defvarx SO_OOBINLINE
2537 @defvarx SO_NO_CHECK
2538 @defvarx SO_PRIORITY
2539 The @var{value} taken or returned is an integer.
2543 The @var{value} taken or returned is a pair of integers
2544 @code{(@var{ENABLE} . @var{TIMEOUT})}. On old systems without timeout
2545 support (ie.@: without @code{struct linger}), only @var{ENABLE} has an
2546 effect but the value in Guile is always a pair.
2549 @c Note that we refer only to ``man ip'' here. On GNU/Linux it's
2550 @c ``man 7 ip'' but on NetBSD it's ``man 4 ip''.
2552 For IP level (@code{IPPROTO_IP}) the following @var{optname}s are
2553 defined (when provided by the system). See @command{man ip} for what
2556 @defvar IP_ADD_MEMBERSHIP
2557 @defvarx IP_DROP_MEMBERSHIP
2558 These can be used only with @code{setsockopt}, not @code{getsockopt}.
2559 @var{value} is a pair @code{(@var{MULTIADDR} . @var{INTERFACEADDR})}
2560 of IPv4 addresses (@pxref{Network Address Conversion}).
2561 @var{MULTIADDR} is a multicast address to be added to or dropped from
2562 the interface @var{INTERFACEADDR}. @var{INTERFACEADDR} can be
2563 @code{INADDR_ANY} to have the system select the interface.
2564 @var{INTERFACEADDR} can also be an interface index number, on systems
2569 @deffn {Scheme Procedure} shutdown sock how
2570 @deffnx {C Function} scm_shutdown (sock, how)
2571 Sockets can be closed simply by using @code{close-port}. The
2572 @code{shutdown} procedure allows reception or transmission on a
2573 connection to be shut down individually, according to the parameter
2578 Stop receiving data for this socket. If further data arrives, reject it.
2580 Stop trying to transmit data from this socket. Discard any
2581 data waiting to be sent. Stop looking for acknowledgement of
2582 data already sent; don't retransmit it if it is lost.
2584 Stop both reception and transmission.
2587 The return value is unspecified.
2590 @deffn {Scheme Procedure} connect sock fam address . args
2591 @deffnx {C Function} scm_connect (sock, fam, address, args)
2592 Initiate a connection from a socket using a specified address
2593 family to the address
2594 specified by @var{address} and possibly @var{args}.
2595 The format required for @var{address}
2596 and @var{args} depends on the family of the socket.
2598 For a socket of family @code{AF_UNIX},
2599 only @var{address} is specified and must be a string with the
2600 filename where the socket is to be created.
2602 For a socket of family @code{AF_INET},
2603 @var{address} must be an integer IPv4 host address and
2604 @var{args} must be a single integer port number.
2606 For a socket of family @code{AF_INET6},
2607 @var{address} must be an integer IPv6 host address and
2608 @var{args} may be up to three integers:
2609 port [flowinfo] [scope_id],
2610 where flowinfo and scope_id default to zero.
2612 The return value is unspecified.
2615 @deffn {Scheme Procedure} bind sock fam address . args
2616 @deffnx {C Function} scm_bind (sock, fam, address, args)
2617 Assign an address to the socket port @var{sock}.
2618 Generally this only needs to be done for server sockets,
2619 so they know where to look for incoming connections. A socket
2620 without an address will be assigned one automatically when it
2621 starts communicating.
2623 The format of @var{address} and @var{args} depends
2624 on the family of the socket.
2626 For a socket of family @code{AF_UNIX}, only @var{address}
2627 is specified and must be a string with the filename where
2628 the socket is to be created.
2630 For a socket of family @code{AF_INET}, @var{address}
2631 must be an integer IPv4 address and @var{args}
2632 must be a single integer port number.
2634 The values of the following variables can also be used for
2638 Allow connections from any address.
2641 @defvar INADDR_LOOPBACK
2642 The address of the local host using the loopback device.
2645 @defvar INADDR_BROADCAST
2646 The broadcast address on the local network.
2653 For a socket of family @code{AF_INET6}, @var{address}
2654 must be an integer IPv6 address and @var{args}
2655 may be up to three integers:
2656 port [flowinfo] [scope_id],
2657 where flowinfo and scope_id default to zero.
2659 The return value is unspecified.
2662 @deffn {Scheme Procedure} listen sock backlog
2663 @deffnx {C Function} scm_listen (sock, backlog)
2664 Enable @var{sock} to accept connection
2665 requests. @var{backlog} is an integer specifying
2666 the maximum length of the queue for pending connections.
2667 If the queue fills, new clients will fail to connect until
2668 the server calls @code{accept} to accept a connection from
2671 The return value is unspecified.
2674 @deffn {Scheme Procedure} accept sock
2675 @deffnx {C Function} scm_accept (sock)
2676 Accept a connection on a bound, listening socket.
2678 are no pending connections in the queue, wait until
2679 one is available unless the non-blocking option has been
2682 The return value is a
2683 pair in which the @acronym{CAR} is a new socket port for the
2685 the @acronym{CDR} is an object with address information about the
2686 client which initiated the connection.
2688 @var{sock} does not become part of the
2689 connection and will continue to accept new requests.
2692 The following functions take a socket address object, as returned
2693 by @code{accept} and other procedures, and return a selected component.
2695 @deffn {Scheme Procedure} sockaddr:fam sa
2696 The socket family, typically equal to the value of @code{AF_UNIX} or
2699 @deffn {Scheme Procedure} sockaddr:path sa
2700 If the socket family is @code{AF_UNIX}, returns the path of the
2701 filename the socket is based on.
2703 @deffn {Scheme Procedure} sockaddr:addr sa
2704 If the socket family is @code{AF_INET}, returns the Internet host
2707 @deffn {Scheme Procedure} sockaddr:port sa
2708 If the socket family is @code{AF_INET}, returns the Internet port
2712 @deffn {Scheme Procedure} getsockname sock
2713 @deffnx {C Function} scm_getsockname (sock)
2714 Return the address of @var{sock}, in the same form as the
2715 object returned by @code{accept}. On many systems the address
2716 of a socket in the @code{AF_FILE} namespace cannot be read.
2719 @deffn {Scheme Procedure} getpeername sock
2720 @deffnx {C Function} scm_getpeername (sock)
2721 Return the address that @var{sock}
2722 is connected to, in the same form as the object returned by
2723 @code{accept}. On many systems the address of a socket in the
2724 @code{AF_FILE} namespace cannot be read.
2727 @deffn {Scheme Procedure} recv! sock buf [flags]
2728 @deffnx {C Function} scm_recv (sock, buf, flags)
2729 Receive data from a socket port.
2730 @var{sock} must already
2731 be bound to the address from which data is to be received.
2732 @var{buf} is a string into which
2733 the data will be written. The size of @var{buf} limits
2735 data which can be received: in the case of packet
2736 protocols, if a packet larger than this limit is encountered
2738 will be irrevocably lost.
2742 @vindex MSG_DONTROUTE
2743 The optional @var{flags} argument is a value or bitwise OR of
2744 @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
2746 The value returned is the number of bytes read from the
2749 Note that the data is read directly from the socket file
2751 any unread buffered port data is ignored.
2754 @deffn {Scheme Procedure} send sock message [flags]
2755 @deffnx {C Function} scm_send (sock, message, flags)
2758 @vindex MSG_DONTROUTE
2759 Transmit the string @var{message} on a socket port @var{sock}.
2760 @var{sock} must already be bound to a destination address. The value
2761 returned is the number of bytes transmitted---it's possible for this
2762 to be less than the length of @var{message} if the socket is set to be
2763 non-blocking. The optional @var{flags} argument is a value or bitwise
2764 OR of @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
2766 Note that the data is written directly to the socket
2768 any unflushed buffered port data is ignored.
2771 @deffn {Scheme Procedure} recvfrom! sock str [flags [start [end]]]
2772 @deffnx {C Function} scm_recvfrom (sock, str, flags, start, end)
2773 Return data from the socket port @var{sock} and also
2774 information about where the data was received from.
2775 @var{sock} must already be bound to the address from which
2776 data is to be received. @code{str}, is a string into which the
2777 data will be written. The size of @var{str} limits the amount
2778 of data which can be received: in the case of packet protocols,
2779 if a packet larger than this limit is encountered then some
2780 data will be irrevocably lost.
2784 @vindex MSG_DONTROUTE
2785 The optional @var{flags} argument is a value or bitwise OR of
2786 @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
2788 The value returned is a pair: the @acronym{CAR} is the number of
2789 bytes read from the socket and the @acronym{CDR} an address object
2790 in the same form as returned by @code{accept}. The address
2791 will given as @code{#f} if not available, as is usually the
2792 case for stream sockets.
2794 The @var{start} and @var{end} arguments specify a substring of
2795 @var{str} to which the data should be written.
2797 Note that the data is read directly from the socket file
2798 descriptor: any unread buffered port data is ignored.
2801 @deffn {Scheme Procedure} sendto sock message fam address . args_and_flags
2802 @deffnx {C Function} scm_sendto (sock, message, fam, address, args_and_flags)
2803 Transmit the string @var{message} on the socket port
2805 destination address is specified using the @var{fam},
2807 @var{args_and_flags} arguments, in a similar way to the
2808 @code{connect} procedure. @var{args_and_flags} contains
2809 the usual connection arguments optionally followed by
2810 a flags argument, which is a value or
2811 bitwise OR of @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
2813 The value returned is the number of bytes transmitted --
2815 this to be less than the length of @var{message} if the
2817 set to be non-blocking.
2818 Note that the data is written directly to the socket
2820 any unflushed buffered port data is ignored.
2823 The following functions can be used to convert short and long integers
2824 between ``host'' and ``network'' order. Although the procedures above do
2825 this automatically for addresses, the conversion will still need to
2826 be done when sending or receiving encoded integer data from the network.
2828 @deffn {Scheme Procedure} htons value
2829 @deffnx {C Function} scm_htons (value)
2830 Convert a 16 bit quantity from host to network byte ordering.
2831 @var{value} is packed into 2 bytes, which are then converted
2832 and returned as a new integer.
2835 @deffn {Scheme Procedure} ntohs value
2836 @deffnx {C Function} scm_ntohs (value)
2837 Convert a 16 bit quantity from network to host byte ordering.
2838 @var{value} is packed into 2 bytes, which are then converted
2839 and returned as a new integer.
2842 @deffn {Scheme Procedure} htonl value
2843 @deffnx {C Function} scm_htonl (value)
2844 Convert a 32 bit quantity from host to network byte ordering.
2845 @var{value} is packed into 4 bytes, which are then converted
2846 and returned as a new integer.
2849 @deffn {Scheme Procedure} ntohl value
2850 @deffnx {C Function} scm_ntohl (value)
2851 Convert a 32 bit quantity from network to host byte ordering.
2852 @var{value} is packed into 4 bytes, which are then converted
2853 and returned as a new integer.
2856 These procedures are inconvenient to use at present, but consider:
2859 (define write-network-long
2860 (lambda (value port)
2861 (let ((v (make-uniform-vector 1 1 0)))
2862 (uniform-vector-set! v 0 (htonl value))
2863 (uniform-vector-write v port))))
2865 (define read-network-long
2867 (let ((v (make-uniform-vector 1 1 0)))
2868 (uniform-vector-read! v port)
2869 (ntohl (uniform-vector-ref v 0)))))
2873 @node Internet Socket Examples
2874 @subsubsection Network Socket Examples
2875 @cindex network examples
2876 @cindex socket examples
2878 The following give examples of how to use network sockets.
2880 @subsubheading Internet Socket Client Example
2882 @cindex socket client example
2883 The following example demonstrates an Internet socket client.
2884 It connects to the HTTP daemon running on the local machine and
2885 returns the contents of the root index URL.
2888 (let ((s (socket PF_INET SOCK_STREAM 0)))
2889 (connect s AF_INET (inet-aton "127.0.0.1") 80)
2890 (display "GET / HTTP/1.0\r\n\r\n" s)
2892 (do ((line (read-line s) (read-line s)))
2893 ((eof-object? line))
2899 @subsubheading Internet Socket Server Example
2901 @cindex socket server example
2902 The following example shows a simple Internet server which listens on
2903 port 2904 for incoming connections and sends a greeting back to the
2907 (let ((s (socket PF_INET SOCK_STREAM 0)))
2908 (setsockopt s SOL_SOCKET SO_REUSEADDR 1)
2909 ;; @r{Specific address?}
2910 ;; @r{(bind s AF_INET (inet-aton "127.0.0.1") 2904)}
2911 (bind s AF_INET INADDR_ANY 2904)
2914 (simple-format #t "Listening for clients in pid: ~S" (getpid))
2918 (let* ((client-connection (accept s))
2919 (client-details (cdr client-connection))
2920 (client (car client-connection)))
2921 (simple-format #t "Got new client connection: ~S"
2924 (simple-format #t "Client address: ~S"
2926 (sockaddr:addr client-details)))
2928 ;; @r{Send back the greeting to the client port}
2929 (display "Hello client\r\n" client)
2934 @node System Identification
2935 @subsection System Identification
2938 This section lists the various procedures Guile provides for accessing
2939 information about the system it runs on.
2941 @deffn {Scheme Procedure} uname
2942 @deffnx {C Function} scm_uname ()
2943 Return an object with some information about the computer
2944 system the program is running on.
2946 The following procedures accept an object as returned by @code{uname}
2947 and return a selected component.
2949 @deffn {Scheme Procedure} utsname:sysname un
2950 The name of the operating system.
2952 @deffn {Scheme Procedure} utsname:nodename un
2953 The network name of the computer.
2955 @deffn {Scheme Procedure} utsname:release un
2956 The current release level of the operating system implementation.
2958 @deffn {Scheme Procedure} utsname:version un
2959 The current version level within the release of the operating system.
2961 @deffn {Scheme Procedure} utsname:machine un
2962 A description of the hardware.
2966 @deffn {Scheme Procedure} gethostname
2967 @deffnx {C Function} scm_gethostname ()
2969 Return the host name of the current processor.
2972 @deffn {Scheme Procedure} sethostname name
2973 @deffnx {C Function} scm_sethostname (name)
2974 Set the host name of the current processor to @var{name}. May
2975 only be used by the superuser. The return value is not
2983 @deffn {Scheme Procedure} setlocale category [locale]
2984 @deffnx {C Function} scm_setlocale (category, locale)
2985 Get or set the current locale, used for various internationalizations.
2986 Locales are strings, such as @samp{sv_SE}.
2988 If @var{locale} is given then the locale for the given @var{category} is set
2989 and the new value returned. If @var{locale} is not given then the
2990 current value is returned. @var{category} should be one of the
2996 @defvarx LC_MESSAGES
2997 @defvarx LC_MONETARY
3003 A common usage is @samp{(setlocale LC_ALL "")}, which initializes all
3004 categories based on standard environment variables (@code{LANG} etc).
3005 For full details on categories and locale names @pxref{Locales,,
3006 Locales and Internationalization, libc, The GNU C Library Reference
3011 @subsection Encryption
3014 Please note that the procedures in this section are not suited for
3015 strong encryption, they are only interfaces to the well-known and
3016 common system library functions of the same name. They are just as good
3017 (or bad) as the underlying functions, so you should refer to your system
3018 documentation before using them.
3020 @deffn {Scheme Procedure} crypt key salt
3021 @deffnx {C Function} scm_crypt (key, salt)
3022 Encrypt @var{key} using @var{salt} as the salt value to the
3023 crypt(3) library call.
3026 Although @code{getpass} is not an encryption procedure per se, it
3027 appears here because it is often used in combination with @code{crypt}:
3029 @deffn {Scheme Procedure} getpass prompt
3030 @deffnx {C Function} scm_getpass (prompt)
3032 Display @var{prompt} to the standard error output and read
3033 a password from @file{/dev/tty}. If this file is not
3034 accessible, it reads from standard input. The password may be
3035 up to 127 characters in length. Additional characters and the
3036 terminating newline character are discarded. While reading
3037 the password, echoing and the generation of signals by special
3038 characters is disabled.
3043 @c TeX-master: "guile.texi"