Functions
g_io_channel_unix_new ()
GIOChannel *
g_io_channel_unix_new (int fd);
Creates a new GIOChannel given a file descriptor. On UNIX systems
this works for plain files, pipes, and sockets.
The returned GIOChannel has a reference count of 1.
The default encoding for GIOChannel 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
g_get_charset()) with the g_io_channel_set_encoding() function.
By default, the fd passed will not be closed when the final reference
to the GIOChannel data structure is dropped.
If you want to read raw binary data without interpretation, then
call the g_io_channel_set_encoding() function with NULL 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.
g_io_channel_unix_get_fd ()
gint
g_io_channel_unix_get_fd (GIOChannel *channel);
Returns the file descriptor of the GIOChannel.
On Windows this function returns the file descriptor or socket of
the GIOChannel.
g_io_channel_win32_new_fd ()
GIOChannel *
g_io_channel_win32_new_fd (gint fd);
Creates a new GIOChannel given a file descriptor on Windows. This
works for file descriptors from the C runtime.
This function works for file descriptors as returned by the open(),
creat(), pipe() and fileno() calls in the Microsoft C runtime. In
order to meaningfully use this function your code should use the
same C runtime as GLib uses, which is msvcrt.dll. Note that in
current Microsoft compilers it is near impossible to convince it to
build code that would use msvcrt.dll. The last Microsoft compiler
version that supported using msvcrt.dll as the C runtime was version 6.
The GNU compiler and toolchain for Windows, also known as Mingw,
fully supports msvcrt.dll.
If you have created a GIOChannel for a file descriptor and started
watching (polling) it, you shouldn't call read() on the file
descriptor. This is because adding polling for a file descriptor is
implemented in GLib on Windows by starting a thread that sits
blocked in a read() from the file descriptor most of the time. All
reads from the file descriptor should be done by this internal GLib
thread. Your code should call only g_io_channel_read().
This function is available only in GLib on Windows.
g_io_channel_win32_new_socket ()
GIOChannel *
g_io_channel_win32_new_socket (gint socket);
Creates a new GIOChannel given a socket on Windows.
This function works for sockets created by Winsock. It's available
only in GLib on Windows.
Polling a GSource 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.
g_io_channel_win32_new_messages ()
GIOChannel *
g_io_channel_win32_new_messages (gsize hwnd);
Creates a new GIOChannel given a window handle on Windows.
This function creates a GIOChannel that can be used to poll for
Windows messages for the window in question.
g_io_channel_init ()
void
g_io_channel_init (GIOChannel *channel);
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).
g_io_channel_new_file ()
GIOChannel *
g_io_channel_new_file (const gchar *filename,
const gchar *mode,
GError **error);
Open a file filename
as a GIOChannel using mode mode
. This
channel will be closed when the last reference to it is dropped,
so there is no need to call 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).
g_io_channel_read_unichar ()
GIOStatus
g_io_channel_read_unichar (GIOChannel *channel,
gunichar *thechar,
GError **error);
Reads a Unicode character from channel
.
This function cannot be called on a channel with NULL encoding.
g_io_channel_read_line ()
GIOStatus
g_io_channel_read_line (GIOChannel *channel,
gchar **str_return,
gsize *length,
gsize *terminator_pos,
GError **error);
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.
Returns
the status of the operation.
g_io_channel_read_to_end ()
GIOStatus
g_io_channel_read_to_end (GIOChannel *channel,
gchar **str_return,
gsize *length,
GError **error);
Reads all the remaining data from the file.
g_io_channel_write_unichar ()
GIOStatus
g_io_channel_write_unichar (GIOChannel *channel,
gunichar thechar,
GError **error);
Writes a Unicode character to channel
.
This function cannot be called on a channel with NULL encoding.
g_io_channel_flush ()
GIOStatus
g_io_channel_flush (GIOChannel *channel,
GError **error);
Flushes the write buffer for the GIOChannel.
g_io_channel_shutdown ()
GIOStatus
g_io_channel_shutdown (GIOChannel *channel,
gboolean flush,
GError **err);
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().
Returns
the status of the operation.
g_io_channel_ref ()
GIOChannel *
g_io_channel_ref (GIOChannel *channel);
Increments the reference count of a GIOChannel.
Returns
the channel
that was passed in (since 2.6)
g_io_channel_unref ()
void
g_io_channel_unref (GIOChannel *channel);
Decrements the reference count of a GIOChannel.
g_io_create_watch ()
GSource *
g_io_create_watch (GIOChannel *channel,
GIOCondition condition);
Creates a GSource that's dispatched when condition
is met for the
given channel
. For example, if condition is G_IO_IN, the source will
be dispatched when there's data available for reading.
The callback function invoked by the GSource should be added with
g_source_set_callback(), but it has type GIOFunc (not GSourceFunc).
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 context
at the default priority.
On Windows, polling a GSource 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.
g_io_channel_get_buffer_size ()
gsize
g_io_channel_get_buffer_size (GIOChannel *channel);
Gets the buffer size.
Returns
the size of the buffer.
g_io_channel_set_buffer_size ()
void
g_io_channel_set_buffer_size (GIOChannel *channel,
gsize size);
Sets the buffer size.
g_io_channel_get_buffer_condition ()
GIOCondition
g_io_channel_get_buffer_condition (GIOChannel *channel);
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.
g_io_channel_get_flags ()
GIOFlags
g_io_channel_get_flags (GIOChannel *channel);
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.
Returns
the flags which are set on the channel
g_io_channel_get_line_term ()
const gchar *
g_io_channel_get_line_term (GIOChannel *channel,
gint *length);
This returns the string that GIOChannel uses to determine
where in the file a line break occurs. A value of NULL
indicates autodetection.
Returns
The line termination string. This value
is owned by GLib and must not be freed.
g_io_channel_set_line_term ()
void
g_io_channel_set_line_term (GIOChannel *channel,
const gchar *line_term,
gint length);
This sets the string that GIOChannel uses to determine
where in the file a line break occurs.
g_io_channel_get_buffered ()
gboolean
g_io_channel_get_buffered (GIOChannel *channel);
Returns whether channel
is buffered.
Returns
TRUE if the channel
is buffered.
g_io_channel_set_buffered ()
void
g_io_channel_set_buffered (GIOChannel *channel,
gboolean 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.
g_io_channel_get_encoding ()
const gchar *
g_io_channel_get_encoding (GIOChannel *channel);
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.
Returns
A string containing the encoding, this string is
owned by GLib and must not be freed.
g_io_channel_set_encoding ()
GIOStatus
g_io_channel_set_encoding (GIOChannel *channel,
const gchar *encoding,
GError **error);
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:
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.
g_io_channel_get_close_on_unref ()
gboolean
g_io_channel_get_close_on_unref (GIOChannel *channel);
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.
Returns
TRUE if the channel will be closed, FALSE otherwise.
g_io_channel_set_close_on_unref ()
void
g_io_channel_set_close_on_unref (GIOChannel *channel,
gboolean 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.
g_io_channel_close ()
void
g_io_channel_close (GIOChannel *channel);
g_io_channel_close has been deprecated since version 2.2 and should not be used in newly-written code.
Use 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 g_io_channel_unref().