luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-03-31 04:43:06 +02:00
Code Issues Packages Projects Releases Wiki Activity

GIOChannel: move docs from tmpl to .c

Browse Source
This commit is contained in:
Ryan Lortie 2010-01-31 00:39:40 -05:00
parent 4353151449
commit 4bdf7d12a8
5 changed files with 285 additions and 666 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/reference/glib/tmpl/.gitignore vendored
View File

@ -9,6 +9,7 @@ ghostutils.sgml
gurifuncs.sgml gurifuncs.sgml
gvarianttype.sgml gvarianttype.sgml
hash_tables.sgml hash_tables.sgml
iochannels.sgml
memory_chunks.sgml memory_chunks.sgml
option.sgml option.sgml
patterns.sgml patterns.sgml

666
docs/reference/glib/tmpl/iochannels.sgml
View File

@ -1,666 +0,0 @@
<!-- ##### SECTION Title ##### -->
IO Channels
<!-- ##### SECTION Short_Description ##### -->
portable support for using files, pipes and sockets
<!-- ##### SECTION Long_Description ##### -->
<para>
The #GIOChannel data type aims to provide a portable method for using file
descriptors, pipes, and sockets, and integrating them into the
<link linkend="glib-The-Main-Event-Loop">main event loop</link>.
Currently full support is available on UNIX platforms, support for
Windows is only partially complete.
</para>
<para>
To create a new #GIOChannel on UNIX systems use g_io_channel_unix_new().
This works for plain file descriptors, pipes and sockets.
Alternatively, a channel can be created for a file in a system independent
manner using g_io_channel_new_file().
</para>
<para>
Once a #GIOChannel has been created, it can be used in a generic manner
with the functions g_io_channel_read_chars(), g_io_channel_write_chars(),
g_io_channel_seek_position(), and g_io_channel_shutdown().
</para>
<para>
To add a #GIOChannel to the
<link linkend="glib-The-Main-Event-Loop">main event loop</link>
use g_io_add_watch() or g_io_add_watch_full(). Here you specify which events
you are interested in on the #GIOChannel, and provide a function to be
called whenever these events occur.
</para>
<para>
#GIOChannel instances are created with an initial reference count of 1.
g_io_channel_ref() and g_io_channel_unref() can be used to increment or
decrement the reference count respectively. When the reference count falls
to 0, the #GIOChannel is freed. (Though it isn't closed automatically,
unless it was created using g_io_channel_new_from_file().)
Using g_io_add_watch() or g_io_add_watch_full() increments a channel's
reference count.
</para>
<para>
The new functions g_io_channel_read_chars(), g_io_channel_read_line(),
g_io_channel_read_line_string(), g_io_channel_read_to_end(),
g_io_channel_write_chars(), g_io_channel_seek_position(),
and g_io_channel_flush() should not be mixed with the
deprecated functions g_io_channel_read(), g_io_channel_write(),
and g_io_channel_seek() on the same channel.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
<variablelist>
<varlistentry>
<term>gtk_input_add_full(), gtk_input_remove(), gdk_input_add(),
gdk_input_add_full(), gdk_input_remove()</term>
<listitem><para>
Convenience functions for creating #GIOChannel instances and adding them to the
<link linkend="glib-The-Main-Event-Loop">main event loop</link>.
</para></listitem>
</varlistentry>
</variablelist>
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### STRUCT GIOChannel ##### -->
<para>
A data structure representing an IO Channel. The fields should be considered
private and should only be accessed with the following functions.
</para>
<!-- ##### FUNCTION g_io_channel_unix_new ##### -->
<para>
Creates a new #GIOChannel given a file descriptor.
On UNIX systems this works for plain files, pipes, and sockets.
</para>
<para>
The returned #GIOChannel has a reference count of 1.
</para>
<para>
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.
</para>
<para>
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.
</para>
<para>
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.
</para>
@fd: a file descriptor.
@Returns: a new #GIOChannel.
<!-- ##### FUNCTION g_io_channel_unix_get_fd ##### -->
<para>
Returns the file descriptor of the #GIOChannel.
</para>
<para>
On Windows this function returns the file descriptor or socket of the #GIOChannel.
</para>
@channel: a #GIOChannel, created with g_io_channel_unix_new().
@Returns: the file descriptor of the #GIOChannel.
<!-- ##### FUNCTION g_io_channel_win32_new_fd ##### -->
<para>
Creates a new #GIOChannel given a file descriptor on Windows.
This works for file descriptors from the C runtime.
</para>
<para>
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.
</para>
<para>
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().
</para>
<para>
This function is available only in GLib on Windows.
</para>
@fd: a C library file descriptor.
@Returns: a new #GIOChannel.
<!-- ##### FUNCTION g_io_channel_win32_new_socket ##### -->
<para>
Creates a new #GIOChannel given a socket on Windows.
</para>
<para>
This function works for sockets created by Winsock.
It's available only in GLib on Windows.
</para>
<para>
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.
</para>
@socket: a Winsock socket
@Returns: a new #GIOChannel
<!-- ##### FUNCTION g_io_channel_win32_new_messages ##### -->
<para>
Creates a new #GIOChannel given a window handle on Windows.
</para>
<para>
This function creates a #GIOChannel that can be used to poll for
Windows messages for the window in question.
</para>
@hwnd: a window handle.
@Returns: a new #GIOChannel.
<!-- ##### FUNCTION g_io_channel_init ##### -->
<para>
</para>
@channel:
<!-- ##### FUNCTION g_io_channel_new_file ##### -->
<para>
</para>
@filename:
@mode:
@error:
@Returns:
<!-- ##### FUNCTION g_io_channel_read_chars ##### -->
<para>
</para>
@channel:
@buf:
@count:
@bytes_read:
@error:
@Returns:
<!-- ##### FUNCTION g_io_channel_read_unichar ##### -->
<para>
</para>
@channel:
@thechar:
@error:
@Returns:
<!-- ##### FUNCTION g_io_channel_read_line ##### -->
<para>
</para>
@channel:
@str_return:
@length:
@terminator_pos:
@error:
@Returns:
<!-- ##### FUNCTION g_io_channel_read_line_string ##### -->
<para>
</para>
@channel:
@buffer:
@terminator_pos:
@error:
@Returns:
<!-- ##### FUNCTION g_io_channel_read_to_end ##### -->
<para>
</para>
@channel:
@str_return:
@length:
@error:
@Returns:
<!-- ##### FUNCTION g_io_channel_write_chars ##### -->
<para>
</para>
@channel:
@buf:
@count:
@bytes_written:
@error:
@Returns:
<!-- ##### FUNCTION g_io_channel_write_unichar ##### -->
<para>
</para>
@channel:
@thechar:
@error:
@Returns:
<!-- ##### FUNCTION g_io_channel_flush ##### -->
<para>
</para>
@channel:
@error:
@Returns:
<!-- ##### FUNCTION g_io_channel_seek_position ##### -->
<para>
</para>
@channel:
@offset:
@type:
@error:
@Returns:
<!-- ##### ENUM GSeekType ##### -->
<para>
An enumeration specifying the base position for a g_io_channel_seek_position()
operation.
</para>
@G_SEEK_CUR: the current position in the file.
@G_SEEK_SET: the start of the file.
@G_SEEK_END: the end of the file.
<!-- ##### FUNCTION g_io_channel_shutdown ##### -->
<para>
</para>
@channel:
@flush:
@err:
@Returns:
<!-- ##### ENUM GIOStatus ##### -->
<para>
Stati returned by most of the #GIOFuncs functions.
</para>
@G_IO_STATUS_ERROR: An error occurred.
@G_IO_STATUS_NORMAL: Success.
@G_IO_STATUS_EOF: End of file.
@G_IO_STATUS_AGAIN: Resource temporarily unavailable.
<!-- ##### ENUM GIOChannelError ##### -->
<para>
Error codes returned by #GIOChannel operations.
</para>
@G_IO_CHANNEL_ERROR_FBIG: File too large.
@G_IO_CHANNEL_ERROR_INVAL: Invalid argument.
@G_IO_CHANNEL_ERROR_IO: IO error.
@G_IO_CHANNEL_ERROR_ISDIR: File is a directory.
@G_IO_CHANNEL_ERROR_NOSPC: No space left on device.
@G_IO_CHANNEL_ERROR_NXIO: No such device or address.
@G_IO_CHANNEL_ERROR_OVERFLOW: Value too large for defined datatype.
@G_IO_CHANNEL_ERROR_PIPE: Broken pipe.
@G_IO_CHANNEL_ERROR_FAILED: Some other error.
<!-- ##### MACRO G_IO_CHANNEL_ERROR ##### -->
<para>
Error domain for #GIOChannel operations. Errors in this domain will
be from the #GIOChannelError enumeration. See #GError for information on
error domains.
</para>
<!-- ##### FUNCTION g_io_channel_error_from_errno ##### -->
<para>
</para>
@en:
@Returns:
<!-- ##### FUNCTION g_io_channel_ref ##### -->
<para>
</para>
@channel:
@Returns:
<!-- ##### FUNCTION g_io_channel_unref ##### -->
<para>
</para>
@channel:
<!-- ##### FUNCTION g_io_create_watch ##### -->
<para>
</para>
@channel:
@condition:
@Returns:
<!-- ##### FUNCTION g_io_add_watch ##### -->
<para>
</para>
@channel:
@condition:
@func:
@user_data:
@Returns:
<!-- ##### FUNCTION g_io_add_watch_full ##### -->
<para>
</para>
@channel:
@priority:
@condition:
@func:
@user_data:
@notify:
@Returns:
<!-- ##### ENUM GIOCondition ##### -->
<para>
A bitwise combination representing a condition to watch for on
an event source.
</para>
@G_IO_IN: There is data to read.
@G_IO_OUT: Data can be written (without blocking).
@G_IO_PRI: There is urgent data to read.
@G_IO_ERR: Error condition.
@G_IO_HUP: Hung up (the connection has been broken, usually for pipes
and sockets).
@G_IO_NVAL: Invalid request. The file descriptor is not open.
<!-- ##### USER_FUNCTION GIOFunc ##### -->
<para>
Specifies the type of function passed to g_io_add_watch() or
g_io_add_watch_full(), which is called when the requested
condition on a #GIOChannel is satisfied.
</para>
@source: the #GIOChannel event source
@condition: the condition which has been satisfied
@data: user data set in g_io_add_watch() or g_io_add_watch_full()
@Returns: the function should return %FALSE if the event source
should be removed
<!-- ##### STRUCT GIOFuncs ##### -->
<para>
A table of functions used to handle different types of #GIOChannel
in a generic way.
</para>
@io_read: reads raw bytes from the channel. This is called from various functions such as g_io_channel_read_chars() to read raw bytes from the channel. Encoding and buffering issues are dealt with at a higher level.
@io_write: writes raw bytes to the channel. This is called from various functions such as g_io_channel_write_chars() to write raw bytes to the channel. Encoding and buffering issues are dealt with at a higher level.
@io_seek: (optional) seeks the channel. This is called from g_io_channel_seek() on channels that support it.
@io_close: closes the channel. This is called from g_io_channel_close() after flushing the buffers.
@io_create_watch: creates a watch on the channel. This call corresponds directly to g_io_create_watch().
@io_free: called from g_io_channel_unref() when the channel needs to be freed. This function must free the memory associated with the channel, including freeing the #GIOChannel structure itself. The channel buffers have been flushed and possibly @io_close has been called by the time this function is called.
@io_set_flags: sets the #GIOFlags on the channel. This is called from g_io_channel_set_flags() with all flags except for %G_IO_FLAG_APPEND and %G_IO_FLAG_NONBLOCK masked out.
@io_get_flags: gets the #GIOFlags for the channel. This function need only return the %G_IO_FLAG_APPEND and %G_IO_FLAG_NONBLOCK flags; g_io_channel_get_flags() automatically adds the others as appropriate.
<!-- ##### FUNCTION g_io_channel_get_buffer_size ##### -->
<para>
</para>
@channel:
@Returns:
<!-- ##### FUNCTION g_io_channel_set_buffer_size ##### -->
<para>
</para>
@channel:
@size:
<!-- ##### FUNCTION g_io_channel_get_buffer_condition ##### -->
<para>
</para>
@channel:
@Returns:
<!-- ##### FUNCTION g_io_channel_get_flags ##### -->
<para>
</para>
@channel:
@Returns:
<!-- ##### FUNCTION g_io_channel_set_flags ##### -->
<para>
</para>
@channel:
@flags:
@error:
@Returns:
<!-- ##### ENUM GIOFlags ##### -->
<para>
Specifies properties of a #GIOChannel. Some of the flags can only
be read with g_io_channel_get_flags(), but not changed with
g_io_channel_set_flags().
</para>
@G_IO_FLAG_APPEND: turns on append mode, corresponds to %O_APPEND
(see the documentation of the UNIX open() syscall).
@G_IO_FLAG_NONBLOCK: turns on nonblocking mode, corresponds to
%O_NONBLOCK/%O_NDELAY (see the documentation of the UNIX open()
syscall).
@G_IO_FLAG_IS_READABLE: indicates that the io channel is readable.
This flag can not be changed.
@G_IO_FLAG_IS_WRITEABLE: indicates that the io channel is writable.
This flag can not be changed.
@G_IO_FLAG_IS_SEEKABLE: indicates that the io channel is seekable,
i.e. that g_io_channel_seek_position() can be used on it.
This flag can not be changed.
@G_IO_FLAG_MASK: the mask that specifies all the valid flags.
@G_IO_FLAG_GET_MASK: the mask of the flags that are returned from g_io_channel_get_flags().
@G_IO_FLAG_SET_MASK: the mask of the flags that the user can modify with g_io_channel_set_flags().
<!-- ##### FUNCTION g_io_channel_get_line_term ##### -->
<para>
</para>
@channel:
@length:
@Returns:
<!-- ##### FUNCTION g_io_channel_set_line_term ##### -->
<para>
</para>
@channel:
@line_term:
@length:
<!-- ##### FUNCTION g_io_channel_get_buffered ##### -->
<para>
</para>
@channel:
@Returns:
<!-- ##### FUNCTION g_io_channel_set_buffered ##### -->
<para>
</para>
@channel:
@buffered:
<!-- ##### FUNCTION g_io_channel_get_encoding ##### -->
<para>
</para>
@channel:
@Returns:
<!-- ##### FUNCTION g_io_channel_set_encoding ##### -->
<para>
</para>
@channel:
@encoding:
@error:
@Returns:
<!-- ##### FUNCTION g_io_channel_get_close_on_unref ##### -->
<para>
</para>
@channel:
@Returns:
<!-- ##### FUNCTION g_io_channel_set_close_on_unref ##### -->
<para>
</para>
@channel:
@do_close:
<!-- ##### FUNCTION g_io_channel_read ##### -->
<para>
</para>
@channel:
@buf:
@count:
@bytes_read:
@Returns:
<!-- ##### ENUM GIOError ##### -->
<para>
#GIOError is only used by the deprecated functions g_io_channel_read(),
g_io_channel_write(), and g_io_channel_seek().
</para>
@G_IO_ERROR_NONE: no error
@G_IO_ERROR_AGAIN: an EAGAIN error occurred
@G_IO_ERROR_INVAL: an EINVAL error occurred
@G_IO_ERROR_UNKNOWN: another error occurred
<!-- ##### FUNCTION g_io_channel_write ##### -->
<para>
</para>
@channel:
@buf:
@count:
@bytes_written:
@Returns:
<!-- ##### FUNCTION g_io_channel_seek ##### -->
<para>
</para>
@channel:
@offset:
@type.
@type:
@Returns:
<!-- ##### FUNCTION g_io_channel_close ##### -->
<para>
</para>
@channel:

196
glib/giochannel.c
View File

@ -50,6 +50,122 @@
#include "galias.h" #include "galias.h"
/**
* SECTION: iochannels
* @title: IO Channels
* @short_description: portable support for using files, pipes and
* sockets
* @see_also: <para> <variablelist> <varlistentry>
* <term>gtk_input_add_full(), gtk_input_remove(),
* gdk_input_add(), gdk_input_add_full(),
* gdk_input_remove()</term> <listitem><para> Convenience
* functions for creating #GIOChannel instances and adding
* them to the <link linkend="glib-The-Main-Event-Loop">main
* event loop</link>. </para></listitem> </varlistentry>
* </variablelist> </para>
*
* The #GIOChannel data type aims to provide a portable method for
* using file descriptors, pipes, and sockets, and integrating them
* into the <link linkend="glib-The-Main-Event-Loop">main event
* loop</link>. Currently full support is available on UNIX platforms,
* support for Windows is only partially complete.
*
* To create a new #GIOChannel on UNIX systems use
* g_io_channel_unix_new(). This works for plain file descriptors,
* pipes and sockets. Alternatively, a channel can be created for a
* file in a system independent manner using g_io_channel_new_file().
*
* Once a #GIOChannel has been created, it can be used in a generic
* manner with the functions g_io_channel_read_chars(),
* g_io_channel_write_chars(), g_io_channel_seek_position(), and
* g_io_channel_shutdown().
*
* To add a #GIOChannel to the <link
* linkend="glib-The-Main-Event-Loop">main event loop</link> use
* g_io_add_watch() or g_io_add_watch_full(). Here you specify which
* events you are interested in on the #GIOChannel, and provide a
* function to be called whenever these events occur.
*
* #GIOChannel instances are created with an initial reference count of
* 1. g_io_channel_ref() and g_io_channel_unref() can be used to
* increment or decrement the reference count respectively. When the
* reference count falls to 0, the #GIOChannel is freed. (Though it
* isn't closed automatically, unless it was created using
* g_io_channel_new_from_file().) Using g_io_add_watch() or
* g_io_add_watch_full() increments a channel's reference count.
*
* The new functions g_io_channel_read_chars(),
* g_io_channel_read_line(), g_io_channel_read_line_string(),
* g_io_channel_read_to_end(), g_io_channel_write_chars(),
* g_io_channel_seek_position(), and g_io_channel_flush() should not be
* mixed with the deprecated functions g_io_channel_read(),
* g_io_channel_write(), and g_io_channel_seek() on the same channel.
**/
/**
* GIOChannel:
*
* A data structure representing an IO Channel. The fields should be
* considered private and should only be accessed with the following
* functions.
**/
/**
* GIOFuncs:
* @io_read: reads raw bytes from the channel. This is called from
* various functions such as g_io_channel_read_chars() to
* read raw bytes from the channel. Encoding and buffering
* issues are dealt with at a higher level.
* @io_write: writes raw bytes to the channel. This is called from
* various functions such as g_io_channel_write_chars() to
* write raw bytes to the channel. Encoding and buffering
* issues are dealt with at a higher level.
* @io_seek: (optional) seeks the channel. This is called from
* g_io_channel_seek() on channels that support it.
* @io_close: closes the channel. This is called from
* g_io_channel_close() after flushing the buffers.
* @io_create_watch: creates a watch on the channel. This call
* corresponds directly to g_io_create_watch().
* @io_free: called from g_io_channel_unref() when the channel needs to
* be freed. This function must free the memory associated
* with the channel, including freeing the #GIOChannel
* structure itself. The channel buffers have been flushed
* and possibly @io_close has been called by the time this
* function is called.
* @io_set_flags: sets the #GIOFlags on the channel. This is called
* from g_io_channel_set_flags() with all flags except
* for %G_IO_FLAG_APPEND and %G_IO_FLAG_NONBLOCK masked
* out.
* @io_get_flags: gets the #GIOFlags for the channel. This function
* need only return the %G_IO_FLAG_APPEND and
* %G_IO_FLAG_NONBLOCK flags; g_io_channel_get_flags()
* automatically adds the others as appropriate.
*
* A table of functions used to handle different types of #GIOChannel
* in a generic way.
**/
/**
* GIOStatus:
* @G_IO_STATUS_ERROR: An error occurred.
* @G_IO_STATUS_NORMAL: Success.
* @G_IO_STATUS_EOF: End of file.
* @G_IO_STATUS_AGAIN: Resource temporarily unavailable.
*
* Stati returned by most of the #GIOFuncs functions.
**/
/**
* GIOError:
* @G_IO_ERROR_NONE: no error
* @G_IO_ERROR_AGAIN: an EAGAIN error occurred
* @G_IO_ERROR_INVAL: an EINVAL error occurred
* @G_IO_ERROR_UNKNOWN: another error occurred
*
* #GIOError is only used by the deprecated functions
* g_io_channel_read(), g_io_channel_write(), and g_io_channel_seek().
**/
#define G_IO_NICE_BUF_SIZE 1024 #define G_IO_NICE_BUF_SIZE 1024
/* This needs to be as wide as the largest character in any possible encoding */ /* This needs to be as wide as the largest character in any possible encoding */
@ -571,6 +687,31 @@ g_io_add_watch_full (GIOChannel *channel,
* *
* Returns: the event source id * Returns: the event source id
*/ */
/**
* GIOFunc:
* @source: the #GIOChannel event source
* @condition: the condition which has been satisfied
* @data: user data set in g_io_add_watch() or g_io_add_watch_full()
* @Returns: the function should return %FALSE if the event source
* should be removed
*
* Specifies the type of function passed to g_io_add_watch() or
* g_io_add_watch_full(), which is called when the requested condition
* on a #GIOChannel is satisfied.
**/
/**
* GIOCondition:
* @G_IO_IN: There is data to read.
* @G_IO_OUT: Data can be written (without blocking).
* @G_IO_PRI: There is urgent data to read.
* @G_IO_ERR: Error condition.
* @G_IO_HUP: Hung up (the connection has been broken, usually for
* pipes and sockets).
* @G_IO_NVAL: Invalid request. The file descriptor is not open.
*
* A bitwise combination representing a condition to watch for on an
* event source.
**/
guint guint
g_io_add_watch (GIOChannel *channel, g_io_add_watch (GIOChannel *channel,
GIOCondition condition, GIOCondition condition,
@ -803,6 +944,31 @@ g_io_channel_get_line_term (GIOChannel *channel,
* *
* Return value: the status of the operation. * Return value: the status of the operation.
**/ **/
/**
* GIOFlags:
* @G_IO_FLAG_APPEND: turns on append mode, corresponds to %O_APPEND
* (see the documentation of the UNIX open()
* syscall).
* @G_IO_FLAG_NONBLOCK: turns on nonblocking mode, corresponds to
* %O_NONBLOCK/%O_NDELAY (see the documentation of
* the UNIX open() syscall).
* @G_IO_FLAG_IS_READABLE: indicates that the io channel is readable.
* This flag can not be changed.
* @G_IO_FLAG_IS_WRITEABLE: indicates that the io channel is writable.
* This flag can not be changed.
* @G_IO_FLAG_IS_SEEKABLE: indicates that the io channel is seekable,
* i.e. that g_io_channel_seek_position() can
* be used on it. This flag can not be changed.
* @G_IO_FLAG_MASK: the mask that specifies all the valid flags.
* @G_IO_FLAG_GET_MASK: the mask of the flags that are returned from
* g_io_channel_get_flags().
* @G_IO_FLAG_SET_MASK: the mask of the flags that the user can modify
* with g_io_channel_set_flags().
*
* Specifies properties of a #GIOChannel. Some of the flags can only be
* read with g_io_channel_get_flags(), but not changed with
* g_io_channel_set_flags().
**/
GIOStatus GIOStatus
g_io_channel_set_flags (GIOChannel *channel, g_io_channel_set_flags (GIOChannel *channel,
GIOFlags flags, GIOFlags flags,
@ -908,6 +1074,15 @@ g_io_channel_get_close_on_unref (GIOChannel *channel)
* *
* Return value: the status of the operation. * Return value: the status of the operation.
**/ **/
/**
* GSeekType:
* @G_SEEK_CUR: the current position in the file.
* @G_SEEK_SET: the start of the file.
* @G_SEEK_END: the end of the file.
*
* An enumeration specifying the base position for a
* g_io_channel_seek_position() operation.
**/
GIOStatus GIOStatus
g_io_channel_seek_position (GIOChannel *channel, g_io_channel_seek_position (GIOChannel *channel,
gint64 offset, gint64 offset,
@ -2379,6 +2554,27 @@ g_io_channel_write_unichar (GIOChannel *channel,
* *
* Return value: the quark used as %G_IO_CHANNEL_ERROR * Return value: the quark used as %G_IO_CHANNEL_ERROR
**/ **/
/**
* G_IO_CHANNEL_ERROR:
*
* Error domain for #GIOChannel operations. Errors in this domain will
* be from the #GIOChannelError enumeration. See #GError for
* information on error domains.
**/
/**
* GIOChannelError:
* @G_IO_CHANNEL_ERROR_FBIG: File too large.
* @G_IO_CHANNEL_ERROR_INVAL: Invalid argument.
* @G_IO_CHANNEL_ERROR_IO: IO error.
* @G_IO_CHANNEL_ERROR_ISDIR: File is a directory.
* @G_IO_CHANNEL_ERROR_NOSPC: No space left on device.
* @G_IO_CHANNEL_ERROR_NXIO: No such device or address.
* @G_IO_CHANNEL_ERROR_OVERFLOW: Value too large for defined datatype.
* @G_IO_CHANNEL_ERROR_PIPE: Broken pipe.
* @G_IO_CHANNEL_ERROR_FAILED: Some other error.
*
* Error codes returned by #GIOChannel operations.
**/
GQuark GQuark
g_io_channel_error_quark (void) g_io_channel_error_quark (void)
{ {

36
glib/giounix.c
View File

@ -569,6 +569,32 @@ g_io_channel_new_file (const gchar *filename,
return channel; return channel;
} }
/**
* g_io_channel_unix_new:
* @fd: a file descriptor.
* @Returns: a new #GIOChannel.
*
* 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.
*
* 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.
**/
GIOChannel * GIOChannel *
g_io_channel_unix_new (gint fd) g_io_channel_unix_new (gint fd)
{ {
@ -598,6 +624,16 @@ g_io_channel_unix_new (gint fd)
return channel; return channel;
} }
/**
* g_io_channel_unix_get_fd:
* @channel: a #GIOChannel, created with g_io_channel_unix_new().
* @Returns: the file descriptor of the #GIOChannel.
*
* Returns the file descriptor of the #GIOChannel.
*
* On Windows this function returns the file descriptor or socket of
* the #GIOChannel.
**/
gint gint
g_io_channel_unix_get_fd (GIOChannel *channel) g_io_channel_unix_get_fd (GIOChannel *channel)
{ {

52
glib/giowin32.c
View File

@ -1973,6 +1973,16 @@ static GIOFuncs win32_channel_sock_funcs = {
g_io_win32_sock_get_flags, g_io_win32_sock_get_flags,
}; };
/**
* g_io_channel_win32_new_messages:
* @hwnd: a window handle.
* @Returns: a new #GIOChannel.
*
* 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.
**/
GIOChannel * GIOChannel *
#if GLIB_SIZEOF_VOID_P == 8 #if GLIB_SIZEOF_VOID_P == 8
g_io_channel_win32_new_messages (gsize hwnd) g_io_channel_win32_new_messages (gsize hwnd)
@ -2036,6 +2046,34 @@ g_io_channel_win32_new_fd_internal (gint fd,
return channel; return channel;
} }
/**
* g_io_channel_win32_new_fd:
* @fd: a C library file descriptor.
* @Returns: a new #GIOChannel.
*
* 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.
**/
GIOChannel * GIOChannel *
g_io_channel_win32_new_fd (gint fd) g_io_channel_win32_new_fd (gint fd)
{ {
@ -2058,6 +2096,20 @@ g_io_channel_win32_get_fd (GIOChannel *channel)
return win32_channel->fd; return win32_channel->fd;
} }
/**
* g_io_channel_win32_new_socket:
* @socket: a Winsock socket
* @Returns: a new #GIOChannel
*
* 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.
**/
GIOChannel * GIOChannel *
g_io_channel_win32_new_socket (int socket) g_io_channel_win32_new_socket (int socket)
{ {