
@c %start of fragment

@deftp Class <gio-channel>
Opaque pointer.

@end deftp

@deffn Function g-io-channel-unix-new  (fd@tie{}@code{int}) @result{}@tie{} (ret@tie{}@code{<gio-channel>})
Creates a new @code{<gio-channel>} given a file descriptor. On UNIX systems this
works for plain files, pipes, and sockets.

The returned @code{<gio-channel>} has a reference count of 1.

The default encoding for @code{<gio-channel>} is UTF-8. If your application is
reading output from a command using via pipe, you may need to set the encoding
to the encoding of the current locale (see @code{g-get-charset}) with the
@code{g-io-channel-set-encoding} function.

If you want to read raw binary data without interpretation, then call the
@code{g-io-channel-set-encoding} function with @samp{@code{#f}} for the encoding
argument.

This function is available in GLib on Windows, too, but you should avoid using
it on Windows. The domain of file descriptors and sockets overlap. There is no
way for GLib to know which one you mean in case the argument you pass to this
function happens to be both a valid file descriptor and socket. If that happens
a warning is issued, and GLib assumes that it is the file descriptor you mean.

@table @var
@item fd
a file descriptor.

@item ret
a new @code{<gio-channel>}.

@end table

@end deffn

@deffn Function g-io-channel-unix-get-fd  (channel@tie{}@code{<gio-channel>}) @result{}@tie{} (ret@tie{}@code{int})
Returns the file descriptor of the @code{<gio-channel>}.

On Windows this function returns the file descriptor or socket of the
@code{<gio-channel>}.

@table @var
@item channel
a @code{<gio-channel>}, created with @code{g-io-channel-unix-new}.

@item ret
the file descriptor of the @code{<gio-channel>}.

@end table

@end deffn

@deffn Function g-io-channel-new-file  (filename@tie{}@code{mchars}) (mode@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{<gio-channel>})
Open a file @var{filename} as a @code{<gio-channel>} using mode @var{mode}. This
channel will be closed when the last reference to it is dropped, so there is no
need to call @code{g-io-channel-close} (though doing so will not cause problems,
as long as no attempt is made to access the channel after it is closed).

@table @var
@item filename
A string containing the name of a file.

@item mode
One of "r", "w", "a", "r+", "w+", "a+". These have the same meaning as in
@code{fopen}.

@item error
A location to return an error of type @samp{G_FILE_ERROR}.

@item ret
A @code{<gio-channel>} on success, @samp{@code{#f}} on failure.

@end table

@end deffn

@deffn Function g-io-channel-flush  (channel@tie{}@code{<gio-channel>}) @result{}@tie{} (ret@tie{}@code{<gio-status>})
Flushes the write buffer for the GIOChannel.

@table @var
@item channel
a @code{<gio-channel>}

@item error
location to store an error of type @code{<gio-channel-error>}

@item ret
the status of the operation: One of @code{<g-io-channel-normal>},
@code{<g-io-channel-again>}, or @code{<g-io-channel-error>}.

@end table

@end deffn

@deffn Function g-io-channel-seek-position  (self@tie{}@code{<gio-channel>}) (offset@tie{}@code{int64}) (type@tie{}@code{<g-seek-type>}) @result{}@tie{} (ret@tie{}@code{<gio-status>})
Replacement for @code{g-io-channel-seek} with the new API.

@table @var
@item channel
a @code{<gio-channel>}

@item offset
The offset in bytes from the position specified by @var{type}

@item type
a @code{<g-seek-type>}. The type @samp{G_SEEK_CUR} is only allowed in those
cases where a call to @code{g-io-channel-set-encoding} is allowed. See the
documentation for @code{g-io-channel-set-encoding} for details.

@item error
A location to return an error of type @code{<gio-channel-error>}

@item ret
the status of the operation.

@end table

@end deffn

@deffn Function g-io-channel-shutdown  (channel@tie{}@code{<gio-channel>}) (flush@tie{}@code{bool}) @result{}@tie{} (ret@tie{}@code{<gio-status>})
Close an IO channel. Any pending data to be written will be flushed if
@var{flush} is @samp{@code{#t}}. The channel will not be freed until the last
reference is dropped using @code{g-io-channel-unref}.

@table @var
@item channel
a @code{<gio-channel>}

@item flush
if @samp{@code{#t}}, flush pending

@item err
location to store a @code{<gio-channel-error>}

@item ret
the status of the operation.

@end table

@end deffn

@deffn Function g-io-channel-error-from-errno  (en@tie{}@code{int}) @result{}@tie{} (ret@tie{}@code{<gio-channel-error>})
Converts an @samp{errno} error number to a @code{<gio-channel-error>}.

@table @var
@item en
an @samp{errno} error number, e.g. @samp{EINVAL}.

@item ret
a @code{<gio-channel-error>} error number, e.g. @samp{G_IO_CHANNEL_ERROR_INVAL}.

@end table

@end deffn

@deffn Function g-io-create-watch  (channel@tie{}@code{<gio-channel>}) (condition@tie{}@code{<gio-condition>}) @result{}@tie{} (ret@tie{}@code{<g-source>})
Creates a @code{<g-source>} that's dispatched when @var{condition} is met for
the given @var{channel}. For example, if condition is @code{<g-io-in>}, the
source will be dispatched when there's data available for reading.
@code{g-io-add-watch} is a simpler interface to this same functionality, for the
case where you want to add the source to the default main loop at the default
priority.

On Windows, polling a @code{<g-source>} created to watch a channel for a socket
puts the socket in non-blocking mode. This is a side-effect of the
implementation and unavoidable.

@table @var
@item channel
a @code{<gio-channel>} to watch

@item condition
conditions to watch for

@item ret
a new @code{<g-source>}

@end table

@end deffn

@deffn Function g-io-add-watch  (channel@tie{}@code{<gio-channel>}) (condition@tie{}@code{<gio-condition>}) (func@tie{}@code{scm}) @result{}@tie{} (ret@tie{}@code{bool})
Adds the @code{<gio-channel>} into the main event loop with the default
priority.

@table @var
@item channel
a @code{<gio-channel>}.

@item condition
the condition to watch for.

@item func
the function to call when the condition is satisfied.

@item user-data
user data to pass to @var{func}.

@item ret
the event source id.

@end table

@end deffn

@deffn Function g-io-channel-get-buffer-size  (channel@tie{}@code{<gio-channel>}) @result{}@tie{} (ret@tie{}@code{size_t})
Gets the buffer size.

@table @var
@item channel
a @code{<gio-channel>}

@item ret
the size of the buffer.

@end table

@end deffn

@deffn Function g-io-channel-set-buffer-size  (channel@tie{}@code{<gio-channel>}) (size@tie{}@code{size_t})
Sets the buffer size.

@table @var
@item channel
a @code{<gio-channel>}

@item size
the size of the buffer. 0 == pick a good size

@end table

@end deffn

@deffn Function g-io-channel-get-buffer-condition  (channel@tie{}@code{<gio-channel>}) @result{}@tie{} (ret@tie{}@code{<gio-condition>})
This function returns a @code{<gio-condition>} depending on whether there is
data to be read/space to write data in the internal buffers in the
@code{<gio-channel>}. Only the flags @samp{G_IO_IN} and @samp{G_IO_OUT} may be
set.

@table @var
@item channel
A @code{<gio-channel>}

@item ret
A @code{<gio-condition>}

@end table

@end deffn

@deffn Function g-io-channel-get-flags  (channel@tie{}@code{<gio-channel>}) @result{}@tie{} (ret@tie{}@code{<gio-flags>})
Gets the current flags for a @code{<gio-channel>}, including read-only flags
such as @samp{G_IO_FLAG_IS_READABLE}.

The values of the flags @samp{G_IO_FLAG_IS_READABLE} and
@samp{G_IO_FLAG_IS_WRITEABLE} 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 @code{shutdown} function), the user should immediately
call @code{g-io-channel-get-flags} to update the internal values of these flags.

@table @var
@item channel
a @code{<gio-channel>}

@item ret
the flags which are set on the channel

@end table

@end deffn

@deffn Function g-io-channel-set-flags  (channel@tie{}@code{<gio-channel>}) (flags@tie{}@code{<gio-flags>}) @result{}@tie{} (ret@tie{}@code{<gio-status>})
Sets the (writeable) flags in @var{channel} to (@var{flags} &
@samp{G_IO_CHANNEL_SET_MASK}).

@table @var
@item channel
a @code{<gio-channel>}.

@item flags
the flags to set on the IO channel.

@item error
A location to return an error of type @code{<gio-channel-error>}.

@item ret
the status of the operation.

@end table

@end deffn

@deffn Function g-io-channel-get-line-term  (channel@tie{}@code{<gio-channel>}) @result{}@tie{} (ret@tie{}@code{mchars}) (length@tie{}@code{int})
This returns the string that @code{<gio-channel>} uses to determine where in the
file a line break occurs. A value of @samp{@code{#f}} indicates auto detection.

@table @var
@item channel
a @code{<gio-channel>}

@item length
a location to return the length of the line terminator

@item ret
The line termination string. This value is owned by GLib and must not be freed.

@end table

@end deffn

@deffn Function g-io-channel-set-line-term  (channel@tie{}@code{<gio-channel>}) (line_term@tie{}@code{mchars}) (length@tie{}@code{int})
This sets the string that @code{<gio-channel>} uses to determine where in the
file a line break occurs.

@table @var
@item channel
a @code{<gio-channel>}

@item line-term
The line termination string. Use @samp{@code{#f}} for auto detect. Auto
detection breaks on "\n", "\r\n", "\r", "\0", and the Unicode paragraph
separator. Auto detection should not be used for anything other than file-based
channels.

@item 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 embeded nuls.

@end table

@end deffn

@deffn Function g-io-channel-get-buffered  (channel@tie{}@code{<gio-channel>}) @result{}@tie{} (ret@tie{}@code{bool})
Returns whether @var{channel} is buffered.

@table @var
@item channel
a @code{<gio-channel>}.

@item ret
@samp{@code{#t}} if the @var{channel} is buffered.

@end table

@end deffn

@deffn Function g-io-channel-set-buffered  (channel@tie{}@code{<gio-channel>}) (buffered@tie{}@code{bool})
The buffering state can only be set if the channel's encoding is
@samp{@code{#f}}. 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
@samp{G_IO_STATUS_EOF} not require such a flush. For write-only channels, a call
to @code{g-io-channel-flush} is sufficient. For all other channels, the buffers
may be flushed by a call to @code{g-io-channel-seek-position}. This includes the
possibility of seeking with seek type @samp{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.

@table @var
@item channel
a @code{<gio-channel>}

@item buffered
whether to set the channel buffered or unbuffered

@end table

@end deffn

@deffn Function g-io-channel-get-encoding  (channel@tie{}@code{<gio-channel>}) @result{}@tie{} (ret@tie{}@code{mchars})
Gets the encoding for the input/output of the channel. The internal encoding is
always UTF-8. The encoding @samp{@code{#f}} makes the channel safe for binary
data.

@table @var
@item channel
a @code{<gio-channel>}

@item ret
A string containing the encoding, this string is owned by GLib and must not be
freed.

@end table

@end deffn

@deffn Function g-io-channel-set-encoding  (channel@tie{}@code{<gio-channel>}) (encoding@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{<gio-status>})
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 @samp{@code{#f}} is safe to use with binary data.

The encoding can only be set if one of the following conditions is true:

1. The channel was just created, and has not been written to or read from yet.

2. The channel is write-only.

3. The channel is a file, and the file pointer was just repositioned by a call
to @code{g-io-channel-seek-position}. (This flushes all the internal buffers.)

4. The current encoding is @samp{@code{#f}} or UTF-8.

5. One of the (new API) read functions has just returned @samp{G_IO_STATUS_EOF}
(or, in the case of @code{g-io-channel-read-to-end}, @samp{G_IO_STATUS_NORMAL}).

6. One of the functions @code{g-io-channel-read-chars} or
@code{g-io-channel-read-unichar} has returned @samp{G_IO_STATUS_AGAIN} or
@samp{G_IO_STATUS_ERROR}. This may be useful in the case of
@samp{G_CONVERT_ERROR_ILLEGAL_SEQUENCE}. Returning one of these statuses from
@code{g-io-channel-read-line}, @code{g-io-channel-read-line-string}, or
@code{g-io-channel-read-to-end} does @emph{not} guarantee that the encoding can
be changed.

Channels which do not meet one of the above conditions cannot call
@code{g-io-channel-seek-position} with an offset of @samp{G_SEEK_CUR}, and, if
they are "seekable", cannot call @code{g-io-channel-write-chars} after calling
one of the API "read" functions.

@table @var
@item channel
a @code{<gio-channel>}

@item encoding
the encoding type

@item error
location to store an error of type @code{<g-convert-error>}.

@item ret
@samp{G_IO_STATUS_NORMAL} if the encoding was successfully set.

@end table

@end deffn

@deffn Function g-io-channel-close  (channel@tie{}@code{<gio-channel>})
@samp{g_io_channel_close} has been deprecated since version 2.2 and should not
be used in newly-written code. Use @code{g-io-channel-shutdown} instead.

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
@code{g-io-channel-unref}.

@table @var
@item channel
A @code{<gio-channel>}

@end table

@end deffn


@c %end of fragment
