Misc textual editing
[bpt/guile.git] / doc / ref / posix.texi
1 @c -*-texinfo-*-
2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2010, 2011
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
6
7 @node POSIX
8 @section @acronym{POSIX} System Calls and Networking
9 @cindex POSIX
10
11 @menu
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.
26 * Encryption::
27 @end menu
28
29 @node Conventions
30 @subsection @acronym{POSIX} Interface Conventions
31
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)}).
36
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}.
41
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.
46
47 General naming conventions are as follows:
48
49 @itemize @bullet
50 @item
51 The Scheme name is often identical to the name of the underlying Unix
52 facility.
53 @item
54 Underscores in Unix procedure names are converted to hyphens.
55 @item
56 Procedures which destructively modify Scheme data have exclamation
57 marks appended, e.g., @code{recv!}.
58 @item
59 Predicates (returning only @code{#t} or @code{#f}) have question marks
60 appended, e.g., @code{access?}.
61 @item
62 Some names are changed to avoid conflict with dissimilar interfaces
63 defined by scsh, e.g., @code{primitive-fork}.
64 @item
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
67 with hyphens).
68 @end itemize
69
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
74 the documentation.
75
76 For ways to deal with exceptions, see @ref{Exceptions}.
77
78 @cindex @code{errno}
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,
84
85 @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))
91
92 (catch 'system-error
93 (lambda () (dup2 -123 -456))
94 my-handler)
95
96 @print{}
97 system-error
98 dup2
99 Bad file descriptor
100 (9)
101 @end example
102
103
104 @sp 1
105 @defun system-error-errno arglist
106 @cindex @code{errno}
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,
110
111 @example
112 (catch
113 'system-error
114 (lambda ()
115 (mkdir "/this-ought-to-fail-if-I'm-not-root"))
116 (lambda stuff
117 (let ((errno (system-error-errno stuff)))
118 (cond
119 ((= errno EACCES)
120 (display "You're not allowed to do that."))
121 ((= errno EEXIST)
122 (display "Already exists."))
123 (#t
124 (display (strerror errno))))
125 (newline))))
126 @end example
127 @end defun
128
129
130 @node Ports and File Descriptors
131 @subsection Ports and File Descriptors
132 @cindex file descriptor
133
134 Conventions generally follow those of scsh, @ref{The Scheme shell (scsh)}.
135
136 File ports are implemented using low-level operating system I/O
137 facilities, with optional buffering to improve efficiency; see
138 @ref{File Ports}.
139
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}.
144
145 The @code{force-output} and @code{drain-input} procedures can be used
146 to clear the buffers.
147
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
151 environment.
152
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.
159
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.
167
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.
175
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}.
183
184 @deffn {Scheme Procedure} port-revealed port
185 @deffnx {C Function} scm_port_revealed (port)
186 Return the revealed count for @var{port}.
187 @end deffn
188
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.
193 @end deffn
194
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.
199 @end deffn
200
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.
204 @end deffn
205
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}).
212 @end deffn
213
214 @deffn {Scheme Procedure} fdes->ports fd
215 @deffnx {C Function} scm_fdes_to_ports (fd)
216 Return a list of existing ports which have @var{fdes} as an
217 underlying file descriptor, without changing their revealed
218 counts.
219 @end deffn
220
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.
225 @end deffn
226
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.
231 @end deffn
232
233 @deffn {Scheme Procedure} primitive-move->fdes port fd
234 @deffnx {C Function} scm_primitive_move_to_fdes (port, fd)
235 Moves the underlying file descriptor for @var{port} to the integer
236 value @var{fdes} without changing the revealed count of @var{port}.
237 Any other ports already using this descriptor will be automatically
238 shifted to new descriptors and their revealed counts reset to zero.
239 The return value is @code{#f} if the file descriptor already had the
240 required value or @code{#t} if it was moved.
241 @end deffn
242
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.
249 @end deffn
250
251 @deffn {Scheme Procedure} release-port-handle port
252 Decrements the revealed count for a port.
253 @end deffn
254
255 @deffn {Scheme Procedure} fsync object
256 @deffnx {C Function} scm_fsync (object)
257 Copies any unwritten data for the specified output file descriptor to disk.
258 If @var{port/fd} is a port, its buffer is flushed before the underlying
259 file descriptor is fsync'd.
260 The return value is unspecified.
261 @end deffn
262
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).
270
271 @var{flags} can be constructed by combining variables using @code{logior}.
272 Basic flags are:
273
274 @defvar O_RDONLY
275 Open the file read-only.
276 @end defvar
277 @defvar O_WRONLY
278 Open the file write-only.
279 @end defvar
280 @defvar O_RDWR
281 Open the file read/write.
282 @end defvar
283 @defvar O_APPEND
284 Append to the file instead of truncating.
285 @end defvar
286 @defvar O_CREAT
287 Create the file if it does not already exist.
288 @end defvar
289
290 @xref{File Status Flags,,,libc,The GNU C Library Reference Manual},
291 for additional flags.
292 @end deffn
293
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
297 a port.
298 @end deffn
299
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.
307 @end deffn
308
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.
315 @end deffn
316
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
323 used.
324 @end deffn
325
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.
331 @end deffn
332
333 @deffn {Scheme Procedure} pipe
334 @deffnx {C Function} scm_pipe ()
335 @cindex 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}.
343
344 @defvar PIPE_BUF
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}).
349 @end defvar
350
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.
354 @end deffn
355
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.
361
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.
365
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.
371 @end deffn
372
373 @deffn {Scheme Procedure} dup->inport port/fd [newfd]
374 Returns a new input port using the new file descriptor.
375 @end deffn
376
377 @deffn {Scheme Procedure} dup->outport port/fd [newfd]
378 Returns a new output port using the new file descriptor.
379 @end deffn
380
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.
384 @end deffn
385
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}).
389 @end deffn
390
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.
396
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
400 port.
401
402 This procedure is equivalent to @code{(dup->port @var{port} @var{modes})}.
403 @end deffn
404
405 @deffn {Scheme Procedure} redirect-port old new
406 @deffnx {C Function} scm_redirect_port (old, new)
407 This procedure takes two ports and duplicates the underlying file
408 descriptor from @var{old-port} into @var{new-port}. The
409 current file descriptor in @var{new-port} will be closed.
410 After the redirection the two ports will share a file position
411 and file status flags.
412
413 The return value is unspecified.
414
415 Unexpected behaviour can result if both ports are subsequently used
416 and the original and/or duplicate ports are buffered.
417
418 This procedure does not have any side effects on other ports or
419 revealed counts.
420 @end deffn
421
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
428 be integers.
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.
432 @end deffn
433
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.
439 @end deffn
440
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.
451
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}
455 cookie.
456 @end deffn
457
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:
462
463 @defvar _IONBF
464 non-buffered
465 @end defvar
466 @defvar _IOLBF
467 line buffered
468 @end defvar
469 @defvar _IOFBF
470 block buffered, using a newly allocated buffer of @var{size} bytes.
471 If @var{size} is omitted, a default size will be used.
472 @end defvar
473 @end deffn
474
475 @deffn {Scheme Procedure} fcntl port/fd cmd [value]
476 @deffnx {C Function} scm_fcntl (object, cmd, value)
477 Apply @var{cmd} on @var{port/fd}, either a port or file descriptor.
478 The @var{value} argument is used by the @code{SET} commands described
479 below, it's an integer value.
480
481 Values for @var{cmd} are:
482
483 @defvar F_DUPFD
484 Duplicate the file descriptor, the same as @code{dup->fdes} above
485 does.
486 @end defvar
487
488 @defvar F_GETFD
489 @defvarx F_SETFD
490 Get or set flags associated with the file descriptor. The only flag
491 is the following,
492
493 @defvar FD_CLOEXEC
494 ``Close on exec'', meaning the file descriptor will be closed on an
495 @code{exec} call (a successful such call). For example to set that
496 flag,
497
498 @example
499 (fcntl port F_SETFD FD_CLOEXEC)
500 @end example
501
502 Or better, set it but leave any other possible future flags unchanged,
503
504 @example
505 (fcntl port F_SETFD (logior FD_CLOEXEC
506 (fcntl port F_GETFD)))
507 @end example
508 @end defvar
509 @end defvar
510
511 @defvar F_GETFL
512 @defvarx F_SETFL
513 Get or set flags associated with the open file. These flags are
514 @code{O_RDONLY} etc described under @code{open} above.
515
516 A common use is to set @code{O_NONBLOCK} on a network socket. The
517 following sets that flag, and leaves other flags unchanged.
518
519 @example
520 (fcntl sock F_SETFL (logior O_NONBLOCK
521 (fcntl sock F_GETFL)))
522 @end example
523 @end defvar
524
525 @defvar F_GETOWN
526 @defvarx F_SETOWN
527 Get or set the process ID of a socket's owner, for @code{SIGIO} signals.
528 @end defvar
529 @end deffn
530
531 @deffn {Scheme Procedure} flock file operation
532 @deffnx {C Function} scm_flock (file, operation)
533 @cindex file locking
534 Apply or remove an advisory lock on an open file.
535 @var{operation} specifies the action to be done:
536
537 @defvar LOCK_SH
538 Shared lock. More than one process may hold a shared lock
539 for a given file at a given time.
540 @end defvar
541 @defvar LOCK_EX
542 Exclusive lock. Only one process may hold an exclusive lock
543 for a given file at a given time.
544 @end defvar
545 @defvar LOCK_UN
546 Unlock the file.
547 @end defvar
548 @defvar LOCK_NB
549 Don't block when locking. This is combined with one of the other
550 operations using @code{logior} (@pxref{Bitwise Operations}). If
551 @code{flock} would block an @code{EWOULDBLOCK} error is thrown
552 (@pxref{Conventions}).
553 @end defvar
554
555 The return value is not specified. @var{file} may be an open
556 file descriptor or an open file descriptor port.
557
558 Note that @code{flock} does not lock files across NFS.
559 @end deffn
560
561 @deffn {Scheme Procedure} select reads writes excepts [secs [usecs]]
562 @deffnx {C Function} scm_select (reads, writes, excepts, secs, usecs)
563 This procedure has a variety of uses: waiting for the ability
564 to provide input, accept output, or the existence of
565 exceptional conditions on a collection of ports or file
566 descriptors, or waiting for a timeout to occur.
567 It also returns if interrupted by a signal.
568
569 @var{reads}, @var{writes} and @var{excepts} can be lists or
570 vectors, with each member a port or a file descriptor.
571 The value returned is a list of three corresponding
572 lists or vectors containing only the members which meet the
573 specified requirement. The ability of port buffers to
574 provide input or accept output is taken into account.
575 Ordering of the input lists or vectors is not preserved.
576
577 The optional arguments @var{secs} and @var{usecs} specify the
578 timeout. Either @var{secs} can be specified alone, as
579 either an integer or a real number, or both @var{secs} and
580 @var{usecs} can be specified as integers, in which case
581 @var{usecs} is an additional timeout expressed in
582 microseconds. If @var{secs} is omitted or is @code{#f} then
583 select will wait for as long as it takes for one of the other
584 conditions to be satisfied.
585
586 The scsh version of @code{select} differs as follows:
587 Only vectors are accepted for the first three arguments.
588 The @var{usecs} argument is not supported.
589 Multiple values are returned instead of a list.
590 Duplicates in the input vectors appear only once in output.
591 An additional @code{select!} interface is provided.
592 @end deffn
593
594 @node File System
595 @subsection File System
596 @cindex file system
597
598 These procedures allow querying and setting file system attributes
599 (such as owner,
600 permissions, sizes and types of files); deleting, copying, renaming and
601 linking files; creating and removing directories and querying their
602 contents; syncing the file system and creating special files.
603
604 @deffn {Scheme Procedure} access? path how
605 @deffnx {C Function} scm_access (path, how)
606 Test accessibility of a file under the real UID and GID of the calling
607 process. The return is @code{#t} if @var{path} exists and the
608 permissions requested by @var{how} are all allowed, or @code{#f} if
609 not.
610
611 @var{how} is an integer which is one of the following values, or a
612 bitwise-OR (@code{logior}) of multiple values.
613
614 @defvar R_OK
615 Test for read permission.
616 @end defvar
617 @defvar W_OK
618 Test for write permission.
619 @end defvar
620 @defvar X_OK
621 Test for execute permission.
622 @end defvar
623 @defvar F_OK
624 Test for existence of the file. This is implied by each of the other
625 tests, so there's no need to combine it with them.
626 @end defvar
627
628 It's important to note that @code{access?} does not simply indicate
629 what will happen on attempting to read or write a file. In normal
630 circumstances it does, but in a set-UID or set-GID program it doesn't
631 because @code{access?} tests the real ID, whereas an open or execute
632 attempt uses the effective ID.
633
634 A program which will never run set-UID/GID can ignore the difference
635 between real and effective IDs, but for maximum generality, especially
636 in library functions, it's best not to use @code{access?} to predict
637 the result of an open or execute, instead simply attempt that and
638 catch any exception.
639
640 The main use for @code{access?} is to let a set-UID/GID program
641 determine what the invoking user would have been allowed to do,
642 without the greater (or perhaps lesser) privileges afforded by the
643 effective ID. For more on this, see @ref{Testing File Access,,, libc,
644 The GNU C Library Reference Manual}.
645 @end deffn
646
647 @findex fstat
648 @deffn {Scheme Procedure} stat object
649 @deffnx {C Function} scm_stat (object)
650 Return an object containing various information about the file
651 determined by @var{obj}. @var{obj} can be a string containing
652 a file name or a port or integer file descriptor which is open
653 on a file (in which case @code{fstat} is used as the underlying
654 system call).
655
656 The object returned by @code{stat} can be passed as a single
657 parameter to the following procedures, all of which return
658 integers:
659
660 @deffn {Scheme Procedure} stat:dev st
661 The device number containing the file.
662 @end deffn
663 @deffn {Scheme Procedure} stat:ino st
664 The file serial number, which distinguishes this file from all
665 other files on the same device.
666 @end deffn
667 @deffn {Scheme Procedure} stat:mode st
668 The mode of the file. This is an integer which incorporates file type
669 information and file permission bits. See also @code{stat:type} and
670 @code{stat:perms} below.
671 @end deffn
672 @deffn {Scheme Procedure} stat:nlink st
673 The number of hard links to the file.
674 @end deffn
675 @deffn {Scheme Procedure} stat:uid st
676 The user ID of the file's owner.
677 @end deffn
678 @deffn {Scheme Procedure} stat:gid st
679 The group ID of the file.
680 @end deffn
681 @deffn {Scheme Procedure} stat:rdev st
682 Device ID; this entry is defined only for character or block special
683 files. On some systems this field is not available at all, in which
684 case @code{stat:rdev} returns @code{#f}.
685 @end deffn
686 @deffn {Scheme Procedure} stat:size st
687 The size of a regular file in bytes.
688 @end deffn
689 @deffn {Scheme Procedure} stat:atime st
690 The last access time for the file, in seconds.
691 @end deffn
692 @deffn {Scheme Procedure} stat:mtime st
693 The last modification time for the file, in seconds.
694 @end deffn
695 @deffn {Scheme Procedure} stat:ctime st
696 The last modification time for the attributes of the file, in seconds.
697 @end deffn
698 @deffn {Scheme Procedure} stat:atimensec st
699 @deffnx {Scheme Procedure} stat:mtimensec st
700 @deffnx {Scheme Procedure} stat:ctimensec st
701 The fractional part of a file's access, modification, or attribute modification
702 time, in nanoseconds. Nanosecond timestamps are only available on some operating
703 systems and file systems. If Guile cannot retrieve nanosecond-level timestamps
704 for a file, these fields will be set to 0.
705 @end deffn
706 @deffn {Scheme Procedure} stat:blksize st
707 The optimal block size for reading or writing the file, in bytes. On
708 some systems this field is not available, in which case
709 @code{stat:blksize} returns a sensible suggested block size.
710 @end deffn
711 @deffn {Scheme Procedure} stat:blocks st
712 The amount of disk space that the file occupies measured in units of
713 512 byte blocks. On some systems this field is not available, in
714 which case @code{stat:blocks} returns @code{#f}.
715 @end deffn
716
717 In addition, the following procedures return the information
718 from @code{stat:mode} in a more convenient form:
719
720 @deffn {Scheme Procedure} stat:type st
721 A symbol representing the type of file. Possible values are
722 @samp{regular}, @samp{directory}, @samp{symlink},
723 @samp{block-special}, @samp{char-special}, @samp{fifo}, @samp{socket},
724 and @samp{unknown}.
725 @end deffn
726 @deffn {Scheme Procedure} stat:perms st
727 An integer representing the access permission bits.
728 @end deffn
729 @end deffn
730
731 @deffn {Scheme Procedure} lstat str
732 @deffnx {C Function} scm_lstat (str)
733 Similar to @code{stat}, but does not follow symbolic links, i.e.,
734 it will return information about a symbolic link itself, not the
735 file it points to. @var{path} must be a string.
736 @end deffn
737
738 @deffn {Scheme Procedure} readlink path
739 @deffnx {C Function} scm_readlink (path)
740 Return the value of the symbolic link named by @var{path} (a
741 string), i.e., the file that the link points to.
742 @end deffn
743
744 @findex fchown
745 @findex lchown
746 @deffn {Scheme Procedure} chown object owner group
747 @deffnx {C Function} scm_chown (object, owner, group)
748 Change the ownership and group of the file referred to by @var{object}
749 to the integer values @var{owner} and @var{group}. @var{object} can
750 be a string containing a file name or, if the platform supports
751 @code{fchown} (@pxref{File Owner,,,libc,The GNU C Library Reference
752 Manual}), a port or integer file descriptor which is open on the file.
753 The return value is unspecified.
754
755 If @var{object} is a symbolic link, either the
756 ownership of the link or the ownership of the referenced file will be
757 changed depending on the operating system (lchown is
758 unsupported at present). If @var{owner} or @var{group} is specified
759 as @code{-1}, then that ID is not changed.
760 @end deffn
761
762 @findex fchmod
763 @deffn {Scheme Procedure} chmod object mode
764 @deffnx {C Function} scm_chmod (object, mode)
765 Changes the permissions of the file referred to by @var{obj}.
766 @var{obj} can be a string containing a file name or a port or integer file
767 descriptor which is open on a file (in which case @code{fchmod} is used
768 as the underlying system call).
769 @var{mode} specifies
770 the new permissions as a decimal number, e.g., @code{(chmod "foo" #o755)}.
771 The return value is unspecified.
772 @end deffn
773
774 @deffn {Scheme Procedure} utime pathname [actime [modtime [actimens [modtimens [flags]]]]]
775 @deffnx {C Function} scm_utime (pathname, actime, modtime, actimens, modtimens, flags)
776 @code{utime} sets the access and modification times for the
777 file named by @var{path}. If @var{actime} or @var{modtime} is
778 not supplied, then the current time is used. @var{actime} and
779 @var{modtime} must be integer time values as returned by the
780 @code{current-time} procedure.
781
782 The optional @var{actimens} and @var{modtimens} are nanoseconds
783 to add @var{actime} and @var{modtime}. Nanosecond precision is
784 only supported on some combinations of file systems and operating
785 systems.
786 @lisp
787 (utime "foo" (- (current-time) 3600))
788 @end lisp
789 will set the access time to one hour in the past and the
790 modification time to the current time.
791 @end deffn
792
793 @findex unlink
794 @deffn {Scheme Procedure} delete-file str
795 @deffnx {C Function} scm_delete_file (str)
796 Deletes (or ``unlinks'') the file whose path is specified by
797 @var{str}.
798 @end deffn
799
800 @deffn {Scheme Procedure} copy-file oldfile newfile
801 @deffnx {C Function} scm_copy_file (oldfile, newfile)
802 Copy the file specified by @var{oldfile} to @var{newfile}.
803 The return value is unspecified.
804 @end deffn
805
806 @findex rename
807 @deffn {Scheme Procedure} rename-file oldname newname
808 @deffnx {C Function} scm_rename (oldname, newname)
809 Renames the file specified by @var{oldname} to @var{newname}.
810 The return value is unspecified.
811 @end deffn
812
813 @deffn {Scheme Procedure} link oldpath newpath
814 @deffnx {C Function} scm_link (oldpath, newpath)
815 Creates a new name @var{newpath} in the file system for the
816 file named by @var{oldpath}. If @var{oldpath} is a symbolic
817 link, the link may or may not be followed depending on the
818 system.
819 @end deffn
820
821 @deffn {Scheme Procedure} symlink oldpath newpath
822 @deffnx {C Function} scm_symlink (oldpath, newpath)
823 Create a symbolic link named @var{newpath} with the value (i.e., pointing to)
824 @var{oldpath}. The return value is unspecified.
825 @end deffn
826
827 @deffn {Scheme Procedure} mkdir path [mode]
828 @deffnx {C Function} scm_mkdir (path, mode)
829 Create a new directory named by @var{path}. If @var{mode} is omitted
830 then the permissions of the directory file are set using the current
831 umask (@pxref{Processes}). Otherwise they are set to the decimal
832 value specified with @var{mode}. The return value is unspecified.
833 @end deffn
834
835 @deffn {Scheme Procedure} rmdir path
836 @deffnx {C Function} scm_rmdir (path)
837 Remove the existing directory named by @var{path}. The directory must
838 be empty for this to succeed. The return value is unspecified.
839 @end deffn
840
841 @deffn {Scheme Procedure} opendir dirname
842 @deffnx {C Function} scm_opendir (dirname)
843 @cindex directory contents
844 Open the directory specified by @var{dirname} and return a directory
845 stream.
846 @end deffn
847
848 @deffn {Scheme Procedure} directory-stream? object
849 @deffnx {C Function} scm_directory_stream_p (object)
850 Return a boolean indicating whether @var{object} is a directory
851 stream as returned by @code{opendir}.
852 @end deffn
853
854 @deffn {Scheme Procedure} readdir stream
855 @deffnx {C Function} scm_readdir (stream)
856 Return (as a string) the next directory entry from the directory stream
857 @var{stream}. If there is no remaining entry to be read then the
858 end of file object is returned.
859 @end deffn
860
861 @deffn {Scheme Procedure} rewinddir stream
862 @deffnx {C Function} scm_rewinddir (stream)
863 Reset the directory port @var{stream} so that the next call to
864 @code{readdir} will return the first directory entry.
865 @end deffn
866
867 @deffn {Scheme Procedure} closedir stream
868 @deffnx {C Function} scm_closedir (stream)
869 Close the directory stream @var{stream}.
870 The return value is unspecified.
871 @end deffn
872
873 Here is an example showing how to display all the entries in a
874 directory:
875
876 @lisp
877 (define dir (opendir "/usr/lib"))
878 (do ((entry (readdir dir) (readdir dir)))
879 ((eof-object? entry))
880 (display entry)(newline))
881 (closedir dir)
882 @end lisp
883
884 @deffn {Scheme Procedure} sync
885 @deffnx {C Function} scm_sync ()
886 Flush the operating system disk buffers.
887 The return value is unspecified.
888 @end deffn
889
890 @deffn {Scheme Procedure} mknod path type perms dev
891 @deffnx {C Function} scm_mknod (path, type, perms, dev)
892 @cindex device file
893 Creates a new special file, such as a file corresponding to a device.
894 @var{path} specifies the name of the file. @var{type} should be one
895 of the following symbols: @samp{regular}, @samp{directory},
896 @samp{symlink}, @samp{block-special}, @samp{char-special},
897 @samp{fifo}, or @samp{socket}. @var{perms} (an integer) specifies the
898 file permissions. @var{dev} (an integer) specifies which device the
899 special file refers to. Its exact interpretation depends on the kind
900 of special file being created.
901
902 E.g.,
903 @lisp
904 (mknod "/dev/fd0" 'block-special #o660 (+ (* 2 256) 2))
905 @end lisp
906
907 The return value is unspecified.
908 @end deffn
909
910 @deffn {Scheme Procedure} tmpnam
911 @deffnx {C Function} scm_tmpnam ()
912 @cindex temporary file
913 Return an auto-generated name of a temporary file, a file which
914 doesn't already exist. The name includes a path, it's usually in
915 @file{/tmp} but that's system dependent.
916
917 Care must be taken when using @code{tmpnam}. In between choosing the
918 name and creating the file another program might use that name, or an
919 attacker might even make it a symlink pointing at something important
920 and causing you to overwrite that.
921
922 The safe way is to create the file using @code{open} with
923 @code{O_EXCL} to avoid any overwriting. A loop can try again with
924 another name if the file exists (error @code{EEXIST}).
925 @code{mkstemp!} below does that.
926 @end deffn
927
928 @deffn {Scheme Procedure} mkstemp! tmpl
929 @deffnx {C Function} scm_mkstemp (tmpl)
930 @cindex temporary file
931 Create a new unique file in the file system and return a new buffered
932 port open for reading and writing to the file.
933
934 @var{tmpl} is a string specifying where the file should be created: it
935 must end with @samp{XXXXXX} and those @samp{X}s will be changed in the
936 string to return the name of the file. (@code{port-filename} on the
937 port also gives the name.)
938
939 POSIX doesn't specify the permissions mode of the file, on GNU and
940 most systems it's @code{#o600}. An application can use @code{chmod}
941 to relax that if desired. For example @code{#o666} less @code{umask},
942 which is usual for ordinary file creation,
943
944 @example
945 (let ((port (mkstemp! (string-copy "/tmp/myfile-XXXXXX"))))
946 (chmod port (logand #o666 (lognot (umask))))
947 ...)
948 @end example
949 @end deffn
950
951 @deffn {Scheme Procedure} tmpfile
952 @deffnx {C Function} scm_tmpfile
953 Return an input/output port to a unique temporary file
954 named using the path prefix @code{P_tmpdir} defined in
955 @file{stdio.h}.
956 The file is automatically deleted when the port is closed
957 or the program terminates.
958 @end deffn
959
960 @deffn {Scheme Procedure} dirname filename
961 @deffnx {C Function} scm_dirname (filename)
962 Return the directory name component of the file name
963 @var{filename}. If @var{filename} does not contain a directory
964 component, @code{.} is returned.
965 @end deffn
966
967 @deffn {Scheme Procedure} basename filename [suffix]
968 @deffnx {C Function} scm_basename (filename, suffix)
969 Return the base name of the file name @var{filename}. The
970 base name is the file name without any directory components.
971 If @var{suffix} is provided, and is equal to the end of
972 @var{basename}, it is removed also.
973
974 @lisp
975 (basename "/tmp/test.xml" ".xml")
976 @result{} "test"
977 @end lisp
978 @end deffn
979
980 @deffn {Scheme Procedure} file-exists? filename
981 Return @code{#t} if the file named @var{filename} exists, @code{#f} if
982 not.
983 @end deffn
984
985
986 @node User Information
987 @subsection User Information
988 @cindex user information
989 @cindex password file
990 @cindex group file
991
992 The facilities in this section provide an interface to the user and
993 group database.
994 They should be used with care since they are not reentrant.
995
996 The following functions accept an object representing user information
997 and return a selected component:
998
999 @deffn {Scheme Procedure} passwd:name pw
1000 The name of the userid.
1001 @end deffn
1002 @deffn {Scheme Procedure} passwd:passwd pw
1003 The encrypted passwd.
1004 @end deffn
1005 @deffn {Scheme Procedure} passwd:uid pw
1006 The user id number.
1007 @end deffn
1008 @deffn {Scheme Procedure} passwd:gid pw
1009 The group id number.
1010 @end deffn
1011 @deffn {Scheme Procedure} passwd:gecos pw
1012 The full name.
1013 @end deffn
1014 @deffn {Scheme Procedure} passwd:dir pw
1015 The home directory.
1016 @end deffn
1017 @deffn {Scheme Procedure} passwd:shell pw
1018 The login shell.
1019 @end deffn
1020 @sp 1
1021
1022 @deffn {Scheme Procedure} getpwuid uid
1023 Look up an integer userid in the user database.
1024 @end deffn
1025
1026 @deffn {Scheme Procedure} getpwnam name
1027 Look up a user name string in the user database.
1028 @end deffn
1029
1030 @deffn {Scheme Procedure} setpwent
1031 Initializes a stream used by @code{getpwent} to read from the user database.
1032 The next use of @code{getpwent} will return the first entry. The
1033 return value is unspecified.
1034 @end deffn
1035
1036 @deffn {Scheme Procedure} getpwent
1037 Read the next entry in the user database stream. The return is a
1038 passwd user object as above, or @code{#f} when no more entries.
1039 @end deffn
1040
1041 @deffn {Scheme Procedure} endpwent
1042 Closes the stream used by @code{getpwent}. The return value is unspecified.
1043 @end deffn
1044
1045 @deffn {Scheme Procedure} setpw [arg]
1046 @deffnx {C Function} scm_setpwent (arg)
1047 If called with a true argument, initialize or reset the password data
1048 stream. Otherwise, close the stream. The @code{setpwent} and
1049 @code{endpwent} procedures are implemented on top of this.
1050 @end deffn
1051
1052 @deffn {Scheme Procedure} getpw [user]
1053 @deffnx {C Function} scm_getpwuid (user)
1054 Look up an entry in the user database. @var{obj} can be an integer,
1055 a string, or omitted, giving the behaviour of getpwuid, getpwnam
1056 or getpwent respectively.
1057 @end deffn
1058
1059 The following functions accept an object representing group information
1060 and return a selected component:
1061
1062 @deffn {Scheme Procedure} group:name gr
1063 The group name.
1064 @end deffn
1065 @deffn {Scheme Procedure} group:passwd gr
1066 The encrypted group password.
1067 @end deffn
1068 @deffn {Scheme Procedure} group:gid gr
1069 The group id number.
1070 @end deffn
1071 @deffn {Scheme Procedure} group:mem gr
1072 A list of userids which have this group as a supplementary group.
1073 @end deffn
1074 @sp 1
1075
1076 @deffn {Scheme Procedure} getgrgid gid
1077 Look up an integer group id in the group database.
1078 @end deffn
1079
1080 @deffn {Scheme Procedure} getgrnam name
1081 Look up a group name in the group database.
1082 @end deffn
1083
1084 @deffn {Scheme Procedure} setgrent
1085 Initializes a stream used by @code{getgrent} to read from the group database.
1086 The next use of @code{getgrent} will return the first entry.
1087 The return value is unspecified.
1088 @end deffn
1089
1090 @deffn {Scheme Procedure} getgrent
1091 Return the next entry in the group database, using the stream set by
1092 @code{setgrent}.
1093 @end deffn
1094
1095 @deffn {Scheme Procedure} endgrent
1096 Closes the stream used by @code{getgrent}.
1097 The return value is unspecified.
1098 @end deffn
1099
1100 @deffn {Scheme Procedure} setgr [arg]
1101 @deffnx {C Function} scm_setgrent (arg)
1102 If called with a true argument, initialize or reset the group data
1103 stream. Otherwise, close the stream. The @code{setgrent} and
1104 @code{endgrent} procedures are implemented on top of this.
1105 @end deffn
1106
1107 @deffn {Scheme Procedure} getgr [name]
1108 @deffnx {C Function} scm_getgrgid (name)
1109 Look up an entry in the group database. @var{obj} can be an integer,
1110 a string, or omitted, giving the behaviour of getgrgid, getgrnam
1111 or getgrent respectively.
1112 @end deffn
1113
1114 In addition to the accessor procedures for the user database, the
1115 following shortcut procedure is also available.
1116
1117 @deffn {Scheme Procedure} getlogin
1118 @deffnx {C Function} scm_getlogin ()
1119 Return a string containing the name of the user logged in on
1120 the controlling terminal of the process, or @code{#f} if this
1121 information cannot be obtained.
1122 @end deffn
1123
1124
1125 @node Time
1126 @subsection Time
1127 @cindex time
1128
1129 @deffn {Scheme Procedure} current-time
1130 @deffnx {C Function} scm_current_time ()
1131 Return the number of seconds since 1970-01-01 00:00:00 @acronym{UTC},
1132 excluding leap seconds.
1133 @end deffn
1134
1135 @deffn {Scheme Procedure} gettimeofday
1136 @deffnx {C Function} scm_gettimeofday ()
1137 Return a pair containing the number of seconds and microseconds
1138 since 1970-01-01 00:00:00 @acronym{UTC}, excluding leap seconds. Note:
1139 whether true microsecond resolution is available depends on the
1140 operating system.
1141 @end deffn
1142
1143 The following procedures either accept an object representing a broken down
1144 time and return a selected component, or accept an object representing
1145 a broken down time and a value and set the component to the value.
1146 The numbers in parentheses give the usual range.
1147
1148 @deffn {Scheme Procedure} tm:sec tm
1149 @deffnx {Scheme Procedure} set-tm:sec tm val
1150 Seconds (0-59).
1151 @end deffn
1152 @deffn {Scheme Procedure} tm:min tm
1153 @deffnx {Scheme Procedure} set-tm:min tm val
1154 Minutes (0-59).
1155 @end deffn
1156 @deffn {Scheme Procedure} tm:hour tm
1157 @deffnx {Scheme Procedure} set-tm:hour tm val
1158 Hours (0-23).
1159 @end deffn
1160 @deffn {Scheme Procedure} tm:mday tm
1161 @deffnx {Scheme Procedure} set-tm:mday tm val
1162 Day of the month (1-31).
1163 @end deffn
1164 @deffn {Scheme Procedure} tm:mon tm
1165 @deffnx {Scheme Procedure} set-tm:mon tm val
1166 Month (0-11).
1167 @end deffn
1168 @deffn {Scheme Procedure} tm:year tm
1169 @deffnx {Scheme Procedure} set-tm:year tm val
1170 Year (70-), the year minus 1900.
1171 @end deffn
1172 @deffn {Scheme Procedure} tm:wday tm
1173 @deffnx {Scheme Procedure} set-tm:wday tm val
1174 Day of the week (0-6) with Sunday represented as 0.
1175 @end deffn
1176 @deffn {Scheme Procedure} tm:yday tm
1177 @deffnx {Scheme Procedure} set-tm:yday tm val
1178 Day of the year (0-364, 365 in leap years).
1179 @end deffn
1180 @deffn {Scheme Procedure} tm:isdst tm
1181 @deffnx {Scheme Procedure} set-tm:isdst tm val
1182 Daylight saving indicator (0 for ``no'', greater than 0 for ``yes'', less than
1183 0 for ``unknown'').
1184 @end deffn
1185 @deffn {Scheme Procedure} tm:gmtoff tm
1186 @deffnx {Scheme Procedure} set-tm:gmtoff tm val
1187 Time zone offset in seconds west of @acronym{UTC} (-46800 to 43200).
1188 For example on East coast USA (zone @samp{EST+5}) this would be 18000
1189 (ie.@: @m{5\times60\times60,5*60*60}) in winter, or 14400
1190 (ie.@: @m{4\times60\times60,4*60*60}) during daylight savings.
1191
1192 Note @code{tm:gmtoff} is not the same as @code{tm_gmtoff} in the C
1193 @code{tm} structure. @code{tm_gmtoff} is seconds east and hence the
1194 negative of the value here.
1195 @end deffn
1196 @deffn {Scheme Procedure} tm:zone tm
1197 @deffnx {Scheme Procedure} set-tm:zone tm val
1198 Time zone label (a string), not necessarily unique.
1199 @end deffn
1200 @sp 1
1201
1202 @deffn {Scheme Procedure} localtime time [zone]
1203 @deffnx {C Function} scm_localtime (time, zone)
1204 @cindex local time
1205 Return an object representing the broken down components of
1206 @var{time}, an integer like the one returned by
1207 @code{current-time}. The time zone for the calculation is
1208 optionally specified by @var{zone} (a string), otherwise the
1209 @env{TZ} environment variable or the system default is used.
1210 @end deffn
1211
1212 @deffn {Scheme Procedure} gmtime time
1213 @deffnx {C Function} scm_gmtime (time)
1214 Return an object representing the broken down components of
1215 @var{time}, an integer like the one returned by
1216 @code{current-time}. The values are calculated for @acronym{UTC}.
1217 @end deffn
1218
1219 @deffn {Scheme Procedure} mktime sbd-time [zone]
1220 @deffnx {C Function} scm_mktime (sbd_time, zone)
1221 For a broken down time object @var{sbd-time}, return a pair the
1222 @code{car} of which is an integer time like @code{current-time}, and
1223 the @code{cdr} of which is a new broken down time with normalized
1224 fields.
1225
1226 @var{zone} is a timezone string, or the default is the @env{TZ}
1227 environment variable or the system default (@pxref{TZ Variable,,
1228 Specifying the Time Zone with @env{TZ}, libc, GNU C Library Reference
1229 Manual}). @var{sbd-time} is taken to be in that @var{zone}.
1230
1231 The following fields of @var{sbd-time} are used: @code{tm:year},
1232 @code{tm:mon}, @code{tm:mday}, @code{tm:hour}, @code{tm:min},
1233 @code{tm:sec}, @code{tm:isdst}. The values can be outside their usual
1234 ranges. For example @code{tm:hour} normally goes up to 23, but a
1235 value say 33 would mean 9 the following day.
1236
1237 @code{tm:isdst} in @var{sbd-time} says whether the time given is with
1238 daylight savings or not. This is ignored if @var{zone} doesn't have
1239 any daylight savings adjustment amount.
1240
1241 The broken down time in the return normalizes the values of
1242 @var{sbd-time} by bringing them into their usual ranges, and using the
1243 actual daylight savings rule for that time in @var{zone} (which may
1244 differ from what @var{sbd-time} had). The easiest way to think of
1245 this is that @var{sbd-time} plus @var{zone} converts to the integer
1246 UTC time, then a @code{localtime} is applied to get the normal
1247 presentation of that time, in @var{zone}.
1248 @end deffn
1249
1250 @deffn {Scheme Procedure} tzset
1251 @deffnx {C Function} scm_tzset ()
1252 Initialize the timezone from the @env{TZ} environment variable
1253 or the system default. It's not usually necessary to call this procedure
1254 since it's done automatically by other procedures that depend on the
1255 timezone.
1256 @end deffn
1257
1258 @deffn {Scheme Procedure} strftime format tm
1259 @deffnx {C Function} scm_strftime (format, tm)
1260 @cindex time formatting
1261 Return a string which is broken-down time structure @var{tm} formatted
1262 according to the given @var{format} string.
1263
1264 @var{format} contains field specifications introduced by a @samp{%}
1265 character. See @ref{Formatting Calendar Time,,, libc, The GNU C
1266 Library Reference Manual}, or @samp{man 3 strftime}, for the available
1267 formatting.
1268
1269 @lisp
1270 (strftime "%c" (localtime (current-time)))
1271 @result{} "Mon Mar 11 20:17:43 2002"
1272 @end lisp
1273
1274 If @code{setlocale} has been called (@pxref{Locales}), month and day
1275 names are from the current locale and in the locale character set.
1276 @end deffn
1277
1278 @deffn {Scheme Procedure} strptime format string
1279 @deffnx {C Function} scm_strptime (format, string)
1280 @cindex time parsing
1281 Performs the reverse action to @code{strftime}, parsing
1282 @var{string} according to the specification supplied in
1283 @var{template}. The interpretation of month and day names is
1284 dependent on the current locale. The value returned is a pair.
1285 The @acronym{CAR} has an object with time components
1286 in the form returned by @code{localtime} or @code{gmtime},
1287 but the time zone components
1288 are not usefully set.
1289 The @acronym{CDR} reports the number of characters from @var{string}
1290 which were used for the conversion.
1291 @end deffn
1292
1293 @defvar internal-time-units-per-second
1294 The value of this variable is the number of time units per second
1295 reported by the following procedures.
1296 @end defvar
1297
1298 @deffn {Scheme Procedure} times
1299 @deffnx {C Function} scm_times ()
1300 Return an object with information about real and processor
1301 time. The following procedures accept such an object as an
1302 argument and return a selected component:
1303
1304 @deffn {Scheme Procedure} tms:clock tms
1305 The current real time, expressed as time units relative to an
1306 arbitrary base.
1307 @end deffn
1308 @deffn {Scheme Procedure} tms:utime tms
1309 The CPU time units used by the calling process.
1310 @end deffn
1311 @deffn {Scheme Procedure} tms:stime tms
1312 The CPU time units used by the system on behalf of the calling
1313 process.
1314 @end deffn
1315 @deffn {Scheme Procedure} tms:cutime tms
1316 The CPU time units used by terminated child processes of the
1317 calling process, whose status has been collected (e.g., using
1318 @code{waitpid}).
1319 @end deffn
1320 @deffn {Scheme Procedure} tms:cstime tms
1321 Similarly, the CPU times units used by the system on behalf of
1322 terminated child processes.
1323 @end deffn
1324 @end deffn
1325
1326 @deffn {Scheme Procedure} get-internal-real-time
1327 @deffnx {C Function} scm_get_internal_real_time ()
1328 Return the number of time units since the interpreter was
1329 started.
1330 @end deffn
1331
1332 @deffn {Scheme Procedure} get-internal-run-time
1333 @deffnx {C Function} scm_get_internal_run_time ()
1334 Return the number of time units of processor time used by the
1335 interpreter. Both @emph{system} and @emph{user} time are
1336 included but subprocesses are not.
1337 @end deffn
1338
1339 @node Runtime Environment
1340 @subsection Runtime Environment
1341
1342 @deffn {Scheme Procedure} program-arguments
1343 @deffnx {Scheme Procedure} command-line
1344 @deffnx {Scheme Procedure} set-program-arguments
1345 @deffnx {C Function} scm_program_arguments ()
1346 @deffnx {C Function} scm_set_program_arguments_scm (lst)
1347 @cindex command line
1348 @cindex program arguments
1349 Get the command line arguments passed to Guile, or set new arguments.
1350
1351 The arguments are a list of strings, the first of which is the invoked
1352 program name. This is just @nicode{"guile"} (or the executable path)
1353 when run interactively, or it's the script name when running a script
1354 with @option{-s} (@pxref{Invoking Guile}).
1355
1356 @example
1357 guile -L /my/extra/dir -s foo.scm abc def
1358
1359 (program-arguments) @result{} ("foo.scm" "abc" "def")
1360 @end example
1361
1362 @code{set-program-arguments} allows a library module or similar to
1363 modify the arguments, for example to strip options it recognises,
1364 leaving the rest for the mainline.
1365
1366 The argument list is held in a fluid, which means it's separate for
1367 each thread. Neither the list nor the strings within it are copied at
1368 any point and normally should not be mutated.
1369
1370 The two names @code{program-arguments} and @code{command-line} are an
1371 historical accident, they both do exactly the same thing. The name
1372 @code{scm_set_program_arguments_scm} has an extra @code{_scm} on the
1373 end to avoid clashing with the C function below.
1374 @end deffn
1375
1376 @deftypefn {C Function} void scm_set_program_arguments (int argc, char **argv, char *first)
1377 @cindex command line
1378 @cindex program arguments
1379 Set the list of command line arguments for @code{program-arguments}
1380 and @code{command-line} above.
1381
1382 @var{argv} is an array of null-terminated strings, as in a C
1383 @code{main} function. @var{argc} is the number of strings in
1384 @var{argv}, or if it's negative then a @code{NULL} in @var{argv} marks
1385 its end.
1386
1387 @var{first} is an extra string put at the start of the arguments, or
1388 @code{NULL} for no such extra. This is a convenient way to pass the
1389 program name after advancing @var{argv} to strip option arguments.
1390 Eg.@:
1391
1392 @example
1393 @{
1394 char *progname = argv[0];
1395 for (argv++; argv[0] != NULL && argv[0][0] == '-'; argv++)
1396 @{
1397 /* munch option ... */
1398 @}
1399 /* remaining args for scheme level use */
1400 scm_set_program_arguments (-1, argv, progname);
1401 @}
1402 @end example
1403
1404 This sort of thing is often done at startup under
1405 @code{scm_boot_guile} with options handled at the C level removed.
1406 The given strings are all copied, so the C data is not accessed again
1407 once @code{scm_set_program_arguments} returns.
1408 @end deftypefn
1409
1410 @deffn {Scheme Procedure} getenv nam
1411 @deffnx {C Function} scm_getenv (nam)
1412 @cindex environment
1413 Looks up the string @var{name} in the current environment. The return
1414 value is @code{#f} unless a string of the form @code{NAME=VALUE} is
1415 found, in which case the string @code{VALUE} is returned.
1416 @end deffn
1417
1418 @deffn {Scheme Procedure} setenv name value
1419 Modifies the environment of the current process, which is
1420 also the default environment inherited by child processes.
1421
1422 If @var{value} is @code{#f}, then @var{name} is removed from the
1423 environment. Otherwise, the string @var{name}=@var{value} is added
1424 to the environment, replacing any existing string with name matching
1425 @var{name}.
1426
1427 The return value is unspecified.
1428 @end deffn
1429
1430 @deffn {Scheme Procedure} unsetenv name
1431 Remove variable @var{name} from the environment. The
1432 name can not contain a @samp{=} character.
1433 @end deffn
1434
1435 @deffn {Scheme Procedure} environ [env]
1436 @deffnx {C Function} scm_environ (env)
1437 If @var{env} is omitted, return the current environment (in the
1438 Unix sense) as a list of strings. Otherwise set the current
1439 environment, which is also the default environment for child
1440 processes, to the supplied list of strings. Each member of
1441 @var{env} should be of the form @var{NAME}=@var{VALUE} and values of
1442 @var{NAME} should not be duplicated. If @var{env} is supplied
1443 then the return value is unspecified.
1444 @end deffn
1445
1446 @deffn {Scheme Procedure} putenv str
1447 @deffnx {C Function} scm_putenv (str)
1448 Modifies the environment of the current process, which is
1449 also the default environment inherited by child processes.
1450
1451 If @var{string} is of the form @code{NAME=VALUE} then it will be written
1452 directly into the environment, replacing any existing environment string
1453 with
1454 name matching @code{NAME}. If @var{string} does not contain an equal
1455 sign, then any existing string with name matching @var{string} will
1456 be removed.
1457
1458 The return value is unspecified.
1459 @end deffn
1460
1461
1462 @node Processes
1463 @subsection Processes
1464 @cindex processes
1465 @cindex child processes
1466
1467 @findex cd
1468 @deffn {Scheme Procedure} chdir str
1469 @deffnx {C Function} scm_chdir (str)
1470 @cindex current directory
1471 Change the current working directory to @var{path}.
1472 The return value is unspecified.
1473 @end deffn
1474
1475 @findex pwd
1476 @deffn {Scheme Procedure} getcwd
1477 @deffnx {C Function} scm_getcwd ()
1478 Return the name of the current working directory.
1479 @end deffn
1480
1481 @deffn {Scheme Procedure} umask [mode]
1482 @deffnx {C Function} scm_umask (mode)
1483 If @var{mode} is omitted, returns a decimal number representing the
1484 current file creation mask. Otherwise the file creation mask is set
1485 to @var{mode} and the previous value is returned. @xref{Setting
1486 Permissions,,Assigning File Permissions,libc,The GNU C Library
1487 Reference Manual}, for more on how to use umasks.
1488
1489 E.g., @code{(umask #o022)} sets the mask to octal 22/decimal 18.
1490 @end deffn
1491
1492 @deffn {Scheme Procedure} chroot path
1493 @deffnx {C Function} scm_chroot (path)
1494 Change the root directory to that specified in @var{path}.
1495 This directory will be used for path names beginning with
1496 @file{/}. The root directory is inherited by all children
1497 of the current process. Only the superuser may change the
1498 root directory.
1499 @end deffn
1500
1501 @deffn {Scheme Procedure} getpid
1502 @deffnx {C Function} scm_getpid ()
1503 Return an integer representing the current process ID.
1504 @end deffn
1505
1506 @deffn {Scheme Procedure} getgroups
1507 @deffnx {C Function} scm_getgroups ()
1508 Return a vector of integers representing the current
1509 supplementary group IDs.
1510 @end deffn
1511
1512 @deffn {Scheme Procedure} getppid
1513 @deffnx {C Function} scm_getppid ()
1514 Return an integer representing the process ID of the parent
1515 process.
1516 @end deffn
1517
1518 @deffn {Scheme Procedure} getuid
1519 @deffnx {C Function} scm_getuid ()
1520 Return an integer representing the current real user ID.
1521 @end deffn
1522
1523 @deffn {Scheme Procedure} getgid
1524 @deffnx {C Function} scm_getgid ()
1525 Return an integer representing the current real group ID.
1526 @end deffn
1527
1528 @deffn {Scheme Procedure} geteuid
1529 @deffnx {C Function} scm_geteuid ()
1530 Return an integer representing the current effective user ID.
1531 If the system does not support effective IDs, then the real ID
1532 is returned. @code{(provided? 'EIDs)} reports whether the
1533 system supports effective IDs.
1534 @end deffn
1535
1536 @deffn {Scheme Procedure} getegid
1537 @deffnx {C Function} scm_getegid ()
1538 Return an integer representing the current effective group ID.
1539 If the system does not support effective IDs, then the real ID
1540 is returned. @code{(provided? 'EIDs)} reports whether the
1541 system supports effective IDs.
1542 @end deffn
1543
1544 @deffn {Scheme Procedure} setgroups vec
1545 @deffnx {C Function} scm_setgroups (vec)
1546 Set the current set of supplementary group IDs to the integers in the
1547 given vector @var{vec}. The return value is unspecified.
1548
1549 Generally only the superuser can set the process group IDs
1550 (@pxref{Setting Groups, Setting the Group IDs,, libc, The GNU C
1551 Library Reference Manual}).
1552 @end deffn
1553
1554 @deffn {Scheme Procedure} setuid id
1555 @deffnx {C Function} scm_setuid (id)
1556 Sets both the real and effective user IDs to the integer @var{id}, provided
1557 the process has appropriate privileges.
1558 The return value is unspecified.
1559 @end deffn
1560
1561 @deffn {Scheme Procedure} setgid id
1562 @deffnx {C Function} scm_setgid (id)
1563 Sets both the real and effective group IDs to the integer @var{id}, provided
1564 the process has appropriate privileges.
1565 The return value is unspecified.
1566 @end deffn
1567
1568 @deffn {Scheme Procedure} seteuid id
1569 @deffnx {C Function} scm_seteuid (id)
1570 Sets the effective user ID to the integer @var{id}, provided the process
1571 has appropriate privileges. If effective IDs are not supported, the
1572 real ID is set instead---@code{(provided? 'EIDs)} reports whether the
1573 system supports effective IDs.
1574 The return value is unspecified.
1575 @end deffn
1576
1577 @deffn {Scheme Procedure} setegid id
1578 @deffnx {C Function} scm_setegid (id)
1579 Sets the effective group ID to the integer @var{id}, provided the process
1580 has appropriate privileges. If effective IDs are not supported, the
1581 real ID is set instead---@code{(provided? 'EIDs)} reports whether the
1582 system supports effective IDs.
1583 The return value is unspecified.
1584 @end deffn
1585
1586 @deffn {Scheme Procedure} getpgrp
1587 @deffnx {C Function} scm_getpgrp ()
1588 Return an integer representing the current process group ID.
1589 This is the @acronym{POSIX} definition, not @acronym{BSD}.
1590 @end deffn
1591
1592 @deffn {Scheme Procedure} setpgid pid pgid
1593 @deffnx {C Function} scm_setpgid (pid, pgid)
1594 Move the process @var{pid} into the process group @var{pgid}. @var{pid} or
1595 @var{pgid} must be integers: they can be zero to indicate the ID of the
1596 current process.
1597 Fails on systems that do not support job control.
1598 The return value is unspecified.
1599 @end deffn
1600
1601 @deffn {Scheme Procedure} setsid
1602 @deffnx {C Function} scm_setsid ()
1603 Creates a new session. The current process becomes the session leader
1604 and is put in a new process group. The process will be detached
1605 from its controlling terminal if it has one.
1606 The return value is an integer representing the new process group ID.
1607 @end deffn
1608
1609 @deffn {Scheme Procedure} getsid pid
1610 @deffnx {C Function} scm_getsid (pid)
1611 Returns the session ID of process @var{pid}. (The session
1612 ID of a process is the process group ID of its session leader.)
1613 @end deffn
1614
1615 @deffn {Scheme Procedure} waitpid pid [options]
1616 @deffnx {C Function} scm_waitpid (pid, options)
1617 This procedure collects status information from a child process which
1618 has terminated or (optionally) stopped. Normally it will
1619 suspend the calling process until this can be done. If more than one
1620 child process is eligible then one will be chosen by the operating system.
1621
1622 The value of @var{pid} determines the behaviour:
1623
1624 @table @asis
1625 @item @var{pid} greater than 0
1626 Request status information from the specified child process.
1627 @item @var{pid} equal to -1 or @code{WAIT_ANY}
1628 @vindex WAIT_ANY
1629 Request status information for any child process.
1630 @item @var{pid} equal to 0 or @code{WAIT_MYPGRP}
1631 @vindex WAIT_MYPGRP
1632 Request status information for any child process in the current process
1633 group.
1634 @item @var{pid} less than -1
1635 Request status information for any child process whose process group ID
1636 is @minus{}@var{pid}.
1637 @end table
1638
1639 The @var{options} argument, if supplied, should be the bitwise OR of the
1640 values of zero or more of the following variables:
1641
1642 @defvar WNOHANG
1643 Return immediately even if there are no child processes to be collected.
1644 @end defvar
1645
1646 @defvar WUNTRACED
1647 Report status information for stopped processes as well as terminated
1648 processes.
1649 @end defvar
1650
1651 The return value is a pair containing:
1652
1653 @enumerate
1654 @item
1655 The process ID of the child process, or 0 if @code{WNOHANG} was
1656 specified and no process was collected.
1657 @item
1658 The integer status value.
1659 @end enumerate
1660 @end deffn
1661
1662 The following three
1663 functions can be used to decode the process status code returned
1664 by @code{waitpid}.
1665
1666 @deffn {Scheme Procedure} status:exit-val status
1667 @deffnx {C Function} scm_status_exit_val (status)
1668 Return the exit status value, as would be set if a process
1669 ended normally through a call to @code{exit} or @code{_exit},
1670 if any, otherwise @code{#f}.
1671 @end deffn
1672
1673 @deffn {Scheme Procedure} status:term-sig status
1674 @deffnx {C Function} scm_status_term_sig (status)
1675 Return the signal number which terminated the process, if any,
1676 otherwise @code{#f}.
1677 @end deffn
1678
1679 @deffn {Scheme Procedure} status:stop-sig status
1680 @deffnx {C Function} scm_status_stop_sig (status)
1681 Return the signal number which stopped the process, if any,
1682 otherwise @code{#f}.
1683 @end deffn
1684
1685 @deffn {Scheme Procedure} system [cmd]
1686 @deffnx {C Function} scm_system (cmd)
1687 Execute @var{cmd} using the operating system's ``command
1688 processor''. Under Unix this is usually the default shell
1689 @code{sh}. The value returned is @var{cmd}'s exit status as
1690 returned by @code{waitpid}, which can be interpreted using the
1691 functions above.
1692
1693 If @code{system} is called without arguments, return a boolean
1694 indicating whether the command processor is available.
1695 @end deffn
1696
1697 @deffn {Scheme Procedure} system* . args
1698 @deffnx {C Function} scm_system_star (args)
1699 Execute the command indicated by @var{args}. The first element must
1700 be a string indicating the command to be executed, and the remaining
1701 items must be strings representing each of the arguments to that
1702 command.
1703
1704 This function returns the exit status of the command as provided by
1705 @code{waitpid}. This value can be handled with @code{status:exit-val}
1706 and the related functions.
1707
1708 @code{system*} is similar to @code{system}, but accepts only one
1709 string per-argument, and performs no shell interpretation. The
1710 command is executed using fork and execlp. Accordingly this function
1711 may be safer than @code{system} in situations where shell
1712 interpretation is not required.
1713
1714 Example: (system* "echo" "foo" "bar")
1715 @end deffn
1716
1717 @deffn {Scheme Procedure} primitive-exit [status]
1718 @deffnx {Scheme Procedure} primitive-_exit [status]
1719 @deffnx {C Function} scm_primitive_exit (status)
1720 @deffnx {C Function} scm_primitive__exit (status)
1721 Terminate the current process without unwinding the Scheme stack. The
1722 exit status is @var{status} if supplied, otherwise zero.
1723
1724 @code{primitive-exit} uses the C @code{exit} function and hence runs
1725 usual C level cleanups (flush output streams, call @code{atexit}
1726 functions, etc, see @ref{Normal Termination,,, libc, The GNU C Library
1727 Reference Manual})).
1728
1729 @code{primitive-_exit} is the @code{_exit} system call
1730 (@pxref{Termination Internals,,, libc, The GNU C Library Reference
1731 Manual}). This terminates the program immediately, with neither
1732 Scheme-level nor C-level cleanups.
1733
1734 The typical use for @code{primitive-_exit} is from a child process
1735 created with @code{primitive-fork}. For example in a Gdk program the
1736 child process inherits the X server connection and a C-level
1737 @code{atexit} cleanup which will close that connection. But closing
1738 in the child would upset the protocol in the parent, so
1739 @code{primitive-_exit} should be used to exit without that.
1740 @end deffn
1741
1742 @deffn {Scheme Procedure} execl filename . args
1743 @deffnx {C Function} scm_execl (filename, args)
1744 Executes the file named by @var{path} as a new process image.
1745 The remaining arguments are supplied to the process; from a C program
1746 they are accessible as the @code{argv} argument to @code{main}.
1747 Conventionally the first @var{arg} is the same as @var{path}.
1748 All arguments must be strings.
1749
1750 If @var{arg} is missing, @var{path} is executed with a null
1751 argument list, which may have system-dependent side-effects.
1752
1753 This procedure is currently implemented using the @code{execv} system
1754 call, but we call it @code{execl} because of its Scheme calling interface.
1755 @end deffn
1756
1757 @deffn {Scheme Procedure} execlp filename . args
1758 @deffnx {C Function} scm_execlp (filename, args)
1759 Similar to @code{execl}, however if
1760 @var{filename} does not contain a slash
1761 then the file to execute will be located by searching the
1762 directories listed in the @code{PATH} environment variable.
1763
1764 This procedure is currently implemented using the @code{execvp} system
1765 call, but we call it @code{execlp} because of its Scheme calling interface.
1766 @end deffn
1767
1768 @deffn {Scheme Procedure} execle filename env . args
1769 @deffnx {C Function} scm_execle (filename, env, args)
1770 Similar to @code{execl}, but the environment of the new process is
1771 specified by @var{env}, which must be a list of strings as returned by the
1772 @code{environ} procedure.
1773
1774 This procedure is currently implemented using the @code{execve} system
1775 call, but we call it @code{execle} because of its Scheme calling interface.
1776 @end deffn
1777
1778 @deffn {Scheme Procedure} primitive-fork
1779 @deffnx {C Function} scm_fork ()
1780 Creates a new ``child'' process by duplicating the current ``parent'' process.
1781 In the child the return value is 0. In the parent the return value is
1782 the integer process ID of the child.
1783
1784 This procedure has been renamed from @code{fork} to avoid a naming conflict
1785 with the scsh fork.
1786 @end deffn
1787
1788 @deffn {Scheme Procedure} nice incr
1789 @deffnx {C Function} scm_nice (incr)
1790 @cindex process priority
1791 Increment the priority of the current process by @var{incr}. A higher
1792 priority value means that the process runs less often.
1793 The return value is unspecified.
1794 @end deffn
1795
1796 @deffn {Scheme Procedure} setpriority which who prio
1797 @deffnx {C Function} scm_setpriority (which, who, prio)
1798 @vindex PRIO_PROCESS
1799 @vindex PRIO_PGRP
1800 @vindex PRIO_USER
1801 Set the scheduling priority of the process, process group
1802 or user, as indicated by @var{which} and @var{who}. @var{which}
1803 is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
1804 or @code{PRIO_USER}, and @var{who} is interpreted relative to
1805 @var{which} (a process identifier for @code{PRIO_PROCESS},
1806 process group identifier for @code{PRIO_PGRP}, and a user
1807 identifier for @code{PRIO_USER}. A zero value of @var{who}
1808 denotes the current process, process group, or user.
1809 @var{prio} is a value in the range [@minus{}20,20]. The default
1810 priority is 0; lower priorities (in numerical terms) cause more
1811 favorable scheduling. Sets the priority of all of the specified
1812 processes. Only the super-user may lower priorities. The return
1813 value is not specified.
1814 @end deffn
1815
1816 @deffn {Scheme Procedure} getpriority which who
1817 @deffnx {C Function} scm_getpriority (which, who)
1818 @vindex PRIO_PROCESS
1819 @vindex PRIO_PGRP
1820 @vindex PRIO_USER
1821 Return the scheduling priority of the process, process group
1822 or user, as indicated by @var{which} and @var{who}. @var{which}
1823 is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
1824 or @code{PRIO_USER}, and @var{who} should be interpreted depending on
1825 @var{which} (a process identifier for @code{PRIO_PROCESS},
1826 process group identifier for @code{PRIO_PGRP}, and a user
1827 identifier for @code{PRIO_USER}). A zero value of @var{who}
1828 denotes the current process, process group, or user. Return
1829 the highest priority (lowest numerical value) of any of the
1830 specified processes.
1831 @end deffn
1832
1833 @cindex affinity, CPU
1834
1835 @deffn {Scheme Procedure} getaffinity pid
1836 @deffnx {C Function} scm_getaffinity (pid)
1837 Return a bitvector representing the CPU affinity mask for
1838 process @var{pid}. Each CPU the process has affinity with
1839 has its corresponding bit set in the returned bitvector.
1840 The number of bits set is a good estimate of how many CPUs
1841 Guile can use without stepping on other processes' toes.
1842
1843 Currently this procedure is only defined on GNU variants
1844 (@pxref{CPU Affinity, @code{sched_getaffinity},, libc, The
1845 GNU C Library Reference Manual}).
1846 @end deffn
1847
1848 @deffn {Scheme Procedure} setaffinity pid mask
1849 @deffnx {C Function} scm_setaffinity (pid, mask)
1850 Install the CPU affinity mask @var{mask}, a bitvector, for
1851 the process or thread with ID @var{pid}. The return value
1852 is unspecified.
1853
1854 Currently this procedure is only defined on GNU variants
1855 (@pxref{CPU Affinity, @code{sched_setaffinity},, libc, The
1856 GNU C Library Reference Manual}).
1857 @end deffn
1858
1859 @deffn {Scheme Procedure} total-processor-count
1860 @deffnx {C Function} scm_total_processor_count ()
1861 Return the total number of processors of the machine, which
1862 is guaranteed to be at least 1. A ``processor'' here is a
1863 thread execution unit, which can be either:
1864
1865 @itemize
1866 @item an execution core in a (possibly multi-core) chip, in a
1867 (possibly multi- chip) module, in a single computer, or
1868 @item a thread execution unit inside a core in the case of
1869 @dfn{hyper-threaded} CPUs.
1870 @end itemize
1871
1872 Which of the two definitions is used, is unspecified.
1873 @end deffn
1874
1875 @deffn {Scheme Procedure} current-processor-count
1876 @deffnx {C Function} scm_current_processor_count ()
1877 Like @code{total-processor-count}, but return the number of
1878 processors available to the current process. See
1879 @code{setaffinity} and @code{getaffinity} for more
1880 information.
1881 @end deffn
1882
1883
1884 @node Signals
1885 @subsection Signals
1886 @cindex signal
1887
1888 The following procedures raise, handle and wait for signals.
1889
1890 Scheme code signal handlers are run via a system async (@pxref{System
1891 asyncs}), so they're called in the handler's thread at the next safe
1892 opportunity. Generally this is after any currently executing
1893 primitive procedure finishes (which could be a long time for
1894 primitives that wait for an external event).
1895
1896 @deffn {Scheme Procedure} kill pid sig
1897 @deffnx {C Function} scm_kill (pid, sig)
1898 Sends a signal to the specified process or group of processes.
1899
1900 @var{pid} specifies the processes to which the signal is sent:
1901
1902 @table @asis
1903 @item @var{pid} greater than 0
1904 The process whose identifier is @var{pid}.
1905 @item @var{pid} equal to 0
1906 All processes in the current process group.
1907 @item @var{pid} less than -1
1908 The process group whose identifier is -@var{pid}
1909 @item @var{pid} equal to -1
1910 If the process is privileged, all processes except for some special
1911 system processes. Otherwise, all processes with the current effective
1912 user ID.
1913 @end table
1914
1915 @var{sig} should be specified using a variable corresponding to
1916 the Unix symbolic name, e.g.,
1917
1918 @defvar SIGHUP
1919 Hang-up signal.
1920 @end defvar
1921
1922 @defvar SIGINT
1923 Interrupt signal.
1924 @end defvar
1925
1926 A full list of signals on the GNU system may be found in @ref{Standard
1927 Signals,,,libc,The GNU C Library Reference Manual}.
1928 @end deffn
1929
1930 @deffn {Scheme Procedure} raise sig
1931 @deffnx {C Function} scm_raise (sig)
1932 Sends a specified signal @var{sig} to the current process, where
1933 @var{sig} is as described for the @code{kill} procedure.
1934 @end deffn
1935
1936 @deffn {Scheme Procedure} sigaction signum [handler [flags [thread]]]
1937 @deffnx {C Function} scm_sigaction (signum, handler, flags)
1938 @deffnx {C Function} scm_sigaction_for_thread (signum, handler, flags, thread)
1939 Install or report the signal handler for a specified signal.
1940
1941 @var{signum} is the signal number, which can be specified using the value
1942 of variables such as @code{SIGINT}.
1943
1944 If @var{handler} is omitted, @code{sigaction} returns a pair: the
1945 @acronym{CAR} is the current signal hander, which will be either an
1946 integer with the value @code{SIG_DFL} (default action) or
1947 @code{SIG_IGN} (ignore), or the Scheme procedure which handles the
1948 signal, or @code{#f} if a non-Scheme procedure handles the signal.
1949 The @acronym{CDR} contains the current @code{sigaction} flags for the
1950 handler.
1951
1952 If @var{handler} is provided, it is installed as the new handler for
1953 @var{signum}. @var{handler} can be a Scheme procedure taking one
1954 argument, or the value of @code{SIG_DFL} (default action) or
1955 @code{SIG_IGN} (ignore), or @code{#f} to restore whatever signal handler
1956 was installed before @code{sigaction} was first used. When a scheme
1957 procedure has been specified, that procedure will run in the given
1958 @var{thread}. When no thread has been given, the thread that made this
1959 call to @code{sigaction} is used.
1960
1961 @var{flags} is a @code{logior} (@pxref{Bitwise Operations}) of the
1962 following (where provided by the system), or @code{0} for none.
1963
1964 @defvar SA_NOCLDSTOP
1965 By default, @code{SIGCHLD} is signalled when a child process stops
1966 (ie.@: receives @code{SIGSTOP}), and when a child process terminates.
1967 With the @code{SA_NOCLDSTOP} flag, @code{SIGCHLD} is only signalled
1968 for termination, not stopping.
1969
1970 @code{SA_NOCLDSTOP} has no effect on signals other than
1971 @code{SIGCHLD}.
1972 @end defvar
1973
1974 @defvar SA_RESTART
1975 If a signal occurs while in a system call, deliver the signal then
1976 restart the system call (as opposed to returning an @code{EINTR} error
1977 from that call).
1978 @end defvar
1979
1980 The return value is a pair with information about the old handler as
1981 described above.
1982
1983 This interface does not provide access to the ``signal blocking''
1984 facility. Maybe this is not needed, since the thread support may
1985 provide solutions to the problem of consistent access to data
1986 structures.
1987 @end deffn
1988
1989 @deffn {Scheme Procedure} restore-signals
1990 @deffnx {C Function} scm_restore_signals ()
1991 Return all signal handlers to the values they had before any call to
1992 @code{sigaction} was made. The return value is unspecified.
1993 @end deffn
1994
1995 @deffn {Scheme Procedure} alarm i
1996 @deffnx {C Function} scm_alarm (i)
1997 Set a timer to raise a @code{SIGALRM} signal after the specified
1998 number of seconds (an integer). It's advisable to install a signal
1999 handler for
2000 @code{SIGALRM} beforehand, since the default action is to terminate
2001 the process.
2002
2003 The return value indicates the time remaining for the previous alarm,
2004 if any. The new value replaces the previous alarm. If there was
2005 no previous alarm, the return value is zero.
2006 @end deffn
2007
2008 @deffn {Scheme Procedure} pause
2009 @deffnx {C Function} scm_pause ()
2010 Pause the current process (thread?) until a signal arrives whose
2011 action is to either terminate the current process or invoke a
2012 handler procedure. The return value is unspecified.
2013 @end deffn
2014
2015 @deffn {Scheme Procedure} sleep secs
2016 @deffnx {Scheme Procedure} usleep usecs
2017 @deffnx {C Function} scm_sleep (secs)
2018 @deffnx {C Function} scm_usleep (usecs)
2019 Wait the given period @var{secs} seconds or @var{usecs} microseconds
2020 (both integers). If a signal arrives the wait stops and the return
2021 value is the time remaining, in seconds or microseconds respectively.
2022 If the period elapses with no signal the return is zero.
2023
2024 On most systems the process scheduler is not microsecond accurate and
2025 the actual period slept by @code{usleep} might be rounded to a system
2026 clock tick boundary, which might be 10 milliseconds for instance.
2027
2028 See @code{scm_std_sleep} and @code{scm_std_usleep} for equivalents at
2029 the C level (@pxref{Blocking}).
2030 @end deffn
2031
2032 @deffn {Scheme Procedure} getitimer which_timer
2033 @deffnx {Scheme Procedure} setitimer which_timer interval_seconds interval_microseconds periodic_seconds periodic_microseconds
2034 @deffnx {C Function} scm_getitimer (which_timer)
2035 @deffnx {C Function} scm_setitimer (which_timer, interval_seconds, interval_microseconds, periodic_seconds, periodic_microseconds)
2036 Get or set the periods programmed in certain system timers. These
2037 timers have a current interval value which counts down and on reaching
2038 zero raises a signal. An optional periodic value can be set to
2039 restart from there each time, for periodic operation.
2040 @var{which_timer} is one of the following values
2041
2042 @defvar ITIMER_REAL
2043 A real-time timer, counting down elapsed real time. At zero it raises
2044 @code{SIGALRM}. This is like @code{alarm} above, but with a higher
2045 resolution period.
2046 @end defvar
2047
2048 @defvar ITIMER_VIRTUAL
2049 A virtual-time timer, counting down while the current process is
2050 actually using CPU. At zero it raises @code{SIGVTALRM}.
2051 @end defvar
2052
2053 @defvar ITIMER_PROF
2054 A profiling timer, counting down while the process is running (like
2055 @code{ITIMER_VIRTUAL}) and also while system calls are running on the
2056 process's behalf. At zero it raises a @code{SIGPROF}.
2057
2058 This timer is intended for profiling where a program is spending its
2059 time (by looking where it is when the timer goes off).
2060 @end defvar
2061
2062 @code{getitimer} returns the current timer value and its programmed
2063 restart value, as a list containing two pairs. Each pair is a time in
2064 seconds and microseconds: @code{((@var{interval_secs}
2065 . @var{interval_usecs}) (@var{periodic_secs}
2066 . @var{periodic_usecs}))}.
2067
2068 @code{setitimer} sets the timer values similarly, in seconds and
2069 microseconds (which must be integers). The periodic value can be zero
2070 to have the timer run down just once. The return value is the timer's
2071 previous setting, in the same form as @code{getitimer} returns.
2072
2073 @example
2074 (setitimer ITIMER_REAL
2075 5 500000 ;; first SIGALRM in 5.5 seconds time
2076 2 0) ;; then repeat every 2 seconds
2077 @end example
2078
2079 Although the timers are programmed in microseconds, the actual
2080 accuracy might not be that high.
2081 @end deffn
2082
2083
2084 @node Terminals and Ptys
2085 @subsection Terminals and Ptys
2086
2087 @deffn {Scheme Procedure} isatty? port
2088 @deffnx {C Function} scm_isatty_p (port)
2089 @cindex terminal
2090 Return @code{#t} if @var{port} is using a serial non--file
2091 device, otherwise @code{#f}.
2092 @end deffn
2093
2094 @deffn {Scheme Procedure} ttyname port
2095 @deffnx {C Function} scm_ttyname (port)
2096 @cindex terminal
2097 Return a string with the name of the serial terminal device
2098 underlying @var{port}.
2099 @end deffn
2100
2101 @deffn {Scheme Procedure} ctermid
2102 @deffnx {C Function} scm_ctermid ()
2103 @cindex terminal
2104 Return a string containing the file name of the controlling
2105 terminal for the current process.
2106 @end deffn
2107
2108 @deffn {Scheme Procedure} tcgetpgrp port
2109 @deffnx {C Function} scm_tcgetpgrp (port)
2110 @cindex process group
2111 Return the process group ID of the foreground process group
2112 associated with the terminal open on the file descriptor
2113 underlying @var{port}.
2114
2115 If there is no foreground process group, the return value is a
2116 number greater than 1 that does not match the process group ID
2117 of any existing process group. This can happen if all of the
2118 processes in the job that was formerly the foreground job have
2119 terminated, and no other job has yet been moved into the
2120 foreground.
2121 @end deffn
2122
2123 @deffn {Scheme Procedure} tcsetpgrp port pgid
2124 @deffnx {C Function} scm_tcsetpgrp (port, pgid)
2125 @cindex process group
2126 Set the foreground process group ID for the terminal used by the file
2127 descriptor underlying @var{port} to the integer @var{pgid}.
2128 The calling process
2129 must be a member of the same session as @var{pgid} and must have the same
2130 controlling terminal. The return value is unspecified.
2131 @end deffn
2132
2133 @node Pipes
2134 @subsection Pipes
2135 @cindex pipe
2136
2137 The following procedures are similar to the @code{popen} and
2138 @code{pclose} system routines. The code is in a separate ``popen''
2139 module:
2140
2141 @lisp
2142 (use-modules (ice-9 popen))
2143 @end lisp
2144
2145 @findex popen
2146 @deffn {Scheme Procedure} open-pipe command mode
2147 @deffnx {Scheme Procedure} open-pipe* mode prog [args...]
2148 Execute a command in a subprocess, with a pipe to it or from it, or
2149 with pipes in both directions.
2150
2151 @code{open-pipe} runs the shell @var{command} using @samp{/bin/sh -c}.
2152 @code{open-pipe*} executes @var{prog} directly, with the optional
2153 @var{args} arguments (all strings).
2154
2155 @var{mode} should be one of the following values. @code{OPEN_READ} is
2156 an input pipe, ie.@: to read from the subprocess. @code{OPEN_WRITE}
2157 is an output pipe, ie.@: to write to it.
2158
2159 @defvar OPEN_READ
2160 @defvarx OPEN_WRITE
2161 @defvarx OPEN_BOTH
2162 @end defvar
2163
2164 For an input pipe, the child's standard output is the pipe and
2165 standard input is inherited from @code{current-input-port}. For an
2166 output pipe, the child's standard input is the pipe and standard
2167 output is inherited from @code{current-output-port}. In all cases
2168 cases the child's standard error is inherited from
2169 @code{current-error-port} (@pxref{Default Ports}).
2170
2171 If those @code{current-X-ports} are not files of some kind, and hence
2172 don't have file descriptors for the child, then @file{/dev/null} is
2173 used instead.
2174
2175 Care should be taken with @code{OPEN_BOTH}, a deadlock will occur if
2176 both parent and child are writing, and waiting until the write
2177 completes before doing any reading. Each direction has
2178 @code{PIPE_BUF} bytes of buffering (@pxref{Ports and File
2179 Descriptors}), which will be enough for small writes, but not for say
2180 putting a big file through a filter.
2181 @end deffn
2182
2183 @deffn {Scheme Procedure} open-input-pipe command
2184 Equivalent to @code{open-pipe} with mode @code{OPEN_READ}.
2185
2186 @lisp
2187 (let* ((port (open-input-pipe "date --utc"))
2188 (str (read-line port)))
2189 (close-pipe port)
2190 str)
2191 @result{} "Mon Mar 11 20:10:44 UTC 2002"
2192 @end lisp
2193 @end deffn
2194
2195 @deffn {Scheme Procedure} open-output-pipe command
2196 Equivalent to @code{open-pipe} with mode @code{OPEN_WRITE}.
2197
2198 @lisp
2199 (let ((port (open-output-pipe "lpr")))
2200 (display "Something for the line printer.\n" port)
2201 (if (not (eqv? 0 (status:exit-val (close-pipe port))))
2202 (error "Cannot print")))
2203 @end lisp
2204 @end deffn
2205
2206 @deffn {Scheme Procedure} open-input-output-pipe command
2207 Equivalent to @code{open-pipe} with mode @code{OPEN_BOTH}.
2208 @end deffn
2209
2210 @findex pclose
2211 @deffn {Scheme Procedure} close-pipe port
2212 Close a pipe created by @code{open-pipe}, wait for the process to
2213 terminate, and return the wait status code. The status is as per
2214 @code{waitpid} and can be decoded with @code{status:exit-val} etc
2215 (@pxref{Processes})
2216 @end deffn
2217
2218 @sp 1
2219 @code{waitpid WAIT_ANY} should not be used when pipes are open, since
2220 it can reap a pipe's child process, causing an error from a subsequent
2221 @code{close-pipe}.
2222
2223 @code{close-port} (@pxref{Closing}) can close a pipe, but it doesn't
2224 reap the child process.
2225
2226 The garbage collector will close a pipe no longer in use, and reap the
2227 child process with @code{waitpid}. If the child hasn't yet terminated
2228 the garbage collector doesn't block, but instead checks again in the
2229 next GC.
2230
2231 Many systems have per-user and system-wide limits on the number of
2232 processes, and a system-wide limit on the number of pipes, so pipes
2233 should be closed explicitly when no longer needed, rather than letting
2234 the garbage collector pick them up at some later time.
2235
2236
2237 @node Networking
2238 @subsection Networking
2239 @cindex network
2240
2241 @menu
2242 * Network Address Conversion::
2243 * Network Databases::
2244 * Network Socket Address::
2245 * Network Sockets and Communication::
2246 * Internet Socket Examples::
2247 @end menu
2248
2249 @node Network Address Conversion
2250 @subsubsection Network Address Conversion
2251 @cindex network address
2252
2253 This section describes procedures which convert internet addresses
2254 between numeric and string formats.
2255
2256 @subsubheading IPv4 Address Conversion
2257 @cindex IPv4
2258
2259 An IPv4 Internet address is a 4-byte value, represented in Guile as an
2260 integer in host byte order, so that say ``0.0.0.1'' is 1, or
2261 ``1.0.0.0'' is 16777216.
2262
2263 Some underlying C functions use network byte order for addresses,
2264 Guile converts as necessary so that at the Scheme level its host byte
2265 order everywhere.
2266
2267 @defvar INADDR_ANY
2268 For a server, this can be used with @code{bind} (@pxref{Network
2269 Sockets and Communication}) to allow connections from any interface on
2270 the machine.
2271 @end defvar
2272
2273 @defvar INADDR_BROADCAST
2274 The broadcast address on the local network.
2275 @end defvar
2276
2277 @defvar INADDR_LOOPBACK
2278 The address of the local host using the loopback device, ie.@:
2279 @samp{127.0.0.1}.
2280 @end defvar
2281
2282 @c INADDR_NONE is defined in the code, but serves no purpose.
2283 @c inet_addr() returns it as an error indication, but that function
2284 @c isn't provided, for the good reason that inet_aton() does the same
2285 @c job and gives an unambiguous error indication. (INADDR_NONE is a
2286 @c valid 4-byte value, in glibc it's the same as INADDR_BROADCAST.)
2287 @c
2288 @c @defvar INADDR_NONE
2289 @c No address.
2290 @c @end defvar
2291
2292 @deffn {Scheme Procedure} inet-aton address
2293 @deffnx {C Function} scm_inet_aton (address)
2294 This function is deprecated in favor of @code{inet-pton}.
2295
2296 Convert an IPv4 Internet address from printable string
2297 (dotted decimal notation) to an integer. E.g.,
2298
2299 @lisp
2300 (inet-aton "127.0.0.1") @result{} 2130706433
2301 @end lisp
2302 @end deffn
2303
2304 @deffn {Scheme Procedure} inet-ntoa inetid
2305 @deffnx {C Function} scm_inet_ntoa (inetid)
2306 This function is deprecated in favor of @code{inet-ntop}.
2307
2308 Convert an IPv4 Internet address to a printable
2309 (dotted decimal notation) string. E.g.,
2310
2311 @lisp
2312 (inet-ntoa 2130706433) @result{} "127.0.0.1"
2313 @end lisp
2314 @end deffn
2315
2316 @deffn {Scheme Procedure} inet-netof address
2317 @deffnx {C Function} scm_inet_netof (address)
2318 Return the network number part of the given IPv4
2319 Internet address. E.g.,
2320
2321 @lisp
2322 (inet-netof 2130706433) @result{} 127
2323 @end lisp
2324 @end deffn
2325
2326 @deffn {Scheme Procedure} inet-lnaof address
2327 @deffnx {C Function} scm_lnaof (address)
2328 Return the local-address-with-network part of the given
2329 IPv4 Internet address, using the obsolete class A/B/C system.
2330 E.g.,
2331
2332 @lisp
2333 (inet-lnaof 2130706433) @result{} 1
2334 @end lisp
2335 @end deffn
2336
2337 @deffn {Scheme Procedure} inet-makeaddr net lna
2338 @deffnx {C Function} scm_inet_makeaddr (net, lna)
2339 Make an IPv4 Internet address by combining the network number
2340 @var{net} with the local-address-within-network number
2341 @var{lna}. E.g.,
2342
2343 @lisp
2344 (inet-makeaddr 127 1) @result{} 2130706433
2345 @end lisp
2346 @end deffn
2347
2348 @subsubheading IPv6 Address Conversion
2349 @cindex IPv6
2350
2351 An IPv6 Internet address is a 16-byte value, represented in Guile as
2352 an integer in host byte order, so that say ``::1'' is 1.
2353
2354 @deffn {Scheme Procedure} inet-ntop family address
2355 @deffnx {C Function} scm_inet_ntop (family, address)
2356 Convert a network address from an integer to a printable string.
2357 @var{family} can be @code{AF_INET} or @code{AF_INET6}. E.g.,
2358
2359 @lisp
2360 (inet-ntop AF_INET 2130706433) @result{} "127.0.0.1"
2361 (inet-ntop AF_INET6 (- (expt 2 128) 1))
2362 @result{} "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff"
2363 @end lisp
2364 @end deffn
2365
2366 @deffn {Scheme Procedure} inet-pton family address
2367 @deffnx {C Function} scm_inet_pton (family, address)
2368 Convert a string containing a printable network address to an integer
2369 address. @var{family} can be @code{AF_INET} or @code{AF_INET6}.
2370 E.g.,
2371
2372 @lisp
2373 (inet-pton AF_INET "127.0.0.1") @result{} 2130706433
2374 (inet-pton AF_INET6 "::1") @result{} 1
2375 @end lisp
2376 @end deffn
2377
2378
2379 @node Network Databases
2380 @subsubsection Network Databases
2381 @cindex network database
2382
2383 This section describes procedures which query various network databases.
2384 Care should be taken when using the database routines since they are not
2385 reentrant.
2386
2387 @subsubheading @code{getaddrinfo}
2388
2389 @cindex @code{addrinfo} object type
2390 @cindex host name lookup
2391 @cindex service name lookup
2392
2393 The @code{getaddrinfo} procedure maps host and service names to socket addresses
2394 and associated information in a protocol-independent way.
2395
2396 @deffn {Scheme Procedure} getaddrinfo name service [hint_flags [hint_family [hint_socktype [hint_protocol]]]]
2397 @deffnx {C Function} scm_getaddrinfo (name, service, hint_flags, hint_family, hint_socktype, hint_protocol)
2398 Return a list of @code{addrinfo} structures containing
2399 a socket address and associated information for host @var{name}
2400 and/or @var{service} to be used in creating a socket with
2401 which to address the specified service.
2402
2403 @example
2404 (let* ((ai (car (getaddrinfo "www.gnu.org" "http")))
2405 (s (socket (addrinfo:fam ai) (addrinfo:socktype ai)
2406 (addrinfo:protocol ai))))
2407 (connect s (addrinfo:addr ai))
2408 s)
2409 @end example
2410
2411 When @var{service} is omitted or is @code{#f}, return
2412 network-level addresses for @var{name}. When @var{name}
2413 is @code{#f} @var{service} must be provided and service
2414 locations local to the caller are returned.
2415
2416 Additional hints can be provided. When specified,
2417 @var{hint_flags} should be a bitwise-or of zero or more
2418 constants among the following:
2419
2420 @table @code
2421 @item AI_PASSIVE
2422 Socket address is intended for @code{bind}.
2423
2424 @item AI_CANONNAME
2425 Request for canonical host name, available via
2426 @code{addrinfo:canonname}. This makes sense mainly when
2427 DNS lookups are involved.
2428
2429 @item AI_NUMERICHOST
2430 Specifies that @var{name} is a numeric host address string
2431 (e.g., @code{"127.0.0.1"}), meaning that name resolution
2432 will not be used.
2433
2434 @item AI_NUMERICSERV
2435 Likewise, specifies that @var{service} is a numeric port
2436 string (e.g., @code{"80"}).
2437
2438 @item AI_ADDRCONFIG
2439 Return only addresses configured on the local system It is
2440 highly recommended to provide this flag when the returned
2441 socket addresses are to be used to make connections;
2442 otherwise, some of the returned addresses could be unreachable
2443 or use a protocol that is not supported.
2444
2445 @item AI_V4MAPPED
2446 When looking up IPv6 addresses, return mapped IPv4 addresses if
2447 there is no IPv6 address available at all.
2448
2449 @item AI_ALL
2450 If this flag is set along with @code{AI_V4MAPPED} when looking up IPv6
2451 addresses, return all IPv6 addresses as well as all IPv4 addresses, the latter
2452 mapped to IPv6 format.
2453 @end table
2454
2455 When given, @var{hint_family} should specify the requested
2456 address family, e.g., @code{AF_INET6}. Similarly,
2457 @var{hint_socktype} should specify the requested socket type
2458 (e.g., @code{SOCK_DGRAM}), and @var{hint_protocol} should
2459 specify the requested protocol (its value is interpreted
2460 as in calls to @code{socket}).
2461
2462 On error, an exception with key @code{getaddrinfo-error} is
2463 thrown, with an error code (an integer) as its argument:
2464
2465 @example
2466 (catch 'getaddrinfo-error
2467 (lambda ()
2468 (getaddrinfo "www.gnu.org" "gopher"))
2469 (lambda (key errcode)
2470 (cond ((= errcode EAI_SERVICE)
2471 (display "doesn't know about Gopher!\n"))
2472 ((= errcode EAI_NONAME)
2473 (display "www.gnu.org not found\\n"))
2474 (else
2475 (format #t "something wrong: ~a\n"
2476 (gai-strerror errcode))))))
2477 @end example
2478
2479 Error codes are:
2480
2481 @table @code
2482 @item EAI_AGAIN
2483 The name or service could not be resolved at this time. Future
2484 attempts may succeed.
2485
2486 @item EAI_BADFLAGS
2487 @var{hint_flags} contains an invalid value.
2488
2489 @item EAI_FAIL
2490 A non-recoverable error occurred when attempting to
2491 resolve the name.
2492
2493 @item EAI_FAMILY
2494 @var{hint_family} was not recognized.
2495
2496 @item EAI_NONAME
2497 Either @var{name} does not resolve for the supplied parameters,
2498 or neither @var{name} nor @var{service} were supplied.
2499
2500 @item EAI_NODATA
2501 This non-POSIX error code can be returned on GNU systems when a
2502 request was actually made but returned no data, meaning
2503 that no address is associated with @var{name}. Error handling
2504 code should be prepared to handle it when it is defined.
2505
2506 @item EAI_SERVICE
2507 @var{service} was not recognized for the specified socket type.
2508
2509 @item EAI_SOCKTYPE
2510 @var{hint_socktype} was not recognized.
2511
2512 @item EAI_SYSTEM
2513 A system error occurred; the error code can be found in
2514 @code{errno}.
2515 @end table
2516
2517 Users are encouraged to read the
2518 @url{http://www.opengroup.org/onlinepubs/9699919799/functions/getaddrinfo.html,
2519 "POSIX specification} for more details.
2520 @end deffn
2521
2522 The following procedures take an @code{addrinfo} object as returned by
2523 @code{getaddrinfo}:
2524
2525 @deffn {Scheme Procedure} addrinfo:flags ai
2526 Return flags for @var{ai} as a bitwise or of @code{AI_} values (see above).
2527 @end deffn
2528
2529 @deffn {Scheme Procedure} addrinfo:fam ai
2530 Return the address family of @var{ai} (a @code{AF_} value).
2531 @end deffn
2532
2533 @deffn {Scheme Procedure} addrinfo:socktype ai
2534 Return the socket type for @var{ai} (a @code{SOCK_} value).
2535 @end deffn
2536
2537 @deffn {Scheme Procedure} addrinfo:protocol ai
2538 Return the protocol of @var{ai}.
2539 @end deffn
2540
2541 @deffn {Scheme Procedure} addrinfo:addr ai
2542 Return the socket address associated with @var{ai} as a @code{sockaddr}
2543 object (@pxref{Network Socket Address}).
2544 @end deffn
2545
2546 @deffn {Scheme Procedure} addrinfo:canonname ai
2547 Return a string for the canonical name associated with @var{ai} if
2548 the @code{AI_CANONNAME} flag was supplied.
2549 @end deffn
2550
2551 @subsubheading The Host Database
2552 @cindex @file{/etc/hosts}
2553 @cindex network database
2554
2555 A @dfn{host object} is a structure that represents what is known about a
2556 network host, and is the usual way of representing a system's network
2557 identity inside software.
2558
2559 The following functions accept a host object and return a selected
2560 component:
2561
2562 @deffn {Scheme Procedure} hostent:name host
2563 The ``official'' hostname for @var{host}.
2564 @end deffn
2565 @deffn {Scheme Procedure} hostent:aliases host
2566 A list of aliases for @var{host}.
2567 @end deffn
2568 @deffn {Scheme Procedure} hostent:addrtype host
2569 The host address type, one of the @code{AF} constants, such as
2570 @code{AF_INET} or @code{AF_INET6}.
2571 @end deffn
2572 @deffn {Scheme Procedure} hostent:length host
2573 The length of each address for @var{host}, in bytes.
2574 @end deffn
2575 @deffn {Scheme Procedure} hostent:addr-list host
2576 The list of network addresses associated with @var{host}. For
2577 @code{AF_INET} these are integer IPv4 address (@pxref{Network Address
2578 Conversion}).
2579 @end deffn
2580
2581 The following procedures can be used to search the host database. However,
2582 @code{getaddrinfo} should be preferred over them since it's more generic and
2583 thread-safe.
2584
2585 @deffn {Scheme Procedure} gethost [host]
2586 @deffnx {Scheme Procedure} gethostbyname hostname
2587 @deffnx {Scheme Procedure} gethostbyaddr address
2588 @deffnx {C Function} scm_gethost (host)
2589 Look up a host by name or address, returning a host object. The
2590 @code{gethost} procedure will accept either a string name or an integer
2591 address; if given no arguments, it behaves like @code{gethostent} (see
2592 below). If a name or address is supplied but the address can not be
2593 found, an error will be thrown to one of the keys:
2594 @code{host-not-found}, @code{try-again}, @code{no-recovery} or
2595 @code{no-data}, corresponding to the equivalent @code{h_error} values.
2596 Unusual conditions may result in errors thrown to the
2597 @code{system-error} or @code{misc_error} keys.
2598
2599 @lisp
2600 (gethost "www.gnu.org")
2601 @result{} #("www.gnu.org" () 2 4 (3353880842))
2602
2603 (gethostbyname "www.emacs.org")
2604 @result{} #("emacs.org" ("www.emacs.org") 2 4 (1073448978))
2605 @end lisp
2606 @end deffn
2607
2608 The following procedures may be used to step through the host
2609 database from beginning to end.
2610
2611 @deffn {Scheme Procedure} sethostent [stayopen]
2612 Initialize an internal stream from which host objects may be read. This
2613 procedure must be called before any calls to @code{gethostent}, and may
2614 also be called afterward to reset the host entry stream. If
2615 @var{stayopen} is supplied and is not @code{#f}, the database is not
2616 closed by subsequent @code{gethostbyname} or @code{gethostbyaddr} calls,
2617 possibly giving an efficiency gain.
2618 @end deffn
2619
2620 @deffn {Scheme Procedure} gethostent
2621 Return the next host object from the host database, or @code{#f} if
2622 there are no more hosts to be found (or an error has been encountered).
2623 This procedure may not be used before @code{sethostent} has been called.
2624 @end deffn
2625
2626 @deffn {Scheme Procedure} endhostent
2627 Close the stream used by @code{gethostent}. The return value is unspecified.
2628 @end deffn
2629
2630 @deffn {Scheme Procedure} sethost [stayopen]
2631 @deffnx {C Function} scm_sethost (stayopen)
2632 If @var{stayopen} is omitted, this is equivalent to @code{endhostent}.
2633 Otherwise it is equivalent to @code{sethostent stayopen}.
2634 @end deffn
2635
2636 @subsubheading The Network Database
2637 @cindex network database
2638
2639 The following functions accept an object representing a network
2640 and return a selected component:
2641
2642 @deffn {Scheme Procedure} netent:name net
2643 The ``official'' network name.
2644 @end deffn
2645 @deffn {Scheme Procedure} netent:aliases net
2646 A list of aliases for the network.
2647 @end deffn
2648 @deffn {Scheme Procedure} netent:addrtype net
2649 The type of the network number. Currently, this returns only
2650 @code{AF_INET}.
2651 @end deffn
2652 @deffn {Scheme Procedure} netent:net net
2653 The network number.
2654 @end deffn
2655
2656 The following procedures are used to search the network database:
2657
2658 @deffn {Scheme Procedure} getnet [net]
2659 @deffnx {Scheme Procedure} getnetbyname net-name
2660 @deffnx {Scheme Procedure} getnetbyaddr net-number
2661 @deffnx {C Function} scm_getnet (net)
2662 Look up a network by name or net number in the network database. The
2663 @var{net-name} argument must be a string, and the @var{net-number}
2664 argument must be an integer. @code{getnet} will accept either type of
2665 argument, behaving like @code{getnetent} (see below) if no arguments are
2666 given.
2667 @end deffn
2668
2669 The following procedures may be used to step through the network
2670 database from beginning to end.
2671
2672 @deffn {Scheme Procedure} setnetent [stayopen]
2673 Initialize an internal stream from which network objects may be read. This
2674 procedure must be called before any calls to @code{getnetent}, and may
2675 also be called afterward to reset the net entry stream. If
2676 @var{stayopen} is supplied and is not @code{#f}, the database is not
2677 closed by subsequent @code{getnetbyname} or @code{getnetbyaddr} calls,
2678 possibly giving an efficiency gain.
2679 @end deffn
2680
2681 @deffn {Scheme Procedure} getnetent
2682 Return the next entry from the network database.
2683 @end deffn
2684
2685 @deffn {Scheme Procedure} endnetent
2686 Close the stream used by @code{getnetent}. The return value is unspecified.
2687 @end deffn
2688
2689 @deffn {Scheme Procedure} setnet [stayopen]
2690 @deffnx {C Function} scm_setnet (stayopen)
2691 If @var{stayopen} is omitted, this is equivalent to @code{endnetent}.
2692 Otherwise it is equivalent to @code{setnetent stayopen}.
2693 @end deffn
2694
2695 @subsubheading The Protocol Database
2696 @cindex @file{/etc/protocols}
2697 @cindex protocols
2698 @cindex network protocols
2699
2700 The following functions accept an object representing a protocol
2701 and return a selected component:
2702
2703 @deffn {Scheme Procedure} protoent:name protocol
2704 The ``official'' protocol name.
2705 @end deffn
2706 @deffn {Scheme Procedure} protoent:aliases protocol
2707 A list of aliases for the protocol.
2708 @end deffn
2709 @deffn {Scheme Procedure} protoent:proto protocol
2710 The protocol number.
2711 @end deffn
2712
2713 The following procedures are used to search the protocol database:
2714
2715 @deffn {Scheme Procedure} getproto [protocol]
2716 @deffnx {Scheme Procedure} getprotobyname name
2717 @deffnx {Scheme Procedure} getprotobynumber number
2718 @deffnx {C Function} scm_getproto (protocol)
2719 Look up a network protocol by name or by number. @code{getprotobyname}
2720 takes a string argument, and @code{getprotobynumber} takes an integer
2721 argument. @code{getproto} will accept either type, behaving like
2722 @code{getprotoent} (see below) if no arguments are supplied.
2723 @end deffn
2724
2725 The following procedures may be used to step through the protocol
2726 database from beginning to end.
2727
2728 @deffn {Scheme Procedure} setprotoent [stayopen]
2729 Initialize an internal stream from which protocol objects may be read. This
2730 procedure must be called before any calls to @code{getprotoent}, and may
2731 also be called afterward to reset the protocol entry stream. If
2732 @var{stayopen} is supplied and is not @code{#f}, the database is not
2733 closed by subsequent @code{getprotobyname} or @code{getprotobynumber} calls,
2734 possibly giving an efficiency gain.
2735 @end deffn
2736
2737 @deffn {Scheme Procedure} getprotoent
2738 Return the next entry from the protocol database.
2739 @end deffn
2740
2741 @deffn {Scheme Procedure} endprotoent
2742 Close the stream used by @code{getprotoent}. The return value is unspecified.
2743 @end deffn
2744
2745 @deffn {Scheme Procedure} setproto [stayopen]
2746 @deffnx {C Function} scm_setproto (stayopen)
2747 If @var{stayopen} is omitted, this is equivalent to @code{endprotoent}.
2748 Otherwise it is equivalent to @code{setprotoent stayopen}.
2749 @end deffn
2750
2751 @subsubheading The Service Database
2752 @cindex @file{/etc/services}
2753 @cindex services
2754 @cindex network services
2755
2756 The following functions accept an object representing a service
2757 and return a selected component:
2758
2759 @deffn {Scheme Procedure} servent:name serv
2760 The ``official'' name of the network service.
2761 @end deffn
2762 @deffn {Scheme Procedure} servent:aliases serv
2763 A list of aliases for the network service.
2764 @end deffn
2765 @deffn {Scheme Procedure} servent:port serv
2766 The Internet port used by the service.
2767 @end deffn
2768 @deffn {Scheme Procedure} servent:proto serv
2769 The protocol used by the service. A service may be listed many times
2770 in the database under different protocol names.
2771 @end deffn
2772
2773 The following procedures are used to search the service database:
2774
2775 @deffn {Scheme Procedure} getserv [name [protocol]]
2776 @deffnx {Scheme Procedure} getservbyname name protocol
2777 @deffnx {Scheme Procedure} getservbyport port protocol
2778 @deffnx {C Function} scm_getserv (name, protocol)
2779 Look up a network service by name or by service number, and return a
2780 network service object. The @var{protocol} argument specifies the name
2781 of the desired protocol; if the protocol found in the network service
2782 database does not match this name, a system error is signalled.
2783
2784 The @code{getserv} procedure will take either a service name or number
2785 as its first argument; if given no arguments, it behaves like
2786 @code{getservent} (see below).
2787
2788 @lisp
2789 (getserv "imap" "tcp")
2790 @result{} #("imap2" ("imap") 143 "tcp")
2791
2792 (getservbyport 88 "udp")
2793 @result{} #("kerberos" ("kerberos5" "krb5") 88 "udp")
2794 @end lisp
2795 @end deffn
2796
2797 The following procedures may be used to step through the service
2798 database from beginning to end.
2799
2800 @deffn {Scheme Procedure} setservent [stayopen]
2801 Initialize an internal stream from which service objects may be read. This
2802 procedure must be called before any calls to @code{getservent}, and may
2803 also be called afterward to reset the service entry stream. If
2804 @var{stayopen} is supplied and is not @code{#f}, the database is not
2805 closed by subsequent @code{getservbyname} or @code{getservbyport} calls,
2806 possibly giving an efficiency gain.
2807 @end deffn
2808
2809 @deffn {Scheme Procedure} getservent
2810 Return the next entry from the services database.
2811 @end deffn
2812
2813 @deffn {Scheme Procedure} endservent
2814 Close the stream used by @code{getservent}. The return value is unspecified.
2815 @end deffn
2816
2817 @deffn {Scheme Procedure} setserv [stayopen]
2818 @deffnx {C Function} scm_setserv (stayopen)
2819 If @var{stayopen} is omitted, this is equivalent to @code{endservent}.
2820 Otherwise it is equivalent to @code{setservent stayopen}.
2821 @end deffn
2822
2823
2824 @node Network Socket Address
2825 @subsubsection Network Socket Address
2826 @cindex socket address
2827 @cindex network socket address
2828 @tpindex Socket address
2829
2830 A @dfn{socket address} object identifies a socket endpoint for
2831 communication. In the case of @code{AF_INET} for instance, the socket
2832 address object comprises the host address (or interface on the host)
2833 and a port number which specifies a particular open socket in a
2834 running client or server process. A socket address object can be
2835 created with,
2836
2837 @deffn {Scheme Procedure} make-socket-address AF_INET ipv4addr port
2838 @deffnx {Scheme Procedure} make-socket-address AF_INET6 ipv6addr port [flowinfo [scopeid]]
2839 @deffnx {Scheme Procedure} make-socket-address AF_UNIX path
2840 @deffnx {C Function} scm_make_socket_address family address arglist
2841 Return a new socket address object. The first argument is the address
2842 family, one of the @code{AF} constants, then the arguments vary
2843 according to the family.
2844
2845 For @code{AF_INET} the arguments are an IPv4 network address number
2846 (@pxref{Network Address Conversion}), and a port number.
2847
2848 For @code{AF_INET6} the arguments are an IPv6 network address number
2849 and a port number. Optional @var{flowinfo} and @var{scopeid}
2850 arguments may be given (both integers, default 0).
2851
2852 For @code{AF_UNIX} the argument is a filename (a string).
2853
2854 The C function @code{scm_make_socket_address} takes the @var{family}
2855 and @var{address} arguments directly, then @var{arglist} is a list of
2856 further arguments, being the port for IPv4, port and optional flowinfo
2857 and scopeid for IPv6, or the empty list @code{SCM_EOL} for Unix
2858 domain.
2859 @end deffn
2860
2861 @noindent
2862 The following functions access the fields of a socket address object,
2863
2864 @deffn {Scheme Procedure} sockaddr:fam sa
2865 Return the address family from socket address object @var{sa}. This
2866 is one of the @code{AF} constants (e.g.@: @code{AF_INET}).
2867 @end deffn
2868
2869 @deffn {Scheme Procedure} sockaddr:path sa
2870 For an @code{AF_UNIX} socket address object @var{sa}, return the
2871 filename.
2872 @end deffn
2873
2874 @deffn {Scheme Procedure} sockaddr:addr sa
2875 For an @code{AF_INET} or @code{AF_INET6} socket address object
2876 @var{sa}, return the network address number.
2877 @end deffn
2878
2879 @deffn {Scheme Procedure} sockaddr:port sa
2880 For an @code{AF_INET} or @code{AF_INET6} socket address object
2881 @var{sa}, return the port number.
2882 @end deffn
2883
2884 @deffn {Scheme Procedure} sockaddr:flowinfo sa
2885 For an @code{AF_INET6} socket address object @var{sa}, return the
2886 flowinfo value.
2887 @end deffn
2888
2889 @deffn {Scheme Procedure} sockaddr:scopeid sa
2890 For an @code{AF_INET6} socket address object @var{sa}, return the
2891 scope ID value.
2892 @end deffn
2893
2894 @tpindex @code{struct sockaddr}
2895 @tpindex @code{sockaddr}
2896 The functions below convert to and from the C @code{struct sockaddr}
2897 (@pxref{Address Formats,,, libc, The GNU C Library Reference Manual}).
2898 That structure is a generic type, an application can cast to or from
2899 @code{struct sockaddr_in}, @code{struct sockaddr_in6} or @code{struct
2900 sockaddr_un} according to the address family.
2901
2902 In a @code{struct sockaddr} taken or returned, the byte ordering in
2903 the fields follows the C conventions (@pxref{Byte Order,, Byte Order
2904 Conversion, libc, The GNU C Library Reference Manual}). This means
2905 network byte order for @code{AF_INET} host address
2906 (@code{sin_addr.s_addr}) and port number (@code{sin_port}), and
2907 @code{AF_INET6} port number (@code{sin6_port}). But at the Scheme
2908 level these values are taken or returned in host byte order, so the
2909 port is an ordinary integer, and the host address likewise is an
2910 ordinary integer (as described in @ref{Network Address Conversion}).
2911
2912 @deftypefn {C Function} {struct sockaddr *} scm_c_make_socket_address (SCM family, SCM address, SCM args, size_t *outsize)
2913 Return a newly-@code{malloc}ed @code{struct sockaddr} created from
2914 arguments like those taken by @code{scm_make_socket_address} above.
2915
2916 The size (in bytes) of the @code{struct sockaddr} return is stored
2917 into @code{*@var{outsize}}. An application must call @code{free} to
2918 release the returned structure when no longer required.
2919 @end deftypefn
2920
2921 @deftypefn {C Function} SCM scm_from_sockaddr (const struct sockaddr *address, unsigned address_size)
2922 Return a Scheme socket address object from the C @var{address}
2923 structure. @var{address_size} is the size in bytes of @var{address}.
2924 @end deftypefn
2925
2926 @deftypefn {C Function} {struct sockaddr *} scm_to_sockaddr (SCM address, size_t *address_size)
2927 Return a newly-@code{malloc}ed @code{struct sockaddr} from a Scheme
2928 level socket address object.
2929
2930 The size (in bytes) of the @code{struct sockaddr} return is stored
2931 into @code{*@var{outsize}}. An application must call @code{free} to
2932 release the returned structure when no longer required.
2933 @end deftypefn
2934
2935
2936 @node Network Sockets and Communication
2937 @subsubsection Network Sockets and Communication
2938 @cindex socket
2939 @cindex network socket
2940
2941 Socket ports can be created using @code{socket} and @code{socketpair}.
2942 The ports are initially unbuffered, to make reading and writing to the
2943 same port more reliable. A buffer can be added to the port using
2944 @code{setvbuf}; see @ref{Ports and File Descriptors}.
2945
2946 Most systems have limits on how many files and sockets can be open, so
2947 it's strongly recommended that socket ports be closed explicitly when
2948 no longer required (@pxref{Ports}).
2949
2950 Some of the underlying C functions take values in network byte order,
2951 but the convention in Guile is that at the Scheme level everything is
2952 ordinary host byte order and conversions are made automatically where
2953 necessary.
2954
2955 @deffn {Scheme Procedure} socket family style proto
2956 @deffnx {C Function} scm_socket (family, style, proto)
2957 Return a new socket port of the type specified by @var{family},
2958 @var{style} and @var{proto}. All three parameters are integers. The
2959 possible values for @var{family} are as follows, where supported by
2960 the system,
2961
2962 @defvar PF_UNIX
2963 @defvarx PF_INET
2964 @defvarx PF_INET6
2965 @end defvar
2966
2967 The possible values for @var{style} are as follows, again where
2968 supported by the system,
2969
2970 @defvar SOCK_STREAM
2971 @defvarx SOCK_DGRAM
2972 @defvarx SOCK_RAW
2973 @defvarx SOCK_RDM
2974 @defvarx SOCK_SEQPACKET
2975 @end defvar
2976
2977 @var{proto} can be obtained from a protocol name using
2978 @code{getprotobyname} (@pxref{Network Databases}). A value of zero
2979 means the default protocol, which is usually right.
2980
2981 A socket cannot by used for communication until it has been connected
2982 somewhere, usually with either @code{connect} or @code{accept} below.
2983 @end deffn
2984
2985 @deffn {Scheme Procedure} socketpair family style proto
2986 @deffnx {C Function} scm_socketpair (family, style, proto)
2987 Return a pair, the @code{car} and @code{cdr} of which are two unnamed
2988 socket ports connected to each other. The connection is full-duplex,
2989 so data can be transferred in either direction between the two.
2990
2991 @var{family}, @var{style} and @var{proto} are as per @code{socket}
2992 above. But many systems only support socket pairs in the
2993 @code{PF_UNIX} family. Zero is likely to be the only meaningful value
2994 for @var{proto}.
2995 @end deffn
2996
2997 @deffn {Scheme Procedure} getsockopt sock level optname
2998 @deffnx {Scheme Procedure} setsockopt sock level optname value
2999 @deffnx {C Function} scm_getsockopt (sock, level, optname)
3000 @deffnx {C Function} scm_setsockopt (sock, level, optname, value)
3001 Get or set an option on socket port @var{sock}. @code{getsockopt}
3002 returns the current value. @code{setsockopt} sets a value and the
3003 return is unspecified.
3004
3005 @var{level} is an integer specifying a protocol layer, either
3006 @code{SOL_SOCKET} for socket level options, or a protocol number from
3007 the @code{IPPROTO} constants or @code{getprotoent} (@pxref{Network
3008 Databases}).
3009
3010 @defvar SOL_SOCKET
3011 @defvarx IPPROTO_IP
3012 @defvarx IPPROTO_TCP
3013 @defvarx IPPROTO_UDP
3014 @end defvar
3015
3016 @var{optname} is an integer specifying an option within the protocol
3017 layer.
3018
3019 For @code{SOL_SOCKET} level the following @var{optname}s are defined
3020 (when provided by the system). For their meaning see
3021 @ref{Socket-Level Options,,, libc, The GNU C Library Reference
3022 Manual}, or @command{man 7 socket}.
3023
3024 @defvar SO_DEBUG
3025 @defvarx SO_REUSEADDR
3026 @defvarx SO_STYLE
3027 @defvarx SO_TYPE
3028 @defvarx SO_ERROR
3029 @defvarx SO_DONTROUTE
3030 @defvarx SO_BROADCAST
3031 @defvarx SO_SNDBUF
3032 @defvarx SO_RCVBUF
3033 @defvarx SO_KEEPALIVE
3034 @defvarx SO_OOBINLINE
3035 @defvarx SO_NO_CHECK
3036 @defvarx SO_PRIORITY
3037 The @var{value} taken or returned is an integer.
3038 @end defvar
3039
3040 @defvar SO_LINGER
3041 The @var{value} taken or returned is a pair of integers
3042 @code{(@var{ENABLE} . @var{TIMEOUT})}. On old systems without timeout
3043 support (ie.@: without @code{struct linger}), only @var{ENABLE} has an
3044 effect but the value in Guile is always a pair.
3045 @end defvar
3046
3047 @c Note that we refer only to ``man ip'' here. On GNU/Linux it's
3048 @c ``man 7 ip'' but on NetBSD it's ``man 4 ip''.
3049 @c
3050 For IP level (@code{IPPROTO_IP}) the following @var{optname}s are
3051 defined (when provided by the system). See @command{man ip} for what
3052 they mean.
3053
3054 @defvar IP_MULTICAST_IF
3055 This sets the source interface used by multicast traffic.
3056 @end defvar
3057
3058 @defvar IP_MULTICAST_TTL
3059 This sets the default TTL for multicast traffic. This defaults
3060 to 1 and should be increased to allow traffic to pass beyond the
3061 local network.
3062 @end defvar
3063
3064 @defvar IP_ADD_MEMBERSHIP
3065 @defvarx IP_DROP_MEMBERSHIP
3066 These can be used only with @code{setsockopt}, not @code{getsockopt}.
3067 @var{value} is a pair @code{(@var{MULTIADDR} . @var{INTERFACEADDR})}
3068 of integer IPv4 addresses (@pxref{Network Address Conversion}).
3069 @var{MULTIADDR} is a multicast address to be added to or dropped from
3070 the interface @var{INTERFACEADDR}. @var{INTERFACEADDR} can be
3071 @code{INADDR_ANY} to have the system select the interface.
3072 @var{INTERFACEADDR} can also be an interface index number, on systems
3073 supporting that.
3074 @end defvar
3075 @end deffn
3076
3077 @deffn {Scheme Procedure} shutdown sock how
3078 @deffnx {C Function} scm_shutdown (sock, how)
3079 Sockets can be closed simply by using @code{close-port}. The
3080 @code{shutdown} procedure allows reception or transmission on a
3081 connection to be shut down individually, according to the parameter
3082 @var{how}:
3083
3084 @table @asis
3085 @item 0
3086 Stop receiving data for this socket. If further data arrives, reject it.
3087 @item 1
3088 Stop trying to transmit data from this socket. Discard any
3089 data waiting to be sent. Stop looking for acknowledgement of
3090 data already sent; don't retransmit it if it is lost.
3091 @item 2
3092 Stop both reception and transmission.
3093 @end table
3094
3095 The return value is unspecified.
3096 @end deffn
3097
3098 @deffn {Scheme Procedure} connect sock sockaddr
3099 @deffnx {Scheme Procedure} connect sock AF_INET ipv4addr port
3100 @deffnx {Scheme Procedure} connect sock AF_INET6 ipv6addr port [flowinfo [scopeid]]
3101 @deffnx {Scheme Procedure} connect sock AF_UNIX path
3102 @deffnx {C Function} scm_connect (sock, fam, address, args)
3103 Initiate a connection on socket port @var{sock} to a given address.
3104 The destination is either a socket address object, or arguments the
3105 same as @code{make-socket-address} would take to make such an object
3106 (@pxref{Network Socket Address}). The return value is unspecified.
3107
3108 @example
3109 (connect sock AF_INET INADDR_LOOPBACK 23)
3110 (connect sock (make-socket-address AF_INET INADDR_LOOPBACK 23))
3111 @end example
3112 @end deffn
3113
3114 @deffn {Scheme Procedure} bind sock sockaddr
3115 @deffnx {Scheme Procedure} bind sock AF_INET ipv4addr port
3116 @deffnx {Scheme Procedure} bind sock AF_INET6 ipv6addr port [flowinfo [scopeid]]
3117 @deffnx {Scheme Procedure} bind sock AF_UNIX path
3118 @deffnx {C Function} scm_bind (sock, fam, address, args)
3119 Bind socket port @var{sock} to the given address. The address is
3120 either a socket address object, or arguments the same as
3121 @code{make-socket-address} would take to make such an object
3122 (@pxref{Network Socket Address}). The return value is unspecified.
3123
3124 Generally a socket is only explicitly bound to a particular address
3125 when making a server, i.e.@: to listen on a particular port. For an
3126 outgoing connection the system will assign a local address
3127 automatically, if not already bound.
3128
3129 @example
3130 (bind sock AF_INET INADDR_ANY 12345)
3131 (bind sock (make-socket-address AF_INET INADDR_ANY 12345))
3132 @end example
3133 @end deffn
3134
3135 @deffn {Scheme Procedure} listen sock backlog
3136 @deffnx {C Function} scm_listen (sock, backlog)
3137 Enable @var{sock} to accept connection
3138 requests. @var{backlog} is an integer specifying
3139 the maximum length of the queue for pending connections.
3140 If the queue fills, new clients will fail to connect until
3141 the server calls @code{accept} to accept a connection from
3142 the queue.
3143
3144 The return value is unspecified.
3145 @end deffn
3146
3147 @deffn {Scheme Procedure} accept sock
3148 @deffnx {C Function} scm_accept (sock)
3149 Accept a connection from socket port @var{sock} which has been enabled
3150 for listening with @code{listen} above. If there are no incoming
3151 connections in the queue, wait until one is available (unless
3152 @code{O_NONBLOCK} has been set on the socket, @pxref{Ports and File
3153 Descriptors,@code{fcntl}}).
3154
3155 The return value is a pair. The @code{car} is a new socket port,
3156 connected and ready to communicate. The @code{cdr} is a socket
3157 address object (@pxref{Network Socket Address}) which is where the
3158 remote connection is from (like @code{getpeername} below).
3159
3160 All communication takes place using the new socket returned. The
3161 given @var{sock} remains bound and listening, and @code{accept} may be
3162 called on it again to get another incoming connection when desired.
3163 @end deffn
3164
3165 @deffn {Scheme Procedure} getsockname sock
3166 @deffnx {C Function} scm_getsockname (sock)
3167 Return a socket address object which is the where @var{sock} is bound
3168 locally. @var{sock} may have obtained its local address from
3169 @code{bind} (above), or if a @code{connect} is done with an otherwise
3170 unbound socket (which is usual) then the system will have assigned an
3171 address.
3172
3173 Note that on many systems the address of a socket in the
3174 @code{AF_UNIX} namespace cannot be read.
3175 @end deffn
3176
3177 @deffn {Scheme Procedure} getpeername sock
3178 @deffnx {C Function} scm_getpeername (sock)
3179 Return a socket address object which is where @var{sock} is connected
3180 to, i.e.@: the remote endpoint.
3181
3182 Note that on many systems the address of a socket in the
3183 @code{AF_UNIX} namespace cannot be read.
3184 @end deffn
3185
3186 @deffn {Scheme Procedure} recv! sock buf [flags]
3187 @deffnx {C Function} scm_recv (sock, buf, flags)
3188 Receive data from a socket port.
3189 @var{sock} must already
3190 be bound to the address from which data is to be received.
3191 @var{buf} is a bytevector into which
3192 the data will be written. The size of @var{buf} limits
3193 the amount of
3194 data which can be received: in the case of packet
3195 protocols, if a packet larger than this limit is encountered
3196 then some data
3197 will be irrevocably lost.
3198
3199 @vindex MSG_OOB
3200 @vindex MSG_PEEK
3201 @vindex MSG_DONTROUTE
3202 The optional @var{flags} argument is a value or bitwise OR of
3203 @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
3204
3205 The value returned is the number of bytes read from the
3206 socket.
3207
3208 Note that the data is read directly from the socket file
3209 descriptor:
3210 any unread buffered port data is ignored.
3211 @end deffn
3212
3213 @deffn {Scheme Procedure} send sock message [flags]
3214 @deffnx {C Function} scm_send (sock, message, flags)
3215 @vindex MSG_OOB
3216 @vindex MSG_PEEK
3217 @vindex MSG_DONTROUTE
3218 Transmit bytevector @var{message} on socket port @var{sock}.
3219 @var{sock} must already be bound to a destination address. The value
3220 returned is the number of bytes transmitted---it's possible for this
3221 to be less than the length of @var{message} if the socket is set to be
3222 non-blocking. The optional @var{flags} argument is a value or bitwise
3223 OR of @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
3224
3225 Note that the data is written directly to the socket
3226 file descriptor:
3227 any unflushed buffered port data is ignored.
3228 @end deffn
3229
3230 @deffn {Scheme Procedure} recvfrom! sock buf [flags [start [end]]]
3231 @deffnx {C Function} scm_recvfrom (sock, buf, flags, start, end)
3232 Receive data from socket port @var{sock}, returning the originating
3233 address as well as the data. This function is usually for datagram
3234 sockets, but can be used on stream-oriented sockets too.
3235
3236 The data received is stored in bytevector @var{buf}, using
3237 either the whole bytevector or just the region between the optional
3238 @var{start} and @var{end} positions. The size of @var{buf}
3239 limits the amount of data that can be received. For datagram
3240 protocols if a packet larger than this is received then excess
3241 bytes are irrevocably lost.
3242
3243 The return value is a pair. The @code{car} is the number of bytes
3244 read. The @code{cdr} is a socket address object (@pxref{Network
3245 Socket Address}) which is where the data came from, or @code{#f} if
3246 the origin is unknown.
3247
3248 @vindex MSG_OOB
3249 @vindex MSG_PEEK
3250 @vindex MSG_DONTROUTE
3251 The optional @var{flags} argument is a or bitwise-OR (@code{logior})
3252 of @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
3253
3254 Data is read directly from the socket file descriptor, any buffered
3255 port data is ignored.
3256
3257 @c This was linux kernel 2.6.15 and glibc 2.3.6, not sure what any
3258 @c specs are supposed to say about recvfrom threading.
3259 @c
3260 On a GNU/Linux system @code{recvfrom!} is not multi-threading, all
3261 threads stop while a @code{recvfrom!} call is in progress. An
3262 application may need to use @code{select}, @code{O_NONBLOCK} or
3263 @code{MSG_DONTWAIT} to avoid this.
3264 @end deffn
3265
3266 @deffn {Scheme Procedure} sendto sock message sockaddr [flags]
3267 @deffnx {Scheme Procedure} sendto sock message AF_INET ipv4addr port [flags]
3268 @deffnx {Scheme Procedure} sendto sock message AF_INET6 ipv6addr port [flowinfo [scopeid [flags]]]
3269 @deffnx {Scheme Procedure} sendto sock message AF_UNIX path [flags]
3270 @deffnx {C Function} scm_sendto (sock, message, fam, address, args_and_flags)
3271 Transmit bytevector @var{message} as a datagram socket port
3272 @var{sock}. The destination is specified either as a socket address
3273 object, or as arguments the same as would be taken by
3274 @code{make-socket-address} to create such an object (@pxref{Network
3275 Socket Address}).
3276
3277 The destination address may be followed by an optional @var{flags}
3278 argument which is a @code{logior} (@pxref{Bitwise Operations}) of
3279 @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
3280
3281 The value returned is the number of bytes transmitted --
3282 it's possible for
3283 this to be less than the length of @var{message} if the
3284 socket is
3285 set to be non-blocking.
3286 Note that the data is written directly to the socket
3287 file descriptor:
3288 any unflushed buffered port data is ignored.
3289 @end deffn
3290
3291 The following functions can be used to convert short and long integers
3292 between ``host'' and ``network'' order. Although the procedures above do
3293 this automatically for addresses, the conversion will still need to
3294 be done when sending or receiving encoded integer data from the network.
3295
3296 @deffn {Scheme Procedure} htons value
3297 @deffnx {C Function} scm_htons (value)
3298 Convert a 16 bit quantity from host to network byte ordering.
3299 @var{value} is packed into 2 bytes, which are then converted
3300 and returned as a new integer.
3301 @end deffn
3302
3303 @deffn {Scheme Procedure} ntohs value
3304 @deffnx {C Function} scm_ntohs (value)
3305 Convert a 16 bit quantity from network to host byte ordering.
3306 @var{value} is packed into 2 bytes, which are then converted
3307 and returned as a new integer.
3308 @end deffn
3309
3310 @deffn {Scheme Procedure} htonl value
3311 @deffnx {C Function} scm_htonl (value)
3312 Convert a 32 bit quantity from host to network byte ordering.
3313 @var{value} is packed into 4 bytes, which are then converted
3314 and returned as a new integer.
3315 @end deffn
3316
3317 @deffn {Scheme Procedure} ntohl value
3318 @deffnx {C Function} scm_ntohl (value)
3319 Convert a 32 bit quantity from network to host byte ordering.
3320 @var{value} is packed into 4 bytes, which are then converted
3321 and returned as a new integer.
3322 @end deffn
3323
3324 These procedures are inconvenient to use at present, but consider:
3325
3326 @example
3327 (define write-network-long
3328 (lambda (value port)
3329 (let ((v (make-uniform-vector 1 1 0)))
3330 (uniform-vector-set! v 0 (htonl value))
3331 (uniform-vector-write v port))))
3332
3333 (define read-network-long
3334 (lambda (port)
3335 (let ((v (make-uniform-vector 1 1 0)))
3336 (uniform-vector-read! v port)
3337 (ntohl (uniform-vector-ref v 0)))))
3338 @end example
3339
3340
3341 @node Internet Socket Examples
3342 @subsubsection Network Socket Examples
3343 @cindex network examples
3344 @cindex socket examples
3345
3346 The following give examples of how to use network sockets.
3347
3348 @subsubheading Internet Socket Client Example
3349
3350 @cindex socket client example
3351 The following example demonstrates an Internet socket client.
3352 It connects to the HTTP daemon running on the local machine and
3353 returns the contents of the root index URL.
3354
3355 @example
3356 (let ((s (socket PF_INET SOCK_STREAM 0)))
3357 (connect s AF_INET (inet-pton AF_INET "127.0.0.1") 80)
3358 (display "GET / HTTP/1.0\r\n\r\n" s)
3359
3360 (do ((line (read-line s) (read-line s)))
3361 ((eof-object? line))
3362 (display line)
3363 (newline)))
3364 @end example
3365
3366
3367 @subsubheading Internet Socket Server Example
3368
3369 @cindex socket server example
3370 The following example shows a simple Internet server which listens on
3371 port 2904 for incoming connections and sends a greeting back to the
3372 client.
3373
3374 @example
3375 (let ((s (socket PF_INET SOCK_STREAM 0)))
3376 (setsockopt s SOL_SOCKET SO_REUSEADDR 1)
3377 ;; @r{Specific address?}
3378 ;; @r{(bind s AF_INET (inet-pton AF_INET "127.0.0.1") 2904)}
3379 (bind s AF_INET INADDR_ANY 2904)
3380 (listen s 5)
3381
3382 (simple-format #t "Listening for clients in pid: ~S" (getpid))
3383 (newline)
3384
3385 (while #t
3386 (let* ((client-connection (accept s))
3387 (client-details (cdr client-connection))
3388 (client (car client-connection)))
3389 (simple-format #t "Got new client connection: ~S"
3390 client-details)
3391 (newline)
3392 (simple-format #t "Client address: ~S"
3393 (gethostbyaddr
3394 (sockaddr:addr client-details)))
3395 (newline)
3396 ;; @r{Send back the greeting to the client port}
3397 (display "Hello client\r\n" client)
3398 (close client))))
3399 @end example
3400
3401
3402 @node System Identification
3403 @subsection System Identification
3404 @cindex system name
3405
3406 This section lists the various procedures Guile provides for accessing
3407 information about the system it runs on.
3408
3409 @deffn {Scheme Procedure} uname
3410 @deffnx {C Function} scm_uname ()
3411 Return an object with some information about the computer
3412 system the program is running on.
3413
3414 The following procedures accept an object as returned by @code{uname}
3415 and return a selected component (all of which are strings).
3416
3417 @deffn {Scheme Procedure} utsname:sysname un
3418 The name of the operating system.
3419 @end deffn
3420 @deffn {Scheme Procedure} utsname:nodename un
3421 The network name of the computer.
3422 @end deffn
3423 @deffn {Scheme Procedure} utsname:release un
3424 The current release level of the operating system implementation.
3425 @end deffn
3426 @deffn {Scheme Procedure} utsname:version un
3427 The current version level within the release of the operating system.
3428 @end deffn
3429 @deffn {Scheme Procedure} utsname:machine un
3430 A description of the hardware.
3431 @end deffn
3432 @end deffn
3433
3434 @deffn {Scheme Procedure} gethostname
3435 @deffnx {C Function} scm_gethostname ()
3436 @cindex host name
3437 Return the host name of the current processor.
3438 @end deffn
3439
3440 @deffn {Scheme Procedure} sethostname name
3441 @deffnx {C Function} scm_sethostname (name)
3442 Set the host name of the current processor to @var{name}. May
3443 only be used by the superuser. The return value is not
3444 specified.
3445 @end deffn
3446
3447 @node Locales
3448 @subsection Locales
3449 @cindex locale
3450
3451 @deffn {Scheme Procedure} setlocale category [locale]
3452 @deffnx {C Function} scm_setlocale (category, locale)
3453 Get or set the current locale, used for various internationalizations.
3454 Locales are strings, such as @samp{sv_SE}.
3455
3456 If @var{locale} is given then the locale for the given @var{category}
3457 is set and the new value returned. If @var{locale} is not given then
3458 the current value is returned. @var{category} should be one of the
3459 following values (@pxref{Locale Categories, Categories of Activities
3460 that Locales Affect,, libc, The GNU C Library Reference Manual}):
3461
3462 @defvar LC_ALL
3463 @defvarx LC_COLLATE
3464 @defvarx LC_CTYPE
3465 @defvarx LC_MESSAGES
3466 @defvarx LC_MONETARY
3467 @defvarx LC_NUMERIC
3468 @defvarx LC_TIME
3469 @end defvar
3470
3471 @cindex @code{LANG}
3472 A common usage is @samp{(setlocale LC_ALL "")}, which initializes all
3473 categories based on standard environment variables (@code{LANG} etc).
3474 For full details on categories and locale names @pxref{Locales,,
3475 Locales and Internationalization, libc, The GNU C Library Reference
3476 Manual}.
3477
3478 Note that @code{setlocale} affects locale settings for the whole
3479 process. @xref{i18n Introduction, locale objects and
3480 @code{make-locale}}, for a thread-safe alternative.
3481 @end deffn
3482
3483 @node Encryption
3484 @subsection Encryption
3485 @cindex encryption
3486
3487 Please note that the procedures in this section are not suited for
3488 strong encryption, they are only interfaces to the well-known and
3489 common system library functions of the same name. They are just as good
3490 (or bad) as the underlying functions, so you should refer to your system
3491 documentation before using them (@pxref{crypt,, Encrypting Passwords,
3492 libc, The GNU C Library Reference Manual}).
3493
3494 @deffn {Scheme Procedure} crypt key salt
3495 @deffnx {C Function} scm_crypt (key, salt)
3496 Encrypt @var{key}, with the addition of @var{salt} (both strings),
3497 using the @code{crypt} C library call.
3498 @end deffn
3499
3500 Although @code{getpass} is not an encryption procedure per se, it
3501 appears here because it is often used in combination with @code{crypt}:
3502
3503 @deffn {Scheme Procedure} getpass prompt
3504 @deffnx {C Function} scm_getpass (prompt)
3505 @cindex password
3506 Display @var{prompt} to the standard error output and read
3507 a password from @file{/dev/tty}. If this file is not
3508 accessible, it reads from standard input. The password may be
3509 up to 127 characters in length. Additional characters and the
3510 terminating newline character are discarded. While reading
3511 the password, echoing and the generation of signals by special
3512 characters is disabled.
3513 @end deffn
3514
3515
3516 @c Local Variables:
3517 @c TeX-master: "guile.texi"
3518 @c End: