2 @chapter POSIX System Calls and Networking
5 * Conventions:: Conventions employed by the POSIX interface.
6 * Ports and File Descriptors:: Scheme ``ports'' and Unix file descriptors
7 have different representations.
8 * File System:: stat, chown, chmod, etc.
9 * User Information:: Retrieving a user's GECOS (/etc/passwd) entry.
10 * Time:: gettimeofday, localtime, strftime, etc.
11 * Runtime Environment:: Accessing and modifying Guile's environment.
12 * Processes:: getuid, getpid, etc.
13 * Signals:: sigaction, kill, pause, alarm, etc.
14 * Terminals and Ptys:: ttyname, tcsetpgrp, etc.
15 * Pipes:: Communicating data between processes.
16 * Networking:: gethostbyaddr, getnetent, socket, bind, listen.
17 * System Identification:: `uname' and getting info about this machine.
18 * Locales:: setlocale, etc.
22 @section POSIX Interface Conventions
24 These interfaces provide access to operating system facilities.
25 They provide a simple wrapping around the underlying C interfaces
26 to make usage from Scheme more convenient. They are also used
27 to implement the Guile port of @ref{The Scheme shell (scsh)}.
29 Generally there is a single procedure for each corresponding Unix
30 facility. There are some exceptions, such as procedures implemented for
31 speed and convenience in Scheme with no primitive Unix equivalent,
32 e.g., @code{copy-file}.
34 The interfaces are intended as far as possible to be portable across
35 different versions of Unix. In some cases procedures which can't be
36 implemented on particular systems may become no-ops, or perform limited
37 actions. In other cases they may throw errors.
39 General naming conventions are as follows:
43 The Scheme name is often identical to the name of the underlying Unix
46 Underscores in Unix procedure names are converted to hyphens.
48 Procedures which destructively modify Scheme data have exclaimation
49 marks appended, e.g., @code{recv!}.
51 Predicates (returning only @code{#t} or @code{#f}) have question marks
52 appended, e.g., @code{access?}.
54 Some names are changed to avoid conflict with dissimilar interfaces
55 defined by scsh, e.g., @code{primitive-fork}.
57 Unix preprocessor names such as @code{EPERM} or @code{R_OK} are converted
58 to Scheme variables of the same name (underscores are not replaced
62 Unexpected conditions are generally handled by raising exceptions.
63 There are a few procedures which return a special value if they don't
64 succeed, e.g., @code{getenv} returns @code{#f} if it the requested
65 string is not found in the environment. These cases are noted in
68 For ways to deal with exceptions, @ref{Exceptions}.
70 Errors which the C-library would report by returning a NULL
71 pointer or through some other means are reported by raising a
72 @code{system-error} exception.
73 The value of the Unix @code{errno} variable is available
74 in the data passed by the exception.
76 Here's an ad-hoc@footnote{This may be changed in the future; be prepared
77 to rewrite this sort of code.} way to extract the @code{errno} value
84 (mkdir "/this-ought-to-fail-if-I'm-not-root"))
86 (let ((errno (car (list-ref stuff 4))))
89 (display "You're not allowed to do that."))
91 (display "Already exists."))
93 (display (strerror errno))))
97 The important thing to note is that the @code{errno} value can be
98 extracted with @code{(car (list-ref stuff 4))}.
100 @node Ports and File Descriptors
101 @section Ports and File Descriptors
103 Conventions generally follow those of scsh, @ref{The Scheme shell (scsh)}.
105 File ports are implemented using low-level operating system I/O
106 facilities, with optional buffering to improve efficiency
109 Note that some procedures (e.g., @code{recv!}) will accept ports as
110 arguments, but will actually operate directly on the file descriptor
111 underlying the port. Any port buffering is ignored, including the
112 buffer which implements @code{peek-char} and @code{unread-char}.
114 The @code{force-output} and @code{drain-input} procedures can be used
115 to clear the buffers.
117 Each open file port has an associated operating system file descriptor.
118 File descriptors are generally not useful in Scheme programs; however
119 they may be needed when interfacing with foreign code and the Unix
122 A file descriptor can be extracted from a port and a new port can be
123 created from a file descriptor. However a file descriptor is just an
124 integer and the garbage collector doesn't recognise it as a reference
125 to the port. If all other references to the port were dropped, then
126 it's likely that the garbage collector would free the port, with the
127 side-effect of closing the file descriptor prematurely.
129 To assist the programmer in avoiding this problem, each port has an
130 associated "revealed count" which can be used to keep track of how many
131 times the underlying file descriptor has been stored in other places.
132 If a port's revealed count is greater than zero, the file descriptor
133 will not be closed when the port is gabage collected. A programmer
134 can therefore ensure that the revealed count will be greater than
135 zero if the file descriptor is needed elsewhere.
137 For the simple case where a file descriptor is "imported" once to become
138 a port, it does not matter if the file descriptor is closed when the
139 port is garbage collected. There is no need to maintain a revealed
140 count. Likewise when "exporting" a file descriptor to the external
141 environment, setting the revealed count is not required provided the
142 port is kept open (i.e., is pointed to by a live Scheme binding) while
143 the file descriptor is in use.
145 To correspond with traditional Unix behaviour, the three file
146 descriptors (0, 1 and 2) are automatically imported when a program
147 starts up and assigned to the initial values of the current input,
148 output and error ports. The revealed count for each is initially set to
149 one, so that dropping references to one of these ports will not result
150 in its garbage collection: it could be retrieved with fdopen or
153 @c docstring begin (texi-doc-string "guile" "port-revealed")
154 @deffn primitive port-revealed port
155 Return the revealed count for @var{port}.
158 @c docstring begin (texi-doc-string "guile" "set-port-revealed!")
159 @deffn primitive set-port-revealed! port rcount
160 Sets the revealed count for a port to a given value.
161 The return value is unspecified.
164 @c docstring begin (texi-doc-string "guile" "fileno")
165 @deffn primitive fileno port
166 Return the integer file descriptor underlying @var{port}. Does
167 not change its revealed count.
170 @deffn procedure port->fdes port
171 Returns the integer file descriptor underlying @var{port}. As a
172 side effect the revealed count of @var{port} is incremented.
175 @c docstring begin (texi-doc-string "guile" "fdopen")
176 @deffn primitive fdopen fdes modes
177 Return a new port based on the file descriptor @var{fdes}.
178 Modes are given by the string @var{modes}. The revealed count
179 of the port is initialized to zero. The modes string is the
180 same as that accepted by @ref{File Ports, open-file}.
183 @c docstring begin (texi-doc-string "guile" "fdes->ports")
184 @deffn primitive fdes->ports fd
185 Return a list of existing ports which have @var{fdes} as an
186 underlying file descriptor, without changing their revealed
190 @deffn procedure fdes->inport fdes
191 Returns an existing input port which has @var{fdes} as its underlying file
192 descriptor, if one exists, and increments its revealed count.
193 Otherwise, returns a new input port with a revealed count of 1.
196 @deffn procedure fdes->outport fdes
197 Returns an existing output port which has @var{fdes} as its underlying file
198 descriptor, if one exists, and increments its revealed count.
199 Otherwise, returns a new output port with a revealed count of 1.
202 @c docstring begin (texi-doc-string "guile" "primitive-move->fdes")
203 @deffn primitive primitive-move->fdes port fd
204 Moves the underlying file descriptor for @var{port} to the integer
205 value @var{fdes} without changing the revealed count of @var{port}.
206 Any other ports already using this descriptor will be automatically
207 shifted to new descriptors and their revealed counts reset to zero.
208 The return value is @code{#f} if the file descriptor already had the
209 required value or @code{#t} if it was moved.
212 @deffn procedure move->fdes port fdes
213 Moves the underlying file descriptor for @var{port} to the integer
214 value @var{fdes} and sets its revealed count to one. Any other ports
215 already using this descriptor will be automatically
216 shifted to new descriptors and their revealed counts reset to zero.
217 The return value is unspecified.
220 @deffn procedure release-port-handle port
221 Decrements the revealed count for a port.
224 @c docstring begin (texi-doc-string "guile" "fsync")
225 @deffn primitive fsync object
226 Copies any unwritten data for the specified output file descriptor to disk.
227 If @var{port/fd} is a port, its buffer is flushed before the underlying
228 file descriptor is fsync'd.
229 The return value is unspecified.
232 @c docstring begin (texi-doc-string "guile" "open")
233 @deffn primitive open path flags [mode]
234 Open the file named by @var{path} for reading and/or writing.
235 @var{flags} is an integer specifying how the file should be opened.
236 @var{mode} is an integer specifying the permission bits of the file, if
237 it needs to be created, before the umask is applied. The default is 666
238 (Unix itself has no default).
240 @var{flags} can be constructed by combining variables using @code{logior}.
244 Open the file read-only.
247 Open the file write-only.
250 Open the file read/write.
253 Append to the file instead of truncating.
256 Create the file if it does not already exist.
259 See the Unix documentation of the @code{open} system call
260 for additional flags.
263 @c docstring begin (texi-doc-string "guile" "open-fdes")
264 @deffn primitive open-fdes path flags [mode]
265 Similar to @code{open} but return a file descriptor instead of
269 @c docstring begin (texi-doc-string "guile" "close")
270 @deffn primitive close fd_or_port
271 Similar to close-port (@pxref{Closing, close-port}), but also works on
272 file descriptors. A side effect of closing a file descriptor is that
273 any ports using that file descriptor are moved to a different file
274 descriptor and have their revealed counts set to zero.
277 @c docstring begin (texi-doc-string "guile" "close-fdes")
278 @deffn primitive close-fdes fd
279 A simple wrapper for the @code{close} system call.
280 Close file descriptor @var{fd}, which must be an integer.
281 Unlike close (@pxref{Ports and File Descriptors, close}),
282 the file descriptor will be closed even if a port is using it.
283 The return value is unspecified.
286 @c docstring begin (texi-doc-string "guile" "unread-char")
287 @deffn primitive unread-char char [port]
288 Place @var{char} in @var{port} so that it will be read by the
289 next read operation. If called multiple times, the unread characters
290 will be read again in last-in first-out order. If @var{port} is
291 not supplied, the current input port is used.
294 @c docstring begin (texi-doc-string "guile" "unread-string")
295 @deffn primitive unread-string str port
296 Place the string @var{str} in @var{port} so that its characters will be
297 read in subsequent read operations. If called multiple times, the
298 unread characters will be read again in last-in first-out order. If
299 @var{port} is not supplied, the current-input-port is used.
302 @c docstring begin (texi-doc-string "guile" "pipe")
303 @deffn primitive pipe
304 Return a newly created pipe: a pair of ports which are linked
305 together on the local machine. The @emph{car} is the input
306 port and the @emph{cdr} is the output port. Data written (and
307 flushed) to the output port can be read from the input port.
308 Pipes are commonly used for communication with a newly forked
309 child process. The need to flush the output port can be
310 avoided by making it unbuffered using @code{setvbuf}.
311 Writes occur atomically provided the size of the data in bytes
312 is not greater than the value of @code{PIPE_BUF}. Note that
313 the output port is likely to block if too much data (typically
314 equal to @code{PIPE_BUF}) has been written but not yet read
318 The next group of procedures perform a @code{dup2}
319 system call, if @var{newfd} (an
320 integer) is supplied, otherwise a @code{dup}. The file descriptor to be
321 duplicated can be supplied as an integer or contained in a port. The
322 type of value returned varies depending on which procedure is used.
324 All procedures also have the side effect when performing @code{dup2} that any
325 ports using @var{newfd} are moved to a different file descriptor and have
326 their revealed counts set to zero.
328 @c docstring begin (texi-doc-string "guile" "dup->fdes")
329 @deffn primitive dup->fdes fd_or_port [fd]
330 Return a new integer file descriptor referring to the open file
331 designated by @var{fd_or_port}, which must be either an open
332 file port or a file descriptor.
335 @deffn procedure dup->inport port/fd [newfd]
336 Returns a new input port using the new file descriptor.
339 @deffn procedure dup->outport port/fd [newfd]
340 Returns a new output port using the new file descriptor.
343 @deffn procedure dup port/fd [newfd]
344 Returns a new port if @var{port/fd} is a port, with the same mode as the
345 supplied port, otherwise returns an integer file descriptor.
348 @deffn procedure dup->port port/fd mode [newfd]
349 Returns a new port using the new file descriptor. @var{mode} supplies a
350 mode string for the port (@pxref{File Ports, open-file}).
353 @deffn procedure duplicate-port port modes
354 Returns a new port which is opened on a duplicate of the file
355 descriptor underlying @var{port}, with mode string @var{modes}
356 as for @ref{File Ports, open-file}. The two ports
357 will share a file position and file status flags.
359 Unexpected behaviour can result if both ports are subsequently used
360 and the original and/or duplicate ports are buffered.
361 The mode string can include @code{0} to obtain an unbuffered duplicate
364 This procedure is equivalent to @code{(dup->port @var{port} @var{modes})}.
367 @c docstring begin (texi-doc-string "guile" "redirect-port")
368 @deffn primitive redirect-port old new
369 This procedure takes two ports and duplicates the underlying file
370 descriptor from @var{old-port} into @var{new-port}. The
371 current file descriptor in @var{new-port} will be closed.
372 After the redirection the two ports will share a file position
373 and file status flags.
375 The return value is unspecified.
377 Unexpected behaviour can result if both ports are subsequently used
378 and the original and/or duplicate ports are buffered.
380 This procedure does not have any side effects on other ports or
384 @c docstring begin (texi-doc-string "guile" "dup2")
385 @deffn primitive dup2 oldfd newfd
386 A simple wrapper for the @code{dup2} system call.
387 Copies the file descriptor @var{oldfd} to descriptor
388 number @var{newfd}, replacing the previous meaning
389 of @var{newfd}. Both @var{oldfd} and @var{newfd} must
391 Unlike for dup->fdes or primitive-move->fdes, no attempt
392 is made to move away ports which are using @var{newfd}.
393 The return value is unspecified.
396 @c docstring begin (texi-doc-string "guile" "port-mode")
397 @deffn primitive port-mode port
398 Return the port modes associated with the open port @var{port}.
399 These will not necessarily be identical to the modes used when
400 the port was opened, since modes such as "append" which are
401 used only during port creation are not retained.
404 @c docstring begin (texi-doc-string "guile" "close-all-ports-except")
405 @deffn primitive close-all-ports-except . ports
406 [DEPRECATED] Close all open file ports used by the interpreter
407 except for those supplied as arguments. This procedure
408 was intended to be used before an exec call to close file descriptors
409 which are not needed in the new process. However it has the
410 undesirable side-effect of flushing buffes, so it's deprecated.
411 Use port-for-each instead.
414 @c docstring begin (texi-doc-string "guile" "port-for-each")
415 @deffn primitive port-for-each proc
416 Apply @var{proc} to each port in the Guile port table
417 in turn. The return value is unspecified. More specifically,
418 @var{proc} is applied exactly once to every port that exists
419 in the system at the time @var{port-for-each} is invoked.
420 Changes to the port table while @var{port-for-each} is running
421 have no effect as far as @var{port-for-each} is concerned.
424 @c docstring begin (texi-doc-string "guile" "setvbuf")
425 @deffn primitive setvbuf port mode [size]
426 Set the buffering mode for @var{port}. @var{mode} can be:
433 block buffered, using a newly allocated buffer of @var{size} bytes.
434 If @var{size} is omitted, a default size will be used.
438 @c docstring begin (texi-doc-string "guile" "fcntl")
439 @deffn primitive fcntl object cmd [value]
440 Apply @var{command} to the specified file descriptor or the underlying
441 file descriptor of the specified port. @var{value} is an optional
444 Values for @var{command} are:
448 Duplicate a file descriptor
450 Get flags associated with the file descriptor.
452 Set flags associated with the file descriptor to @var{value}.
454 Get flags associated with the open file.
456 Set flags associated with the open file to @var{value}
458 Get the process ID of a socket's owner, for @code{SIGIO} signals.
460 Set the process that owns a socket to @var{value}, for @code{SIGIO} signals.
462 The value used to indicate the "close on exec" flag with @code{F_GETFL} or
467 @c docstring begin (texi-doc-string "guile" "select")
468 @deffn primitive select reads writes excepts [secs [usecs]]
469 This procedure has a variety of uses: waiting for the ability
470 to provide input, accept output, or the existance of
471 exceptional conditions on a collection of ports or file
472 descriptors, or waiting for a timeout to occur.
473 It also returns if interrupted by a signal.
475 @var{reads}, @var{writes} and @var{excepts} can be lists or
476 vectors, with each member a port or a file descriptor.
477 The value returned is a list of three corresponding
478 lists or vectors containing only the members which meet the
479 specified requirement. The ability of port buffers to
480 provide input or accept output is taken into account.
481 Ordering of the input lists or vectors is not preserved.
483 The optional arguments @var{secs} and @var{usecs} specify the
484 timeout. Either @var{secs} can be specified alone, as
485 either an integer or a real number, or both @var{secs} and
486 @var{usecs} can be specified as integers, in which case
487 @var{usecs} is an additional timeout expressed in
488 microseconds. If @var{secs} is omitted or is @code{#f} then
489 select will wait for as long as it takes for one of the other
490 conditions to be satisfied.
492 The scsh version of @code{select} differs as follows:
493 Only vectors are accepted for the first three arguments.
494 The @var{usecs} argument is not supported.
495 Multiple values are returned instead of a list.
496 Duplicates in the input vectors appear only once in output.
497 An additional @code{select!} interface is provided.
503 These procedures allow querying and setting file system attributes
505 permissions, sizes and types of files); deleting, copying, renaming and
506 linking files; creating and removing directories and querying their
507 contents; syncing the file system and creating special files.
509 @c docstring begin (texi-doc-string "guile" "access?")
510 @deffn primitive access? path how
511 Return @code{#t} if @var{path} corresponds to an existing file
512 and the current process has the type of access specified by
513 @var{how}, otherwise @code{#f}. @var{how} should be specified
514 using the values of the variables listed below. Multiple
515 values can be combined using a bitwise or, in which case
516 @code{#t} will only be returned if all accesses are granted.
517 Permissions are checked using the real id of the current
518 process, not the effective id, although it's the effective id
519 which determines whether the access would actually be granted.
521 test for read permission.
524 test for write permission.
527 test for execute permission.
530 test for existence of the file.
535 @c docstring begin (texi-doc-string "guile" "stat")
536 @deffn primitive stat object
537 Return an object containing various information about the file
538 determined by @var{obj}. @var{obj} can be a string containing
539 a file name or a port or integer file descriptor which is open
540 on a file (in which case @code{fstat} is used as the underlying
542 The object returned by @code{stat} can be passed as a single
543 parameter to the following procedures, all of which return
547 The device containing the file.
549 The file serial number, which distinguishes this file from all
550 other files on the same device.
552 The mode of the file. This includes file type information and
553 the file permission bits. See @code{stat:type} and
554 @code{stat:perms} below.
556 The number of hard links to the file.
558 The user ID of the file's owner.
560 The group ID of the file.
562 Device ID; this entry is defined only for character or block
565 The size of a regular file in bytes.
567 The last access time for the file.
569 The last modification time for the file.
571 The last modification time for the attributes of the file.
573 The optimal block size for reading or writing the file, in
576 The amount of disk space that the file occupies measured in
577 units of 512 byte blocks.
579 In addition, the following procedures return the information
580 from stat:mode in a more convenient form:
583 A symbol representing the type of file. Possible values are
584 regular, directory, symlink, block-special, char-special, fifo,
587 An integer representing the access permission bits.
591 @c docstring begin (texi-doc-string "guile" "lstat")
592 @deffn primitive lstat str
593 Similar to @code{stat}, but does not follow symbolic links, i.e.,
594 it will return information about a symbolic link itself, not the
595 file it points to. @var{path} must be a string.
598 @c docstring begin (texi-doc-string "guile" "readlink")
599 @deffn primitive readlink path
600 Return the value of the symbolic link named by @var{path} (a
601 string), i.e., the file that the link points to.
606 @c docstring begin (texi-doc-string "guile" "chown")
607 @deffn primitive chown object owner group
608 Change the ownership and group of the file referred to by @var{object} to
609 the integer values @var{owner} and @var{group}. @var{object} can be
610 a string containing a file name or, if the platform
611 supports fchown, a port or integer file descriptor
612 which is open on the file. The return value
615 If @var{object} is a symbolic link, either the
616 ownership of the link or the ownership of the referenced file will be
617 changed depending on the operating system (lchown is
618 unsupported at present). If @var{owner} or @var{group} is specified
619 as @code{-1}, then that ID is not changed.
623 @c docstring begin (texi-doc-string "guile" "chmod")
624 @deffn primitive chmod object mode
625 Changes the permissions of the file referred to by @var{obj}.
626 @var{obj} can be a string containing a file name or a port or integer file
627 descriptor which is open on a file (in which case @code{fchmod} is used
628 as the underlying system call).
630 the new permissions as a decimal number, e.g., @code{(chmod "foo" #o755)}.
631 The return value is unspecified.
634 @c docstring begin (texi-doc-string "guile" "utime")
635 @deffn primitive utime pathname [actime [modtime]]
636 @code{utime} sets the access and modification times for the
637 file named by @var{path}. If @var{actime} or @var{modtime} is
638 not supplied, then the current time is used. @var{actime} and
639 @var{modtime} must be integer time values as returned by the
640 @code{current-time} procedure.
642 (utime "foo" (- (current-time) 3600))
644 will set the access time to one hour in the past and the
645 modification time to the current time.
649 @c docstring begin (texi-doc-string "guile" "delete-file")
650 @deffn primitive delete-file str
651 Deletes (or "unlinks") the file specified by @var{path}.
654 @c docstring begin (texi-doc-string "guile" "copy-file")
655 @deffn primitive copy-file oldfile newfile
656 Copy the file specified by @var{path-from} to @var{path-to}.
657 The return value is unspecified.
661 @c docstring begin (texi-doc-string "guile" "rename-file")
662 @deffn primitive rename-file oldname newname
663 Renames the file specified by @var{oldname} to @var{newname}.
664 The return value is unspecified.
667 @c docstring begin (texi-doc-string "guile" "link")
668 @deffn primitive link oldpath newpath
669 Creates a new name @var{newpath} in the file system for the
670 file named by @var{oldpath}. If @var{oldpath} is a symbolic
671 link, the link may or may not be followed depending on the
675 @c docstring begin (texi-doc-string "guile" "symlink")
676 @deffn primitive symlink oldpath newpath
677 Create a symbolic link named @var{path-to} with the value (i.e., pointing to)
678 @var{path-from}. The return value is unspecified.
681 @c docstring begin (texi-doc-string "guile" "mkdir")
682 @deffn primitive mkdir path [mode]
683 Create a new directory named by @var{path}. If @var{mode} is omitted
684 then the permissions of the directory file are set using the current
685 umask. Otherwise they are set to the decimal value specified with
686 @var{mode}. The return value is unspecified.
689 @c docstring begin (texi-doc-string "guile" "rmdir")
690 @deffn primitive rmdir path
691 Remove the existing directory named by @var{path}. The directory must
692 be empty for this to succeed. The return value is unspecified.
695 @c docstring begin (texi-doc-string "guile" "opendir")
696 @deffn primitive opendir dirname
697 Open the directory specified by @var{path} and return a directory
701 @c docstring begin (texi-doc-string "guile" "directory-stream?")
702 @deffn primitive directory-stream? obj
703 Return a boolean indicating whether @var{object} is a directory
704 stream as returned by @code{opendir}.
707 @c docstring begin (texi-doc-string "guile" "readdir")
708 @deffn primitive readdir port
709 Return (as a string) the next directory entry from the directory stream
710 @var{stream}. If there is no remaining entry to be read then the
711 end of file object is returned.
714 @c docstring begin (texi-doc-string "guile" "rewinddir")
715 @deffn primitive rewinddir port
716 Reset the directory port @var{stream} so that the next call to
717 @code{readdir} will return the first directory entry.
720 @c docstring begin (texi-doc-string "guile" "closedir")
721 @deffn primitive closedir port
722 Close the directory stream @var{stream}.
723 The return value is unspecified.
726 @c docstring begin (texi-doc-string "guile" "sync")
727 @deffn primitive sync
728 Flush the operating system disk buffers.
729 The return value is unspecified.
732 @c docstring begin (texi-doc-string "guile" "mknod")
733 @deffn primitive mknod path type perms dev
734 Creates a new special file, such as a file corresponding to a device.
735 @var{path} specifies the name of the file. @var{type} should
736 be one of the following symbols:
737 regular, directory, symlink, block-special, char-special,
738 fifo, or socket. @var{perms} (an integer) specifies the file permissions.
739 @var{dev} (an integer) specifies which device the special file refers
740 to. Its exact interpretation depends on the kind of special file
745 (mknod "/dev/fd0" 'block-special #o660 (+ (* 2 256) 2))
748 The return value is unspecified.
751 @c docstring begin (texi-doc-string "guile" "tmpnam")
752 @deffn primitive tmpnam
753 Return a name in the file system that does not match any
754 existing file. However there is no guarantee that another
755 process will not create the file after @code{tmpnam} is called.
756 Care should be taken if opening the file, e.g., use the
757 @code{O_EXCL} open flag or use @code{mkstemp!} instead.
760 @c docstring begin (texi-doc-string "guile" "dirname")
761 @deffn primitive dirname filename
762 Return the directory name component of the file name
763 @var{filename}. If @var{filename} does not contain a directory
764 component, @code{.} is returned.
767 @c docstring begin (texi-doc-string "guile" "basename")
768 @deffn primitive basename filename [suffix]
769 Return the base name of the file name @var{filename}. The
770 base name is the file name without any directory components.
771 If @var{suffix} is privided, and is equal to the end of
772 @var{basename}, it is removed also.
776 @node User Information
777 @section User Information
779 The facilities in this section provide an interface to the user and
781 They should be used with care since they are not reentrant.
783 The following functions accept an object representing user information
784 and return a selected component:
788 The name of the userid.
790 The encrypted passwd.
803 @deffn procedure getpwuid uid
804 Look up an integer userid in the user database.
807 @deffn procedure getpwnam name
808 Look up a user name string in the user database.
811 @deffn procedure setpwent
812 Initializes a stream used by @code{getpwent} to read from the user database.
813 The next use of @code{getpwent} will return the first entry. The
814 return value is unspecified.
817 @deffn procedure getpwent
818 Return the next entry in the user database, using the stream set by
822 @deffn procedure endpwent
823 Closes the stream used by @code{getpwent}. The return value is unspecified.
826 @c docstring begin (texi-doc-string "guile" "setpw")
827 @deffn primitive setpw [arg]
828 If called with a true argument, initialize or reset the password data
829 stream. Otherwise, close the stream. The @code{setpwent} and
830 @code{endpwent} procedures are implemented on top of this.
833 @c docstring begin (texi-doc-string "guile" "getpw")
834 @deffn primitive getpw [user]
835 Look up an entry in the user database. @var{obj} can be an integer,
836 a string, or omitted, giving the behaviour of getpwuid, getpwnam
837 or getpwent respectively.
840 The following functions accept an object representing group information
841 and return a selected component:
847 The encrypted group password.
851 A list of userids which have this group as a supplimentary group.
854 @deffn procedure getgrgid gid
855 Look up an integer groupid in the group database.
858 @deffn procedure getgrnam name
859 Look up a group name in the group database.
862 @deffn procedure setgrent
863 Initializes a stream used by @code{getgrent} to read from the group database.
864 The next use of @code{getgrent} will return the first entry.
865 The return value is unspecified.
868 @deffn procedure getgrent
869 Return the next entry in the group database, using the stream set by
873 @deffn procedure endgrent
874 Closes the stream used by @code{getgrent}.
875 The return value is unspecified.
878 @c docstring begin (texi-doc-string "guile" "setgr")
879 @deffn primitive setgr [arg]
880 If called with a true argument, initialize or reset the group data
881 stream. Otherwise, close the stream. The @code{setgrent} and
882 @code{endgrent} procedures are implemented on top of this.
885 @c docstring begin (texi-doc-string "guile" "getgr")
886 @deffn primitive getgr [name]
887 Look up an entry in the group database. @var{obj} can be an integer,
888 a string, or omitted, giving the behaviour of getgrgid, getgrnam
889 or getgrent respectively.
895 @c docstring begin (texi-doc-string "guile" "current-time")
896 @deffn primitive current-time
897 Return the number of seconds since 1970-01-01 00:00:00 UTC,
898 excluding leap seconds.
901 @c docstring begin (texi-doc-string "guile" "gettimeofday")
902 @deffn primitive gettimeofday
903 Return a pair containing the number of seconds and microseconds
904 since 1970-01-01 00:00:00 UTC, excluding leap seconds. Note:
905 whether true microsecond resolution is available depends on the
909 The following procedures either accept an object representing a broken down
910 time and return a selected component, or accept an object representing
911 a broken down time and a value and set the component to the value.
912 The numbers in parentheses give the usual range.
915 @item tm:sec, set-tm:sec
917 @item tm:min, set-tm:min
919 @item tm:hour, set-tm:hour
921 @item tm:mday, set-tm:mday
922 Day of the month (1-31).
923 @item tm:mon, set-tm:mon
925 @item tm:year, set-tm:year
926 Year (70-), the year minus 1900.
927 @item tm:wday, set-tm:wday
928 Day of the week (0-6) with Sunday represented as 0.
929 @item tm:yday, set-tm:yday
930 Day of the year (0-364, 365 in leap years).
931 @item tm:isdst, set-tm:isdst
932 Daylight saving indicator (0 for "no", greater than 0 for "yes", less than
934 @item tm:gmtoff, set-tm:gmtoff
935 Time zone offset in seconds west of UTC (-46800 to 43200).
936 @item tm:zone, set-tm:zone
937 Time zone label (a string), not necessarily unique.
940 @c docstring begin (texi-doc-string "guile" "localtime")
941 @deffn primitive localtime time [zone]
942 Return an object representing the broken down components of
943 @var{time}, an integer like the one returned by
944 @code{current-time}. The time zone for the calculation is
945 optionally specified by @var{zone} (a string), otherwise the
946 @code{TZ} environment variable or the system default is used.
949 @c docstring begin (texi-doc-string "guile" "gmtime")
950 @deffn primitive gmtime time
951 Return an object representing the broken down components of
952 @var{time}, an integer like the one returned by
953 @code{current-time}. The values are calculated for UTC.
956 @c docstring begin (texi-doc-string "guile" "mktime")
957 @deffn primitive mktime sbd_time [zone]
958 @var{bd-time} is an object representing broken down time and @code{zone}
959 is an optional time zone specifier (otherwise the TZ environment variable
960 or the system default is used).
962 Returns a pair: the car is a corresponding
963 integer time value like that returned
964 by @code{current-time}; the cdr is a broken down time object, similar to
965 as @var{bd-time} but with normalized values.
968 @c docstring begin (texi-doc-string "guile" "tzset")
969 @deffn primitive tzset
970 Initialize the timezone from the TZ environment variable
971 or the system default. It's not usually necessary to call this procedure
972 since it's done automatically by other procedures that depend on the
976 @c docstring begin (texi-doc-string "guile" "strftime")
977 @deffn primitive strftime format stime
978 Formats a time specification @var{time} using @var{template}. @var{time}
979 is an object with time components in the form returned by @code{localtime}
980 or @code{gmtime}. @var{template} is a string which can include formatting
981 specifications introduced by a @code{%} character. The formatting of
982 month and day names is dependent on the current locale. The value returned
983 is the formatted string.
984 @xref{Formatting Date and Time, , , libc, The GNU C Library Reference Manual}.)
987 @c docstring begin (texi-doc-string "guile" "strptime")
988 @deffn primitive strptime format string
989 Performs the reverse action to @code{strftime}, parsing
990 @var{string} according to the specification supplied in
991 @var{template}. The interpretation of month and day names is
992 dependent on the current locale. The value returned is a pair.
993 The car has an object with time components
994 in the form returned by @code{localtime} or @code{gmtime},
995 but the time zone components
996 are not usefully set.
997 The cdr reports the number of characters from @var{string}
998 which were used for the conversion.
1001 @defvar internal-time-units-per-second
1002 The value of this variable is the number of time units per second
1003 reported by the following procedures.
1006 @c docstring begin (texi-doc-string "guile" "times")
1007 @deffn primitive times
1008 Return an object with information about real and processor
1009 time. The following procedures accept such an object as an
1010 argument and return a selected component:
1013 The current real time, expressed as time units relative to an
1016 The CPU time units used by the calling process.
1018 The CPU time units used by the system on behalf of the calling
1021 The CPU time units used by terminated child processes of the
1022 calling process, whose status has been collected (e.g., using
1025 Similarly, the CPU times units used by the system on behalf of
1026 terminated child processes.
1030 @c docstring begin (texi-doc-string "guile" "get-internal-real-time")
1031 @deffn primitive get-internal-real-time
1032 Return the number of time units since the interpreter was
1036 @c docstring begin (texi-doc-string "guile" "get-internal-run-time")
1037 @deffn primitive get-internal-run-time
1038 Return the number of time units of processor time used by the
1039 interpreter. Both @emph{system} and @emph{user} time are
1040 included but subprocesses are not.
1043 @node Runtime Environment
1044 @section Runtime Environment
1046 @c docstring begin (texi-doc-string "guile" "program-arguments")
1047 @deffn primitive program-arguments
1048 @deffnx procedure command-line
1049 Return the list of command line arguments passed to Guile, as a list of
1050 strings. The list includes the invoked program name, which is usually
1051 @code{"guile"}, but excludes switches and parameters for command line
1052 options like @code{-e} and @code{-l}.
1055 @c docstring begin (texi-doc-string "guile" "getenv")
1056 @deffn primitive getenv nam
1057 Looks up the string @var{name} in the current environment. The return
1058 value is @code{#f} unless a string of the form @code{NAME=VALUE} is
1059 found, in which case the string @code{VALUE} is returned.
1062 @c begin (scm-doc-string "boot-9.scm" "setenv")
1063 @deffn procedure setenv name value
1064 Modifies the environment of the current process, which is
1065 also the default environment inherited by child processes.
1067 If @var{value} is @code{#f}, then @var{name} is removed from the
1068 environment. Otherwise, the string @var{name}=@var{value} is added
1069 to the environment, replacing any existing string with name matching
1072 The return value is unspecified.
1075 @c docstring begin (texi-doc-string "guile" "environ")
1076 @deffn primitive environ [env]
1077 If @var{env} is omitted, return the current environment (in the
1078 Unix sense) as a list of strings. Otherwise set the current
1079 environment, which is also the default environment for child
1080 processes, to the supplied list of strings. Each member of
1081 @var{env} should be of the form @code{NAME=VALUE} and values of
1082 @code{NAME} should not be duplicated. If @var{env} is supplied
1083 then the return value is unspecified.
1086 @c docstring begin (texi-doc-string "guile" "putenv")
1087 @deffn primitive putenv str
1088 Modifies the environment of the current process, which is
1089 also the default environment inherited by child processes.
1091 If @var{string} is of the form @code{NAME=VALUE} then it will be written
1092 directly into the environment, replacing any existing environment string
1094 name matching @code{NAME}. If @var{string} does not contain an equal
1095 sign, then any existing string with name matching @var{string} will
1098 The return value is unspecified.
1106 @c docstring begin (texi-doc-string "guile" "chdir")
1107 @deffn primitive chdir str
1108 Change the current working directory to @var{path}.
1109 The return value is unspecified.
1113 @c docstring begin (texi-doc-string "guile" "getcwd")
1114 @deffn primitive getcwd
1115 Return the name of the current working directory.
1118 @c docstring begin (texi-doc-string "guile" "umask")
1119 @deffn primitive umask [mode]
1120 If @var{mode} is omitted, retuns a decimal number representing the current
1121 file creation mask. Otherwise the file creation mask is set to
1122 @var{mode} and the previous value is returned.
1124 E.g., @code{(umask #o022)} sets the mask to octal 22, decimal 18.
1127 @c docstring begin (texi-doc-string "guile" "getpid")
1128 @deffn primitive getpid
1129 Return an integer representing the current process ID.
1132 @c docstring begin (texi-doc-string "guile" "getgroups")
1133 @deffn primitive getgroups
1134 Return a vector of integers representing the current
1135 supplimentary group IDs.
1138 @c docstring begin (texi-doc-string "guile" "getppid")
1139 @deffn primitive getppid
1140 Return an integer representing the process ID of the parent
1144 @c docstring begin (texi-doc-string "guile" "getuid")
1145 @deffn primitive getuid
1146 Return an integer representing the current real user ID.
1149 @c docstring begin (texi-doc-string "guile" "getgid")
1150 @deffn primitive getgid
1151 Return an integer representing the current real group ID.
1154 @c docstring begin (texi-doc-string "guile" "geteuid")
1155 @deffn primitive geteuid
1156 Return an integer representing the current effective user ID.
1157 If the system does not support effective IDs, then the real ID
1158 is returned. @code{(feature? 'EIDs)} reports whether the
1159 system supports effective IDs.
1162 @c docstring begin (texi-doc-string "guile" "getegid")
1163 @deffn primitive getegid
1164 Return an integer representing the current effective group ID.
1165 If the system does not support effective IDs, then the real ID
1166 is returned. @code{(feature? 'EIDs)} reports whether the
1167 system supports effective IDs.
1170 @c docstring begin (texi-doc-string "guile" "setuid")
1171 @deffn primitive setuid id
1172 Sets both the real and effective user IDs to the integer @var{id}, provided
1173 the process has appropriate privileges.
1174 The return value is unspecified.
1177 @c docstring begin (texi-doc-string "guile" "setgid")
1178 @deffn primitive setgid id
1179 Sets both the real and effective group IDs to the integer @var{id}, provided
1180 the process has appropriate privileges.
1181 The return value is unspecified.
1184 @c docstring begin (texi-doc-string "guile" "seteuid")
1185 @deffn primitive seteuid id
1186 Sets the effective user ID to the integer @var{id}, provided the process
1187 has appropriate privileges. If effective IDs are not supported, the
1188 real ID is set instead -- @code{(feature? 'EIDs)} reports whether the
1189 system supports effective IDs.
1190 The return value is unspecified.
1193 @c docstring begin (texi-doc-string "guile" "setegid")
1194 @deffn primitive setegid id
1195 Sets the effective group ID to the integer @var{id}, provided the process
1196 has appropriate privileges. If effective IDs are not supported, the
1197 real ID is set instead -- @code{(feature? 'EIDs)} reports whether the
1198 system supports effective IDs.
1199 The return value is unspecified.
1202 @c docstring begin (texi-doc-string "guile" "getpgrp")
1203 @deffn primitive getpgrp
1204 Return an integer representing the current process group ID.
1205 This is the POSIX definition, not BSD.
1208 @c docstring begin (texi-doc-string "guile" "setpgid")
1209 @deffn primitive setpgid pid pgid
1210 Move the process @var{pid} into the process group @var{pgid}. @var{pid} or
1211 @var{pgid} must be integers: they can be zero to indicate the ID of the
1213 Fails on systems that do not support job control.
1214 The return value is unspecified.
1217 @c docstring begin (texi-doc-string "guile" "setsid")
1218 @deffn primitive setsid
1219 Creates a new session. The current process becomes the session leader
1220 and is put in a new process group. The process will be detached
1221 from its controlling terminal if it has one.
1222 The return value is an integer representing the new process group ID.
1225 @c docstring begin (texi-doc-string "guile" "waitpid")
1226 @deffn primitive waitpid pid [options]
1227 This procedure collects status information from a child process which
1228 has terminated or (optionally) stopped. Normally it will
1229 suspend the calling process until this can be done. If more than one
1230 child process is eligible then one will be chosen by the operating system.
1232 The value of @var{pid} determines the behaviour:
1235 @item @var{pid} greater than 0
1236 Request status information from the specified child process.
1237 @item @var{pid} equal to -1 or WAIT_ANY
1238 Request status information for any child process.
1239 @item @var{pid} equal to 0 or WAIT_MYPGRP
1240 Request status information for any child process in the current process
1242 @item @var{pid} less than -1
1243 Request status information for any child process whose process group ID
1247 The @var{options} argument, if supplied, should be the bitwise OR of the
1248 values of zero or more of the following variables:
1251 Return immediately even if there are no child processes to be collected.
1255 Report status information for stopped processes as well as terminated
1259 The return value is a pair containing:
1263 The process ID of the child process, or 0 if @code{WNOHANG} was
1264 specified and no process was collected.
1266 The integer status value.
1271 functions can be used to decode the process status code returned
1274 @c docstring begin (texi-doc-string "guile" "status:exit-val")
1275 @deffn primitive status:exit-val status
1276 Return the exit status value, as would be set if a process
1277 ended normally through a call to @code{exit} or @code{_exit},
1278 if any, otherwise @code{#f}.
1281 @c docstring begin (texi-doc-string "guile" "status:term-sig")
1282 @deffn primitive status:term-sig status
1283 Return the signal number which terminated the process, if any,
1284 otherwise @code{#f}.
1287 @c docstring begin (texi-doc-string "guile" "status:stop-sig")
1288 @deffn primitive status:stop-sig status
1289 Return the signal number which stopped the process, if any,
1290 otherwise @code{#f}.
1293 @c docstring begin (texi-doc-string "guile" "system")
1294 @deffn primitive system [cmd]
1295 Execute @var{cmd} using the operating system's "command
1296 processor". Under Unix this is usually the default shell
1297 @code{sh}. The value returned is @var{cmd}'s exit status as
1298 returned by @code{waitpid}, which can be interpreted using the
1300 If @code{system} is called without arguments, return a boolean
1301 indicating whether the command processor is available.
1304 @c docstring begin (texi-doc-string "guile" "primitive-exit")
1305 @deffn primitive primitive-exit [status]
1306 Terminate the current process without unwinding the Scheme stack.
1307 This is would typically be useful after a fork. The exit status
1308 is @var{status} if supplied, otherwise zero.
1311 @c docstring begin (texi-doc-string "guile" "execl")
1312 @deffn primitive execl filename . args
1313 Executes the file named by @var{path} as a new process image.
1314 The remaining arguments are supplied to the process; from a C program
1315 they are accessable as the @code{argv} argument to @code{main}.
1316 Conventionally the first @var{arg} is the same as @var{path}.
1317 All arguments must be strings.
1319 If @var{arg} is missing, @var{path} is executed with a null
1320 argument list, which may have system-dependent side-effects.
1322 This procedure is currently implemented using the @code{execv} system
1323 call, but we call it @code{execl} because of its Scheme calling interface.
1326 @c docstring begin (texi-doc-string "guile" "execlp")
1327 @deffn primitive execlp filename . args
1328 Similar to @code{execl}, however if
1329 @var{filename} does not contain a slash
1330 then the file to execute will be located by searching the
1331 directories listed in the @code{PATH} environment variable.
1333 This procedure is currently implemented using the @code{execvp} system
1334 call, but we call it @code{execlp} because of its Scheme calling interface.
1337 @c docstring begin (texi-doc-string "guile" "execle")
1338 @deffn primitive execle filename env . args
1339 Similar to @code{execl}, but the environment of the new process is
1340 specified by @var{env}, which must be a list of strings as returned by the
1341 @code{environ} procedure.
1343 This procedure is currently implemented using the @code{execve} system
1344 call, but we call it @code{execle} because of its Scheme calling interface.
1347 @c docstring begin (texi-doc-string "guile" "primitive-fork")
1348 @deffn primitive primitive-fork
1349 Creates a new "child" process by duplicating the current "parent" process.
1350 In the child the return value is 0. In the parent the return value is
1351 the integer process ID of the child.
1353 This procedure has been renamed from @code{fork} to avoid a naming conflict
1357 @c docstring begin (texi-doc-string "guile" "nice")
1358 @deffn primitive nice incr
1359 Increment the priority of the current process by @var{incr}. A higher
1360 priority value means that the process runs less often.
1361 The return value is unspecified.
1367 Procedures to raise, handle and wait for signals.
1369 @c docstring begin (texi-doc-string "guile" "kill")
1370 @deffn primitive kill pid sig
1371 Sends a signal to the specified process or group of processes.
1373 @var{pid} specifies the processes to which the signal is sent:
1376 @item @var{pid} greater than 0
1377 The process whose identifier is @var{pid}.
1378 @item @var{pid} equal to 0
1379 All processes in the current process group.
1380 @item @var{pid} less than -1
1381 The process group whose identifier is -@var{pid}
1382 @item @var{pid} equal to -1
1383 If the process is privileged, all processes except for some special
1384 system processes. Otherwise, all processes with the current effective
1388 @var{sig} should be specified using a variable corresponding to
1389 the Unix symbolic name, e.g.,
1400 @c docstring begin (texi-doc-string "guile" "raise")
1401 @deffn primitive raise sig
1402 Sends a specified signal @var{sig} to the current process, where
1403 @var{sig} is as described for the kill procedure.
1406 @c docstring begin (texi-doc-string "guile" "sigaction")
1407 @deffn primitive sigaction signum [handler [flags]]
1408 Install or report the signal handler for a specified signal.
1410 @var{signum} is the signal number, which can be specified using the value
1411 of variables such as @code{SIGINT}.
1413 If @var{action} is omitted, @code{sigaction} returns a pair: the
1415 signal hander, which will be either an integer with the value @code{SIG_DFL}
1416 (default action) or @code{SIG_IGN} (ignore), or the Scheme procedure which
1417 handles the signal, or @code{#f} if a non-Scheme procedure handles the
1418 signal. The CDR contains the current @code{sigaction} flags for the handler.
1420 If @var{action} is provided, it is installed as the new handler for
1421 @var{signum}. @var{action} can be a Scheme procedure taking one
1422 argument, or the value of @code{SIG_DFL} (default action) or
1423 @code{SIG_IGN} (ignore), or @code{#f} to restore whatever signal handler
1424 was installed before @code{sigaction} was first used. Flags can
1425 optionally be specified for the new handler (@code{SA_RESTART} will
1426 always be added if it's available and the system is using restartable
1427 system calls.) The return value is a pair with information about the
1428 old handler as described above.
1430 This interface does not provide access to the "signal blocking"
1431 facility. Maybe this is not needed, since the thread support may
1432 provide solutions to the problem of consistent access to data
1436 @c docstring begin (texi-doc-string "guile" "restore-signals")
1437 @deffn primitive restore-signals
1438 Return all signal handlers to the values they had before any call to
1439 @code{sigaction} was made. The return value is unspecified.
1442 @c docstring begin (texi-doc-string "guile" "alarm")
1443 @deffn primitive alarm i
1444 Set a timer to raise a @code{SIGALRM} signal after the specified
1445 number of seconds (an integer). It's advisable to install a signal
1447 @code{SIGALRM} beforehand, since the default action is to terminate
1450 The return value indicates the time remaining for the previous alarm,
1451 if any. The new value replaces the previous alarm. If there was
1452 no previous alarm, the return value is zero.
1455 @c docstring begin (texi-doc-string "guile" "pause")
1456 @deffn primitive pause
1457 Pause the current process (thread?) until a signal arrives whose
1458 action is to either terminate the current process or invoke a
1459 handler procedure. The return value is unspecified.
1462 @c docstring begin (texi-doc-string "guile" "sleep")
1463 @deffn primitive sleep i
1464 Wait for the given number of seconds (an integer) or until a signal
1465 arrives. The return value is zero if the time elapses or the number
1466 of seconds remaining otherwise.
1469 @c docstring begin (texi-doc-string "guile" "usleep")
1470 @deffn primitive usleep i
1471 Sleep for I microseconds. @code{usleep} is not available on
1475 @node Terminals and Ptys
1476 @section Terminals and Ptys
1478 @c docstring begin (texi-doc-string "guile" "isatty?")
1479 @deffn primitive isatty? port
1480 Return @code{#t} if @var{port} is using a serial non--file
1481 device, otherwise @code{#f}.
1484 @c docstring begin (texi-doc-string "guile" "ttyname")
1485 @deffn primitive ttyname port
1486 Return a string with the name of the serial terminal device
1487 underlying @var{port}.
1490 @c docstring begin (texi-doc-string "guile" "ctermid")
1491 @deffn primitive ctermid
1492 Return a string containing the file name of the controlling
1493 terminal for the current process.
1496 @c docstring begin (texi-doc-string "guile" "tcgetpgrp")
1497 @deffn primitive tcgetpgrp port
1498 Return the process group ID of the foreground process group
1499 associated with the terminal open on the file descriptor
1500 underlying @var{port}.
1501 If there is no foreground process group, the return value is a
1502 number greater than 1 that does not match the process group ID
1503 of any existing process group. This can happen if all of the
1504 processes in the job that was formerly the foreground job have
1505 terminated, and no other job has yet been moved into the
1509 @c docstring begin (texi-doc-string "guile" "tcsetpgrp")
1510 @deffn primitive tcsetpgrp port pgid
1511 Set the foreground process group ID for the terminal used by the file
1512 descriptor underlying @var{port} to the integer @var{pgid}.
1514 must be a member of the same session as @var{pgid} and must have the same
1515 controlling terminal. The return value is unspecified.
1521 The following procedures provide an interface to the @code{popen} and
1522 @code{pclose} system routines. The code is in a separate "popen"
1526 (use-modules (ice-9 popen))
1530 @deffn procedure open-pipe command modes
1531 Executes the shell command @var{command} (a string) in a subprocess.
1532 A pipe to the process is created and returned. @var{modes} specifies
1533 whether an input or output pipe to the process is created: it should
1534 be the value of @code{OPEN_READ} or @code{OPEN_WRITE}.
1537 @deffn procedure open-input-pipe command
1538 Equivalent to @code{open-pipe} with mode @code{OPEN_READ}.
1541 @deffn procedure open-output-pipe command
1542 Equivalent to @code{open-pipe} with mode @code{OPEN_WRITE}.
1546 @deffn procedure close-pipe port
1547 Closes the pipe created by @code{open-pipe}, then waits for the process
1548 to terminate and returns its status value, @xref{Processes, waitpid}, for
1549 information on how to interpret this value.
1551 @code{close-port} (@pxref{Closing, close-port}) can also be used to
1552 close a pipe, but doesn't return the status.
1559 * Network Databases and Address Conversion::
1560 * Network Sockets and Communication::
1563 @node Network Databases and Address Conversion
1564 @subsection Network Databases and Address Conversion
1566 This section describes procedures which convert internet addresses
1567 and query various network databases. Care should be taken when using
1568 the database routines since they are not reentrant.
1570 @subsubsection Address Conversion
1572 @c docstring begin (texi-doc-string "guile" "inet-aton")
1573 @deffn primitive inet-aton address
1574 Converts a string containing an Internet host address in the
1575 traditional dotted decimal notation into an integer.
1577 (inet-aton "127.0.0.1") @result{} 2130706433
1581 @c docstring begin (texi-doc-string "guile" "inet-ntoa")
1582 @deffn primitive inet-ntoa inetid
1583 Converts an integer Internet host address into a string with
1584 the traditional dotted decimal representation.
1586 (inet-ntoa 2130706433) @result{} "127.0.0.1"
1590 @c docstring begin (texi-doc-string "guile" "inet-netof")
1591 @deffn primitive inet-netof address
1592 Return the network number part of the given integer Internet
1595 (inet-netof 2130706433) @result{} 127
1599 @c docstring begin (texi-doc-string "guile" "inet-lnaof")
1600 @deffn primitive inet-lnaof address
1601 Return the local-address-with-network part of the given
1604 (inet-lnaof 2130706433) @result{} 1
1608 @c docstring begin (texi-doc-string "guile" "inet-makeaddr")
1609 @deffn primitive inet-makeaddr net lna
1610 Makes an Internet host address by combining the network number
1611 @var{net} with the local-address-within-network number
1614 (inet-makeaddr 127 1) @result{} 2130706433
1618 @subsubsection The Host Database
1620 A @dfn{host object} is a structure that represents what is known about a
1621 network host, and is the usual way of representing a system's network
1622 identity inside software.
1624 The following functions accept a host object and return a selected
1627 @deffn procedure hostent:name host
1628 The "official" hostname for @var{host}.
1630 @deffn procedure hostent:aliases host
1631 A list of aliases for @var{host}.
1633 @deffn procedure hostent:addrtype host
1634 The host address type. For hosts with Internet addresses, this will
1635 return @code{AF_INET}.
1637 @deffn procedure hostent:length host
1638 The length of each address for @var{host}, in bytes.
1640 @deffn procedure hostent:addr-list host
1641 The list of network addresses associated with @var{host}.
1644 The following procedures are used to search the host database:
1646 @c docstring begin (texi-doc-string "guile" "gethost")
1647 @deffn primitive gethost [host]
1648 @deffnx procedure gethostbyname hostname
1649 @deffnx procedure gethostbyaddr address
1650 Look up a host by name or address, returning a host object. The
1651 @code{gethost} procedure will accept either a string name or an integer
1652 address; if given no arguments, it behaves like @code{gethostent} (see
1653 below). If a name or address is supplied but the address can not be
1654 found, an error will be thrown to one of the keys:
1655 @code{host-not-found}, @code{try-again}, @code{no-recovery} or
1656 @code{no-data}, corresponding to the equivalent @code{h_error} values.
1657 Unusual conditions may result in errors thrown to the
1658 @code{system-error} or @code{misc_error} keys.
1661 The following procedures may be used to step through the host
1662 database from beginning to end.
1664 @deffn procedure sethostent [stayopen]
1665 Initialize an internal stream from which host objects may be read. This
1666 procedure must be called before any calls to @code{gethostent}, and may
1667 also be called afterward to reset the host entry stream. If
1668 @var{stayopen} is supplied and is not @code{#f}, the database is not
1669 closed by subsequent @code{gethostbyname} or @code{gethostbyaddr} calls,
1670 possibly giving an efficiency gain.
1673 @deffn procedure gethostent
1674 Return the next host object from the host database, or @code{#f} if
1675 there are no more hosts to be found (or an error has been encountered).
1676 This procedure may not be used before @code{sethostent} has been called.
1679 @deffn procedure endhostent
1680 Close the stream used by @code{gethostent}. The return value is unspecified.
1683 @c docstring begin (texi-doc-string "guile" "sethost")
1684 @deffn primitive sethost [stayopen]
1685 If @var{stayopen} is omitted, this is equivalent to @code{endhostent}.
1686 Otherwise it is equivalent to @code{sethostent stayopen}.
1688 @subsubsection The Network Database
1690 The following functions accept an object representing a network
1691 and return a selected component:
1693 @deffn procedure netent:name net
1694 The "official" network name.
1696 @deffn procedure netent:aliases net
1697 A list of aliases for the network.
1699 @deffn procedure netent:addrtype net
1700 The type of the network number. Currently, this returns only
1703 @deffn procedure netent:net net
1707 The following procedures are used to search the network database:
1709 @c docstring begin (texi-doc-string "guile" "getnet")
1710 @deffn primitive getnet [net]
1711 @deffnx procedure getnetbyname net-name
1712 @deffnx procedure getnetbyaddr net-number
1713 Look up a network by name or net number in the network database. The
1714 @var{net-name} argument must be a string, and the @var{net-number}
1715 argument must be an integer. @code{getnet} will accept either type of
1716 argument, behaving like @code{getnetent} (see below) if no arguments are
1720 The following procedures may be used to step through the network
1721 database from beginning to end.
1723 @deffn procedure setnetent [stayopen]
1724 Initialize an internal stream from which network objects may be read. This
1725 procedure must be called before any calls to @code{getnetent}, and may
1726 also be called afterward to reset the net entry stream. If
1727 @var{stayopen} is supplied and is not @code{#f}, the database is not
1728 closed by subsequent @code{getnetbyname} or @code{getnetbyaddr} calls,
1729 possibly giving an efficiency gain.
1732 @deffn procedure getnetent
1733 Return the next entry from the network database.
1736 @deffn procedure endnetent
1737 Close the stream used by @code{getnetent}. The return value is unspecified.
1740 @c docstring begin (texi-doc-string "guile" "setnet")
1741 @deffn primitive setnet [stayopen]
1742 If @var{stayopen} is omitted, this is equivalent to @code{endnetent}.
1743 Otherwise it is equivalent to @code{setnetent stayopen}.
1746 @subsubsection The Protocol Database
1748 The following functions accept an object representing a protocol
1749 and return a selected component:
1751 @deffn procedure protoent:name protocol
1752 The "official" protocol name.
1754 @deffn procedure protoent:aliases protocol
1755 A list of aliases for the protocol.
1757 @deffn procedure protoent:proto protocol
1758 The protocol number.
1761 The following procedures are used to search the protocol database:
1763 @c docstring begin (texi-doc-string "guile" "getproto")
1764 @deffn primitive getproto [protocol]
1765 @deffnx procedure getprotobyname name
1766 @deffnx procedure getprotobynumber number
1767 Look up a network protocol by name or by number. @code{getprotobyname}
1768 takes a string argument, and @code{getprotobynumber} takes an integer
1769 argument. @code{getproto} will accept either type, behaving like
1770 @code{getprotoent} (see below) if no arguments are supplied.
1773 The following procedures may be used to step through the protocol
1774 database from beginning to end.
1776 @deffn procedure setprotoent [stayopen]
1777 Initialize an internal stream from which protocol objects may be read. This
1778 procedure must be called before any calls to @code{getprotoent}, and may
1779 also be called afterward to reset the protocol entry stream. If
1780 @var{stayopen} is supplied and is not @code{#f}, the database is not
1781 closed by subsequent @code{getprotobyname} or @code{getprotobynumber} calls,
1782 possibly giving an efficiency gain.
1785 @deffn procedure getprotoent
1786 Return the next entry from the protocol database.
1789 @deffn procedure endprotoent
1790 Close the stream used by @code{getprotoent}. The return value is unspecified.
1793 @c docstring begin (texi-doc-string "guile" "setproto")
1794 @deffn primitive setproto [stayopen]
1795 If @var{stayopen} is omitted, this is equivalent to @code{endprotoent}.
1796 Otherwise it is equivalent to @code{setprotoent stayopen}.
1799 @subsubsection The Service Database
1801 The following functions accept an object representing a service
1802 and return a selected component:
1804 @deffn procedure servent:name serv
1805 The "official" name of the network service.
1807 @deffn procedure servent:aliases serv
1808 A list of aliases for the network service.
1810 @deffn procedure servent:port serv
1811 The Internet port used by the service.
1813 @deffn procedure servent:proto serv
1814 The protocol used by the service. A service may be listed many times
1815 in the database under different protocol names.
1818 The following procedures are used to search the service database:
1820 @c docstring begin (texi-doc-string "guile" "getserv")
1821 @deffn primitive getserv [name [protocol]]
1822 @deffnx procedure getservbyname name protocol
1823 @deffnx procedure getservbyport port protocol
1824 Look up a network service by name or by service number, and return a
1825 network service object. The @var{protocol} argument specifies the name
1826 of the desired protocol; if the protocol found in the network service
1827 database does not match this name, a system error is signalled.
1829 The @code{getserv} procedure will take either a service name or number
1830 as its first argument; if given no arguments, it behaves like
1831 @code{getservent} (see below).
1834 The following procedures may be used to step through the service
1835 database from beginning to end.
1837 @deffn procedure setservent [stayopen]
1838 Initialize an internal stream from which service objects may be read. This
1839 procedure must be called before any calls to @code{getservent}, and may
1840 also be called afterward to reset the service entry stream. If
1841 @var{stayopen} is supplied and is not @code{#f}, the database is not
1842 closed by subsequent @code{getservbyname} or @code{getservbyport} calls,
1843 possibly giving an efficiency gain.
1846 @deffn procedure getservent
1847 Return the next entry from the services database.
1850 @deffn procedure endservent
1851 Close the stream used by @code{getservent}. The return value is unspecified.
1854 @c docstring begin (texi-doc-string "guile" "setserv")
1855 @deffn primitive setserv [stayopen]
1856 If @var{stayopen} is omitted, this is equivalent to @code{endservent}.
1857 Otherwise it is equivalent to @code{setservent stayopen}.
1860 @node Network Sockets and Communication
1861 @subsection Network Sockets and Communication
1863 Socket ports can be created using @code{socket} and @code{socketpair}.
1864 The ports are initially unbuffered, to
1865 makes reading and writing to the same port more reliable.
1866 A buffer can be added to the port using @code{setvbuf},
1867 @xref{Ports and File Descriptors}.
1869 The convention used for "host" vs "network" addresses is that addresses
1870 are always held in host order at the Scheme level. The procedures in
1871 this section automatically convert between host and network order when
1872 required. The arguments and return values are thus in host order.
1874 @c docstring begin (texi-doc-string "guile" "socket")
1875 @deffn primitive socket family style proto
1876 Return a new socket port of the type specified by @var{family},
1877 @var{style} and @var{protocol}. All three parameters are
1878 integers. Typical values for @var{family} are the values of
1879 @code{AF_UNIX} and @code{AF_INET}. Typical values for
1880 @var{style} are the values of @code{SOCK_STREAM},
1881 @code{SOCK_DGRAM} and @code{SOCK_RAW}.
1882 @var{protocol} can be obtained from a protocol name using
1883 @code{getprotobyname}. A value of zero specifies the default
1884 protocol, which is usually right.
1885 A single socket port cannot by used for communication until it
1886 has been connected to another socket.
1889 @c docstring begin (texi-doc-string "guile" "socketpair")
1890 @deffn primitive socketpair family style proto
1891 Return a pair of connected (but unnamed) socket ports of the
1892 type specified by @var{family}, @var{style} and @var{protocol}.
1893 Many systems support only socket pairs of the @code{AF_UNIX}
1894 family. Zero is likely to be the only meaningful value for
1898 @c docstring begin (texi-doc-string "guile" "getsockopt")
1899 @deffn primitive getsockopt sock level optname
1900 Return the value of a particular socket option for the socket
1901 port @var{socket}. @var{level} is an integer code for type of
1902 option being requested, e.g., @code{SOL_SOCKET} for
1903 socket-level options. @var{optname} is an integer code for the
1904 option required and should be specified using one of the
1905 symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc.
1906 The returned value is typically an integer but @code{SO_LINGER}
1907 returns a pair of integers.
1910 @c docstring begin (texi-doc-string "guile" "setsockopt")
1911 @deffn primitive setsockopt sock level optname value
1912 Sets the value of a particular socket option for the socket
1913 port @var{socket}. @var{level} is an integer code for type of option
1914 being set, e.g., @code{SOL_SOCKET} for socket-level options.
1916 integer code for the option to set and should be specified using one of
1917 the symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc.
1918 @var{value} is the value to which the option should be set. For
1919 most options this must be an integer, but for @code{SO_LINGER} it must
1922 The return value is unspecified.
1925 @c docstring begin (texi-doc-string "guile" "shutdown")
1926 @deffn primitive shutdown sock how
1927 Sockets can be closed simply by using @code{close-port}. The
1928 @code{shutdown} procedure allows reception or tranmission on a
1929 connection to be shut down individually, according to the parameter
1934 Stop receiving data for this socket. If further data arrives, reject it.
1936 Stop trying to transmit data from this socket. Discard any
1937 data waiting to be sent. Stop looking for acknowledgement of
1938 data already sent; don't retransmit it if it is lost.
1940 Stop both reception and transmission.
1943 The return value is unspecified.
1946 @c docstring begin (texi-doc-string "guile" "connect")
1947 @deffn primitive connect sock fam address . args
1948 Initiates a connection from @var{socket} to the address
1949 specified by @var{address} and possibly @var{arg @dots{}}. The format
1950 required for @var{address}
1951 and @var{arg} @dots{} depends on the family of the socket.
1953 For a socket of family @code{AF_UNIX},
1954 only @code{address} is specified and must be a string with the
1955 filename where the socket is to be created.
1957 For a socket of family @code{AF_INET},
1958 @code{address} must be an integer Internet host address and @var{arg} @dots{}
1959 must be a single integer port number.
1961 The return value is unspecified.
1964 @c docstring begin (texi-doc-string "guile" "bind")
1965 @deffn primitive bind sock fam address . args
1966 Assigns an address to the socket port @var{socket}.
1967 Generally this only needs to be done for server sockets,
1968 so they know where to look for incoming connections. A socket
1969 without an address will be assigned one automatically when it
1970 starts communicating.
1972 The format of @var{address} and @var{ARG} @dots{} depends on the family
1975 For a socket of family @code{AF_UNIX}, only @var{address} is specified
1976 and must be a string with the filename where the socket is to be
1979 For a socket of family @code{AF_INET}, @var{address} must be an integer
1980 Internet host address and @var{arg} @dots{} must be a single integer
1983 The values of the following variables can also be used for @var{address}:
1986 Allow connections from any address.
1989 @defvar INADDR_LOOPBACK
1990 The address of the local host using the loopback device.
1993 @defvar INADDR_BROADCAST
1994 The broadcast address on the local network.
2001 The return value is unspecified.
2004 @c docstring begin (texi-doc-string "guile" "listen")
2005 @deffn primitive listen sock backlog
2006 This procedure enables @var{socket} to accept connection
2007 requests. @var{backlog} is an integer specifying
2008 the maximum length of the queue for pending connections.
2009 If the queue fills, new clients will fail to connect until the
2010 server calls @code{accept} to accept a connection from the queue.
2012 The return value is unspecified.
2015 @c docstring begin (texi-doc-string "guile" "accept")
2016 @deffn primitive accept sock
2017 Accepts a connection on a bound, listening socket @var{socket}. If there
2018 are no pending connections in the queue, it waits until
2019 one is available unless the non-blocking option has been set on the
2022 The return value is a
2023 pair in which the CAR is a new socket port for the connection and
2024 the CDR is an object with address information about the client which
2025 initiated the connection.
2027 If the address is not available then the CDR will be an empty vector.
2029 @var{socket} does not become part of the
2030 connection and will continue to accept new requests.
2033 The following functions take a socket address object, as returned
2034 by @code{accept} and other procedures, and return a selected component.
2038 The socket family, typically equal to the value of @code{AF_UNIX} or
2041 If the socket family is @code{AF_UNIX}, returns the path of the
2042 filename the socket is based on.
2044 If the socket family is @code{AF_INET}, returns the Internet host
2047 If the socket family is @code{AF_INET}, returns the Internet port
2051 @c docstring begin (texi-doc-string "guile" "getsockname")
2052 @deffn primitive getsockname sock
2053 Return the address of @var{socket}, in the same form as the
2054 object returned by @code{accept}. On many systems the address
2055 of a socket in the @code{AF_FILE} namespace cannot be read.
2058 @c docstring begin (texi-doc-string "guile" "getpeername")
2059 @deffn primitive getpeername sock
2060 Return the address of the socket that the socket @var{socket}
2061 is connected to, in the same form as the object returned by
2062 @code{accept}. On many systems the address of a socket in the
2063 @code{AF_FILE} namespace cannot be read.
2066 @c docstring begin (texi-doc-string "guile" "recv!")
2067 @deffn primitive recv! sock buf [flags]
2068 Receives data from the socket port @var{socket}. @var{socket} must already
2069 be bound to the address from which data is to be received.
2070 @var{buf} is a string into which
2071 the data will be written. The size of @var{buf} limits the amount of
2072 data which can be received: in the case of packet
2073 protocols, if a packet larger than this limit is encountered then some data
2074 will be irrevocably lost.
2076 The optional @var{flags} argument is a value or
2077 bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.
2079 The value returned is the number of bytes read from the socket.
2081 Note that the data is read directly from the socket file descriptor:
2082 any unread buffered port data is ignored.
2085 @c docstring begin (texi-doc-string "guile" "send")
2086 @deffn primitive send sock message [flags]
2087 Transmits the string @var{message} on the socket port @var{socket}.
2088 @var{socket} must already be bound to a destination address. The
2089 value returned is the number of bytes transmitted -- it's possible for
2090 this to be less than the length of @var{message} if the socket is
2091 set to be non-blocking. The optional @var{flags} argument is a value or
2092 bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.
2094 Note that the data is written directly to the socket file descriptor:
2095 any unflushed buffered port data is ignored.
2098 @c docstring begin (texi-doc-string "guile" "recvfrom!")
2099 @deffn primitive recvfrom! sock str [flags [start [end]]]
2100 Return data from the socket port @var{socket} and also
2101 information about where the data was received from.
2102 @var{socket} must already be bound to the address from which
2103 data is to be received. @code{str}, is a string into which the
2104 data will be written. The size of @var{str} limits the amount
2105 of data which can be received: in the case of packet protocols,
2106 if a packet larger than this limit is encountered then some
2107 data will be irrevocably lost.
2108 The optional @var{flags} argument is a value or bitwise OR of
2109 @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
2110 The value returned is a pair: the @emph{car} is the number of
2111 bytes read from the socket and the @emph{cdr} an address object
2112 in the same form as returned by @code{accept}.
2113 The @var{start} and @var{end} arguments specify a substring of
2114 @var{str} to which the data should be written.
2115 Note that the data is read directly from the socket file
2116 descriptor: any unread buffered port data is ignored.
2119 @c docstring begin (texi-doc-string "guile" "sendto")
2120 @deffn primitive sendto sock message fam address . args_and_flags
2121 Transmits the string @var{message} on the socket port @var{socket}. The
2122 destination address is specified using the @var{family}, @var{address} and
2123 @var{arg} arguments, in a similar way to the @code{connect}
2125 value returned is the number of bytes transmitted -- it's possible for
2126 this to be less than the length of @var{message} if the socket is
2127 set to be non-blocking. The optional @var{flags} argument is a value or
2128 bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.
2130 Note that the data is written directly to the socket file descriptor:
2131 any unflushed buffered port data is ignored.
2134 The following functions can be used to convert short and long integers
2135 between "host" and "network" order. Although the procedures above do
2136 this automatically for addresses, the conversion will still need to
2137 be done when sending or receiving encoded integer data from the network.
2139 @c docstring begin (texi-doc-string "guile" "htons")
2140 @deffn primitive htons in
2141 Return a new integer from @var{value} by converting from host
2142 to network order. @var{value} must be within the range of a C
2143 unsigned short integer.
2146 @c docstring begin (texi-doc-string "guile" "ntohs")
2147 @deffn primitive ntohs in
2148 Return a new integer from @var{value} by converting from
2149 network to host order. @var{value} must be within the range of
2150 a C unsigned short integer.
2153 @c docstring begin (texi-doc-string "guile" "htonl")
2154 @deffn primitive htonl in
2155 Return a new integer from @var{value} by converting from host
2156 to network order. @var{value} must be within the range of a C
2157 unsigned long integer.
2160 @c docstring begin (texi-doc-string "guile" "ntohl")
2161 @deffn primitive ntohl in
2162 Return a new integer from @var{value} by converting from
2163 network to host order. @var{value} must be within the range of
2164 a C unsigned long integer.
2167 These procedures are inconvenient to use at present, but consider:
2170 (define write-network-long
2171 (lambda (value port)
2172 (let ((v (make-uniform-vector 1 1 0)))
2173 (uniform-vector-set! v 0 (htonl value))
2174 (uniform-vector-write v port))))
2176 (define read-network-long
2178 (let ((v (make-uniform-vector 1 1 0)))
2179 (uniform-vector-read! v port)
2180 (ntohl (uniform-vector-ref v 0)))))
2183 @node System Identification
2184 @section System Identification
2186 @c docstring begin (texi-doc-string "guile" "uname")
2187 @deffn primitive uname
2188 Return an object with some information about the computer
2189 system the program is running on.
2192 The following procedures accept an object as returned by @code{uname}
2193 and return a selected component.
2196 @item utsname:sysname
2197 The name of the operating system.
2198 @item utsname:nodename
2199 The network name of the computer.
2200 @item utsname:release
2201 The current release level of the operating system implementation.
2202 @item utsname:version
2203 The current version level within the release of the operating system.
2204 @item utsname:machine
2205 A description of the hardware.
2208 @deffn primitive software-type
2209 Return a symbol describing the current platform's operating system.
2210 This may be one of AIX, VMS, UNIX, COHERENT, WINDOWS, MS-DOS, OS/2,
2211 THINKC, AMIGA, ATARIST, MACH, or ACORN.
2213 Note that most varieties of Unix are considered to be simply "UNIX".
2214 That is because when a program depends on features that are not present
2215 on every operating system, it is usually better to test for the presence
2216 or absence of that specific feature. The return value of
2217 @code{software-type} should only be used for this purpose when there is
2218 no other easy or unambiguous way of detecting such features.
2224 @c docstring begin (texi-doc-string "guile" "setlocale")
2225 @deffn primitive setlocale category [locale]
2226 If @var{locale} is omitted, return the current value of the
2227 specified locale category as a system-dependent string.
2228 @var{category} should be specified using the values
2229 @code{LC_COLLATE}, @code{LC_ALL} etc.
2230 Otherwise the specified locale category is set to the string
2231 @var{locale} and the new value is returned as a
2232 system-dependent string. If @var{locale} is an empty string,
2233 the locale will be set using envirionment variables.