![]() |
![]() |
![]() |
![]() |
<GIOChannel>
A data structure representing an IO Channel. The fields should be considered private and should only be accessed with the following functions.
(define-values () (iochannel:close self))
Close an IO channel. Any pending data to be written will be
flushed, ignoring errors. The channel will not be freed until the
last reference is dropped using g_io_channel_unref()
.
(define-values (%return) (iochannel:get-buffer-condition self))
This function returns a GIOCondition depending on whether there
is data to be read/space to write data in the internal buffers in
the GIOChannel. Only the flags G_IO_IN
and G_IO_OUT
may be set.
(define-values (%return) (iochannel:get-buffered? self))
Returns whether channel
is buffered.
(define-values (%return) (iochannel:get-close-on-unref? self))
Returns whether the file/socket/whatever associated with channel
will be closed when channel
receives its final unref and is
destroyed. The default value of this is TRUE
for channels created
by g_io_channel_new_file (), and FALSE
for all other channels.
(define-values (%return) (iochannel:get-encoding self))
Gets the encoding for the input/output of the channel.
The internal encoding is always UTF-8. The encoding NULL
makes the channel safe for binary data.
(define-values (%return) (iochannel:get-flags self))
Gets the current flags for a GIOChannel, including read-only
flags such as G_IO_FLAG_IS_READABLE
.
The values of the flags G_IO_FLAG_IS_READABLE
and G_IO_FLAG_IS_WRITABLE
are cached for internal use by the channel when it is created.
If they should change at some later point (e.g. partial shutdown
of a socket with the UNIX shutdown()
function), the user
should immediately call g_io_channel_get_flags()
to update
the internal values of these flags.
(define-values (%return) (iochannel:get-line-term self length))
This returns the string that GIOChannel uses to determine
where in the file a line break occurs. A value of NULL
indicates autodetection.
(define-values () (iochannel:init self))
Initializes a GIOChannel struct.
This is called by each of the above functions when creating a GIOChannel, and so is not often needed by the application programmer (unless you are creating a new type of GIOChannel).
(define-values (%return) (iochannel:read self buf count bytes-read))
Reads data from a GIOChannel.
(define-values (%return buf bytes-read) (iochannel:read-chars! self buf))
Replacement for g_io_channel_read()
with the new API.
channel |
a GIOChannel Passed as |
buf |
a buffer to read data into Passed as |
count |
the size of the buffer. Note that the buffer may not be completely filled even if there is data in the buffer if the remaining data is not a complete character. Inferred from |
bytes_read |
The number of bytes read. This may be
zero even on success if count < 6 and the channel's encoding
is non- Passed as |
(define-values (%return str-return length terminator-pos) (iochannel:read-line self))
Reads a line, including the terminating character(s),
from a GIOChannel into a newly-allocated string.
str_return
will contain allocated memory if the return
is G_IO_STATUS_NORMAL
.
channel |
a GIOChannel Passed as |
str_return |
The line read from the GIOChannel, including the
line terminator. This data should be freed with Passed as |
length |
location to store length of the read data, or Passed as |
terminator_pos |
location to store position of line terminator, or Passed as |
(define-values (%return) (iochannel:read-line-string self buffer terminator-pos))
Reads a line from a GIOChannel, using a GString as a buffer.
(define-values (%return str-return length) (iochannel:read-to-end self))
Reads all the remaining data from the file.
channel |
a GIOChannel Passed as |
str_return |
Location to
store a pointer to a string holding the remaining data in the
GIOChannel. This data should be freed with Passed as |
length |
location to store length of the data Inferred from |
(define-values (%return thechar) (iochannel:read-unichar self))
Reads a Unicode character from channel
.
This function cannot be called on a channel with NULL
encoding.
(define-values (%return) (iochannel:seek self offset type))
Sets the current position in the GIOChannel, similar to the standard
library function fseek()
.
channel |
a GIOChannel Passed as |
offset |
an offset, in bytes, which is added to the position specified
by Passed as |
type |
the position in the file, which can be Passed as |
(define-values (%return) (iochannel:seek-position self offset type))
Replacement for g_io_channel_seek()
with the new API.
channel |
a GIOChannel Passed as |
offset |
The offset in bytes from the position specified by Passed as |
type |
a GSeekType. The type Passed as |
(define-values () (iochannel:set-buffered self buffered))
The buffering state can only be set if the channel's encoding
is NULL
. For any other encoding, the channel must be buffered.
A buffered channel can only be set unbuffered if the channel's
internal buffers have been flushed. Newly created channels or
channels which have returned G_IO_STATUS_EOF
not require such a flush. For write-only channels, a call to
g_io_channel_flush () is sufficient. For all other channels,
the buffers may be flushed by a call to g_io_channel_seek_position ().
This includes the possibility of seeking with seek type G_SEEK_CUR
and an offset of zero. Note that this means that socket-based
channels cannot be set unbuffered once they have had data
read from them.
On unbuffered channels, it is safe to mix read and write calls from the new and old APIs, if this is necessary for maintaining old code.
The default state of the channel is buffered.
(define-values () (iochannel:set-close-on-unref self do-close))
Whether to close the channel on the final unref of the GIOChannel
data structure. The default value of this is TRUE
for channels
created by g_io_channel_new_file (), and FALSE
for all other channels.
Setting this flag to TRUE
for a channel you have already closed
can cause problems when the final reference to the GIOChannel is dropped.
(define-values (%return) (iochannel:set-encoding self encoding))
Sets the encoding for the input/output of the channel. The internal encoding is always UTF-8. The default encoding for the external file is UTF-8.
The encoding NULL
is safe to use with binary data.
The encoding can only be set if one of the following conditions is true:
- The channel was just created, and has not been written to or read from yet.
- The channel is write-only.
- The channel is a file, and the file pointer was just repositioned
by a call to g_io_channel_seek_position()
. (This flushes all the
internal buffers.)
- The current encoding is NULL
or UTF-8.
- One of the (new API) read functions has just returned G_IO_STATUS_EOF
(or, in the case of g_io_channel_read_to_end()
, G_IO_STATUS_NORMAL
).
- One of the functions g_io_channel_read_chars()
or
g_io_channel_read_unichar()
has returned G_IO_STATUS_AGAIN
or
G_IO_STATUS_ERROR
. This may be useful in the case of
G_CONVERT_ERROR_ILLEGAL_SEQUENCE
.
Returning one of these statuses from g_io_channel_read_line()
,
g_io_channel_read_line_string()
, or g_io_channel_read_to_end()
does not guarantee that the encoding can be changed.
Channels which do not meet one of the above conditions cannot call
g_io_channel_seek_position()
with an offset of G_SEEK_CUR
, and, if
they are "seekable", cannot call g_io_channel_write_chars()
after
calling one of the API "read" functions.
(define-values (%return) (iochannel:set-flags self flags))
Sets the (writeable) flags in channel
to (flags
& G_IO_FLAG_SET_MASK
).
(define-values () (iochannel:set-line-term self line-term length))
This sets the string that GIOChannel uses to determine where in the file a line break occurs.
channel |
a GIOChannel Passed as |
line_term |
The line termination string. Use Passed as |
length |
The length of the termination string. If -1 is passed, the string is assumed to be nul-terminated. This option allows termination strings with embedded nuls. Passed as |
(define-values (%return) (iochannel:shutdown self flush))
Close an IO channel. Any pending data to be written will be
flushed if flush
is TRUE
. The channel will not be freed until the
last reference is dropped using g_io_channel_unref()
.
(define-values (%return) (iochannel:unix-get-fd self))
Returns the file descriptor of the GIOChannel.
On Windows this function returns the file descriptor or socket of the GIOChannel.
(define-values (%return) (iochannel:write self buf count bytes-written))
Writes data to a GIOChannel.
(define-values (%return bytes-written) (iochannel:write-chars self buf count))
Replacement for g_io_channel_write()
with the new API.
On seekable channels with encodings other than NULL
or UTF-8, generic
mixing of reading and writing is not allowed. A call to g_io_channel_write_chars ()
may only be made on a channel from which data has been read in the
cases described in the documentation for g_io_channel_set_encoding ().
channel |
a GIOChannel Passed as |
buf |
a buffer to write data from Passed as |
count |
the size of the buffer. If -1, the buffer is taken to be a nul-terminated string. Passed as |
bytes_written |
The number of bytes written. This can be nonzero
even if the return value is not Passed as |
(define-values (%return) (iochannel:write-unichar self thechar))
Writes a Unicode character to channel
.
This function cannot be called on a channel with NULL
encoding.