GNU Info
(guile.info)Ports and File Descriptors
Ports and File Descriptors ========================== Conventions generally follow those of scsh, Note: The Scheme shell (scsh). File ports are implemented using low-level operating system I/O facilities, with optional buffering to improve efficiency Note: File Ports Note that some procedures (e.g., `recv!') will accept ports as arguments, but will actually operate directly on the file descriptor underlying the port. Any port buffering is ignored, including the buffer which implements `peek-char' and `unread-char'. The `force-output' and `drain-input' procedures can be used to clear the buffers. Each open file port has an associated operating system file descriptor. File descriptors are generally not useful in Scheme programs; however they may be needed when interfacing with foreign code and the Unix environment. A file descriptor can be extracted from a port and a new port can be created from a file descriptor. However a file descriptor is just an integer and the garbage collector doesn't recognise it as a reference to the port. If all other references to the port were dropped, then it's likely that the garbage collector would free the port, with the side-effect of closing the file descriptor prematurely. To assist the programmer in avoiding this problem, each port has an associated "revealed count" which can be used to keep track of how many times the underlying file descriptor has been stored in other places. If a port's revealed count is greater than zero, the file descriptor will not be closed when the port is gabage collected. A programmer can therefore ensure that the revealed count will be greater than zero if the file descriptor is needed elsewhere. For the simple case where a file descriptor is "imported" once to become a port, it does not matter if the file descriptor is closed when the port is garbage collected. There is no need to maintain a revealed count. Likewise when "exporting" a file descriptor to the external environment, setting the revealed count is not required provided the port is kept open (i.e., is pointed to by a live Scheme binding) while the file descriptor is in use. To correspond with traditional Unix behaviour, the three file descriptors (0, 1 and 2) are automatically imported when a program starts up and assigned to the initial values of the current input, output and error ports. The revealed count for each is initially set to one, so that dropping references to one of these ports will not result in its garbage collection: it could be retrieved with fdopen or fdes->ports. - primitive: port-revealed port Returns the revealed count for PORT. - primitive: set-port-revealed! port rcount Sets the revealed count for a port to a given value. The return value is unspecified. - primitive: fileno port Returns the integer file descriptor underlying PORT. Does not change its revealed count. - procedure: port->fdes port Returns the integer file descriptor underlying PORT. As a side effect the revealed count of PORT is incremented. - primitive: fdopen fdes modes Returns a new port based on the file descriptor FDES. Modes are given by the string MODES. The revealed count of the port is initialized to zero. The modes string is the same as that accepted by Note: open-file. - primitive: fdes->ports fd Returns a list of existing ports which have FDES as an underlying file descriptor, without changing their revealed counts. - procedure: fdes->inport fdes Returns an existing input port which has FDES as its underlying file descriptor, if one exists, and increments its revealed count. Otherwise, returns a new input port with a revealed count of 1. - procedure: fdes->outport fdes Returns an existing output port which has FDES as its underlying file descriptor, if one exists, and increments its revealed count. Otherwise, returns a new output port with a revealed count of 1. - primitive: primitive-move->fdes port fd Moves the underlying file descriptor for PORT to the integer value FDES without changing the revealed count of PORT. Any other ports already using this descriptor will be automatically shifted to new descriptors and their revealed counts reset to zero. The return value is `#f' if the file descriptor already had the required value or `#t' if it was moved. - procedure: move->fdes port fdes Moves the underlying file descriptor for PORT to the integer value FDES and sets its revealed count to one. Any other ports already using this descriptor will be automatically shifted to new descriptors and their revealed counts reset to zero. The return value is unspecified. - procedure: release-port-handle port Decrements the revealed count for a port. - primitive: fsync object Copies any unwritten data for the specified output file descriptor to disk. If PORT/FD is a port, its buffer is flushed before the underlying file descriptor is fsync'd. The return value is unspecified. - primitive: open path flags [mode] Open the file named by PATH for reading and/or writing. FLAGS is an integer specifying how the file should be opened. MODE is an integer specifying the permission bits of the file, if it needs to be created, before the umask is applied. The default is 666 (Unix itself has no default). FLAGS can be constructed by combining variables using `logior'. Basic flags are: - Variable: O_RDONLY Open the file read-only. - Variable: O_WRONLY Open the file write-only. - Variable: O_RDWR Open the file read/write. - Variable: O_APPEND Append to the file instead of truncating. - Variable: O_CREAT Create the file if it does not already exist. See the Unix documentation of the `open' system call for additional flags. - primitive: open-fdes path flags [mode] Similar to `open' but returns a file descriptor instead of a port. - primitive: close fd_or_port Similar to close-port (Note: close-port.), but also works on file descriptors. A side effect of closing a file descriptor is that any ports using that file descriptor are moved to a different file descriptor and have their revealed counts set to zero. - primitive: close-fdes fd A simple wrapper for the `close' system call. Close file descriptor FD, which must be an integer. Unlike close (Note: close.), the file descriptor will be closed even if a port is using it. The return value is unspecified. - primitive: unread-char char [port] Place CHAR in PORT so that it will be read by the next read operation. If called multiple times, the unread characters will be read again in last-in first-out order. If PORT is not supplied, the current input port is used. - primitive: unread-string str port Place the string STR in PORT so that its characters will be read in subsequent read operations. If called multiple times, the unread characters will be read again in last-in first-out order. If PORT is not supplied, the current-input-port is used. - primitive: pipe Returns a newly created pipe: a pair of ports which are linked together on the local machine. The CAR is the input port and the CDR is the output port. Data written (and flushed) to the output port can be read from the input port. Pipes are commonly used for communication with a newly forked child process. The need to flush the output port can be avoided by making it unbuffered using `setvbuf'. Writes occur atomically provided the size of the data in bytes is not greater than the value of `PIPE_BUF' Note that the output port is likely to block if too much data (typically equal to `PIPE_BUF') has been written but not yet read from the input port. The next group of procedures perform a `dup2' system call, if NEWFD (an integer) is supplied, otherwise a `dup'. The file descriptor to be duplicated can be supplied as an integer or contained in a port. The type of value returned varies depending on which procedure is used. All procedures also have the side effect when performing `dup2' that any ports using NEWFD are moved to a different file descriptor and have their revealed counts set to zero. - primitive: dup->fdes fd_or_port [fd] Returns an integer file descriptor. - procedure: dup->inport port/fd [newfd] Returns a new input port using the new file descriptor. - procedure: dup->outport port/fd [newfd] Returns a new output port using the new file descriptor. - procedure: dup port/fd [newfd] Returns a new port if PORT/FD is a port, with the same mode as the supplied port, otherwise returns an integer file descriptor. - procedure: dup->port port/fd mode [newfd] Returns a new port using the new file descriptor. MODE supplies a mode string for the port (Note: open-file.). - procedure: duplicate-port port modes Returns a new port which is opened on a duplicate of the file descriptor underlying PORT, with mode string MODES as for Note: open-file. The two ports will share a file position and file status flags. Unexpected behaviour can result if both ports are subsequently used and the original and/or duplicate ports are buffered. The mode string can include `0' to obtain an unbuffered duplicate port. This procedure is equivalent to `(dup->port PORT MODES)'. - primitive: redirect-port old new This procedure takes two ports and duplicates the underlying file descriptor from OLD-PORT into NEW-PORT. The current file descriptor in NEW-PORT will be closed. After the redirection the two ports will share a file position and file status flags. The return value is unspecified. Unexpected behaviour can result if both ports are subsequently used and the original and/or duplicate ports are buffered. This procedure does not have any side effects on other ports or revealed counts. - primitive: dup2 oldfd newfd A simple wrapper for the `dup2' system call. Copies the file descriptor OLDFD to descriptor number NEWFD, replacing the previous meaning of NEWFD. Both OLDFD and NEWFD must be integers. Unlike for dup->fdes or primitive-move->fdes, no attempt is made to move away ports which are using NEWFD. The return value is unspecified. - primitive: port-mode port Returns the port modes associated with the open port PORT. These will not necessarily be identical to the modes used when the port was opened, since modes such as "append" which are used only during port creation are not retained. - primitive: close-all-ports-except . ports [DEPRECATED] Close all open file ports used by the interpreter except for those supplied as arguments. This procedure was intended to be used before an exec call to close file descriptors which are not needed in the new process. However it has the undesirable side-effect of flushing buffes, so it's deprecated. Use port-for-each instead. - primitive: port-for-each proc Apply PROC to each port in the Guile port table in turn. The return value is unspecified. - primitive: setvbuf port mode [size] Set the buffering mode for PORT. MODE can be: `_IONBF' non-buffered `_IOLBF' line buffered `_IOFBF' block buffered, using a newly allocated buffer of SIZE bytes. If SIZE is omitted, a default size will be used. - primitive: fcntl object cmd [value] Apply COMMAND to the specified file descriptor or the underlying file descriptor of the specified port. VALUE is an optional integer argument. Values for COMMAND are: `F_DUPFD' Duplicate a file descriptor `F_GETFD' Get flags associated with the file descriptor. `F_SETFD' Set flags associated with the file descriptor to VALUE. `F_GETFL' Get flags associated with the open file. `F_SETFL' Set flags associated with the open file to VALUE `F_GETOWN' Get the process ID of a socket's owner, for `SIGIO' signals. `F_SETOWN' Set the process that owns a socket to VALUE, for `SIGIO' signals. `FD_CLOEXEC' The value used to indicate the "close on exec" flag with `F_GETFL' or `F_SETFL'. - primitive: select reads writes excepts [secs [usecs]] This procedure has a variety of uses: waiting for the ability to provide input, accept output, or the existance of exceptional conditions on a collection of ports or file descriptors, or waiting for a timeout to occur. It also returns if interrupted by a signal. READS, WRITES and EXCEPTS can be lists or vectors, with each member a port or a file descriptor. The value returned is a list of three corresponding lists or vectors containing only the members which meet the specified requirement. The ability of port buffers to provide input or accept output is taken into account. Ordering of the input lists or vectors is not preserved. The optional arguments SECS and USECS specify the timeout. Either SECS can be specified alone, as either an integer or a real number, or both SECS and USECS can be specified as integers, in which case USECS is an additional timeout expressed in microseconds. If SECS is omitted or is `#f' then select will wait for as long as it takes for one of the other conditions to be satisfied. The scsh version of `select' differs as follows: Only vectors are accepted for the first three arguments. The USECS argument is not supported. Multiple values are returned instead of a list. Duplicates in the input vectors appear only once in output. An additional `select!' interface is provided.
automatically generated by info2www version 1.2.2.9