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 port/fd cmd [value]
476 @deffnx {C Function} scm_fcntl (object, cmd, value)
477 Apply @var{cmd} on @var{port/fd}, either a port or file descriptor.
478 The @var{value} argument is used by the @code{SET} commands described
479 below, it's an integer value.
481 Values for @var{cmd} are:
484 Duplicate the file descriptor, the same as @code{dup->fdes} above
490 Get or set flags associated with the file descriptor. The only flag
494 ``Close on exec'', meaning the file descriptor will be closed on an
495 @code{exec} call (a successful such call). For example to set that
499 (fcntl port F_SETFD FD_CLOEXEC)
502 Or better, set it but leave any other possible future flags unchanged,
505 (fcntl port F_SETFD (logior FD_CLOEXEC
506 (fcntl port F_GETFD)))
513 Get or set flags associated with the open file. These flags are
514 @code{O_RDONLY} etc described under @code{open} above.
516 A common use is to set @code{O_NONBLOCK} on a network socket. The
517 following sets that flag, and leaves other flags unchanged.
520 (fcntl sock F_SETFL (logior O_NONBLOCK
521 (fcntl sock F_GETFL)))
527 Get or set the process ID of a socket's owner, for @code{SIGIO} signals.
531 @deffn {Scheme Procedure} flock file operation
532 @deffnx {C Function} scm_flock (file, operation)
534 Apply or remove an advisory lock on an open file.
535 @var{operation} specifies the action to be done:
538 Shared lock. More than one process may hold a shared lock
539 for a given file at a given time.
542 Exclusive lock. Only one process may hold an exclusive lock
543 for a given file at a given time.
549 Don't block when locking. This is combined with one of the other
550 operations using @code{logior} (@pxref{Bitwise Operations}). If
551 @code{flock} would block an @code{EWOULDBLOCK} error is thrown
552 (@pxref{Conventions}).
555 The return value is not specified. @var{file} may be an open
556 file descriptor or an open file descriptor port.
558 Note that @code{flock} does not lock files across NFS.
561 @deffn {Scheme Procedure} select reads writes excepts [secs [usecs]]
562 @deffnx {C Function} scm_select (reads, writes, excepts, secs, usecs)
563 This procedure has a variety of uses: waiting for the ability
564 to provide input, accept output, or the existence of
565 exceptional conditions on a collection of ports or file
566 descriptors, or waiting for a timeout to occur.
567 It also returns if interrupted by a signal.
569 @var{reads}, @var{writes} and @var{excepts} can be lists or
570 vectors, with each member a port or a file descriptor.
571 The value returned is a list of three corresponding
572 lists or vectors containing only the members which meet the
573 specified requirement. The ability of port buffers to
574 provide input or accept output is taken into account.
575 Ordering of the input lists or vectors is not preserved.
577 The optional arguments @var{secs} and @var{usecs} specify the
578 timeout. Either @var{secs} can be specified alone, as
579 either an integer or a real number, or both @var{secs} and
580 @var{usecs} can be specified as integers, in which case
581 @var{usecs} is an additional timeout expressed in
582 microseconds. If @var{secs} is omitted or is @code{#f} then
583 select will wait for as long as it takes for one of the other
584 conditions to be satisfied.
586 The scsh version of @code{select} differs as follows:
587 Only vectors are accepted for the first three arguments.
588 The @var{usecs} argument is not supported.
589 Multiple values are returned instead of a list.
590 Duplicates in the input vectors appear only once in output.
591 An additional @code{select!} interface is provided.
595 @subsection File System
598 These procedures allow querying and setting file system attributes
600 permissions, sizes and types of files); deleting, copying, renaming and
601 linking files; creating and removing directories and querying their
602 contents; syncing the file system and creating special files.
604 @deffn {Scheme Procedure} access? path how
605 @deffnx {C Function} scm_access (path, how)
606 Test accessibility of a file under the real UID and GID of the calling
607 process. The return is @code{#t} if @var{path} exists and the
608 permissions requested by @var{how} are all allowed, or @code{#f} if
611 @var{how} is an integer which is one of the following values, or a
612 bitwise-OR (@code{logior}) of multiple values.
615 Test for read permission.
618 Test for write permission.
621 Test for execute permission.
624 Test for existence of the file. This is implied by each of the other
625 tests, so there's no need to combine it with them.
628 It's important to note that @code{access?} does not simply indicate
629 what will happen on attempting to read or write a file. In normal
630 circumstances it does, but in a set-UID or set-GID program it doesn't
631 because @code{access?} tests the real ID, whereas an open or execute
632 attempt uses the effective ID.
634 A program which will never run set-UID/GID can ignore the difference
635 between real and effective IDs, but for maximum generality, especially
636 in library functions, it's best not to use @code{access?} to predict
637 the result of an open or execute, instead simply attempt that and
640 The main use for @code{access?} is to let a set-UID/GID program
641 determine what the invoking user would have been allowed to do,
642 without the greater (or perhaps lesser) privileges afforded by the
643 effective ID. For more on this, see @ref{Testing File Access,,, libc,
644 The GNU C Library Reference Manual}.
648 @deffn {Scheme Procedure} stat object
649 @deffnx {C Function} scm_stat (object)
650 Return an object containing various information about the file
651 determined by @var{obj}. @var{obj} can be a string containing
652 a file name or a port or integer file descriptor which is open
653 on a file (in which case @code{fstat} is used as the underlying
656 The object returned by @code{stat} can be passed as a single
657 parameter to the following procedures, all of which return
660 @deffn {Scheme Procedure} stat:dev st
661 The device number containing the file.
663 @deffn {Scheme Procedure} stat:ino st
664 The file serial number, which distinguishes this file from all
665 other files on the same device.
667 @deffn {Scheme Procedure} stat:mode st
668 The mode of the file. This is an integer which incorporates file type
669 information and file permission bits. See also @code{stat:type} and
670 @code{stat:perms} below.
672 @deffn {Scheme Procedure} stat:nlink st
673 The number of hard links to the file.
675 @deffn {Scheme Procedure} stat:uid st
676 The user ID of the file's owner.
678 @deffn {Scheme Procedure} stat:gid st
679 The group ID of the file.
681 @deffn {Scheme Procedure} stat:rdev st
682 Device ID; this entry is defined only for character or block special
683 files. On some systems this field is not available at all, in which
684 case @code{stat:rdev} returns @code{#f}.
686 @deffn {Scheme Procedure} stat:size st
687 The size of a regular file in bytes.
689 @deffn {Scheme Procedure} stat:atime st
690 The last access time for the file.
692 @deffn {Scheme Procedure} stat:mtime st
693 The last modification time for the file.
695 @deffn {Scheme Procedure} stat:ctime st
696 The last modification time for the attributes of the file.
698 @deffn {Scheme Procedure} stat:blksize st
699 The optimal block size for reading or writing the file, in bytes. On
700 some systems this field is not available, in which case
701 @code{stat:blksize} returns a sensible suggested block size.
703 @deffn {Scheme Procedure} stat:blocks st
704 The amount of disk space that the file occupies measured in units of
705 512 byte blocks. On some systems this field is not available, in
706 which case @code{stat:blocks} returns @code{#f}.
709 In addition, the following procedures return the information
710 from @code{stat:mode} in a more convenient form:
712 @deffn {Scheme Procedure} stat:type st
713 A symbol representing the type of file. Possible values are
714 @samp{regular}, @samp{directory}, @samp{symlink},
715 @samp{block-special}, @samp{char-special}, @samp{fifo}, @samp{socket},
718 @deffn {Scheme Procedure} stat:perms st
719 An integer representing the access permission bits.
723 @deffn {Scheme Procedure} lstat str
724 @deffnx {C Function} scm_lstat (str)
725 Similar to @code{stat}, but does not follow symbolic links, i.e.,
726 it will return information about a symbolic link itself, not the
727 file it points to. @var{path} must be a string.
730 @deffn {Scheme Procedure} readlink path
731 @deffnx {C Function} scm_readlink (path)
732 Return the value of the symbolic link named by @var{path} (a
733 string), i.e., the file that the link points to.
738 @deffn {Scheme Procedure} chown object owner group
739 @deffnx {C Function} scm_chown (object, owner, group)
740 Change the ownership and group of the file referred to by @var{object}
741 to the integer values @var{owner} and @var{group}. @var{object} can
742 be a string containing a file name or, if the platform supports
743 @code{fchown} (@pxref{File Owner,,,libc,The GNU C Library Reference
744 Manual}), a port or integer file descriptor which is open on the file.
745 The return value is unspecified.
747 If @var{object} is a symbolic link, either the
748 ownership of the link or the ownership of the referenced file will be
749 changed depending on the operating system (lchown is
750 unsupported at present). If @var{owner} or @var{group} is specified
751 as @code{-1}, then that ID is not changed.
755 @deffn {Scheme Procedure} chmod object mode
756 @deffnx {C Function} scm_chmod (object, mode)
757 Changes the permissions of the file referred to by @var{obj}.
758 @var{obj} can be a string containing a file name or a port or integer file
759 descriptor which is open on a file (in which case @code{fchmod} is used
760 as the underlying system call).
762 the new permissions as a decimal number, e.g., @code{(chmod "foo" #o755)}.
763 The return value is unspecified.
766 @deffn {Scheme Procedure} utime pathname [actime [modtime]]
767 @deffnx {C Function} scm_utime (pathname, actime, modtime)
769 @code{utime} sets the access and modification times for the
770 file named by @var{path}. If @var{actime} or @var{modtime} is
771 not supplied, then the current time is used. @var{actime} and
772 @var{modtime} must be integer time values as returned by the
773 @code{current-time} procedure.
775 (utime "foo" (- (current-time) 3600))
777 will set the access time to one hour in the past and the
778 modification time to the current time.
782 @deffn {Scheme Procedure} delete-file str
783 @deffnx {C Function} scm_delete_file (str)
784 Deletes (or ``unlinks'') the file whose path is specified by
788 @deffn {Scheme Procedure} copy-file oldfile newfile
789 @deffnx {C Function} scm_copy_file (oldfile, newfile)
790 Copy the file specified by @var{oldfile} to @var{newfile}.
791 The return value is unspecified.
795 @deffn {Scheme Procedure} rename-file oldname newname
796 @deffnx {C Function} scm_rename (oldname, newname)
797 Renames the file specified by @var{oldname} to @var{newname}.
798 The return value is unspecified.
801 @deffn {Scheme Procedure} link oldpath newpath
802 @deffnx {C Function} scm_link (oldpath, newpath)
803 Creates a new name @var{newpath} in the file system for the
804 file named by @var{oldpath}. If @var{oldpath} is a symbolic
805 link, the link may or may not be followed depending on the
809 @deffn {Scheme Procedure} symlink oldpath newpath
810 @deffnx {C Function} scm_symlink (oldpath, newpath)
811 Create a symbolic link named @var{newpath} with the value (i.e., pointing to)
812 @var{oldpath}. The return value is unspecified.
815 @deffn {Scheme Procedure} mkdir path [mode]
816 @deffnx {C Function} scm_mkdir (path, mode)
817 Create a new directory named by @var{path}. If @var{mode} is omitted
818 then the permissions of the directory file are set using the current
819 umask (@pxref{Processes}). Otherwise they are set to the decimal
820 value specified with @var{mode}. The return value is unspecified.
823 @deffn {Scheme Procedure} rmdir path
824 @deffnx {C Function} scm_rmdir (path)
825 Remove the existing directory named by @var{path}. The directory must
826 be empty for this to succeed. The return value is unspecified.
829 @deffn {Scheme Procedure} opendir dirname
830 @deffnx {C Function} scm_opendir (dirname)
831 @cindex directory contents
832 Open the directory specified by @var{dirname} and return a directory
836 @deffn {Scheme Procedure} directory-stream? object
837 @deffnx {C Function} scm_directory_stream_p (object)
838 Return a boolean indicating whether @var{object} is a directory
839 stream as returned by @code{opendir}.
842 @deffn {Scheme Procedure} readdir stream
843 @deffnx {C Function} scm_readdir (stream)
844 Return (as a string) the next directory entry from the directory stream
845 @var{stream}. If there is no remaining entry to be read then the
846 end of file object is returned.
849 @deffn {Scheme Procedure} rewinddir stream
850 @deffnx {C Function} scm_rewinddir (stream)
851 Reset the directory port @var{stream} so that the next call to
852 @code{readdir} will return the first directory entry.
855 @deffn {Scheme Procedure} closedir stream
856 @deffnx {C Function} scm_closedir (stream)
857 Close the directory stream @var{stream}.
858 The return value is unspecified.
861 Here is an example showing how to display all the entries in a
865 (define dir (opendir "/usr/lib"))
866 (do ((entry (readdir dir) (readdir dir)))
867 ((eof-object? entry))
868 (display entry)(newline))
872 @deffn {Scheme Procedure} sync
873 @deffnx {C Function} scm_sync ()
874 Flush the operating system disk buffers.
875 The return value is unspecified.
878 @deffn {Scheme Procedure} mknod path type perms dev
879 @deffnx {C Function} scm_mknod (path, type, perms, dev)
881 Creates a new special file, such as a file corresponding to a device.
882 @var{path} specifies the name of the file. @var{type} should be one
883 of the following symbols: @samp{regular}, @samp{directory},
884 @samp{symlink}, @samp{block-special}, @samp{char-special},
885 @samp{fifo}, or @samp{socket}. @var{perms} (an integer) specifies the
886 file permissions. @var{dev} (an integer) specifies which device the
887 special file refers to. Its exact interpretation depends on the kind
888 of special file being created.
892 (mknod "/dev/fd0" 'block-special #o660 (+ (* 2 256) 2))
895 The return value is unspecified.
898 @deffn {Scheme Procedure} tmpnam
899 @deffnx {C Function} scm_tmpnam ()
900 @cindex temporary file
901 Return an auto-generated name of a temporary file, a file which
902 doesn't already exist. The name includes a path, it's usually in
903 @file{/tmp} but that's system dependent.
905 Care must be taken when using @code{tmpnam}. In between choosing the
906 name and creating the file another program might use that name, or an
907 attacker might even make it a symlink pointing at something important
908 and causing you to overwrite that.
910 The safe way is to create the file using @code{open} with
911 @code{O_EXCL} to avoid any overwriting. A loop can try again with
912 another name if the file exists (error @code{EEXIST}).
913 @code{mkstemp!} below does that.
916 @deffn {Scheme Procedure} mkstemp! tmpl
917 @deffnx {C Function} scm_mkstemp (tmpl)
918 @cindex temporary file
919 Create a new unique file in the file system and return a new buffered
920 port open for reading and writing to the file.
922 @var{tmpl} is a string specifying where the file should be created: it
923 must end with @samp{XXXXXX} and those @samp{X}s will be changed in the
924 string to return the name of the file. (@code{port-filename} on the
925 port also gives the name.)
927 POSIX doesn't specify the permissions mode of the file, on GNU and
928 most systems it's @code{#o600}. An application can use @code{chmod}
929 to relax that if desired. For example @code{#o666} less @code{umask},
930 which is usual for ordinary file creation,
933 (let ((port (mkstemp! (string-copy "/tmp/myfile-XXXXXX"))))
934 (chmod port (logand #o666 (lognot (umask))))
939 @deffn {Scheme Procedure} dirname filename
940 @deffnx {C Function} scm_dirname (filename)
941 Return the directory name component of the file name
942 @var{filename}. If @var{filename} does not contain a directory
943 component, @code{.} is returned.
946 @deffn {Scheme Procedure} basename filename [suffix]
947 @deffnx {C Function} scm_basename (filename, suffix)
948 Return the base name of the file name @var{filename}. The
949 base name is the file name without any directory components.
950 If @var{suffix} is provided, and is equal to the end of
951 @var{basename}, it is removed also.
954 (basename "/tmp/test.xml" ".xml")
960 @node User Information
961 @subsection User Information
962 @cindex user information
963 @cindex password file
966 The facilities in this section provide an interface to the user and
968 They should be used with care since they are not reentrant.
970 The following functions accept an object representing user information
971 and return a selected component:
973 @deffn {Scheme Procedure} passwd:name pw
974 The name of the userid.
976 @deffn {Scheme Procedure} passwd:passwd pw
977 The encrypted passwd.
979 @deffn {Scheme Procedure} passwd:uid pw
982 @deffn {Scheme Procedure} passwd:gid pw
985 @deffn {Scheme Procedure} passwd:gecos pw
988 @deffn {Scheme Procedure} passwd:dir pw
991 @deffn {Scheme Procedure} passwd:shell pw
996 @deffn {Scheme Procedure} getpwuid uid
997 Look up an integer userid in the user database.
1000 @deffn {Scheme Procedure} getpwnam name
1001 Look up a user name string in the user database.
1004 @deffn {Scheme Procedure} setpwent
1005 Initializes a stream used by @code{getpwent} to read from the user database.
1006 The next use of @code{getpwent} will return the first entry. The
1007 return value is unspecified.
1010 @deffn {Scheme Procedure} getpwent
1011 Return the next entry in the user database, using the stream set by
1015 @deffn {Scheme Procedure} endpwent
1016 Closes the stream used by @code{getpwent}. The return value is unspecified.
1019 @deffn {Scheme Procedure} setpw [arg]
1020 @deffnx {C Function} scm_setpwent (arg)
1021 If called with a true argument, initialize or reset the password data
1022 stream. Otherwise, close the stream. The @code{setpwent} and
1023 @code{endpwent} procedures are implemented on top of this.
1026 @deffn {Scheme Procedure} getpw [user]
1027 @deffnx {C Function} scm_getpwuid (user)
1028 Look up an entry in the user database. @var{obj} can be an integer,
1029 a string, or omitted, giving the behaviour of getpwuid, getpwnam
1030 or getpwent respectively.
1033 The following functions accept an object representing group information
1034 and return a selected component:
1036 @deffn {Scheme Procedure} group:name gr
1039 @deffn {Scheme Procedure} group:passwd gr
1040 The encrypted group password.
1042 @deffn {Scheme Procedure} group:gid gr
1043 The group id number.
1045 @deffn {Scheme Procedure} group:mem gr
1046 A list of userids which have this group as a supplementary group.
1050 @deffn {Scheme Procedure} getgrgid gid
1051 Look up an integer group id in the group database.
1054 @deffn {Scheme Procedure} getgrnam name
1055 Look up a group name in the group database.
1058 @deffn {Scheme Procedure} setgrent
1059 Initializes a stream used by @code{getgrent} to read from the group database.
1060 The next use of @code{getgrent} will return the first entry.
1061 The return value is unspecified.
1064 @deffn {Scheme Procedure} getgrent
1065 Return the next entry in the group database, using the stream set by
1069 @deffn {Scheme Procedure} endgrent
1070 Closes the stream used by @code{getgrent}.
1071 The return value is unspecified.
1074 @deffn {Scheme Procedure} setgr [arg]
1075 @deffnx {C Function} scm_setgrent (arg)
1076 If called with a true argument, initialize or reset the group data
1077 stream. Otherwise, close the stream. The @code{setgrent} and
1078 @code{endgrent} procedures are implemented on top of this.
1081 @deffn {Scheme Procedure} getgr [name]
1082 @deffnx {C Function} scm_getgrgid (name)
1083 Look up an entry in the group database. @var{obj} can be an integer,
1084 a string, or omitted, giving the behaviour of getgrgid, getgrnam
1085 or getgrent respectively.
1088 In addition to the accessor procedures for the user database, the
1089 following shortcut procedures are also available.
1091 @deffn {Scheme Procedure} cuserid
1092 @deffnx {C Function} scm_cuserid ()
1093 Return a string containing a user name associated with the
1094 effective user id of the process. Return @code{#f} if this
1095 information cannot be obtained.
1097 This function has been removed from the latest POSIX specification,
1098 Guile provides it only if the system has it. Using @code{(getpwuid
1099 (geteuid))} may be a better idea.
1102 @deffn {Scheme Procedure} getlogin
1103 @deffnx {C Function} scm_getlogin ()
1104 Return a string containing the name of the user logged in on
1105 the controlling terminal of the process, or @code{#f} if this
1106 information cannot be obtained.
1114 @deffn {Scheme Procedure} current-time
1115 @deffnx {C Function} scm_current_time ()
1116 Return the number of seconds since 1970-01-01 00:00:00 @acronym{UTC},
1117 excluding leap seconds.
1120 @deffn {Scheme Procedure} gettimeofday
1121 @deffnx {C Function} scm_gettimeofday ()
1122 Return a pair containing the number of seconds and microseconds
1123 since 1970-01-01 00:00:00 @acronym{UTC}, excluding leap seconds. Note:
1124 whether true microsecond resolution is available depends on the
1128 The following procedures either accept an object representing a broken down
1129 time and return a selected component, or accept an object representing
1130 a broken down time and a value and set the component to the value.
1131 The numbers in parentheses give the usual range.
1133 @deffn {Scheme Procedure} tm:sec tm
1134 @deffnx {Scheme Procedure} set-tm:sec tm val
1137 @deffn {Scheme Procedure} tm:min tm
1138 @deffnx {Scheme Procedure} set-tm:min tm val
1141 @deffn {Scheme Procedure} tm:hour tm
1142 @deffnx {Scheme Procedure} set-tm:hour tm val
1145 @deffn {Scheme Procedure} tm:mday tm
1146 @deffnx {Scheme Procedure} set-tm:mday tm val
1147 Day of the month (1-31).
1149 @deffn {Scheme Procedure} tm:mon tm
1150 @deffnx {Scheme Procedure} set-tm:mon tm val
1153 @deffn {Scheme Procedure} tm:year tm
1154 @deffnx {Scheme Procedure} set-tm:year tm val
1155 Year (70-), the year minus 1900.
1157 @deffn {Scheme Procedure} tm:wday tm
1158 @deffnx {Scheme Procedure} set-tm:wday tm val
1159 Day of the week (0-6) with Sunday represented as 0.
1161 @deffn {Scheme Procedure} tm:yday tm
1162 @deffnx {Scheme Procedure} set-tm:yday tm val
1163 Day of the year (0-364, 365 in leap years).
1165 @deffn {Scheme Procedure} tm:isdst tm
1166 @deffnx {Scheme Procedure} set-tm:isdst tm val
1167 Daylight saving indicator (0 for ``no'', greater than 0 for ``yes'', less than
1170 @deffn {Scheme Procedure} tm:gmtoff tm
1171 @deffnx {Scheme Procedure} set-tm:gmtoff tm val
1172 Time zone offset in seconds west of @acronym{UTC} (-46800 to 43200).
1174 @deffn {Scheme Procedure} tm:zone tm
1175 @deffnx {Scheme Procedure} set-tm:zone tm val
1176 Time zone label (a string), not necessarily unique.
1180 @deffn {Scheme Procedure} localtime time [zone]
1181 @deffnx {C Function} scm_localtime (time, zone)
1183 Return an object representing the broken down components of
1184 @var{time}, an integer like the one returned by
1185 @code{current-time}. The time zone for the calculation is
1186 optionally specified by @var{zone} (a string), otherwise the
1187 @env{TZ} environment variable or the system default is used.
1190 @deffn {Scheme Procedure} gmtime time
1191 @deffnx {C Function} scm_gmtime (time)
1192 Return an object representing the broken down components of
1193 @var{time}, an integer like the one returned by
1194 @code{current-time}. The values are calculated for @acronym{UTC}.
1197 @deffn {Scheme Procedure} mktime sbd-time [zone]
1198 @deffnx {C Function} scm_mktime (sbd_time, zone)
1199 For a broken down time object @var{sbd-time}, return a pair the
1200 @code{car} of which is an integer time like @code{current-time}, and
1201 the @code{cdr} of which is a new broken down time with normalized
1204 @var{zone} is a timezone string, or the default is the @env{TZ}
1205 environment variable or the system default (@pxref{TZ Variable,,
1206 Specifying the Time Zone with @env{TZ}, libc, GNU C Library Reference
1207 Manual}). @var{sbd-time} is taken to be in that @var{zone}.
1209 The following fields of @var{sbd-time} are used: @code{tm:year},
1210 @code{tm:mon}, @code{tm:mday}, @code{tm:hour}, @code{tm:min},
1211 @code{tm:sec}, @code{tm:isdst}. The values can be outside their usual
1212 ranges. For example @code{tm:hour} normally goes up to 23, but a
1213 value say 33 would mean 9 the following day.
1215 @code{tm:isdst} in @var{sbd-time} says whether the time given is with
1216 daylight savings or not. This is ignored if @var{zone} doesn't have
1217 any daylight savings adjustment amount.
1219 The broken down time in the return normalizes the values of
1220 @var{sbd-time} by bringing them into their usual ranges, and using the
1221 actual daylight savings rule for that time in @var{zone} (which may
1222 differ from what @var{sbd-time} had). The easiest way to think of
1223 this is that @var{sbd-time} plus @var{zone} converts to the integer
1224 UTC time, then a @code{localtime} is applied to get the normal
1225 presentation of that time, in @var{zone}.
1228 @deffn {Scheme Procedure} tzset
1229 @deffnx {C Function} scm_tzset ()
1230 Initialize the timezone from the @env{TZ} environment variable
1231 or the system default. It's not usually necessary to call this procedure
1232 since it's done automatically by other procedures that depend on the
1236 @deffn {Scheme Procedure} strftime format tm
1237 @deffnx {C Function} scm_strftime (format, tm)
1238 @cindex time formatting
1239 Return a string which is broken-down time structure @var{tm} formatted
1240 according to the given @var{format} string.
1242 @var{format} contains field specifications introduced by a @samp{%}
1243 character. See @ref{Formatting Calendar Time,,, libc, The GNU C
1244 Library Reference Manual}, or @samp{man 3 strftime}, for the available
1248 (strftime "%c" (localtime (current-time)))
1249 @result{} "Mon Mar 11 20:17:43 2002"
1252 If @code{setlocale} has been called (@pxref{Locales}), month and day
1253 names are from the current locale and in the locale character set.
1255 Note that @samp{%Z} might print the @code{tm:zone} in @var{tm} or it
1256 might print just the current zone (@code{tzset} above). A GNU system
1257 prints @code{tm:zone}, a strict C99 system like NetBSD prints the
1258 current zone. Perhaps in the future Guile will try to get
1259 @code{tm:zone} used always.
1261 @c The issue in the above is not just whether tm_zone exists in
1262 @c struct tm, but whether libc feels it should read it. Being a
1263 @c non-C99 field, a strict C99 program won't know to set it, quite
1264 @c likely leaving garbage there. NetBSD, which has the field,
1265 @c therefore takes the view that it mustn't read it. See the PR
1268 @c http://www.netbsd.org/cgi-bin/query-pr-single.pl?number=21722
1270 @c Uniformly making tm:zone used on all systems (all those which have
1271 @c %Z at all of course) might be nice (either mung TZ and tzset, or
1272 @c mung tzname[]). On the other hand it would make us do more than
1273 @c C99 says, and we really don't want to get intimate with the gory
1274 @c details of libc time funcs, no more than can be helped.
1278 @deffn {Scheme Procedure} strptime format string
1279 @deffnx {C Function} scm_strptime (format, string)
1280 @cindex time parsing
1281 Performs the reverse action to @code{strftime}, parsing
1282 @var{string} according to the specification supplied in
1283 @var{template}. The interpretation of month and day names is
1284 dependent on the current locale. The value returned is a pair.
1285 The @acronym{CAR} has an object with time components
1286 in the form returned by @code{localtime} or @code{gmtime},
1287 but the time zone components
1288 are not usefully set.
1289 The @acronym{CDR} reports the number of characters from @var{string}
1290 which were used for the conversion.
1293 @defvar internal-time-units-per-second
1294 The value of this variable is the number of time units per second
1295 reported by the following procedures.
1298 @deffn {Scheme Procedure} times
1299 @deffnx {C Function} scm_times ()
1300 Return an object with information about real and processor
1301 time. The following procedures accept such an object as an
1302 argument and return a selected component:
1304 @deffn {Scheme Procedure} tms:clock tms
1305 The current real time, expressed as time units relative to an
1308 @deffn {Scheme Procedure} tms:utime tms
1309 The CPU time units used by the calling process.
1311 @deffn {Scheme Procedure} tms:stime tms
1312 The CPU time units used by the system on behalf of the calling
1315 @deffn {Scheme Procedure} tms:cutime tms
1316 The CPU time units used by terminated child processes of the
1317 calling process, whose status has been collected (e.g., using
1320 @deffn {Scheme Procedure} tms:cstime tms
1321 Similarly, the CPU times units used by the system on behalf of
1322 terminated child processes.
1326 @deffn {Scheme Procedure} get-internal-real-time
1327 @deffnx {C Function} scm_get_internal_real_time ()
1328 Return the number of time units since the interpreter was
1332 @deffn {Scheme Procedure} get-internal-run-time
1333 @deffnx {C Function} scm_get_internal_run_time ()
1334 Return the number of time units of processor time used by the
1335 interpreter. Both @emph{system} and @emph{user} time are
1336 included but subprocesses are not.
1339 @node Runtime Environment
1340 @subsection Runtime Environment
1342 @deffn {Scheme Procedure} program-arguments
1343 @deffnx {Scheme Procedure} command-line
1344 @deffnx {C Function} scm_program_arguments ()
1345 @cindex command line
1346 @cindex program arguments
1347 Return the list of command line arguments passed to Guile, as a list of
1348 strings. The list includes the invoked program name, which is usually
1349 @code{"guile"}, but excludes switches and parameters for command line
1350 options like @code{-e} and @code{-l}.
1353 @deffn {Scheme Procedure} getenv nam
1354 @deffnx {C Function} scm_getenv (nam)
1356 Looks up the string @var{name} in the current environment. The return
1357 value is @code{#f} unless a string of the form @code{NAME=VALUE} is
1358 found, in which case the string @code{VALUE} is returned.
1361 @deffn {Scheme Procedure} setenv name value
1362 Modifies the environment of the current process, which is
1363 also the default environment inherited by child processes.
1365 If @var{value} is @code{#f}, then @var{name} is removed from the
1366 environment. Otherwise, the string @var{name}=@var{value} is added
1367 to the environment, replacing any existing string with name matching
1370 The return value is unspecified.
1373 @deffn {Scheme Procedure} unsetenv name
1374 Remove variable @var{name} from the environment. The
1375 name can not contain a @samp{=} character.
1378 @deffn {Scheme Procedure} environ [env]
1379 @deffnx {C Function} scm_environ (env)
1380 If @var{env} is omitted, return the current environment (in the
1381 Unix sense) as a list of strings. Otherwise set the current
1382 environment, which is also the default environment for child
1383 processes, to the supplied list of strings. Each member of
1384 @var{env} should be of the form @var{NAME}=@var{VALUE} and values of
1385 @var{NAME} should not be duplicated. If @var{env} is supplied
1386 then the return value is unspecified.
1389 @deffn {Scheme Procedure} putenv str
1390 @deffnx {C Function} scm_putenv (str)
1391 Modifies the environment of the current process, which is
1392 also the default environment inherited by child processes.
1394 If @var{string} is of the form @code{NAME=VALUE} then it will be written
1395 directly into the environment, replacing any existing environment string
1397 name matching @code{NAME}. If @var{string} does not contain an equal
1398 sign, then any existing string with name matching @var{string} will
1401 The return value is unspecified.
1406 @subsection Processes
1408 @cindex child processes
1411 @deffn {Scheme Procedure} chdir str
1412 @deffnx {C Function} scm_chdir (str)
1413 @cindex current directory
1414 Change the current working directory to @var{path}.
1415 The return value is unspecified.
1419 @deffn {Scheme Procedure} getcwd
1420 @deffnx {C Function} scm_getcwd ()
1421 Return the name of the current working directory.
1424 @deffn {Scheme Procedure} umask [mode]
1425 @deffnx {C Function} scm_umask (mode)
1426 If @var{mode} is omitted, returns a decimal number representing the
1427 current file creation mask. Otherwise the file creation mask is set
1428 to @var{mode} and the previous value is returned. @xref{Setting
1429 Permissions,,Assigning File Permissions,libc,The GNU C Library
1430 Reference Manual}, for more on how to use umasks.
1432 E.g., @code{(umask #o022)} sets the mask to octal 22/decimal 18.
1435 @deffn {Scheme Procedure} chroot path
1436 @deffnx {C Function} scm_chroot (path)
1437 Change the root directory to that specified in @var{path}.
1438 This directory will be used for path names beginning with
1439 @file{/}. The root directory is inherited by all children
1440 of the current process. Only the superuser may change the
1444 @deffn {Scheme Procedure} getpid
1445 @deffnx {C Function} scm_getpid ()
1446 Return an integer representing the current process ID.
1449 @deffn {Scheme Procedure} getgroups
1450 @deffnx {C Function} scm_getgroups ()
1451 Return a vector of integers representing the current
1452 supplementary group IDs.
1455 @deffn {Scheme Procedure} getppid
1456 @deffnx {C Function} scm_getppid ()
1457 Return an integer representing the process ID of the parent
1461 @deffn {Scheme Procedure} getuid
1462 @deffnx {C Function} scm_getuid ()
1463 Return an integer representing the current real user ID.
1466 @deffn {Scheme Procedure} getgid
1467 @deffnx {C Function} scm_getgid ()
1468 Return an integer representing the current real group ID.
1471 @deffn {Scheme Procedure} geteuid
1472 @deffnx {C Function} scm_geteuid ()
1473 Return an integer representing the current effective user ID.
1474 If the system does not support effective IDs, then the real ID
1475 is returned. @code{(provided? 'EIDs)} reports whether the
1476 system supports effective IDs.
1479 @deffn {Scheme Procedure} getegid
1480 @deffnx {C Function} scm_getegid ()
1481 Return an integer representing the current effective group ID.
1482 If the system does not support effective IDs, then the real ID
1483 is returned. @code{(provided? 'EIDs)} reports whether the
1484 system supports effective IDs.
1487 @deffn {Scheme Procedure} setgroups vec
1488 @deffnx {C Function} scm_setgroups (vec)
1489 Set the current set of supplementary group IDs to the integers in the
1490 given vector @var{vec}. The return value is unspecified.
1492 Generally only the superuser can set the process group IDs
1493 (@pxref{Setting Groups, Setting the Group IDs,, libc, The GNU C
1494 Library Reference Manual}).
1497 @deffn {Scheme Procedure} setuid id
1498 @deffnx {C Function} scm_setuid (id)
1499 Sets both the real and effective user IDs to the integer @var{id}, provided
1500 the process has appropriate privileges.
1501 The return value is unspecified.
1504 @deffn {Scheme Procedure} setgid id
1505 @deffnx {C Function} scm_setgid (id)
1506 Sets both the real and effective group IDs to the integer @var{id}, provided
1507 the process has appropriate privileges.
1508 The return value is unspecified.
1511 @deffn {Scheme Procedure} seteuid id
1512 @deffnx {C Function} scm_seteuid (id)
1513 Sets the effective user ID to the integer @var{id}, provided the process
1514 has appropriate privileges. If effective IDs are not supported, the
1515 real ID is set instead---@code{(provided? 'EIDs)} reports whether the
1516 system supports effective IDs.
1517 The return value is unspecified.
1520 @deffn {Scheme Procedure} setegid id
1521 @deffnx {C Function} scm_setegid (id)
1522 Sets the effective group ID to the integer @var{id}, provided the process
1523 has appropriate privileges. If effective IDs are not supported, the
1524 real ID is set instead---@code{(provided? 'EIDs)} reports whether the
1525 system supports effective IDs.
1526 The return value is unspecified.
1529 @deffn {Scheme Procedure} getpgrp
1530 @deffnx {C Function} scm_getpgrp ()
1531 Return an integer representing the current process group ID.
1532 This is the @acronym{POSIX} definition, not @acronym{BSD}.
1535 @deffn {Scheme Procedure} setpgid pid pgid
1536 @deffnx {C Function} scm_setpgid (pid, pgid)
1537 Move the process @var{pid} into the process group @var{pgid}. @var{pid} or
1538 @var{pgid} must be integers: they can be zero to indicate the ID of the
1540 Fails on systems that do not support job control.
1541 The return value is unspecified.
1544 @deffn {Scheme Procedure} setsid
1545 @deffnx {C Function} scm_setsid ()
1546 Creates a new session. The current process becomes the session leader
1547 and is put in a new process group. The process will be detached
1548 from its controlling terminal if it has one.
1549 The return value is an integer representing the new process group ID.
1552 @deffn {Scheme Procedure} waitpid pid [options]
1553 @deffnx {C Function} scm_waitpid (pid, options)
1554 This procedure collects status information from a child process which
1555 has terminated or (optionally) stopped. Normally it will
1556 suspend the calling process until this can be done. If more than one
1557 child process is eligible then one will be chosen by the operating system.
1559 The value of @var{pid} determines the behaviour:
1562 @item @var{pid} greater than 0
1563 Request status information from the specified child process.
1564 @item @var{pid} equal to -1 or @code{WAIT_ANY}
1566 Request status information for any child process.
1567 @item @var{pid} equal to 0 or @code{WAIT_MYPGRP}
1569 Request status information for any child process in the current process
1571 @item @var{pid} less than -1
1572 Request status information for any child process whose process group ID
1573 is @minus{}@var{pid}.
1576 The @var{options} argument, if supplied, should be the bitwise OR of the
1577 values of zero or more of the following variables:
1580 Return immediately even if there are no child processes to be collected.
1584 Report status information for stopped processes as well as terminated
1588 The return value is a pair containing:
1592 The process ID of the child process, or 0 if @code{WNOHANG} was
1593 specified and no process was collected.
1595 The integer status value.
1600 functions can be used to decode the process status code returned
1603 @deffn {Scheme Procedure} status:exit-val status
1604 @deffnx {C Function} scm_status_exit_val (status)
1605 Return the exit status value, as would be set if a process
1606 ended normally through a call to @code{exit} or @code{_exit},
1607 if any, otherwise @code{#f}.
1610 @deffn {Scheme Procedure} status:term-sig status
1611 @deffnx {C Function} scm_status_term_sig (status)
1612 Return the signal number which terminated the process, if any,
1613 otherwise @code{#f}.
1616 @deffn {Scheme Procedure} status:stop-sig status
1617 @deffnx {C Function} scm_status_stop_sig (status)
1618 Return the signal number which stopped the process, if any,
1619 otherwise @code{#f}.
1622 @deffn {Scheme Procedure} system [cmd]
1623 @deffnx {C Function} scm_system (cmd)
1624 Execute @var{cmd} using the operating system's ``command
1625 processor''. Under Unix this is usually the default shell
1626 @code{sh}. The value returned is @var{cmd}'s exit status as
1627 returned by @code{waitpid}, which can be interpreted using the
1630 If @code{system} is called without arguments, return a boolean
1631 indicating whether the command processor is available.
1634 @deffn {Scheme Procedure} system* . args
1635 @deffnx {C Function} scm_system_star (args)
1636 Execute the command indicated by @var{args}. The first element must
1637 be a string indicating the command to be executed, and the remaining
1638 items must be strings representing each of the arguments to that
1641 This function returns the exit status of the command as provided by
1642 @code{waitpid}. This value can be handled with @code{status:exit-val}
1643 and the related functions.
1645 @code{system*} is similar to @code{system}, but accepts only one
1646 string per-argument, and performs no shell interpretation. The
1647 command is executed using fork and execlp. Accordingly this function
1648 may be safer than @code{system} in situations where shell
1649 interpretation is not required.
1651 Example: (system* "echo" "foo" "bar")
1654 @deffn {Scheme Procedure} primitive-exit [status]
1655 @deffnx {Scheme Procedure} primitive-_exit [status]
1656 @deffnx {C Function} scm_primitive_exit (status)
1657 @deffnx {C Function} scm_primitive__exit (status)
1658 Terminate the current process without unwinding the Scheme stack. The
1659 exit status is @var{status} if supplied, otherwise zero.
1661 @code{primitive-exit} uses the C @code{exit} function and hence runs
1662 usual C level cleanups (flush output streams, call @code{atexit}
1663 functions, etc, see @ref{Normal Termination,,, libc, The GNU C Library
1664 Reference Manual})).
1666 @code{primitive-_exit} is the @code{_exit} system call
1667 (@pxref{Termination Internals,,, libc, The GNU C Library Reference
1668 Manual}). This terminates the program immediately, with neither
1669 Scheme-level nor C-level cleanups.
1671 The typical use for @code{primitive-_exit} is from a child process
1672 created with @code{primitive-fork}. For example in a Gdk program the
1673 child process inherits the X server connection and a C-level
1674 @code{atexit} cleanup which will close that connection. But closing
1675 in the child would upset the protocol in the parent, so
1676 @code{primitive-_exit} should be used to exit without that.
1679 @deffn {Scheme Procedure} execl filename . args
1680 @deffnx {C Function} scm_execl (filename, args)
1681 Executes the file named by @var{path} as a new process image.
1682 The remaining arguments are supplied to the process; from a C program
1683 they are accessible as the @code{argv} argument to @code{main}.
1684 Conventionally the first @var{arg} is the same as @var{path}.
1685 All arguments must be strings.
1687 If @var{arg} is missing, @var{path} is executed with a null
1688 argument list, which may have system-dependent side-effects.
1690 This procedure is currently implemented using the @code{execv} system
1691 call, but we call it @code{execl} because of its Scheme calling interface.
1694 @deffn {Scheme Procedure} execlp filename . args
1695 @deffnx {C Function} scm_execlp (filename, args)
1696 Similar to @code{execl}, however if
1697 @var{filename} does not contain a slash
1698 then the file to execute will be located by searching the
1699 directories listed in the @code{PATH} environment variable.
1701 This procedure is currently implemented using the @code{execvp} system
1702 call, but we call it @code{execlp} because of its Scheme calling interface.
1705 @deffn {Scheme Procedure} execle filename env . args
1706 @deffnx {C Function} scm_execle (filename, env, args)
1707 Similar to @code{execl}, but the environment of the new process is
1708 specified by @var{env}, which must be a list of strings as returned by the
1709 @code{environ} procedure.
1711 This procedure is currently implemented using the @code{execve} system
1712 call, but we call it @code{execle} because of its Scheme calling interface.
1715 @deffn {Scheme Procedure} primitive-fork
1716 @deffnx {C Function} scm_fork ()
1717 Creates a new ``child'' process by duplicating the current ``parent'' process.
1718 In the child the return value is 0. In the parent the return value is
1719 the integer process ID of the child.
1721 This procedure has been renamed from @code{fork} to avoid a naming conflict
1725 @deffn {Scheme Procedure} nice incr
1726 @deffnx {C Function} scm_nice (incr)
1727 @cindex process priority
1728 Increment the priority of the current process by @var{incr}. A higher
1729 priority value means that the process runs less often.
1730 The return value is unspecified.
1733 @deffn {Scheme Procedure} setpriority which who prio
1734 @deffnx {C Function} scm_setpriority (which, who, prio)
1735 @vindex PRIO_PROCESS
1738 Set the scheduling priority of the process, process group
1739 or user, as indicated by @var{which} and @var{who}. @var{which}
1740 is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
1741 or @code{PRIO_USER}, and @var{who} is interpreted relative to
1742 @var{which} (a process identifier for @code{PRIO_PROCESS},
1743 process group identifier for @code{PRIO_PGRP}, and a user
1744 identifier for @code{PRIO_USER}. A zero value of @var{who}
1745 denotes the current process, process group, or user.
1746 @var{prio} is a value in the range [@minus{}20,20]. The default
1747 priority is 0; lower priorities (in numerical terms) cause more
1748 favorable scheduling. Sets the priority of all of the specified
1749 processes. Only the super-user may lower priorities. The return
1750 value is not specified.
1753 @deffn {Scheme Procedure} getpriority which who
1754 @deffnx {C Function} scm_getpriority (which, who)
1755 @vindex PRIO_PROCESS
1758 Return the scheduling priority of the process, process group
1759 or user, as indicated by @var{which} and @var{who}. @var{which}
1760 is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
1761 or @code{PRIO_USER}, and @var{who} should be interpreted depending on
1762 @var{which} (a process identifier for @code{PRIO_PROCESS},
1763 process group identifier for @code{PRIO_PGRP}, and a user
1764 identifier for @code{PRIO_USER}). A zero value of @var{who}
1765 denotes the current process, process group, or user. Return
1766 the highest priority (lowest numerical value) of any of the
1767 specified processes.
1775 Procedures to raise, handle and wait for signals.
1777 @deffn {Scheme Procedure} kill pid sig
1778 @deffnx {C Function} scm_kill (pid, sig)
1779 Sends a signal to the specified process or group of processes.
1781 @var{pid} specifies the processes to which the signal is sent:
1784 @item @var{pid} greater than 0
1785 The process whose identifier is @var{pid}.
1786 @item @var{pid} equal to 0
1787 All processes in the current process group.
1788 @item @var{pid} less than -1
1789 The process group whose identifier is -@var{pid}
1790 @item @var{pid} equal to -1
1791 If the process is privileged, all processes except for some special
1792 system processes. Otherwise, all processes with the current effective
1796 @var{sig} should be specified using a variable corresponding to
1797 the Unix symbolic name, e.g.,
1807 A full list of signals on the GNU system may be found in @ref{Standard
1808 Signals,,,libc,The GNU C Library Reference Manual}.
1811 @deffn {Scheme Procedure} raise sig
1812 @deffnx {C Function} scm_raise (sig)
1813 Sends a specified signal @var{sig} to the current process, where
1814 @var{sig} is as described for the @code{kill} procedure.
1817 @deffn {Scheme Procedure} sigaction signum [handler [flags [thread]]]
1818 @deffnx {C Function} scm_sigaction (signum, handler, flags)
1819 @deffnx {C Function} scm_sigaction_for_thread (signum, handler, flags, thread)
1820 Install or report the signal handler for a specified signal.
1822 @var{signum} is the signal number, which can be specified using the value
1823 of variables such as @code{SIGINT}.
1825 If @var{handler} is omitted, @code{sigaction} returns a pair: the
1826 @acronym{CAR} is the current signal hander, which will be either an
1827 integer with the value @code{SIG_DFL} (default action) or
1828 @code{SIG_IGN} (ignore), or the Scheme procedure which handles the
1829 signal, or @code{#f} if a non-Scheme procedure handles the signal.
1830 The @acronym{CDR} contains the current @code{sigaction} flags for the
1833 If @var{handler} is provided, it is installed as the new handler for
1834 @var{signum}. @var{handler} can be a Scheme procedure taking one
1835 argument, or the value of @code{SIG_DFL} (default action) or
1836 @code{SIG_IGN} (ignore), or @code{#f} to restore whatever signal handler
1837 was installed before @code{sigaction} was first used. When a scheme
1838 procedure has been specified, that procedure will run in the given
1839 @var{thread}. When no thread has been given, the thread that made this
1840 call to @code{sigaction} is used.
1842 @var{flags} is a @code{logior} (@pxref{Bitwise Operations}) of the
1843 following (where provided by the system), or @code{0} for none.
1845 @defvar SA_NOCLDSTOP
1846 By default, @code{SIGCHLD} is signalled when a child process stops
1847 (ie.@: receives @code{SIGSTOP}), and when a child process terminates.
1848 With the @code{SA_NOCLDSTOP} flag, @code{SIGCHLD} is only signalled
1849 for termination, not stopping.
1851 @code{SA_NOCLDSTOP} has no effect on signals other than
1856 If a signal occurs while in a system call, deliver the signal then
1857 restart the system call (as opposed to returning an @code{EINTR} error
1860 Guile always enables this flag where available, no matter what
1861 @var{flags} are specified. This avoids spurious error returns in low
1865 The return value is a pair with information about the old handler as
1868 This interface does not provide access to the ``signal blocking''
1869 facility. Maybe this is not needed, since the thread support may
1870 provide solutions to the problem of consistent access to data
1874 @deffn {Scheme Procedure} restore-signals
1875 @deffnx {C Function} scm_restore_signals ()
1876 Return all signal handlers to the values they had before any call to
1877 @code{sigaction} was made. The return value is unspecified.
1880 @deffn {Scheme Procedure} alarm i
1881 @deffnx {C Function} scm_alarm (i)
1882 Set a timer to raise a @code{SIGALRM} signal after the specified
1883 number of seconds (an integer). It's advisable to install a signal
1885 @code{SIGALRM} beforehand, since the default action is to terminate
1888 The return value indicates the time remaining for the previous alarm,
1889 if any. The new value replaces the previous alarm. If there was
1890 no previous alarm, the return value is zero.
1893 @deffn {Scheme Procedure} pause
1894 @deffnx {C Function} scm_pause ()
1895 Pause the current process (thread?) until a signal arrives whose
1896 action is to either terminate the current process or invoke a
1897 handler procedure. The return value is unspecified.
1900 @deffn {Scheme Procedure} sleep i
1901 @deffnx {C Function} scm_sleep (i)
1902 Wait for the given number of seconds (an integer) or until a signal
1903 arrives. The return value is zero if the time elapses or the number
1904 of seconds remaining otherwise.
1907 @deffn {Scheme Procedure} usleep i
1908 @deffnx {C Function} scm_usleep (i)
1909 Sleep for @var{i} microseconds. @code{usleep} is not available on
1910 all platforms. [FIXME: so what happens when it isn't?]
1913 @deffn {Scheme Procedure} setitimer which_timer interval_seconds interval_microseconds value_seconds value_microseconds
1914 @deffnx {C Function} scm_setitimer (which_timer, interval_seconds, interval_microseconds, value_seconds, value_microseconds)
1915 Set the timer specified by @var{which_timer} according to the given
1916 @var{interval_seconds}, @var{interval_microseconds},
1917 @var{value_seconds}, and @var{value_microseconds} values.
1919 Return information about the timer's previous setting.
1921 The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
1922 and @code{ITIMER_PROF}.
1924 The return value will be a list of two cons pairs representing the
1925 current state of the given timer. The first pair is the seconds and
1926 microseconds of the timer @code{it_interval}, and the second pair is
1927 the seconds and microseconds of the timer @code{it_value}.
1930 @deffn {Scheme Procedure} getitimer which_timer
1931 @deffnx {C Function} scm_getitimer (which_timer)
1932 Return information about the timer specified by @var{which_timer}.
1934 The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
1935 and @code{ITIMER_PROF}.
1937 The return value will be a list of two cons pairs representing the
1938 current state of the given timer. The first pair is the seconds and
1939 microseconds of the timer @code{it_interval}, and the second pair is
1940 the seconds and microseconds of the timer @code{it_value}.
1944 @node Terminals and Ptys
1945 @subsection Terminals and Ptys
1947 @deffn {Scheme Procedure} isatty? port
1948 @deffnx {C Function} scm_isatty_p (port)
1950 Return @code{#t} if @var{port} is using a serial non--file
1951 device, otherwise @code{#f}.
1954 @deffn {Scheme Procedure} ttyname port
1955 @deffnx {C Function} scm_ttyname (port)
1957 Return a string with the name of the serial terminal device
1958 underlying @var{port}.
1961 @deffn {Scheme Procedure} ctermid
1962 @deffnx {C Function} scm_ctermid ()
1964 Return a string containing the file name of the controlling
1965 terminal for the current process.
1968 @deffn {Scheme Procedure} tcgetpgrp port
1969 @deffnx {C Function} scm_tcgetpgrp (port)
1970 @cindex process group
1971 Return the process group ID of the foreground process group
1972 associated with the terminal open on the file descriptor
1973 underlying @var{port}.
1975 If there is no foreground process group, the return value is a
1976 number greater than 1 that does not match the process group ID
1977 of any existing process group. This can happen if all of the
1978 processes in the job that was formerly the foreground job have
1979 terminated, and no other job has yet been moved into the
1983 @deffn {Scheme Procedure} tcsetpgrp port pgid
1984 @deffnx {C Function} scm_tcsetpgrp (port, pgid)
1985 @cindex process group
1986 Set the foreground process group ID for the terminal used by the file
1987 descriptor underlying @var{port} to the integer @var{pgid}.
1989 must be a member of the same session as @var{pgid} and must have the same
1990 controlling terminal. The return value is unspecified.
1997 The following procedures are similar to the @code{popen} and
1998 @code{pclose} system routines. The code is in a separate ``popen''
2002 (use-modules (ice-9 popen))
2006 @deffn {Scheme Procedure} open-pipe command mode
2007 @deffnx {Scheme Procedure} open-pipe* mode prog [args...]
2008 Execute a command in a subprocess, with a pipe to it or from it, or
2009 with pipes in both directions.
2011 @code{open-pipe} runs the shell @var{command} using @samp{/bin/sh -c}.
2012 @code{open-pipe*} executes @var{prog} directly, with the optional
2013 @var{args} arguments (all strings).
2015 @var{mode} should be one of the following values. @code{OPEN_READ} is
2016 an input pipe, ie.@: to read from the subprocess. @code{OPEN_WRITE}
2017 is an output pipe, ie.@: to write to it.
2024 For an input pipe, the child's standard output is the pipe and
2025 standard input is inherited from @code{current-input-port}. For an
2026 output pipe, the child's standard input is the pipe and standard
2027 output is inherited from @code{current-output-port}. In all cases
2028 cases the child's standard error is inherited from
2029 @code{current-error-port} (@pxref{Default Ports}).
2031 If those @code{current-X-ports} are not files of some kind, and hence
2032 don't have file descriptors for the child, then @file{/dev/null} is
2035 Care should be taken with @code{OPEN_BOTH}, a deadlock will occur if
2036 both parent and child are writing, and waiting until the write
2037 completes before doing any reading. Each direction has
2038 @code{PIPE_BUF} bytes of buffering (@pxref{Ports and File
2039 Descriptors}), which will be enough for small writes, but not for say
2040 putting a big file through a filter.
2043 @deffn {Scheme Procedure} open-input-pipe command
2044 Equivalent to @code{open-pipe} with mode @code{OPEN_READ}.
2047 (let* ((port (open-input-pipe "date --utc"))
2048 (str (read-line port)))
2051 @result{} "Mon Mar 11 20:10:44 UTC 2002"
2055 @deffn {Scheme Procedure} open-output-pipe command
2056 Equivalent to @code{open-pipe} with mode @code{OPEN_WRITE}.
2059 (let ((port (open-output-pipe "lpr")))
2060 (display "Something for the line printer.\n" port)
2061 (if (not (eqv? 0 (status:exit-val (close-pipe port))))
2062 (error "Cannot print")))
2066 @deffn {Scheme Procedure} open-input-output-pipe command
2067 Equivalent to @code{open-pipe} with mode @code{OPEN_BOTH}.
2071 @deffn {Scheme Procedure} close-pipe port
2072 Close a pipe created by @code{open-pipe}, wait for the process to
2073 terminate, and return the wait status code. The status is as per
2074 @code{waitpid} and can be decoded with @code{status:exit-val} etc
2079 @code{waitpid WAIT_ANY} should not be used when pipes are open, since
2080 it can reap a pipe's child process, causing an error from a subsequent
2083 @code{close-port} (@pxref{Closing}) can close a pipe, but it doesn't
2084 reap the child process.
2086 The garbage collector will close a pipe no longer in use, and reap the
2087 child process with @code{waitpid}. If the child hasn't yet terminated
2088 the garbage collector doesn't block, but instead checks again in the
2091 Many systems have per-user and system-wide limits on the number of
2092 processes, and a system-wide limit on the number of pipes, so pipes
2093 should be closed explicitly when no longer needed, rather than letting
2094 the garbage collector pick them up at some later time.
2098 @subsection Networking
2102 * Network Address Conversion::
2103 * Network Databases::
2104 * Network Socket Address::
2105 * Network Sockets and Communication::
2106 * Internet Socket Examples::
2109 @node Network Address Conversion
2110 @subsubsection Network Address Conversion
2111 @cindex network address
2113 This section describes procedures which convert internet addresses
2114 between numeric and string formats.
2116 @subsubheading IPv4 Address Conversion
2119 An IPv4 Internet address is a 4-byte value, represented in Guile as an
2120 integer in host byte order, so that say ``0.0.0.1'' is 1, or
2121 ``1.0.0.0'' is 16777216.
2123 Some underlying C functions use network byte order for addresses,
2124 Guile converts as necessary so that at the Scheme level its host byte
2128 For a server, this can be used with @code{bind} (@pxref{Network
2129 Sockets and Communication}) to allow connections from any interface on
2133 @defvar INADDR_BROADCAST
2134 The broadcast address on the local network.
2137 @defvar INADDR_LOOPBACK
2138 The address of the local host using the loopback device, ie.@:
2142 @c INADDR_NONE is defined in the code, but serves no purpose.
2143 @c inet_addr() returns it as an error indication, but that function
2144 @c isn't provided, for the good reason that inet_aton() does the same
2145 @c job and gives an unambiguous error indication. (INADDR_NONE is a
2146 @c valid 4-byte value, in glibc it's the same as INADDR_BROADCAST.)
2148 @c @defvar INADDR_NONE
2152 @deffn {Scheme Procedure} inet-aton address
2153 @deffnx {C Function} scm_inet_aton (address)
2154 Convert an IPv4 Internet address from printable string
2155 (dotted decimal notation) to an integer. E.g.,
2158 (inet-aton "127.0.0.1") @result{} 2130706433
2162 @deffn {Scheme Procedure} inet-ntoa inetid
2163 @deffnx {C Function} scm_inet_ntoa (inetid)
2164 Convert an IPv4 Internet address to a printable
2165 (dotted decimal notation) string. E.g.,
2168 (inet-ntoa 2130706433) @result{} "127.0.0.1"
2172 @deffn {Scheme Procedure} inet-netof address
2173 @deffnx {C Function} scm_inet_netof (address)
2174 Return the network number part of the given IPv4
2175 Internet address. E.g.,
2178 (inet-netof 2130706433) @result{} 127
2182 @deffn {Scheme Procedure} inet-lnaof address
2183 @deffnx {C Function} scm_lnaof (address)
2184 Return the local-address-with-network part of the given
2185 IPv4 Internet address, using the obsolete class A/B/C system.
2189 (inet-lnaof 2130706433) @result{} 1
2193 @deffn {Scheme Procedure} inet-makeaddr net lna
2194 @deffnx {C Function} scm_inet_makeaddr (net, lna)
2195 Make an IPv4 Internet address by combining the network number
2196 @var{net} with the local-address-within-network number
2200 (inet-makeaddr 127 1) @result{} 2130706433
2204 @subsubheading IPv6 Address Conversion
2207 An IPv6 Internet address is a 16-byte value, represented in Guile as
2208 an integer in host byte order, so that say ``::1'' is 1.
2210 @deffn {Scheme Procedure} inet-ntop family address
2211 @deffnx {C Function} scm_inet_ntop (family, address)
2212 Convert a network address from an integer to a printable string.
2213 @var{family} can be @code{AF_INET} or @code{AF_INET6}. E.g.,
2216 (inet-ntop AF_INET 2130706433) @result{} "127.0.0.1"
2217 (inet-ntop AF_INET6 (- (expt 2 128) 1)) @result{}
2218 ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
2222 @deffn {Scheme Procedure} inet-pton family address
2223 @deffnx {C Function} scm_inet_pton (family, address)
2224 Convert a string containing a printable network address to an integer
2225 address. @var{family} can be @code{AF_INET} or @code{AF_INET6}.
2229 (inet-pton AF_INET "127.0.0.1") @result{} 2130706433
2230 (inet-pton AF_INET6 "::1") @result{} 1
2235 @node Network Databases
2236 @subsubsection Network Databases
2237 @cindex network database
2239 This section describes procedures which query various network databases.
2240 Care should be taken when using the database routines since they are not
2243 @subsubheading The Host Database
2244 @cindex @file{/etc/hosts}
2245 @cindex network database
2247 A @dfn{host object} is a structure that represents what is known about a
2248 network host, and is the usual way of representing a system's network
2249 identity inside software.
2251 The following functions accept a host object and return a selected
2254 @deffn {Scheme Procedure} hostent:name host
2255 The ``official'' hostname for @var{host}.
2257 @deffn {Scheme Procedure} hostent:aliases host
2258 A list of aliases for @var{host}.
2260 @deffn {Scheme Procedure} hostent:addrtype host
2261 The host address type, one of the @code{AF} constants, such as
2262 @code{AF_INET} or @code{AF_INET6}.
2264 @deffn {Scheme Procedure} hostent:length host
2265 The length of each address for @var{host}, in bytes.
2267 @deffn {Scheme Procedure} hostent:addr-list host
2268 The list of network addresses associated with @var{host}. For
2269 @code{AF_INET} these are integer IPv4 address (@pxref{Network Address
2273 The following procedures are used to search the host database:
2275 @deffn {Scheme Procedure} gethost [host]
2276 @deffnx {Scheme Procedure} gethostbyname hostname
2277 @deffnx {Scheme Procedure} gethostbyaddr address
2278 @deffnx {C Function} scm_gethost (host)
2279 Look up a host by name or address, returning a host object. The
2280 @code{gethost} procedure will accept either a string name or an integer
2281 address; if given no arguments, it behaves like @code{gethostent} (see
2282 below). If a name or address is supplied but the address can not be
2283 found, an error will be thrown to one of the keys:
2284 @code{host-not-found}, @code{try-again}, @code{no-recovery} or
2285 @code{no-data}, corresponding to the equivalent @code{h_error} values.
2286 Unusual conditions may result in errors thrown to the
2287 @code{system-error} or @code{misc_error} keys.
2290 (gethost "www.gnu.org")
2291 @result{} #("www.gnu.org" () 2 4 (3353880842))
2293 (gethostbyname "www.emacs.org")
2294 @result{} #("emacs.org" ("www.emacs.org") 2 4 (1073448978))
2298 The following procedures may be used to step through the host
2299 database from beginning to end.
2301 @deffn {Scheme Procedure} sethostent [stayopen]
2302 Initialize an internal stream from which host objects may be read. This
2303 procedure must be called before any calls to @code{gethostent}, and may
2304 also be called afterward to reset the host entry stream. If
2305 @var{stayopen} is supplied and is not @code{#f}, the database is not
2306 closed by subsequent @code{gethostbyname} or @code{gethostbyaddr} calls,
2307 possibly giving an efficiency gain.
2310 @deffn {Scheme Procedure} gethostent
2311 Return the next host object from the host database, or @code{#f} if
2312 there are no more hosts to be found (or an error has been encountered).
2313 This procedure may not be used before @code{sethostent} has been called.
2316 @deffn {Scheme Procedure} endhostent
2317 Close the stream used by @code{gethostent}. The return value is unspecified.
2320 @deffn {Scheme Procedure} sethost [stayopen]
2321 @deffnx {C Function} scm_sethost (stayopen)
2322 If @var{stayopen} is omitted, this is equivalent to @code{endhostent}.
2323 Otherwise it is equivalent to @code{sethostent stayopen}.
2326 @subsubheading The Network Database
2327 @cindex network database
2329 The following functions accept an object representing a network
2330 and return a selected component:
2332 @deffn {Scheme Procedure} netent:name net
2333 The ``official'' network name.
2335 @deffn {Scheme Procedure} netent:aliases net
2336 A list of aliases for the network.
2338 @deffn {Scheme Procedure} netent:addrtype net
2339 The type of the network number. Currently, this returns only
2342 @deffn {Scheme Procedure} netent:net net
2346 The following procedures are used to search the network database:
2348 @deffn {Scheme Procedure} getnet [net]
2349 @deffnx {Scheme Procedure} getnetbyname net-name
2350 @deffnx {Scheme Procedure} getnetbyaddr net-number
2351 @deffnx {C Function} scm_getnet (net)
2352 Look up a network by name or net number in the network database. The
2353 @var{net-name} argument must be a string, and the @var{net-number}
2354 argument must be an integer. @code{getnet} will accept either type of
2355 argument, behaving like @code{getnetent} (see below) if no arguments are
2359 The following procedures may be used to step through the network
2360 database from beginning to end.
2362 @deffn {Scheme Procedure} setnetent [stayopen]
2363 Initialize an internal stream from which network objects may be read. This
2364 procedure must be called before any calls to @code{getnetent}, and may
2365 also be called afterward to reset the net entry stream. If
2366 @var{stayopen} is supplied and is not @code{#f}, the database is not
2367 closed by subsequent @code{getnetbyname} or @code{getnetbyaddr} calls,
2368 possibly giving an efficiency gain.
2371 @deffn {Scheme Procedure} getnetent
2372 Return the next entry from the network database.
2375 @deffn {Scheme Procedure} endnetent
2376 Close the stream used by @code{getnetent}. The return value is unspecified.
2379 @deffn {Scheme Procedure} setnet [stayopen]
2380 @deffnx {C Function} scm_setnet (stayopen)
2381 If @var{stayopen} is omitted, this is equivalent to @code{endnetent}.
2382 Otherwise it is equivalent to @code{setnetent stayopen}.
2385 @subsubheading The Protocol Database
2386 @cindex @file{/etc/protocols}
2388 @cindex network protocols
2390 The following functions accept an object representing a protocol
2391 and return a selected component:
2393 @deffn {Scheme Procedure} protoent:name protocol
2394 The ``official'' protocol name.
2396 @deffn {Scheme Procedure} protoent:aliases protocol
2397 A list of aliases for the protocol.
2399 @deffn {Scheme Procedure} protoent:proto protocol
2400 The protocol number.
2403 The following procedures are used to search the protocol database:
2405 @deffn {Scheme Procedure} getproto [protocol]
2406 @deffnx {Scheme Procedure} getprotobyname name
2407 @deffnx {Scheme Procedure} getprotobynumber number
2408 @deffnx {C Function} scm_getproto (protocol)
2409 Look up a network protocol by name or by number. @code{getprotobyname}
2410 takes a string argument, and @code{getprotobynumber} takes an integer
2411 argument. @code{getproto} will accept either type, behaving like
2412 @code{getprotoent} (see below) if no arguments are supplied.
2415 The following procedures may be used to step through the protocol
2416 database from beginning to end.
2418 @deffn {Scheme Procedure} setprotoent [stayopen]
2419 Initialize an internal stream from which protocol objects may be read. This
2420 procedure must be called before any calls to @code{getprotoent}, and may
2421 also be called afterward to reset the protocol entry stream. If
2422 @var{stayopen} is supplied and is not @code{#f}, the database is not
2423 closed by subsequent @code{getprotobyname} or @code{getprotobynumber} calls,
2424 possibly giving an efficiency gain.
2427 @deffn {Scheme Procedure} getprotoent
2428 Return the next entry from the protocol database.
2431 @deffn {Scheme Procedure} endprotoent
2432 Close the stream used by @code{getprotoent}. The return value is unspecified.
2435 @deffn {Scheme Procedure} setproto [stayopen]
2436 @deffnx {C Function} scm_setproto (stayopen)
2437 If @var{stayopen} is omitted, this is equivalent to @code{endprotoent}.
2438 Otherwise it is equivalent to @code{setprotoent stayopen}.
2441 @subsubheading The Service Database
2442 @cindex @file{/etc/services}
2444 @cindex network services
2446 The following functions accept an object representing a service
2447 and return a selected component:
2449 @deffn {Scheme Procedure} servent:name serv
2450 The ``official'' name of the network service.
2452 @deffn {Scheme Procedure} servent:aliases serv
2453 A list of aliases for the network service.
2455 @deffn {Scheme Procedure} servent:port serv
2456 The Internet port used by the service.
2458 @deffn {Scheme Procedure} servent:proto serv
2459 The protocol used by the service. A service may be listed many times
2460 in the database under different protocol names.
2463 The following procedures are used to search the service database:
2465 @deffn {Scheme Procedure} getserv [name [protocol]]
2466 @deffnx {Scheme Procedure} getservbyname name protocol
2467 @deffnx {Scheme Procedure} getservbyport port protocol
2468 @deffnx {C Function} scm_getserv (name, protocol)
2469 Look up a network service by name or by service number, and return a
2470 network service object. The @var{protocol} argument specifies the name
2471 of the desired protocol; if the protocol found in the network service
2472 database does not match this name, a system error is signalled.
2474 The @code{getserv} procedure will take either a service name or number
2475 as its first argument; if given no arguments, it behaves like
2476 @code{getservent} (see below).
2479 (getserv "imap" "tcp")
2480 @result{} #("imap2" ("imap") 143 "tcp")
2482 (getservbyport 88 "udp")
2483 @result{} #("kerberos" ("kerberos5" "krb5") 88 "udp")
2487 The following procedures may be used to step through the service
2488 database from beginning to end.
2490 @deffn {Scheme Procedure} setservent [stayopen]
2491 Initialize an internal stream from which service objects may be read. This
2492 procedure must be called before any calls to @code{getservent}, and may
2493 also be called afterward to reset the service entry stream. If
2494 @var{stayopen} is supplied and is not @code{#f}, the database is not
2495 closed by subsequent @code{getservbyname} or @code{getservbyport} calls,
2496 possibly giving an efficiency gain.
2499 @deffn {Scheme Procedure} getservent
2500 Return the next entry from the services database.
2503 @deffn {Scheme Procedure} endservent
2504 Close the stream used by @code{getservent}. The return value is unspecified.
2507 @deffn {Scheme Procedure} setserv [stayopen]
2508 @deffnx {C Function} scm_setserv (stayopen)
2509 If @var{stayopen} is omitted, this is equivalent to @code{endservent}.
2510 Otherwise it is equivalent to @code{setservent stayopen}.
2514 @node Network Socket Address
2515 @subsubsection Network Socket Address
2516 @cindex socket address
2517 @cindex network socket address
2518 @tpindex Socket address
2520 A @dfn{socket address} object identifies a socket endpoint for
2521 communication. In the case of @code{AF_INET} for instance, the socket
2522 address object comprises the host address (or interface on the host)
2523 and a port number which specifies a particular open socket in a
2524 running client or server process. A socket address object can be
2527 @deffn {Scheme Procedure} make-socket-address AF_INET ipv4addr port
2528 @deffnx {Scheme Procedure} make-socket-address AF_INET6 ipv6addr port [flowinfo [scopeid]]
2529 @deffnx {Scheme Procedure} make-socket-address AF_UNIX path
2530 @deffnx {C Function} scm_make_socket_address family address arglist
2531 Return a new socket address object. The first argument is the address
2532 family, one of the @code{AF} constants, then the arguments vary
2533 according to the family.
2535 For @code{AF_INET} the arguments are an IPv4 network address number
2536 (@pxref{Network Address Conversion}), and a port number.
2538 For @code{AF_INET6} the arguments are an IPv6 network address number
2539 and a port number. Optional @var{flowinfo} and @var{scopeid}
2540 arguments may be given (both integers, default 0).
2542 For @code{AF_UNIX} the argument is a filename (a string).
2544 The C function @code{scm_make_socket_address} takes the @var{family}
2545 and @var{address} arguments directly, then @var{arglist} is a list of
2546 further arguments, being the port for IPv4, port and optional flowinfo
2547 and scopeid for IPv6, or the empty list @code{SCM_EOL} for Unix
2552 The following functions access the fields of a socket address object,
2554 @deffn {Scheme Procedure} sockaddr:fam sa
2555 Return the address family from socket address object @var{sa}. This
2556 is one of the @code{AF} constants (eg. @code{AF_INET}).
2559 @deffn {Scheme Procedure} sockaddr:path sa
2560 For an @code{AF_UNIX} socket address object @var{sa}, return the
2564 @deffn {Scheme Procedure} sockaddr:addr sa
2565 For an @code{AF_INET} or @code{AF_INET6} socket address object
2566 @var{sa}, return the network address number.
2569 @deffn {Scheme Procedure} sockaddr:port sa
2570 For an @code{AF_INET} or @code{AF_INET6} socket address object
2571 @var{sa}, return the port number.
2574 @deffn {Scheme Procedure} sockaddr:flowinfo sa
2575 For an @code{AF_INET6} socket address object @var{sa}, return the
2579 @deffn {Scheme Procedure} sockaddr:scopeid sa
2580 For an @code{AF_INET6} socket address object @var{sa}, return the
2584 @tpindex @code{struct sockaddr}
2585 @tpindex @code{sockaddr}
2586 The functions below convert to and from the C @code{struct sockaddr}
2587 (@pxref{Address Formats,,, libc, The GNU C Library Reference Manual}).
2588 That structure is a generic type, an application can cast to or from
2589 @code{struct sockaddr_in}, @code{struct sockaddr_in6} or @code{struct
2590 sockaddr_un} according to the address family.
2592 In a @code{struct sockaddr} taken or returned, the byte ordering in
2593 the fields follows the C conventions (@pxref{Byte Order,, Byte Order
2594 Conversion, libc, The GNU C Library Reference Manual}). This means
2595 network byte order for @code{AF_INET} host address
2596 (@code{sin_addr.s_addr}) and port number (@code{sin_port}), and
2597 @code{AF_INET6} port number (@code{sin6_port}). But at the Scheme
2598 level these values are taken or returned in host byte order, so the
2599 port is an ordinary integer, and the host address likewise is an
2600 ordinary integer (as described in @ref{Network Address Conversion}).
2602 @deftypefn {C Function} {struct sockaddr *} scm_c_make_socket_address (SCM family, SCM address, SCM args, size_t *outsize)
2603 Return a newly-@code{malloc}ed @code{struct sockaddr} created from
2604 arguments like those taken by @code{scm_make_socket_address} above.
2606 The size (in bytes) of the @code{struct sockaddr} return is stored
2607 into @code{*@var{outsize}}. An application must call @code{free} to
2608 release the returned structure when no longer required.
2611 @deftypefn {C Function} SCM scm_from_sockaddr (const struct sockaddr *address, unsigned address_size)
2612 Return a Scheme socket address object from the C @var{address}
2613 structure. @var{address_size} is the size in bytes of @var{address}.
2616 @deftypefn {C Function} {struct sockaddr *} scm_to_sockaddr (SCM address, size_t *address_size)
2617 Return a newly-@code{malloc}ed @code{struct sockaddr} from a Scheme
2618 level socket address object.
2620 The size (in bytes) of the @code{struct sockaddr} return is stored
2621 into @code{*@var{outsize}}. An application must call @code{free} to
2622 release the returned structure when no longer required.
2626 @node Network Sockets and Communication
2627 @subsubsection Network Sockets and Communication
2629 @cindex network socket
2631 Socket ports can be created using @code{socket} and @code{socketpair}.
2632 The ports are initially unbuffered, to make reading and writing to the
2633 same port more reliable. A buffer can be added to the port using
2634 @code{setvbuf}; see @ref{Ports and File Descriptors}.
2636 Most systems have limits on how many files and sockets can be open, so
2637 it's strongly recommended that socket ports be closed explicitly when
2638 no longer required (@pxref{Ports}).
2640 Some of the underlying C functions take values in network byte order,
2641 but the convention in Guile is that at the Scheme level everything is
2642 ordinary host byte order and conversions are made automatically where
2645 @deffn {Scheme Procedure} socket family style proto
2646 @deffnx {C Function} scm_socket (family, style, proto)
2647 Return a new socket port of the type specified by @var{family},
2648 @var{style} and @var{proto}. All three parameters are integers. The
2649 possible values for @var{family} are as follows, where supported by
2657 The possible values for @var{style} are as follows, again where
2658 supported by the system,
2664 @defvarx SOCK_SEQPACKET
2667 @var{proto} can be obtained from a protocol name using
2668 @code{getprotobyname} (@pxref{Network Databases}). A value of zero
2669 means the default protocol, which is usually right.
2671 A socket cannot by used for communication until it has been connected
2672 somewhere, usually with either @code{connect} or @code{accept} below.
2675 @deffn {Scheme Procedure} socketpair family style proto
2676 @deffnx {C Function} scm_socketpair (family, style, proto)
2677 Return a pair, the @code{car} and @code{cdr} of which are two unnamed
2678 socket ports connected to each other. The connection is full-duplex,
2679 so data can be transferred in either direction between the two.
2681 @var{family}, @var{style} and @var{proto} are as per @code{socket}
2682 above. But many systems only support socket pairs in the
2683 @code{PF_UNIX} family. Zero is likely to be the only meaningful value
2687 @deffn {Scheme Procedure} getsockopt sock level optname
2688 @deffnx {Scheme Procedure} setsockopt sock level optname value
2689 @deffnx {C Function} scm_getsockopt (sock, level, optname)
2690 @deffnx {C Function} scm_setsockopt (sock, level, optname, value)
2691 Get or set an option on socket port @var{sock}. @code{getsockopt}
2692 returns the current value. @code{setsockopt} sets a value and the
2693 return is unspecified.
2695 @var{level} is an integer specifying a protocol layer, either
2696 @code{SOL_SOCKET} for socket level options, or a protocol number from
2697 the @code{IPPROTO} constants or @code{getprotoent} (@pxref{Network
2702 @defvarx IPPROTO_TCP
2703 @defvarx IPPROTO_UDP
2706 @var{optname} is an integer specifying an option within the protocol
2709 For @code{SOL_SOCKET} level the following @var{optname}s are defined
2710 (when provided by the system). For their meaning see
2711 @ref{Socket-Level Options,,, libc, The GNU C Library Reference
2712 Manual}, or @command{man 7 socket}.
2715 @defvarx SO_REUSEADDR
2719 @defvarx SO_DONTROUTE
2720 @defvarx SO_BROADCAST
2723 @defvarx SO_KEEPALIVE
2724 @defvarx SO_OOBINLINE
2725 @defvarx SO_NO_CHECK
2726 @defvarx SO_PRIORITY
2727 The @var{value} taken or returned is an integer.
2731 The @var{value} taken or returned is a pair of integers
2732 @code{(@var{ENABLE} . @var{TIMEOUT})}. On old systems without timeout
2733 support (ie.@: without @code{struct linger}), only @var{ENABLE} has an
2734 effect but the value in Guile is always a pair.
2737 @c Note that we refer only to ``man ip'' here. On GNU/Linux it's
2738 @c ``man 7 ip'' but on NetBSD it's ``man 4 ip''.
2740 For IP level (@code{IPPROTO_IP}) the following @var{optname}s are
2741 defined (when provided by the system). See @command{man ip} for what
2744 @defvar IP_ADD_MEMBERSHIP
2745 @defvarx IP_DROP_MEMBERSHIP
2746 These can be used only with @code{setsockopt}, not @code{getsockopt}.
2747 @var{value} is a pair @code{(@var{MULTIADDR} . @var{INTERFACEADDR})}
2748 of integer IPv4 addresses (@pxref{Network Address Conversion}).
2749 @var{MULTIADDR} is a multicast address to be added to or dropped from
2750 the interface @var{INTERFACEADDR}. @var{INTERFACEADDR} can be
2751 @code{INADDR_ANY} to have the system select the interface.
2752 @var{INTERFACEADDR} can also be an interface index number, on systems
2757 @deffn {Scheme Procedure} shutdown sock how
2758 @deffnx {C Function} scm_shutdown (sock, how)
2759 Sockets can be closed simply by using @code{close-port}. The
2760 @code{shutdown} procedure allows reception or transmission on a
2761 connection to be shut down individually, according to the parameter
2766 Stop receiving data for this socket. If further data arrives, reject it.
2768 Stop trying to transmit data from this socket. Discard any
2769 data waiting to be sent. Stop looking for acknowledgement of
2770 data already sent; don't retransmit it if it is lost.
2772 Stop both reception and transmission.
2775 The return value is unspecified.
2778 @deffn {Scheme Procedure} connect sock sockaddr
2779 @deffnx {Scheme Procedure} connect sock AF_INET ipv4addr port
2780 @deffnx {Scheme Procedure} connect sock AF_INET6 ipv6addr port [flowinfo [scopeid]]
2781 @deffnx {Scheme Procedure} connect sock AF_UNIX path
2782 @deffnx {C Function} scm_connect (sock, fam, address, args)
2783 Initiate a connection on socket port @var{sock} to a given address.
2784 The destination is either a socket address object, or arguments the
2785 same as @code{make-socket-address} would take to make such an object
2786 (@pxref{Network Socket Address}). The return value is unspecified.
2789 (connect sock AF_INET INADDR_LOCALHOST 23)
2790 (connect sock (make-socket-address AF_INET INADDR_LOCALHOST 23))
2794 @deffn {Scheme Procedure} bind sock sockaddr
2795 @deffnx {Scheme Procedure} bind sock AF_INET ipv4addr port
2796 @deffnx {Scheme Procedure} bind sock AF_INET6 ipv6addr port [flowinfo [scopeid]]
2797 @deffnx {Scheme Procedure} bind sock AF_UNIX path
2798 @deffnx {C Function} scm_bind (sock, fam, address, args)
2799 Bind socket port @var{sock} to the given address. The address is
2800 either a socket address object, or arguments the same as
2801 @code{make-socket-address} would take to make such an object
2802 (@pxref{Network Socket Address}). The return value is unspecified.
2804 Generally a socket is only explicitly bound to a particular address
2805 when making a server, ie. to listen on a particular port. For an
2806 outgoing connection the system will assign a local address
2807 automatically, if not already bound.
2810 (bind sock AF_INET INADDR_ANY 12345)
2811 (bind sock (make-socket-object AF_INET INADDR_ANY 12345))
2815 @deffn {Scheme Procedure} listen sock backlog
2816 @deffnx {C Function} scm_listen (sock, backlog)
2817 Enable @var{sock} to accept connection
2818 requests. @var{backlog} is an integer specifying
2819 the maximum length of the queue for pending connections.
2820 If the queue fills, new clients will fail to connect until
2821 the server calls @code{accept} to accept a connection from
2824 The return value is unspecified.
2827 @deffn {Scheme Procedure} accept sock
2828 @deffnx {C Function} scm_accept (sock)
2829 Accept a connection from socket port @var{sock} which has been enabled
2830 for listening with @code{listen} above. If there are no incoming
2831 connections in the queue, wait until one is available (unless
2832 @code{O_NONBLOCK} has been set on the socket, @pxref{Ports and File
2833 Descriptors,@code{fcntl}}).
2835 The return value is a pair. The @code{car} is a new socket port,
2836 connected and ready to communicate. The @code{cdr} is a socket
2837 address object (@pxref{Network Socket Address}) which is where the
2838 remote connection is from (like @code{getpeername} below).
2840 All communication takes place using the new socket returned. The
2841 given @var{sock} remains bound and listening, and @code{accept} may be
2842 called on it again to get another incoming connection when desired.
2845 @deffn {Scheme Procedure} getsockname sock
2846 @deffnx {C Function} scm_getsockname (sock)
2847 Return a socket address object which is the where @var{sock} is bound
2848 locally. @var{sock} may have obtained its local address from
2849 @code{bind} (above), or if a @code{connect} is done with an otherwise
2850 unbound socket (which is usual) then the system will have assigned an
2853 Note that on many systems the address of a socket in the
2854 @code{AF_UNIX} namespace cannot be read.
2857 @deffn {Scheme Procedure} getpeername sock
2858 @deffnx {C Function} scm_getpeername (sock)
2859 Return a socket address object which is where @var{sock} is connected
2860 to, ie. the remote endpoint.
2862 Note that on many systems the address of a socket in the
2863 @code{AF_UNIX} namespace cannot be read.
2866 @deffn {Scheme Procedure} recv! sock buf [flags]
2867 @deffnx {C Function} scm_recv (sock, buf, flags)
2868 Receive data from a socket port.
2869 @var{sock} must already
2870 be bound to the address from which data is to be received.
2871 @var{buf} is a string into which
2872 the data will be written. The size of @var{buf} limits
2874 data which can be received: in the case of packet
2875 protocols, if a packet larger than this limit is encountered
2877 will be irrevocably lost.
2881 @vindex MSG_DONTROUTE
2882 The optional @var{flags} argument is a value or bitwise OR of
2883 @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
2885 The value returned is the number of bytes read from the
2888 Note that the data is read directly from the socket file
2890 any unread buffered port data is ignored.
2893 @deffn {Scheme Procedure} send sock message [flags]
2894 @deffnx {C Function} scm_send (sock, message, flags)
2897 @vindex MSG_DONTROUTE
2898 Transmit the string @var{message} on a socket port @var{sock}.
2899 @var{sock} must already be bound to a destination address. The value
2900 returned is the number of bytes transmitted---it's possible for this
2901 to be less than the length of @var{message} if the socket is set to be
2902 non-blocking. The optional @var{flags} argument is a value or bitwise
2903 OR of @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
2905 Note that the data is written directly to the socket
2907 any unflushed buffered port data is ignored.
2910 @deffn {Scheme Procedure} recvfrom! sock str [flags [start [end]]]
2911 @deffnx {C Function} scm_recvfrom (sock, str, flags, start, end)
2912 Return data from the socket port @var{sock} and also
2913 information about where the data was received from.
2914 @var{sock} must already be bound to the address from which
2915 data is to be received. @code{str}, is a string into which the
2916 data will be written. The size of @var{str} limits the amount
2917 of data which can be received: in the case of packet protocols,
2918 if a packet larger than this limit is encountered then some
2919 data will be irrevocably lost.
2923 @vindex MSG_DONTROUTE
2924 The optional @var{flags} argument is a value or bitwise OR of
2925 @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
2927 The value returned is a pair: the @acronym{CAR} is the number of
2928 bytes read from the socket and the @acronym{CDR} an address object
2929 in the same form as returned by @code{accept}. The address
2930 will given as @code{#f} if not available, as is usually the
2931 case for stream sockets.
2933 The @var{start} and @var{end} arguments specify a substring of
2934 @var{str} to which the data should be written.
2936 Note that the data is read directly from the socket file
2937 descriptor: any unread buffered port data is ignored.
2940 @deffn {Scheme Procedure} sendto sock message sockaddr [flags]
2941 @deffnx {Scheme Procedure} sendto sock message AF_INET ipv4addr port [flags]
2942 @deffnx {Scheme Procedure} sendto sock message AF_INET6 ipv6addr port [flowinfo [scopeid [flags]]]
2943 @deffnx {Scheme Procedure} sendto sock message AF_UNIX path [flags]
2944 @deffnx {C Function} scm_sendto (sock, message, fam, address, args_and_flags)
2945 Transmit the string @var{message} as a datagram on socket port
2946 @var{sock}. The destination is specified either as a socket address
2947 object, or as arguments the same as would be taken by
2948 @code{make-socket-address} to create such an object (@pxref{Network
2951 The destination address may be followed by an optional @var{flags}
2952 argument which is a @code{logior} (@pxref{Bitwise Operations}) of
2953 @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
2955 The value returned is the number of bytes transmitted --
2957 this to be less than the length of @var{message} if the
2959 set to be non-blocking.
2960 Note that the data is written directly to the socket
2962 any unflushed buffered port data is ignored.
2965 The following functions can be used to convert short and long integers
2966 between ``host'' and ``network'' order. Although the procedures above do
2967 this automatically for addresses, the conversion will still need to
2968 be done when sending or receiving encoded integer data from the network.
2970 @deffn {Scheme Procedure} htons value
2971 @deffnx {C Function} scm_htons (value)
2972 Convert a 16 bit quantity from host to network byte ordering.
2973 @var{value} is packed into 2 bytes, which are then converted
2974 and returned as a new integer.
2977 @deffn {Scheme Procedure} ntohs value
2978 @deffnx {C Function} scm_ntohs (value)
2979 Convert a 16 bit quantity from network to host byte ordering.
2980 @var{value} is packed into 2 bytes, which are then converted
2981 and returned as a new integer.
2984 @deffn {Scheme Procedure} htonl value
2985 @deffnx {C Function} scm_htonl (value)
2986 Convert a 32 bit quantity from host to network byte ordering.
2987 @var{value} is packed into 4 bytes, which are then converted
2988 and returned as a new integer.
2991 @deffn {Scheme Procedure} ntohl value
2992 @deffnx {C Function} scm_ntohl (value)
2993 Convert a 32 bit quantity from network to host byte ordering.
2994 @var{value} is packed into 4 bytes, which are then converted
2995 and returned as a new integer.
2998 These procedures are inconvenient to use at present, but consider:
3001 (define write-network-long
3002 (lambda (value port)
3003 (let ((v (make-uniform-vector 1 1 0)))
3004 (uniform-vector-set! v 0 (htonl value))
3005 (uniform-vector-write v port))))
3007 (define read-network-long
3009 (let ((v (make-uniform-vector 1 1 0)))
3010 (uniform-vector-read! v port)
3011 (ntohl (uniform-vector-ref v 0)))))
3015 @node Internet Socket Examples
3016 @subsubsection Network Socket Examples
3017 @cindex network examples
3018 @cindex socket examples
3020 The following give examples of how to use network sockets.
3022 @subsubheading Internet Socket Client Example
3024 @cindex socket client example
3025 The following example demonstrates an Internet socket client.
3026 It connects to the HTTP daemon running on the local machine and
3027 returns the contents of the root index URL.
3030 (let ((s (socket PF_INET SOCK_STREAM 0)))
3031 (connect s AF_INET (inet-aton "127.0.0.1") 80)
3032 (display "GET / HTTP/1.0\r\n\r\n" s)
3034 (do ((line (read-line s) (read-line s)))
3035 ((eof-object? line))
3041 @subsubheading Internet Socket Server Example
3043 @cindex socket server example
3044 The following example shows a simple Internet server which listens on
3045 port 2904 for incoming connections and sends a greeting back to the
3049 (let ((s (socket PF_INET SOCK_STREAM 0)))
3050 (setsockopt s SOL_SOCKET SO_REUSEADDR 1)
3051 ;; @r{Specific address?}
3052 ;; @r{(bind s AF_INET (inet-aton "127.0.0.1") 2904)}
3053 (bind s AF_INET INADDR_ANY 2904)
3056 (simple-format #t "Listening for clients in pid: ~S" (getpid))
3060 (let* ((client-connection (accept s))
3061 (client-details (cdr client-connection))
3062 (client (car client-connection)))
3063 (simple-format #t "Got new client connection: ~S"
3066 (simple-format #t "Client address: ~S"
3068 (sockaddr:addr client-details)))
3070 ;; @r{Send back the greeting to the client port}
3071 (display "Hello client\r\n" client)
3076 @node System Identification
3077 @subsection System Identification
3080 This section lists the various procedures Guile provides for accessing
3081 information about the system it runs on.
3083 @deffn {Scheme Procedure} uname
3084 @deffnx {C Function} scm_uname ()
3085 Return an object with some information about the computer
3086 system the program is running on.
3088 The following procedures accept an object as returned by @code{uname}
3089 and return a selected component (all of which are strings).
3091 @deffn {Scheme Procedure} utsname:sysname un
3092 The name of the operating system.
3094 @deffn {Scheme Procedure} utsname:nodename un
3095 The network name of the computer.
3097 @deffn {Scheme Procedure} utsname:release un
3098 The current release level of the operating system implementation.
3100 @deffn {Scheme Procedure} utsname:version un
3101 The current version level within the release of the operating system.
3103 @deffn {Scheme Procedure} utsname:machine un
3104 A description of the hardware.
3108 @deffn {Scheme Procedure} gethostname
3109 @deffnx {C Function} scm_gethostname ()
3111 Return the host name of the current processor.
3114 @deffn {Scheme Procedure} sethostname name
3115 @deffnx {C Function} scm_sethostname (name)
3116 Set the host name of the current processor to @var{name}. May
3117 only be used by the superuser. The return value is not
3125 @deffn {Scheme Procedure} setlocale category [locale]
3126 @deffnx {C Function} scm_setlocale (category, locale)
3127 Get or set the current locale, used for various internationalizations.
3128 Locales are strings, such as @samp{sv_SE}.
3130 If @var{locale} is given then the locale for the given @var{category} is set
3131 and the new value returned. If @var{locale} is not given then the
3132 current value is returned. @var{category} should be one of the
3138 @defvarx LC_MESSAGES
3139 @defvarx LC_MONETARY
3145 A common usage is @samp{(setlocale LC_ALL "")}, which initializes all
3146 categories based on standard environment variables (@code{LANG} etc).
3147 For full details on categories and locale names @pxref{Locales,,
3148 Locales and Internationalization, libc, The GNU C Library Reference
3153 @subsection Encryption
3156 Please note that the procedures in this section are not suited for
3157 strong encryption, they are only interfaces to the well-known and
3158 common system library functions of the same name. They are just as good
3159 (or bad) as the underlying functions, so you should refer to your system
3160 documentation before using them.
3162 @deffn {Scheme Procedure} crypt key salt
3163 @deffnx {C Function} scm_crypt (key, salt)
3164 Encrypt @var{key} using @var{salt} as the salt value to the
3165 crypt(3) library call.
3168 Although @code{getpass} is not an encryption procedure per se, it
3169 appears here because it is often used in combination with @code{crypt}:
3171 @deffn {Scheme Procedure} getpass prompt
3172 @deffnx {C Function} scm_getpass (prompt)
3174 Display @var{prompt} to the standard error output and read
3175 a password from @file{/dev/tty}. If this file is not
3176 accessible, it reads from standard input. The password may be
3177 up to 127 characters in length. Additional characters and the
3178 terminating newline character are discarded. While reading
3179 the password, echoing and the generation of signals by special
3180 characters is disabled.
3185 @c TeX-master: "guile.texi"