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