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 |
|
|
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 |
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. |
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: |