Commit | Line | Data |
---|---|---|
2da09c3f MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004 | |
4 | @c Free Software Foundation, Inc. | |
5 | @c See the file guile.texi for copying conditions. | |
6 | ||
a0e07ba4 | 7 | @node POSIX |
3229f68b | 8 | @section @acronym{POSIX} System Calls and Networking |
a0e07ba4 NJ |
9 | |
10 | @menu | |
11 | * Conventions:: Conventions employed by the POSIX interface. | |
12 | * Ports and File Descriptors:: Scheme ``ports'' and Unix file descriptors | |
13 | have different representations. | |
14 | * File System:: stat, chown, chmod, etc. | |
15 | * User Information:: Retrieving a user's GECOS (/etc/passwd) entry. | |
16 | * Time:: gettimeofday, localtime, strftime, etc. | |
17 | * Runtime Environment:: Accessing and modifying Guile's environment. | |
18 | * Processes:: getuid, getpid, etc. | |
19 | * Signals:: sigaction, kill, pause, alarm, setitimer, etc. | |
20 | * Terminals and Ptys:: ttyname, tcsetpgrp, etc. | |
21 | * Pipes:: Communicating data between processes. | |
22 | * Networking:: gethostbyaddr, getnetent, socket, bind, listen. | |
23 | * System Identification:: Obtaining information about the system. | |
24 | * Locales:: setlocale, etc. | |
5f378d17 | 25 | * Encryption:: |
a0e07ba4 NJ |
26 | @end menu |
27 | ||
28 | @node Conventions | |
3229f68b | 29 | @subsection @acronym{POSIX} Interface Conventions |
a0e07ba4 NJ |
30 | |
31 | These interfaces provide access to operating system facilities. | |
32 | They provide a simple wrapping around the underlying C interfaces | |
33 | to make usage from Scheme more convenient. They are also used | |
7403e409 | 34 | to implement the Guile port of scsh (@pxref{The Scheme shell (scsh)}). |
a0e07ba4 NJ |
35 | |
36 | Generally there is a single procedure for each corresponding Unix | |
37 | facility. There are some exceptions, such as procedures implemented for | |
38 | speed and convenience in Scheme with no primitive Unix equivalent, | |
7403e409 | 39 | e.g.@: @code{copy-file}. |
a0e07ba4 NJ |
40 | |
41 | The interfaces are intended as far as possible to be portable across | |
42 | different versions of Unix. In some cases procedures which can't be | |
43 | implemented on particular systems may become no-ops, or perform limited | |
44 | actions. In other cases they may throw errors. | |
45 | ||
46 | General naming conventions are as follows: | |
47 | ||
48 | @itemize @bullet | |
49 | @item | |
50 | The Scheme name is often identical to the name of the underlying Unix | |
51 | facility. | |
52 | @item | |
53 | Underscores in Unix procedure names are converted to hyphens. | |
54 | @item | |
85a9b4ed | 55 | Procedures which destructively modify Scheme data have exclamation |
a0e07ba4 NJ |
56 | marks appended, e.g., @code{recv!}. |
57 | @item | |
58 | Predicates (returning only @code{#t} or @code{#f}) have question marks | |
59 | appended, e.g., @code{access?}. | |
60 | @item | |
61 | Some names are changed to avoid conflict with dissimilar interfaces | |
62 | defined by scsh, e.g., @code{primitive-fork}. | |
63 | @item | |
64 | Unix preprocessor names such as @code{EPERM} or @code{R_OK} are converted | |
65 | to Scheme variables of the same name (underscores are not replaced | |
66 | with hyphens). | |
67 | @end itemize | |
68 | ||
69 | Unexpected conditions are generally handled by raising exceptions. | |
70 | There are a few procedures which return a special value if they don't | |
71 | succeed, e.g., @code{getenv} returns @code{#f} if it the requested | |
72 | string is not found in the environment. These cases are noted in | |
73 | the documentation. | |
74 | ||
7403e409 | 75 | For ways to deal with exceptions, see @ref{Exceptions}. |
a0e07ba4 | 76 | |
7403e409 | 77 | Errors which the C library would report by returning a null pointer or |
a0e07ba4 | 78 | through some other means are reported by raising a @code{system-error} |
5982a8e0 KR |
79 | exception with @code{scm-error} (@pxref{Error Reporting}). The |
80 | @var{data} parameter is a list containing the Unix @code{errno} value | |
81 | (an integer). For example, | |
a0e07ba4 | 82 | |
5982a8e0 KR |
83 | @example |
84 | (define (my-handler key func fmt fmtargs data) | |
85 | (display key) (newline) | |
86 | (display func) (newline) | |
87 | (apply format #t fmt fmtargs) (newline) | |
88 | (display data) (newline)) | |
89 | ||
90 | (catch 'system-error | |
91 | (lambda () (dup2 -123 -456)) | |
92 | my-handler) | |
93 | ||
94 | @print{} | |
95 | system-error | |
96 | dup2 | |
97 | Bad file descriptor | |
98 | (9) | |
99 | @end example | |
100 | ||
101 | ||
102 | @sp 1 | |
103 | @defun system-error-errno arglist | |
104 | Return the @code{errno} value from a list which is the arguments to an | |
105 | exception handler. If the exception is not a @code{system-error}, | |
106 | then the return is @code{#f}. For example, | |
a0e07ba4 NJ |
107 | |
108 | @example | |
109 | (catch | |
110 | 'system-error | |
111 | (lambda () | |
112 | (mkdir "/this-ought-to-fail-if-I'm-not-root")) | |
113 | (lambda stuff | |
114 | (let ((errno (system-error-errno stuff))) | |
115 | (cond | |
116 | ((= errno EACCES) | |
117 | (display "You're not allowed to do that.")) | |
118 | ((= errno EEXIST) | |
119 | (display "Already exists.")) | |
120 | (#t | |
121 | (display (strerror errno)))) | |
122 | (newline)))) | |
123 | @end example | |
5982a8e0 KR |
124 | @end defun |
125 | ||
a0e07ba4 NJ |
126 | |
127 | @node Ports and File Descriptors | |
3229f68b | 128 | @subsection Ports and File Descriptors |
a0e07ba4 NJ |
129 | |
130 | Conventions generally follow those of scsh, @ref{The Scheme shell (scsh)}. | |
131 | ||
132 | File ports are implemented using low-level operating system I/O | |
7403e409 NJ |
133 | facilities, with optional buffering to improve efficiency; see |
134 | @ref{File Ports}. | |
a0e07ba4 NJ |
135 | |
136 | Note that some procedures (e.g., @code{recv!}) will accept ports as | |
137 | arguments, but will actually operate directly on the file descriptor | |
138 | underlying the port. Any port buffering is ignored, including the | |
139 | buffer which implements @code{peek-char} and @code{unread-char}. | |
140 | ||
141 | The @code{force-output} and @code{drain-input} procedures can be used | |
142 | to clear the buffers. | |
143 | ||
144 | Each open file port has an associated operating system file descriptor. | |
145 | File descriptors are generally not useful in Scheme programs; however | |
146 | they may be needed when interfacing with foreign code and the Unix | |
147 | environment. | |
148 | ||
149 | A file descriptor can be extracted from a port and a new port can be | |
150 | created from a file descriptor. However a file descriptor is just an | |
85a9b4ed | 151 | integer and the garbage collector doesn't recognize it as a reference |
a0e07ba4 NJ |
152 | to the port. If all other references to the port were dropped, then |
153 | it's likely that the garbage collector would free the port, with the | |
154 | side-effect of closing the file descriptor prematurely. | |
155 | ||
156 | To assist the programmer in avoiding this problem, each port has an | |
7403e409 | 157 | associated @dfn{revealed count} which can be used to keep track of how many |
a0e07ba4 NJ |
158 | times the underlying file descriptor has been stored in other places. |
159 | If a port's revealed count is greater than zero, the file descriptor | |
85a9b4ed | 160 | will not be closed when the port is garbage collected. A programmer |
a0e07ba4 NJ |
161 | can therefore ensure that the revealed count will be greater than |
162 | zero if the file descriptor is needed elsewhere. | |
163 | ||
7403e409 | 164 | For the simple case where a file descriptor is ``imported'' once to become |
a0e07ba4 NJ |
165 | a port, it does not matter if the file descriptor is closed when the |
166 | port is garbage collected. There is no need to maintain a revealed | |
7403e409 | 167 | count. Likewise when ``exporting'' a file descriptor to the external |
a0e07ba4 NJ |
168 | environment, setting the revealed count is not required provided the |
169 | port is kept open (i.e., is pointed to by a live Scheme binding) while | |
170 | the file descriptor is in use. | |
171 | ||
7403e409 NJ |
172 | To correspond with traditional Unix behaviour, three file descriptors |
173 | (0, 1, and 2) are automatically imported when a program starts up and | |
174 | assigned to the initial values of the current/standard input, output, | |
175 | and error ports, respectively. The revealed count for each is | |
176 | initially set to one, so that dropping references to one of these | |
177 | ports will not result in its garbage collection: it could be retrieved | |
178 | with @code{fdopen} or @code{fdes->ports}. | |
a0e07ba4 | 179 | |
8f85c0c6 NJ |
180 | @deffn {Scheme Procedure} port-revealed port |
181 | @deffnx {C Function} scm_port_revealed (port) | |
a0e07ba4 NJ |
182 | Return the revealed count for @var{port}. |
183 | @end deffn | |
184 | ||
8f85c0c6 NJ |
185 | @deffn {Scheme Procedure} set-port-revealed! port rcount |
186 | @deffnx {C Function} scm_set_port_revealed_x (port, rcount) | |
7403e409 | 187 | Sets the revealed count for a @var{port} to @var{rcount}. |
a0e07ba4 NJ |
188 | The return value is unspecified. |
189 | @end deffn | |
190 | ||
8f85c0c6 NJ |
191 | @deffn {Scheme Procedure} fileno port |
192 | @deffnx {C Function} scm_fileno (port) | |
a0e07ba4 NJ |
193 | Return the integer file descriptor underlying @var{port}. Does |
194 | not change its revealed count. | |
195 | @end deffn | |
196 | ||
8f85c0c6 | 197 | @deffn {Scheme Procedure} port->fdes port |
a0e07ba4 NJ |
198 | Returns the integer file descriptor underlying @var{port}. As a |
199 | side effect the revealed count of @var{port} is incremented. | |
200 | @end deffn | |
201 | ||
8f85c0c6 NJ |
202 | @deffn {Scheme Procedure} fdopen fdes modes |
203 | @deffnx {C Function} scm_fdopen (fdes, modes) | |
7403e409 NJ |
204 | Return a new port based on the file descriptor @var{fdes}. Modes are |
205 | given by the string @var{modes}. The revealed count of the port is | |
206 | initialized to zero. The @var{modes} string is the same as that | |
207 | accepted by @code{open-file} (@pxref{File Ports, open-file}). | |
a0e07ba4 NJ |
208 | @end deffn |
209 | ||
8f85c0c6 NJ |
210 | @deffn {Scheme Procedure} fdes->ports fd |
211 | @deffnx {C Function} scm_fdes_to_ports (fd) | |
a0e07ba4 NJ |
212 | Return a list of existing ports which have @var{fdes} as an |
213 | underlying file descriptor, without changing their revealed | |
214 | counts. | |
215 | @end deffn | |
216 | ||
8f85c0c6 | 217 | @deffn {Scheme Procedure} fdes->inport fdes |
a0e07ba4 NJ |
218 | Returns an existing input port which has @var{fdes} as its underlying file |
219 | descriptor, if one exists, and increments its revealed count. | |
220 | Otherwise, returns a new input port with a revealed count of 1. | |
221 | @end deffn | |
222 | ||
8f85c0c6 | 223 | @deffn {Scheme Procedure} fdes->outport fdes |
a0e07ba4 NJ |
224 | Returns an existing output port which has @var{fdes} as its underlying file |
225 | descriptor, if one exists, and increments its revealed count. | |
226 | Otherwise, returns a new output port with a revealed count of 1. | |
227 | @end deffn | |
228 | ||
8f85c0c6 NJ |
229 | @deffn {Scheme Procedure} primitive-move->fdes port fd |
230 | @deffnx {C Function} scm_primitive_move_to_fdes (port, fd) | |
a0e07ba4 NJ |
231 | Moves the underlying file descriptor for @var{port} to the integer |
232 | value @var{fdes} without changing the revealed count of @var{port}. | |
233 | Any other ports already using this descriptor will be automatically | |
234 | shifted to new descriptors and their revealed counts reset to zero. | |
235 | The return value is @code{#f} if the file descriptor already had the | |
236 | required value or @code{#t} if it was moved. | |
237 | @end deffn | |
238 | ||
8f85c0c6 | 239 | @deffn {Scheme Procedure} move->fdes port fdes |
a0e07ba4 NJ |
240 | Moves the underlying file descriptor for @var{port} to the integer |
241 | value @var{fdes} and sets its revealed count to one. Any other ports | |
242 | already using this descriptor will be automatically | |
243 | shifted to new descriptors and their revealed counts reset to zero. | |
244 | The return value is unspecified. | |
245 | @end deffn | |
246 | ||
8f85c0c6 | 247 | @deffn {Scheme Procedure} release-port-handle port |
a0e07ba4 NJ |
248 | Decrements the revealed count for a port. |
249 | @end deffn | |
250 | ||
8f85c0c6 NJ |
251 | @deffn {Scheme Procedure} fsync object |
252 | @deffnx {C Function} scm_fsync (object) | |
a0e07ba4 NJ |
253 | Copies any unwritten data for the specified output file descriptor to disk. |
254 | If @var{port/fd} is a port, its buffer is flushed before the underlying | |
255 | file descriptor is fsync'd. | |
256 | The return value is unspecified. | |
257 | @end deffn | |
258 | ||
8f85c0c6 NJ |
259 | @deffn {Scheme Procedure} open path flags [mode] |
260 | @deffnx {C Function} scm_open (path, flags, mode) | |
a0e07ba4 NJ |
261 | Open the file named by @var{path} for reading and/or writing. |
262 | @var{flags} is an integer specifying how the file should be opened. | |
7403e409 NJ |
263 | @var{mode} is an integer specifying the permission bits of the file, |
264 | if it needs to be created, before the umask (@pxref{Processes}) is | |
265 | applied. The default is 666 (Unix itself has no default). | |
a0e07ba4 NJ |
266 | |
267 | @var{flags} can be constructed by combining variables using @code{logior}. | |
268 | Basic flags are: | |
269 | ||
270 | @defvar O_RDONLY | |
271 | Open the file read-only. | |
272 | @end defvar | |
273 | @defvar O_WRONLY | |
274 | Open the file write-only. | |
275 | @end defvar | |
276 | @defvar O_RDWR | |
277 | Open the file read/write. | |
278 | @end defvar | |
279 | @defvar O_APPEND | |
280 | Append to the file instead of truncating. | |
281 | @end defvar | |
282 | @defvar O_CREAT | |
283 | Create the file if it does not already exist. | |
284 | @end defvar | |
285 | ||
7403e409 | 286 | @xref{File Status Flags,,,libc,The GNU C Library Reference Manual}, |
a0e07ba4 NJ |
287 | for additional flags. |
288 | @end deffn | |
289 | ||
8f85c0c6 NJ |
290 | @deffn {Scheme Procedure} open-fdes path flags [mode] |
291 | @deffnx {C Function} scm_open_fdes (path, flags, mode) | |
a0e07ba4 NJ |
292 | Similar to @code{open} but return a file descriptor instead of |
293 | a port. | |
294 | @end deffn | |
295 | ||
8f85c0c6 NJ |
296 | @deffn {Scheme Procedure} close fd_or_port |
297 | @deffnx {C Function} scm_close (fd_or_port) | |
7403e409 | 298 | Similar to @code{close-port} (@pxref{Closing, close-port}), |
8f85c0c6 NJ |
299 | but also works on file descriptors. A side |
300 | effect of closing a file descriptor is that any ports using that file | |
301 | descriptor are moved to a different file descriptor and have | |
302 | their revealed counts set to zero. | |
a0e07ba4 NJ |
303 | @end deffn |
304 | ||
8f85c0c6 NJ |
305 | @deffn {Scheme Procedure} close-fdes fd |
306 | @deffnx {C Function} scm_close_fdes (fd) | |
7403e409 NJ |
307 | A simple wrapper for the @code{close} system call. Close file |
308 | descriptor @var{fd}, which must be an integer. Unlike @code{close}, | |
309 | the file descriptor will be closed even if a port is using it. The | |
310 | return value is unspecified. | |
a0e07ba4 NJ |
311 | @end deffn |
312 | ||
8f85c0c6 | 313 | @deffn {Scheme Procedure} unread-char char [port] |
c16da59f | 314 | @deffnx {C Function} scm_unread_char (char, port) |
7403e409 NJ |
315 | Place @var{char} in @var{port} so that it will be read by the next |
316 | read operation on that port. If called multiple times, the unread | |
317 | characters will be read again in ``last-in, first-out'' order (i.e.@: | |
318 | a stack). If @var{port} is not supplied, the current input port is | |
319 | used. | |
a0e07ba4 NJ |
320 | @end deffn |
321 | ||
8f85c0c6 | 322 | @deffn {Scheme Procedure} unread-string str port |
a0e07ba4 NJ |
323 | Place the string @var{str} in @var{port} so that its characters will be |
324 | read in subsequent read operations. If called multiple times, the | |
325 | unread characters will be read again in last-in first-out order. If | |
326 | @var{port} is not supplied, the current-input-port is used. | |
327 | @end deffn | |
328 | ||
8f85c0c6 NJ |
329 | @deffn {Scheme Procedure} pipe |
330 | @deffnx {C Function} scm_pipe () | |
a0e07ba4 | 331 | Return a newly created pipe: a pair of ports which are linked |
7403e409 NJ |
332 | together on the local machine. The @acronym{CAR} is the input |
333 | port and the @acronym{CDR} is the output port. Data written (and | |
a0e07ba4 NJ |
334 | flushed) to the output port can be read from the input port. |
335 | Pipes are commonly used for communication with a newly forked | |
336 | child process. The need to flush the output port can be | |
337 | avoided by making it unbuffered using @code{setvbuf}. | |
338 | ||
c6ba64cd KR |
339 | @defvar PIPE_BUF |
340 | A write of up to @code{PIPE_BUF} many bytes to a pipe is atomic, | |
341 | meaning when done it goes into the pipe instantaneously and as a | |
342 | contiguous block (@pxref{Pipe Atomicity,, Atomicity of Pipe I/O, libc, | |
343 | The GNU C Library Reference Manual}). | |
344 | @end defvar | |
345 | ||
346 | Note that the output port is likely to block if too much data has been | |
347 | written but not yet read from the input port. Typically the capacity | |
348 | is @code{PIPE_BUF} bytes. | |
a0e07ba4 NJ |
349 | @end deffn |
350 | ||
351 | The next group of procedures perform a @code{dup2} | |
352 | system call, if @var{newfd} (an | |
353 | integer) is supplied, otherwise a @code{dup}. The file descriptor to be | |
354 | duplicated can be supplied as an integer or contained in a port. The | |
355 | type of value returned varies depending on which procedure is used. | |
356 | ||
357 | All procedures also have the side effect when performing @code{dup2} that any | |
358 | ports using @var{newfd} are moved to a different file descriptor and have | |
359 | their revealed counts set to zero. | |
360 | ||
8f85c0c6 NJ |
361 | @deffn {Scheme Procedure} dup->fdes fd_or_port [fd] |
362 | @deffnx {C Function} scm_dup_to_fdes (fd_or_port, fd) | |
a0e07ba4 NJ |
363 | Return a new integer file descriptor referring to the open file |
364 | designated by @var{fd_or_port}, which must be either an open | |
365 | file port or a file descriptor. | |
366 | @end deffn | |
367 | ||
8f85c0c6 | 368 | @deffn {Scheme Procedure} dup->inport port/fd [newfd] |
a0e07ba4 NJ |
369 | Returns a new input port using the new file descriptor. |
370 | @end deffn | |
371 | ||
8f85c0c6 | 372 | @deffn {Scheme Procedure} dup->outport port/fd [newfd] |
a0e07ba4 NJ |
373 | Returns a new output port using the new file descriptor. |
374 | @end deffn | |
375 | ||
8f85c0c6 | 376 | @deffn {Scheme Procedure} dup port/fd [newfd] |
a0e07ba4 NJ |
377 | Returns a new port if @var{port/fd} is a port, with the same mode as the |
378 | supplied port, otherwise returns an integer file descriptor. | |
379 | @end deffn | |
380 | ||
8f85c0c6 | 381 | @deffn {Scheme Procedure} dup->port port/fd mode [newfd] |
a0e07ba4 NJ |
382 | Returns a new port using the new file descriptor. @var{mode} supplies a |
383 | mode string for the port (@pxref{File Ports, open-file}). | |
384 | @end deffn | |
385 | ||
8f85c0c6 | 386 | @deffn {Scheme Procedure} duplicate-port port modes |
a0e07ba4 NJ |
387 | Returns a new port which is opened on a duplicate of the file |
388 | descriptor underlying @var{port}, with mode string @var{modes} | |
389 | as for @ref{File Ports, open-file}. The two ports | |
390 | will share a file position and file status flags. | |
391 | ||
392 | Unexpected behaviour can result if both ports are subsequently used | |
393 | and the original and/or duplicate ports are buffered. | |
394 | The mode string can include @code{0} to obtain an unbuffered duplicate | |
395 | port. | |
396 | ||
397 | This procedure is equivalent to @code{(dup->port @var{port} @var{modes})}. | |
398 | @end deffn | |
399 | ||
8f85c0c6 NJ |
400 | @deffn {Scheme Procedure} redirect-port old new |
401 | @deffnx {C Function} scm_redirect_port (old, new) | |
a0e07ba4 NJ |
402 | This procedure takes two ports and duplicates the underlying file |
403 | descriptor from @var{old-port} into @var{new-port}. The | |
404 | current file descriptor in @var{new-port} will be closed. | |
405 | After the redirection the two ports will share a file position | |
406 | and file status flags. | |
407 | ||
408 | The return value is unspecified. | |
409 | ||
410 | Unexpected behaviour can result if both ports are subsequently used | |
411 | and the original and/or duplicate ports are buffered. | |
412 | ||
413 | This procedure does not have any side effects on other ports or | |
414 | revealed counts. | |
415 | @end deffn | |
416 | ||
8f85c0c6 NJ |
417 | @deffn {Scheme Procedure} dup2 oldfd newfd |
418 | @deffnx {C Function} scm_dup2 (oldfd, newfd) | |
a0e07ba4 NJ |
419 | A simple wrapper for the @code{dup2} system call. |
420 | Copies the file descriptor @var{oldfd} to descriptor | |
421 | number @var{newfd}, replacing the previous meaning | |
422 | of @var{newfd}. Both @var{oldfd} and @var{newfd} must | |
423 | be integers. | |
7403e409 | 424 | Unlike for @code{dup->fdes} or @code{primitive-move->fdes}, no attempt |
a0e07ba4 NJ |
425 | is made to move away ports which are using @var{newfd}. |
426 | The return value is unspecified. | |
427 | @end deffn | |
428 | ||
8f85c0c6 | 429 | @deffn {Scheme Procedure} port-mode port |
a0e07ba4 NJ |
430 | Return the port modes associated with the open port @var{port}. |
431 | These will not necessarily be identical to the modes used when | |
7403e409 | 432 | the port was opened, since modes such as ``append'' which are |
a0e07ba4 NJ |
433 | used only during port creation are not retained. |
434 | @end deffn | |
435 | ||
8f85c0c6 | 436 | @deffn {Scheme Procedure} port-for-each proc |
c2e15516 MV |
437 | @deffnx {C Function} scm_port_for_each (SCM proc) |
438 | @deffnx {C Function} scm_c_port_for_each (void (*proc)(void *, SCM), void *data) | |
a0e07ba4 | 439 | Apply @var{proc} to each port in the Guile port table |
7403e409 | 440 | (FIXME: what is the Guile port table?) |
a0e07ba4 | 441 | in turn. The return value is unspecified. More specifically, |
7403e409 NJ |
442 | @var{proc} is applied exactly once to every port that exists in the |
443 | system at the time @code{port-for-each} is invoked. Changes to the | |
444 | port table while @code{port-for-each} is running have no effect as far | |
445 | as @code{port-for-each} is concerned. | |
c2e15516 MV |
446 | |
447 | The C function @code{scm_port_for_each} takes a Scheme procedure | |
448 | encoded as a @code{SCM} value, while @code{scm_c_port_for_each} takes | |
449 | a pointer to a C function and passes along a arbitrary @var{data} | |
450 | cookie. | |
a0e07ba4 NJ |
451 | @end deffn |
452 | ||
8f85c0c6 NJ |
453 | @deffn {Scheme Procedure} setvbuf port mode [size] |
454 | @deffnx {C Function} scm_setvbuf (port, mode, size) | |
a0e07ba4 | 455 | Set the buffering mode for @var{port}. @var{mode} can be: |
2ce02471 NJ |
456 | |
457 | @defvar _IONBF | |
a0e07ba4 | 458 | non-buffered |
2ce02471 NJ |
459 | @end defvar |
460 | @defvar _IOLBF | |
a0e07ba4 | 461 | line buffered |
2ce02471 NJ |
462 | @end defvar |
463 | @defvar _IOFBF | |
a0e07ba4 NJ |
464 | block buffered, using a newly allocated buffer of @var{size} bytes. |
465 | If @var{size} is omitted, a default size will be used. | |
2ce02471 | 466 | @end defvar |
a0e07ba4 NJ |
467 | @end deffn |
468 | ||
8f85c0c6 NJ |
469 | @deffn {Scheme Procedure} fcntl object cmd [value] |
470 | @deffnx {C Function} scm_fcntl (object, cmd, value) | |
a0e07ba4 NJ |
471 | Apply @var{command} to the specified file descriptor or the underlying |
472 | file descriptor of the specified port. @var{value} is an optional | |
473 | integer argument. | |
474 | ||
475 | Values for @var{command} are: | |
476 | ||
2ce02471 | 477 | @defvar F_DUPFD |
a0e07ba4 | 478 | Duplicate a file descriptor |
2ce02471 NJ |
479 | @end defvar |
480 | @defvar F_GETFD | |
a0e07ba4 | 481 | Get flags associated with the file descriptor. |
2ce02471 NJ |
482 | @end defvar |
483 | @defvar F_SETFD | |
a0e07ba4 | 484 | Set flags associated with the file descriptor to @var{value}. |
2ce02471 NJ |
485 | @end defvar |
486 | @defvar F_GETFL | |
a0e07ba4 | 487 | Get flags associated with the open file. |
2ce02471 NJ |
488 | @end defvar |
489 | @defvar F_SETFL | |
a0e07ba4 | 490 | Set flags associated with the open file to @var{value} |
2ce02471 NJ |
491 | @end defvar |
492 | @defvar F_GETOWN | |
a0e07ba4 | 493 | Get the process ID of a socket's owner, for @code{SIGIO} signals. |
2ce02471 NJ |
494 | @end defvar |
495 | @defvar F_SETOWN | |
a0e07ba4 | 496 | Set the process that owns a socket to @var{value}, for @code{SIGIO} signals. |
2ce02471 NJ |
497 | @end defvar |
498 | @defvar FD_CLOEXEC | |
7403e409 | 499 | The value used to indicate the ``close on exec'' flag with @code{F_GETFL} or |
a0e07ba4 | 500 | @code{F_SETFL}. |
2ce02471 | 501 | @end defvar |
a0e07ba4 NJ |
502 | @end deffn |
503 | ||
8f85c0c6 NJ |
504 | @deffn {Scheme Procedure} flock file operation |
505 | @deffnx {C Function} scm_flock (file, operation) | |
a0e07ba4 NJ |
506 | Apply or remove an advisory lock on an open file. |
507 | @var{operation} specifies the action to be done: | |
2ce02471 NJ |
508 | |
509 | @defvar LOCK_SH | |
a0e07ba4 NJ |
510 | Shared lock. More than one process may hold a shared lock |
511 | for a given file at a given time. | |
2ce02471 NJ |
512 | @end defvar |
513 | @defvar LOCK_EX | |
a0e07ba4 NJ |
514 | Exclusive lock. Only one process may hold an exclusive lock |
515 | for a given file at a given time. | |
2ce02471 NJ |
516 | @end defvar |
517 | @defvar LOCK_UN | |
a0e07ba4 | 518 | Unlock the file. |
2ce02471 NJ |
519 | @end defvar |
520 | @defvar LOCK_NB | |
a0e07ba4 NJ |
521 | Don't block when locking. May be specified by bitwise OR'ing |
522 | it to one of the other operations. | |
2ce02471 NJ |
523 | @end defvar |
524 | ||
a0e07ba4 | 525 | The return value is not specified. @var{file} may be an open |
85a9b4ed | 526 | file descriptor or an open file descriptor port. |
a0e07ba4 NJ |
527 | @end deffn |
528 | ||
8f85c0c6 NJ |
529 | @deffn {Scheme Procedure} select reads writes excepts [secs [usecs]] |
530 | @deffnx {C Function} scm_select (reads, writes, excepts, secs, usecs) | |
a0e07ba4 | 531 | This procedure has a variety of uses: waiting for the ability |
85a9b4ed | 532 | to provide input, accept output, or the existence of |
a0e07ba4 NJ |
533 | exceptional conditions on a collection of ports or file |
534 | descriptors, or waiting for a timeout to occur. | |
535 | It also returns if interrupted by a signal. | |
536 | ||
537 | @var{reads}, @var{writes} and @var{excepts} can be lists or | |
538 | vectors, with each member a port or a file descriptor. | |
539 | The value returned is a list of three corresponding | |
540 | lists or vectors containing only the members which meet the | |
541 | specified requirement. The ability of port buffers to | |
542 | provide input or accept output is taken into account. | |
543 | Ordering of the input lists or vectors is not preserved. | |
544 | ||
545 | The optional arguments @var{secs} and @var{usecs} specify the | |
546 | timeout. Either @var{secs} can be specified alone, as | |
547 | either an integer or a real number, or both @var{secs} and | |
548 | @var{usecs} can be specified as integers, in which case | |
549 | @var{usecs} is an additional timeout expressed in | |
550 | microseconds. If @var{secs} is omitted or is @code{#f} then | |
551 | select will wait for as long as it takes for one of the other | |
552 | conditions to be satisfied. | |
553 | ||
554 | The scsh version of @code{select} differs as follows: | |
555 | Only vectors are accepted for the first three arguments. | |
556 | The @var{usecs} argument is not supported. | |
557 | Multiple values are returned instead of a list. | |
558 | Duplicates in the input vectors appear only once in output. | |
559 | An additional @code{select!} interface is provided. | |
560 | @end deffn | |
561 | ||
562 | @node File System | |
3229f68b | 563 | @subsection File System |
a0e07ba4 NJ |
564 | |
565 | These procedures allow querying and setting file system attributes | |
566 | (such as owner, | |
567 | permissions, sizes and types of files); deleting, copying, renaming and | |
568 | linking files; creating and removing directories and querying their | |
569 | contents; syncing the file system and creating special files. | |
570 | ||
8f85c0c6 NJ |
571 | @deffn {Scheme Procedure} access? path how |
572 | @deffnx {C Function} scm_access (path, how) | |
ad1c1f18 KR |
573 | Test accessibility of a file under the real UID and GID of the calling |
574 | process. The return is @code{#t} if @var{path} exists and the | |
575 | permissions requested by @var{how} are all allowed, or @code{#f} if | |
576 | not. | |
a0e07ba4 | 577 | |
ad1c1f18 KR |
578 | @var{how} is an integer which is one of the following values, or a |
579 | bitwise-OR (@code{logior}) of multiple values. | |
a0e07ba4 NJ |
580 | |
581 | @defvar R_OK | |
ad1c1f18 | 582 | Test for read permission. |
a0e07ba4 NJ |
583 | @end defvar |
584 | @defvar W_OK | |
ad1c1f18 | 585 | Test for write permission. |
a0e07ba4 NJ |
586 | @end defvar |
587 | @defvar X_OK | |
ad1c1f18 | 588 | Test for execute permission. |
a0e07ba4 NJ |
589 | @end defvar |
590 | @defvar F_OK | |
ad1c1f18 KR |
591 | Test for existence of the file. This is implied by each of the other |
592 | tests, so there's no need to combine it with them. | |
a0e07ba4 | 593 | @end defvar |
ad1c1f18 KR |
594 | |
595 | It's important to note that @code{access?} does not simply indicate | |
596 | what will happen on attempting to read or write a file. In normal | |
597 | circumstances it does, but in a set-UID or set-GID program it doesn't | |
598 | because @code{access?} tests the real ID, whereas an open or execute | |
599 | attempt uses the effective ID. | |
600 | ||
601 | A program which will never run set-UID/GID can ignore the difference | |
602 | between real and effective IDs, but for maximum generality, especially | |
1cd9ea69 KR |
603 | in library functions, it's best not to use @code{access?} to predict |
604 | the result of an open or execute, instead simply attempt that and | |
605 | catch any exception. | |
ad1c1f18 KR |
606 | |
607 | The main use for @code{access?} is to let a set-UID/GID program | |
608 | determine what the invoking user would have been allowed to do, | |
609 | without the greater (or perhaps lesser) privileges afforded by the | |
610 | effective ID. For more on this, see @ref{Testing File Access,,, libc, | |
611 | The GNU C Library Reference Manual}. | |
a0e07ba4 NJ |
612 | @end deffn |
613 | ||
614 | @findex fstat | |
8f85c0c6 NJ |
615 | @deffn {Scheme Procedure} stat object |
616 | @deffnx {C Function} scm_stat (object) | |
a0e07ba4 NJ |
617 | Return an object containing various information about the file |
618 | determined by @var{obj}. @var{obj} can be a string containing | |
619 | a file name or a port or integer file descriptor which is open | |
620 | on a file (in which case @code{fstat} is used as the underlying | |
621 | system call). | |
622 | ||
623 | The object returned by @code{stat} can be passed as a single | |
624 | parameter to the following procedures, all of which return | |
625 | integers: | |
626 | ||
2ce02471 | 627 | @deffn {Scheme Procedure} stat:dev st |
5c3917e7 | 628 | The device number containing the file. |
2ce02471 NJ |
629 | @end deffn |
630 | @deffn {Scheme Procedure} stat:ino st | |
a0e07ba4 NJ |
631 | The file serial number, which distinguishes this file from all |
632 | other files on the same device. | |
2ce02471 NJ |
633 | @end deffn |
634 | @deffn {Scheme Procedure} stat:mode st | |
5c3917e7 KR |
635 | The mode of the file. This is an integer which incorporates file type |
636 | information and file permission bits. See also @code{stat:type} and | |
a0e07ba4 | 637 | @code{stat:perms} below. |
2ce02471 NJ |
638 | @end deffn |
639 | @deffn {Scheme Procedure} stat:nlink st | |
a0e07ba4 | 640 | The number of hard links to the file. |
2ce02471 NJ |
641 | @end deffn |
642 | @deffn {Scheme Procedure} stat:uid st | |
a0e07ba4 | 643 | The user ID of the file's owner. |
2ce02471 NJ |
644 | @end deffn |
645 | @deffn {Scheme Procedure} stat:gid st | |
a0e07ba4 | 646 | The group ID of the file. |
2ce02471 NJ |
647 | @end deffn |
648 | @deffn {Scheme Procedure} stat:rdev st | |
f5f7888d KR |
649 | Device ID; this entry is defined only for character or block special |
650 | files. On some systems this field is not available at all, in which | |
651 | case @code{stat:rdev} returns @code{#f}. | |
2ce02471 NJ |
652 | @end deffn |
653 | @deffn {Scheme Procedure} stat:size st | |
a0e07ba4 | 654 | The size of a regular file in bytes. |
2ce02471 NJ |
655 | @end deffn |
656 | @deffn {Scheme Procedure} stat:atime st | |
a0e07ba4 | 657 | The last access time for the file. |
2ce02471 NJ |
658 | @end deffn |
659 | @deffn {Scheme Procedure} stat:mtime st | |
a0e07ba4 | 660 | The last modification time for the file. |
2ce02471 NJ |
661 | @end deffn |
662 | @deffn {Scheme Procedure} stat:ctime st | |
a0e07ba4 | 663 | The last modification time for the attributes of the file. |
2ce02471 NJ |
664 | @end deffn |
665 | @deffn {Scheme Procedure} stat:blksize st | |
f5f7888d KR |
666 | The optimal block size for reading or writing the file, in bytes. On |
667 | some systems this field is not available, in which case | |
668 | @code{stat:blksize} returns a sensible suggested block size. | |
2ce02471 NJ |
669 | @end deffn |
670 | @deffn {Scheme Procedure} stat:blocks st | |
f5f7888d KR |
671 | The amount of disk space that the file occupies measured in units of |
672 | 512 byte blocks. On some systems this field is not available, in | |
673 | which case @code{stat:blocks} returns @code{#f}. | |
2ce02471 | 674 | @end deffn |
a0e07ba4 NJ |
675 | |
676 | In addition, the following procedures return the information | |
5c3917e7 | 677 | from @code{stat:mode} in a more convenient form: |
a0e07ba4 | 678 | |
2ce02471 | 679 | @deffn {Scheme Procedure} stat:type st |
a0e07ba4 | 680 | A symbol representing the type of file. Possible values are |
7403e409 NJ |
681 | @samp{regular}, @samp{directory}, @samp{symlink}, |
682 | @samp{block-special}, @samp{char-special}, @samp{fifo}, @samp{socket}, | |
683 | and @samp{unknown}. | |
2ce02471 NJ |
684 | @end deffn |
685 | @deffn {Scheme Procedure} stat:perms st | |
a0e07ba4 | 686 | An integer representing the access permission bits. |
2ce02471 | 687 | @end deffn |
a0e07ba4 NJ |
688 | @end deffn |
689 | ||
8f85c0c6 NJ |
690 | @deffn {Scheme Procedure} lstat str |
691 | @deffnx {C Function} scm_lstat (str) | |
a0e07ba4 NJ |
692 | Similar to @code{stat}, but does not follow symbolic links, i.e., |
693 | it will return information about a symbolic link itself, not the | |
694 | file it points to. @var{path} must be a string. | |
695 | @end deffn | |
696 | ||
8f85c0c6 NJ |
697 | @deffn {Scheme Procedure} readlink path |
698 | @deffnx {C Function} scm_readlink (path) | |
a0e07ba4 NJ |
699 | Return the value of the symbolic link named by @var{path} (a |
700 | string), i.e., the file that the link points to. | |
701 | @end deffn | |
702 | ||
703 | @findex fchown | |
704 | @findex lchown | |
8f85c0c6 NJ |
705 | @deffn {Scheme Procedure} chown object owner group |
706 | @deffnx {C Function} scm_chown (object, owner, group) | |
7403e409 NJ |
707 | Change the ownership and group of the file referred to by @var{object} |
708 | to the integer values @var{owner} and @var{group}. @var{object} can | |
709 | be a string containing a file name or, if the platform supports | |
710 | @code{fchown} (@pxref{File Owner,,,libc,The GNU C Library Reference | |
711 | Manual}), a port or integer file descriptor which is open on the file. | |
712 | The return value is unspecified. | |
a0e07ba4 NJ |
713 | |
714 | If @var{object} is a symbolic link, either the | |
715 | ownership of the link or the ownership of the referenced file will be | |
716 | changed depending on the operating system (lchown is | |
717 | unsupported at present). If @var{owner} or @var{group} is specified | |
718 | as @code{-1}, then that ID is not changed. | |
719 | @end deffn | |
720 | ||
721 | @findex fchmod | |
8f85c0c6 NJ |
722 | @deffn {Scheme Procedure} chmod object mode |
723 | @deffnx {C Function} scm_chmod (object, mode) | |
a0e07ba4 NJ |
724 | Changes the permissions of the file referred to by @var{obj}. |
725 | @var{obj} can be a string containing a file name or a port or integer file | |
726 | descriptor which is open on a file (in which case @code{fchmod} is used | |
727 | as the underlying system call). | |
728 | @var{mode} specifies | |
729 | the new permissions as a decimal number, e.g., @code{(chmod "foo" #o755)}. | |
730 | The return value is unspecified. | |
731 | @end deffn | |
732 | ||
8f85c0c6 NJ |
733 | @deffn {Scheme Procedure} utime pathname [actime [modtime]] |
734 | @deffnx {C Function} scm_utime (pathname, actime, modtime) | |
a0e07ba4 NJ |
735 | @code{utime} sets the access and modification times for the |
736 | file named by @var{path}. If @var{actime} or @var{modtime} is | |
737 | not supplied, then the current time is used. @var{actime} and | |
738 | @var{modtime} must be integer time values as returned by the | |
739 | @code{current-time} procedure. | |
740 | @lisp | |
741 | (utime "foo" (- (current-time) 3600)) | |
742 | @end lisp | |
743 | will set the access time to one hour in the past and the | |
744 | modification time to the current time. | |
745 | @end deffn | |
746 | ||
747 | @findex unlink | |
8f85c0c6 NJ |
748 | @deffn {Scheme Procedure} delete-file str |
749 | @deffnx {C Function} scm_delete_file (str) | |
7403e409 NJ |
750 | Deletes (or ``unlinks'') the file whose path is specified by |
751 | @var{str}. | |
a0e07ba4 NJ |
752 | @end deffn |
753 | ||
8f85c0c6 NJ |
754 | @deffn {Scheme Procedure} copy-file oldfile newfile |
755 | @deffnx {C Function} scm_copy_file (oldfile, newfile) | |
7403e409 | 756 | Copy the file specified by @var{oldfile} to @var{newfile}. |
a0e07ba4 NJ |
757 | The return value is unspecified. |
758 | @end deffn | |
759 | ||
760 | @findex rename | |
8f85c0c6 NJ |
761 | @deffn {Scheme Procedure} rename-file oldname newname |
762 | @deffnx {C Function} scm_rename (oldname, newname) | |
a0e07ba4 NJ |
763 | Renames the file specified by @var{oldname} to @var{newname}. |
764 | The return value is unspecified. | |
765 | @end deffn | |
766 | ||
8f85c0c6 NJ |
767 | @deffn {Scheme Procedure} link oldpath newpath |
768 | @deffnx {C Function} scm_link (oldpath, newpath) | |
a0e07ba4 NJ |
769 | Creates a new name @var{newpath} in the file system for the |
770 | file named by @var{oldpath}. If @var{oldpath} is a symbolic | |
771 | link, the link may or may not be followed depending on the | |
772 | system. | |
773 | @end deffn | |
774 | ||
8f85c0c6 NJ |
775 | @deffn {Scheme Procedure} symlink oldpath newpath |
776 | @deffnx {C Function} scm_symlink (oldpath, newpath) | |
7403e409 NJ |
777 | Create a symbolic link named @var{newpath} with the value (i.e., pointing to) |
778 | @var{oldpath}. The return value is unspecified. | |
a0e07ba4 NJ |
779 | @end deffn |
780 | ||
8f85c0c6 NJ |
781 | @deffn {Scheme Procedure} mkdir path [mode] |
782 | @deffnx {C Function} scm_mkdir (path, mode) | |
a0e07ba4 NJ |
783 | Create a new directory named by @var{path}. If @var{mode} is omitted |
784 | then the permissions of the directory file are set using the current | |
7403e409 NJ |
785 | umask (@pxref{Processes}). Otherwise they are set to the decimal |
786 | value specified with @var{mode}. The return value is unspecified. | |
a0e07ba4 NJ |
787 | @end deffn |
788 | ||
8f85c0c6 NJ |
789 | @deffn {Scheme Procedure} rmdir path |
790 | @deffnx {C Function} scm_rmdir (path) | |
a0e07ba4 NJ |
791 | Remove the existing directory named by @var{path}. The directory must |
792 | be empty for this to succeed. The return value is unspecified. | |
793 | @end deffn | |
794 | ||
8f85c0c6 NJ |
795 | @deffn {Scheme Procedure} opendir dirname |
796 | @deffnx {C Function} scm_opendir (dirname) | |
7403e409 | 797 | Open the directory specified by @var{dirname} and return a directory |
a0e07ba4 NJ |
798 | stream. |
799 | @end deffn | |
800 | ||
7403e409 NJ |
801 | @deffn {Scheme Procedure} directory-stream? object |
802 | @deffnx {C Function} scm_directory_stream_p (object) | |
a0e07ba4 NJ |
803 | Return a boolean indicating whether @var{object} is a directory |
804 | stream as returned by @code{opendir}. | |
805 | @end deffn | |
806 | ||
7403e409 NJ |
807 | @deffn {Scheme Procedure} readdir stream |
808 | @deffnx {C Function} scm_readdir (stream) | |
a0e07ba4 NJ |
809 | Return (as a string) the next directory entry from the directory stream |
810 | @var{stream}. If there is no remaining entry to be read then the | |
811 | end of file object is returned. | |
812 | @end deffn | |
813 | ||
7403e409 NJ |
814 | @deffn {Scheme Procedure} rewinddir stream |
815 | @deffnx {C Function} scm_rewinddir (stream) | |
a0e07ba4 NJ |
816 | Reset the directory port @var{stream} so that the next call to |
817 | @code{readdir} will return the first directory entry. | |
818 | @end deffn | |
819 | ||
7403e409 NJ |
820 | @deffn {Scheme Procedure} closedir stream |
821 | @deffnx {C Function} scm_closedir (stream) | |
a0e07ba4 NJ |
822 | Close the directory stream @var{stream}. |
823 | The return value is unspecified. | |
824 | @end deffn | |
825 | ||
bcf009c3 NJ |
826 | Here is an example showing how to display all the entries in a |
827 | directory: | |
828 | ||
829 | @lisp | |
830 | (define dir (opendir "/usr/lib")) | |
831 | (do ((entry (readdir dir) (readdir dir))) | |
832 | ((eof-object? entry)) | |
833 | (display entry)(newline)) | |
834 | (closedir dir) | |
835 | @end lisp | |
836 | ||
8f85c0c6 NJ |
837 | @deffn {Scheme Procedure} sync |
838 | @deffnx {C Function} scm_sync () | |
a0e07ba4 NJ |
839 | Flush the operating system disk buffers. |
840 | The return value is unspecified. | |
841 | @end deffn | |
842 | ||
8f85c0c6 NJ |
843 | @deffn {Scheme Procedure} mknod path type perms dev |
844 | @deffnx {C Function} scm_mknod (path, type, perms, dev) | |
a0e07ba4 | 845 | Creates a new special file, such as a file corresponding to a device. |
7403e409 NJ |
846 | @var{path} specifies the name of the file. @var{type} should be one |
847 | of the following symbols: @samp{regular}, @samp{directory}, | |
848 | @samp{symlink}, @samp{block-special}, @samp{char-special}, | |
849 | @samp{fifo}, or @samp{socket}. @var{perms} (an integer) specifies the | |
850 | file permissions. @var{dev} (an integer) specifies which device the | |
851 | special file refers to. Its exact interpretation depends on the kind | |
852 | of special file being created. | |
a0e07ba4 NJ |
853 | |
854 | E.g., | |
855 | @lisp | |
856 | (mknod "/dev/fd0" 'block-special #o660 (+ (* 2 256) 2)) | |
857 | @end lisp | |
858 | ||
859 | The return value is unspecified. | |
860 | @end deffn | |
861 | ||
8f85c0c6 NJ |
862 | @deffn {Scheme Procedure} tmpnam |
863 | @deffnx {C Function} scm_tmpnam () | |
a0e07ba4 NJ |
864 | Return a name in the file system that does not match any |
865 | existing file. However there is no guarantee that another | |
866 | process will not create the file after @code{tmpnam} is called. | |
867 | Care should be taken if opening the file, e.g., use the | |
868 | @code{O_EXCL} open flag or use @code{mkstemp!} instead. | |
869 | @end deffn | |
870 | ||
8f85c0c6 NJ |
871 | @deffn {Scheme Procedure} mkstemp! tmpl |
872 | @deffnx {C Function} scm_mkstemp (tmpl) | |
a0e07ba4 NJ |
873 | Create a new unique file in the file system and returns a new |
874 | buffered port open for reading and writing to the file. | |
875 | @var{tmpl} is a string specifying where the file should be | |
7403e409 | 876 | created: it must end with @samp{XXXXXX} and will be changed in |
a0e07ba4 NJ |
877 | place to return the name of the temporary file. |
878 | @end deffn | |
879 | ||
8f85c0c6 NJ |
880 | @deffn {Scheme Procedure} dirname filename |
881 | @deffnx {C Function} scm_dirname (filename) | |
a0e07ba4 NJ |
882 | Return the directory name component of the file name |
883 | @var{filename}. If @var{filename} does not contain a directory | |
884 | component, @code{.} is returned. | |
885 | @end deffn | |
886 | ||
8f85c0c6 NJ |
887 | @deffn {Scheme Procedure} basename filename [suffix] |
888 | @deffnx {C Function} scm_basename (filename, suffix) | |
a0e07ba4 NJ |
889 | Return the base name of the file name @var{filename}. The |
890 | base name is the file name without any directory components. | |
85a9b4ed | 891 | If @var{suffix} is provided, and is equal to the end of |
a0e07ba4 | 892 | @var{basename}, it is removed also. |
bcf009c3 NJ |
893 | |
894 | @lisp | |
895 | (basename "/tmp/test.xml" ".xml") | |
896 | @result{} "test" | |
897 | @end lisp | |
a0e07ba4 NJ |
898 | @end deffn |
899 | ||
900 | ||
901 | @node User Information | |
3229f68b | 902 | @subsection User Information |
a0e07ba4 NJ |
903 | |
904 | The facilities in this section provide an interface to the user and | |
905 | group database. | |
906 | They should be used with care since they are not reentrant. | |
907 | ||
908 | The following functions accept an object representing user information | |
909 | and return a selected component: | |
910 | ||
2ce02471 | 911 | @deffn {Scheme Procedure} passwd:name pw |
a0e07ba4 | 912 | The name of the userid. |
2ce02471 NJ |
913 | @end deffn |
914 | @deffn {Scheme Procedure} passwd:passwd pw | |
a0e07ba4 | 915 | The encrypted passwd. |
2ce02471 NJ |
916 | @end deffn |
917 | @deffn {Scheme Procedure} passwd:uid pw | |
a0e07ba4 | 918 | The user id number. |
2ce02471 NJ |
919 | @end deffn |
920 | @deffn {Scheme Procedure} passwd:gid pw | |
a0e07ba4 | 921 | The group id number. |
2ce02471 NJ |
922 | @end deffn |
923 | @deffn {Scheme Procedure} passwd:gecos pw | |
a0e07ba4 | 924 | The full name. |
2ce02471 NJ |
925 | @end deffn |
926 | @deffn {Scheme Procedure} passwd:dir pw | |
a0e07ba4 | 927 | The home directory. |
2ce02471 NJ |
928 | @end deffn |
929 | @deffn {Scheme Procedure} passwd:shell pw | |
a0e07ba4 | 930 | The login shell. |
2ce02471 NJ |
931 | @end deffn |
932 | @sp 1 | |
a0e07ba4 | 933 | |
8f85c0c6 | 934 | @deffn {Scheme Procedure} getpwuid uid |
a0e07ba4 NJ |
935 | Look up an integer userid in the user database. |
936 | @end deffn | |
937 | ||
8f85c0c6 | 938 | @deffn {Scheme Procedure} getpwnam name |
a0e07ba4 NJ |
939 | Look up a user name string in the user database. |
940 | @end deffn | |
941 | ||
8f85c0c6 | 942 | @deffn {Scheme Procedure} setpwent |
a0e07ba4 NJ |
943 | Initializes a stream used by @code{getpwent} to read from the user database. |
944 | The next use of @code{getpwent} will return the first entry. The | |
945 | return value is unspecified. | |
946 | @end deffn | |
947 | ||
8f85c0c6 | 948 | @deffn {Scheme Procedure} getpwent |
a0e07ba4 NJ |
949 | Return the next entry in the user database, using the stream set by |
950 | @code{setpwent}. | |
951 | @end deffn | |
952 | ||
8f85c0c6 | 953 | @deffn {Scheme Procedure} endpwent |
a0e07ba4 NJ |
954 | Closes the stream used by @code{getpwent}. The return value is unspecified. |
955 | @end deffn | |
956 | ||
8f85c0c6 NJ |
957 | @deffn {Scheme Procedure} setpw [arg] |
958 | @deffnx {C Function} scm_setpwent (arg) | |
a0e07ba4 NJ |
959 | If called with a true argument, initialize or reset the password data |
960 | stream. Otherwise, close the stream. The @code{setpwent} and | |
961 | @code{endpwent} procedures are implemented on top of this. | |
962 | @end deffn | |
963 | ||
8f85c0c6 NJ |
964 | @deffn {Scheme Procedure} getpw [user] |
965 | @deffnx {C Function} scm_getpwuid (user) | |
a0e07ba4 NJ |
966 | Look up an entry in the user database. @var{obj} can be an integer, |
967 | a string, or omitted, giving the behaviour of getpwuid, getpwnam | |
968 | or getpwent respectively. | |
969 | @end deffn | |
970 | ||
971 | The following functions accept an object representing group information | |
972 | and return a selected component: | |
973 | ||
2ce02471 | 974 | @deffn {Scheme Procedure} group:name gr |
a0e07ba4 | 975 | The group name. |
2ce02471 NJ |
976 | @end deffn |
977 | @deffn {Scheme Procedure} group:passwd gr | |
a0e07ba4 | 978 | The encrypted group password. |
2ce02471 NJ |
979 | @end deffn |
980 | @deffn {Scheme Procedure} group:gid gr | |
a0e07ba4 | 981 | The group id number. |
2ce02471 NJ |
982 | @end deffn |
983 | @deffn {Scheme Procedure} group:mem gr | |
85a9b4ed | 984 | A list of userids which have this group as a supplementary group. |
2ce02471 NJ |
985 | @end deffn |
986 | @sp 1 | |
a0e07ba4 | 987 | |
8f85c0c6 | 988 | @deffn {Scheme Procedure} getgrgid gid |
85a9b4ed | 989 | Look up an integer group id in the group database. |
a0e07ba4 NJ |
990 | @end deffn |
991 | ||
8f85c0c6 | 992 | @deffn {Scheme Procedure} getgrnam name |
a0e07ba4 NJ |
993 | Look up a group name in the group database. |
994 | @end deffn | |
995 | ||
8f85c0c6 | 996 | @deffn {Scheme Procedure} setgrent |
a0e07ba4 NJ |
997 | Initializes a stream used by @code{getgrent} to read from the group database. |
998 | The next use of @code{getgrent} will return the first entry. | |
999 | The return value is unspecified. | |
1000 | @end deffn | |
1001 | ||
8f85c0c6 | 1002 | @deffn {Scheme Procedure} getgrent |
a0e07ba4 NJ |
1003 | Return the next entry in the group database, using the stream set by |
1004 | @code{setgrent}. | |
1005 | @end deffn | |
1006 | ||
8f85c0c6 | 1007 | @deffn {Scheme Procedure} endgrent |
a0e07ba4 NJ |
1008 | Closes the stream used by @code{getgrent}. |
1009 | The return value is unspecified. | |
1010 | @end deffn | |
1011 | ||
8f85c0c6 NJ |
1012 | @deffn {Scheme Procedure} setgr [arg] |
1013 | @deffnx {C Function} scm_setgrent (arg) | |
a0e07ba4 NJ |
1014 | If called with a true argument, initialize or reset the group data |
1015 | stream. Otherwise, close the stream. The @code{setgrent} and | |
1016 | @code{endgrent} procedures are implemented on top of this. | |
1017 | @end deffn | |
1018 | ||
8f85c0c6 NJ |
1019 | @deffn {Scheme Procedure} getgr [name] |
1020 | @deffnx {C Function} scm_getgrgid (name) | |
a0e07ba4 NJ |
1021 | Look up an entry in the group database. @var{obj} can be an integer, |
1022 | a string, or omitted, giving the behaviour of getgrgid, getgrnam | |
1023 | or getgrent respectively. | |
1024 | @end deffn | |
1025 | ||
1026 | In addition to the accessor procedures for the user database, the | |
1027 | following shortcut procedures are also available. | |
1028 | ||
8f85c0c6 NJ |
1029 | @deffn {Scheme Procedure} cuserid |
1030 | @deffnx {C Function} scm_cuserid () | |
a0e07ba4 NJ |
1031 | Return a string containing a user name associated with the |
1032 | effective user id of the process. Return @code{#f} if this | |
1033 | information cannot be obtained. | |
1034 | @end deffn | |
1035 | ||
8f85c0c6 NJ |
1036 | @deffn {Scheme Procedure} getlogin |
1037 | @deffnx {C Function} scm_getlogin () | |
a0e07ba4 NJ |
1038 | Return a string containing the name of the user logged in on |
1039 | the controlling terminal of the process, or @code{#f} if this | |
1040 | information cannot be obtained. | |
1041 | @end deffn | |
1042 | ||
1043 | ||
1044 | @node Time | |
3229f68b | 1045 | @subsection Time |
a0e07ba4 | 1046 | |
8f85c0c6 NJ |
1047 | @deffn {Scheme Procedure} current-time |
1048 | @deffnx {C Function} scm_current_time () | |
7403e409 | 1049 | Return the number of seconds since 1970-01-01 00:00:00 @acronym{UTC}, |
a0e07ba4 NJ |
1050 | excluding leap seconds. |
1051 | @end deffn | |
1052 | ||
8f85c0c6 NJ |
1053 | @deffn {Scheme Procedure} gettimeofday |
1054 | @deffnx {C Function} scm_gettimeofday () | |
a0e07ba4 | 1055 | Return a pair containing the number of seconds and microseconds |
7403e409 | 1056 | since 1970-01-01 00:00:00 @acronym{UTC}, excluding leap seconds. Note: |
a0e07ba4 NJ |
1057 | whether true microsecond resolution is available depends on the |
1058 | operating system. | |
1059 | @end deffn | |
1060 | ||
1061 | The following procedures either accept an object representing a broken down | |
1062 | time and return a selected component, or accept an object representing | |
1063 | a broken down time and a value and set the component to the value. | |
1064 | The numbers in parentheses give the usual range. | |
1065 | ||
2ce02471 NJ |
1066 | @deffn {Scheme Procedure} tm:sec tm |
1067 | @deffnx {Scheme Procedure} set-tm:sec tm val | |
a0e07ba4 | 1068 | Seconds (0-59). |
2ce02471 NJ |
1069 | @end deffn |
1070 | @deffn {Scheme Procedure} tm:min tm | |
1071 | @deffnx {Scheme Procedure} set-tm:min tm val | |
a0e07ba4 | 1072 | Minutes (0-59). |
2ce02471 NJ |
1073 | @end deffn |
1074 | @deffn {Scheme Procedure} tm:hour tm | |
1075 | @deffnx {Scheme Procedure} set-tm:hour tm val | |
a0e07ba4 | 1076 | Hours (0-23). |
2ce02471 NJ |
1077 | @end deffn |
1078 | @deffn {Scheme Procedure} tm:mday tm | |
1079 | @deffnx {Scheme Procedure} set-tm:mday tm val | |
a0e07ba4 | 1080 | Day of the month (1-31). |
2ce02471 NJ |
1081 | @end deffn |
1082 | @deffn {Scheme Procedure} tm:mon tm | |
1083 | @deffnx {Scheme Procedure} set-tm:mon tm val | |
a0e07ba4 | 1084 | Month (0-11). |
2ce02471 NJ |
1085 | @end deffn |
1086 | @deffn {Scheme Procedure} tm:year tm | |
1087 | @deffnx {Scheme Procedure} set-tm:year tm val | |
a0e07ba4 | 1088 | Year (70-), the year minus 1900. |
2ce02471 NJ |
1089 | @end deffn |
1090 | @deffn {Scheme Procedure} tm:wday tm | |
1091 | @deffnx {Scheme Procedure} set-tm:wday tm val | |
a0e07ba4 | 1092 | Day of the week (0-6) with Sunday represented as 0. |
2ce02471 NJ |
1093 | @end deffn |
1094 | @deffn {Scheme Procedure} tm:yday tm | |
1095 | @deffnx {Scheme Procedure} set-tm:yday tm val | |
a0e07ba4 | 1096 | Day of the year (0-364, 365 in leap years). |
2ce02471 NJ |
1097 | @end deffn |
1098 | @deffn {Scheme Procedure} tm:isdst tm | |
1099 | @deffnx {Scheme Procedure} set-tm:isdst tm val | |
7403e409 NJ |
1100 | Daylight saving indicator (0 for ``no'', greater than 0 for ``yes'', less than |
1101 | 0 for ``unknown''). | |
2ce02471 NJ |
1102 | @end deffn |
1103 | @deffn {Scheme Procedure} tm:gmtoff tm | |
1104 | @deffnx {Scheme Procedure} set-tm:gmtoff tm val | |
7403e409 | 1105 | Time zone offset in seconds west of @acronym{UTC} (-46800 to 43200). |
2ce02471 NJ |
1106 | @end deffn |
1107 | @deffn {Scheme Procedure} tm:zone tm | |
1108 | @deffnx {Scheme Procedure} set-tm:zone tm val | |
a0e07ba4 | 1109 | Time zone label (a string), not necessarily unique. |
2ce02471 NJ |
1110 | @end deffn |
1111 | @sp 1 | |
a0e07ba4 | 1112 | |
8f85c0c6 NJ |
1113 | @deffn {Scheme Procedure} localtime time [zone] |
1114 | @deffnx {C Function} scm_localtime (time, zone) | |
a0e07ba4 NJ |
1115 | Return an object representing the broken down components of |
1116 | @var{time}, an integer like the one returned by | |
1117 | @code{current-time}. The time zone for the calculation is | |
1118 | optionally specified by @var{zone} (a string), otherwise the | |
7403e409 | 1119 | @env{TZ} environment variable or the system default is used. |
a0e07ba4 NJ |
1120 | @end deffn |
1121 | ||
8f85c0c6 NJ |
1122 | @deffn {Scheme Procedure} gmtime time |
1123 | @deffnx {C Function} scm_gmtime (time) | |
a0e07ba4 NJ |
1124 | Return an object representing the broken down components of |
1125 | @var{time}, an integer like the one returned by | |
7403e409 | 1126 | @code{current-time}. The values are calculated for @acronym{UTC}. |
a0e07ba4 NJ |
1127 | @end deffn |
1128 | ||
82512be0 | 1129 | @deffn {Scheme Procedure} mktime sbd-time [zone] |
8f85c0c6 | 1130 | @deffnx {C Function} scm_mktime (sbd_time, zone) |
7403e409 NJ |
1131 | @var{sbd-time} is an object representing broken down time and |
1132 | @code{zone} is an optional time zone specifier (otherwise the @env{TZ} | |
1133 | environment variable or the system default is used). | |
a0e07ba4 | 1134 | |
7403e409 NJ |
1135 | Returns a pair: the @acronym{CAR} is a corresponding integer time |
1136 | value like that returned by @code{current-time}; the @acronym{CDR} is | |
1137 | a broken down time object, similar to @var{sbd-time} but with | |
1138 | normalized values; i.e.@: with corrected @code{tm:wday} and | |
1139 | @code{tm:yday} fields. | |
a0e07ba4 NJ |
1140 | @end deffn |
1141 | ||
8f85c0c6 NJ |
1142 | @deffn {Scheme Procedure} tzset |
1143 | @deffnx {C Function} scm_tzset () | |
7403e409 | 1144 | Initialize the timezone from the @env{TZ} environment variable |
a0e07ba4 NJ |
1145 | or the system default. It's not usually necessary to call this procedure |
1146 | since it's done automatically by other procedures that depend on the | |
1147 | timezone. | |
1148 | @end deffn | |
1149 | ||
8f85c0c6 NJ |
1150 | @deffn {Scheme Procedure} strftime format stime |
1151 | @deffnx {C Function} scm_strftime (format, stime) | |
a0e07ba4 NJ |
1152 | Formats a time specification @var{time} using @var{template}. @var{time} |
1153 | is an object with time components in the form returned by @code{localtime} | |
1154 | or @code{gmtime}. @var{template} is a string which can include formatting | |
7403e409 | 1155 | specifications introduced by a @samp{%} character. The formatting of |
a0e07ba4 NJ |
1156 | month and day names is dependent on the current locale. The value returned |
1157 | is the formatted string. | |
158fab2b | 1158 | @xref{Formatting Calendar Time, , , libc, The GNU C Library Reference Manual}. |
bcf009c3 NJ |
1159 | |
1160 | @lisp | |
1161 | (strftime "%c" (localtime (current-time))) | |
1162 | @result{} "Mon Mar 11 20:17:43 2002" | |
1163 | @end lisp | |
a0e07ba4 NJ |
1164 | @end deffn |
1165 | ||
8f85c0c6 NJ |
1166 | @deffn {Scheme Procedure} strptime format string |
1167 | @deffnx {C Function} scm_strptime (format, string) | |
a0e07ba4 NJ |
1168 | Performs the reverse action to @code{strftime}, parsing |
1169 | @var{string} according to the specification supplied in | |
1170 | @var{template}. The interpretation of month and day names is | |
1171 | dependent on the current locale. The value returned is a pair. | |
7403e409 | 1172 | The @acronym{CAR} has an object with time components |
a0e07ba4 NJ |
1173 | in the form returned by @code{localtime} or @code{gmtime}, |
1174 | but the time zone components | |
1175 | are not usefully set. | |
7403e409 | 1176 | The @acronym{CDR} reports the number of characters from @var{string} |
a0e07ba4 NJ |
1177 | which were used for the conversion. |
1178 | @end deffn | |
1179 | ||
1180 | @defvar internal-time-units-per-second | |
1181 | The value of this variable is the number of time units per second | |
1182 | reported by the following procedures. | |
1183 | @end defvar | |
1184 | ||
8f85c0c6 NJ |
1185 | @deffn {Scheme Procedure} times |
1186 | @deffnx {C Function} scm_times () | |
a0e07ba4 NJ |
1187 | Return an object with information about real and processor |
1188 | time. The following procedures accept such an object as an | |
1189 | argument and return a selected component: | |
1190 | ||
2ce02471 | 1191 | @deffn {Scheme Procedure} tms:clock tms |
a0e07ba4 NJ |
1192 | The current real time, expressed as time units relative to an |
1193 | arbitrary base. | |
2ce02471 NJ |
1194 | @end deffn |
1195 | @deffn {Scheme Procedure} tms:utime tms | |
a0e07ba4 | 1196 | The CPU time units used by the calling process. |
2ce02471 NJ |
1197 | @end deffn |
1198 | @deffn {Scheme Procedure} tms:stime tms | |
a0e07ba4 NJ |
1199 | The CPU time units used by the system on behalf of the calling |
1200 | process. | |
2ce02471 NJ |
1201 | @end deffn |
1202 | @deffn {Scheme Procedure} tms:cutime tms | |
a0e07ba4 NJ |
1203 | The CPU time units used by terminated child processes of the |
1204 | calling process, whose status has been collected (e.g., using | |
1205 | @code{waitpid}). | |
2ce02471 NJ |
1206 | @end deffn |
1207 | @deffn {Scheme Procedure} tms:cstime tms | |
a0e07ba4 NJ |
1208 | Similarly, the CPU times units used by the system on behalf of |
1209 | terminated child processes. | |
2ce02471 | 1210 | @end deffn |
a0e07ba4 NJ |
1211 | @end deffn |
1212 | ||
8f85c0c6 NJ |
1213 | @deffn {Scheme Procedure} get-internal-real-time |
1214 | @deffnx {C Function} scm_get_internal_real_time () | |
a0e07ba4 NJ |
1215 | Return the number of time units since the interpreter was |
1216 | started. | |
1217 | @end deffn | |
1218 | ||
8f85c0c6 NJ |
1219 | @deffn {Scheme Procedure} get-internal-run-time |
1220 | @deffnx {C Function} scm_get_internal_run_time () | |
a0e07ba4 NJ |
1221 | Return the number of time units of processor time used by the |
1222 | interpreter. Both @emph{system} and @emph{user} time are | |
1223 | included but subprocesses are not. | |
1224 | @end deffn | |
1225 | ||
1226 | @node Runtime Environment | |
3229f68b | 1227 | @subsection Runtime Environment |
a0e07ba4 | 1228 | |
8f85c0c6 NJ |
1229 | @deffn {Scheme Procedure} program-arguments |
1230 | @deffnx {Scheme Procedure} command-line | |
1231 | @deffnx {C Function} scm_program_arguments () | |
a0e07ba4 NJ |
1232 | Return the list of command line arguments passed to Guile, as a list of |
1233 | strings. The list includes the invoked program name, which is usually | |
1234 | @code{"guile"}, but excludes switches and parameters for command line | |
1235 | options like @code{-e} and @code{-l}. | |
1236 | @end deffn | |
1237 | ||
8f85c0c6 NJ |
1238 | @deffn {Scheme Procedure} getenv nam |
1239 | @deffnx {C Function} scm_getenv (nam) | |
a0e07ba4 NJ |
1240 | Looks up the string @var{name} in the current environment. The return |
1241 | value is @code{#f} unless a string of the form @code{NAME=VALUE} is | |
1242 | found, in which case the string @code{VALUE} is returned. | |
1243 | @end deffn | |
1244 | ||
8f85c0c6 | 1245 | @deffn {Scheme Procedure} setenv name value |
a0e07ba4 NJ |
1246 | Modifies the environment of the current process, which is |
1247 | also the default environment inherited by child processes. | |
1248 | ||
1249 | If @var{value} is @code{#f}, then @var{name} is removed from the | |
1250 | environment. Otherwise, the string @var{name}=@var{value} is added | |
1251 | to the environment, replacing any existing string with name matching | |
1252 | @var{name}. | |
1253 | ||
1254 | The return value is unspecified. | |
1255 | @end deffn | |
1256 | ||
395b0a34 NJ |
1257 | @deffn {Scheme Procedure} unsetenv name |
1258 | Remove variable @var{name} from the environment. The | |
1259 | name can not contain a @samp{=} character. | |
1260 | @end deffn | |
1261 | ||
8f85c0c6 NJ |
1262 | @deffn {Scheme Procedure} environ [env] |
1263 | @deffnx {C Function} scm_environ (env) | |
a0e07ba4 NJ |
1264 | If @var{env} is omitted, return the current environment (in the |
1265 | Unix sense) as a list of strings. Otherwise set the current | |
1266 | environment, which is also the default environment for child | |
1267 | processes, to the supplied list of strings. Each member of | |
7403e409 NJ |
1268 | @var{env} should be of the form @var{NAME}=@var{VALUE} and values of |
1269 | @var{NAME} should not be duplicated. If @var{env} is supplied | |
a0e07ba4 NJ |
1270 | then the return value is unspecified. |
1271 | @end deffn | |
1272 | ||
8f85c0c6 NJ |
1273 | @deffn {Scheme Procedure} putenv str |
1274 | @deffnx {C Function} scm_putenv (str) | |
a0e07ba4 NJ |
1275 | Modifies the environment of the current process, which is |
1276 | also the default environment inherited by child processes. | |
1277 | ||
1278 | If @var{string} is of the form @code{NAME=VALUE} then it will be written | |
1279 | directly into the environment, replacing any existing environment string | |
1280 | with | |
1281 | name matching @code{NAME}. If @var{string} does not contain an equal | |
1282 | sign, then any existing string with name matching @var{string} will | |
1283 | be removed. | |
1284 | ||
1285 | The return value is unspecified. | |
1286 | @end deffn | |
1287 | ||
1288 | ||
1289 | @node Processes | |
3229f68b | 1290 | @subsection Processes |
a0e07ba4 NJ |
1291 | |
1292 | @findex cd | |
8f85c0c6 NJ |
1293 | @deffn {Scheme Procedure} chdir str |
1294 | @deffnx {C Function} scm_chdir (str) | |
a0e07ba4 NJ |
1295 | Change the current working directory to @var{path}. |
1296 | The return value is unspecified. | |
1297 | @end deffn | |
1298 | ||
1299 | @findex pwd | |
8f85c0c6 NJ |
1300 | @deffn {Scheme Procedure} getcwd |
1301 | @deffnx {C Function} scm_getcwd () | |
a0e07ba4 NJ |
1302 | Return the name of the current working directory. |
1303 | @end deffn | |
1304 | ||
8f85c0c6 NJ |
1305 | @deffn {Scheme Procedure} umask [mode] |
1306 | @deffnx {C Function} scm_umask (mode) | |
7403e409 NJ |
1307 | If @var{mode} is omitted, returns a decimal number representing the |
1308 | current file creation mask. Otherwise the file creation mask is set | |
1309 | to @var{mode} and the previous value is returned. @xref{Setting | |
1310 | Permissions,,Assigning File Permissions,libc,The GNU C Library | |
1311 | Reference Manual}, for more on how to use umasks. | |
a0e07ba4 | 1312 | |
7403e409 | 1313 | E.g., @code{(umask #o022)} sets the mask to octal 22/decimal 18. |
a0e07ba4 NJ |
1314 | @end deffn |
1315 | ||
8f85c0c6 NJ |
1316 | @deffn {Scheme Procedure} chroot path |
1317 | @deffnx {C Function} scm_chroot (path) | |
a0e07ba4 NJ |
1318 | Change the root directory to that specified in @var{path}. |
1319 | This directory will be used for path names beginning with | |
1320 | @file{/}. The root directory is inherited by all children | |
1321 | of the current process. Only the superuser may change the | |
1322 | root directory. | |
1323 | @end deffn | |
1324 | ||
8f85c0c6 NJ |
1325 | @deffn {Scheme Procedure} getpid |
1326 | @deffnx {C Function} scm_getpid () | |
a0e07ba4 NJ |
1327 | Return an integer representing the current process ID. |
1328 | @end deffn | |
1329 | ||
8f85c0c6 NJ |
1330 | @deffn {Scheme Procedure} getgroups |
1331 | @deffnx {C Function} scm_getgroups () | |
a0e07ba4 | 1332 | Return a vector of integers representing the current |
85a9b4ed | 1333 | supplementary group IDs. |
a0e07ba4 NJ |
1334 | @end deffn |
1335 | ||
8f85c0c6 NJ |
1336 | @deffn {Scheme Procedure} getppid |
1337 | @deffnx {C Function} scm_getppid () | |
a0e07ba4 NJ |
1338 | Return an integer representing the process ID of the parent |
1339 | process. | |
1340 | @end deffn | |
1341 | ||
8f85c0c6 NJ |
1342 | @deffn {Scheme Procedure} getuid |
1343 | @deffnx {C Function} scm_getuid () | |
a0e07ba4 NJ |
1344 | Return an integer representing the current real user ID. |
1345 | @end deffn | |
1346 | ||
8f85c0c6 NJ |
1347 | @deffn {Scheme Procedure} getgid |
1348 | @deffnx {C Function} scm_getgid () | |
a0e07ba4 NJ |
1349 | Return an integer representing the current real group ID. |
1350 | @end deffn | |
1351 | ||
8f85c0c6 NJ |
1352 | @deffn {Scheme Procedure} geteuid |
1353 | @deffnx {C Function} scm_geteuid () | |
a0e07ba4 NJ |
1354 | Return an integer representing the current effective user ID. |
1355 | If the system does not support effective IDs, then the real ID | |
66add4eb | 1356 | is returned. @code{(provided? 'EIDs)} reports whether the |
a0e07ba4 NJ |
1357 | system supports effective IDs. |
1358 | @end deffn | |
1359 | ||
8f85c0c6 NJ |
1360 | @deffn {Scheme Procedure} getegid |
1361 | @deffnx {C Function} scm_getegid () | |
a0e07ba4 NJ |
1362 | Return an integer representing the current effective group ID. |
1363 | If the system does not support effective IDs, then the real ID | |
66add4eb | 1364 | is returned. @code{(provided? 'EIDs)} reports whether the |
a0e07ba4 NJ |
1365 | system supports effective IDs. |
1366 | @end deffn | |
1367 | ||
8f85c0c6 NJ |
1368 | @deffn {Scheme Procedure} setuid id |
1369 | @deffnx {C Function} scm_setuid (id) | |
a0e07ba4 NJ |
1370 | Sets both the real and effective user IDs to the integer @var{id}, provided |
1371 | the process has appropriate privileges. | |
1372 | The return value is unspecified. | |
1373 | @end deffn | |
1374 | ||
8f85c0c6 NJ |
1375 | @deffn {Scheme Procedure} setgid id |
1376 | @deffnx {C Function} scm_setgid (id) | |
a0e07ba4 NJ |
1377 | Sets both the real and effective group IDs to the integer @var{id}, provided |
1378 | the process has appropriate privileges. | |
1379 | The return value is unspecified. | |
1380 | @end deffn | |
1381 | ||
8f85c0c6 NJ |
1382 | @deffn {Scheme Procedure} seteuid id |
1383 | @deffnx {C Function} scm_seteuid (id) | |
a0e07ba4 NJ |
1384 | Sets the effective user ID to the integer @var{id}, provided the process |
1385 | has appropriate privileges. If effective IDs are not supported, the | |
7403e409 | 1386 | real ID is set instead---@code{(provided? 'EIDs)} reports whether the |
a0e07ba4 NJ |
1387 | system supports effective IDs. |
1388 | The return value is unspecified. | |
1389 | @end deffn | |
1390 | ||
8f85c0c6 NJ |
1391 | @deffn {Scheme Procedure} setegid id |
1392 | @deffnx {C Function} scm_setegid (id) | |
a0e07ba4 NJ |
1393 | Sets the effective group ID to the integer @var{id}, provided the process |
1394 | has appropriate privileges. If effective IDs are not supported, the | |
7403e409 | 1395 | real ID is set instead---@code{(provided? 'EIDs)} reports whether the |
a0e07ba4 NJ |
1396 | system supports effective IDs. |
1397 | The return value is unspecified. | |
1398 | @end deffn | |
1399 | ||
8f85c0c6 NJ |
1400 | @deffn {Scheme Procedure} getpgrp |
1401 | @deffnx {C Function} scm_getpgrp () | |
a0e07ba4 | 1402 | Return an integer representing the current process group ID. |
7403e409 | 1403 | This is the @acronym{POSIX} definition, not @acronym{BSD}. |
a0e07ba4 NJ |
1404 | @end deffn |
1405 | ||
8f85c0c6 NJ |
1406 | @deffn {Scheme Procedure} setpgid pid pgid |
1407 | @deffnx {C Function} scm_setpgid (pid, pgid) | |
a0e07ba4 NJ |
1408 | Move the process @var{pid} into the process group @var{pgid}. @var{pid} or |
1409 | @var{pgid} must be integers: they can be zero to indicate the ID of the | |
1410 | current process. | |
1411 | Fails on systems that do not support job control. | |
1412 | The return value is unspecified. | |
1413 | @end deffn | |
1414 | ||
8f85c0c6 NJ |
1415 | @deffn {Scheme Procedure} setsid |
1416 | @deffnx {C Function} scm_setsid () | |
a0e07ba4 NJ |
1417 | Creates a new session. The current process becomes the session leader |
1418 | and is put in a new process group. The process will be detached | |
1419 | from its controlling terminal if it has one. | |
1420 | The return value is an integer representing the new process group ID. | |
1421 | @end deffn | |
1422 | ||
8f85c0c6 NJ |
1423 | @deffn {Scheme Procedure} waitpid pid [options] |
1424 | @deffnx {C Function} scm_waitpid (pid, options) | |
a0e07ba4 NJ |
1425 | This procedure collects status information from a child process which |
1426 | has terminated or (optionally) stopped. Normally it will | |
1427 | suspend the calling process until this can be done. If more than one | |
1428 | child process is eligible then one will be chosen by the operating system. | |
1429 | ||
1430 | The value of @var{pid} determines the behaviour: | |
1431 | ||
7403e409 | 1432 | @table @asis |
a0e07ba4 NJ |
1433 | @item @var{pid} greater than 0 |
1434 | Request status information from the specified child process. | |
7403e409 | 1435 | @item @var{pid} equal to -1 or @code{WAIT_ANY} |
2ce02471 | 1436 | @vindex WAIT_ANY |
a0e07ba4 | 1437 | Request status information for any child process. |
7403e409 | 1438 | @item @var{pid} equal to 0 or @code{WAIT_MYPGRP} |
2ce02471 | 1439 | @vindex WAIT_MYPGRP |
a0e07ba4 NJ |
1440 | Request status information for any child process in the current process |
1441 | group. | |
1442 | @item @var{pid} less than -1 | |
1443 | Request status information for any child process whose process group ID | |
7403e409 | 1444 | is @minus{}@var{pid}. |
a0e07ba4 NJ |
1445 | @end table |
1446 | ||
1447 | The @var{options} argument, if supplied, should be the bitwise OR of the | |
1448 | values of zero or more of the following variables: | |
1449 | ||
1450 | @defvar WNOHANG | |
1451 | Return immediately even if there are no child processes to be collected. | |
1452 | @end defvar | |
1453 | ||
1454 | @defvar WUNTRACED | |
1455 | Report status information for stopped processes as well as terminated | |
1456 | processes. | |
1457 | @end defvar | |
1458 | ||
1459 | The return value is a pair containing: | |
1460 | ||
1461 | @enumerate | |
1462 | @item | |
1463 | The process ID of the child process, or 0 if @code{WNOHANG} was | |
1464 | specified and no process was collected. | |
1465 | @item | |
1466 | The integer status value. | |
1467 | @end enumerate | |
1468 | @end deffn | |
1469 | ||
1470 | The following three | |
1471 | functions can be used to decode the process status code returned | |
1472 | by @code{waitpid}. | |
1473 | ||
8f85c0c6 NJ |
1474 | @deffn {Scheme Procedure} status:exit-val status |
1475 | @deffnx {C Function} scm_status_exit_val (status) | |
a0e07ba4 NJ |
1476 | Return the exit status value, as would be set if a process |
1477 | ended normally through a call to @code{exit} or @code{_exit}, | |
1478 | if any, otherwise @code{#f}. | |
1479 | @end deffn | |
1480 | ||
8f85c0c6 NJ |
1481 | @deffn {Scheme Procedure} status:term-sig status |
1482 | @deffnx {C Function} scm_status_term_sig (status) | |
a0e07ba4 NJ |
1483 | Return the signal number which terminated the process, if any, |
1484 | otherwise @code{#f}. | |
1485 | @end deffn | |
1486 | ||
8f85c0c6 NJ |
1487 | @deffn {Scheme Procedure} status:stop-sig status |
1488 | @deffnx {C Function} scm_status_stop_sig (status) | |
a0e07ba4 NJ |
1489 | Return the signal number which stopped the process, if any, |
1490 | otherwise @code{#f}. | |
1491 | @end deffn | |
1492 | ||
8f85c0c6 NJ |
1493 | @deffn {Scheme Procedure} system [cmd] |
1494 | @deffnx {C Function} scm_system (cmd) | |
7403e409 NJ |
1495 | Execute @var{cmd} using the operating system's ``command |
1496 | processor''. Under Unix this is usually the default shell | |
a0e07ba4 NJ |
1497 | @code{sh}. The value returned is @var{cmd}'s exit status as |
1498 | returned by @code{waitpid}, which can be interpreted using the | |
1499 | functions above. | |
1500 | ||
1501 | If @code{system} is called without arguments, return a boolean | |
1502 | indicating whether the command processor is available. | |
1503 | @end deffn | |
1504 | ||
8141bd98 RB |
1505 | @deffn {Scheme Procedure} system* . args |
1506 | @deffnx {C Function} scm_system_star (args) | |
1507 | Execute the command indicated by @var{args}. The first element must | |
1508 | be a string indicating the command to be executed, and the remaining | |
1509 | items must be strings representing each of the arguments to that | |
1510 | command. | |
1511 | ||
1512 | This function returns the exit status of the command as provided by | |
1513 | @code{waitpid}. This value can be handled with @code{status:exit-val} | |
1514 | and the related functions. | |
1515 | ||
1516 | @code{system*} is similar to @code{system}, but accepts only one | |
1517 | string per-argument, and performs no shell interpretation. The | |
1518 | command is executed using fork and execlp. Accordingly this function | |
1519 | may be safer than @code{system} in situations where shell | |
1520 | interpretation is not required. | |
1521 | ||
1522 | Example: (system* "echo" "foo" "bar") | |
1523 | @end deffn | |
1524 | ||
8f85c0c6 NJ |
1525 | @deffn {Scheme Procedure} primitive-exit [status] |
1526 | @deffnx {C Function} scm_primitive_exit (status) | |
a0e07ba4 NJ |
1527 | Terminate the current process without unwinding the Scheme stack. |
1528 | This is would typically be useful after a fork. The exit status | |
1529 | is @var{status} if supplied, otherwise zero. | |
1530 | @end deffn | |
1531 | ||
8f85c0c6 NJ |
1532 | @deffn {Scheme Procedure} execl filename . args |
1533 | @deffnx {C Function} scm_execl (filename, args) | |
a0e07ba4 NJ |
1534 | Executes the file named by @var{path} as a new process image. |
1535 | The remaining arguments are supplied to the process; from a C program | |
85a9b4ed | 1536 | they are accessible as the @code{argv} argument to @code{main}. |
a0e07ba4 NJ |
1537 | Conventionally the first @var{arg} is the same as @var{path}. |
1538 | All arguments must be strings. | |
1539 | ||
1540 | If @var{arg} is missing, @var{path} is executed with a null | |
1541 | argument list, which may have system-dependent side-effects. | |
1542 | ||
1543 | This procedure is currently implemented using the @code{execv} system | |
1544 | call, but we call it @code{execl} because of its Scheme calling interface. | |
1545 | @end deffn | |
1546 | ||
8f85c0c6 NJ |
1547 | @deffn {Scheme Procedure} execlp filename . args |
1548 | @deffnx {C Function} scm_execlp (filename, args) | |
a0e07ba4 NJ |
1549 | Similar to @code{execl}, however if |
1550 | @var{filename} does not contain a slash | |
1551 | then the file to execute will be located by searching the | |
1552 | directories listed in the @code{PATH} environment variable. | |
1553 | ||
1554 | This procedure is currently implemented using the @code{execvp} system | |
1555 | call, but we call it @code{execlp} because of its Scheme calling interface. | |
1556 | @end deffn | |
1557 | ||
8f85c0c6 NJ |
1558 | @deffn {Scheme Procedure} execle filename env . args |
1559 | @deffnx {C Function} scm_execle (filename, env, args) | |
a0e07ba4 NJ |
1560 | Similar to @code{execl}, but the environment of the new process is |
1561 | specified by @var{env}, which must be a list of strings as returned by the | |
1562 | @code{environ} procedure. | |
1563 | ||
1564 | This procedure is currently implemented using the @code{execve} system | |
1565 | call, but we call it @code{execle} because of its Scheme calling interface. | |
1566 | @end deffn | |
1567 | ||
8f85c0c6 NJ |
1568 | @deffn {Scheme Procedure} primitive-fork |
1569 | @deffnx {C Function} scm_fork () | |
7403e409 | 1570 | Creates a new ``child'' process by duplicating the current ``parent'' process. |
a0e07ba4 NJ |
1571 | In the child the return value is 0. In the parent the return value is |
1572 | the integer process ID of the child. | |
1573 | ||
1574 | This procedure has been renamed from @code{fork} to avoid a naming conflict | |
1575 | with the scsh fork. | |
1576 | @end deffn | |
1577 | ||
8f85c0c6 NJ |
1578 | @deffn {Scheme Procedure} nice incr |
1579 | @deffnx {C Function} scm_nice (incr) | |
a0e07ba4 NJ |
1580 | Increment the priority of the current process by @var{incr}. A higher |
1581 | priority value means that the process runs less often. | |
1582 | The return value is unspecified. | |
1583 | @end deffn | |
1584 | ||
8f85c0c6 NJ |
1585 | @deffn {Scheme Procedure} setpriority which who prio |
1586 | @deffnx {C Function} scm_setpriority (which, who, prio) | |
2ce02471 NJ |
1587 | @vindex PRIO_PROCESS |
1588 | @vindex PRIO_PGRP | |
1589 | @vindex PRIO_USER | |
a0e07ba4 NJ |
1590 | Set the scheduling priority of the process, process group |
1591 | or user, as indicated by @var{which} and @var{who}. @var{which} | |
1592 | is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP} | |
1593 | or @code{PRIO_USER}, and @var{who} is interpreted relative to | |
1594 | @var{which} (a process identifier for @code{PRIO_PROCESS}, | |
004fe2c8 | 1595 | process group identifier for @code{PRIO_PGRP}, and a user |
a0e07ba4 NJ |
1596 | identifier for @code{PRIO_USER}. A zero value of @var{who} |
1597 | denotes the current process, process group, or user. | |
7403e409 NJ |
1598 | @var{prio} is a value in the range [@minus{}20,20]. The default |
1599 | priority is 0; lower priorities (in numerical terms) cause more | |
1600 | favorable scheduling. Sets the priority of all of the specified | |
1601 | processes. Only the super-user may lower priorities. The return | |
1602 | value is not specified. | |
a0e07ba4 NJ |
1603 | @end deffn |
1604 | ||
8f85c0c6 NJ |
1605 | @deffn {Scheme Procedure} getpriority which who |
1606 | @deffnx {C Function} scm_getpriority (which, who) | |
2ce02471 NJ |
1607 | @vindex PRIO_PROCESS |
1608 | @vindex PRIO_PGRP | |
1609 | @vindex PRIO_USER | |
a0e07ba4 NJ |
1610 | Return the scheduling priority of the process, process group |
1611 | or user, as indicated by @var{which} and @var{who}. @var{which} | |
1612 | is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP} | |
7403e409 | 1613 | or @code{PRIO_USER}, and @var{who} should be interpreted depending on |
a0e07ba4 NJ |
1614 | @var{which} (a process identifier for @code{PRIO_PROCESS}, |
1615 | process group identifier for @code{PRIO_PGRP}, and a user | |
7403e409 | 1616 | identifier for @code{PRIO_USER}). A zero value of @var{who} |
a0e07ba4 NJ |
1617 | denotes the current process, process group, or user. Return |
1618 | the highest priority (lowest numerical value) of any of the | |
1619 | specified processes. | |
1620 | @end deffn | |
1621 | ||
1622 | ||
1623 | @node Signals | |
3229f68b | 1624 | @subsection Signals |
a0e07ba4 NJ |
1625 | |
1626 | Procedures to raise, handle and wait for signals. | |
1627 | ||
8f85c0c6 NJ |
1628 | @deffn {Scheme Procedure} kill pid sig |
1629 | @deffnx {C Function} scm_kill (pid, sig) | |
a0e07ba4 NJ |
1630 | Sends a signal to the specified process or group of processes. |
1631 | ||
1632 | @var{pid} specifies the processes to which the signal is sent: | |
1633 | ||
7403e409 | 1634 | @table @asis |
a0e07ba4 NJ |
1635 | @item @var{pid} greater than 0 |
1636 | The process whose identifier is @var{pid}. | |
1637 | @item @var{pid} equal to 0 | |
1638 | All processes in the current process group. | |
1639 | @item @var{pid} less than -1 | |
1640 | The process group whose identifier is -@var{pid} | |
1641 | @item @var{pid} equal to -1 | |
1642 | If the process is privileged, all processes except for some special | |
1643 | system processes. Otherwise, all processes with the current effective | |
1644 | user ID. | |
1645 | @end table | |
1646 | ||
1647 | @var{sig} should be specified using a variable corresponding to | |
1648 | the Unix symbolic name, e.g., | |
1649 | ||
1650 | @defvar SIGHUP | |
1651 | Hang-up signal. | |
1652 | @end defvar | |
1653 | ||
1654 | @defvar SIGINT | |
1655 | Interrupt signal. | |
1656 | @end defvar | |
7403e409 NJ |
1657 | |
1658 | A full list of signals on the GNU system may be found in @ref{Standard | |
1659 | Signals,,,libc,The GNU C Library Reference Manual}. | |
a0e07ba4 NJ |
1660 | @end deffn |
1661 | ||
8f85c0c6 NJ |
1662 | @deffn {Scheme Procedure} raise sig |
1663 | @deffnx {C Function} scm_raise (sig) | |
a0e07ba4 | 1664 | Sends a specified signal @var{sig} to the current process, where |
7403e409 | 1665 | @var{sig} is as described for the @code{kill} procedure. |
a0e07ba4 NJ |
1666 | @end deffn |
1667 | ||
b6506f45 | 1668 | @deffn {Scheme Procedure} sigaction signum [handler [flags [thread]]] |
8f85c0c6 | 1669 | @deffnx {C Function} scm_sigaction (signum, handler, flags) |
b6506f45 | 1670 | @deffnx {C Function} scm_sigaction_for_thread (signum, handler, flags, thread) |
a0e07ba4 NJ |
1671 | Install or report the signal handler for a specified signal. |
1672 | ||
1673 | @var{signum} is the signal number, which can be specified using the value | |
1674 | of variables such as @code{SIGINT}. | |
1675 | ||
b6506f45 | 1676 | If @var{handler} is omitted, @code{sigaction} returns a pair: the |
7403e409 NJ |
1677 | @acronym{CAR} is the current signal hander, which will be either an |
1678 | integer with the value @code{SIG_DFL} (default action) or | |
1679 | @code{SIG_IGN} (ignore), or the Scheme procedure which handles the | |
1680 | signal, or @code{#f} if a non-Scheme procedure handles the signal. | |
1681 | The @acronym{CDR} contains the current @code{sigaction} flags for the | |
1682 | handler. | |
a0e07ba4 | 1683 | |
b6506f45 | 1684 | If @var{handler} is provided, it is installed as the new handler for |
0a50eeaa NJ |
1685 | @var{signum}. @var{handler} can be a Scheme procedure taking one |
1686 | argument, or the value of @code{SIG_DFL} (default action) or | |
a0e07ba4 | 1687 | @code{SIG_IGN} (ignore), or @code{#f} to restore whatever signal handler |
b6506f45 MV |
1688 | was installed before @code{sigaction} was first used. When a scheme |
1689 | procedure has been specified, that procedure will run in the given | |
1690 | @var{thread}. When no thread has been given, the thread that made this | |
1691 | call to @code{sigaction} is used. | |
1692 | ||
1693 | Flags can optionally be specified for the new handler (@code{SA_RESTART} | |
1694 | will always be added if it's available and the system is using | |
1695 | restartable system calls.) The return value is a pair with information | |
1696 | about the old handler as described above. | |
a0e07ba4 | 1697 | |
7403e409 | 1698 | This interface does not provide access to the ``signal blocking'' |
a0e07ba4 NJ |
1699 | facility. Maybe this is not needed, since the thread support may |
1700 | provide solutions to the problem of consistent access to data | |
1701 | structures. | |
1702 | @end deffn | |
1703 | ||
8f85c0c6 NJ |
1704 | @deffn {Scheme Procedure} restore-signals |
1705 | @deffnx {C Function} scm_restore_signals () | |
a0e07ba4 NJ |
1706 | Return all signal handlers to the values they had before any call to |
1707 | @code{sigaction} was made. The return value is unspecified. | |
1708 | @end deffn | |
1709 | ||
8f85c0c6 NJ |
1710 | @deffn {Scheme Procedure} alarm i |
1711 | @deffnx {C Function} scm_alarm (i) | |
a0e07ba4 NJ |
1712 | Set a timer to raise a @code{SIGALRM} signal after the specified |
1713 | number of seconds (an integer). It's advisable to install a signal | |
1714 | handler for | |
1715 | @code{SIGALRM} beforehand, since the default action is to terminate | |
1716 | the process. | |
1717 | ||
1718 | The return value indicates the time remaining for the previous alarm, | |
1719 | if any. The new value replaces the previous alarm. If there was | |
1720 | no previous alarm, the return value is zero. | |
1721 | @end deffn | |
1722 | ||
8f85c0c6 NJ |
1723 | @deffn {Scheme Procedure} pause |
1724 | @deffnx {C Function} scm_pause () | |
a0e07ba4 NJ |
1725 | Pause the current process (thread?) until a signal arrives whose |
1726 | action is to either terminate the current process or invoke a | |
1727 | handler procedure. The return value is unspecified. | |
1728 | @end deffn | |
1729 | ||
8f85c0c6 NJ |
1730 | @deffn {Scheme Procedure} sleep i |
1731 | @deffnx {C Function} scm_sleep (i) | |
a0e07ba4 NJ |
1732 | Wait for the given number of seconds (an integer) or until a signal |
1733 | arrives. The return value is zero if the time elapses or the number | |
1734 | of seconds remaining otherwise. | |
1735 | @end deffn | |
1736 | ||
8f85c0c6 NJ |
1737 | @deffn {Scheme Procedure} usleep i |
1738 | @deffnx {C Function} scm_usleep (i) | |
7403e409 NJ |
1739 | Sleep for @var{i} microseconds. @code{usleep} is not available on |
1740 | all platforms. [FIXME: so what happens when it isn't?] | |
a0e07ba4 NJ |
1741 | @end deffn |
1742 | ||
8f85c0c6 NJ |
1743 | @deffn {Scheme Procedure} setitimer which_timer interval_seconds interval_microseconds value_seconds value_microseconds |
1744 | @deffnx {C Function} scm_setitimer (which_timer, interval_seconds, interval_microseconds, value_seconds, value_microseconds) | |
a0e07ba4 NJ |
1745 | Set the timer specified by @var{which_timer} according to the given |
1746 | @var{interval_seconds}, @var{interval_microseconds}, | |
9401323e NJ |
1747 | @var{value_seconds}, and @var{value_microseconds} values. |
1748 | ||
1749 | Return information about the timer's previous setting. | |
9401323e NJ |
1750 | |
1751 | The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL}, | |
1752 | and @code{ITIMER_PROF}. | |
1753 | ||
1754 | The return value will be a list of two cons pairs representing the | |
a0e07ba4 | 1755 | current state of the given timer. The first pair is the seconds and |
9401323e NJ |
1756 | microseconds of the timer @code{it_interval}, and the second pair is |
1757 | the seconds and microseconds of the timer @code{it_value}. | |
a0e07ba4 NJ |
1758 | @end deffn |
1759 | ||
8f85c0c6 NJ |
1760 | @deffn {Scheme Procedure} getitimer which_timer |
1761 | @deffnx {C Function} scm_getitimer (which_timer) | |
7403e409 | 1762 | Return information about the timer specified by @var{which_timer}. |
9401323e NJ |
1763 | |
1764 | The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL}, | |
1765 | and @code{ITIMER_PROF}. | |
1766 | ||
1767 | The return value will be a list of two cons pairs representing the | |
1768 | current state of the given timer. The first pair is the seconds and | |
1769 | microseconds of the timer @code{it_interval}, and the second pair is | |
1770 | the seconds and microseconds of the timer @code{it_value}. | |
a0e07ba4 NJ |
1771 | @end deffn |
1772 | ||
1773 | ||
1774 | @node Terminals and Ptys | |
3229f68b | 1775 | @subsection Terminals and Ptys |
a0e07ba4 | 1776 | |
8f85c0c6 NJ |
1777 | @deffn {Scheme Procedure} isatty? port |
1778 | @deffnx {C Function} scm_isatty_p (port) | |
a0e07ba4 NJ |
1779 | Return @code{#t} if @var{port} is using a serial non--file |
1780 | device, otherwise @code{#f}. | |
1781 | @end deffn | |
1782 | ||
8f85c0c6 NJ |
1783 | @deffn {Scheme Procedure} ttyname port |
1784 | @deffnx {C Function} scm_ttyname (port) | |
a0e07ba4 NJ |
1785 | Return a string with the name of the serial terminal device |
1786 | underlying @var{port}. | |
1787 | @end deffn | |
1788 | ||
8f85c0c6 NJ |
1789 | @deffn {Scheme Procedure} ctermid |
1790 | @deffnx {C Function} scm_ctermid () | |
a0e07ba4 NJ |
1791 | Return a string containing the file name of the controlling |
1792 | terminal for the current process. | |
1793 | @end deffn | |
1794 | ||
8f85c0c6 NJ |
1795 | @deffn {Scheme Procedure} tcgetpgrp port |
1796 | @deffnx {C Function} scm_tcgetpgrp (port) | |
a0e07ba4 NJ |
1797 | Return the process group ID of the foreground process group |
1798 | associated with the terminal open on the file descriptor | |
1799 | underlying @var{port}. | |
1800 | ||
1801 | If there is no foreground process group, the return value is a | |
1802 | number greater than 1 that does not match the process group ID | |
1803 | of any existing process group. This can happen if all of the | |
1804 | processes in the job that was formerly the foreground job have | |
1805 | terminated, and no other job has yet been moved into the | |
1806 | foreground. | |
1807 | @end deffn | |
1808 | ||
8f85c0c6 NJ |
1809 | @deffn {Scheme Procedure} tcsetpgrp port pgid |
1810 | @deffnx {C Function} scm_tcsetpgrp (port, pgid) | |
a0e07ba4 NJ |
1811 | Set the foreground process group ID for the terminal used by the file |
1812 | descriptor underlying @var{port} to the integer @var{pgid}. | |
1813 | The calling process | |
1814 | must be a member of the same session as @var{pgid} and must have the same | |
1815 | controlling terminal. The return value is unspecified. | |
1816 | @end deffn | |
1817 | ||
1818 | @node Pipes | |
3229f68b | 1819 | @subsection Pipes |
a0e07ba4 NJ |
1820 | |
1821 | The following procedures provide an interface to the @code{popen} and | |
7403e409 | 1822 | @code{pclose} system routines. The code is in a separate ``popen'' |
a0e07ba4 NJ |
1823 | module: |
1824 | ||
1825 | @smalllisp | |
1826 | (use-modules (ice-9 popen)) | |
1827 | @end smalllisp | |
1828 | ||
1829 | @findex popen | |
8f85c0c6 | 1830 | @deffn {Scheme Procedure} open-pipe command modes |
a0e07ba4 NJ |
1831 | Executes the shell command @var{command} (a string) in a subprocess. |
1832 | A pipe to the process is created and returned. @var{modes} specifies | |
1833 | whether an input or output pipe to the process is created: it should | |
1834 | be the value of @code{OPEN_READ} or @code{OPEN_WRITE}. | |
1835 | @end deffn | |
1836 | ||
8f85c0c6 | 1837 | @deffn {Scheme Procedure} open-input-pipe command |
a0e07ba4 | 1838 | Equivalent to @code{open-pipe} with mode @code{OPEN_READ}. |
bcf009c3 NJ |
1839 | |
1840 | @lisp | |
1841 | (read-line (open-input-pipe "date")) | |
1842 | @result{} "Mon Mar 11 20:10:44 GMT 2002" | |
1843 | ||
1844 | (waitpid WAIT_ANY) | |
1845 | @result{} (24160 . 0) | |
1846 | @end lisp | |
a0e07ba4 NJ |
1847 | @end deffn |
1848 | ||
8f85c0c6 | 1849 | @deffn {Scheme Procedure} open-output-pipe command |
a0e07ba4 NJ |
1850 | Equivalent to @code{open-pipe} with mode @code{OPEN_WRITE}. |
1851 | @end deffn | |
1852 | ||
1853 | @findex pclose | |
8f85c0c6 | 1854 | @deffn {Scheme Procedure} close-pipe port |
a0e07ba4 NJ |
1855 | Closes the pipe created by @code{open-pipe}, then waits for the process |
1856 | to terminate and returns its status value, @xref{Processes, waitpid}, for | |
1857 | information on how to interpret this value. | |
1858 | ||
1859 | @code{close-port} (@pxref{Closing, close-port}) can also be used to | |
1860 | close a pipe, but doesn't return the status. | |
1861 | @end deffn | |
1862 | ||
1863 | @node Networking | |
3229f68b | 1864 | @subsection Networking |
a0e07ba4 NJ |
1865 | |
1866 | @menu | |
1867 | * Network Address Conversion:: | |
5f378d17 TTN |
1868 | * Network Databases:: |
1869 | * Network Sockets and Communication:: | |
bcf009c3 | 1870 | * Internet Socket Examples:: |
a0e07ba4 NJ |
1871 | @end menu |
1872 | ||
1873 | @node Network Address Conversion | |
3229f68b | 1874 | @subsubsection Network Address Conversion |
a0e07ba4 NJ |
1875 | |
1876 | This section describes procedures which convert internet addresses | |
1877 | between numeric and string formats. | |
1878 | ||
3229f68b | 1879 | @subsubheading IPv4 Address Conversion |
a0e07ba4 | 1880 | |
957f9f62 KR |
1881 | An IPv4 Internet address is a 4-byte value, represented in Guile as an |
1882 | integer in network byte order (meaning the first byte is the most | |
1883 | significant in the number). | |
1884 | ||
1885 | @defvar INADDR_LOOPBACK | |
1886 | The address of the local host using the loopback device, ie.@: | |
1887 | @samp{127.0.0.1}. | |
1888 | @end defvar | |
1889 | ||
1890 | @defvar INADDR_BROADCAST | |
1891 | The broadcast address on the local network. | |
1892 | @end defvar | |
1893 | ||
1894 | @c INADDR_NONE is defined in the code, but serves no purpose. | |
1895 | @c inet_addr() returns it as an error indication, but that function | |
1896 | @c isn't provided, for the good reason that inet_aton() does the same | |
1897 | @c job and gives an unambiguous error indication. (INADDR_NONE is a | |
1898 | @c valid 4-byte value, in glibc it's the same as INADDR_BROADCAST.) | |
1899 | @c | |
1900 | @c @defvar INADDR_NONE | |
1901 | @c No address. | |
1902 | @c @end defvar | |
1903 | ||
8f85c0c6 NJ |
1904 | @deffn {Scheme Procedure} inet-aton address |
1905 | @deffnx {C Function} scm_inet_aton (address) | |
a0e07ba4 NJ |
1906 | Convert an IPv4 Internet address from printable string |
1907 | (dotted decimal notation) to an integer. E.g., | |
1908 | ||
1909 | @lisp | |
1910 | (inet-aton "127.0.0.1") @result{} 2130706433 | |
1911 | @end lisp | |
1912 | @end deffn | |
1913 | ||
8f85c0c6 NJ |
1914 | @deffn {Scheme Procedure} inet-ntoa inetid |
1915 | @deffnx {C Function} scm_inet_ntoa (inetid) | |
a0e07ba4 NJ |
1916 | Convert an IPv4 Internet address to a printable |
1917 | (dotted decimal notation) string. E.g., | |
1918 | ||
1919 | @lisp | |
1920 | (inet-ntoa 2130706433) @result{} "127.0.0.1" | |
1921 | @end lisp | |
1922 | @end deffn | |
1923 | ||
8f85c0c6 NJ |
1924 | @deffn {Scheme Procedure} inet-netof address |
1925 | @deffnx {C Function} scm_inet_netof (address) | |
a0e07ba4 NJ |
1926 | Return the network number part of the given IPv4 |
1927 | Internet address. E.g., | |
1928 | ||
1929 | @lisp | |
1930 | (inet-netof 2130706433) @result{} 127 | |
1931 | @end lisp | |
1932 | @end deffn | |
1933 | ||
8f85c0c6 NJ |
1934 | @deffn {Scheme Procedure} inet-lnaof address |
1935 | @deffnx {C Function} scm_lnaof (address) | |
a0e07ba4 NJ |
1936 | Return the local-address-with-network part of the given |
1937 | IPv4 Internet address, using the obsolete class A/B/C system. | |
1938 | E.g., | |
1939 | ||
1940 | @lisp | |
1941 | (inet-lnaof 2130706433) @result{} 1 | |
1942 | @end lisp | |
1943 | @end deffn | |
1944 | ||
8f85c0c6 NJ |
1945 | @deffn {Scheme Procedure} inet-makeaddr net lna |
1946 | @deffnx {C Function} scm_inet_makeaddr (net, lna) | |
a0e07ba4 NJ |
1947 | Make an IPv4 Internet address by combining the network number |
1948 | @var{net} with the local-address-within-network number | |
1949 | @var{lna}. E.g., | |
1950 | ||
1951 | @lisp | |
1952 | (inet-makeaddr 127 1) @result{} 2130706433 | |
1953 | @end lisp | |
1954 | @end deffn | |
1955 | ||
3229f68b | 1956 | @subsubheading IPv6 Address Conversion |
a0e07ba4 | 1957 | |
8f85c0c6 NJ |
1958 | @deffn {Scheme Procedure} inet-ntop family address |
1959 | @deffnx {C Function} scm_inet_ntop (family, address) | |
a0e07ba4 NJ |
1960 | Convert a network address into a printable string. |
1961 | Note that unlike the C version of this function, | |
1962 | the input is an integer with normal host byte ordering. | |
1963 | @var{family} can be @code{AF_INET} or @code{AF_INET6}. E.g., | |
1964 | ||
1965 | @lisp | |
1966 | (inet-ntop AF_INET 2130706433) @result{} "127.0.0.1" | |
1967 | (inet-ntop AF_INET6 (- (expt 2 128) 1)) @result{} | |
1968 | ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff | |
1969 | @end lisp | |
1970 | @end deffn | |
1971 | ||
8f85c0c6 NJ |
1972 | @deffn {Scheme Procedure} inet-pton family address |
1973 | @deffnx {C Function} scm_inet_pton (family, address) | |
a0e07ba4 NJ |
1974 | Convert a string containing a printable network address to |
1975 | an integer address. Note that unlike the C version of this | |
1976 | function, | |
1977 | the result is an integer with normal host byte ordering. | |
1978 | @var{family} can be @code{AF_INET} or @code{AF_INET6}. E.g., | |
1979 | ||
1980 | @lisp | |
1981 | (inet-pton AF_INET "127.0.0.1") @result{} 2130706433 | |
1982 | (inet-pton AF_INET6 "::1") @result{} 1 | |
1983 | @end lisp | |
1984 | @end deffn | |
1985 | ||
1986 | ||
1987 | @node Network Databases | |
3229f68b | 1988 | @subsubsection Network Databases |
a0e07ba4 NJ |
1989 | |
1990 | This section describes procedures which query various network databases. | |
1991 | Care should be taken when using the database routines since they are not | |
1992 | reentrant. | |
1993 | ||
3229f68b | 1994 | @subsubheading The Host Database |
a0e07ba4 NJ |
1995 | |
1996 | A @dfn{host object} is a structure that represents what is known about a | |
1997 | network host, and is the usual way of representing a system's network | |
1998 | identity inside software. | |
1999 | ||
2000 | The following functions accept a host object and return a selected | |
2001 | component: | |
2002 | ||
8f85c0c6 | 2003 | @deffn {Scheme Procedure} hostent:name host |
7403e409 | 2004 | The ``official'' hostname for @var{host}. |
a0e07ba4 | 2005 | @end deffn |
8f85c0c6 | 2006 | @deffn {Scheme Procedure} hostent:aliases host |
a0e07ba4 NJ |
2007 | A list of aliases for @var{host}. |
2008 | @end deffn | |
8f85c0c6 | 2009 | @deffn {Scheme Procedure} hostent:addrtype host |
a0e07ba4 NJ |
2010 | The host address type. For hosts with Internet addresses, this will |
2011 | return @code{AF_INET}. | |
2012 | @end deffn | |
8f85c0c6 | 2013 | @deffn {Scheme Procedure} hostent:length host |
a0e07ba4 NJ |
2014 | The length of each address for @var{host}, in bytes. |
2015 | @end deffn | |
8f85c0c6 | 2016 | @deffn {Scheme Procedure} hostent:addr-list host |
a0e07ba4 NJ |
2017 | The list of network addresses associated with @var{host}. |
2018 | @end deffn | |
2019 | ||
2020 | The following procedures are used to search the host database: | |
2021 | ||
8f85c0c6 NJ |
2022 | @deffn {Scheme Procedure} gethost [host] |
2023 | @deffnx {Scheme Procedure} gethostbyname hostname | |
2024 | @deffnx {Scheme Procedure} gethostbyaddr address | |
2025 | @deffnx {C Function} scm_gethost (host) | |
a0e07ba4 NJ |
2026 | Look up a host by name or address, returning a host object. The |
2027 | @code{gethost} procedure will accept either a string name or an integer | |
2028 | address; if given no arguments, it behaves like @code{gethostent} (see | |
2029 | below). If a name or address is supplied but the address can not be | |
2030 | found, an error will be thrown to one of the keys: | |
2031 | @code{host-not-found}, @code{try-again}, @code{no-recovery} or | |
2032 | @code{no-data}, corresponding to the equivalent @code{h_error} values. | |
2033 | Unusual conditions may result in errors thrown to the | |
2034 | @code{system-error} or @code{misc_error} keys. | |
bcf009c3 NJ |
2035 | |
2036 | @lisp | |
2037 | (gethost "www.gnu.org") | |
2038 | @result{} #("www.gnu.org" () 2 4 (3353880842)) | |
2039 | ||
2040 | (gethostbyname "www.emacs.org") | |
2041 | @result{} #("emacs.org" ("www.emacs.org") 2 4 (1073448978)) | |
2042 | @end lisp | |
a0e07ba4 NJ |
2043 | @end deffn |
2044 | ||
2045 | The following procedures may be used to step through the host | |
2046 | database from beginning to end. | |
2047 | ||
8f85c0c6 | 2048 | @deffn {Scheme Procedure} sethostent [stayopen] |
a0e07ba4 NJ |
2049 | Initialize an internal stream from which host objects may be read. This |
2050 | procedure must be called before any calls to @code{gethostent}, and may | |
2051 | also be called afterward to reset the host entry stream. If | |
2052 | @var{stayopen} is supplied and is not @code{#f}, the database is not | |
2053 | closed by subsequent @code{gethostbyname} or @code{gethostbyaddr} calls, | |
2054 | possibly giving an efficiency gain. | |
2055 | @end deffn | |
2056 | ||
8f85c0c6 | 2057 | @deffn {Scheme Procedure} gethostent |
a0e07ba4 NJ |
2058 | Return the next host object from the host database, or @code{#f} if |
2059 | there are no more hosts to be found (or an error has been encountered). | |
2060 | This procedure may not be used before @code{sethostent} has been called. | |
2061 | @end deffn | |
2062 | ||
8f85c0c6 | 2063 | @deffn {Scheme Procedure} endhostent |
a0e07ba4 NJ |
2064 | Close the stream used by @code{gethostent}. The return value is unspecified. |
2065 | @end deffn | |
2066 | ||
8f85c0c6 NJ |
2067 | @deffn {Scheme Procedure} sethost [stayopen] |
2068 | @deffnx {C Function} scm_sethost (stayopen) | |
a0e07ba4 NJ |
2069 | If @var{stayopen} is omitted, this is equivalent to @code{endhostent}. |
2070 | Otherwise it is equivalent to @code{sethostent stayopen}. | |
2071 | @end deffn | |
3229f68b MV |
2072 | |
2073 | @subsubheading The Network Database | |
a0e07ba4 NJ |
2074 | |
2075 | The following functions accept an object representing a network | |
2076 | and return a selected component: | |
2077 | ||
8f85c0c6 | 2078 | @deffn {Scheme Procedure} netent:name net |
7403e409 | 2079 | The ``official'' network name. |
a0e07ba4 | 2080 | @end deffn |
8f85c0c6 | 2081 | @deffn {Scheme Procedure} netent:aliases net |
a0e07ba4 NJ |
2082 | A list of aliases for the network. |
2083 | @end deffn | |
8f85c0c6 | 2084 | @deffn {Scheme Procedure} netent:addrtype net |
a0e07ba4 NJ |
2085 | The type of the network number. Currently, this returns only |
2086 | @code{AF_INET}. | |
2087 | @end deffn | |
8f85c0c6 | 2088 | @deffn {Scheme Procedure} netent:net net |
a0e07ba4 NJ |
2089 | The network number. |
2090 | @end deffn | |
2091 | ||
2092 | The following procedures are used to search the network database: | |
2093 | ||
8f85c0c6 NJ |
2094 | @deffn {Scheme Procedure} getnet [net] |
2095 | @deffnx {Scheme Procedure} getnetbyname net-name | |
2096 | @deffnx {Scheme Procedure} getnetbyaddr net-number | |
2097 | @deffnx {C Function} scm_getnet (net) | |
a0e07ba4 NJ |
2098 | Look up a network by name or net number in the network database. The |
2099 | @var{net-name} argument must be a string, and the @var{net-number} | |
2100 | argument must be an integer. @code{getnet} will accept either type of | |
2101 | argument, behaving like @code{getnetent} (see below) if no arguments are | |
2102 | given. | |
2103 | @end deffn | |
2104 | ||
2105 | The following procedures may be used to step through the network | |
2106 | database from beginning to end. | |
2107 | ||
8f85c0c6 | 2108 | @deffn {Scheme Procedure} setnetent [stayopen] |
a0e07ba4 NJ |
2109 | Initialize an internal stream from which network objects may be read. This |
2110 | procedure must be called before any calls to @code{getnetent}, and may | |
2111 | also be called afterward to reset the net entry stream. If | |
2112 | @var{stayopen} is supplied and is not @code{#f}, the database is not | |
2113 | closed by subsequent @code{getnetbyname} or @code{getnetbyaddr} calls, | |
2114 | possibly giving an efficiency gain. | |
2115 | @end deffn | |
2116 | ||
8f85c0c6 | 2117 | @deffn {Scheme Procedure} getnetent |
a0e07ba4 NJ |
2118 | Return the next entry from the network database. |
2119 | @end deffn | |
2120 | ||
8f85c0c6 | 2121 | @deffn {Scheme Procedure} endnetent |
a0e07ba4 NJ |
2122 | Close the stream used by @code{getnetent}. The return value is unspecified. |
2123 | @end deffn | |
2124 | ||
8f85c0c6 NJ |
2125 | @deffn {Scheme Procedure} setnet [stayopen] |
2126 | @deffnx {C Function} scm_setnet (stayopen) | |
a0e07ba4 NJ |
2127 | If @var{stayopen} is omitted, this is equivalent to @code{endnetent}. |
2128 | Otherwise it is equivalent to @code{setnetent stayopen}. | |
2129 | @end deffn | |
2130 | ||
3229f68b | 2131 | @subsubheading The Protocol Database |
a0e07ba4 NJ |
2132 | |
2133 | The following functions accept an object representing a protocol | |
2134 | and return a selected component: | |
2135 | ||
8f85c0c6 | 2136 | @deffn {Scheme Procedure} protoent:name protocol |
7403e409 | 2137 | The ``official'' protocol name. |
a0e07ba4 | 2138 | @end deffn |
8f85c0c6 | 2139 | @deffn {Scheme Procedure} protoent:aliases protocol |
a0e07ba4 NJ |
2140 | A list of aliases for the protocol. |
2141 | @end deffn | |
8f85c0c6 | 2142 | @deffn {Scheme Procedure} protoent:proto protocol |
a0e07ba4 NJ |
2143 | The protocol number. |
2144 | @end deffn | |
2145 | ||
2146 | The following procedures are used to search the protocol database: | |
2147 | ||
8f85c0c6 NJ |
2148 | @deffn {Scheme Procedure} getproto [protocol] |
2149 | @deffnx {Scheme Procedure} getprotobyname name | |
2150 | @deffnx {Scheme Procedure} getprotobynumber number | |
2151 | @deffnx {C Function} scm_getproto (protocol) | |
a0e07ba4 NJ |
2152 | Look up a network protocol by name or by number. @code{getprotobyname} |
2153 | takes a string argument, and @code{getprotobynumber} takes an integer | |
2154 | argument. @code{getproto} will accept either type, behaving like | |
2155 | @code{getprotoent} (see below) if no arguments are supplied. | |
2156 | @end deffn | |
2157 | ||
2158 | The following procedures may be used to step through the protocol | |
2159 | database from beginning to end. | |
2160 | ||
8f85c0c6 | 2161 | @deffn {Scheme Procedure} setprotoent [stayopen] |
a0e07ba4 NJ |
2162 | Initialize an internal stream from which protocol objects may be read. This |
2163 | procedure must be called before any calls to @code{getprotoent}, and may | |
2164 | also be called afterward to reset the protocol entry stream. If | |
2165 | @var{stayopen} is supplied and is not @code{#f}, the database is not | |
2166 | closed by subsequent @code{getprotobyname} or @code{getprotobynumber} calls, | |
2167 | possibly giving an efficiency gain. | |
2168 | @end deffn | |
2169 | ||
8f85c0c6 | 2170 | @deffn {Scheme Procedure} getprotoent |
a0e07ba4 NJ |
2171 | Return the next entry from the protocol database. |
2172 | @end deffn | |
2173 | ||
8f85c0c6 | 2174 | @deffn {Scheme Procedure} endprotoent |
a0e07ba4 NJ |
2175 | Close the stream used by @code{getprotoent}. The return value is unspecified. |
2176 | @end deffn | |
2177 | ||
8f85c0c6 NJ |
2178 | @deffn {Scheme Procedure} setproto [stayopen] |
2179 | @deffnx {C Function} scm_setproto (stayopen) | |
a0e07ba4 NJ |
2180 | If @var{stayopen} is omitted, this is equivalent to @code{endprotoent}. |
2181 | Otherwise it is equivalent to @code{setprotoent stayopen}. | |
2182 | @end deffn | |
2183 | ||
3229f68b | 2184 | @subsubheading The Service Database |
a0e07ba4 NJ |
2185 | |
2186 | The following functions accept an object representing a service | |
2187 | and return a selected component: | |
2188 | ||
8f85c0c6 | 2189 | @deffn {Scheme Procedure} servent:name serv |
7403e409 | 2190 | The ``official'' name of the network service. |
a0e07ba4 | 2191 | @end deffn |
8f85c0c6 | 2192 | @deffn {Scheme Procedure} servent:aliases serv |
a0e07ba4 NJ |
2193 | A list of aliases for the network service. |
2194 | @end deffn | |
8f85c0c6 | 2195 | @deffn {Scheme Procedure} servent:port serv |
a0e07ba4 NJ |
2196 | The Internet port used by the service. |
2197 | @end deffn | |
8f85c0c6 | 2198 | @deffn {Scheme Procedure} servent:proto serv |
a0e07ba4 NJ |
2199 | The protocol used by the service. A service may be listed many times |
2200 | in the database under different protocol names. | |
2201 | @end deffn | |
2202 | ||
2203 | The following procedures are used to search the service database: | |
2204 | ||
8f85c0c6 NJ |
2205 | @deffn {Scheme Procedure} getserv [name [protocol]] |
2206 | @deffnx {Scheme Procedure} getservbyname name protocol | |
2207 | @deffnx {Scheme Procedure} getservbyport port protocol | |
2208 | @deffnx {C Function} scm_getserv (name, protocol) | |
a0e07ba4 NJ |
2209 | Look up a network service by name or by service number, and return a |
2210 | network service object. The @var{protocol} argument specifies the name | |
2211 | of the desired protocol; if the protocol found in the network service | |
2212 | database does not match this name, a system error is signalled. | |
2213 | ||
2214 | The @code{getserv} procedure will take either a service name or number | |
2215 | as its first argument; if given no arguments, it behaves like | |
2216 | @code{getservent} (see below). | |
bcf009c3 NJ |
2217 | |
2218 | @lisp | |
2219 | (getserv "imap" "tcp") | |
2220 | @result{} #("imap2" ("imap") 143 "tcp") | |
2221 | ||
2222 | (getservbyport 88 "udp") | |
2223 | @result{} #("kerberos" ("kerberos5" "krb5") 88 "udp") | |
2224 | @end lisp | |
a0e07ba4 NJ |
2225 | @end deffn |
2226 | ||
2227 | The following procedures may be used to step through the service | |
2228 | database from beginning to end. | |
2229 | ||
8f85c0c6 | 2230 | @deffn {Scheme Procedure} setservent [stayopen] |
a0e07ba4 NJ |
2231 | Initialize an internal stream from which service objects may be read. This |
2232 | procedure must be called before any calls to @code{getservent}, and may | |
2233 | also be called afterward to reset the service entry stream. If | |
2234 | @var{stayopen} is supplied and is not @code{#f}, the database is not | |
2235 | closed by subsequent @code{getservbyname} or @code{getservbyport} calls, | |
2236 | possibly giving an efficiency gain. | |
2237 | @end deffn | |
2238 | ||
8f85c0c6 | 2239 | @deffn {Scheme Procedure} getservent |
a0e07ba4 NJ |
2240 | Return the next entry from the services database. |
2241 | @end deffn | |
2242 | ||
8f85c0c6 | 2243 | @deffn {Scheme Procedure} endservent |
a0e07ba4 NJ |
2244 | Close the stream used by @code{getservent}. The return value is unspecified. |
2245 | @end deffn | |
2246 | ||
8f85c0c6 NJ |
2247 | @deffn {Scheme Procedure} setserv [stayopen] |
2248 | @deffnx {C Function} scm_setserv (stayopen) | |
a0e07ba4 NJ |
2249 | If @var{stayopen} is omitted, this is equivalent to @code{endservent}. |
2250 | Otherwise it is equivalent to @code{setservent stayopen}. | |
2251 | @end deffn | |
2252 | ||
2253 | @node Network Sockets and Communication | |
3229f68b | 2254 | @subsubsection Network Sockets and Communication |
a0e07ba4 NJ |
2255 | |
2256 | Socket ports can be created using @code{socket} and @code{socketpair}. | |
2257 | The ports are initially unbuffered, to make reading and writing to the | |
2258 | same port more reliable. A buffer can be added to the port using | |
7403e409 | 2259 | @code{setvbuf}; see @ref{Ports and File Descriptors}. |
a0e07ba4 | 2260 | |
9e996fb1 KR |
2261 | Most systems have limits on how many files and sockets can be open, so |
2262 | it's strongly recommended that socket ports be closed explicitly when | |
2263 | no longer required (@pxref{Ports}). | |
2264 | ||
7403e409 NJ |
2265 | The convention used for ``host'' vs.@: ``network'' addresses is that |
2266 | addresses are always held in host order at the Scheme level. The | |
2267 | procedures in this section automatically convert between host and | |
2268 | network order when required. The arguments and return values are thus | |
2269 | in host order. | |
a0e07ba4 | 2270 | |
8f85c0c6 NJ |
2271 | @deffn {Scheme Procedure} socket family style proto |
2272 | @deffnx {C Function} scm_socket (family, style, proto) | |
a0e07ba4 | 2273 | Return a new socket port of the type specified by @var{family}, |
3dba2dd9 KR |
2274 | @var{style} and @var{proto}. All three parameters are integers. The |
2275 | possible values for @var{family} are as follows, where supported by | |
2276 | the system, | |
2277 | ||
2278 | @defvar PF_UNIX | |
2279 | @defvarx PF_INET | |
2280 | @defvarx PF_INET6 | |
2281 | @end defvar | |
2282 | ||
2283 | The possible values for @var{style} are as follows, again where | |
2284 | supported by the system, | |
2285 | ||
2286 | @defvar SOCK_STREAM | |
2287 | @defvarx SOCK_DGRAM | |
2288 | @defvarx SOCK_RAW | |
2289 | @end defvar | |
a0e07ba4 NJ |
2290 | |
2291 | @var{proto} can be obtained from a protocol name using | |
3dba2dd9 KR |
2292 | @code{getprotobyname} (@pxref{Network Databases}). A value of zero |
2293 | means the default protocol, which is usually right. | |
a0e07ba4 | 2294 | |
3dba2dd9 KR |
2295 | A socket cannot by used for communication until it has been connected |
2296 | somewhere, usually with either @code{connect} or @code{accept} below. | |
a0e07ba4 NJ |
2297 | @end deffn |
2298 | ||
8f85c0c6 NJ |
2299 | @deffn {Scheme Procedure} socketpair family style proto |
2300 | @deffnx {C Function} scm_socketpair (family, style, proto) | |
497cbe20 KR |
2301 | Return a pair, the @code{car} and @code{cdr} of which are two unnamed |
2302 | socket ports connected to each other. The connection is full-duplex, | |
2303 | so data can be transferred in either direction between the two. | |
2304 | ||
2305 | @var{family}, @var{style} and @var{proto} are as per @code{socket} | |
2306 | above. But many systems only support socket pairs in the | |
2307 | @code{PF_UNIX} family. Zero is likely to be the only meaningful value | |
2308 | for @var{proto}. | |
a0e07ba4 NJ |
2309 | @end deffn |
2310 | ||
8f85c0c6 NJ |
2311 | @deffn {Scheme Procedure} getsockopt sock level optname |
2312 | @deffnx {C Function} scm_getsockopt (sock, level, optname) | |
a0e07ba4 NJ |
2313 | Return the value of a particular socket option for the socket |
2314 | port @var{sock}. @var{level} is an integer code for type of | |
2315 | option being requested, e.g., @code{SOL_SOCKET} for | |
2316 | socket-level options. @var{optname} is an integer code for the | |
2317 | option required and should be specified using one of the | |
2318 | symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc. | |
2319 | ||
2320 | The returned value is typically an integer but @code{SO_LINGER} | |
2321 | returns a pair of integers. | |
2322 | @end deffn | |
2323 | ||
8f85c0c6 NJ |
2324 | @deffn {Scheme Procedure} setsockopt sock level optname value |
2325 | @deffnx {C Function} scm_setsockopt (sock, level, optname, value) | |
a0e07ba4 NJ |
2326 | Set the value of a particular socket option for the socket |
2327 | port @var{sock}. @var{level} is an integer code for type of option | |
2328 | being set, e.g., @code{SOL_SOCKET} for socket-level options. | |
2329 | @var{optname} is an | |
2330 | integer code for the option to set and should be specified using one of | |
2331 | the symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc. | |
2332 | @var{value} is the value to which the option should be set. For | |
2333 | most options this must be an integer, but for @code{SO_LINGER} it must | |
2334 | be a pair. | |
2335 | ||
2336 | The return value is unspecified. | |
2337 | @end deffn | |
2338 | ||
8f85c0c6 NJ |
2339 | @deffn {Scheme Procedure} shutdown sock how |
2340 | @deffnx {C Function} scm_shutdown (sock, how) | |
a0e07ba4 | 2341 | Sockets can be closed simply by using @code{close-port}. The |
85a9b4ed | 2342 | @code{shutdown} procedure allows reception or transmission on a |
a0e07ba4 NJ |
2343 | connection to be shut down individually, according to the parameter |
2344 | @var{how}: | |
2345 | ||
2346 | @table @asis | |
2347 | @item 0 | |
2348 | Stop receiving data for this socket. If further data arrives, reject it. | |
2349 | @item 1 | |
2350 | Stop trying to transmit data from this socket. Discard any | |
2351 | data waiting to be sent. Stop looking for acknowledgement of | |
2352 | data already sent; don't retransmit it if it is lost. | |
2353 | @item 2 | |
2354 | Stop both reception and transmission. | |
2355 | @end table | |
2356 | ||
2357 | The return value is unspecified. | |
2358 | @end deffn | |
2359 | ||
8f85c0c6 NJ |
2360 | @deffn {Scheme Procedure} connect sock fam address . args |
2361 | @deffnx {C Function} scm_connect (sock, fam, address, args) | |
a0e07ba4 NJ |
2362 | Initiate a connection from a socket using a specified address |
2363 | family to the address | |
2364 | specified by @var{address} and possibly @var{args}. | |
2365 | The format required for @var{address} | |
2366 | and @var{args} depends on the family of the socket. | |
2367 | ||
2368 | For a socket of family @code{AF_UNIX}, | |
2369 | only @var{address} is specified and must be a string with the | |
2370 | filename where the socket is to be created. | |
2371 | ||
2372 | For a socket of family @code{AF_INET}, | |
2373 | @var{address} must be an integer IPv4 host address and | |
2374 | @var{args} must be a single integer port number. | |
2375 | ||
2376 | For a socket of family @code{AF_INET6}, | |
2377 | @var{address} must be an integer IPv6 host address and | |
2378 | @var{args} may be up to three integers: | |
2379 | port [flowinfo] [scope_id], | |
2380 | where flowinfo and scope_id default to zero. | |
2381 | ||
2382 | The return value is unspecified. | |
2383 | @end deffn | |
2384 | ||
8f85c0c6 NJ |
2385 | @deffn {Scheme Procedure} bind sock fam address . args |
2386 | @deffnx {C Function} scm_bind (sock, fam, address, args) | |
a0e07ba4 NJ |
2387 | Assign an address to the socket port @var{sock}. |
2388 | Generally this only needs to be done for server sockets, | |
2389 | so they know where to look for incoming connections. A socket | |
2390 | without an address will be assigned one automatically when it | |
2391 | starts communicating. | |
2392 | ||
2393 | The format of @var{address} and @var{args} depends | |
2394 | on the family of the socket. | |
2395 | ||
2396 | For a socket of family @code{AF_UNIX}, only @var{address} | |
2397 | is specified and must be a string with the filename where | |
2398 | the socket is to be created. | |
2399 | ||
2400 | For a socket of family @code{AF_INET}, @var{address} | |
2401 | must be an integer IPv4 address and @var{args} | |
2402 | must be a single integer port number. | |
2403 | ||
2404 | The values of the following variables can also be used for | |
2405 | @var{address}: | |
2406 | ||
2407 | @defvar INADDR_ANY | |
2408 | Allow connections from any address. | |
2409 | @end defvar | |
2410 | ||
2411 | @defvar INADDR_LOOPBACK | |
2412 | The address of the local host using the loopback device. | |
2413 | @end defvar | |
2414 | ||
2415 | @defvar INADDR_BROADCAST | |
2416 | The broadcast address on the local network. | |
2417 | @end defvar | |
2418 | ||
2419 | @defvar INADDR_NONE | |
2420 | No address. | |
2421 | @end defvar | |
2422 | ||
2423 | For a socket of family @code{AF_INET6}, @var{address} | |
2424 | must be an integer IPv6 address and @var{args} | |
2425 | may be up to three integers: | |
2426 | port [flowinfo] [scope_id], | |
2427 | where flowinfo and scope_id default to zero. | |
2428 | ||
2429 | The return value is unspecified. | |
2430 | @end deffn | |
2431 | ||
8f85c0c6 NJ |
2432 | @deffn {Scheme Procedure} listen sock backlog |
2433 | @deffnx {C Function} scm_listen (sock, backlog) | |
a0e07ba4 NJ |
2434 | Enable @var{sock} to accept connection |
2435 | requests. @var{backlog} is an integer specifying | |
2436 | the maximum length of the queue for pending connections. | |
2437 | If the queue fills, new clients will fail to connect until | |
2438 | the server calls @code{accept} to accept a connection from | |
2439 | the queue. | |
2440 | ||
2441 | The return value is unspecified. | |
2442 | @end deffn | |
2443 | ||
8f85c0c6 NJ |
2444 | @deffn {Scheme Procedure} accept sock |
2445 | @deffnx {C Function} scm_accept (sock) | |
a0e07ba4 NJ |
2446 | Accept a connection on a bound, listening socket. |
2447 | If there | |
2448 | are no pending connections in the queue, wait until | |
2449 | one is available unless the non-blocking option has been | |
2450 | set on the socket. | |
2451 | ||
2452 | The return value is a | |
7403e409 | 2453 | pair in which the @acronym{CAR} is a new socket port for the |
a0e07ba4 | 2454 | connection and |
7403e409 | 2455 | the @acronym{CDR} is an object with address information about the |
a0e07ba4 NJ |
2456 | client which initiated the connection. |
2457 | ||
2458 | @var{sock} does not become part of the | |
2459 | connection and will continue to accept new requests. | |
2460 | @end deffn | |
2461 | ||
2462 | The following functions take a socket address object, as returned | |
2463 | by @code{accept} and other procedures, and return a selected component. | |
2464 | ||
2ce02471 | 2465 | @deffn {Scheme Procedure} sockaddr:fam sa |
a0e07ba4 NJ |
2466 | The socket family, typically equal to the value of @code{AF_UNIX} or |
2467 | @code{AF_INET}. | |
2ce02471 NJ |
2468 | @end deffn |
2469 | @deffn {Scheme Procedure} sockaddr:path sa | |
a0e07ba4 NJ |
2470 | If the socket family is @code{AF_UNIX}, returns the path of the |
2471 | filename the socket is based on. | |
2ce02471 NJ |
2472 | @end deffn |
2473 | @deffn {Scheme Procedure} sockaddr:addr sa | |
a0e07ba4 NJ |
2474 | If the socket family is @code{AF_INET}, returns the Internet host |
2475 | address. | |
2ce02471 NJ |
2476 | @end deffn |
2477 | @deffn {Scheme Procedure} sockaddr:port sa | |
a0e07ba4 NJ |
2478 | If the socket family is @code{AF_INET}, returns the Internet port |
2479 | number. | |
2ce02471 | 2480 | @end deffn |
a0e07ba4 | 2481 | |
8f85c0c6 NJ |
2482 | @deffn {Scheme Procedure} getsockname sock |
2483 | @deffnx {C Function} scm_getsockname (sock) | |
a0e07ba4 NJ |
2484 | Return the address of @var{sock}, in the same form as the |
2485 | object returned by @code{accept}. On many systems the address | |
c16da59f | 2486 | of a socket in the @code{AF_FILE} namespace cannot be read. |
a0e07ba4 NJ |
2487 | @end deffn |
2488 | ||
8f85c0c6 NJ |
2489 | @deffn {Scheme Procedure} getpeername sock |
2490 | @deffnx {C Function} scm_getpeername (sock) | |
a0e07ba4 NJ |
2491 | Return the address that @var{sock} |
2492 | is connected to, in the same form as the object returned by | |
2493 | @code{accept}. On many systems the address of a socket in the | |
c16da59f | 2494 | @code{AF_FILE} namespace cannot be read. |
a0e07ba4 NJ |
2495 | @end deffn |
2496 | ||
8f85c0c6 NJ |
2497 | @deffn {Scheme Procedure} recv! sock buf [flags] |
2498 | @deffnx {C Function} scm_recv (sock, buf, flags) | |
a0e07ba4 NJ |
2499 | Receive data from a socket port. |
2500 | @var{sock} must already | |
2501 | be bound to the address from which data is to be received. | |
2502 | @var{buf} is a string into which | |
2503 | the data will be written. The size of @var{buf} limits | |
2504 | the amount of | |
2505 | data which can be received: in the case of packet | |
2506 | protocols, if a packet larger than this limit is encountered | |
2507 | then some data | |
2508 | will be irrevocably lost. | |
2509 | ||
2ce02471 NJ |
2510 | @vindex MSG_OOB |
2511 | @vindex MSG_PEEK | |
2512 | @vindex MSG_DONTROUTE | |
7403e409 NJ |
2513 | The optional @var{flags} argument is a value or bitwise OR of |
2514 | @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc. | |
a0e07ba4 NJ |
2515 | |
2516 | The value returned is the number of bytes read from the | |
2517 | socket. | |
2518 | ||
2519 | Note that the data is read directly from the socket file | |
2520 | descriptor: | |
2521 | any unread buffered port data is ignored. | |
2522 | @end deffn | |
2523 | ||
8f85c0c6 NJ |
2524 | @deffn {Scheme Procedure} send sock message [flags] |
2525 | @deffnx {C Function} scm_send (sock, message, flags) | |
2ce02471 NJ |
2526 | @vindex MSG_OOB |
2527 | @vindex MSG_PEEK | |
2528 | @vindex MSG_DONTROUTE | |
a0e07ba4 | 2529 | Transmit the string @var{message} on a socket port @var{sock}. |
7403e409 NJ |
2530 | @var{sock} must already be bound to a destination address. The value |
2531 | returned is the number of bytes transmitted---it's possible for this | |
2532 | to be less than the length of @var{message} if the socket is set to be | |
2533 | non-blocking. The optional @var{flags} argument is a value or bitwise | |
2534 | OR of @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc. | |
a0e07ba4 NJ |
2535 | |
2536 | Note that the data is written directly to the socket | |
2537 | file descriptor: | |
2538 | any unflushed buffered port data is ignored. | |
2539 | @end deffn | |
2540 | ||
8f85c0c6 NJ |
2541 | @deffn {Scheme Procedure} recvfrom! sock str [flags [start [end]]] |
2542 | @deffnx {C Function} scm_recvfrom (sock, str, flags, start, end) | |
a0e07ba4 NJ |
2543 | Return data from the socket port @var{sock} and also |
2544 | information about where the data was received from. | |
2545 | @var{sock} must already be bound to the address from which | |
2546 | data is to be received. @code{str}, is a string into which the | |
2547 | data will be written. The size of @var{str} limits the amount | |
2548 | of data which can be received: in the case of packet protocols, | |
2549 | if a packet larger than this limit is encountered then some | |
2550 | data will be irrevocably lost. | |
2551 | ||
2ce02471 NJ |
2552 | @vindex MSG_OOB |
2553 | @vindex MSG_PEEK | |
2554 | @vindex MSG_DONTROUTE | |
a0e07ba4 NJ |
2555 | The optional @var{flags} argument is a value or bitwise OR of |
2556 | @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc. | |
2557 | ||
7403e409 NJ |
2558 | The value returned is a pair: the @acronym{CAR} is the number of |
2559 | bytes read from the socket and the @acronym{CDR} an address object | |
a0e07ba4 NJ |
2560 | in the same form as returned by @code{accept}. The address |
2561 | will given as @code{#f} if not available, as is usually the | |
2562 | case for stream sockets. | |
2563 | ||
2564 | The @var{start} and @var{end} arguments specify a substring of | |
2565 | @var{str} to which the data should be written. | |
2566 | ||
2567 | Note that the data is read directly from the socket file | |
2568 | descriptor: any unread buffered port data is ignored. | |
2569 | @end deffn | |
2570 | ||
8f85c0c6 NJ |
2571 | @deffn {Scheme Procedure} sendto sock message fam address . args_and_flags |
2572 | @deffnx {C Function} scm_sendto (sock, message, fam, address, args_and_flags) | |
a0e07ba4 NJ |
2573 | Transmit the string @var{message} on the socket port |
2574 | @var{sock}. The | |
2575 | destination address is specified using the @var{fam}, | |
2576 | @var{address} and | |
2577 | @var{args_and_flags} arguments, in a similar way to the | |
2578 | @code{connect} procedure. @var{args_and_flags} contains | |
2579 | the usual connection arguments optionally followed by | |
2580 | a flags argument, which is a value or | |
7403e409 | 2581 | bitwise OR of @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc. |
a0e07ba4 NJ |
2582 | |
2583 | The value returned is the number of bytes transmitted -- | |
2584 | it's possible for | |
2585 | this to be less than the length of @var{message} if the | |
2586 | socket is | |
2587 | set to be non-blocking. | |
2588 | Note that the data is written directly to the socket | |
2589 | file descriptor: | |
2590 | any unflushed buffered port data is ignored. | |
2591 | @end deffn | |
2592 | ||
2593 | The following functions can be used to convert short and long integers | |
7403e409 | 2594 | between ``host'' and ``network'' order. Although the procedures above do |
a0e07ba4 NJ |
2595 | this automatically for addresses, the conversion will still need to |
2596 | be done when sending or receiving encoded integer data from the network. | |
2597 | ||
8f85c0c6 NJ |
2598 | @deffn {Scheme Procedure} htons value |
2599 | @deffnx {C Function} scm_htons (value) | |
a0e07ba4 NJ |
2600 | Convert a 16 bit quantity from host to network byte ordering. |
2601 | @var{value} is packed into 2 bytes, which are then converted | |
2602 | and returned as a new integer. | |
2603 | @end deffn | |
2604 | ||
8f85c0c6 NJ |
2605 | @deffn {Scheme Procedure} ntohs value |
2606 | @deffnx {C Function} scm_ntohs (value) | |
a0e07ba4 NJ |
2607 | Convert a 16 bit quantity from network to host byte ordering. |
2608 | @var{value} is packed into 2 bytes, which are then converted | |
2609 | and returned as a new integer. | |
2610 | @end deffn | |
2611 | ||
8f85c0c6 NJ |
2612 | @deffn {Scheme Procedure} htonl value |
2613 | @deffnx {C Function} scm_htonl (value) | |
a0e07ba4 NJ |
2614 | Convert a 32 bit quantity from host to network byte ordering. |
2615 | @var{value} is packed into 4 bytes, which are then converted | |
2616 | and returned as a new integer. | |
2617 | @end deffn | |
2618 | ||
8f85c0c6 NJ |
2619 | @deffn {Scheme Procedure} ntohl value |
2620 | @deffnx {C Function} scm_ntohl (value) | |
a0e07ba4 NJ |
2621 | Convert a 32 bit quantity from network to host byte ordering. |
2622 | @var{value} is packed into 4 bytes, which are then converted | |
2623 | and returned as a new integer. | |
2624 | @end deffn | |
2625 | ||
2626 | These procedures are inconvenient to use at present, but consider: | |
2627 | ||
2628 | @example | |
2629 | (define write-network-long | |
2630 | (lambda (value port) | |
2631 | (let ((v (make-uniform-vector 1 1 0))) | |
2632 | (uniform-vector-set! v 0 (htonl value)) | |
2633 | (uniform-vector-write v port)))) | |
2634 | ||
2635 | (define read-network-long | |
2636 | (lambda (port) | |
2637 | (let ((v (make-uniform-vector 1 1 0))) | |
2638 | (uniform-vector-read! v port) | |
2639 | (ntohl (uniform-vector-ref v 0))))) | |
2640 | @end example | |
2641 | ||
bcf009c3 NJ |
2642 | |
2643 | @node Internet Socket Examples | |
3229f68b | 2644 | @subsubsection Network Socket Examples |
bcf009c3 | 2645 | |
3229f68b | 2646 | The following give examples of how to use network sockets. |
bcf009c3 | 2647 | |
3229f68b | 2648 | @subsubheading Internet Socket Client Example |
bcf009c3 NJ |
2649 | |
2650 | @cindex socket client example | |
2651 | The following example demonstrates an Internet socket client. | |
2652 | It connects to the HTTP daemon running on the local machine and | |
2653 | returns the contents of the root index URL. | |
2654 | ||
2655 | @example | |
2656 | (let ((s (socket AF_INET SOCK_STREAM 0))) | |
2657 | (connect s AF_INET (inet-aton "127.0.0.1") 80) | |
2658 | (display "GET / HTTP/1.0\r\n\r\n" s) | |
2659 | ||
2660 | (do ((line (read-line s) (read-line s))) | |
2661 | ((eof-object? line)) | |
2662 | (display line) | |
2663 | (newline))) | |
2664 | @end example | |
2665 | ||
2666 | ||
3229f68b | 2667 | @subsubheading Internet Socket Server Example |
bcf009c3 NJ |
2668 | |
2669 | @cindex socket server example | |
2670 | The following example shows a simple Internet server which listens on | |
2671 | port 2904 for incoming connections and sends a greeting back to the | |
2672 | client. | |
2673 | ||
2674 | @example | |
2675 | (let ((s (socket AF_INET SOCK_STREAM 0))) | |
2676 | (setsockopt s SOL_SOCKET SO_REUSEADDR 1) | |
7403e409 NJ |
2677 | ;; @r{Specific address?} |
2678 | ;; @r{(bind s AF_INET (inet-aton "127.0.0.1") 2904)} | |
bcf009c3 NJ |
2679 | (bind s AF_INET INADDR_ANY 2904) |
2680 | (listen s 5) | |
2681 | ||
2682 | (simple-format #t "Listening for clients in pid: ~S" (getpid)) | |
2683 | (newline) | |
2684 | ||
2685 | (while #t | |
2686 | (let* ((client-connection (accept s)) | |
2687 | (client-details (cdr client-connection)) | |
2688 | (client (car client-connection))) | |
2689 | (simple-format #t "Got new client connection: ~S" | |
2690 | client-details) | |
2691 | (newline) | |
2692 | (simple-format #t "Client address: ~S" | |
2693 | (gethostbyaddr | |
2694 | (sockaddr:addr client-details))) | |
2695 | (newline) | |
7403e409 | 2696 | ;; @r{Send back the greeting to the client port} |
bcf009c3 NJ |
2697 | (display "Hello client\r\n" client) |
2698 | (close client)))) | |
2699 | @end example | |
2700 | ||
2701 | ||
a0e07ba4 | 2702 | @node System Identification |
3229f68b | 2703 | @subsection System Identification |
a0e07ba4 NJ |
2704 | |
2705 | This section lists the various procedures Guile provides for accessing | |
2706 | information about the system it runs on. | |
2707 | ||
8f85c0c6 NJ |
2708 | @deffn {Scheme Procedure} uname |
2709 | @deffnx {C Function} scm_uname () | |
a0e07ba4 NJ |
2710 | Return an object with some information about the computer |
2711 | system the program is running on. | |
a0e07ba4 NJ |
2712 | |
2713 | The following procedures accept an object as returned by @code{uname} | |
2714 | and return a selected component. | |
2715 | ||
2ce02471 | 2716 | @deffn {Scheme Procedure} utsname:sysname un |
a0e07ba4 | 2717 | The name of the operating system. |
2ce02471 NJ |
2718 | @end deffn |
2719 | @deffn {Scheme Procedure} utsname:nodename un | |
a0e07ba4 | 2720 | The network name of the computer. |
2ce02471 NJ |
2721 | @end deffn |
2722 | @deffn {Scheme Procedure} utsname:release un | |
a0e07ba4 | 2723 | The current release level of the operating system implementation. |
2ce02471 NJ |
2724 | @end deffn |
2725 | @deffn {Scheme Procedure} utsname:version un | |
a0e07ba4 | 2726 | The current version level within the release of the operating system. |
2ce02471 NJ |
2727 | @end deffn |
2728 | @deffn {Scheme Procedure} utsname:machine un | |
a0e07ba4 | 2729 | A description of the hardware. |
2ce02471 NJ |
2730 | @end deffn |
2731 | @end deffn | |
a0e07ba4 | 2732 | |
8f85c0c6 NJ |
2733 | @deffn {Scheme Procedure} gethostname |
2734 | @deffnx {C Function} scm_gethostname () | |
a0e07ba4 NJ |
2735 | Return the host name of the current processor. |
2736 | @end deffn | |
2737 | ||
8f85c0c6 NJ |
2738 | @deffn {Scheme Procedure} sethostname name |
2739 | @deffnx {C Function} scm_sethostname (name) | |
a0e07ba4 NJ |
2740 | Set the host name of the current processor to @var{name}. May |
2741 | only be used by the superuser. The return value is not | |
2742 | specified. | |
2743 | @end deffn | |
2744 | ||
2745 | @c FIXME::martin: Not in libguile! | |
8f85c0c6 | 2746 | @deffn {Scheme Procedure} software-type |
a0e07ba4 | 2747 | Return a symbol describing the current platform's operating system. |
7403e409 NJ |
2748 | This may be one of @samp{AIX}, @samp{VMS}, @samp{UNIX}, |
2749 | @samp{COHERENT}, @samp{WINDOWS}, @samp{MS-DOS}, @samp{OS/2}, | |
2750 | @samp{THINKC}, @samp{AMIGA}, @samp{ATARIST}, @samp{MACH}, or | |
2751 | @samp{ACORN}. | |
a0e07ba4 | 2752 | |
7403e409 | 2753 | Note that most varieties of Unix are considered to be simply @samp{UNIX}. |
a0e07ba4 NJ |
2754 | That is because when a program depends on features that are not present |
2755 | on every operating system, it is usually better to test for the presence | |
2756 | or absence of that specific feature. The return value of | |
2757 | @code{software-type} should only be used for this purpose when there is | |
2758 | no other easy or unambiguous way of detecting such features. | |
2759 | @end deffn | |
2760 | ||
2761 | @node Locales | |
3229f68b | 2762 | @subsection Locales |
a0e07ba4 | 2763 | |
8f85c0c6 NJ |
2764 | @deffn {Scheme Procedure} setlocale category [locale] |
2765 | @deffnx {C Function} scm_setlocale (category, locale) | |
74f76d62 KR |
2766 | Get or set the current locale, used for various internationalizations. |
2767 | Locales are strings, such as @samp{sv_SE}. | |
2768 | ||
2769 | If @var{locale} is given then the locale for the given category is set | |
2770 | and the new value returned. If @var{locale} is not given then the | |
2771 | current value is returned. @var{category} should be one of the | |
2772 | following values | |
2773 | ||
2774 | @defvar LC_ALL | |
2775 | @defvarx LC_COLLATE | |
2776 | @defvarx LC_CTYPE | |
2777 | @defvarx LC_MESSAGES | |
2778 | @defvarx LC_MONETARY | |
2779 | @defvarx LC_NUMERIC | |
2780 | @defvarx LC_TIME | |
2781 | @end defvar | |
2782 | ||
2783 | A common usage is @samp{(setlocale LC_ALL "")}, which initializes all | |
2784 | categories based on standard environment variables (@code{LANG} etc). | |
2785 | For full details on categories and locale names @pxref{Locales,, | |
2786 | Locales and Internationalization, libc, The GNU C Library Reference | |
2787 | Manual}. | |
a0e07ba4 NJ |
2788 | @end deffn |
2789 | ||
2790 | @node Encryption | |
3229f68b | 2791 | @subsection Encryption |
a0e07ba4 NJ |
2792 | |
2793 | Please note that the procedures in this section are not suited for | |
2794 | strong encryption, they are only interfaces to the well-known and | |
2795 | common system library functions of the same name. They are just as good | |
2796 | (or bad) as the underlying functions, so you should refer to your system | |
2797 | documentation before using them. | |
2798 | ||
8f85c0c6 NJ |
2799 | @deffn {Scheme Procedure} crypt key salt |
2800 | @deffnx {C Function} scm_crypt (key, salt) | |
a0e07ba4 | 2801 | Encrypt @var{key} using @var{salt} as the salt value to the |
9401323e | 2802 | crypt(3) library call. |
a0e07ba4 NJ |
2803 | @end deffn |
2804 | ||
5f378d17 TTN |
2805 | Although @code{getpass} is not an encryption procedure per se, it |
2806 | appears here because it is often used in combination with @code{crypt}: | |
a0e07ba4 | 2807 | |
8f85c0c6 NJ |
2808 | @deffn {Scheme Procedure} getpass prompt |
2809 | @deffnx {C Function} scm_getpass (prompt) | |
a0e07ba4 NJ |
2810 | Display @var{prompt} to the standard error output and read |
2811 | a password from @file{/dev/tty}. If this file is not | |
2812 | accessible, it reads from standard input. The password may be | |
2813 | up to 127 characters in length. Additional characters and the | |
2814 | terminating newline character are discarded. While reading | |
2815 | the password, echoing and the generation of signals by special | |
2816 | characters is disabled. | |
2817 | @end deffn | |
5982a8e0 KR |
2818 | |
2819 | ||
2820 | @c Local Variables: | |
2821 | @c TeX-master: "guile.texi" | |
2822 | @c End: |