DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH
 

(guile.info.gz) Ports and File Descriptors

Info Catalog (guile.info.gz) Conventions (guile.info.gz) POSIX (guile.info.gz) File System
 
 38.2 Ports and File Descriptors
 ===============================
 
 Conventions generally follow those of scsh,  The Scheme shell
 (scsh).
 
    File ports are implemented using low-level operating system I/O
 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 recognize 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 garbage 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.
 
  -- Scheme Procedure: port-revealed port
  -- C Function: scm_port_revealed (port)
      Return the revealed count for PORT.
 
  -- Scheme Procedure: set-port-revealed! port rcount
  -- C Function: scm_set_port_revealed_x (port, rcount)
      Sets the revealed count for a port to a given value.  The return
      value is unspecified.
 
  -- Scheme Procedure: fileno port
  -- C Function: scm_fileno (port)
      Return the integer file descriptor underlying PORT.  Does not
      change its revealed count.
 
  -- Scheme Procedure: port->fdes port
      Returns the integer file descriptor underlying PORT.  As a side
      effect the revealed count of PORT is incremented.
 
  -- Scheme Procedure: fdopen fdes modes
  -- C Function: scm_fdopen (fdes, modes)
      Return 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  open-file File Ports.
 
  -- Scheme Procedure: fdes->ports fd
  -- C Function: scm_fdes_to_ports (fd)
      Return a list of existing ports which have FDES as an underlying
      file descriptor, without changing their revealed counts.
 
  -- Scheme 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.
 
  -- Scheme 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.
 
  -- Scheme Procedure: primitive-move->fdes port fd
  -- C Function: scm_primitive_move_to_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.
 
  -- Scheme 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.
 
  -- Scheme Procedure: release-port-handle port
      Decrements the revealed count for a port.
 
  -- Scheme Procedure: fsync object
  -- C Function: scm_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.
 
  -- Scheme Procedure: open path flags [mode]
  -- C Function: scm_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.
 
  -- Scheme Procedure: open-fdes path flags [mode]
  -- C Function: scm_open_fdes (path, flags, mode)
      Similar to `open' but return a file descriptor instead of a port.
 
  -- Scheme Procedure: close fd_or_port
  -- C Function: scm_close (fd_or_port)
      Similar to close-port ( close-port Closing.), 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.
 
  -- Scheme Procedure: close-fdes fd
  -- C Function: scm_close_fdes (fd)
      A simple wrapper for the `close' system call.  Close file
      descriptor FD, which must be an integer.  Unlike close (
      close Ports and File Descriptors.), the file descriptor will be
      closed even if a port is using it.  The return value is
      unspecified.
 
  -- Scheme Procedure: unread-char char [port]
  -- C Function: scm_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.
 
  -- Scheme Procedure: 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.
 
  -- Scheme Procedure: pipe
  -- C Function: scm_pipe ()
      Return 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.
 
  -- Scheme Procedure: dup->fdes fd_or_port [fd]
  -- C Function: scm_dup_to_fdes (fd_or_port, fd)
      Return a new integer file descriptor referring to the open file
      designated by FD_OR_PORT, which must be either an open file port
      or a file descriptor.
 
  -- Scheme Procedure: dup->inport port/fd [newfd]
      Returns a new input port using the new file descriptor.
 
  -- Scheme Procedure: dup->outport port/fd [newfd]
      Returns a new output port using the new file descriptor.
 
  -- Scheme 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.
 
  -- Scheme Procedure: dup->port port/fd mode [newfd]
      Returns a new port using the new file descriptor.  MODE supplies a
      mode string for the port ( open-file File Ports.).