Commit | Line | Data |
---|---|---|
38a93523 NJ |
1 | @node POSIX |
2 | @chapter POSIX System Calls and Networking | |
3 | ||
4 | @menu | |
5 | * Conventions:: Conventions employed by the POSIX interface. | |
6 | * Ports and File Descriptors:: Scheme ``ports'' and Unix file descriptors | |
7 | have different representations. | |
8 | * File System:: stat, chown, chmod, etc. | |
9 | * User Information:: Retrieving a user's GECOS (/etc/passwd) entry. | |
10 | * Time:: gettimeofday, localtime, strftime, etc. | |
11 | * Runtime Environment:: Accessing and modifying Guile's environment. | |
12 | * Processes:: getuid, getpid, etc. | |
13 | * Signals:: sigaction, kill, pause, alarm, etc. | |
14 | * Terminals and Ptys:: ttyname, tcsetpgrp, etc. | |
15 | * Pipes:: Communicating data between processes. | |
16 | * Networking:: gethostbyaddr, getnetent, socket, bind, listen. | |
17 | * System Identification:: `uname' and getting info about this machine. | |
18 | * Locales:: setlocale, etc. | |
19 | @end menu | |
20 | ||
21 | @node Conventions | |
22 | @section POSIX Interface Conventions | |
23 | ||
24 | These interfaces provide access to operating system facilities. | |
25 | They provide a simple wrapping around the underlying C interfaces | |
26 | to make usage from Scheme more convenient. They are also used | |
27 | to implement the Guile port of @ref{The Scheme shell (scsh)}. | |
28 | ||
29 | Generally there is a single procedure for each corresponding Unix | |
30 | facility. There are some exceptions, such as procedures implemented for | |
31 | speed and convenience in Scheme with no primitive Unix equivalent, | |
32 | e.g., @code{copy-file}. | |
33 | ||
34 | The interfaces are intended as far as possible to be portable across | |
35 | different versions of Unix. In some cases procedures which can't be | |
36 | implemented on particular systems may become no-ops, or perform limited | |
37 | actions. In other cases they may throw errors. | |
38 | ||
39 | General naming conventions are as follows: | |
40 | ||
41 | @itemize @bullet | |
42 | @item | |
43 | The Scheme name is often identical to the name of the underlying Unix | |
44 | facility. | |
45 | @item | |
46 | Underscores in Unix procedure names are converted to hyphens. | |
47 | @item | |
48 | Procedures which destructively modify Scheme data have exclaimation | |
49 | marks appended, e.g., @code{recv!}. | |
50 | @item | |
51 | Predicates (returning only @code{#t} or @code{#f}) have question marks | |
52 | appended, e.g., @code{access?}. | |
53 | @item | |
54 | Some names are changed to avoid conflict with dissimilar interfaces | |
55 | defined by scsh, e.g., @code{primitive-fork}. | |
56 | @item | |
57 | Unix preprocessor names such as @code{EPERM} or @code{R_OK} are converted | |
58 | to Scheme variables of the same name (underscores are not replaced | |
59 | with hyphens). | |
60 | @end itemize | |
61 | ||
62 | Unexpected conditions are generally handled by raising exceptions. | |
63 | There are a few procedures which return a special value if they don't | |
64 | succeed, e.g., @code{getenv} returns @code{#f} if it the requested | |
65 | string is not found in the environment. These cases are noted in | |
66 | the documentation. | |
67 | ||
68 | For ways to deal with exceptions, @ref{Exceptions}. | |
69 | ||
70 | Errors which the C-library would report by returning a NULL | |
71 | pointer or through some other means are reported by raising a | |
72 | @code{system-error} exception. | |
73 | The value of the Unix @code{errno} variable is available | |
74 | in the data passed by the exception. | |
75 | ||
76 | Here's an ad-hoc@footnote{This may be changed in the future; be prepared | |
77 | to rewrite this sort of code.} way to extract the @code{errno} value | |
78 | from an exception: | |
79 | ||
80 | @example | |
81 | (catch | |
82 | 'system-error | |
83 | (lambda () | |
84 | (mkdir "/this-ought-to-fail-if-I'm-not-root")) | |
85 | (lambda stuff | |
86 | (let ((errno (car (list-ref stuff 4)))) | |
87 | (cond | |
88 | ((= errno EACCES) | |
89 | (display "You're not allowed to do that.")) | |
90 | ((= errno EEXIST) | |
91 | (display "Already exists.")) | |
92 | (#t | |
93 | (display (strerror errno)))) | |
94 | (newline)))) | |
95 | @end example | |
96 | ||
97 | The important thing to note is that the @code{errno} value can be | |
98 | extracted with @code{(car (list-ref stuff 4))}. | |
99 | ||
100 | @node Ports and File Descriptors | |
101 | @section Ports and File Descriptors | |
102 | ||
103 | Conventions generally follow those of scsh, @ref{The Scheme shell (scsh)}. | |
104 | ||
105 | File ports are implemented using low-level operating system I/O | |
106 | facilities, with optional buffering to improve efficiency | |
107 | @pxref{File Ports} | |
108 | ||
109 | Note that some procedures (e.g., @code{recv!}) will accept ports as | |
110 | arguments, but will actually operate directly on the file descriptor | |
111 | underlying the port. Any port buffering is ignored, including the | |
112 | buffer which implements @code{peek-char} and @code{unread-char}. | |
113 | ||
114 | The @code{force-output} and @code{drain-input} procedures can be used | |
115 | to clear the buffers. | |
116 | ||
117 | Each open file port has an associated operating system file descriptor. | |
118 | File descriptors are generally not useful in Scheme programs; however | |
119 | they may be needed when interfacing with foreign code and the Unix | |
120 | environment. | |
121 | ||
122 | A file descriptor can be extracted from a port and a new port can be | |
123 | created from a file descriptor. However a file descriptor is just an | |
124 | integer and the garbage collector doesn't recognise it as a reference | |
125 | to the port. If all other references to the port were dropped, then | |
126 | it's likely that the garbage collector would free the port, with the | |
127 | side-effect of closing the file descriptor prematurely. | |
128 | ||
129 | To assist the programmer in avoiding this problem, each port has an | |
130 | associated "revealed count" which can be used to keep track of how many | |
131 | times the underlying file descriptor has been stored in other places. | |
132 | If a port's revealed count is greater than zero, the file descriptor | |
133 | will not be closed when the port is gabage collected. A programmer | |
134 | can therefore ensure that the revealed count will be greater than | |
135 | zero if the file descriptor is needed elsewhere. | |
136 | ||
137 | For the simple case where a file descriptor is "imported" once to become | |
138 | a port, it does not matter if the file descriptor is closed when the | |
139 | port is garbage collected. There is no need to maintain a revealed | |
140 | count. Likewise when "exporting" a file descriptor to the external | |
141 | environment, setting the revealed count is not required provided the | |
142 | port is kept open (i.e., is pointed to by a live Scheme binding) while | |
143 | the file descriptor is in use. | |
144 | ||
145 | To correspond with traditional Unix behaviour, the three file | |
146 | descriptors (0, 1 and 2) are automatically imported when a program | |
147 | starts up and assigned to the initial values of the current input, | |
148 | output and error ports. The revealed count for each is initially set to | |
149 | one, so that dropping references to one of these ports will not result | |
150 | in its garbage collection: it could be retrieved with fdopen or | |
151 | fdes->ports. | |
152 | ||
153 | @c docstring begin (texi-doc-string "guile" "port-revealed") | |
154 | @deffn primitive port-revealed port | |
155 | Returns the revealed count for @var{port}. | |
156 | @end deffn | |
157 | ||
158 | @c docstring begin (texi-doc-string "guile" "set-port-revealed!") | |
159 | @deffn primitive set-port-revealed! port rcount | |
160 | Sets the revealed count for a port to a given value. | |
161 | The return value is unspecified. | |
162 | @end deffn | |
163 | ||
164 | @c docstring begin (texi-doc-string "guile" "fileno") | |
165 | @deffn primitive fileno port | |
166 | Returns the integer file descriptor underlying @var{port}. | |
167 | Does not change its revealed count. | |
168 | @end deffn | |
169 | ||
170 | @deffn procedure port->fdes port | |
171 | Returns the integer file descriptor underlying @var{port}. As a | |
172 | side effect the revealed count of @var{port} is incremented. | |
173 | @end deffn | |
174 | ||
175 | @c docstring begin (texi-doc-string "guile" "fdopen") | |
176 | @deffn primitive fdopen fdes modes | |
177 | Returns a new port based on the file descriptor @var{fdes}. | |
178 | Modes are given by the string @var{modes}. The revealed count of the port | |
179 | is initialized to zero. The modes string is the same as that accepted | |
180 | by @ref{File Ports, open-file}. | |
181 | @end deffn | |
182 | ||
183 | @c docstring begin (texi-doc-string "guile" "fdes->ports") | |
184 | @deffn primitive fdes->ports fd | |
185 | Returns a list of existing ports which have @var{fdes} as an | |
186 | underlying file descriptor, without changing their revealed counts. | |
187 | @end deffn | |
188 | ||
189 | @deffn procedure fdes->inport fdes | |
190 | Returns an existing input port which has @var{fdes} as its underlying file | |
191 | descriptor, if one exists, and increments its revealed count. | |
192 | Otherwise, returns a new input port with a revealed count of 1. | |
193 | @end deffn | |
194 | ||
195 | @deffn procedure fdes->outport fdes | |
196 | Returns an existing output port which has @var{fdes} as its underlying file | |
197 | descriptor, if one exists, and increments its revealed count. | |
198 | Otherwise, returns a new output port with a revealed count of 1. | |
199 | @end deffn | |
200 | ||
201 | @c docstring begin (texi-doc-string "guile" "primitive-move->fdes") | |
202 | @deffn primitive primitive-move->fdes port fd | |
203 | Moves the underlying file descriptor for @var{port} to the integer | |
204 | value @var{fdes} without changing the revealed count of @var{port}. | |
205 | Any other ports already using this descriptor will be automatically | |
206 | shifted to new descriptors and their revealed counts reset to zero. | |
207 | The return value is @code{#f} if the file descriptor already had the | |
208 | required value or @code{#t} if it was moved. | |
209 | @end deffn | |
210 | ||
211 | @deffn procedure move->fdes port fdes | |
212 | Moves the underlying file descriptor for @var{port} to the integer | |
213 | value @var{fdes} and sets its revealed count to one. Any other ports | |
214 | already using this descriptor will be automatically | |
215 | shifted to new descriptors and their revealed counts reset to zero. | |
216 | The return value is unspecified. | |
217 | @end deffn | |
218 | ||
219 | @deffn procedure release-port-handle port | |
220 | Decrements the revealed count for a port. | |
221 | @end deffn | |
222 | ||
223 | @c docstring begin (texi-doc-string "guile" "fsync") | |
224 | @deffn primitive fsync object | |
225 | Copies any unwritten data for the specified output file descriptor to disk. | |
226 | If @var{port/fd} is a port, its buffer is flushed before the underlying | |
227 | file descriptor is fsync'd. | |
228 | The return value is unspecified. | |
229 | @end deffn | |
230 | ||
231 | @c docstring begin (texi-doc-string "guile" "open") | |
232 | @deffn primitive open path flags [mode] | |
233 | Open the file named by @var{path} for reading and/or writing. | |
234 | @var{flags} is an integer specifying how the file should be opened. | |
235 | @var{mode} is an integer specifying the permission bits of the file, if | |
236 | it needs to be created, before the umask is applied. The default is 666 | |
237 | (Unix itself has no default). | |
238 | ||
239 | @var{flags} can be constructed by combining variables using @code{logior}. | |
240 | Basic flags are: | |
241 | ||
242 | @defvar O_RDONLY | |
243 | Open the file read-only. | |
244 | @end defvar | |
245 | @defvar O_WRONLY | |
246 | Open the file write-only. | |
247 | @end defvar | |
248 | @defvar O_RDWR | |
249 | Open the file read/write. | |
250 | @end defvar | |
251 | @defvar O_APPEND | |
252 | Append to the file instead of truncating. | |
253 | @end defvar | |
254 | @defvar O_CREAT | |
255 | Create the file if it does not already exist. | |
256 | @end defvar | |
257 | ||
258 | See the Unix documentation of the @code{open} system call | |
259 | for additional flags. | |
260 | @end deffn | |
261 | ||
262 | @c docstring begin (texi-doc-string "guile" "open-fdes") | |
263 | @deffn primitive open-fdes path flags [mode] | |
264 | Similar to @code{open} but returns a file descriptor instead of a | |
265 | port. | |
266 | @end deffn | |
267 | ||
268 | @c docstring begin (texi-doc-string "guile" "close") | |
269 | @deffn primitive close fd_or_port | |
270 | Similar to close-port (@pxref{Closing, close-port}), but also works on | |
271 | file descriptors. A side effect of closing a file descriptor is that | |
272 | any ports using that file descriptor are moved to a different file | |
273 | descriptor and have their revealed counts set to zero. | |
274 | @end deffn | |
275 | ||
276 | @c docstring begin (texi-doc-string "guile" "close-fdes") | |
277 | @deffn primitive close-fdes fd | |
278 | A simple wrapper for the @code{close} system call. | |
279 | Close file descriptor @var{fd}, which must be an integer. | |
280 | Unlike close (@pxref{Ports and File Descriptors, close}), | |
281 | the file descriptor will be closed even if a port is using it. | |
282 | The return value is unspecified. | |
283 | @end deffn | |
284 | ||
285 | @c docstring begin (texi-doc-string "guile" "unread-char") | |
286 | @deffn primitive unread-char char [port] | |
287 | Place @var{char} in @var{port} so that it will be read by the | |
288 | next read operation. If called multiple times, the unread characters | |
289 | will be read again in last-in first-out order. If @var{port} is | |
290 | not supplied, the current input port is used. | |
291 | @end deffn | |
292 | ||
293 | @c docstring begin (texi-doc-string "guile" "unread-string") | |
294 | @deffn primitive unread-string str port | |
295 | Place the string @var{str} in @var{port} so that its characters will be | |
296 | read in subsequent read operations. If called multiple times, the | |
297 | unread characters will be read again in last-in first-out order. If | |
298 | @var{port} is not supplied, the current-input-port is used. | |
299 | @end deffn | |
300 | ||
301 | @c docstring begin (texi-doc-string "guile" "pipe") | |
302 | @deffn primitive pipe | |
303 | Returns a newly created pipe: a pair of ports which are linked | |
304 | together on the local machine. The CAR is the input port and | |
305 | the CDR is the output port. Data written (and flushed) to the | |
306 | output port can be read from the input port. | |
307 | Pipes are commonly used for communication with a newly | |
308 | forked child process. The need to flush the output port | |
309 | can be avoided by making it unbuffered using @code{setvbuf}. | |
310 | ||
311 | Writes occur atomically provided the size of the data in | |
312 | bytes is not greater than the value of @code{PIPE_BUF} | |
313 | Note that the output port is likely to block if too much data | |
314 | (typically equal to @code{PIPE_BUF}) has been written but not | |
315 | yet read from the input port. | |
316 | @end deffn | |
317 | ||
318 | The next group of procedures perform a @code{dup2} | |
319 | system call, if @var{newfd} (an | |
320 | integer) is supplied, otherwise a @code{dup}. The file descriptor to be | |
321 | duplicated can be supplied as an integer or contained in a port. The | |
322 | type of value returned varies depending on which procedure is used. | |
323 | ||
324 | All procedures also have the side effect when performing @code{dup2} that any | |
325 | ports using @var{newfd} are moved to a different file descriptor and have | |
326 | their revealed counts set to zero. | |
327 | ||
328 | @c docstring begin (texi-doc-string "guile" "dup->fdes") | |
329 | @deffn primitive dup->fdes fd_or_port [fd] | |
330 | Returns an integer file descriptor. | |
331 | @end deffn | |
332 | ||
333 | @deffn procedure dup->inport port/fd [newfd] | |
334 | Returns a new input port using the new file descriptor. | |
335 | @end deffn | |
336 | ||
337 | @deffn procedure dup->outport port/fd [newfd] | |
338 | Returns a new output port using the new file descriptor. | |
339 | @end deffn | |
340 | ||
341 | @deffn procedure dup port/fd [newfd] | |
342 | Returns a new port if @var{port/fd} is a port, with the same mode as the | |
343 | supplied port, otherwise returns an integer file descriptor. | |
344 | @end deffn | |
345 | ||
346 | @deffn procedure dup->port port/fd mode [newfd] | |
347 | Returns a new port using the new file descriptor. @var{mode} supplies a | |
348 | mode string for the port (@pxref{File Ports, open-file}). | |
349 | @end deffn | |
350 | ||
351 | @deffn procedure duplicate-port port modes | |
352 | Returns a new port which is opened on a duplicate of the file | |
353 | descriptor underlying @var{port}, with mode string @var{modes} | |
354 | as for @ref{File Ports, open-file}. The two ports | |
355 | will share a file position and file status flags. | |
356 | ||
357 | Unexpected behaviour can result if both ports are subsequently used | |
358 | and the original and/or duplicate ports are buffered. | |
359 | The mode string can include @code{0} to obtain an unbuffered duplicate | |
360 | port. | |
361 | ||
362 | This procedure is equivalent to @code{(dup->port @var{port} @var{modes})}. | |
363 | @end deffn | |
364 | ||
365 | @c docstring begin (texi-doc-string "guile" "redirect-port") | |
366 | @deffn primitive redirect-port old new | |
367 | This procedure takes two ports and duplicates the underlying file | |
368 | descriptor from @var{old-port} into @var{new-port}. The | |
369 | current file descriptor in @var{new-port} will be closed. | |
370 | After the redirection the two ports will share a file position | |
371 | and file status flags. | |
372 | ||
373 | The return value is unspecified. | |
374 | ||
375 | Unexpected behaviour can result if both ports are subsequently used | |
376 | and the original and/or duplicate ports are buffered. | |
377 | ||
378 | This procedure does not have any side effects on other ports or | |
379 | revealed counts. | |
380 | @end deffn | |
381 | ||
382 | @c docstring begin (texi-doc-string "guile" "dup2") | |
383 | @deffn primitive dup2 oldfd newfd | |
384 | A simple wrapper for the @code{dup2} system call. | |
385 | Copies the file descriptor @var{oldfd} to descriptor | |
386 | number @var{newfd}, replacing the previous meaning | |
387 | of @var{newfd}. Both @var{oldfd} and @var{newfd} must | |
388 | be integers. | |
389 | Unlike for dup->fdes or primitive-move->fdes, no attempt | |
390 | is made to move away ports which are using @var{newfd}. | |
391 | The return value is unspecified. | |
392 | @end deffn | |
393 | ||
394 | @c docstring begin (texi-doc-string "guile" "port-mode") | |
395 | @deffn primitive port-mode port | |
396 | Returns the port modes associated with the open port @var{port}. These | |
397 | will not necessarily be identical to the modes used when the port was | |
398 | opened, since modes such as "append" which are used only during | |
399 | port creation are not retained. | |
400 | @end deffn | |
401 | ||
402 | @c docstring begin (texi-doc-string "guile" "close-all-ports-except") | |
403 | @deffn primitive close-all-ports-except . ports | |
404 | [DEPRECATED] Close all open file ports used by the interpreter | |
405 | except for those supplied as arguments. This procedure | |
406 | was intended to be used before an exec call to close file descriptors | |
407 | which are not needed in the new process. However it has the | |
408 | undesirable side-effect of flushing buffes, so it's deprecated. | |
409 | Use port-for-each instead. | |
410 | @end deffn | |
411 | ||
412 | @c docstring begin (texi-doc-string "guile" "port-for-each") | |
413 | @deffn primitive port-for-each proc | |
414 | Apply @var{proc} to each port in the Guile port table | |
415 | in turn. The return value is unspecified. More specifically, | |
416 | @var{proc} is applied exactly once to every port that exists | |
417 | in the system at the time @var{port-for-each} is invoked. | |
418 | Changes to the port table while @var{port-for-each} is running | |
419 | have no effect as far as @var{port-for-each} is concerned. | |
420 | @end deffn | |
421 | ||
422 | @c docstring begin (texi-doc-string "guile" "setvbuf") | |
423 | @deffn primitive setvbuf port mode [size] | |
424 | Set the buffering mode for @var{port}. @var{mode} can be: | |
425 | @table @code | |
426 | @item _IONBF | |
427 | non-buffered | |
428 | @item _IOLBF | |
429 | line buffered | |
430 | @item _IOFBF | |
431 | block buffered, using a newly allocated buffer of @var{size} bytes. | |
432 | If @var{size} is omitted, a default size will be used. | |
433 | @end table | |
434 | @end deffn | |
435 | ||
436 | @c docstring begin (texi-doc-string "guile" "fcntl") | |
437 | @deffn primitive fcntl object cmd [value] | |
438 | Apply @var{command} to the specified file descriptor or the underlying | |
439 | file descriptor of the specified port. @var{value} is an optional | |
440 | integer argument. | |
441 | ||
442 | Values for @var{command} are: | |
443 | ||
444 | @table @code | |
445 | @item F_DUPFD | |
446 | Duplicate a file descriptor | |
447 | @item F_GETFD | |
448 | Get flags associated with the file descriptor. | |
449 | @item F_SETFD | |
450 | Set flags associated with the file descriptor to @var{value}. | |
451 | @item F_GETFL | |
452 | Get flags associated with the open file. | |
453 | @item F_SETFL | |
454 | Set flags associated with the open file to @var{value} | |
455 | @item F_GETOWN | |
456 | Get the process ID of a socket's owner, for @code{SIGIO} signals. | |
457 | @item F_SETOWN | |
458 | Set the process that owns a socket to @var{value}, for @code{SIGIO} signals. | |
459 | @item FD_CLOEXEC | |
460 | The value used to indicate the "close on exec" flag with @code{F_GETFL} or | |
461 | @code{F_SETFL}. | |
462 | @end table | |
463 | @end deffn | |
464 | ||
465 | @c docstring begin (texi-doc-string "guile" "select") | |
466 | @deffn primitive select reads writes excepts [secs [usecs]] | |
467 | This procedure has a variety of uses: waiting for the ability | |
468 | to provide input, accept output, or the existance of | |
469 | exceptional conditions on a collection of ports or file | |
470 | descriptors, or waiting for a timeout to occur. | |
471 | It also returns if interrupted by a signal. | |
472 | ||
473 | @var{reads}, @var{writes} and @var{excepts} can be lists or | |
474 | vectors, with each member a port or a file descriptor. | |
475 | The value returned is a list of three corresponding | |
476 | lists or vectors containing only the members which meet the | |
477 | specified requirement. The ability of port buffers to | |
478 | provide input or accept output is taken into account. | |
479 | Ordering of the input lists or vectors is not preserved. | |
480 | ||
481 | The optional arguments @var{secs} and @var{usecs} specify the | |
482 | timeout. Either @var{secs} can be specified alone, as | |
483 | either an integer or a real number, or both @var{secs} and | |
484 | @var{usecs} can be specified as integers, in which case | |
485 | @var{usecs} is an additional timeout expressed in | |
486 | microseconds. If @var{secs} is omitted or is @code{#f} then | |
487 | select will wait for as long as it takes for one of the other | |
488 | conditions to be satisfied. | |
489 | ||
490 | The scsh version of @code{select} differs as follows: | |
491 | Only vectors are accepted for the first three arguments. | |
492 | The @var{usecs} argument is not supported. | |
493 | Multiple values are returned instead of a list. | |
494 | Duplicates in the input vectors appear only once in output. | |
495 | An additional @code{select!} interface is provided. | |
496 | @end deffn | |
497 | ||
498 | @node File System | |
499 | @section File System | |
500 | ||
501 | These procedures allow querying and setting file system attributes | |
502 | (such as owner, | |
503 | permissions, sizes and types of files); deleting, copying, renaming and | |
504 | linking files; creating and removing directories and querying their | |
505 | contents; syncing the file system and creating special files. | |
506 | ||
507 | @c docstring begin (texi-doc-string "guile" "access?") | |
508 | @deffn primitive access? path how | |
509 | Returns @code{#t} if @var{path} corresponds to an existing | |
510 | file and the current process | |
511 | has the type of access specified by @var{how}, otherwise | |
512 | @code{#f}. | |
513 | @var{how} should be specified | |
514 | using the values of the variables listed below. Multiple values can | |
515 | be combined using a bitwise or, in which case @code{#t} will only | |
516 | be returned if all accesses are granted. | |
517 | ||
518 | Permissions are checked using the real id of the current process, | |
519 | not the effective id, although it's the effective id which determines | |
520 | whether the access would actually be granted. | |
521 | ||
522 | @defvar R_OK | |
523 | test for read permission. | |
524 | @end defvar | |
525 | @defvar W_OK | |
526 | test for write permission. | |
527 | @end defvar | |
528 | @defvar X_OK | |
529 | test for execute permission. | |
530 | @end defvar | |
531 | @defvar F_OK | |
532 | test for existence of the file. | |
533 | @end defvar | |
534 | @end deffn | |
535 | ||
536 | @findex fstat | |
537 | @c docstring begin (texi-doc-string "guile" "stat") | |
538 | @deffn primitive stat object | |
539 | Returns an object containing various information | |
540 | about the file determined by @var{obj}. | |
541 | @var{obj} can be a string containing a file name or a port or integer file | |
542 | descriptor which is open on a file (in which case @code{fstat} is used | |
543 | as the underlying system call). | |
544 | ||
545 | The object returned by @code{stat} can be passed as a single parameter | |
546 | to the following procedures, all of which return integers: | |
547 | ||
548 | @table @code | |
549 | @item stat:dev | |
550 | The device containing the file. | |
551 | @item stat:ino | |
552 | The file serial number, which distinguishes this file from all other | |
553 | files on the same device. | |
554 | @item stat:mode | |
555 | The mode of the file. This includes file type information | |
556 | and the file permission bits. See @code{stat:type} and @code{stat:perms} | |
557 | below. | |
558 | @item stat:nlink | |
559 | The number of hard links to the file. | |
560 | @item stat:uid | |
561 | The user ID of the file's owner. | |
562 | @item stat:gid | |
563 | The group ID of the file. | |
564 | @item stat:rdev | |
565 | Device ID; this entry is defined only for character or block | |
566 | special files. | |
567 | @item stat:size | |
568 | The size of a regular file in bytes. | |
569 | @item stat:atime | |
570 | The last access time for the file. | |
571 | @item stat:mtime | |
572 | The last modification time for the file. | |
573 | @item stat:ctime | |
574 | The last modification time for the attributes of the file. | |
575 | @item stat:blksize | |
576 | The optimal block size for reading or writing the file, in bytes. | |
577 | @item stat:blocks | |
578 | The amount of disk space that the file occupies measured in units of | |
579 | 512 byte blocks. | |
580 | @end table | |
581 | ||
582 | In addition, the following procedures return the information | |
583 | from stat:mode in a more convenient form: | |
584 | ||
585 | @table @code | |
586 | @item stat:type | |
587 | A symbol representing the type of file. Possible values are | |
588 | regular, directory, symlink, block-special, char-special, | |
589 | fifo, socket and unknown | |
590 | @item stat:perms | |
591 | An integer representing the access permission bits. | |
592 | @end table | |
593 | @end deffn | |
594 | ||
595 | @c docstring begin (texi-doc-string "guile" "lstat") | |
596 | @deffn primitive lstat str | |
597 | Similar to @code{stat}, but does not follow symbolic links, i.e., | |
598 | it will return information about a symbolic link itself, not the | |
599 | file it points to. @var{path} must be a string. | |
600 | @end deffn | |
601 | ||
602 | @c docstring begin (texi-doc-string "guile" "readlink") | |
603 | @deffn primitive readlink path | |
604 | Returns the value of the symbolic link named by | |
605 | @var{path} (a string), i.e., the | |
606 | file that the link points to. | |
607 | @end deffn | |
608 | ||
609 | @findex fchown | |
610 | @findex lchown | |
611 | @c docstring begin (texi-doc-string "guile" "chown") | |
612 | @deffn primitive chown object owner group | |
613 | Change the ownership and group of the file referred to by @var{object} to | |
614 | the integer values @var{owner} and @var{group}. @var{object} can be | |
615 | a string containing a file name or, if the platform | |
616 | supports fchown, a port or integer file descriptor | |
617 | which is open on the file. The return value | |
618 | is unspecified. | |
619 | ||
620 | If @var{object} is a symbolic link, either the | |
621 | ownership of the link or the ownership of the referenced file will be | |
622 | changed depending on the operating system (lchown is | |
623 | unsupported at present). If @var{owner} or @var{group} is specified | |
624 | as @code{-1}, then that ID is not changed. | |
625 | @end deffn | |
626 | ||
627 | @findex fchmod | |
628 | @c docstring begin (texi-doc-string "guile" "chmod") | |
629 | @deffn primitive chmod object mode | |
630 | Changes the permissions of the file referred to by @var{obj}. | |
631 | @var{obj} can be a string containing a file name or a port or integer file | |
632 | descriptor which is open on a file (in which case @code{fchmod} is used | |
633 | as the underlying system call). | |
634 | @var{mode} specifies | |
635 | the new permissions as a decimal number, e.g., @code{(chmod "foo" #o755)}. | |
636 | The return value is unspecified. | |
637 | @end deffn | |
638 | ||
639 | @c docstring begin (texi-doc-string "guile" "utime") | |
640 | @deffn primitive utime pathname [actime [modtime]] | |
641 | @code{utime} sets the access and modification times for | |
642 | the file named by @var{path}. If @var{actime} or @var{modtime} | |
643 | is not supplied, then the current time is used. | |
644 | @var{actime} and @var{modtime} | |
645 | must be integer time values as returned by the @code{current-time} | |
646 | procedure. | |
647 | ||
648 | E.g., | |
649 | ||
650 | @smalllisp | |
651 | (utime "foo" (- (current-time) 3600)) | |
652 | @end smalllisp | |
653 | ||
654 | will set the access time to one hour in the past and the modification | |
655 | time to the current time. | |
656 | @end deffn | |
657 | ||
658 | @findex unlink | |
659 | @c docstring begin (texi-doc-string "guile" "delete-file") | |
660 | @deffn primitive delete-file str | |
661 | Deletes (or "unlinks") the file specified by @var{path}. | |
662 | @end deffn | |
663 | ||
664 | @c docstring begin (texi-doc-string "guile" "copy-file") | |
665 | @deffn primitive copy-file oldfile newfile | |
666 | Copy the file specified by @var{path-from} to @var{path-to}. | |
667 | The return value is unspecified. | |
668 | @end deffn | |
669 | ||
670 | @findex rename | |
671 | @c docstring begin (texi-doc-string "guile" "rename-file") | |
672 | @deffn primitive rename-file oldname newname | |
673 | Renames the file specified by @var{oldname} to @var{newname}. | |
674 | The return value is unspecified. | |
675 | @end deffn | |
676 | ||
677 | @c docstring begin (texi-doc-string "guile" "link") | |
678 | @deffn primitive link oldpath newpath | |
679 | Creates a new name @var{newpath} in the file system for the | |
680 | file named by @var{oldpath}. If @var{oldpath} is a symbolic | |
681 | link, the link may or may not be followed depending on the | |
682 | system. | |
683 | @end deffn | |
684 | ||
685 | @c docstring begin (texi-doc-string "guile" "symlink") | |
686 | @deffn primitive symlink oldpath newpath | |
687 | Create a symbolic link named @var{path-to} with the value (i.e., pointing to) | |
688 | @var{path-from}. The return value is unspecified. | |
689 | @end deffn | |
690 | ||
691 | @c docstring begin (texi-doc-string "guile" "mkdir") | |
692 | @deffn primitive mkdir path [mode] | |
693 | Create a new directory named by @var{path}. If @var{mode} is omitted | |
694 | then the permissions of the directory file are set using the current | |
695 | umask. Otherwise they are set to the decimal value specified with | |
696 | @var{mode}. The return value is unspecified. | |
697 | @end deffn | |
698 | ||
699 | @c docstring begin (texi-doc-string "guile" "rmdir") | |
700 | @deffn primitive rmdir path | |
701 | Remove the existing directory named by @var{path}. The directory must | |
702 | be empty for this to succeed. The return value is unspecified. | |
703 | @end deffn | |
704 | ||
705 | @c docstring begin (texi-doc-string "guile" "opendir") | |
706 | @deffn primitive opendir dirname | |
707 | Open the directory specified by @var{path} and return a directory | |
708 | stream. | |
709 | @end deffn | |
710 | ||
711 | @c docstring begin (texi-doc-string "guile" "directory-stream?") | |
712 | @deffn primitive directory-stream? obj | |
713 | Returns a boolean indicating whether @var{object} is a directory stream | |
714 | as returned by @code{opendir}. | |
715 | @end deffn | |
716 | ||
717 | @c docstring begin (texi-doc-string "guile" "readdir") | |
718 | @deffn primitive readdir port | |
719 | Return (as a string) the next directory entry from the directory stream | |
720 | @var{stream}. If there is no remaining entry to be read then the | |
721 | end of file object is returned. | |
722 | @end deffn | |
723 | ||
724 | @c docstring begin (texi-doc-string "guile" "rewinddir") | |
725 | @deffn primitive rewinddir port | |
726 | Reset the directory port @var{stream} so that the next call to | |
727 | @code{readdir} will return the first directory entry. | |
728 | @end deffn | |
729 | ||
730 | @c docstring begin (texi-doc-string "guile" "closedir") | |
731 | @deffn primitive closedir port | |
732 | Close the directory stream @var{stream}. | |
733 | The return value is unspecified. | |
734 | @end deffn | |
735 | ||
736 | @c docstring begin (texi-doc-string "guile" "sync") | |
737 | @deffn primitive sync | |
738 | Flush the operating system disk buffers. | |
739 | The return value is unspecified. | |
740 | @end deffn | |
741 | ||
742 | @c docstring begin (texi-doc-string "guile" "mknod") | |
743 | @deffn primitive mknod path type perms dev | |
744 | Creates a new special file, such as a file corresponding to a device. | |
745 | @var{path} specifies the name of the file. @var{type} should | |
746 | be one of the following symbols: | |
747 | regular, directory, symlink, block-special, char-special, | |
748 | fifo, or socket. @var{perms} (an integer) specifies the file permissions. | |
749 | @var{dev} (an integer) specifies which device the special file refers | |
750 | to. Its exact interpretation depends on the kind of special file | |
751 | being created. | |
752 | ||
753 | E.g., | |
754 | @example | |
755 | (mknod "/dev/fd0" 'block-special #o660 (+ (* 2 256) 2)) | |
756 | @end example | |
757 | ||
758 | The return value is unspecified. | |
759 | @end deffn | |
760 | ||
761 | @c docstring begin (texi-doc-string "guile" "tmpnam") | |
762 | @deffn primitive tmpnam | |
780ee65e NJ |
763 | tmpnam returns a name in the file system that does not match |
764 | any existing file. However there is no guarantee that | |
765 | another process will not create the file after tmpnam | |
766 | is called. Care should be taken if opening the file, | |
767 | e.g., use the O_EXCL open flag or use @code{mkstemp!} instead. | |
38a93523 NJ |
768 | @end deffn |
769 | ||
770 | @c docstring begin (texi-doc-string "guile" "dirname") | |
771 | @deffn primitive dirname filename | |
772 | Return the directory name component of the file name | |
773 | @var{filename}. If @var{filename} does not contain a directory | |
774 | component, @code{.} is returned. | |
775 | @end deffn | |
776 | ||
777 | @c docstring begin (texi-doc-string "guile" "basename") | |
778 | @deffn primitive basename filename [suffix] | |
779 | Return the base name of the file name @var{filename}. The | |
780 | base name is the file name without any directory components. | |
781 | If @var{suffix} is privided, and is equal to the end of | |
782 | @var{basename}, it is removed also. | |
783 | @end deffn | |
784 | ||
785 | ||
786 | @node User Information | |
787 | @section User Information | |
788 | ||
789 | The facilities in this section provide an interface to the user and | |
790 | group database. | |
791 | They should be used with care since they are not reentrant. | |
792 | ||
793 | The following functions accept an object representing user information | |
794 | and return a selected component: | |
795 | ||
796 | @table @code | |
797 | @item passwd:name | |
798 | The name of the userid. | |
799 | @item passwd:passwd | |
800 | The encrypted passwd. | |
801 | @item passwd:uid | |
802 | The user id number. | |
803 | @item passwd:gid | |
804 | The group id number. | |
805 | @item passwd:gecos | |
806 | The full name. | |
807 | @item passwd:dir | |
808 | The home directory. | |
809 | @item passwd:shell | |
810 | The login shell. | |
811 | @end table | |
812 | ||
813 | @deffn procedure getpwuid uid | |
814 | Look up an integer userid in the user database. | |
815 | @end deffn | |
816 | ||
817 | @deffn procedure getpwnam name | |
818 | Look up a user name string in the user database. | |
819 | @end deffn | |
820 | ||
821 | @deffn procedure setpwent | |
822 | Initializes a stream used by @code{getpwent} to read from the user database. | |
823 | The next use of @code{getpwent} will return the first entry. The | |
824 | return value is unspecified. | |
825 | @end deffn | |
826 | ||
827 | @deffn procedure getpwent | |
828 | Return the next entry in the user database, using the stream set by | |
829 | @code{setpwent}. | |
830 | @end deffn | |
831 | ||
832 | @deffn procedure endpwent | |
833 | Closes the stream used by @code{getpwent}. The return value is unspecified. | |
834 | @end deffn | |
835 | ||
836 | @c docstring begin (texi-doc-string "guile" "setpw") | |
837 | @deffn primitive setpw [arg] | |
838 | If called with a true argument, initialize or reset the password data | |
839 | stream. Otherwise, close the stream. The @code{setpwent} and | |
840 | @code{endpwent} procedures are implemented on top of this. | |
841 | @end deffn | |
842 | ||
843 | @c docstring begin (texi-doc-string "guile" "getpw") | |
844 | @deffn primitive getpw [user] | |
845 | Look up an entry in the user database. @var{obj} can be an integer, | |
846 | a string, or omitted, giving the behaviour of getpwuid, getpwnam | |
847 | or getpwent respectively. | |
848 | @end deffn | |
849 | ||
850 | The following functions accept an object representing group information | |
851 | and return a selected component: | |
852 | ||
853 | @table @code | |
854 | @item group:name | |
855 | The group name. | |
856 | @item group:passwd | |
857 | The encrypted group password. | |
858 | @item group:gid | |
859 | The group id number. | |
860 | @item group:mem | |
861 | A list of userids which have this group as a supplimentary group. | |
862 | @end table | |
863 | ||
864 | @deffn procedure getgrgid gid | |
865 | Look up an integer groupid in the group database. | |
866 | @end deffn | |
867 | ||
868 | @deffn procedure getgrnam name | |
869 | Look up a group name in the group database. | |
870 | @end deffn | |
871 | ||
872 | @deffn procedure setgrent | |
873 | Initializes a stream used by @code{getgrent} to read from the group database. | |
874 | The next use of @code{getgrent} will return the first entry. | |
875 | The return value is unspecified. | |
876 | @end deffn | |
877 | ||
878 | @deffn procedure getgrent | |
879 | Return the next entry in the group database, using the stream set by | |
880 | @code{setgrent}. | |
881 | @end deffn | |
882 | ||
883 | @deffn procedure endgrent | |
884 | Closes the stream used by @code{getgrent}. | |
885 | The return value is unspecified. | |
886 | @end deffn | |
887 | ||
888 | @c docstring begin (texi-doc-string "guile" "setgr") | |
889 | @deffn primitive setgr [arg] | |
890 | If called with a true argument, initialize or reset the group data | |
891 | stream. Otherwise, close the stream. The @code{setgrent} and | |
892 | @code{endgrent} procedures are implemented on top of this. | |
893 | @end deffn | |
894 | ||
895 | @c docstring begin (texi-doc-string "guile" "getgr") | |
896 | @deffn primitive getgr [name] | |
897 | Look up an entry in the group database. @var{obj} can be an integer, | |
898 | a string, or omitted, giving the behaviour of getgrgid, getgrnam | |
899 | or getgrent respectively. | |
900 | @end deffn | |
901 | ||
902 | @node Time | |
903 | @section Time | |
904 | ||
905 | @c docstring begin (texi-doc-string "guile" "current-time") | |
906 | @deffn primitive current-time | |
907 | Returns the number of seconds since 1970-01-01 00:00:00 UTC, excluding | |
908 | leap seconds. | |
909 | @end deffn | |
910 | ||
911 | @c docstring begin (texi-doc-string "guile" "gettimeofday") | |
912 | @deffn primitive gettimeofday | |
913 | Returns a pair containing the number of seconds and microseconds since | |
914 | 1970-01-01 00:00:00 UTC, excluding leap seconds. Note: whether true | |
915 | microsecond resolution is available depends on the operating system. | |
916 | @end deffn | |
917 | ||
918 | The following procedures either accept an object representing a broken down | |
919 | time and return a selected component, or accept an object representing | |
920 | a broken down time and a value and set the component to the value. | |
921 | The numbers in parentheses give the usual range. | |
922 | ||
923 | @table @code | |
924 | @item tm:sec, set-tm:sec | |
925 | Seconds (0-59). | |
926 | @item tm:min, set-tm:min | |
927 | Minutes (0-59). | |
928 | @item tm:hour, set-tm:hour | |
929 | Hours (0-23). | |
930 | @item tm:mday, set-tm:mday | |
931 | Day of the month (1-31). | |
932 | @item tm:mon, set-tm:mon | |
933 | Month (0-11). | |
934 | @item tm:year, set-tm:year | |
935 | Year (70-), the year minus 1900. | |
936 | @item tm:wday, set-tm:wday | |
937 | Day of the week (0-6) with Sunday represented as 0. | |
938 | @item tm:yday, set-tm:yday | |
939 | Day of the year (0-364, 365 in leap years). | |
940 | @item tm:isdst, set-tm:isdst | |
941 | Daylight saving indicator (0 for "no", greater than 0 for "yes", less than | |
942 | 0 for "unknown"). | |
943 | @item tm:gmtoff, set-tm:gmtoff | |
944 | Time zone offset in seconds west of UTC (-46800 to 43200). | |
945 | @item tm:zone, set-tm:zone | |
946 | Time zone label (a string), not necessarily unique. | |
947 | @end table | |
948 | ||
949 | @c docstring begin (texi-doc-string "guile" "localtime") | |
950 | @deffn primitive localtime time [zone] | |
951 | Returns an object representing the broken down components of @var{time}, | |
952 | an integer like the one returned by @code{current-time}. The time zone | |
953 | for the calculation is optionally specified by @var{zone} (a string), | |
954 | otherwise the @code{TZ} environment variable or the system default is | |
955 | used. | |
956 | @end deffn | |
957 | ||
958 | @c docstring begin (texi-doc-string "guile" "gmtime") | |
959 | @deffn primitive gmtime time | |
960 | Returns an object representing the broken down components of @var{time}, | |
961 | an integer like the one returned by @code{current-time}. The values | |
962 | are calculated for UTC. | |
963 | @end deffn | |
964 | ||
965 | @c docstring begin (texi-doc-string "guile" "mktime") | |
966 | @deffn primitive mktime sbd_time [zone] | |
967 | @var{bd-time} is an object representing broken down time and @code{zone} | |
968 | is an optional time zone specifier (otherwise the TZ environment variable | |
969 | or the system default is used). | |
970 | ||
971 | Returns a pair: the car is a corresponding | |
972 | integer time value like that returned | |
973 | by @code{current-time}; the cdr is a broken down time object, similar to | |
974 | as @var{bd-time} but with normalized values. | |
975 | @end deffn | |
976 | ||
977 | @c docstring begin (texi-doc-string "guile" "tzset") | |
978 | @deffn primitive tzset | |
979 | Initialize the timezone from the TZ environment variable | |
980 | or the system default. It's not usually necessary to call this procedure | |
981 | since it's done automatically by other procedures that depend on the | |
982 | timezone. | |
983 | @end deffn | |
984 | ||
985 | @c docstring begin (texi-doc-string "guile" "strftime") | |
986 | @deffn primitive strftime format stime | |
987 | Formats a time specification @var{time} using @var{template}. @var{time} | |
988 | is an object with time components in the form returned by @code{localtime} | |
989 | or @code{gmtime}. @var{template} is a string which can include formatting | |
990 | specifications introduced by a @code{%} character. The formatting of | |
991 | month and day names is dependent on the current locale. The value returned | |
992 | is the formatted string. | |
993 | @xref{Formatting Date and Time, , , libc, The GNU C Library Reference Manual}.) | |
994 | @end deffn | |
995 | ||
996 | @c docstring begin (texi-doc-string "guile" "strptime") | |
997 | @deffn primitive strptime format string | |
998 | Performs the reverse action to @code{strftime}, parsing | |
999 | @var{string} according to the specification supplied in | |
1000 | @var{template}. The interpretation of month and day names is | |
1001 | dependent on the current locale. The value returned is a pair. | |
1002 | The car has an object with time components | |
1003 | in the form returned by @code{localtime} or @code{gmtime}, | |
1004 | but the time zone components | |
1005 | are not usefully set. | |
1006 | The cdr reports the number of characters from @var{string} | |
1007 | which were used for the conversion. | |
1008 | @end deffn | |
1009 | ||
1010 | @defvar internal-time-units-per-second | |
1011 | The value of this variable is the number of time units per second | |
1012 | reported by the following procedures. | |
1013 | @end defvar | |
1014 | ||
1015 | @c docstring begin (texi-doc-string "guile" "times") | |
1016 | @deffn primitive times | |
1017 | Returns an object with information about real and processor time. | |
1018 | The following procedures accept such an object as an argument and | |
1019 | return a selected component: | |
1020 | ||
1021 | @table @code | |
1022 | @item tms:clock | |
1023 | The current real time, expressed as time units relative to an | |
1024 | arbitrary base. | |
1025 | @item tms:utime | |
1026 | The CPU time units used by the calling process. | |
1027 | @item tms:stime | |
1028 | The CPU time units used by the system on behalf of the calling process. | |
1029 | @item tms:cutime | |
1030 | The CPU time units used by terminated child processes of the calling | |
1031 | process, whose status has been collected (e.g., using @code{waitpid}). | |
1032 | @item tms:cstime | |
1033 | Similarly, the CPU times units used by the system on behalf of | |
1034 | terminated child processes. | |
1035 | @end table | |
1036 | @end deffn | |
1037 | ||
1038 | @c docstring begin (texi-doc-string "guile" "get-internal-real-time") | |
1039 | @deffn primitive get-internal-real-time | |
1040 | Returns the number of time units since the interpreter was started. | |
1041 | @end deffn | |
1042 | ||
1043 | @c docstring begin (texi-doc-string "guile" "get-internal-run-time") | |
1044 | @deffn primitive get-internal-run-time | |
1045 | Returns the number of time units of processor time used by the interpreter. | |
1046 | Both "system" and "user" time are included but subprocesses are not. | |
1047 | @end deffn | |
1048 | ||
1049 | @node Runtime Environment | |
1050 | @section Runtime Environment | |
1051 | ||
1052 | @c docstring begin (texi-doc-string "guile" "program-arguments") | |
1053 | @deffn primitive program-arguments | |
1054 | @deffnx procedure command-line | |
1055 | Return the list of command line arguments passed to Guile, as a list of | |
1056 | strings. The list includes the invoked program name, which is usually | |
1057 | @code{"guile"}, but excludes switches and parameters for command line | |
1058 | options like @code{-e} and @code{-l}. | |
1059 | @end deffn | |
1060 | ||
1061 | @c docstring begin (texi-doc-string "guile" "getenv") | |
1062 | @deffn primitive getenv nam | |
1063 | Looks up the string @var{name} in the current environment. The return | |
1064 | value is @code{#f} unless a string of the form @code{NAME=VALUE} is | |
1065 | found, in which case the string @code{VALUE} is returned. | |
1066 | @end deffn | |
1067 | ||
1068 | @c begin (scm-doc-string "boot-9.scm" "setenv") | |
1069 | @deffn procedure setenv name value | |
1070 | Modifies the environment of the current process, which is | |
1071 | also the default environment inherited by child processes. | |
1072 | ||
1073 | If @var{value} is @code{#f}, then @var{name} is removed from the | |
1074 | environment. Otherwise, the string @var{name}=@var{value} is added | |
1075 | to the environment, replacing any existing string with name matching | |
1076 | @var{name}. | |
1077 | ||
1078 | The return value is unspecified. | |
1079 | @end deffn | |
1080 | ||
1081 | @c docstring begin (texi-doc-string "guile" "environ") | |
1082 | @deffn primitive environ [env] | |
1083 | If @var{env} is omitted, returns the current environment as a list of strings. | |
1084 | Otherwise it sets the current environment, which is also the | |
1085 | default environment for child processes, to the supplied list of strings. | |
1086 | Each member of @var{env} should be of the form | |
1087 | @code{NAME=VALUE} and values of @code{NAME} should not be duplicated. | |
1088 | If @var{env} is supplied then the return value is unspecified. | |
1089 | @end deffn | |
1090 | ||
1091 | @c docstring begin (texi-doc-string "guile" "putenv") | |
1092 | @deffn primitive putenv str | |
1093 | Modifies the environment of the current process, which is | |
1094 | also the default environment inherited by child processes. | |
1095 | ||
1096 | If @var{string} is of the form @code{NAME=VALUE} then it will be written | |
1097 | directly into the environment, replacing any existing environment string | |
1098 | with | |
1099 | name matching @code{NAME}. If @var{string} does not contain an equal | |
1100 | sign, then any existing string with name matching @var{string} will | |
1101 | be removed. | |
1102 | ||
1103 | The return value is unspecified. | |
1104 | @end deffn | |
1105 | ||
1106 | ||
1107 | @node Processes | |
1108 | @section Processes | |
1109 | ||
1110 | @findex cd | |
1111 | @c docstring begin (texi-doc-string "guile" "chdir") | |
1112 | @deffn primitive chdir str | |
1113 | Change the current working directory to @var{path}. | |
1114 | The return value is unspecified. | |
1115 | @end deffn | |
1116 | ||
1117 | @findex pwd | |
1118 | @c docstring begin (texi-doc-string "guile" "getcwd") | |
1119 | @deffn primitive getcwd | |
1120 | Returns the name of the current working directory. | |
1121 | @end deffn | |
1122 | ||
1123 | @c docstring begin (texi-doc-string "guile" "umask") | |
1124 | @deffn primitive umask [mode] | |
1125 | If @var{mode} is omitted, retuns a decimal number representing the current | |
1126 | file creation mask. Otherwise the file creation mask is set to | |
1127 | @var{mode} and the previous value is returned. | |
1128 | ||
1129 | E.g., @code{(umask #o022)} sets the mask to octal 22, decimal 18. | |
1130 | @end deffn | |
1131 | ||
1132 | @c docstring begin (texi-doc-string "guile" "getpid") | |
1133 | @deffn primitive getpid | |
1134 | Returns an integer representing the current process ID. | |
1135 | @end deffn | |
1136 | ||
1137 | @c docstring begin (texi-doc-string "guile" "getgroups") | |
1138 | @deffn primitive getgroups | |
1139 | Returns a vector of integers representing the current supplimentary group IDs. | |
1140 | @end deffn | |
1141 | ||
1142 | @c docstring begin (texi-doc-string "guile" "getppid") | |
1143 | @deffn primitive getppid | |
1144 | Returns an integer representing the process ID of the parent process. | |
1145 | @end deffn | |
1146 | ||
1147 | @c docstring begin (texi-doc-string "guile" "getuid") | |
1148 | @deffn primitive getuid | |
1149 | Returns an integer representing the current real user ID. | |
1150 | @end deffn | |
1151 | ||
1152 | @c docstring begin (texi-doc-string "guile" "getgid") | |
1153 | @deffn primitive getgid | |
1154 | Returns an integer representing the current real group ID. | |
1155 | @end deffn | |
1156 | ||
1157 | @c docstring begin (texi-doc-string "guile" "geteuid") | |
1158 | @deffn primitive geteuid | |
1159 | Returns an integer representing the current effective user ID. | |
1160 | If the system does not support effective IDs, then the real ID | |
1161 | is returned. @code{(feature? 'EIDs)} reports whether the system | |
1162 | supports effective IDs. | |
1163 | @end deffn | |
1164 | ||
1165 | @c docstring begin (texi-doc-string "guile" "getegid") | |
1166 | @deffn primitive getegid | |
1167 | Returns an integer representing the current effective group ID. | |
1168 | If the system does not support effective IDs, then the real ID | |
1169 | is returned. @code{(feature? 'EIDs)} reports whether the system | |
1170 | supports effective IDs. | |
1171 | @end deffn | |
1172 | ||
1173 | @c docstring begin (texi-doc-string "guile" "setuid") | |
1174 | @deffn primitive setuid id | |
1175 | Sets both the real and effective user IDs to the integer @var{id}, provided | |
1176 | the process has appropriate privileges. | |
1177 | The return value is unspecified. | |
1178 | @end deffn | |
1179 | ||
1180 | @c docstring begin (texi-doc-string "guile" "setgid") | |
1181 | @deffn primitive setgid id | |
1182 | Sets both the real and effective group IDs to the integer @var{id}, provided | |
1183 | the process has appropriate privileges. | |
1184 | The return value is unspecified. | |
1185 | @end deffn | |
1186 | ||
1187 | @c docstring begin (texi-doc-string "guile" "seteuid") | |
1188 | @deffn primitive seteuid id | |
1189 | Sets the effective user ID to the integer @var{id}, provided the process | |
1190 | has appropriate privileges. If effective IDs are not supported, the | |
1191 | real ID is set instead -- @code{(feature? 'EIDs)} reports whether the | |
1192 | system supports effective IDs. | |
1193 | The return value is unspecified. | |
1194 | @end deffn | |
1195 | ||
1196 | @c docstring begin (texi-doc-string "guile" "setegid") | |
1197 | @deffn primitive setegid id | |
1198 | Sets the effective group ID to the integer @var{id}, provided the process | |
1199 | has appropriate privileges. If effective IDs are not supported, the | |
1200 | real ID is set instead -- @code{(feature? 'EIDs)} reports whether the | |
1201 | system supports effective IDs. | |
1202 | The return value is unspecified. | |
1203 | @end deffn | |
1204 | ||
1205 | @c docstring begin (texi-doc-string "guile" "getpgrp") | |
1206 | @deffn primitive getpgrp | |
1207 | Returns an integer representing the current process group ID. | |
1208 | This is the POSIX definition, not BSD. | |
1209 | @end deffn | |
1210 | ||
1211 | @c docstring begin (texi-doc-string "guile" "setpgid") | |
1212 | @deffn primitive setpgid pid pgid | |
1213 | Move the process @var{pid} into the process group @var{pgid}. @var{pid} or | |
1214 | @var{pgid} must be integers: they can be zero to indicate the ID of the | |
1215 | current process. | |
1216 | Fails on systems that do not support job control. | |
1217 | The return value is unspecified. | |
1218 | @end deffn | |
1219 | ||
1220 | @c docstring begin (texi-doc-string "guile" "setsid") | |
1221 | @deffn primitive setsid | |
1222 | Creates a new session. The current process becomes the session leader | |
1223 | and is put in a new process group. The process will be detached | |
1224 | from its controlling terminal if it has one. | |
1225 | The return value is an integer representing the new process group ID. | |
1226 | @end deffn | |
1227 | ||
1228 | @c docstring begin (texi-doc-string "guile" "waitpid") | |
1229 | @deffn primitive waitpid pid [options] | |
1230 | This procedure collects status information from a child process which | |
1231 | has terminated or (optionally) stopped. Normally it will | |
1232 | suspend the calling process until this can be done. If more than one | |
1233 | child process is eligible then one will be chosen by the operating system. | |
1234 | ||
1235 | The value of @var{pid} determines the behaviour: | |
1236 | ||
1237 | @table @r | |
1238 | @item @var{pid} greater than 0 | |
1239 | Request status information from the specified child process. | |
1240 | @item @var{pid} equal to -1 or WAIT_ANY | |
1241 | Request status information for any child process. | |
1242 | @item @var{pid} equal to 0 or WAIT_MYPGRP | |
1243 | Request status information for any child process in the current process | |
1244 | group. | |
1245 | @item @var{pid} less than -1 | |
1246 | Request status information for any child process whose process group ID | |
1247 | is -@var{PID}. | |
1248 | @end table | |
1249 | ||
1250 | The @var{options} argument, if supplied, should be the bitwise OR of the | |
1251 | values of zero or more of the following variables: | |
1252 | ||
1253 | @defvar WNOHANG | |
1254 | Return immediately even if there are no child processes to be collected. | |
1255 | @end defvar | |
1256 | ||
1257 | @defvar WUNTRACED | |
1258 | Report status information for stopped processes as well as terminated | |
1259 | processes. | |
1260 | @end defvar | |
1261 | ||
1262 | The return value is a pair containing: | |
1263 | ||
1264 | @enumerate | |
1265 | @item | |
1266 | The process ID of the child process, or 0 if @code{WNOHANG} was | |
1267 | specified and no process was collected. | |
1268 | @item | |
1269 | The integer status value. | |
1270 | @end enumerate | |
1271 | @end deffn | |
1272 | ||
1273 | The following three | |
1274 | functions can be used to decode the process status code returned | |
1275 | by @code{waitpid}. | |
1276 | ||
1277 | @c docstring begin (texi-doc-string "guile" "status:exit-val") | |
1278 | @deffn primitive status:exit-val status | |
1279 | Returns the exit status value, as would be | |
1280 | set if a process ended normally through a | |
1281 | call to @code{exit} or @code{_exit}, if any, otherwise @code{#f}. | |
1282 | @end deffn | |
1283 | ||
1284 | @c docstring begin (texi-doc-string "guile" "status:term-sig") | |
1285 | @deffn primitive status:term-sig status | |
1286 | Returns the signal number which terminated the | |
1287 | process, if any, otherwise @code{#f}. | |
1288 | @end deffn | |
1289 | ||
1290 | @c docstring begin (texi-doc-string "guile" "status:stop-sig") | |
1291 | @deffn primitive status:stop-sig status | |
1292 | Returns the signal number which stopped the | |
1293 | process, if any, otherwise @code{#f}. | |
1294 | @end deffn | |
1295 | ||
1296 | @c docstring begin (texi-doc-string "guile" "system") | |
1297 | @deffn primitive system [cmd] | |
1298 | Executes @var{cmd} using the operating system's "command processor". | |
1299 | Under Unix this is usually the default shell @code{sh}. The value | |
1300 | returned is @var{cmd}'s exit status as returned by @code{waitpid}, which | |
1301 | can be interpreted using the functions above. | |
1302 | ||
1303 | If @code{system} is called without arguments, it returns a boolean | |
1304 | indicating whether the command processor is available. | |
1305 | @end deffn | |
1306 | ||
1307 | @c docstring begin (texi-doc-string "guile" "primitive-exit") | |
1308 | @deffn primitive primitive-exit [status] | |
1309 | Terminate the current process without unwinding the Scheme stack. | |
1310 | This is would typically be useful after a fork. The exit status | |
1311 | is @var{status} if supplied, otherwise zero. | |
1312 | @end deffn | |
1313 | ||
1314 | @c docstring begin (texi-doc-string "guile" "execl") | |
1315 | @deffn primitive execl filename . args | |
1316 | Executes the file named by @var{path} as a new process image. | |
1317 | The remaining arguments are supplied to the process; from a C program | |
1318 | they are accessable as the @code{argv} argument to @code{main}. | |
1319 | Conventionally the first @var{arg} is the same as @var{path}. | |
1320 | All arguments must be strings. | |
1321 | ||
1322 | If @var{arg} is missing, @var{path} is executed with a null | |
1323 | argument list, which may have system-dependent side-effects. | |
1324 | ||
1325 | This procedure is currently implemented using the @code{execv} system | |
1326 | call, but we call it @code{execl} because of its Scheme calling interface. | |
1327 | @end deffn | |
1328 | ||
1329 | @c docstring begin (texi-doc-string "guile" "execlp") | |
1330 | @deffn primitive execlp filename . args | |
1331 | Similar to @code{execl}, however if | |
1332 | @var{filename} does not contain a slash | |
1333 | then the file to execute will be located by searching the | |
1334 | directories listed in the @code{PATH} environment variable. | |
1335 | ||
1336 | This procedure is currently implemented using the @code{execvp} system | |
1337 | call, but we call it @code{execlp} because of its Scheme calling interface. | |
1338 | @end deffn | |
1339 | ||
1340 | @c docstring begin (texi-doc-string "guile" "execle") | |
1341 | @deffn primitive execle filename env . args | |
1342 | Similar to @code{execl}, but the environment of the new process is | |
1343 | specified by @var{env}, which must be a list of strings as returned by the | |
1344 | @code{environ} procedure. | |
1345 | ||
1346 | This procedure is currently implemented using the @code{execve} system | |
1347 | call, but we call it @code{execle} because of its Scheme calling interface. | |
1348 | @end deffn | |
1349 | ||
1350 | @c docstring begin (texi-doc-string "guile" "primitive-fork") | |
1351 | @deffn primitive primitive-fork | |
1352 | Creates a new "child" process by duplicating the current "parent" process. | |
1353 | In the child the return value is 0. In the parent the return value is | |
1354 | the integer process ID of the child. | |
1355 | ||
1356 | This procedure has been renamed from @code{fork} to avoid a naming conflict | |
1357 | with the scsh fork. | |
1358 | @end deffn | |
1359 | ||
1360 | @c docstring begin (texi-doc-string "guile" "nice") | |
1361 | @deffn primitive nice incr | |
1362 | Increment the priority of the current process by @var{incr}. A higher | |
1363 | priority value means that the process runs less often. | |
1364 | The return value is unspecified. | |
1365 | @end deffn | |
1366 | ||
1367 | @node Signals | |
1368 | @section Signals | |
1369 | ||
1370 | Procedures to raise, handle and wait for signals. | |
1371 | ||
1372 | @c docstring begin (texi-doc-string "guile" "kill") | |
1373 | @deffn primitive kill pid sig | |
1374 | Sends a signal to the specified process or group of processes. | |
1375 | ||
1376 | @var{pid} specifies the processes to which the signal is sent: | |
1377 | ||
1378 | @table @r | |
1379 | @item @var{pid} greater than 0 | |
1380 | The process whose identifier is @var{pid}. | |
1381 | @item @var{pid} equal to 0 | |
1382 | All processes in the current process group. | |
1383 | @item @var{pid} less than -1 | |
1384 | The process group whose identifier is -@var{pid} | |
1385 | @item @var{pid} equal to -1 | |
1386 | If the process is privileged, all processes except for some special | |
1387 | system processes. Otherwise, all processes with the current effective | |
1388 | user ID. | |
1389 | @end table | |
1390 | ||
1391 | @var{sig} should be specified using a variable corresponding to | |
1392 | the Unix symbolic name, e.g., | |
1393 | ||
1394 | @defvar SIGHUP | |
1395 | Hang-up signal. | |
1396 | @end defvar | |
1397 | ||
1398 | @defvar SIGINT | |
1399 | Interrupt signal. | |
1400 | @end defvar | |
1401 | @end deffn | |
1402 | ||
1403 | @c docstring begin (texi-doc-string "guile" "raise") | |
1404 | @deffn primitive raise sig | |
1405 | Sends a specified signal @var{sig} to the current process, where | |
1406 | @var{sig} is as described for the kill procedure. | |
1407 | @end deffn | |
1408 | ||
1409 | @c docstring begin (texi-doc-string "guile" "sigaction") | |
1410 | @deffn primitive sigaction signum [handler [flags]] | |
1411 | Install or report the signal handler for a specified signal. | |
1412 | ||
1413 | @var{signum} is the signal number, which can be specified using the value | |
1414 | of variables such as @code{SIGINT}. | |
1415 | ||
1416 | If @var{action} is omitted, @code{sigaction} returns a pair: the | |
1417 | CAR is the current | |
1418 | signal hander, which will be either an integer with the value @code{SIG_DFL} | |
1419 | (default action) or @code{SIG_IGN} (ignore), or the Scheme procedure which | |
1420 | handles the signal, or @code{#f} if a non-Scheme procedure handles the | |
1421 | signal. The CDR contains the current @code{sigaction} flags for the handler. | |
1422 | ||
1423 | If @var{action} is provided, it is installed as the new handler for | |
1424 | @var{signum}. @var{action} can be a Scheme procedure taking one | |
1425 | argument, or the value of @code{SIG_DFL} (default action) or | |
1426 | @code{SIG_IGN} (ignore), or @code{#f} to restore whatever signal handler | |
1427 | was installed before @code{sigaction} was first used. Flags can | |
1428 | optionally be specified for the new handler (@code{SA_RESTART} will | |
1429 | always be added if it's available and the system is using restartable | |
1430 | system calls.) The return value is a pair with information about the | |
1431 | old handler as described above. | |
1432 | ||
1433 | This interface does not provide access to the "signal blocking" | |
1434 | facility. Maybe this is not needed, since the thread support may | |
1435 | provide solutions to the problem of consistent access to data | |
1436 | structures. | |
1437 | @end deffn | |
1438 | ||
1439 | @c docstring begin (texi-doc-string "guile" "restore-signals") | |
1440 | @deffn primitive restore-signals | |
1441 | Return all signal handlers to the values they had before any call to | |
1442 | @code{sigaction} was made. The return value is unspecified. | |
1443 | @end deffn | |
1444 | ||
1445 | @c docstring begin (texi-doc-string "guile" "alarm") | |
1446 | @deffn primitive alarm i | |
1447 | Set a timer to raise a @code{SIGALRM} signal after the specified | |
1448 | number of seconds (an integer). It's advisable to install a signal | |
1449 | handler for | |
1450 | @code{SIGALRM} beforehand, since the default action is to terminate | |
1451 | the process. | |
1452 | ||
1453 | The return value indicates the time remaining for the previous alarm, | |
1454 | if any. The new value replaces the previous alarm. If there was | |
1455 | no previous alarm, the return value is zero. | |
1456 | @end deffn | |
1457 | ||
1458 | @c docstring begin (texi-doc-string "guile" "pause") | |
1459 | @deffn primitive pause | |
1460 | Pause the current process (thread?) until a signal arrives whose | |
1461 | action is to either terminate the current process or invoke a | |
1462 | handler procedure. The return value is unspecified. | |
1463 | @end deffn | |
1464 | ||
1465 | @c docstring begin (texi-doc-string "guile" "sleep") | |
1466 | @deffn primitive sleep i | |
1467 | Wait for the given number of seconds (an integer) or until a signal | |
1468 | arrives. The return value is zero if the time elapses or the number | |
1469 | of seconds remaining otherwise. | |
1470 | @end deffn | |
1471 | ||
1472 | @c docstring begin (texi-doc-string "guile" "usleep") | |
1473 | @deffn primitive usleep i | |
780ee65e NJ |
1474 | Sleep for I microseconds. @code{usleep} is not available on |
1475 | all platforms. | |
38a93523 NJ |
1476 | @end deffn |
1477 | ||
1478 | @node Terminals and Ptys | |
1479 | @section Terminals and Ptys | |
1480 | ||
1481 | @c docstring begin (texi-doc-string "guile" "isatty?") | |
1482 | @deffn primitive isatty? port | |
1483 | Returns @code{#t} if @var{port} is using a serial | |
1484 | non-file device, otherwise @code{#f}. | |
1485 | @end deffn | |
1486 | ||
1487 | @c docstring begin (texi-doc-string "guile" "ttyname") | |
1488 | @deffn primitive ttyname port | |
1489 | Returns a string with the name of the serial terminal device underlying | |
1490 | @var{port}. | |
1491 | @end deffn | |
1492 | ||
1493 | @c docstring begin (texi-doc-string "guile" "ctermid") | |
1494 | @deffn primitive ctermid | |
1495 | Returns a string containing the file name of the controlling terminal | |
1496 | for the current process. | |
1497 | @end deffn | |
1498 | ||
1499 | @c docstring begin (texi-doc-string "guile" "tcgetpgrp") | |
1500 | @deffn primitive tcgetpgrp port | |
1501 | Returns the process group ID of the foreground | |
1502 | process group associated with the terminal open on the file descriptor | |
1503 | underlying @var{port}. | |
1504 | ||
1505 | If there is no foreground process group, the return value is a | |
1506 | number greater than 1 that does not match the process group ID | |
1507 | of any existing process group. This can happen if all of the | |
1508 | processes in the job that was formerly the foreground job have | |
1509 | terminated, and no other job has yet been moved into the | |
1510 | foreground. | |
1511 | @end deffn | |
1512 | ||
1513 | @c docstring begin (texi-doc-string "guile" "tcsetpgrp") | |
1514 | @deffn primitive tcsetpgrp port pgid | |
1515 | Set the foreground process group ID for the terminal used by the file | |
1516 | descriptor underlying @var{port} to the integer @var{pgid}. | |
1517 | The calling process | |
1518 | must be a member of the same session as @var{pgid} and must have the same | |
1519 | controlling terminal. The return value is unspecified. | |
1520 | @end deffn | |
1521 | ||
1522 | @node Pipes | |
1523 | @section Pipes | |
1524 | ||
1525 | The following procedures provide an interface to the @code{popen} and | |
1526 | @code{pclose} system routines. The code is in a separate "popen" | |
1527 | module: | |
1528 | ||
1529 | @smalllisp | |
1530 | (use-modules (ice-9 popen)) | |
1531 | @end smalllisp | |
1532 | ||
1533 | @findex popen | |
1534 | @deffn procedure open-pipe command modes | |
1535 | Executes the shell command @var{command} (a string) in a subprocess. | |
1536 | A pipe to the process is created and returned. @var{modes} specifies | |
1537 | whether an input or output pipe to the process is created: it should | |
1538 | be the value of @code{OPEN_READ} or @code{OPEN_WRITE}. | |
1539 | @end deffn | |
1540 | ||
1541 | @deffn procedure open-input-pipe command | |
1542 | Equivalent to @code{open-pipe} with mode @code{OPEN_READ}. | |
1543 | @end deffn | |
1544 | ||
1545 | @deffn procedure open-output-pipe command | |
1546 | Equivalent to @code{open-pipe} with mode @code{OPEN_WRITE}. | |
1547 | @end deffn | |
1548 | ||
1549 | @findex pclose | |
1550 | @deffn procedure close-pipe port | |
1551 | Closes the pipe created by @code{open-pipe}, then waits for the process | |
1552 | to terminate and returns its status value, @xref{Processes, waitpid}, for | |
1553 | information on how to interpret this value. | |
1554 | ||
1555 | @code{close-port} (@pxref{Closing, close-port}) can also be used to | |
1556 | close a pipe, but doesn't return the status. | |
1557 | @end deffn | |
1558 | ||
1559 | @node Networking | |
1560 | @section Networking | |
1561 | ||
1562 | @menu | |
1563 | * Network Databases and Address Conversion:: | |
1564 | * Network Sockets and Communication:: | |
1565 | @end menu | |
1566 | ||
1567 | @node Network Databases and Address Conversion | |
1568 | @subsection Network Databases and Address Conversion | |
1569 | ||
1570 | This section describes procedures which convert internet addresses | |
1571 | and query various network databases. Care should be taken when using | |
1572 | the database routines since they are not reentrant. | |
1573 | ||
1574 | @subsubsection Address Conversion | |
1575 | ||
1576 | @c docstring begin (texi-doc-string "guile" "inet-aton") | |
1577 | @deffn primitive inet-aton address | |
1578 | Converts a string containing an Internet host address in the traditional | |
1579 | dotted decimal notation into an integer. | |
1580 | ||
1581 | @smalllisp | |
1582 | (inet-aton "127.0.0.1") @result{} 2130706433 | |
1583 | ||
1584 | @end smalllisp | |
1585 | @end deffn | |
1586 | ||
1587 | @c docstring begin (texi-doc-string "guile" "inet-ntoa") | |
1588 | @deffn primitive inet-ntoa inetid | |
1589 | Converts an integer Internet host address into a string with the | |
1590 | traditional dotted decimal representation. | |
1591 | ||
1592 | @smalllisp | |
1593 | (inet-ntoa 2130706433) @result{} "127.0.0.1" | |
1594 | @end smalllisp | |
1595 | @end deffn | |
1596 | ||
1597 | @c docstring begin (texi-doc-string "guile" "inet-netof") | |
1598 | @deffn primitive inet-netof address | |
1599 | Returns the network number part of the given integer Internet address. | |
1600 | ||
1601 | @smalllisp | |
1602 | (inet-netof 2130706433) @result{} 127 | |
1603 | @end smalllisp | |
1604 | @end deffn | |
1605 | ||
1606 | @c docstring begin (texi-doc-string "guile" "inet-lnaof") | |
1607 | @deffn primitive inet-lnaof address | |
1608 | Returns the local-address-with-network part of the given Internet | |
1609 | address. | |
1610 | ||
1611 | @smalllisp | |
1612 | (inet-lnaof 2130706433) @result{} 1 | |
1613 | @end smalllisp | |
1614 | @end deffn | |
1615 | ||
1616 | @c docstring begin (texi-doc-string "guile" "inet-makeaddr") | |
1617 | @deffn primitive inet-makeaddr net lna | |
1618 | Makes an Internet host address by combining the network number @var{net} | |
1619 | with the local-address-within-network number @var{lna}. | |
1620 | ||
1621 | @smalllisp | |
1622 | (inet-makeaddr 127 1) @result{} 2130706433 | |
1623 | @end smalllisp | |
1624 | @end deffn | |
1625 | ||
1626 | @subsubsection The Host Database | |
1627 | ||
1628 | A @dfn{host object} is a structure that represents what is known about a | |
1629 | network host, and is the usual way of representing a system's network | |
1630 | identity inside software. | |
1631 | ||
1632 | The following functions accept a host object and return a selected | |
1633 | component: | |
1634 | ||
1635 | @deffn procedure hostent:name host | |
1636 | The "official" hostname for @var{host}. | |
1637 | @end deffn | |
1638 | @deffn procedure hostent:aliases host | |
1639 | A list of aliases for @var{host}. | |
1640 | @end deffn | |
1641 | @deffn procedure hostent:addrtype host | |
1642 | The host address type. For hosts with Internet addresses, this will | |
1643 | return @code{AF_INET}. | |
1644 | @end deffn | |
1645 | @deffn procedure hostent:length host | |
1646 | The length of each address for @var{host}, in bytes. | |
1647 | @end deffn | |
1648 | @deffn procedure hostent:addr-list host | |
1649 | The list of network addresses associated with @var{host}. | |
1650 | @end deffn | |
1651 | ||
1652 | The following procedures are used to search the host database: | |
1653 | ||
1654 | @c docstring begin (texi-doc-string "guile" "gethost") | |
1655 | @deffn primitive gethost [host] | |
1656 | @deffnx procedure gethostbyname hostname | |
1657 | @deffnx procedure gethostbyaddr address | |
1658 | Look up a host by name or address, returning a host object. The | |
1659 | @code{gethost} procedure will accept either a string name or an integer | |
1660 | address; if given no arguments, it behaves like @code{gethostent} (see | |
1661 | below). If a name or address is supplied but the address can not be | |
1662 | found, an error will be thrown to one of the keys: | |
1663 | @code{host-not-found}, @code{try-again}, @code{no-recovery} or | |
1664 | @code{no-data}, corresponding to the equivalent @code{h_error} values. | |
1665 | Unusual conditions may result in errors thrown to the | |
1666 | @code{system-error} or @code{misc_error} keys. | |
1667 | @end deffn | |
1668 | ||
1669 | The following procedures may be used to step through the host | |
1670 | database from beginning to end. | |
1671 | ||
1672 | @deffn procedure sethostent [stayopen] | |
1673 | Initialize an internal stream from which host objects may be read. This | |
1674 | procedure must be called before any calls to @code{gethostent}, and may | |
1675 | also be called afterward to reset the host entry stream. If | |
1676 | @var{stayopen} is supplied and is not @code{#f}, the database is not | |
1677 | closed by subsequent @code{gethostbyname} or @code{gethostbyaddr} calls, | |
1678 | possibly giving an efficiency gain. | |
1679 | @end deffn | |
1680 | ||
1681 | @deffn procedure gethostent | |
1682 | Return the next host object from the host database, or @code{#f} if | |
1683 | there are no more hosts to be found (or an error has been encountered). | |
1684 | This procedure may not be used before @code{sethostent} has been called. | |
1685 | @end deffn | |
1686 | ||
1687 | @deffn procedure endhostent | |
1688 | Close the stream used by @code{gethostent}. The return value is unspecified. | |
1689 | @end deffn | |
1690 | ||
1691 | @c docstring begin (texi-doc-string "guile" "sethost") | |
1692 | @deffn primitive sethost [stayopen] | |
1693 | If @var{stayopen} is omitted, this is equivalent to @code{endhostent}. | |
1694 | Otherwise it is equivalent to @code{sethostent stayopen}. | |
1695 | @end deffn | |
1696 | @subsubsection The Network Database | |
1697 | ||
1698 | The following functions accept an object representing a network | |
1699 | and return a selected component: | |
1700 | ||
1701 | @deffn procedure netent:name net | |
1702 | The "official" network name. | |
1703 | @end deffn | |
1704 | @deffn procedure netent:aliases net | |
1705 | A list of aliases for the network. | |
1706 | @end deffn | |
1707 | @deffn procedure netent:addrtype net | |
1708 | The type of the network number. Currently, this returns only | |
1709 | @code{AF_INET}. | |
1710 | @end deffn | |
1711 | @deffn procedure netent:net net | |
1712 | The network number. | |
1713 | @end deffn | |
1714 | ||
1715 | The following procedures are used to search the network database: | |
1716 | ||
1717 | @c docstring begin (texi-doc-string "guile" "getnet") | |
1718 | @deffn primitive getnet [net] | |
1719 | @deffnx procedure getnetbyname net-name | |
1720 | @deffnx procedure getnetbyaddr net-number | |
1721 | Look up a network by name or net number in the network database. The | |
1722 | @var{net-name} argument must be a string, and the @var{net-number} | |
1723 | argument must be an integer. @code{getnet} will accept either type of | |
1724 | argument, behaving like @code{getnetent} (see below) if no arguments are | |
1725 | given. | |
1726 | @end deffn | |
1727 | ||
1728 | The following procedures may be used to step through the network | |
1729 | database from beginning to end. | |
1730 | ||
1731 | @deffn procedure setnetent [stayopen] | |
1732 | Initialize an internal stream from which network objects may be read. This | |
1733 | procedure must be called before any calls to @code{getnetent}, and may | |
1734 | also be called afterward to reset the net entry stream. If | |
1735 | @var{stayopen} is supplied and is not @code{#f}, the database is not | |
1736 | closed by subsequent @code{getnetbyname} or @code{getnetbyaddr} calls, | |
1737 | possibly giving an efficiency gain. | |
1738 | @end deffn | |
1739 | ||
1740 | @deffn procedure getnetent | |
1741 | Return the next entry from the network database. | |
1742 | @end deffn | |
1743 | ||
1744 | @deffn procedure endnetent | |
1745 | Close the stream used by @code{getnetent}. The return value is unspecified. | |
1746 | @end deffn | |
1747 | ||
1748 | @c docstring begin (texi-doc-string "guile" "setnet") | |
1749 | @deffn primitive setnet [stayopen] | |
1750 | If @var{stayopen} is omitted, this is equivalent to @code{endnetent}. | |
1751 | Otherwise it is equivalent to @code{setnetent stayopen}. | |
1752 | @end deffn | |
1753 | ||
1754 | @subsubsection The Protocol Database | |
1755 | ||
1756 | The following functions accept an object representing a protocol | |
1757 | and return a selected component: | |
1758 | ||
1759 | @deffn procedure protoent:name protocol | |
1760 | The "official" protocol name. | |
1761 | @end deffn | |
1762 | @deffn procedure protoent:aliases protocol | |
1763 | A list of aliases for the protocol. | |
1764 | @end deffn | |
1765 | @deffn procedure protoent:proto protocol | |
1766 | The protocol number. | |
1767 | @end deffn | |
1768 | ||
1769 | The following procedures are used to search the protocol database: | |
1770 | ||
1771 | @c docstring begin (texi-doc-string "guile" "getproto") | |
1772 | @deffn primitive getproto [protocol] | |
1773 | @deffnx procedure getprotobyname name | |
1774 | @deffnx procedure getprotobynumber number | |
1775 | Look up a network protocol by name or by number. @code{getprotobyname} | |
1776 | takes a string argument, and @code{getprotobynumber} takes an integer | |
1777 | argument. @code{getproto} will accept either type, behaving like | |
1778 | @code{getprotoent} (see below) if no arguments are supplied. | |
1779 | @end deffn | |
1780 | ||
1781 | The following procedures may be used to step through the protocol | |
1782 | database from beginning to end. | |
1783 | ||
1784 | @deffn procedure setprotoent [stayopen] | |
1785 | Initialize an internal stream from which protocol objects may be read. This | |
1786 | procedure must be called before any calls to @code{getprotoent}, and may | |
1787 | also be called afterward to reset the protocol entry stream. If | |
1788 | @var{stayopen} is supplied and is not @code{#f}, the database is not | |
1789 | closed by subsequent @code{getprotobyname} or @code{getprotobynumber} calls, | |
1790 | possibly giving an efficiency gain. | |
1791 | @end deffn | |
1792 | ||
1793 | @deffn procedure getprotoent | |
1794 | Return the next entry from the protocol database. | |
1795 | @end deffn | |
1796 | ||
1797 | @deffn procedure endprotoent | |
1798 | Close the stream used by @code{getprotoent}. The return value is unspecified. | |
1799 | @end deffn | |
1800 | ||
1801 | @c docstring begin (texi-doc-string "guile" "setproto") | |
1802 | @deffn primitive setproto [stayopen] | |
1803 | If @var{stayopen} is omitted, this is equivalent to @code{endprotoent}. | |
1804 | Otherwise it is equivalent to @code{setprotoent stayopen}. | |
1805 | @end deffn | |
1806 | ||
1807 | @subsubsection The Service Database | |
1808 | ||
1809 | The following functions accept an object representing a service | |
1810 | and return a selected component: | |
1811 | ||
1812 | @deffn procedure servent:name serv | |
1813 | The "official" name of the network service. | |
1814 | @end deffn | |
1815 | @deffn procedure servent:aliases serv | |
1816 | A list of aliases for the network service. | |
1817 | @end deffn | |
1818 | @deffn procedure servent:port serv | |
1819 | The Internet port used by the service. | |
1820 | @end deffn | |
1821 | @deffn procedure servent:proto serv | |
1822 | The protocol used by the service. A service may be listed many times | |
1823 | in the database under different protocol names. | |
1824 | @end deffn | |
1825 | ||
1826 | The following procedures are used to search the service database: | |
1827 | ||
1828 | @c docstring begin (texi-doc-string "guile" "getserv") | |
1829 | @deffn primitive getserv [name [protocol]] | |
1830 | @deffnx procedure getservbyname name protocol | |
1831 | @deffnx procedure getservbyport port protocol | |
1832 | Look up a network service by name or by service number, and return a | |
1833 | network service object. The @var{protocol} argument specifies the name | |
1834 | of the desired protocol; if the protocol found in the network service | |
1835 | database does not match this name, a system error is signalled. | |
1836 | ||
1837 | The @code{getserv} procedure will take either a service name or number | |
1838 | as its first argument; if given no arguments, it behaves like | |
1839 | @code{getservent} (see below). | |
1840 | @end deffn | |
1841 | ||
1842 | The following procedures may be used to step through the service | |
1843 | database from beginning to end. | |
1844 | ||
1845 | @deffn procedure setservent [stayopen] | |
1846 | Initialize an internal stream from which service objects may be read. This | |
1847 | procedure must be called before any calls to @code{getservent}, and may | |
1848 | also be called afterward to reset the service entry stream. If | |
1849 | @var{stayopen} is supplied and is not @code{#f}, the database is not | |
1850 | closed by subsequent @code{getservbyname} or @code{getservbyport} calls, | |
1851 | possibly giving an efficiency gain. | |
1852 | @end deffn | |
1853 | ||
1854 | @deffn procedure getservent | |
1855 | Return the next entry from the services database. | |
1856 | @end deffn | |
1857 | ||
1858 | @deffn procedure endservent | |
1859 | Close the stream used by @code{getservent}. The return value is unspecified. | |
1860 | @end deffn | |
1861 | ||
1862 | @c docstring begin (texi-doc-string "guile" "setserv") | |
1863 | @deffn primitive setserv [stayopen] | |
1864 | If @var{stayopen} is omitted, this is equivalent to @code{endservent}. | |
1865 | Otherwise it is equivalent to @code{setservent stayopen}. | |
1866 | @end deffn | |
1867 | ||
1868 | @node Network Sockets and Communication | |
1869 | @subsection Network Sockets and Communication | |
1870 | ||
1871 | Socket ports can be created using @code{socket} and @code{socketpair}. | |
1872 | The ports are initially unbuffered, to | |
1873 | makes reading and writing to the same port more reliable. | |
1874 | A buffer can be added to the port using @code{setvbuf}, | |
1875 | @xref{Ports and File Descriptors}. | |
1876 | ||
1877 | The convention used for "host" vs "network" addresses is that addresses | |
1878 | are always held in host order at the Scheme level. The procedures in | |
1879 | this section automatically convert between host and network order when | |
1880 | required. The arguments and return values are thus in host order. | |
1881 | ||
1882 | @c docstring begin (texi-doc-string "guile" "socket") | |
1883 | @deffn primitive socket family style proto | |
1884 | Returns a new socket port of the type specified by @var{family}, @var{style} | |
1885 | and @var{protocol}. All three parameters are integers. Typical values | |
1886 | for @var{family} are the values of @code{AF_UNIX} | |
1887 | and @code{AF_INET}. Typical values for @var{style} are | |
1888 | the values of @code{SOCK_STREAM}, @code{SOCK_DGRAM} and @code{SOCK_RAW}. | |
1889 | ||
1890 | @var{protocol} can be obtained from a protocol name using | |
1891 | @code{getprotobyname}. A value of | |
1892 | zero specifies the default protocol, which is usually right. | |
1893 | ||
1894 | A single socket port cannot by used for communication until | |
1895 | it has been connected to another socket. | |
1896 | @end deffn | |
1897 | ||
1898 | @c docstring begin (texi-doc-string "guile" "socketpair") | |
1899 | @deffn primitive socketpair family style proto | |
1900 | Returns a pair of connected (but unnamed) socket ports of the type specified | |
1901 | by @var{family}, @var{style} and @var{protocol}. | |
1902 | Many systems support only | |
1903 | socket pairs of the @code{AF_UNIX} family. Zero is likely to be | |
1904 | the only meaningful value for @var{protocol}. | |
1905 | @end deffn | |
1906 | ||
1907 | @c docstring begin (texi-doc-string "guile" "getsockopt") | |
1908 | @deffn primitive getsockopt sock level optname | |
1909 | Returns the value of a particular socket option for the socket | |
1910 | port @var{socket}. @var{level} is an integer code for type of option | |
1911 | being requested, e.g., @code{SOL_SOCKET} for socket-level options. | |
1912 | @var{optname} is an | |
1913 | integer code for the option required and should be specified using one of | |
1914 | the symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc. | |
1915 | ||
1916 | The returned value is typically an integer but @code{SO_LINGER} returns a | |
1917 | pair of integers. | |
1918 | @end deffn | |
1919 | ||
1920 | @c docstring begin (texi-doc-string "guile" "setsockopt") | |
1921 | @deffn primitive setsockopt sock level optname value | |
1922 | Sets the value of a particular socket option for the socket | |
1923 | port @var{socket}. @var{level} is an integer code for type of option | |
1924 | being set, e.g., @code{SOL_SOCKET} for socket-level options. | |
1925 | @var{optname} is an | |
1926 | integer code for the option to set and should be specified using one of | |
1927 | the symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc. | |
1928 | @var{value} is the value to which the option should be set. For | |
1929 | most options this must be an integer, but for @code{SO_LINGER} it must | |
1930 | be a pair. | |
1931 | ||
1932 | The return value is unspecified. | |
1933 | @end deffn | |
1934 | ||
1935 | @c docstring begin (texi-doc-string "guile" "shutdown") | |
1936 | @deffn primitive shutdown sock how | |
1937 | Sockets can be closed simply by using @code{close-port}. The | |
1938 | @code{shutdown} procedure allows reception or tranmission on a | |
1939 | connection to be shut down individually, according to the parameter | |
1940 | @var{how}: | |
1941 | ||
1942 | @table @asis | |
1943 | @item 0 | |
1944 | Stop receiving data for this socket. If further data arrives, reject it. | |
1945 | @item 1 | |
1946 | Stop trying to transmit data from this socket. Discard any | |
1947 | data waiting to be sent. Stop looking for acknowledgement of | |
1948 | data already sent; don't retransmit it if it is lost. | |
1949 | @item 2 | |
1950 | Stop both reception and transmission. | |
1951 | @end table | |
1952 | ||
1953 | The return value is unspecified. | |
1954 | @end deffn | |
1955 | ||
1956 | @c docstring begin (texi-doc-string "guile" "connect") | |
1957 | @deffn primitive connect sock fam address . args | |
1958 | Initiates a connection from @var{socket} to the address | |
1959 | specified by @var{address} and possibly @var{arg @dots{}}. The format | |
1960 | required for @var{address} | |
1961 | and @var{arg} @dots{} depends on the family of the socket. | |
1962 | ||
1963 | For a socket of family @code{AF_UNIX}, | |
1964 | only @code{address} is specified and must be a string with the | |
1965 | filename where the socket is to be created. | |
1966 | ||
1967 | For a socket of family @code{AF_INET}, | |
1968 | @code{address} must be an integer Internet host address and @var{arg} @dots{} | |
1969 | must be a single integer port number. | |
1970 | ||
1971 | The return value is unspecified. | |
1972 | @end deffn | |
1973 | ||
1974 | @c docstring begin (texi-doc-string "guile" "bind") | |
1975 | @deffn primitive bind sock fam address . args | |
1976 | Assigns an address to the socket port @var{socket}. | |
1977 | Generally this only needs to be done for server sockets, | |
1978 | so they know where to look for incoming connections. A socket | |
1979 | without an address will be assigned one automatically when it | |
1980 | starts communicating. | |
1981 | ||
1982 | The format of @var{address} and @var{ARG} @dots{} depends on the family | |
1983 | of the socket. | |
1984 | ||
1985 | For a socket of family @code{AF_UNIX}, only @var{address} is specified | |
1986 | and must be a string with the filename where the socket is to be | |
1987 | created. | |
1988 | ||
1989 | For a socket of family @code{AF_INET}, @var{address} must be an integer | |
1990 | Internet host address and @var{arg} @dots{} must be a single integer | |
1991 | port number. | |
1992 | ||
1993 | The values of the following variables can also be used for @var{address}: | |
1994 | ||
1995 | @defvar INADDR_ANY | |
1996 | Allow connections from any address. | |
1997 | @end defvar | |
1998 | ||
1999 | @defvar INADDR_LOOPBACK | |
2000 | The address of the local host using the loopback device. | |
2001 | @end defvar | |
2002 | ||
2003 | @defvar INADDR_BROADCAST | |
2004 | The broadcast address on the local network. | |
2005 | @end defvar | |
2006 | ||
2007 | @defvar INADDR_NONE | |
2008 | No address. | |
2009 | @end defvar | |
2010 | ||
2011 | The return value is unspecified. | |
2012 | @end deffn | |
2013 | ||
2014 | @c docstring begin (texi-doc-string "guile" "listen") | |
2015 | @deffn primitive listen sock backlog | |
2016 | This procedure enables @var{socket} to accept connection | |
2017 | requests. @var{backlog} is an integer specifying | |
2018 | the maximum length of the queue for pending connections. | |
2019 | If the queue fills, new clients will fail to connect until the | |
2020 | server calls @code{accept} to accept a connection from the queue. | |
2021 | ||
2022 | The return value is unspecified. | |
2023 | @end deffn | |
2024 | ||
2025 | @c docstring begin (texi-doc-string "guile" "accept") | |
2026 | @deffn primitive accept sock | |
2027 | Accepts a connection on a bound, listening socket @var{socket}. If there | |
2028 | are no pending connections in the queue, it waits until | |
2029 | one is available unless the non-blocking option has been set on the | |
2030 | socket. | |
2031 | ||
2032 | The return value is a | |
2033 | pair in which the CAR is a new socket port for the connection and | |
2034 | the CDR is an object with address information about the client which | |
2035 | initiated the connection. | |
2036 | ||
2037 | If the address is not available then the CDR will be an empty vector. | |
2038 | ||
2039 | @var{socket} does not become part of the | |
2040 | connection and will continue to accept new requests. | |
2041 | @end deffn | |
2042 | ||
2043 | The following functions take a socket address object, as returned | |
2044 | by @code{accept} and other procedures, and return a selected component. | |
2045 | ||
2046 | @table @code | |
2047 | @item sockaddr:fam | |
2048 | The socket family, typically equal to the value of @code{AF_UNIX} or | |
2049 | @code{AF_INET}. | |
2050 | @item sockaddr:path | |
2051 | If the socket family is @code{AF_UNIX}, returns the path of the | |
2052 | filename the socket is based on. | |
2053 | @item sockaddr:addr | |
2054 | If the socket family is @code{AF_INET}, returns the Internet host | |
2055 | address. | |
2056 | @item sockaddr:port | |
2057 | If the socket family is @code{AF_INET}, returns the Internet port | |
2058 | number. | |
2059 | @end table | |
2060 | ||
2061 | @c docstring begin (texi-doc-string "guile" "getsockname") | |
2062 | @deffn primitive getsockname sock | |
2063 | Returns the address of @var{socket}, in the same form as the object | |
2064 | returned by @code{accept}. On many systems the address of a socket | |
2065 | in the @code{AF_FILE} namespace cannot be read. | |
2066 | @end deffn | |
2067 | ||
2068 | @c docstring begin (texi-doc-string "guile" "getpeername") | |
2069 | @deffn primitive getpeername sock | |
2070 | Returns the address of the socket that the socket @var{socket} is connected to, | |
2071 | in the same form as the object | |
2072 | returned by @code{accept}. On many systems the address of a socket | |
2073 | in the @code{AF_FILE} namespace cannot be read. | |
2074 | @end deffn | |
2075 | ||
2076 | @c docstring begin (texi-doc-string "guile" "recv!") | |
2077 | @deffn primitive recv! sock buf [flags] | |
2078 | Receives data from the socket port @var{socket}. @var{socket} must already | |
2079 | be bound to the address from which data is to be received. | |
2080 | @var{buf} is a string into which | |
2081 | the data will be written. The size of @var{buf} limits the amount of | |
2082 | data which can be received: in the case of packet | |
2083 | protocols, if a packet larger than this limit is encountered then some data | |
2084 | will be irrevocably lost. | |
2085 | ||
2086 | The optional @var{flags} argument is a value or | |
2087 | bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc. | |
2088 | ||
2089 | The value returned is the number of bytes read from the socket. | |
2090 | ||
2091 | Note that the data is read directly from the socket file descriptor: | |
2092 | any unread buffered port data is ignored. | |
2093 | @end deffn | |
2094 | ||
2095 | @c docstring begin (texi-doc-string "guile" "send") | |
2096 | @deffn primitive send sock message [flags] | |
2097 | Transmits the string @var{message} on the socket port @var{socket}. | |
2098 | @var{socket} must already be bound to a destination address. The | |
2099 | value returned is the number of bytes transmitted -- it's possible for | |
2100 | this to be less than the length of @var{message} if the socket is | |
2101 | set to be non-blocking. The optional @var{flags} argument is a value or | |
2102 | bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc. | |
2103 | ||
2104 | Note that the data is written directly to the socket file descriptor: | |
2105 | any unflushed buffered port data is ignored. | |
2106 | @end deffn | |
2107 | ||
2108 | @c docstring begin (texi-doc-string "guile" "recvfrom!") | |
2109 | @deffn primitive recvfrom! sock str [flags [start [end]]] | |
2110 | Returns data from the socket port @var{socket} and also information about | |
2111 | where the data was received from. @var{socket} must already | |
2112 | be bound to the address from which data is to be received. | |
2113 | @code{str}, is a string into which | |
2114 | the data will be written. The size of @var{str} limits the amount of | |
2115 | data which can be received: in the case of packet | |
2116 | protocols, if a packet larger than this limit is encountered then some data | |
2117 | will be irrevocably lost. | |
2118 | ||
2119 | The optional @var{flags} argument is a value or | |
2120 | bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc. | |
2121 | ||
2122 | The value returned is a pair: the CAR is the number of bytes read from | |
2123 | the socket and the CDR an address object in the same form as returned by | |
2124 | @code{accept}. | |
2125 | ||
2126 | The @var{start} and @var{end} arguments specify a substring of @var{str} | |
2127 | to which the data should be written. | |
2128 | ||
2129 | Note that the data is read directly from the socket file descriptor: | |
2130 | any unread buffered port data is ignored. | |
2131 | @end deffn | |
2132 | ||
2133 | @c docstring begin (texi-doc-string "guile" "sendto") | |
2134 | @deffn primitive sendto sock message fam address . args_and_flags | |
2135 | Transmits the string @var{message} on the socket port @var{socket}. The | |
2136 | destination address is specified using the @var{family}, @var{address} and | |
2137 | @var{arg} arguments, in a similar way to the @code{connect} | |
2138 | procedure. The | |
2139 | value returned is the number of bytes transmitted -- it's possible for | |
2140 | this to be less than the length of @var{message} if the socket is | |
2141 | set to be non-blocking. The optional @var{flags} argument is a value or | |
2142 | bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc. | |
2143 | ||
2144 | Note that the data is written directly to the socket file descriptor: | |
2145 | any unflushed buffered port data is ignored. | |
2146 | @end deffn | |
2147 | ||
2148 | The following functions can be used to convert short and long integers | |
2149 | between "host" and "network" order. Although the procedures above do | |
2150 | this automatically for addresses, the conversion will still need to | |
2151 | be done when sending or receiving encoded integer data from the network. | |
2152 | ||
2153 | @c docstring begin (texi-doc-string "guile" "htons") | |
2154 | @deffn primitive htons in | |
2155 | Returns a new integer from @var{value} by converting from host to | |
2156 | network order. @var{value} must be within the range of a C unsigned | |
2157 | short integer. | |
2158 | @end deffn | |
2159 | ||
2160 | @c docstring begin (texi-doc-string "guile" "ntohs") | |
2161 | @deffn primitive ntohs in | |
2162 | Returns a new integer from @var{value} by converting from network to | |
2163 | host order. @var{value} must be within the range of a C unsigned short | |
2164 | integer. | |
2165 | @end deffn | |
2166 | ||
2167 | @c docstring begin (texi-doc-string "guile" "htonl") | |
2168 | @deffn primitive htonl in | |
2169 | Returns a new integer from @var{value} by converting from host to | |
2170 | network order. @var{value} must be within the range of a C unsigned | |
2171 | long integer. | |
2172 | @end deffn | |
2173 | ||
2174 | @c docstring begin (texi-doc-string "guile" "ntohl") | |
2175 | @deffn primitive ntohl in | |
2176 | Returns a new integer from @var{value} by converting from network to | |
2177 | host order. @var{value} must be within the range of a C unsigned | |
2178 | long integer. | |
2179 | @end deffn | |
2180 | ||
2181 | These procedures are inconvenient to use at present, but consider: | |
2182 | ||
2183 | @example | |
2184 | (define write-network-long | |
2185 | (lambda (value port) | |
2186 | (let ((v (make-uniform-vector 1 1 0))) | |
2187 | (uniform-vector-set! v 0 (htonl value)) | |
2188 | (uniform-vector-write v port)))) | |
2189 | ||
2190 | (define read-network-long | |
2191 | (lambda (port) | |
2192 | (let ((v (make-uniform-vector 1 1 0))) | |
2193 | (uniform-vector-read! v port) | |
2194 | (ntohl (uniform-vector-ref v 0))))) | |
2195 | @end example | |
2196 | ||
2197 | @node System Identification | |
2198 | @section System Identification | |
2199 | ||
2200 | @c docstring begin (texi-doc-string "guile" "uname") | |
2201 | @deffn primitive uname | |
2202 | Returns an object with some information about the computer system the | |
2203 | program is running on. | |
2204 | @end deffn | |
2205 | ||
2206 | The following procedures accept an object as returned by @code{uname} | |
2207 | and return a selected component. | |
2208 | ||
2209 | @table @code | |
2210 | @item utsname:sysname | |
2211 | The name of the operating system. | |
2212 | @item utsname:nodename | |
2213 | The network name of the computer. | |
2214 | @item utsname:release | |
2215 | The current release level of the operating system implementation. | |
2216 | @item utsname:version | |
2217 | The current version level within the release of the operating system. | |
2218 | @item utsname:machine | |
2219 | A description of the hardware. | |
2220 | @end table | |
2221 | ||
2222 | @deffn primitive software-type | |
2223 | Return a symbol describing the current platform's operating system. | |
2224 | This may be one of AIX, VMS, UNIX, COHERENT, WINDOWS, MS-DOS, OS/2, | |
2225 | THINKC, AMIGA, ATARIST, MACH, or ACORN. | |
2226 | ||
2227 | Note that most varieties of Unix are considered to be simply "UNIX". | |
2228 | That is because when a program depends on features that are not present | |
2229 | on every operating system, it is usually better to test for the presence | |
2230 | or absence of that specific feature. The return value of | |
2231 | @code{software-type} should only be used for this purpose when there is | |
2232 | no other easy or unambiguous way of detecting such features. | |
2233 | @end deffn | |
2234 | ||
2235 | @node Locales | |
2236 | @section Locales | |
2237 | ||
2238 | @c docstring begin (texi-doc-string "guile" "setlocale") | |
2239 | @deffn primitive setlocale category [locale] | |
2240 | If @var{locale} is omitted, returns the current value of the specified | |
2241 | locale category as a system-dependent string. | |
2242 | @var{category} should be specified using the values @code{LC_COLLATE}, | |
2243 | @code{LC_ALL} etc. | |
2244 | ||
2245 | Otherwise the specified locale category is set to | |
2246 | the string @var{locale} | |
2247 | and the new value is returned as a system-dependent string. If @var{locale} | |
2248 | is an empty string, the locale will be set using envirionment variables. | |
2249 | @end deffn |