/[guile]/guile/guile-core/doc/ref/scheme-io.texi
ViewVC logotype

Diff of /guile/guile-core/doc/ref/scheme-io.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.1.2.6 by ossau, Fri Mar 15 14:12:58 2002 UTC revision 1.1.2.7 by ossau, Sat Mar 16 13:35:23 2002 UTC
# Line 12  Line 12 
12  * Block Reading and Writing::   Reading and writing blocks of text.  * Block Reading and Writing::   Reading and writing blocks of text.
13  * Default Ports::               Defaults for input, output and errors.  * Default Ports::               Defaults for input, output and errors.
14  * Port Types::                  Types of port and how to make them.  * Port Types::                  Types of port and how to make them.
15    * I/O Extensions::              Using and extending ports in C.
16  @end menu  @end menu
17    
18    
# Line 111  an interactive port will hang waiting fo Line 112  an interactive port will hang waiting fo
112  to @code{read-char} would have hung.}  to @code{read-char} would have hung.}
113  @end deffn  @end deffn
114    
115  @deffn {Scheme Procedure} unread-char cobj port  @deffn {Scheme Procedure} unread-char cobj [port]
116    @deffnx {C Function} scm_unread_char (cobj, port)
117  Place @var{char} in @var{port} so that it will be read by the  Place @var{char} in @var{port} so that it will be read by the
118  next read operation.  If called multiple times, the unread characters  next read operation.  If called multiple times, the unread characters
119  will be read again in last-in first-out order.  If @var{port} is  will be read again in last-in first-out order.  If @var{port} is
# Line 579  Return the port to which errors and warn Line 581  Return the port to which errors and warn
581  @deffnx {Scheme Procedure} set-current-output-port port  @deffnx {Scheme Procedure} set-current-output-port port
582  @deffnx {Scheme Procedure} set-current-error-port port  @deffnx {Scheme Procedure} set-current-error-port port
583  @deffnx {C Function} scm_set_current_input_port (port)  @deffnx {C Function} scm_set_current_input_port (port)
584    @deffnx {C Function} scm_set_current_output_port (port)
585    @deffnx {C Function} scm_set_current_error_port (port)
586  Change the ports returned by @code{current-input-port},  Change the ports returned by @code{current-input-port},
587  @code{current-output-port} and @code{current-error-port}, respectively,  @code{current-output-port} and @code{current-error-port}, respectively,
588  so that they use the supplied @var{port} for input or output.  so that they use the supplied @var{port} for input or output.
# Line 892  documentation for @code{open-file} in @r Line 896  documentation for @code{open-file} in @r
896  @end deffn  @end deffn
897    
898    
899    @node I/O Extensions
900    @section Using and Extending Ports in C
901    
902    @menu
903    * C Port Interface:: Using ports from C.
904    * Port Implementation:: How to implement a new port type in C.
905    @end menu
906    
907    
908    @node C Port Interface
909    @subsection C Port Interface
910    
911    This section describes how to use Scheme ports from C.
912    
913    @subsubsection Port basics
914    
915    There are two main data structures.  A port type object (ptob) is of
916    type @code{scm_ptob_descriptor}.  A port instance is of type
917    @code{scm_port}.  Given an @code{SCM} variable which points to a port,
918    the corresponding C port object can be obtained using the
919    @code{SCM_PTAB_ENTRY} macro.  The ptob can be obtained by using
920    @code{SCM_PTOBNUM} to give an index into the @code{scm_ptobs}
921    global array.
922    
923    @subsubsection Port buffers
924    
925    An input port always has a read buffer and an output port always has a
926    write buffer.  However the size of these buffers is not guaranteed to be
927    more than one byte (e.g., the @code{shortbuf} field in @code{scm_port}
928    which is used when no other buffer is allocated).  The way in which the
929    buffers are allocated depends on the implementation of the ptob.  For
930    example in the case of an fport, buffers may be allocated with malloc
931    when the port is created, but in the case of an strport the underlying
932    string is used as the buffer.
933    
934    @subsubsection The @code{rw_random} flag
935    
936    Special treatment is required for ports which can be seeked at random.
937    Before various operations, such as seeking the port or changing from
938    input to output on a bidirectional port or vice versa, the port
939    implementation must be given a chance to update its state.  The write
940    buffer is updated by calling the @code{flush} ptob procedure and the
941    input buffer is updated by calling the @code{end_input} ptob procedure.
942    In the case of an fport, @code{flush} causes buffered output to be
943    written to the file descriptor, while @code{end_input} causes the
944    descriptor position to be adjusted to account for buffered input which
945    was never read.
946    
947    The special treatment must be performed if the @code{rw_random} flag in
948    the port is non-zero.
949    
950    @subsubsection The @code{rw_active} variable
951    
952    The @code{rw_active} variable in the port is only used if
953    @code{rw_random} is set.  It's defined as an enum with the following
954    values:
955    
956    @table @code
957    @item SCM_PORT_READ
958    the read buffer may have unread data.
959    
960    @item SCM_PORT_WRITE
961    the write buffer may have unwritten data.
962    
963    @item SCM_PORT_NEITHER
964    neither the write nor the read buffer has data.
965    @end table
966    
967    @subsubsection Reading from a port.
968    
969    To read from a port, it's possible to either call existing libguile
970    procedures such as @code{scm_getc} and @code{scm_read_line} or to read
971    data from the read buffer directly.  Reading from the buffer involves
972    the following steps:
973    
974    @enumerate
975    @item
976    Flush output on the port, if @code{rw_active} is @code{SCM_PORT_WRITE}.
977    
978    @item
979    Fill the read buffer, if it's empty, using @code{scm_fill_input}.
980    
981    @item Read the data from the buffer and update the read position in
982    the buffer.  Steps 2) and 3) may be repeated as many times as required.
983    
984    @item Set rw_active to @code{SCM_PORT_READ} if @code{rw_random} is set.
985    
986    @item update the port's line and column counts.
987    @end enumerate
988    
989    @subsubsection Writing to a port.
990    
991    To write data to a port, calling @code{scm_lfwrite} should be sufficient for
992    most purposes.  This takes care of the following steps:
993    
994    @enumerate
995    @item
996    End input on the port, if @code{rw_active} is @code{SCM_PORT_READ}.
997    
998    @item
999    Pass the data to the ptob implementation using the @code{write} ptob
1000    procedure.  The advantage of using the ptob @code{write} instead of
1001    manipulating the write buffer directly is that it allows the data to be
1002    written in one operation even if the port is using the single-byte
1003    @code{shortbuf}.
1004    
1005    @item
1006    Set @code{rw_active} to @code{SCM_PORT_WRITE} if @code{rw_random}
1007    is set.
1008    @end enumerate
1009    
1010    
1011    @node Port Implementation
1012    @subsection Port Implementation
1013    
1014    This section describes how to implement a new port type in C.
1015    
1016    As described in the previous section, a port type object (ptob) is
1017    a structure of type @code{scm_ptob_descriptor}.  A ptob is created by
1018    calling @code{scm_make_port_type}.
1019    
1020    All of the elements of the ptob, apart from @code{name}, are procedures
1021    which collectively implement the port behaviour.  Creating a new port
1022    type mostly involves writing these procedures.
1023    
1024    @code{scm_make_port_type} initializes three elements of the structure
1025    (@code{name}, @code{fill_input} and @code{write}) from its arguments.
1026    The remaining elements are initialized with default values and can be
1027    set later if required.
1028    
1029    @table @code
1030    @item name
1031    A pointer to a NUL terminated string: the name of the port type.  This
1032    is the only element of @code{scm_ptob_descriptor} which is not
1033    a procedure.  Set via the first argument to @code{scm_make_port_type}.
1034    
1035    @item mark
1036    Called during garbage collection to mark any SCM objects that a port
1037    object may contain.  It doesn't need to be set unless the port has
1038    @code{SCM} components.  Set using @code{scm_set_port_mark}.
1039    
1040    @item free
1041    Called when the port is collected during gc.  It
1042    should free any resources used by the port.
1043    Set using @code{scm_set_port_free}.
1044    
1045    @item print
1046    Called when @code{write} is called on the port object, to print a
1047    port description.  e.g., for an fport it may produce something like:
1048    @code{#<input: /etc/passwd 3>}.   Set using @code{scm_set_port_print}.
1049    
1050    @item equalp
1051    Not used at present.  Set using @code{scm_set_port_equalp}.
1052    
1053    @item close
1054    Called when the port is closed, unless it was collected during gc.  It
1055    should free any resources used by the port.
1056    Set using @code{scm_set_port_close}.
1057    
1058    @item write
1059    Accept data which is to be written using the port.  The port implementation
1060    may choose to buffer the data instead of processing it directly.
1061    Set via the third argument to @code{scm_make_port_type}.
1062    
1063    @item flush
1064    Complete the processing of buffered output data.  Reset the value of
1065    @code{rw_active} to @code{SCM_PORT_NEITHER}.
1066    Set using @code{scm_set_port_flush}.
1067    
1068    @item end_input
1069    Perform any synchronization required when switching from input to output
1070    on the port.  Reset the value of @code{rw_active} to @code{SCM_PORT_NEITHER}.
1071    Set using @code{scm_set_port_end_input}.
1072    
1073    @item fill_input
1074    Read new data into the read buffer and return the first character.  It
1075    can be assumed that the read buffer is empty when this procedure is called.
1076    Set via the second argument to @code{scm_make_port_type}.
1077    
1078    @item input_waiting
1079    Return a lower bound on the number of bytes that could be read from the
1080    port without blocking.  It can be assumed that the current state of
1081    @code{rw_active} is @code{SCM_PORT_NEITHER}.
1082    Set using @code{scm_set_port_input_waiting}.
1083    
1084    @item seek
1085    Set the current position of the port.  The procedure can not make
1086    any assumptions about the value of @code{rw_active} when it's
1087    called.  It can reset the buffers first if desired by using something
1088    like:
1089    
1090    @example
1091          if (pt->rw_active == SCM_PORT_READ)
1092            scm_end_input (object);
1093          else if (pt->rw_active == SCM_PORT_WRITE)
1094            ptob->flush (object);
1095    @end example
1096    
1097    However note that this will have the side effect of discarding any data
1098    in the unread-char buffer, in addition to any side effects from the
1099    @code{end_input} and @code{flush} ptob procedures.  This is undesirable
1100    when seek is called to measure the current position of the port, i.e.,
1101    @code{(seek p 0 SEEK_CUR)}.  The libguile fport and string port
1102    implementations take care to avoid this problem.
1103    
1104    The procedure is set using @code{scm_set_port_seek}.
1105    
1106    @item truncate
1107    Truncate the port data to be specified length.  It can be assumed that the
1108    current state of @code{rw_active} is @code{SCM_PORT_NEITHER}.
1109    Set using @code{scm_set_port_truncate}.
1110    
1111    @end table
1112    
1113    
1114  @c Local Variables:  @c Local Variables:
1115  @c TeX-master: "guile.texi"  @c TeX-master: "guile.texi"
1116  @c End:  @c End:

Legend:
Removed from v.1.1.2.6  
changed lines
  Added in v.1.1.2.7

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26