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