(guile.info.gz) C Port Interface

Info Catalog

(guile.info.gz) I/O Extensions

(guile.info.gz) Port Implementation

 
 27.10.1 C Port Interface
 ------------------------
 
 This section describes how to use Scheme ports from C.
 
 27.10.1.1 Port basics
 .....................
 
 There are two main data structures.  A port type object (ptob) is of
 type `scm_ptob_descriptor'.  A port instance is of type `scm_port'.
 Given an `SCM' variable which points to a port, the corresponding C
 port object can be obtained using the `SCM_PTAB_ENTRY' macro.  The ptob
 can be obtained by using `SCM_PTOBNUM' to give an index into the
 `scm_ptobs' global array.
 
 27.10.1.2 Port buffers
 ......................
 
 An input port always has a read buffer and an output port always has a
 write buffer.  However the size of these buffers is not guaranteed to be
 more than one byte (e.g., the `shortbuf' field in `scm_port' which is
 used when no other buffer is allocated).  The way in which the buffers
 are allocated depends on the implementation of the ptob.  For example
 in the case of an fport, buffers may be allocated with malloc when the
 port is created, but in the case of an strport the underlying string is
 used as the buffer.
 
 27.10.1.3 The `rw_random' flag
 ..............................
 
 Special treatment is required for ports which can be seeked at random.
 Before various operations, such as seeking the port or changing from
 input to output on a bidirectional port or vice versa, the port
 implementation must be given a chance to update its state.  The write
 buffer is updated by calling the `flush' ptob procedure and the input
 buffer is updated by calling the `end_input' ptob procedure.  In the
 case of an fport, `flush' causes buffered output to be written to the
 file descriptor, while `end_input' causes the descriptor position to be
 adjusted to account for buffered input which was never read.
 
    The special treatment must be performed if the `rw_random' flag in
 the port is non-zero.
 
 27.10.1.4 The `rw_active' variable
 ..................................
 
 The `rw_active' variable in the port is only used if `rw_random' is
 set.  It's defined as an enum with the following values:
 
 `SCM_PORT_READ'
      the read buffer may have unread data.
 
 `SCM_PORT_WRITE'
      the write buffer may have unwritten data.
 
 `SCM_PORT_NEITHER'
      neither the write nor the read buffer has data.
 
 27.10.1.5 Reading from a port.
 ..............................
 
 To read from a port, it's possible to either call existing libguile
 procedures such as `scm_getc' and `scm_read_line' or to read data from
 the read buffer directly.  Reading from the buffer involves the
 following steps:
 
   1. Flush output on the port, if `rw_active' is `SCM_PORT_WRITE'.
 
   2. Fill the read buffer, if it's empty, using `scm_fill_input'.
 
   3. Read the data from the buffer and update the read position in the
      buffer.  Steps 2) and 3) may be repeated as many times as required.
 
   4. Set rw_active to `SCM_PORT_READ' if `rw_random' is set.
 
   5. update the port's line and column counts.
 
 27.10.1.6 Writing to a port.
 ............................
 
 To write data to a port, calling `scm_lfwrite' should be sufficient for
 most purposes.  This takes care of the following steps:
 
   1. End input on the port, if `rw_active' is `SCM_PORT_READ'.
 
   2. Pass the data to the ptob implementation using the `write' ptob
      procedure.  The advantage of using the ptob `write' instead of
      manipulating the write buffer directly is that it allows the data
      to be written in one operation even if the port is using the
      single-byte `shortbuf'.
 
   3. Set `rw_active' to `SCM_PORT_WRITE' if `rw_random' is set.
 

Info Catalog

(guile.info.gz) I/O Extensions

(guile.info.gz) Port Implementation