diff options
author | Andy Wingo <wingo@pobox.com> | 2016-05-14 23:27:38 +0200 |
---|---|---|
committer | Andy Wingo <wingo@pobox.com> | 2016-05-14 23:27:38 +0200 |
commit | 556ac9777b06c0d53713752b1b3ccd6480baf118 (patch) | |
tree | c8877d84cbc3d9a1faf0a1c5a0320e425a46cc86 /doc/ref/api-io.texi | |
parent | a9d0fe9ea136563aaac3423faffe8041f0db68fe (diff) | |
download | guile-556ac9777b06c0d53713752b1b3ccd6480baf118.tar.gz |
Document scm_c_make_port and friends
* doc/ref/api-io.texi (I/O Extensions): Document scm_c_make_port and
friends, and document "mode bits".
Diffstat (limited to 'doc/ref/api-io.texi')
-rw-r--r-- | doc/ref/api-io.texi | 22 |
1 files changed, 21 insertions, 1 deletions
diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi index 8c91bae7f..23d3b50cd 100644 --- a/doc/ref/api-io.texi +++ b/doc/ref/api-io.texi @@ -2242,7 +2242,9 @@ only you control. Get a stream from a port using the @code{SCM_STREAM} macro. Note that your port methods are only ever called with ports of your type. -A port type is created by calling @code{scm_make_port_type}. +A port type is created by calling @code{scm_make_port_type}. Once you +have your port type, you can create ports with @code{scm_c_make_port}, +or @code{scm_c_make_port_with_encoding}. @deftypefun scm_t_port_type* scm_make_port_type (char *name, size_t (*read) (SCM port, SCM dst, size_t start, size_t count), size_t (*write) (SCM port, SCM src, size_t start, size_t count)) Define a new port type. The @var{name}, @var{read} and @var{write} @@ -2251,6 +2253,24 @@ below. The other fields are initialized with default values and can be changed later. @end deftypefun +@deftypefun SCM scm_c_make_port_with_encoding (scm_t_port_type *type, unsigned long mode_bits, SCM encoding, SCM conversion_strategy, scm_t_bits stream) +@deftypefunx SCM scm_c_make_port (scm_t_port_type *type, unsigned long mode_bits, scm_t_bits stream) +Make a port with the given @var{type}. The @var{stream} indicates the +private data associated with the port, which your port implementation +may later retrieve with @code{SCM_STREAM}. The mode bits should include +one or more of the flags @code{SCM_RDNG} or @code{SCM_WRTNG}, indicating +that the port is an input and/or an output port, respectively. The mode +bits may also include @code{SCM_BUF0} or @code{SCM_BUFLINE}, indicating +that the port should be unbuffered or line-buffered, respectively. The +default is that the port will be block-buffered. @xref{Buffering}. + +As you would imagine, @var{encoding} and @var{conversion_strategy} +specify the port's initial textual encoding and conversion strategy. +Both are symbols. @code{scm_c_make_port} is the same as +@code{scm_c_make_port_with_encoding}, except it uses the default port +encoding and conversion strategy. +@end deftypefun + The port type has a number of associate procedures and properties which collectively implement the port's behavior. Creating a new port type mostly involves writing these procedures. |