2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007,
4 @c 2008, 2009, 2010, 2011, 2012, 2013 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 fdes
215 @deffnx {C Function} scm_fdes_to_ports (fdes)
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 fdes
234 @deffnx {C Function} scm_primitive_move_to_fdes (port, fdes)
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 port_or_fd
256 @deffnx {C Function} scm_fsync (port_or_fd)
257 Copies any unwritten data for the specified output file descriptor to disk.
258 If @var{port_or_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_port new_port
406 @deffnx {C Function} scm_redirect_port (old_port, new_port)
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.
474 Only certain types of ports are supported, most importantly
478 @deffn {Scheme Procedure} fcntl port/fd cmd [value]
479 @deffnx {C Function} scm_fcntl (object, cmd, value)
480 Apply @var{cmd} on @var{port/fd}, either a port or file descriptor.
481 The @var{value} argument is used by the @code{SET} commands described
482 below, it's an integer value.
484 Values for @var{cmd} are:
487 Duplicate the file descriptor, the same as @code{dup->fdes} above
493 Get or set flags associated with the file descriptor. The only flag
497 ``Close on exec'', meaning the file descriptor will be closed on an
498 @code{exec} call (a successful such call). For example to set that
502 (fcntl port F_SETFD FD_CLOEXEC)
505 Or better, set it but leave any other possible future flags unchanged,
508 (fcntl port F_SETFD (logior FD_CLOEXEC
509 (fcntl port F_GETFD)))
516 Get or set flags associated with the open file. These flags are
517 @code{O_RDONLY} etc described under @code{open} above.
519 A common use is to set @code{O_NONBLOCK} on a network socket. The
520 following sets that flag, and leaves other flags unchanged.
523 (fcntl sock F_SETFL (logior O_NONBLOCK
524 (fcntl sock F_GETFL)))
530 Get or set the process ID of a socket's owner, for @code{SIGIO} signals.
534 @deffn {Scheme Procedure} flock file operation
535 @deffnx {C Function} scm_flock (file, operation)
537 Apply or remove an advisory lock on an open file.
538 @var{operation} specifies the action to be done:
541 Shared lock. More than one process may hold a shared lock
542 for a given file at a given time.
545 Exclusive lock. Only one process may hold an exclusive lock
546 for a given file at a given time.
552 Don't block when locking. This is combined with one of the other
553 operations using @code{logior} (@pxref{Bitwise Operations}). If
554 @code{flock} would block an @code{EWOULDBLOCK} error is thrown
555 (@pxref{Conventions}).
558 The return value is not specified. @var{file} may be an open
559 file descriptor or an open file descriptor port.
561 Note that @code{flock} does not lock files across NFS.
564 @deffn {Scheme Procedure} select reads writes excepts [secs [usecs]]
565 @deffnx {C Function} scm_select (reads, writes, excepts, secs, usecs)
566 This procedure has a variety of uses: waiting for the ability
567 to provide input, accept output, or the existence of
568 exceptional conditions on a collection of ports or file
569 descriptors, or waiting for a timeout to occur.
570 It also returns if interrupted by a signal.
572 @var{reads}, @var{writes} and @var{excepts} can be lists or
573 vectors, with each member a port or a file descriptor.
574 The value returned is a list of three corresponding
575 lists or vectors containing only the members which meet the
576 specified requirement. The ability of port buffers to
577 provide input or accept output is taken into account.
578 Ordering of the input lists or vectors is not preserved.
580 The optional arguments @var{secs} and @var{usecs} specify the
581 timeout. Either @var{secs} can be specified alone, as
582 either an integer or a real number, or both @var{secs} and
583 @var{usecs} can be specified as integers, in which case
584 @var{usecs} is an additional timeout expressed in
585 microseconds. If @var{secs} is omitted or is @code{#f} then
586 select will wait for as long as it takes for one of the other
587 conditions to be satisfied.
589 The scsh version of @code{select} differs as follows:
590 Only vectors are accepted for the first three arguments.
591 The @var{usecs} argument is not supported.
592 Multiple values are returned instead of a list.
593 Duplicates in the input vectors appear only once in output.
594 An additional @code{select!} interface is provided.
598 @subsection File System
601 These procedures allow querying and setting file system attributes
603 permissions, sizes and types of files); deleting, copying, renaming and
604 linking files; creating and removing directories and querying their
605 contents; syncing the file system and creating special files.
607 @deffn {Scheme Procedure} access? path how
608 @deffnx {C Function} scm_access (path, how)
609 Test accessibility of a file under the real UID and GID of the calling
610 process. The return is @code{#t} if @var{path} exists and the
611 permissions requested by @var{how} are all allowed, or @code{#f} if
614 @var{how} is an integer which is one of the following values, or a
615 bitwise-OR (@code{logior}) of multiple values.
618 Test for read permission.
621 Test for write permission.
624 Test for execute permission.
627 Test for existence of the file. This is implied by each of the other
628 tests, so there's no need to combine it with them.
631 It's important to note that @code{access?} does not simply indicate
632 what will happen on attempting to read or write a file. In normal
633 circumstances it does, but in a set-UID or set-GID program it doesn't
634 because @code{access?} tests the real ID, whereas an open or execute
635 attempt uses the effective ID.
637 A program which will never run set-UID/GID can ignore the difference
638 between real and effective IDs, but for maximum generality, especially
639 in library functions, it's best not to use @code{access?} to predict
640 the result of an open or execute, instead simply attempt that and
643 The main use for @code{access?} is to let a set-UID/GID program
644 determine what the invoking user would have been allowed to do,
645 without the greater (or perhaps lesser) privileges afforded by the
646 effective ID. For more on this, see @ref{Testing File Access,,, libc,
647 The GNU C Library Reference Manual}.
651 @deffn {Scheme Procedure} stat object
652 @deffnx {C Function} scm_stat (object)
653 Return an object containing various information about the file
654 determined by @var{object}. @var{object} can be a string containing
655 a file name or a port or integer file descriptor which is open
656 on a file (in which case @code{fstat} is used as the underlying
659 The object returned by @code{stat} can be passed as a single
660 parameter to the following procedures, all of which return
663 @deffn {Scheme Procedure} stat:dev st
664 The device number containing the file.
666 @deffn {Scheme Procedure} stat:ino st
667 The file serial number, which distinguishes this file from all
668 other files on the same device.
670 @deffn {Scheme Procedure} stat:mode st
671 The mode of the file. This is an integer which incorporates file type
672 information and file permission bits. See also @code{stat:type} and
673 @code{stat:perms} below.
675 @deffn {Scheme Procedure} stat:nlink st
676 The number of hard links to the file.
678 @deffn {Scheme Procedure} stat:uid st
679 The user ID of the file's owner.
681 @deffn {Scheme Procedure} stat:gid st
682 The group ID of the file.
684 @deffn {Scheme Procedure} stat:rdev st
685 Device ID; this entry is defined only for character or block special
686 files. On some systems this field is not available at all, in which
687 case @code{stat:rdev} returns @code{#f}.
689 @deffn {Scheme Procedure} stat:size st
690 The size of a regular file in bytes.
692 @deffn {Scheme Procedure} stat:atime st
693 The last access time for the file, in seconds.
695 @deffn {Scheme Procedure} stat:mtime st
696 The last modification time for the file, in seconds.
698 @deffn {Scheme Procedure} stat:ctime st
699 The last modification time for the attributes of the file, in seconds.
701 @deffn {Scheme Procedure} stat:atimensec st
702 @deffnx {Scheme Procedure} stat:mtimensec st
703 @deffnx {Scheme Procedure} stat:ctimensec st
704 The fractional part of a file's access, modification, or attribute modification
705 time, in nanoseconds. Nanosecond timestamps are only available on some operating
706 systems and file systems. If Guile cannot retrieve nanosecond-level timestamps
707 for a file, these fields will be set to 0.
709 @deffn {Scheme Procedure} stat:blksize st
710 The optimal block size for reading or writing the file, in bytes. On
711 some systems this field is not available, in which case
712 @code{stat:blksize} returns a sensible suggested block size.
714 @deffn {Scheme Procedure} stat:blocks st
715 The amount of disk space that the file occupies measured in units of
716 512 byte blocks. On some systems this field is not available, in
717 which case @code{stat:blocks} returns @code{#f}.
720 In addition, the following procedures return the information
721 from @code{stat:mode} in a more convenient form:
723 @deffn {Scheme Procedure} stat:type st
724 A symbol representing the type of file. Possible values are
725 @samp{regular}, @samp{directory}, @samp{symlink},
726 @samp{block-special}, @samp{char-special}, @samp{fifo}, @samp{socket},
729 @deffn {Scheme Procedure} stat:perms st
730 An integer representing the access permission bits.
734 @deffn {Scheme Procedure} lstat path
735 @deffnx {C Function} scm_lstat (path)
736 Similar to @code{stat}, but does not follow symbolic links, i.e.,
737 it will return information about a symbolic link itself, not the
738 file it points to. @var{path} must be a string.
741 @deffn {Scheme Procedure} readlink path
742 @deffnx {C Function} scm_readlink (path)
743 Return the value of the symbolic link named by @var{path} (a
744 string), i.e., the file that the link points to.
749 @deffn {Scheme Procedure} chown object owner group
750 @deffnx {C Function} scm_chown (object, owner, group)
751 Change the ownership and group of the file referred to by @var{object}
752 to the integer values @var{owner} and @var{group}. @var{object} can
753 be a string containing a file name or, if the platform supports
754 @code{fchown} (@pxref{File Owner,,,libc,The GNU C Library Reference
755 Manual}), a port or integer file descriptor which is open on the file.
756 The return value is unspecified.
758 If @var{object} is a symbolic link, either the
759 ownership of the link or the ownership of the referenced file will be
760 changed depending on the operating system (lchown is
761 unsupported at present). If @var{owner} or @var{group} is specified
762 as @code{-1}, then that ID is not changed.
766 @deffn {Scheme Procedure} chmod object mode
767 @deffnx {C Function} scm_chmod (object, mode)
768 Changes the permissions of the file referred to by @var{object}.
769 @var{object} can be a string containing a file name or a port or integer file
770 descriptor which is open on a file (in which case @code{fchmod} is used
771 as the underlying system call).
773 the new permissions as a decimal number, e.g., @code{(chmod "foo" #o755)}.
774 The return value is unspecified.
777 @deffn {Scheme Procedure} utime pathname [actime [modtime [actimens [modtimens [flags]]]]]
778 @deffnx {C Function} scm_utime (pathname, actime, modtime, actimens, modtimens, flags)
779 @code{utime} sets the access and modification times for the
780 file named by @var{pathname}. If @var{actime} or @var{modtime} is
781 not supplied, then the current time is used. @var{actime} and
782 @var{modtime} must be integer time values as returned by the
783 @code{current-time} procedure.
785 The optional @var{actimens} and @var{modtimens} are nanoseconds
786 to add @var{actime} and @var{modtime}. Nanosecond precision is
787 only supported on some combinations of file systems and operating
790 (utime "foo" (- (current-time) 3600))
792 will set the access time to one hour in the past and the
793 modification time to the current time.
797 @deffn {Scheme Procedure} delete-file str
798 @deffnx {C Function} scm_delete_file (str)
799 Deletes (or ``unlinks'') the file whose path is specified by
803 @deffn {Scheme Procedure} copy-file oldfile newfile
804 @deffnx {C Function} scm_copy_file (oldfile, newfile)
805 Copy the file specified by @var{oldfile} to @var{newfile}.
806 The return value is unspecified.
809 @deffn {Scheme Procedure} sendfile out in count [offset]
810 @deffnx {C Function} scm_sendfile (out, in, count, offset)
811 Send @var{count} bytes from @var{in} to @var{out}, both of which
812 must be either open file ports or file descriptors. When
813 @var{offset} is omitted, start reading from @var{in}'s current
814 position; otherwise, start reading at @var{offset}. Return
815 the number of bytes actually sent.
817 When @var{in} is a port, it is often preferable to specify @var{offset},
818 because @var{in}'s offset as a port may be different from the offset of
819 its underlying file descriptor.
821 On systems that support it, such as GNU/Linux, this procedure uses the
822 @code{sendfile} libc function, which usually corresponds to a system
823 call. This is faster than doing a series of @code{read} and
824 @code{write} system calls. A typical application is to send a file over
827 In some cases, the @code{sendfile} libc function may return
828 @code{EINVAL} or @code{ENOSYS}. In that case, Guile's @code{sendfile}
829 procedure automatically falls back to doing a series of @code{read} and
832 In other cases, the libc function may send fewer bytes than
833 @var{count}---for instance because @var{out} is a slow or limited
834 device, such as a pipe. When that happens, Guile's @code{sendfile}
835 automatically retries until exactly @var{count} bytes were sent or an
840 @deffn {Scheme Procedure} rename-file oldname newname
841 @deffnx {C Function} scm_rename (oldname, newname)
842 Renames the file specified by @var{oldname} to @var{newname}.
843 The return value is unspecified.
846 @deffn {Scheme Procedure} link oldpath newpath
847 @deffnx {C Function} scm_link (oldpath, newpath)
848 Creates a new name @var{newpath} in the file system for the
849 file named by @var{oldpath}. If @var{oldpath} is a symbolic
850 link, the link may or may not be followed depending on the
854 @deffn {Scheme Procedure} symlink oldpath newpath
855 @deffnx {C Function} scm_symlink (oldpath, newpath)
856 Create a symbolic link named @var{newpath} with the value (i.e., pointing to)
857 @var{oldpath}. The return value is unspecified.
860 @deffn {Scheme Procedure} mkdir path [mode]
861 @deffnx {C Function} scm_mkdir (path, mode)
862 Create a new directory named by @var{path}. If @var{mode} is omitted
863 then the permissions of the directory file are set using the current
864 umask (@pxref{Processes}). Otherwise they are set to the decimal
865 value specified with @var{mode}. The return value is unspecified.
868 @deffn {Scheme Procedure} rmdir path
869 @deffnx {C Function} scm_rmdir (path)
870 Remove the existing directory named by @var{path}. The directory must
871 be empty for this to succeed. The return value is unspecified.
874 @deffn {Scheme Procedure} opendir dirname
875 @deffnx {C Function} scm_opendir (dirname)
876 @cindex directory contents
877 Open the directory specified by @var{dirname} and return a directory
880 Before using this and the procedures below, make sure to see the
881 higher-level procedures for directory traversal that are available
882 (@pxref{File Tree Walk}).
885 @deffn {Scheme Procedure} directory-stream? object
886 @deffnx {C Function} scm_directory_stream_p (object)
887 Return a boolean indicating whether @var{object} is a directory
888 stream as returned by @code{opendir}.
891 @deffn {Scheme Procedure} readdir stream
892 @deffnx {C Function} scm_readdir (stream)
893 Return (as a string) the next directory entry from the directory stream
894 @var{stream}. If there is no remaining entry to be read then the
895 end of file object is returned.
898 @deffn {Scheme Procedure} rewinddir stream
899 @deffnx {C Function} scm_rewinddir (stream)
900 Reset the directory port @var{stream} so that the next call to
901 @code{readdir} will return the first directory entry.
904 @deffn {Scheme Procedure} closedir stream
905 @deffnx {C Function} scm_closedir (stream)
906 Close the directory stream @var{stream}.
907 The return value is unspecified.
910 Here is an example showing how to display all the entries in a
914 (define dir (opendir "/usr/lib"))
915 (do ((entry (readdir dir) (readdir dir)))
916 ((eof-object? entry))
917 (display entry)(newline))
921 @deffn {Scheme Procedure} sync
922 @deffnx {C Function} scm_sync ()
923 Flush the operating system disk buffers.
924 The return value is unspecified.
927 @deffn {Scheme Procedure} mknod path type perms dev
928 @deffnx {C Function} scm_mknod (path, type, perms, dev)
930 Creates a new special file, such as a file corresponding to a device.
931 @var{path} specifies the name of the file. @var{type} should be one
932 of the following symbols: @samp{regular}, @samp{directory},
933 @samp{symlink}, @samp{block-special}, @samp{char-special},
934 @samp{fifo}, or @samp{socket}. @var{perms} (an integer) specifies the
935 file permissions. @var{dev} (an integer) specifies which device the
936 special file refers to. Its exact interpretation depends on the kind
937 of special file being created.
941 (mknod "/dev/fd0" 'block-special #o660 (+ (* 2 256) 2))
944 The return value is unspecified.
947 @deffn {Scheme Procedure} tmpnam
948 @deffnx {C Function} scm_tmpnam ()
949 @cindex temporary file
950 Return an auto-generated name of a temporary file, a file which
951 doesn't already exist. The name includes a path, it's usually in
952 @file{/tmp} but that's system dependent.
954 Care must be taken when using @code{tmpnam}. In between choosing the
955 name and creating the file another program might use that name, or an
956 attacker might even make it a symlink pointing at something important
957 and causing you to overwrite that.
959 The safe way is to create the file using @code{open} with
960 @code{O_EXCL} to avoid any overwriting. A loop can try again with
961 another name if the file exists (error @code{EEXIST}).
962 @code{mkstemp!} below does that.
965 @deffn {Scheme Procedure} mkstemp! tmpl
966 @deffnx {C Function} scm_mkstemp (tmpl)
967 @cindex temporary file
968 Create a new unique file in the file system and return a new buffered
969 port open for reading and writing to the file.
971 @var{tmpl} is a string specifying where the file should be created: it
972 must end with @samp{XXXXXX} and those @samp{X}s will be changed in the
973 string to return the name of the file. (@code{port-filename} on the
974 port also gives the name.)
976 POSIX doesn't specify the permissions mode of the file, on GNU and
977 most systems it's @code{#o600}. An application can use @code{chmod}
978 to relax that if desired. For example @code{#o666} less @code{umask},
979 which is usual for ordinary file creation,
982 (let ((port (mkstemp! (string-copy "/tmp/myfile-XXXXXX"))))
983 (chmod port (logand #o666 (lognot (umask))))
988 @deffn {Scheme Procedure} tmpfile
989 @deffnx {C Function} scm_tmpfile ()
990 Return an input/output port to a unique temporary file
991 named using the path prefix @code{P_tmpdir} defined in
993 The file is automatically deleted when the port is closed
994 or the program terminates.
997 @deffn {Scheme Procedure} dirname filename
998 @deffnx {C Function} scm_dirname (filename)
999 Return the directory name component of the file name
1000 @var{filename}. If @var{filename} does not contain a directory
1001 component, @code{.} is returned.
1004 @deffn {Scheme Procedure} basename filename [suffix]
1005 @deffnx {C Function} scm_basename (filename, suffix)
1006 Return the base name of the file name @var{filename}. The
1007 base name is the file name without any directory components.
1008 If @var{suffix} is provided, and is equal to the end of
1009 @var{basename}, it is removed also.
1012 (basename "/tmp/test.xml" ".xml")
1017 @deffn {Scheme Procedure} file-exists? filename
1018 Return @code{#t} if the file named @var{filename} exists, @code{#f} if
1022 @cindex file name separator
1023 @cindex absolute file name
1025 Many operating systems, such as GNU, use @code{/} (forward slash) to
1026 separate the components of a file name; any file name starting with
1027 @code{/} is considered an @dfn{absolute file name}. These conventions
1028 are specified by the POSIX Base Definitions, which refer to conforming
1029 file names as ``pathnames''. Some operating systems use a different
1030 convention; in particular, Windows uses @code{\} (backslash) as the file
1031 name separator, and also has the notion of @dfn{volume names} like
1032 @code{C:\} for absolute file names. The following procedures and
1033 variables provide support for portable file name manipulations.
1035 @deffn {Scheme Procedure} system-file-name-convention
1036 Return either @code{posix} or @code{windows}, depending on
1037 what kind of system this Guile is running on.
1040 @deffn {Scheme Procedure} file-name-separator? c
1041 Return true if character @var{c} is a file name separator on the host
1045 @deffn {Scheme Procedure} absolute-file-name? file-name
1046 Return true if @var{file-name} denotes an absolute file name on the host
1050 @defvr {Scheme Variable} file-name-separator-string
1051 The preferred file name separator.
1053 Note that on MinGW builds for Windows, both @code{/} and @code{\} are
1054 valid separators. Thus, programs should not assume that
1055 @code{file-name-separator-string} is the @emph{only} file name
1056 separator---e.g., when extracting the components of a file name.
1060 @node User Information
1061 @subsection User Information
1062 @cindex user information
1063 @cindex password file
1066 The facilities in this section provide an interface to the user and
1068 They should be used with care since they are not reentrant.
1070 The following functions accept an object representing user information
1071 and return a selected component:
1073 @deffn {Scheme Procedure} passwd:name pw
1074 The name of the userid.
1076 @deffn {Scheme Procedure} passwd:passwd pw
1077 The encrypted passwd.
1079 @deffn {Scheme Procedure} passwd:uid pw
1082 @deffn {Scheme Procedure} passwd:gid pw
1083 The group id number.
1085 @deffn {Scheme Procedure} passwd:gecos pw
1088 @deffn {Scheme Procedure} passwd:dir pw
1091 @deffn {Scheme Procedure} passwd:shell pw
1096 @deffn {Scheme Procedure} getpwuid uid
1097 Look up an integer userid in the user database.
1100 @deffn {Scheme Procedure} getpwnam name
1101 Look up a user name string in the user database.
1104 @deffn {Scheme Procedure} setpwent
1105 Initializes a stream used by @code{getpwent} to read from the user database.
1106 The next use of @code{getpwent} will return the first entry. The
1107 return value is unspecified.
1110 @deffn {Scheme Procedure} getpwent
1111 Read the next entry in the user database stream. The return is a
1112 passwd user object as above, or @code{#f} when no more entries.
1115 @deffn {Scheme Procedure} endpwent
1116 Closes the stream used by @code{getpwent}. The return value is unspecified.
1119 @deffn {Scheme Procedure} setpw [arg]
1120 @deffnx {C Function} scm_setpwent (arg)
1121 If called with a true argument, initialize or reset the password data
1122 stream. Otherwise, close the stream. The @code{setpwent} and
1123 @code{endpwent} procedures are implemented on top of this.
1126 @deffn {Scheme Procedure} getpw [user]
1127 @deffnx {C Function} scm_getpwuid (user)
1128 Look up an entry in the user database. @var{user} can be an integer,
1129 a string, or omitted, giving the behaviour of getpwuid, getpwnam
1130 or getpwent respectively.
1133 The following functions accept an object representing group information
1134 and return a selected component:
1136 @deffn {Scheme Procedure} group:name gr
1139 @deffn {Scheme Procedure} group:passwd gr
1140 The encrypted group password.
1142 @deffn {Scheme Procedure} group:gid gr
1143 The group id number.
1145 @deffn {Scheme Procedure} group:mem gr
1146 A list of userids which have this group as a supplementary group.
1150 @deffn {Scheme Procedure} getgrgid gid
1151 Look up an integer group id in the group database.
1154 @deffn {Scheme Procedure} getgrnam name
1155 Look up a group name in the group database.
1158 @deffn {Scheme Procedure} setgrent
1159 Initializes a stream used by @code{getgrent} to read from the group database.
1160 The next use of @code{getgrent} will return the first entry.
1161 The return value is unspecified.
1164 @deffn {Scheme Procedure} getgrent
1165 Return the next entry in the group database, using the stream set by
1169 @deffn {Scheme Procedure} endgrent
1170 Closes the stream used by @code{getgrent}.
1171 The return value is unspecified.
1174 @deffn {Scheme Procedure} setgr [arg]
1175 @deffnx {C Function} scm_setgrent (arg)
1176 If called with a true argument, initialize or reset the group data
1177 stream. Otherwise, close the stream. The @code{setgrent} and
1178 @code{endgrent} procedures are implemented on top of this.
1181 @deffn {Scheme Procedure} getgr [group]
1182 @deffnx {C Function} scm_getgrgid (group)
1183 Look up an entry in the group database. @var{group} can be an integer,
1184 a string, or omitted, giving the behaviour of getgrgid, getgrnam
1185 or getgrent respectively.
1188 In addition to the accessor procedures for the user database, the
1189 following shortcut procedure is also available.
1191 @deffn {Scheme Procedure} getlogin
1192 @deffnx {C Function} scm_getlogin ()
1193 Return a string containing the name of the user logged in on
1194 the controlling terminal of the process, or @code{#f} if this
1195 information cannot be obtained.
1203 @deffn {Scheme Procedure} current-time
1204 @deffnx {C Function} scm_current_time ()
1205 Return the number of seconds since 1970-01-01 00:00:00 @acronym{UTC},
1206 excluding leap seconds.
1209 @deffn {Scheme Procedure} gettimeofday
1210 @deffnx {C Function} scm_gettimeofday ()
1211 Return a pair containing the number of seconds and microseconds
1212 since 1970-01-01 00:00:00 @acronym{UTC}, excluding leap seconds. Note:
1213 whether true microsecond resolution is available depends on the
1217 The following procedures either accept an object representing a broken down
1218 time and return a selected component, or accept an object representing
1219 a broken down time and a value and set the component to the value.
1220 The numbers in parentheses give the usual range.
1222 @deffn {Scheme Procedure} tm:sec tm
1223 @deffnx {Scheme Procedure} set-tm:sec tm val
1226 @deffn {Scheme Procedure} tm:min tm
1227 @deffnx {Scheme Procedure} set-tm:min tm val
1230 @deffn {Scheme Procedure} tm:hour tm
1231 @deffnx {Scheme Procedure} set-tm:hour tm val
1234 @deffn {Scheme Procedure} tm:mday tm
1235 @deffnx {Scheme Procedure} set-tm:mday tm val
1236 Day of the month (1-31).
1238 @deffn {Scheme Procedure} tm:mon tm
1239 @deffnx {Scheme Procedure} set-tm:mon tm val
1242 @deffn {Scheme Procedure} tm:year tm
1243 @deffnx {Scheme Procedure} set-tm:year tm val
1244 Year (70-), the year minus 1900.
1246 @deffn {Scheme Procedure} tm:wday tm
1247 @deffnx {Scheme Procedure} set-tm:wday tm val
1248 Day of the week (0-6) with Sunday represented as 0.
1250 @deffn {Scheme Procedure} tm:yday tm
1251 @deffnx {Scheme Procedure} set-tm:yday tm val
1252 Day of the year (0-364, 365 in leap years).
1254 @deffn {Scheme Procedure} tm:isdst tm
1255 @deffnx {Scheme Procedure} set-tm:isdst tm val
1256 Daylight saving indicator (0 for ``no'', greater than 0 for ``yes'', less than
1259 @deffn {Scheme Procedure} tm:gmtoff tm
1260 @deffnx {Scheme Procedure} set-tm:gmtoff tm val
1261 Time zone offset in seconds west of @acronym{UTC} (-46800 to 43200).
1262 For example on East coast USA (zone @samp{EST+5}) this would be 18000
1263 (ie.@: @m{5\times60\times60,5*60*60}) in winter, or 14400
1264 (ie.@: @m{4\times60\times60,4*60*60}) during daylight savings.
1266 Note @code{tm:gmtoff} is not the same as @code{tm_gmtoff} in the C
1267 @code{tm} structure. @code{tm_gmtoff} is seconds east and hence the
1268 negative of the value here.
1270 @deffn {Scheme Procedure} tm:zone tm
1271 @deffnx {Scheme Procedure} set-tm:zone tm val
1272 Time zone label (a string), not necessarily unique.
1276 @deffn {Scheme Procedure} localtime time [zone]
1277 @deffnx {C Function} scm_localtime (time, zone)
1279 Return an object representing the broken down components of
1280 @var{time}, an integer like the one returned by
1281 @code{current-time}. The time zone for the calculation is
1282 optionally specified by @var{zone} (a string), otherwise the
1283 @env{TZ} environment variable or the system default is used.
1286 @deffn {Scheme Procedure} gmtime time
1287 @deffnx {C Function} scm_gmtime (time)
1288 Return an object representing the broken down components of
1289 @var{time}, an integer like the one returned by
1290 @code{current-time}. The values are calculated for @acronym{UTC}.
1293 @deffn {Scheme Procedure} mktime sbd-time [zone]
1294 @deffnx {C Function} scm_mktime (sbd_time, zone)
1295 For a broken down time object @var{sbd-time}, return a pair the
1296 @code{car} of which is an integer time like @code{current-time}, and
1297 the @code{cdr} of which is a new broken down time with normalized
1300 @var{zone} is a timezone string, or the default is the @env{TZ}
1301 environment variable or the system default (@pxref{TZ Variable,,
1302 Specifying the Time Zone with @env{TZ}, libc, GNU C Library Reference
1303 Manual}). @var{sbd-time} is taken to be in that @var{zone}.
1305 The following fields of @var{sbd-time} are used: @code{tm:year},
1306 @code{tm:mon}, @code{tm:mday}, @code{tm:hour}, @code{tm:min},
1307 @code{tm:sec}, @code{tm:isdst}. The values can be outside their usual
1308 ranges. For example @code{tm:hour} normally goes up to 23, but a
1309 value say 33 would mean 9 the following day.
1311 @code{tm:isdst} in @var{sbd-time} says whether the time given is with
1312 daylight savings or not. This is ignored if @var{zone} doesn't have
1313 any daylight savings adjustment amount.
1315 The broken down time in the return normalizes the values of
1316 @var{sbd-time} by bringing them into their usual ranges, and using the
1317 actual daylight savings rule for that time in @var{zone} (which may
1318 differ from what @var{sbd-time} had). The easiest way to think of
1319 this is that @var{sbd-time} plus @var{zone} converts to the integer
1320 UTC time, then a @code{localtime} is applied to get the normal
1321 presentation of that time, in @var{zone}.
1324 @deffn {Scheme Procedure} tzset
1325 @deffnx {C Function} scm_tzset ()
1326 Initialize the timezone from the @env{TZ} environment variable
1327 or the system default. It's not usually necessary to call this procedure
1328 since it's done automatically by other procedures that depend on the
1332 @deffn {Scheme Procedure} strftime format tm
1333 @deffnx {C Function} scm_strftime (format, tm)
1334 @cindex time formatting
1335 Return a string which is broken-down time structure @var{tm} formatted
1336 according to the given @var{format} string.
1338 @var{format} contains field specifications introduced by a @samp{%}
1339 character. See @ref{Formatting Calendar Time,,, libc, The GNU C
1340 Library Reference Manual}, or @samp{man 3 strftime}, for the available
1344 (strftime "%c" (localtime (current-time)))
1345 @result{} "Mon Mar 11 20:17:43 2002"
1348 If @code{setlocale} has been called (@pxref{Locales}), month and day
1349 names are from the current locale and in the locale character set.
1352 @deffn {Scheme Procedure} strptime format string
1353 @deffnx {C Function} scm_strptime (format, string)
1354 @cindex time parsing
1355 Performs the reverse action to @code{strftime}, parsing
1356 @var{string} according to the specification supplied in
1357 @var{format}. The interpretation of month and day names is
1358 dependent on the current locale. The value returned is a pair.
1359 The @acronym{CAR} has an object with time components
1360 in the form returned by @code{localtime} or @code{gmtime},
1361 but the time zone components
1362 are not usefully set.
1363 The @acronym{CDR} reports the number of characters from @var{string}
1364 which were used for the conversion.
1367 @defvar internal-time-units-per-second
1368 The value of this variable is the number of time units per second
1369 reported by the following procedures.
1372 @deffn {Scheme Procedure} times
1373 @deffnx {C Function} scm_times ()
1374 Return an object with information about real and processor
1375 time. The following procedures accept such an object as an
1376 argument and return a selected component:
1378 @deffn {Scheme Procedure} tms:clock tms
1379 The current real time, expressed as time units relative to an
1382 @deffn {Scheme Procedure} tms:utime tms
1383 The CPU time units used by the calling process.
1385 @deffn {Scheme Procedure} tms:stime tms
1386 The CPU time units used by the system on behalf of the calling
1389 @deffn {Scheme Procedure} tms:cutime tms
1390 The CPU time units used by terminated child processes of the
1391 calling process, whose status has been collected (e.g., using
1394 @deffn {Scheme Procedure} tms:cstime tms
1395 Similarly, the CPU times units used by the system on behalf of
1396 terminated child processes.
1400 @deffn {Scheme Procedure} get-internal-real-time
1401 @deffnx {C Function} scm_get_internal_real_time ()
1402 Return the number of time units since the interpreter was
1406 @deffn {Scheme Procedure} get-internal-run-time
1407 @deffnx {C Function} scm_get_internal_run_time ()
1408 Return the number of time units of processor time used by the
1409 interpreter. Both @emph{system} and @emph{user} time are
1410 included but subprocesses are not.
1413 @node Runtime Environment
1414 @subsection Runtime Environment
1416 @deffn {Scheme Procedure} program-arguments
1417 @deffnx {Scheme Procedure} command-line
1418 @deffnx {Scheme Procedure} set-program-arguments
1419 @deffnx {C Function} scm_program_arguments ()
1420 @deffnx {C Function} scm_set_program_arguments_scm (lst)
1421 @cindex command line
1422 @cindex program arguments
1423 Get the command line arguments passed to Guile, or set new arguments.
1425 The arguments are a list of strings, the first of which is the invoked
1426 program name. This is just @nicode{"guile"} (or the executable path)
1427 when run interactively, or it's the script name when running a script
1428 with @option{-s} (@pxref{Invoking Guile}).
1431 guile -L /my/extra/dir -s foo.scm abc def
1433 (program-arguments) @result{} ("foo.scm" "abc" "def")
1436 @code{set-program-arguments} allows a library module or similar to
1437 modify the arguments, for example to strip options it recognises,
1438 leaving the rest for the mainline.
1440 The argument list is held in a fluid, which means it's separate for
1441 each thread. Neither the list nor the strings within it are copied at
1442 any point and normally should not be mutated.
1444 The two names @code{program-arguments} and @code{command-line} are an
1445 historical accident, they both do exactly the same thing. The name
1446 @code{scm_set_program_arguments_scm} has an extra @code{_scm} on the
1447 end to avoid clashing with the C function below.
1450 @deftypefn {C Function} void scm_set_program_arguments (int argc, char **argv, char *first)
1451 @cindex command line
1452 @cindex program arguments
1453 Set the list of command line arguments for @code{program-arguments}
1454 and @code{command-line} above.
1456 @var{argv} is an array of null-terminated strings, as in a C
1457 @code{main} function. @var{argc} is the number of strings in
1458 @var{argv}, or if it's negative then a @code{NULL} in @var{argv} marks
1461 @var{first} is an extra string put at the start of the arguments, or
1462 @code{NULL} for no such extra. This is a convenient way to pass the
1463 program name after advancing @var{argv} to strip option arguments.
1468 char *progname = argv[0];
1469 for (argv++; argv[0] != NULL && argv[0][0] == '-'; argv++)
1471 /* munch option ... */
1473 /* remaining args for scheme level use */
1474 scm_set_program_arguments (-1, argv, progname);
1478 This sort of thing is often done at startup under
1479 @code{scm_boot_guile} with options handled at the C level removed.
1480 The given strings are all copied, so the C data is not accessed again
1481 once @code{scm_set_program_arguments} returns.
1484 @deffn {Scheme Procedure} getenv name
1485 @deffnx {C Function} scm_getenv (name)
1487 Looks up the string @var{name} in the current environment. The return
1488 value is @code{#f} unless a string of the form @code{NAME=VALUE} is
1489 found, in which case the string @code{VALUE} is returned.
1492 @deffn {Scheme Procedure} setenv name value
1493 Modifies the environment of the current process, which is
1494 also the default environment inherited by child processes.
1496 If @var{value} is @code{#f}, then @var{name} is removed from the
1497 environment. Otherwise, the string @var{name}=@var{value} is added
1498 to the environment, replacing any existing string with name matching
1501 The return value is unspecified.
1504 @deffn {Scheme Procedure} unsetenv name
1505 Remove variable @var{name} from the environment. The
1506 name can not contain a @samp{=} character.
1509 @deffn {Scheme Procedure} environ [env]
1510 @deffnx {C Function} scm_environ (env)
1511 If @var{env} is omitted, return the current environment (in the
1512 Unix sense) as a list of strings. Otherwise set the current
1513 environment, which is also the default environment for child
1514 processes, to the supplied list of strings. Each member of
1515 @var{env} should be of the form @var{name}=@var{value} and values of
1516 @var{name} should not be duplicated. If @var{env} is supplied
1517 then the return value is unspecified.
1520 @deffn {Scheme Procedure} putenv str
1521 @deffnx {C Function} scm_putenv (str)
1522 Modifies the environment of the current process, which is
1523 also the default environment inherited by child processes.
1525 If @var{str} is of the form @code{NAME=VALUE} then it will be written
1526 directly into the environment, replacing any existing environment string
1528 name matching @code{NAME}. If @var{str} does not contain an equal
1529 sign, then any existing string with name matching @var{str} will
1532 The return value is unspecified.
1537 @subsection Processes
1539 @cindex child processes
1542 @deffn {Scheme Procedure} chdir str
1543 @deffnx {C Function} scm_chdir (str)
1544 @cindex current directory
1545 Change the current working directory to @var{str}.
1546 The return value is unspecified.
1550 @deffn {Scheme Procedure} getcwd
1551 @deffnx {C Function} scm_getcwd ()
1552 Return the name of the current working directory.
1555 @deffn {Scheme Procedure} umask [mode]
1556 @deffnx {C Function} scm_umask (mode)
1557 If @var{mode} is omitted, returns a decimal number representing the
1558 current file creation mask. Otherwise the file creation mask is set
1559 to @var{mode} and the previous value is returned. @xref{Setting
1560 Permissions,,Assigning File Permissions,libc,The GNU C Library
1561 Reference Manual}, for more on how to use umasks.
1563 E.g., @code{(umask #o022)} sets the mask to octal 22/decimal 18.
1566 @deffn {Scheme Procedure} chroot path
1567 @deffnx {C Function} scm_chroot (path)
1568 Change the root directory to that specified in @var{path}.
1569 This directory will be used for path names beginning with
1570 @file{/}. The root directory is inherited by all children
1571 of the current process. Only the superuser may change the
1575 @deffn {Scheme Procedure} getpid
1576 @deffnx {C Function} scm_getpid ()
1577 Return an integer representing the current process ID.
1580 @deffn {Scheme Procedure} getgroups
1581 @deffnx {C Function} scm_getgroups ()
1582 Return a vector of integers representing the current
1583 supplementary group IDs.
1586 @deffn {Scheme Procedure} getppid
1587 @deffnx {C Function} scm_getppid ()
1588 Return an integer representing the process ID of the parent
1592 @deffn {Scheme Procedure} getuid
1593 @deffnx {C Function} scm_getuid ()
1594 Return an integer representing the current real user ID.
1597 @deffn {Scheme Procedure} getgid
1598 @deffnx {C Function} scm_getgid ()
1599 Return an integer representing the current real group ID.
1602 @deffn {Scheme Procedure} geteuid
1603 @deffnx {C Function} scm_geteuid ()
1604 Return an integer representing the current effective user ID.
1605 If the system does not support effective IDs, then the real ID
1606 is returned. @code{(provided? 'EIDs)} reports whether the
1607 system supports effective IDs.
1610 @deffn {Scheme Procedure} getegid
1611 @deffnx {C Function} scm_getegid ()
1612 Return an integer representing the current effective group ID.
1613 If the system does not support effective IDs, then the real ID
1614 is returned. @code{(provided? 'EIDs)} reports whether the
1615 system supports effective IDs.
1618 @deffn {Scheme Procedure} setgroups vec
1619 @deffnx {C Function} scm_setgroups (vec)
1620 Set the current set of supplementary group IDs to the integers in the
1621 given vector @var{vec}. The return value is unspecified.
1623 Generally only the superuser can set the process group IDs
1624 (@pxref{Setting Groups, Setting the Group IDs,, libc, The GNU C
1625 Library Reference Manual}).
1628 @deffn {Scheme Procedure} setuid id
1629 @deffnx {C Function} scm_setuid (id)
1630 Sets both the real and effective user IDs to the integer @var{id}, provided
1631 the process has appropriate privileges.
1632 The return value is unspecified.
1635 @deffn {Scheme Procedure} setgid id
1636 @deffnx {C Function} scm_setgid (id)
1637 Sets both the real and effective group IDs to the integer @var{id}, provided
1638 the process has appropriate privileges.
1639 The return value is unspecified.
1642 @deffn {Scheme Procedure} seteuid id
1643 @deffnx {C Function} scm_seteuid (id)
1644 Sets the effective user ID to the integer @var{id}, provided the process
1645 has appropriate privileges. If effective IDs are not supported, the
1646 real ID is set instead---@code{(provided? 'EIDs)} reports whether the
1647 system supports effective IDs.
1648 The return value is unspecified.
1651 @deffn {Scheme Procedure} setegid id
1652 @deffnx {C Function} scm_setegid (id)
1653 Sets the effective group ID to the integer @var{id}, provided the process
1654 has appropriate privileges. If effective IDs are not supported, the
1655 real ID is set instead---@code{(provided? 'EIDs)} reports whether the
1656 system supports effective IDs.
1657 The return value is unspecified.
1660 @deffn {Scheme Procedure} getpgrp
1661 @deffnx {C Function} scm_getpgrp ()
1662 Return an integer representing the current process group ID.
1663 This is the @acronym{POSIX} definition, not @acronym{BSD}.
1666 @deffn {Scheme Procedure} setpgid pid pgid
1667 @deffnx {C Function} scm_setpgid (pid, pgid)
1668 Move the process @var{pid} into the process group @var{pgid}. @var{pid} or
1669 @var{pgid} must be integers: they can be zero to indicate the ID of the
1671 Fails on systems that do not support job control.
1672 The return value is unspecified.
1675 @deffn {Scheme Procedure} setsid
1676 @deffnx {C Function} scm_setsid ()
1677 Creates a new session. The current process becomes the session leader
1678 and is put in a new process group. The process will be detached
1679 from its controlling terminal if it has one.
1680 The return value is an integer representing the new process group ID.
1683 @deffn {Scheme Procedure} getsid pid
1684 @deffnx {C Function} scm_getsid (pid)
1685 Returns the session ID of process @var{pid}. (The session
1686 ID of a process is the process group ID of its session leader.)
1689 @deffn {Scheme Procedure} waitpid pid [options]
1690 @deffnx {C Function} scm_waitpid (pid, options)
1691 This procedure collects status information from a child process which
1692 has terminated or (optionally) stopped. Normally it will
1693 suspend the calling process until this can be done. If more than one
1694 child process is eligible then one will be chosen by the operating system.
1696 The value of @var{pid} determines the behaviour:
1699 @item @var{pid} greater than 0
1700 Request status information from the specified child process.
1701 @item @var{pid} equal to -1 or @code{WAIT_ANY}
1703 Request status information for any child process.
1704 @item @var{pid} equal to 0 or @code{WAIT_MYPGRP}
1706 Request status information for any child process in the current process
1708 @item @var{pid} less than -1
1709 Request status information for any child process whose process group ID
1710 is @minus{}@var{pid}.
1713 The @var{options} argument, if supplied, should be the bitwise OR of the
1714 values of zero or more of the following variables:
1717 Return immediately even if there are no child processes to be collected.
1721 Report status information for stopped processes as well as terminated
1725 The return value is a pair containing:
1729 The process ID of the child process, or 0 if @code{WNOHANG} was
1730 specified and no process was collected.
1732 The integer status value.
1737 functions can be used to decode the process status code returned
1740 @deffn {Scheme Procedure} status:exit-val status
1741 @deffnx {C Function} scm_status_exit_val (status)
1742 Return the exit status value, as would be set if a process
1743 ended normally through a call to @code{exit} or @code{_exit},
1744 if any, otherwise @code{#f}.
1747 @deffn {Scheme Procedure} status:term-sig status
1748 @deffnx {C Function} scm_status_term_sig (status)
1749 Return the signal number which terminated the process, if any,
1750 otherwise @code{#f}.
1753 @deffn {Scheme Procedure} status:stop-sig status
1754 @deffnx {C Function} scm_status_stop_sig (status)
1755 Return the signal number which stopped the process, if any,
1756 otherwise @code{#f}.
1759 @deffn {Scheme Procedure} system [cmd]
1760 @deffnx {C Function} scm_system (cmd)
1761 Execute @var{cmd} using the operating system's ``command
1762 processor''. Under Unix this is usually the default shell
1763 @code{sh}. The value returned is @var{cmd}'s exit status as
1764 returned by @code{waitpid}, which can be interpreted using the
1767 If @code{system} is called without arguments, return a boolean
1768 indicating whether the command processor is available.
1771 @deffn {Scheme Procedure} system* arg1 arg2 @dots{}
1772 @deffnx {C Function} scm_system_star (args)
1773 Execute the command indicated by @var{arg1} @var{arg2} @enddots{}. The
1774 first element must be a string indicating the command to be executed,
1775 and the remaining items must be strings representing each of the
1776 arguments to that command.
1778 This function returns the exit status of the command as provided by
1779 @code{waitpid}. This value can be handled with @code{status:exit-val}
1780 and the related functions.
1782 @code{system*} is similar to @code{system}, but accepts only one
1783 string per-argument, and performs no shell interpretation. The
1784 command is executed using fork and execlp. Accordingly this function
1785 may be safer than @code{system} in situations where shell
1786 interpretation is not required.
1788 Example: (system* "echo" "foo" "bar")
1791 @deffn {Scheme Procedure} quit [status]
1792 @deffnx {Scheme Procedure} exit [status]
1793 Terminate the current process with proper unwinding of the Scheme stack.
1794 The exit status zero if @var{status} is not supplied. If @var{status}
1795 is supplied, and it is an integer, that integer is used as the exit
1796 status. If @var{status} is @code{#t} or @code{#f}, the exit status is 0
1799 The procedure @code{exit} is an alias of @code{quit}. They have the
1803 @deffn {Scheme Procedure} primitive-exit [status]
1804 @deffnx {Scheme Procedure} primitive-_exit [status]
1805 @deffnx {C Function} scm_primitive_exit (status)
1806 @deffnx {C Function} scm_primitive__exit (status)
1807 Terminate the current process without unwinding the Scheme stack. The
1808 exit status is @var{status} if supplied, otherwise zero.
1810 @code{primitive-exit} uses the C @code{exit} function and hence runs
1811 usual C level cleanups (flush output streams, call @code{atexit}
1812 functions, etc, see @ref{Normal Termination,,, libc, The GNU C Library
1813 Reference Manual})).
1815 @code{primitive-_exit} is the @code{_exit} system call
1816 (@pxref{Termination Internals,,, libc, The GNU C Library Reference
1817 Manual}). This terminates the program immediately, with neither
1818 Scheme-level nor C-level cleanups.
1820 The typical use for @code{primitive-_exit} is from a child process
1821 created with @code{primitive-fork}. For example in a Gdk program the
1822 child process inherits the X server connection and a C-level
1823 @code{atexit} cleanup which will close that connection. But closing
1824 in the child would upset the protocol in the parent, so
1825 @code{primitive-_exit} should be used to exit without that.
1828 @deffn {Scheme Procedure} execl filename arg @dots{}
1829 @deffnx {C Function} scm_execl (filename, args)
1830 Executes the file named by @var{filename} as a new process image.
1831 The remaining arguments are supplied to the process; from a C program
1832 they are accessible as the @code{argv} argument to @code{main}.
1833 Conventionally the first @var{arg} is the same as @var{filename}.
1834 All arguments must be strings.
1836 If @var{arg} is missing, @var{filename} is executed with a null
1837 argument list, which may have system-dependent side-effects.
1839 This procedure is currently implemented using the @code{execv} system
1840 call, but we call it @code{execl} because of its Scheme calling interface.
1843 @deffn {Scheme Procedure} execlp filename arg @dots{}
1844 @deffnx {C Function} scm_execlp (filename, args)
1845 Similar to @code{execl}, however if
1846 @var{filename} does not contain a slash
1847 then the file to execute will be located by searching the
1848 directories listed in the @code{PATH} environment variable.
1850 This procedure is currently implemented using the @code{execvp} system
1851 call, but we call it @code{execlp} because of its Scheme calling interface.
1854 @deffn {Scheme Procedure} execle filename env arg @dots{}
1855 @deffnx {C Function} scm_execle (filename, env, args)
1856 Similar to @code{execl}, but the environment of the new process is
1857 specified by @var{env}, which must be a list of strings as returned by the
1858 @code{environ} procedure.
1860 This procedure is currently implemented using the @code{execve} system
1861 call, but we call it @code{execle} because of its Scheme calling interface.
1864 @deffn {Scheme Procedure} primitive-fork
1865 @deffnx {C Function} scm_fork ()
1866 Creates a new ``child'' process by duplicating the current ``parent'' process.
1867 In the child the return value is 0. In the parent the return value is
1868 the integer process ID of the child.
1870 Note that it is unsafe to fork a process that has multiple threads
1871 running, as only the thread that calls @code{primitive-fork} will
1872 persist in the child. Any resources that other threads held, such as
1873 locked mutexes or open file descriptors, are lost. Indeed,
1874 @acronym{POSIX} specifies that only async-signal-safe procedures are
1875 safe to call after a multithreaded fork, which is a very limited set.
1876 Guile issues a warning if it detects a fork from a multi-threaded
1879 If you are going to @code{exec} soon after forking, the procedures in
1880 @code{(ice-9 popen)} may be useful to you, as they fork and exec within
1881 an async-signal-safe function carefully written to ensure robust program
1882 behavior, even in the presence of threads. @xref{Pipes}, for more.
1884 This procedure has been renamed from @code{fork} to avoid a naming conflict
1888 @deffn {Scheme Procedure} nice incr
1889 @deffnx {C Function} scm_nice (incr)
1890 @cindex process priority
1891 Increment the priority of the current process by @var{incr}. A higher
1892 priority value means that the process runs less often.
1893 The return value is unspecified.
1896 @deffn {Scheme Procedure} setpriority which who prio
1897 @deffnx {C Function} scm_setpriority (which, who, prio)
1898 @vindex PRIO_PROCESS
1901 Set the scheduling priority of the process, process group
1902 or user, as indicated by @var{which} and @var{who}. @var{which}
1903 is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
1904 or @code{PRIO_USER}, and @var{who} is interpreted relative to
1905 @var{which} (a process identifier for @code{PRIO_PROCESS},
1906 process group identifier for @code{PRIO_PGRP}, and a user
1907 identifier for @code{PRIO_USER}. A zero value of @var{who}
1908 denotes the current process, process group, or user.
1909 @var{prio} is a value in the range [@minus{}20,20]. The default
1910 priority is 0; lower priorities (in numerical terms) cause more
1911 favorable scheduling. Sets the priority of all of the specified
1912 processes. Only the super-user may lower priorities. The return
1913 value is not specified.
1916 @deffn {Scheme Procedure} getpriority which who
1917 @deffnx {C Function} scm_getpriority (which, who)
1918 @vindex PRIO_PROCESS
1921 Return the scheduling priority of the process, process group
1922 or user, as indicated by @var{which} and @var{who}. @var{which}
1923 is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
1924 or @code{PRIO_USER}, and @var{who} should be interpreted depending on
1925 @var{which} (a process identifier for @code{PRIO_PROCESS},
1926 process group identifier for @code{PRIO_PGRP}, and a user
1927 identifier for @code{PRIO_USER}). A zero value of @var{who}
1928 denotes the current process, process group, or user. Return
1929 the highest priority (lowest numerical value) of any of the
1930 specified processes.
1933 @cindex affinity, CPU
1935 @deffn {Scheme Procedure} getaffinity pid
1936 @deffnx {C Function} scm_getaffinity (pid)
1937 Return a bitvector representing the CPU affinity mask for
1938 process @var{pid}. Each CPU the process has affinity with
1939 has its corresponding bit set in the returned bitvector.
1940 The number of bits set is a good estimate of how many CPUs
1941 Guile can use without stepping on other processes' toes.
1943 Currently this procedure is only defined on GNU variants
1944 (@pxref{CPU Affinity, @code{sched_getaffinity},, libc, The
1945 GNU C Library Reference Manual}).
1948 @deffn {Scheme Procedure} setaffinity pid mask
1949 @deffnx {C Function} scm_setaffinity (pid, mask)
1950 Install the CPU affinity mask @var{mask}, a bitvector, for
1951 the process or thread with ID @var{pid}. The return value
1954 Currently this procedure is only defined on GNU variants
1955 (@pxref{CPU Affinity, @code{sched_setaffinity},, libc, The
1956 GNU C Library Reference Manual}).
1959 @deffn {Scheme Procedure} total-processor-count
1960 @deffnx {C Function} scm_total_processor_count ()
1961 Return the total number of processors of the machine, which
1962 is guaranteed to be at least 1. A ``processor'' here is a
1963 thread execution unit, which can be either:
1966 @item an execution core in a (possibly multi-core) chip, in a
1967 (possibly multi- chip) module, in a single computer, or
1968 @item a thread execution unit inside a core in the case of
1969 @dfn{hyper-threaded} CPUs.
1972 Which of the two definitions is used, is unspecified.
1975 @deffn {Scheme Procedure} current-processor-count
1976 @deffnx {C Function} scm_current_processor_count ()
1977 Like @code{total-processor-count}, but return the number of
1978 processors available to the current process. See
1979 @code{setaffinity} and @code{getaffinity} for more
1988 The following procedures raise, handle and wait for signals.
1990 Scheme code signal handlers are run via a system async (@pxref{System
1991 asyncs}), so they're called in the handler's thread at the next safe
1992 opportunity. Generally this is after any currently executing
1993 primitive procedure finishes (which could be a long time for
1994 primitives that wait for an external event).
1996 @deffn {Scheme Procedure} kill pid sig
1997 @deffnx {C Function} scm_kill (pid, sig)
1998 Sends a signal to the specified process or group of processes.
2000 @var{pid} specifies the processes to which the signal is sent:
2003 @item @var{pid} greater than 0
2004 The process whose identifier is @var{pid}.
2005 @item @var{pid} equal to 0
2006 All processes in the current process group.
2007 @item @var{pid} less than -1
2008 The process group whose identifier is -@var{pid}
2009 @item @var{pid} equal to -1
2010 If the process is privileged, all processes except for some special
2011 system processes. Otherwise, all processes with the current effective
2015 @var{sig} should be specified using a variable corresponding to
2016 the Unix symbolic name, e.g.,
2026 A full list of signals on the GNU system may be found in @ref{Standard
2027 Signals,,,libc,The GNU C Library Reference Manual}.
2030 @deffn {Scheme Procedure} raise sig
2031 @deffnx {C Function} scm_raise (sig)
2032 Sends a specified signal @var{sig} to the current process, where
2033 @var{sig} is as described for the @code{kill} procedure.
2036 @deffn {Scheme Procedure} sigaction signum [handler [flags [thread]]]
2037 @deffnx {C Function} scm_sigaction (signum, handler, flags)
2038 @deffnx {C Function} scm_sigaction_for_thread (signum, handler, flags, thread)
2039 Install or report the signal handler for a specified signal.
2041 @var{signum} is the signal number, which can be specified using the value
2042 of variables such as @code{SIGINT}.
2044 If @var{handler} is omitted, @code{sigaction} returns a pair: the
2045 @acronym{CAR} is the current signal hander, which will be either an
2046 integer with the value @code{SIG_DFL} (default action) or
2047 @code{SIG_IGN} (ignore), or the Scheme procedure which handles the
2048 signal, or @code{#f} if a non-Scheme procedure handles the signal.
2049 The @acronym{CDR} contains the current @code{sigaction} flags for the
2052 If @var{handler} is provided, it is installed as the new handler for
2053 @var{signum}. @var{handler} can be a Scheme procedure taking one
2054 argument, or the value of @code{SIG_DFL} (default action) or
2055 @code{SIG_IGN} (ignore), or @code{#f} to restore whatever signal handler
2056 was installed before @code{sigaction} was first used. When a scheme
2057 procedure has been specified, that procedure will run in the given
2058 @var{thread}. When no thread has been given, the thread that made this
2059 call to @code{sigaction} is used.
2061 @var{flags} is a @code{logior} (@pxref{Bitwise Operations}) of the
2062 following (where provided by the system), or @code{0} for none.
2064 @defvar SA_NOCLDSTOP
2065 By default, @code{SIGCHLD} is signalled when a child process stops
2066 (ie.@: receives @code{SIGSTOP}), and when a child process terminates.
2067 With the @code{SA_NOCLDSTOP} flag, @code{SIGCHLD} is only signalled
2068 for termination, not stopping.
2070 @code{SA_NOCLDSTOP} has no effect on signals other than
2075 If a signal occurs while in a system call, deliver the signal then
2076 restart the system call (as opposed to returning an @code{EINTR} error
2080 The return value is a pair with information about the old handler as
2083 This interface does not provide access to the ``signal blocking''
2084 facility. Maybe this is not needed, since the thread support may
2085 provide solutions to the problem of consistent access to data
2089 @deffn {Scheme Procedure} restore-signals
2090 @deffnx {C Function} scm_restore_signals ()
2091 Return all signal handlers to the values they had before any call to
2092 @code{sigaction} was made. The return value is unspecified.
2095 @deffn {Scheme Procedure} alarm i
2096 @deffnx {C Function} scm_alarm (i)
2097 Set a timer to raise a @code{SIGALRM} signal after the specified
2098 number of seconds (an integer). It's advisable to install a signal
2100 @code{SIGALRM} beforehand, since the default action is to terminate
2103 The return value indicates the time remaining for the previous alarm,
2104 if any. The new value replaces the previous alarm. If there was
2105 no previous alarm, the return value is zero.
2108 @deffn {Scheme Procedure} pause
2109 @deffnx {C Function} scm_pause ()
2110 Pause the current process (thread?) until a signal arrives whose
2111 action is to either terminate the current process or invoke a
2112 handler procedure. The return value is unspecified.
2115 @deffn {Scheme Procedure} sleep secs
2116 @deffnx {Scheme Procedure} usleep usecs
2117 @deffnx {C Function} scm_sleep (secs)
2118 @deffnx {C Function} scm_usleep (usecs)
2119 Wait the given period @var{secs} seconds or @var{usecs} microseconds
2120 (both integers). If a signal arrives the wait stops and the return
2121 value is the time remaining, in seconds or microseconds respectively.
2122 If the period elapses with no signal the return is zero.
2124 On most systems the process scheduler is not microsecond accurate and
2125 the actual period slept by @code{usleep} might be rounded to a system
2126 clock tick boundary, which might be 10 milliseconds for instance.
2128 See @code{scm_std_sleep} and @code{scm_std_usleep} for equivalents at
2129 the C level (@pxref{Blocking}).
2132 @deffn {Scheme Procedure} getitimer which_timer
2133 @deffnx {Scheme Procedure} setitimer which_timer interval_seconds interval_microseconds periodic_seconds periodic_microseconds
2134 @deffnx {C Function} scm_getitimer (which_timer)
2135 @deffnx {C Function} scm_setitimer (which_timer, interval_seconds, interval_microseconds, periodic_seconds, periodic_microseconds)
2136 Get or set the periods programmed in certain system timers. These
2137 timers have a current interval value which counts down and on reaching
2138 zero raises a signal. An optional periodic value can be set to
2139 restart from there each time, for periodic operation.
2140 @var{which_timer} is one of the following values
2143 A real-time timer, counting down elapsed real time. At zero it raises
2144 @code{SIGALRM}. This is like @code{alarm} above, but with a higher
2148 @defvar ITIMER_VIRTUAL
2149 A virtual-time timer, counting down while the current process is
2150 actually using CPU. At zero it raises @code{SIGVTALRM}.
2154 A profiling timer, counting down while the process is running (like
2155 @code{ITIMER_VIRTUAL}) and also while system calls are running on the
2156 process's behalf. At zero it raises a @code{SIGPROF}.
2158 This timer is intended for profiling where a program is spending its
2159 time (by looking where it is when the timer goes off).
2162 @code{getitimer} returns the current timer value and its programmed
2163 restart value, as a list containing two pairs. Each pair is a time in
2164 seconds and microseconds: @code{((@var{interval_secs}
2165 . @var{interval_usecs}) (@var{periodic_secs}
2166 . @var{periodic_usecs}))}.
2168 @code{setitimer} sets the timer values similarly, in seconds and
2169 microseconds (which must be integers). The periodic value can be zero
2170 to have the timer run down just once. The return value is the timer's
2171 previous setting, in the same form as @code{getitimer} returns.
2174 (setitimer ITIMER_REAL
2175 5 500000 ;; first SIGALRM in 5.5 seconds time
2176 2 0) ;; then repeat every 2 seconds
2179 Although the timers are programmed in microseconds, the actual
2180 accuracy might not be that high.
2184 @node Terminals and Ptys
2185 @subsection Terminals and Ptys
2187 @deffn {Scheme Procedure} isatty? port
2188 @deffnx {C Function} scm_isatty_p (port)
2190 Return @code{#t} if @var{port} is using a serial non--file
2191 device, otherwise @code{#f}.
2194 @deffn {Scheme Procedure} ttyname port
2195 @deffnx {C Function} scm_ttyname (port)
2197 Return a string with the name of the serial terminal device
2198 underlying @var{port}.
2201 @deffn {Scheme Procedure} ctermid
2202 @deffnx {C Function} scm_ctermid ()
2204 Return a string containing the file name of the controlling
2205 terminal for the current process.
2208 @deffn {Scheme Procedure} tcgetpgrp port
2209 @deffnx {C Function} scm_tcgetpgrp (port)
2210 @cindex process group
2211 Return the process group ID of the foreground process group
2212 associated with the terminal open on the file descriptor
2213 underlying @var{port}.
2215 If there is no foreground process group, the return value is a
2216 number greater than 1 that does not match the process group ID
2217 of any existing process group. This can happen if all of the
2218 processes in the job that was formerly the foreground job have
2219 terminated, and no other job has yet been moved into the
2223 @deffn {Scheme Procedure} tcsetpgrp port pgid
2224 @deffnx {C Function} scm_tcsetpgrp (port, pgid)
2225 @cindex process group
2226 Set the foreground process group ID for the terminal used by the file
2227 descriptor underlying @var{port} to the integer @var{pgid}.
2229 must be a member of the same session as @var{pgid} and must have the same
2230 controlling terminal. The return value is unspecified.
2237 The following procedures are similar to the @code{popen} and
2238 @code{pclose} system routines. The code is in a separate ``popen''
2239 module@footnote{This module is only available on systems where the
2240 @code{fork} feature is provided (@pxref{Common Feature Symbols}).}:
2243 (use-modules (ice-9 popen))
2247 @deffn {Scheme Procedure} open-pipe command mode
2248 @deffnx {Scheme Procedure} open-pipe* mode prog [args...]
2249 Execute a command in a subprocess, with a pipe to it or from it, or
2250 with pipes in both directions.
2252 @code{open-pipe} runs the shell @var{command} using @samp{/bin/sh -c}.
2253 @code{open-pipe*} executes @var{prog} directly, with the optional
2254 @var{args} arguments (all strings).
2256 @var{mode} should be one of the following values. @code{OPEN_READ} is
2257 an input pipe, ie.@: to read from the subprocess. @code{OPEN_WRITE}
2258 is an output pipe, ie.@: to write to it.
2265 For an input pipe, the child's standard output is the pipe and
2266 standard input is inherited from @code{current-input-port}. For an
2267 output pipe, the child's standard input is the pipe and standard
2268 output is inherited from @code{current-output-port}. In all cases
2269 cases the child's standard error is inherited from
2270 @code{current-error-port} (@pxref{Default Ports}).
2272 If those @code{current-X-ports} are not files of some kind, and hence
2273 don't have file descriptors for the child, then @file{/dev/null} is
2276 Care should be taken with @code{OPEN_BOTH}, a deadlock will occur if
2277 both parent and child are writing, and waiting until the write
2278 completes before doing any reading. Each direction has
2279 @code{PIPE_BUF} bytes of buffering (@pxref{Ports and File
2280 Descriptors}), which will be enough for small writes, but not for say
2281 putting a big file through a filter.
2284 @deffn {Scheme Procedure} open-input-pipe command
2285 Equivalent to @code{open-pipe} with mode @code{OPEN_READ}.
2288 (let* ((port (open-input-pipe "date --utc"))
2289 (str (read-line port)))
2292 @result{} "Mon Mar 11 20:10:44 UTC 2002"
2296 @deffn {Scheme Procedure} open-output-pipe command
2297 Equivalent to @code{open-pipe} with mode @code{OPEN_WRITE}.
2300 (let ((port (open-output-pipe "lpr")))
2301 (display "Something for the line printer.\n" port)
2302 (if (not (eqv? 0 (status:exit-val (close-pipe port))))
2303 (error "Cannot print")))
2307 @deffn {Scheme Procedure} open-input-output-pipe command
2308 Equivalent to @code{open-pipe} with mode @code{OPEN_BOTH}.
2312 @deffn {Scheme Procedure} close-pipe port
2313 Close a pipe created by @code{open-pipe}, wait for the process to
2314 terminate, and return the wait status code. The status is as per
2315 @code{waitpid} and can be decoded with @code{status:exit-val} etc
2320 @code{waitpid WAIT_ANY} should not be used when pipes are open, since
2321 it can reap a pipe's child process, causing an error from a subsequent
2324 @code{close-port} (@pxref{Closing}) can close a pipe, but it doesn't
2325 reap the child process.
2327 The garbage collector will close a pipe no longer in use, and reap the
2328 child process with @code{waitpid}. If the child hasn't yet terminated
2329 the garbage collector doesn't block, but instead checks again in the
2332 Many systems have per-user and system-wide limits on the number of
2333 processes, and a system-wide limit on the number of pipes, so pipes
2334 should be closed explicitly when no longer needed, rather than letting
2335 the garbage collector pick them up at some later time.
2339 @subsection Networking
2343 * Network Address Conversion::
2344 * Network Databases::
2345 * Network Socket Address::
2346 * Network Sockets and Communication::
2347 * Internet Socket Examples::
2350 @node Network Address Conversion
2351 @subsubsection Network Address Conversion
2352 @cindex network address
2354 This section describes procedures which convert internet addresses
2355 between numeric and string formats.
2357 @subsubheading IPv4 Address Conversion
2360 An IPv4 Internet address is a 4-byte value, represented in Guile as an
2361 integer in host byte order, so that say ``0.0.0.1'' is 1, or
2362 ``1.0.0.0'' is 16777216.
2364 Some underlying C functions use network byte order for addresses,
2365 Guile converts as necessary so that at the Scheme level its host byte
2369 For a server, this can be used with @code{bind} (@pxref{Network
2370 Sockets and Communication}) to allow connections from any interface on
2374 @defvar INADDR_BROADCAST
2375 The broadcast address on the local network.
2378 @defvar INADDR_LOOPBACK
2379 The address of the local host using the loopback device, ie.@:
2383 @c INADDR_NONE is defined in the code, but serves no purpose.
2384 @c inet_addr() returns it as an error indication, but that function
2385 @c isn't provided, for the good reason that inet_aton() does the same
2386 @c job and gives an unambiguous error indication. (INADDR_NONE is a
2387 @c valid 4-byte value, in glibc it's the same as INADDR_BROADCAST.)
2389 @c @defvar INADDR_NONE
2393 @deffn {Scheme Procedure} inet-aton address
2394 @deffnx {C Function} scm_inet_aton (address)
2395 This function is deprecated in favor of @code{inet-pton}.
2397 Convert an IPv4 Internet address from printable string
2398 (dotted decimal notation) to an integer. E.g.,
2401 (inet-aton "127.0.0.1") @result{} 2130706433
2405 @deffn {Scheme Procedure} inet-ntoa inetid
2406 @deffnx {C Function} scm_inet_ntoa (inetid)
2407 This function is deprecated in favor of @code{inet-ntop}.
2409 Convert an IPv4 Internet address to a printable
2410 (dotted decimal notation) string. E.g.,
2413 (inet-ntoa 2130706433) @result{} "127.0.0.1"
2417 @deffn {Scheme Procedure} inet-netof address
2418 @deffnx {C Function} scm_inet_netof (address)
2419 Return the network number part of the given IPv4
2420 Internet address. E.g.,
2423 (inet-netof 2130706433) @result{} 127
2427 @deffn {Scheme Procedure} inet-lnaof address
2428 @deffnx {C Function} scm_lnaof (address)
2429 Return the local-address-with-network part of the given
2430 IPv4 Internet address, using the obsolete class A/B/C system.
2434 (inet-lnaof 2130706433) @result{} 1
2438 @deffn {Scheme Procedure} inet-makeaddr net lna
2439 @deffnx {C Function} scm_inet_makeaddr (net, lna)
2440 Make an IPv4 Internet address by combining the network number
2441 @var{net} with the local-address-within-network number
2445 (inet-makeaddr 127 1) @result{} 2130706433
2449 @subsubheading IPv6 Address Conversion
2452 An IPv6 Internet address is a 16-byte value, represented in Guile as
2453 an integer in host byte order, so that say ``::1'' is 1.
2455 @deffn {Scheme Procedure} inet-ntop family address
2456 @deffnx {C Function} scm_inet_ntop (family, address)
2457 Convert a network address from an integer to a printable string.
2458 @var{family} can be @code{AF_INET} or @code{AF_INET6}. E.g.,
2461 (inet-ntop AF_INET 2130706433) @result{} "127.0.0.1"
2462 (inet-ntop AF_INET6 (- (expt 2 128) 1))
2463 @result{} "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff"
2467 @deffn {Scheme Procedure} inet-pton family address
2468 @deffnx {C Function} scm_inet_pton (family, address)
2469 Convert a string containing a printable network address to an integer
2470 address. @var{family} can be @code{AF_INET} or @code{AF_INET6}.
2474 (inet-pton AF_INET "127.0.0.1") @result{} 2130706433
2475 (inet-pton AF_INET6 "::1") @result{} 1
2480 @node Network Databases
2481 @subsubsection Network Databases
2482 @cindex network database
2484 This section describes procedures which query various network databases.
2485 Care should be taken when using the database routines since they are not
2488 @subsubheading @code{getaddrinfo}
2490 @cindex @code{addrinfo} object type
2491 @cindex host name lookup
2492 @cindex service name lookup
2494 The @code{getaddrinfo} procedure maps host and service names to socket addresses
2495 and associated information in a protocol-independent way.
2497 @deffn {Scheme Procedure} getaddrinfo name service [hint_flags [hint_family [hint_socktype [hint_protocol]]]]
2498 @deffnx {C Function} scm_getaddrinfo (name, service, hint_flags, hint_family, hint_socktype, hint_protocol)
2499 Return a list of @code{addrinfo} structures containing
2500 a socket address and associated information for host @var{name}
2501 and/or @var{service} to be used in creating a socket with
2502 which to address the specified service.
2505 (let* ((ai (car (getaddrinfo "www.gnu.org" "http")))
2506 (s (socket (addrinfo:fam ai) (addrinfo:socktype ai)
2507 (addrinfo:protocol ai))))
2508 (connect s (addrinfo:addr ai))
2512 When @var{service} is omitted or is @code{#f}, return
2513 network-level addresses for @var{name}. When @var{name}
2514 is @code{#f} @var{service} must be provided and service
2515 locations local to the caller are returned.
2517 Additional hints can be provided. When specified,
2518 @var{hint_flags} should be a bitwise-or of zero or more
2519 constants among the following:
2523 Socket address is intended for @code{bind}.
2526 Request for canonical host name, available via
2527 @code{addrinfo:canonname}. This makes sense mainly when
2528 DNS lookups are involved.
2530 @item AI_NUMERICHOST
2531 Specifies that @var{name} is a numeric host address string
2532 (e.g., @code{"127.0.0.1"}), meaning that name resolution
2535 @item AI_NUMERICSERV
2536 Likewise, specifies that @var{service} is a numeric port
2537 string (e.g., @code{"80"}).
2540 Return only addresses configured on the local system It is
2541 highly recommended to provide this flag when the returned
2542 socket addresses are to be used to make connections;
2543 otherwise, some of the returned addresses could be unreachable
2544 or use a protocol that is not supported.
2547 When looking up IPv6 addresses, return mapped IPv4 addresses if
2548 there is no IPv6 address available at all.
2551 If this flag is set along with @code{AI_V4MAPPED} when looking up IPv6
2552 addresses, return all IPv6 addresses as well as all IPv4 addresses, the latter
2553 mapped to IPv6 format.
2556 When given, @var{hint_family} should specify the requested
2557 address family, e.g., @code{AF_INET6}. Similarly,
2558 @var{hint_socktype} should specify the requested socket type
2559 (e.g., @code{SOCK_DGRAM}), and @var{hint_protocol} should
2560 specify the requested protocol (its value is interpreted
2561 as in calls to @code{socket}).
2563 On error, an exception with key @code{getaddrinfo-error} is
2564 thrown, with an error code (an integer) as its argument:
2567 (catch 'getaddrinfo-error
2569 (getaddrinfo "www.gnu.org" "gopher"))
2570 (lambda (key errcode)
2571 (cond ((= errcode EAI_SERVICE)
2572 (display "doesn't know about Gopher!\n"))
2573 ((= errcode EAI_NONAME)
2574 (display "www.gnu.org not found\\n"))
2576 (format #t "something wrong: ~a\n"
2577 (gai-strerror errcode))))))
2584 The name or service could not be resolved at this time. Future
2585 attempts may succeed.
2588 @var{hint_flags} contains an invalid value.
2591 A non-recoverable error occurred when attempting to
2595 @var{hint_family} was not recognized.
2598 Either @var{name} does not resolve for the supplied parameters,
2599 or neither @var{name} nor @var{service} were supplied.
2602 This non-POSIX error code can be returned on some systems (GNU
2603 and Darwin, at least), for example when @var{name} is known
2604 but requests that were made turned out no data. Error handling
2605 code should be prepared to handle it when it is defined.
2608 @var{service} was not recognized for the specified socket type.
2611 @var{hint_socktype} was not recognized.
2614 A system error occurred. In C, the error code can be found in
2615 @code{errno}; this value is not accessible from Scheme, but in
2616 practice it provides little information about the actual error
2618 @c See <http://bugs.gnu.org/13958>.
2621 Users are encouraged to read the
2622 @url{http://www.opengroup.org/onlinepubs/9699919799/functions/getaddrinfo.html,
2623 "POSIX specification} for more details.
2626 The following procedures take an @code{addrinfo} object as returned by
2629 @deffn {Scheme Procedure} addrinfo:flags ai
2630 Return flags for @var{ai} as a bitwise or of @code{AI_} values (see above).
2633 @deffn {Scheme Procedure} addrinfo:fam ai
2634 Return the address family of @var{ai} (a @code{AF_} value).
2637 @deffn {Scheme Procedure} addrinfo:socktype ai
2638 Return the socket type for @var{ai} (a @code{SOCK_} value).
2641 @deffn {Scheme Procedure} addrinfo:protocol ai
2642 Return the protocol of @var{ai}.
2645 @deffn {Scheme Procedure} addrinfo:addr ai
2646 Return the socket address associated with @var{ai} as a @code{sockaddr}
2647 object (@pxref{Network Socket Address}).
2650 @deffn {Scheme Procedure} addrinfo:canonname ai
2651 Return a string for the canonical name associated with @var{ai} if
2652 the @code{AI_CANONNAME} flag was supplied.
2655 @subsubheading The Host Database
2656 @cindex @file{/etc/hosts}
2657 @cindex network database
2659 A @dfn{host object} is a structure that represents what is known about a
2660 network host, and is the usual way of representing a system's network
2661 identity inside software.
2663 The following functions accept a host object and return a selected
2666 @deffn {Scheme Procedure} hostent:name host
2667 The ``official'' hostname for @var{host}.
2669 @deffn {Scheme Procedure} hostent:aliases host
2670 A list of aliases for @var{host}.
2672 @deffn {Scheme Procedure} hostent:addrtype host
2673 The host address type, one of the @code{AF} constants, such as
2674 @code{AF_INET} or @code{AF_INET6}.
2676 @deffn {Scheme Procedure} hostent:length host
2677 The length of each address for @var{host}, in bytes.
2679 @deffn {Scheme Procedure} hostent:addr-list host
2680 The list of network addresses associated with @var{host}. For
2681 @code{AF_INET} these are integer IPv4 address (@pxref{Network Address
2685 The following procedures can be used to search the host database. However,
2686 @code{getaddrinfo} should be preferred over them since it's more generic and
2689 @deffn {Scheme Procedure} gethost [host]
2690 @deffnx {Scheme Procedure} gethostbyname hostname
2691 @deffnx {Scheme Procedure} gethostbyaddr address
2692 @deffnx {C Function} scm_gethost (host)
2693 Look up a host by name or address, returning a host object. The
2694 @code{gethost} procedure will accept either a string name or an integer
2695 address; if given no arguments, it behaves like @code{gethostent} (see
2696 below). If a name or address is supplied but the address can not be
2697 found, an error will be thrown to one of the keys:
2698 @code{host-not-found}, @code{try-again}, @code{no-recovery} or
2699 @code{no-data}, corresponding to the equivalent @code{h_error} values.
2700 Unusual conditions may result in errors thrown to the
2701 @code{system-error} or @code{misc_error} keys.
2704 (gethost "www.gnu.org")
2705 @result{} #("www.gnu.org" () 2 4 (3353880842))
2707 (gethostbyname "www.emacs.org")
2708 @result{} #("emacs.org" ("www.emacs.org") 2 4 (1073448978))
2712 The following procedures may be used to step through the host
2713 database from beginning to end.
2715 @deffn {Scheme Procedure} sethostent [stayopen]
2716 Initialize an internal stream from which host objects may be read. This
2717 procedure must be called before any calls to @code{gethostent}, and may
2718 also be called afterward to reset the host entry stream. If
2719 @var{stayopen} is supplied and is not @code{#f}, the database is not
2720 closed by subsequent @code{gethostbyname} or @code{gethostbyaddr} calls,
2721 possibly giving an efficiency gain.
2724 @deffn {Scheme Procedure} gethostent
2725 Return the next host object from the host database, or @code{#f} if
2726 there are no more hosts to be found (or an error has been encountered).
2727 This procedure may not be used before @code{sethostent} has been called.
2730 @deffn {Scheme Procedure} endhostent
2731 Close the stream used by @code{gethostent}. The return value is unspecified.
2734 @deffn {Scheme Procedure} sethost [stayopen]
2735 @deffnx {C Function} scm_sethost (stayopen)
2736 If @var{stayopen} is omitted, this is equivalent to @code{endhostent}.
2737 Otherwise it is equivalent to @code{sethostent stayopen}.
2740 @subsubheading The Network Database
2741 @cindex network database
2743 The following functions accept an object representing a network
2744 and return a selected component:
2746 @deffn {Scheme Procedure} netent:name net
2747 The ``official'' network name.
2749 @deffn {Scheme Procedure} netent:aliases net
2750 A list of aliases for the network.
2752 @deffn {Scheme Procedure} netent:addrtype net
2753 The type of the network number. Currently, this returns only
2756 @deffn {Scheme Procedure} netent:net net
2760 The following procedures are used to search the network database:
2762 @deffn {Scheme Procedure} getnet [net]
2763 @deffnx {Scheme Procedure} getnetbyname net-name
2764 @deffnx {Scheme Procedure} getnetbyaddr net-number
2765 @deffnx {C Function} scm_getnet (net)
2766 Look up a network by name or net number in the network database. The
2767 @var{net-name} argument must be a string, and the @var{net-number}
2768 argument must be an integer. @code{getnet} will accept either type of
2769 argument, behaving like @code{getnetent} (see below) if no arguments are
2773 The following procedures may be used to step through the network
2774 database from beginning to end.
2776 @deffn {Scheme Procedure} setnetent [stayopen]
2777 Initialize an internal stream from which network objects may be read. This
2778 procedure must be called before any calls to @code{getnetent}, and may
2779 also be called afterward to reset the net entry stream. If
2780 @var{stayopen} is supplied and is not @code{#f}, the database is not
2781 closed by subsequent @code{getnetbyname} or @code{getnetbyaddr} calls,
2782 possibly giving an efficiency gain.
2785 @deffn {Scheme Procedure} getnetent
2786 Return the next entry from the network database.
2789 @deffn {Scheme Procedure} endnetent
2790 Close the stream used by @code{getnetent}. The return value is unspecified.
2793 @deffn {Scheme Procedure} setnet [stayopen]
2794 @deffnx {C Function} scm_setnet (stayopen)
2795 If @var{stayopen} is omitted, this is equivalent to @code{endnetent}.
2796 Otherwise it is equivalent to @code{setnetent stayopen}.
2799 @subsubheading The Protocol Database
2800 @cindex @file{/etc/protocols}
2802 @cindex network protocols
2804 The following functions accept an object representing a protocol
2805 and return a selected component:
2807 @deffn {Scheme Procedure} protoent:name protocol
2808 The ``official'' protocol name.
2810 @deffn {Scheme Procedure} protoent:aliases protocol
2811 A list of aliases for the protocol.
2813 @deffn {Scheme Procedure} protoent:proto protocol
2814 The protocol number.
2817 The following procedures are used to search the protocol database:
2819 @deffn {Scheme Procedure} getproto [protocol]
2820 @deffnx {Scheme Procedure} getprotobyname name
2821 @deffnx {Scheme Procedure} getprotobynumber number
2822 @deffnx {C Function} scm_getproto (protocol)
2823 Look up a network protocol by name or by number. @code{getprotobyname}
2824 takes a string argument, and @code{getprotobynumber} takes an integer
2825 argument. @code{getproto} will accept either type, behaving like
2826 @code{getprotoent} (see below) if no arguments are supplied.
2829 The following procedures may be used to step through the protocol
2830 database from beginning to end.
2832 @deffn {Scheme Procedure} setprotoent [stayopen]
2833 Initialize an internal stream from which protocol objects may be read. This
2834 procedure must be called before any calls to @code{getprotoent}, and may
2835 also be called afterward to reset the protocol entry stream. If
2836 @var{stayopen} is supplied and is not @code{#f}, the database is not
2837 closed by subsequent @code{getprotobyname} or @code{getprotobynumber} calls,
2838 possibly giving an efficiency gain.
2841 @deffn {Scheme Procedure} getprotoent
2842 Return the next entry from the protocol database.
2845 @deffn {Scheme Procedure} endprotoent
2846 Close the stream used by @code{getprotoent}. The return value is unspecified.
2849 @deffn {Scheme Procedure} setproto [stayopen]
2850 @deffnx {C Function} scm_setproto (stayopen)
2851 If @var{stayopen} is omitted, this is equivalent to @code{endprotoent}.
2852 Otherwise it is equivalent to @code{setprotoent stayopen}.
2855 @subsubheading The Service Database
2856 @cindex @file{/etc/services}
2858 @cindex network services
2860 The following functions accept an object representing a service
2861 and return a selected component:
2863 @deffn {Scheme Procedure} servent:name serv
2864 The ``official'' name of the network service.
2866 @deffn {Scheme Procedure} servent:aliases serv
2867 A list of aliases for the network service.
2869 @deffn {Scheme Procedure} servent:port serv
2870 The Internet port used by the service.
2872 @deffn {Scheme Procedure} servent:proto serv
2873 The protocol used by the service. A service may be listed many times
2874 in the database under different protocol names.
2877 The following procedures are used to search the service database:
2879 @deffn {Scheme Procedure} getserv [name [protocol]]
2880 @deffnx {Scheme Procedure} getservbyname name protocol
2881 @deffnx {Scheme Procedure} getservbyport port protocol
2882 @deffnx {C Function} scm_getserv (name, protocol)
2883 Look up a network service by name or by service number, and return a
2884 network service object. The @var{protocol} argument specifies the name
2885 of the desired protocol; if the protocol found in the network service
2886 database does not match this name, a system error is signalled.
2888 The @code{getserv} procedure will take either a service name or number
2889 as its first argument; if given no arguments, it behaves like
2890 @code{getservent} (see below).
2893 (getserv "imap" "tcp")
2894 @result{} #("imap2" ("imap") 143 "tcp")
2896 (getservbyport 88 "udp")
2897 @result{} #("kerberos" ("kerberos5" "krb5") 88 "udp")
2901 The following procedures may be used to step through the service
2902 database from beginning to end.
2904 @deffn {Scheme Procedure} setservent [stayopen]
2905 Initialize an internal stream from which service objects may be read. This
2906 procedure must be called before any calls to @code{getservent}, and may
2907 also be called afterward to reset the service entry stream. If
2908 @var{stayopen} is supplied and is not @code{#f}, the database is not
2909 closed by subsequent @code{getservbyname} or @code{getservbyport} calls,
2910 possibly giving an efficiency gain.
2913 @deffn {Scheme Procedure} getservent
2914 Return the next entry from the services database.
2917 @deffn {Scheme Procedure} endservent
2918 Close the stream used by @code{getservent}. The return value is unspecified.
2921 @deffn {Scheme Procedure} setserv [stayopen]
2922 @deffnx {C Function} scm_setserv (stayopen)
2923 If @var{stayopen} is omitted, this is equivalent to @code{endservent}.
2924 Otherwise it is equivalent to @code{setservent stayopen}.
2928 @node Network Socket Address
2929 @subsubsection Network Socket Address
2930 @cindex socket address
2931 @cindex network socket address
2932 @tpindex Socket address
2934 A @dfn{socket address} object identifies a socket endpoint for
2935 communication. In the case of @code{AF_INET} for instance, the socket
2936 address object comprises the host address (or interface on the host)
2937 and a port number which specifies a particular open socket in a
2938 running client or server process. A socket address object can be
2941 @deffn {Scheme Procedure} make-socket-address AF_INET ipv4addr port
2942 @deffnx {Scheme Procedure} make-socket-address AF_INET6 ipv6addr port [flowinfo [scopeid]]
2943 @deffnx {Scheme Procedure} make-socket-address AF_UNIX path
2944 @deffnx {C Function} scm_make_socket_address (family, address, arglist)
2945 Return a new socket address object. The first argument is the address
2946 family, one of the @code{AF} constants, then the arguments vary
2947 according to the family.
2949 For @code{AF_INET} the arguments are an IPv4 network address number
2950 (@pxref{Network Address Conversion}), and a port number.
2952 For @code{AF_INET6} the arguments are an IPv6 network address number
2953 and a port number. Optional @var{flowinfo} and @var{scopeid}
2954 arguments may be given (both integers, default 0).
2956 For @code{AF_UNIX} the argument is a filename (a string).
2958 The C function @code{scm_make_socket_address} takes the @var{family}
2959 and @var{address} arguments directly, then @var{arglist} is a list of
2960 further arguments, being the port for IPv4, port and optional flowinfo
2961 and scopeid for IPv6, or the empty list @code{SCM_EOL} for Unix
2966 The following functions access the fields of a socket address object,
2968 @deffn {Scheme Procedure} sockaddr:fam sa
2969 Return the address family from socket address object @var{sa}. This
2970 is one of the @code{AF} constants (e.g.@: @code{AF_INET}).
2973 @deffn {Scheme Procedure} sockaddr:path sa
2974 For an @code{AF_UNIX} socket address object @var{sa}, return the
2978 @deffn {Scheme Procedure} sockaddr:addr sa
2979 For an @code{AF_INET} or @code{AF_INET6} socket address object
2980 @var{sa}, return the network address number.
2983 @deffn {Scheme Procedure} sockaddr:port sa
2984 For an @code{AF_INET} or @code{AF_INET6} socket address object
2985 @var{sa}, return the port number.
2988 @deffn {Scheme Procedure} sockaddr:flowinfo sa
2989 For an @code{AF_INET6} socket address object @var{sa}, return the
2993 @deffn {Scheme Procedure} sockaddr:scopeid sa
2994 For an @code{AF_INET6} socket address object @var{sa}, return the
2998 @tpindex @code{struct sockaddr}
2999 @tpindex @code{sockaddr}
3000 The functions below convert to and from the C @code{struct sockaddr}
3001 (@pxref{Address Formats,,, libc, The GNU C Library Reference Manual}).
3002 That structure is a generic type, an application can cast to or from
3003 @code{struct sockaddr_in}, @code{struct sockaddr_in6} or @code{struct
3004 sockaddr_un} according to the address family.
3006 In a @code{struct sockaddr} taken or returned, the byte ordering in
3007 the fields follows the C conventions (@pxref{Byte Order,, Byte Order
3008 Conversion, libc, The GNU C Library Reference Manual}). This means
3009 network byte order for @code{AF_INET} host address
3010 (@code{sin_addr.s_addr}) and port number (@code{sin_port}), and
3011 @code{AF_INET6} port number (@code{sin6_port}). But at the Scheme
3012 level these values are taken or returned in host byte order, so the
3013 port is an ordinary integer, and the host address likewise is an
3014 ordinary integer (as described in @ref{Network Address Conversion}).
3016 @deftypefn {C Function} {struct sockaddr *} scm_c_make_socket_address (SCM family, SCM address, SCM args, size_t *outsize)
3017 Return a newly-@code{malloc}ed @code{struct sockaddr} created from
3018 arguments like those taken by @code{scm_make_socket_address} above.
3020 The size (in bytes) of the @code{struct sockaddr} return is stored
3021 into @code{*@var{outsize}}. An application must call @code{free} to
3022 release the returned structure when no longer required.
3025 @deftypefn {C Function} SCM scm_from_sockaddr (const struct sockaddr *address, unsigned address_size)
3026 Return a Scheme socket address object from the C @var{address}
3027 structure. @var{address_size} is the size in bytes of @var{address}.
3030 @deftypefn {C Function} {struct sockaddr *} scm_to_sockaddr (SCM address, size_t *address_size)
3031 Return a newly-@code{malloc}ed @code{struct sockaddr} from a Scheme
3032 level socket address object.
3034 The size (in bytes) of the @code{struct sockaddr} return is stored
3035 into @code{*@var{outsize}}. An application must call @code{free} to
3036 release the returned structure when no longer required.
3040 @node Network Sockets and Communication
3041 @subsubsection Network Sockets and Communication
3043 @cindex network socket
3045 Socket ports can be created using @code{socket} and @code{socketpair}.
3046 The ports are initially unbuffered, to make reading and writing to the
3047 same port more reliable. A buffer can be added to the port using
3048 @code{setvbuf}; see @ref{Ports and File Descriptors}.
3050 Most systems have limits on how many files and sockets can be open, so
3051 it's strongly recommended that socket ports be closed explicitly when
3052 no longer required (@pxref{Ports}).
3054 Some of the underlying C functions take values in network byte order,
3055 but the convention in Guile is that at the Scheme level everything is
3056 ordinary host byte order and conversions are made automatically where
3059 @deffn {Scheme Procedure} socket family style proto
3060 @deffnx {C Function} scm_socket (family, style, proto)
3061 Return a new socket port of the type specified by @var{family},
3062 @var{style} and @var{proto}. All three parameters are integers. The
3063 possible values for @var{family} are as follows, where supported by
3071 The possible values for @var{style} are as follows, again where
3072 supported by the system,
3078 @defvarx SOCK_SEQPACKET
3081 @var{proto} can be obtained from a protocol name using
3082 @code{getprotobyname} (@pxref{Network Databases}). A value of zero
3083 means the default protocol, which is usually right.
3085 A socket cannot by used for communication until it has been connected
3086 somewhere, usually with either @code{connect} or @code{accept} below.
3089 @deffn {Scheme Procedure} socketpair family style proto
3090 @deffnx {C Function} scm_socketpair (family, style, proto)
3091 Return a pair, the @code{car} and @code{cdr} of which are two unnamed
3092 socket ports connected to each other. The connection is full-duplex,
3093 so data can be transferred in either direction between the two.
3095 @var{family}, @var{style} and @var{proto} are as per @code{socket}
3096 above. But many systems only support socket pairs in the
3097 @code{PF_UNIX} family. Zero is likely to be the only meaningful value
3101 @deffn {Scheme Procedure} getsockopt sock level optname
3102 @deffnx {Scheme Procedure} setsockopt sock level optname value
3103 @deffnx {C Function} scm_getsockopt (sock, level, optname)
3104 @deffnx {C Function} scm_setsockopt (sock, level, optname, value)
3105 Get or set an option on socket port @var{sock}. @code{getsockopt}
3106 returns the current value. @code{setsockopt} sets a value and the
3107 return is unspecified.
3109 @var{level} is an integer specifying a protocol layer, either
3110 @code{SOL_SOCKET} for socket level options, or a protocol number from
3111 the @code{IPPROTO} constants or @code{getprotoent} (@pxref{Network
3116 @defvarx IPPROTO_TCP
3117 @defvarx IPPROTO_UDP
3120 @var{optname} is an integer specifying an option within the protocol
3123 For @code{SOL_SOCKET} level the following @var{optname}s are defined
3124 (when provided by the system). For their meaning see
3125 @ref{Socket-Level Options,,, libc, The GNU C Library Reference
3126 Manual}, or @command{man 7 socket}.
3129 @defvarx SO_REUSEADDR
3133 @defvarx SO_DONTROUTE
3134 @defvarx SO_BROADCAST
3137 @defvarx SO_KEEPALIVE
3138 @defvarx SO_OOBINLINE
3139 @defvarx SO_NO_CHECK
3140 @defvarx SO_PRIORITY
3141 @defvarx SO_REUSEPORT
3142 The @var{value} taken or returned is an integer.
3146 The @var{value} taken or returned is a pair of integers
3147 @code{(@var{ENABLE} . @var{TIMEOUT})}. On old systems without timeout
3148 support (ie.@: without @code{struct linger}), only @var{ENABLE} has an
3149 effect but the value in Guile is always a pair.
3152 @c Note that we refer only to ``man ip'' here. On GNU/Linux it's
3153 @c ``man 7 ip'' but on NetBSD it's ``man 4 ip''.
3155 For IP level (@code{IPPROTO_IP}) the following @var{optname}s are
3156 defined (when provided by the system). See @command{man ip} for what
3159 @defvar IP_MULTICAST_IF
3160 This sets the source interface used by multicast traffic.
3163 @defvar IP_MULTICAST_TTL
3164 This sets the default TTL for multicast traffic. This defaults
3165 to 1 and should be increased to allow traffic to pass beyond the
3169 @defvar IP_ADD_MEMBERSHIP
3170 @defvarx IP_DROP_MEMBERSHIP
3171 These can be used only with @code{setsockopt}, not @code{getsockopt}.
3172 @var{value} is a pair @code{(@var{MULTIADDR} . @var{INTERFACEADDR})}
3173 of integer IPv4 addresses (@pxref{Network Address Conversion}).
3174 @var{MULTIADDR} is a multicast address to be added to or dropped from
3175 the interface @var{INTERFACEADDR}. @var{INTERFACEADDR} can be
3176 @code{INADDR_ANY} to have the system select the interface.
3177 @var{INTERFACEADDR} can also be an interface index number, on systems
3182 @deffn {Scheme Procedure} shutdown sock how
3183 @deffnx {C Function} scm_shutdown (sock, how)
3184 Sockets can be closed simply by using @code{close-port}. The
3185 @code{shutdown} procedure allows reception or transmission on a
3186 connection to be shut down individually, according to the parameter
3191 Stop receiving data for this socket. If further data arrives, reject it.
3193 Stop trying to transmit data from this socket. Discard any
3194 data waiting to be sent. Stop looking for acknowledgement of
3195 data already sent; don't retransmit it if it is lost.
3197 Stop both reception and transmission.
3200 The return value is unspecified.
3203 @deffn {Scheme Procedure} connect sock sockaddr
3204 @deffnx {Scheme Procedure} connect sock AF_INET ipv4addr port
3205 @deffnx {Scheme Procedure} connect sock AF_INET6 ipv6addr port [flowinfo [scopeid]]
3206 @deffnx {Scheme Procedure} connect sock AF_UNIX path
3207 @deffnx {C Function} scm_connect (sock, fam, address, args)
3208 Initiate a connection on socket port @var{sock} to a given address.
3209 The destination is either a socket address object, or arguments the
3210 same as @code{make-socket-address} would take to make such an object
3211 (@pxref{Network Socket Address}). The return value is unspecified.
3214 (connect sock AF_INET INADDR_LOOPBACK 23)
3215 (connect sock (make-socket-address AF_INET INADDR_LOOPBACK 23))
3219 @deffn {Scheme Procedure} bind sock sockaddr
3220 @deffnx {Scheme Procedure} bind sock AF_INET ipv4addr port
3221 @deffnx {Scheme Procedure} bind sock AF_INET6 ipv6addr port [flowinfo [scopeid]]
3222 @deffnx {Scheme Procedure} bind sock AF_UNIX path
3223 @deffnx {C Function} scm_bind (sock, fam, address, args)
3224 Bind socket port @var{sock} to the given address. The address is
3225 either a socket address object, or arguments the same as
3226 @code{make-socket-address} would take to make such an object
3227 (@pxref{Network Socket Address}). The return value is unspecified.
3229 Generally a socket is only explicitly bound to a particular address
3230 when making a server, i.e.@: to listen on a particular port. For an
3231 outgoing connection the system will assign a local address
3232 automatically, if not already bound.
3235 (bind sock AF_INET INADDR_ANY 12345)
3236 (bind sock (make-socket-address AF_INET INADDR_ANY 12345))
3240 @deffn {Scheme Procedure} listen sock backlog
3241 @deffnx {C Function} scm_listen (sock, backlog)
3242 Enable @var{sock} to accept connection
3243 requests. @var{backlog} is an integer specifying
3244 the maximum length of the queue for pending connections.
3245 If the queue fills, new clients will fail to connect until
3246 the server calls @code{accept} to accept a connection from
3249 The return value is unspecified.
3252 @deffn {Scheme Procedure} accept sock
3253 @deffnx {C Function} scm_accept (sock)
3254 Accept a connection from socket port @var{sock} which has been enabled
3255 for listening with @code{listen} above. If there are no incoming
3256 connections in the queue, wait until one is available (unless
3257 @code{O_NONBLOCK} has been set on the socket, @pxref{Ports and File
3258 Descriptors,@code{fcntl}}).
3260 The return value is a pair. The @code{car} is a new socket port,
3261 connected and ready to communicate. The @code{cdr} is a socket
3262 address object (@pxref{Network Socket Address}) which is where the
3263 remote connection is from (like @code{getpeername} below).
3265 All communication takes place using the new socket returned. The
3266 given @var{sock} remains bound and listening, and @code{accept} may be
3267 called on it again to get another incoming connection when desired.
3270 @deffn {Scheme Procedure} getsockname sock
3271 @deffnx {C Function} scm_getsockname (sock)
3272 Return a socket address object which is the where @var{sock} is bound
3273 locally. @var{sock} may have obtained its local address from
3274 @code{bind} (above), or if a @code{connect} is done with an otherwise
3275 unbound socket (which is usual) then the system will have assigned an
3278 Note that on many systems the address of a socket in the
3279 @code{AF_UNIX} namespace cannot be read.
3282 @deffn {Scheme Procedure} getpeername sock
3283 @deffnx {C Function} scm_getpeername (sock)
3284 Return a socket address object which is where @var{sock} is connected
3285 to, i.e.@: the remote endpoint.
3287 Note that on many systems the address of a socket in the
3288 @code{AF_UNIX} namespace cannot be read.
3291 @deffn {Scheme Procedure} recv! sock buf [flags]
3292 @deffnx {C Function} scm_recv (sock, buf, flags)
3293 Receive data from a socket port.
3294 @var{sock} must already
3295 be bound to the address from which data is to be received.
3296 @var{buf} is a bytevector into which
3297 the data will be written. The size of @var{buf} limits
3299 data which can be received: in the case of packet
3300 protocols, if a packet larger than this limit is encountered
3302 will be irrevocably lost.
3306 @vindex MSG_DONTROUTE
3307 The optional @var{flags} argument is a value or bitwise OR of
3308 @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
3310 The value returned is the number of bytes read from the
3313 Note that the data is read directly from the socket file
3315 any unread buffered port data is ignored.
3318 @deffn {Scheme Procedure} send sock message [flags]
3319 @deffnx {C Function} scm_send (sock, message, flags)
3322 @vindex MSG_DONTROUTE
3323 Transmit bytevector @var{message} on socket port @var{sock}.
3324 @var{sock} must already be bound to a destination address. The value
3325 returned is the number of bytes transmitted---it's possible for this
3326 to be less than the length of @var{message} if the socket is set to be
3327 non-blocking. The optional @var{flags} argument is a value or bitwise
3328 OR of @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
3330 Note that the data is written directly to the socket
3332 any unflushed buffered port data is ignored.
3335 @deffn {Scheme Procedure} recvfrom! sock buf [flags [start [end]]]
3336 @deffnx {C Function} scm_recvfrom (sock, buf, flags, start, end)
3337 Receive data from socket port @var{sock}, returning the originating
3338 address as well as the data. This function is usually for datagram
3339 sockets, but can be used on stream-oriented sockets too.
3341 The data received is stored in bytevector @var{buf}, using
3342 either the whole bytevector or just the region between the optional
3343 @var{start} and @var{end} positions. The size of @var{buf}
3344 limits the amount of data that can be received. For datagram
3345 protocols if a packet larger than this is received then excess
3346 bytes are irrevocably lost.
3348 The return value is a pair. The @code{car} is the number of bytes
3349 read. The @code{cdr} is a socket address object (@pxref{Network
3350 Socket Address}) which is where the data came from, or @code{#f} if
3351 the origin is unknown.
3355 @vindex MSG_DONTROUTE
3356 The optional @var{flags} argument is a or bitwise-OR (@code{logior})
3357 of @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
3359 Data is read directly from the socket file descriptor, any buffered
3360 port data is ignored.
3362 @c This was linux kernel 2.6.15 and glibc 2.3.6, not sure what any
3363 @c specs are supposed to say about recvfrom threading.
3365 On a GNU/Linux system @code{recvfrom!} is not multi-threading, all
3366 threads stop while a @code{recvfrom!} call is in progress. An
3367 application may need to use @code{select}, @code{O_NONBLOCK} or
3368 @code{MSG_DONTWAIT} to avoid this.
3371 @deffn {Scheme Procedure} sendto sock message sockaddr [flags]
3372 @deffnx {Scheme Procedure} sendto sock message AF_INET ipv4addr port [flags]
3373 @deffnx {Scheme Procedure} sendto sock message AF_INET6 ipv6addr port [flowinfo [scopeid [flags]]]
3374 @deffnx {Scheme Procedure} sendto sock message AF_UNIX path [flags]
3375 @deffnx {C Function} scm_sendto (sock, message, fam, address, args_and_flags)
3376 Transmit bytevector @var{message} as a datagram socket port
3377 @var{sock}. The destination is specified either as a socket address
3378 object, or as arguments the same as would be taken by
3379 @code{make-socket-address} to create such an object (@pxref{Network
3382 The destination address may be followed by an optional @var{flags}
3383 argument which is a @code{logior} (@pxref{Bitwise Operations}) of
3384 @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
3386 The value returned is the number of bytes transmitted --
3388 this to be less than the length of @var{message} if the
3390 set to be non-blocking.
3391 Note that the data is written directly to the socket
3393 any unflushed buffered port data is ignored.
3396 The following functions can be used to convert short and long integers
3397 between ``host'' and ``network'' order. Although the procedures above do
3398 this automatically for addresses, the conversion will still need to
3399 be done when sending or receiving encoded integer data from the network.
3401 @deffn {Scheme Procedure} htons value
3402 @deffnx {C Function} scm_htons (value)
3403 Convert a 16 bit quantity from host to network byte ordering.
3404 @var{value} is packed into 2 bytes, which are then converted
3405 and returned as a new integer.
3408 @deffn {Scheme Procedure} ntohs value
3409 @deffnx {C Function} scm_ntohs (value)
3410 Convert a 16 bit quantity from network to host byte ordering.
3411 @var{value} is packed into 2 bytes, which are then converted
3412 and returned as a new integer.
3415 @deffn {Scheme Procedure} htonl value
3416 @deffnx {C Function} scm_htonl (value)
3417 Convert a 32 bit quantity from host to network byte ordering.
3418 @var{value} is packed into 4 bytes, which are then converted
3419 and returned as a new integer.
3422 @deffn {Scheme Procedure} ntohl value
3423 @deffnx {C Function} scm_ntohl (value)
3424 Convert a 32 bit quantity from network to host byte ordering.
3425 @var{value} is packed into 4 bytes, which are then converted
3426 and returned as a new integer.
3429 These procedures are inconvenient to use at present, but consider:
3432 (define write-network-long
3433 (lambda (value port)
3434 (let ((v (make-uniform-vector 1 1 0)))
3435 (uniform-vector-set! v 0 (htonl value))
3436 (uniform-vector-write v port))))
3438 (define read-network-long
3440 (let ((v (make-uniform-vector 1 1 0)))
3441 (uniform-vector-read! v port)
3442 (ntohl (uniform-vector-ref v 0)))))
3446 @node Internet Socket Examples
3447 @subsubsection Network Socket Examples
3448 @cindex network examples
3449 @cindex socket examples
3451 The following give examples of how to use network sockets.
3453 @subsubheading Internet Socket Client Example
3455 @cindex socket client example
3456 The following example demonstrates an Internet socket client.
3457 It connects to the HTTP daemon running on the local machine and
3458 returns the contents of the root index URL.
3461 (let ((s (socket PF_INET SOCK_STREAM 0)))
3462 (connect s AF_INET (inet-pton AF_INET "127.0.0.1") 80)
3463 (display "GET / HTTP/1.0\r\n\r\n" s)
3465 (do ((line (read-line s) (read-line s)))
3466 ((eof-object? line))
3472 @subsubheading Internet Socket Server Example
3474 @cindex socket server example
3475 The following example shows a simple Internet server which listens on
3476 port 2904 for incoming connections and sends a greeting back to the
3480 (let ((s (socket PF_INET SOCK_STREAM 0)))
3481 (setsockopt s SOL_SOCKET SO_REUSEADDR 1)
3482 ;; @r{Specific address?}
3483 ;; @r{(bind s AF_INET (inet-pton AF_INET "127.0.0.1") 2904)}
3484 (bind s AF_INET INADDR_ANY 2904)
3487 (simple-format #t "Listening for clients in pid: ~S" (getpid))
3491 (let* ((client-connection (accept s))
3492 (client-details (cdr client-connection))
3493 (client (car client-connection)))
3494 (simple-format #t "Got new client connection: ~S"
3497 (simple-format #t "Client address: ~S"
3499 (sockaddr:addr client-details)))
3501 ;; @r{Send back the greeting to the client port}
3502 (display "Hello client\r\n" client)
3507 @node System Identification
3508 @subsection System Identification
3511 This section lists the various procedures Guile provides for accessing
3512 information about the system it runs on.
3514 @deffn {Scheme Procedure} uname
3515 @deffnx {C Function} scm_uname ()
3516 Return an object with some information about the computer
3517 system the program is running on.
3519 The following procedures accept an object as returned by @code{uname}
3520 and return a selected component (all of which are strings).
3522 @deffn {Scheme Procedure} utsname:sysname un
3523 The name of the operating system.
3525 @deffn {Scheme Procedure} utsname:nodename un
3526 The network name of the computer.
3528 @deffn {Scheme Procedure} utsname:release un
3529 The current release level of the operating system implementation.
3531 @deffn {Scheme Procedure} utsname:version un
3532 The current version level within the release of the operating system.
3534 @deffn {Scheme Procedure} utsname:machine un
3535 A description of the hardware.
3539 @deffn {Scheme Procedure} gethostname
3540 @deffnx {C Function} scm_gethostname ()
3542 Return the host name of the current processor.
3545 @deffn {Scheme Procedure} sethostname name
3546 @deffnx {C Function} scm_sethostname (name)
3547 Set the host name of the current processor to @var{name}. May
3548 only be used by the superuser. The return value is not
3556 @deffn {Scheme Procedure} setlocale category [locale]
3557 @deffnx {C Function} scm_setlocale (category, locale)
3558 Get or set the current locale, used for various internationalizations.
3559 Locales are strings, such as @samp{sv_SE}.
3561 If @var{locale} is given then the locale for the given @var{category}
3562 is set and the new value returned. If @var{locale} is not given then
3563 the current value is returned. @var{category} should be one of the
3564 following values (@pxref{Locale Categories, Categories of Activities
3565 that Locales Affect,, libc, The GNU C Library Reference Manual}):
3570 @defvarx LC_MESSAGES
3571 @defvarx LC_MONETARY
3577 A common usage is @samp{(setlocale LC_ALL "")}, which initializes all
3578 categories based on standard environment variables (@code{LANG} etc).
3579 For full details on categories and locale names @pxref{Locales,,
3580 Locales and Internationalization, libc, The GNU C Library Reference
3583 Note that @code{setlocale} affects locale settings for the whole
3584 process. @xref{i18n Introduction, locale objects and
3585 @code{make-locale}}, for a thread-safe alternative.
3589 @subsection Encryption
3592 Please note that the procedures in this section are not suited for
3593 strong encryption, they are only interfaces to the well-known and
3594 common system library functions of the same name. They are just as good
3595 (or bad) as the underlying functions, so you should refer to your system
3596 documentation before using them (@pxref{crypt,, Encrypting Passwords,
3597 libc, The GNU C Library Reference Manual}).
3599 @deffn {Scheme Procedure} crypt key salt
3600 @deffnx {C Function} scm_crypt (key, salt)
3601 Encrypt @var{key}, with the addition of @var{salt} (both strings),
3602 using the @code{crypt} C library call.
3605 Although @code{getpass} is not an encryption procedure per se, it
3606 appears here because it is often used in combination with @code{crypt}:
3608 @deffn {Scheme Procedure} getpass prompt
3609 @deffnx {C Function} scm_getpass (prompt)
3611 Display @var{prompt} to the standard error output and read
3612 a password from @file{/dev/tty}. If this file is not
3613 accessible, it reads from standard input. The password may be
3614 up to 127 characters in length. Additional characters and the
3615 terminating newline character are discarded. While reading
3616 the password, echoing and the generation of signals by special
3617 characters is disabled.
3622 @c TeX-master: "guile.texi"