GI.GLib.Structs.IOChannel

The GIOChannel data type aims to provide a portable method for using file descriptors, pipes, and sockets, and integrating them into the main event loop (see [structgLib.MainContext]). Currently, full support is available on UNIX platforms; support for Windows is only partially complete.

To create a new GIOChannel on UNIX systems use iOChannelUnixNew. This works for plain file descriptors, pipes and sockets. Alternatively, a channel can be created for a file in a system independent manner using iOChannelNewFile.

Once a GIOChannel has been created, it can be used in a generic manner with the functions iOChannelReadChars, iOChannelWriteChars, iOChannelSeekPosition, and iOChannelShutdown.

To add a GIOChannel to the main event loop, use ioAddWatch or GLib.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. iOChannelRef and iOChannelUnref 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 iOChannelNewFile.) Using ioAddWatch or GLib.io_add_watch_full increments a channel’s reference count.

The new functions iOChannelReadChars, iOChannelReadLine, IOChannel.read_line_string(), iOChannelReadToEnd, iOChannelWriteChars, iOChannelSeekPosition, and iOChannelFlush should not be mixed with the deprecated functions iOChannelRead, iOChannelWrite, and iOChannelSeek on the same channel.

Exported types

newtype IOChannel

Memory-managed wrapper type.

Constructors

IOChannel (ManagedPtr IOChannel)

Instances

Eq IOChannel

Defined in GI.GLib.Structs.IOChannel

Methods

(==) :: IOChannel -> IOChannel -> Bool

(/=) :: IOChannel -> IOChannel -> Bool

GBoxed IOChannel

Defined in GI.GLib.Structs.IOChannel

ManagedPtrNewtype IOChannel

Defined in GI.GLib.Structs.IOChannel

Methods

toManagedPtr :: IOChannel -> ManagedPtr IOChannel

TypedObject IOChannel

Defined in GI.GLib.Structs.IOChannel

Methods

glibType :: IO GType

HasParentTypes IOChannel

Defined in GI.GLib.Structs.IOChannel

tag ~ 'AttrSet => Constructible IOChannel tag

Defined in GI.GLib.Structs.IOChannel

Methods

new :: MonadIO m => (ManagedPtr IOChannel -> IOChannel) -> [AttrOp IOChannel tag] -> m IOChannel

IsGValue (Maybe IOChannel)

Convert IOChannel to and from GValue. See toGValue and fromGValue.

Defined in GI.GLib.Structs.IOChannel

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe IOChannel -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe IOChannel)

type ParentTypes IOChannel

Defined in GI.GLib.Structs.IOChannel

type ParentTypes IOChannel = '[] :: [Type]

newZeroIOChannel :: MonadIO m => m IOChannel

Construct a IOChannel struct initialized to zero.

Methods

Click to display all available methods, including inherited ones

Methods

close, flush, init, read, readChars, readLine, readToEnd, readUnichar, ref, seek, seekPosition, shutdown, unixGetFd, unref, write, writeChars, writeUnichar.

Getters

getBufferCondition, getBufferSize, getBuffered, getCloseOnUnref, getEncoding, getFlags, getLineTerm.

Setters

setBufferSize, setBuffered, setCloseOnUnref, setEncoding, setFlags, setLineTerm.

close

iOChannelClose

Arguments

:: (HasCallStack, MonadIO m)

=> IOChannel

channel: A IOChannel

-> m ()

Deprecated: (Since version 2.2)Use iOChannelShutdown 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 iOChannelUnref.

errorFromErrno

iOChannelErrorFromErrno

Arguments

:: (HasCallStack, MonadIO m)

=> Int32

en: an errno error number, e.g. EINVAL

-> m IOChannelError

Returns: a IOChannelError error number, e.g. IOChannelErrorInval.

Converts an errno error number to a IOChannelError.

errorQuark

iOChannelErrorQuark :: (HasCallStack, MonadIO m) => m Word32

No description available in the introspection data.

flush

iOChannelFlush

Arguments

:: (HasCallStack, MonadIO m)

=> IOChannel

channel: a IOChannel

-> m IOStatus

Returns: the status of the operation: One of IOStatusNormal, IOStatusAgain, or IOStatusError. (Can throw GError)

Flushes the write buffer for the GIOChannel.

getBufferCondition

iOChannelGetBufferCondition

Arguments

:: (HasCallStack, MonadIO m)

=> IOChannel

channel: A IOChannel

-> m [IOCondition]

Returns: A IOCondition

This function returns a IOCondition depending on whether there is data to be read/space to write data in the internal buffers in the IOChannel. Only the flags IOConditionIn and IOConditionOut may be set.

getBufferSize

iOChannelGetBufferSize

Arguments

:: (HasCallStack, MonadIO m)

=> IOChannel

channel: a IOChannel

-> m CSize

Returns: the size of the buffer.

Gets the buffer size.

getBuffered

iOChannelGetBuffered

Arguments

:: (HasCallStack, MonadIO m)

=> IOChannel

channel: a IOChannel

-> m Bool

Returns: True if the channel is buffered.

Returns whether channel is buffered.

getCloseOnUnref

iOChannelGetCloseOnUnref

Arguments

:: (HasCallStack, MonadIO m)

=> IOChannel

channel: a IOChannel.

-> m Bool

Returns: True if the channel will be closed, False otherwise.

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.

getEncoding

iOChannelGetEncoding

Arguments

:: (HasCallStack, MonadIO m)

=> IOChannel

channel: a IOChannel

-> m Text

Returns: A string containing the encoding, this string is owned by GLib and must not be freed.

Gets the encoding for the input/output of the channel. The internal encoding is always UTF-8. The encoding Nothing makes the channel safe for binary data.

getFlags

iOChannelGetFlags

Arguments

:: (HasCallStack, MonadIO m)

=> IOChannel

channel: a IOChannel

-> m [IOFlags]

Returns: the flags which are set on the channel

Gets the current flags for a IOChannel, including read-only flags such as IOFlagsIsReadable.

The values of the flags IOFlagsIsReadable and IOFlagsIsWritable 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 iOChannelGetFlags to update the internal values of these flags.

getLineTerm

iOChannelGetLineTerm

Arguments

:: (HasCallStack, MonadIO m)

=> IOChannel

channel: a IOChannel

-> m (Text, Int32)

Returns: The line termination string. This value is owned by GLib and must not be freed.

This returns the string that IOChannel uses to determine where in the file a line break occurs. A value of Nothing indicates autodetection.

init

iOChannelInit

Arguments

:: (HasCallStack, MonadIO m)

=> IOChannel

channel: a IOChannel

-> m ()

Initializes a IOChannel struct.

This is called by each of the above functions when creating a IOChannel, and so is not often needed by the application programmer (unless you are creating a new type of IOChannel).

newFile

iOChannelNewFile

Arguments

:: (HasCallStack, MonadIO m)

=> [Char]

filename: A string containing the name of a file

-> Text

mode: One of "r", "w", "a", "r+", "w+", "a+". These have the same meaning as in fopen()

-> m IOChannel

Returns: A IOChannel on success, Nothing on failure. (Can throw GError)

Open a file filename as a IOChannel using mode mode. This channel will be closed when the last reference to it is dropped, so there is no need to call iOChannelClose (though doing so will not cause problems, as long as no attempt is made to access the channel after it is closed).

read

iOChannelRead

Arguments

:: (HasCallStack, MonadIO m)

=> IOChannel

channel: a IOChannel

-> Text

buf: a buffer to read the data into (which should be at least count bytes long)

-> CSize

count: the number of bytes to read from the IOChannel

-> CSize

bytesRead: returns the number of bytes actually read

-> m IOError

Returns: IOErrorNone if the operation was successful.

Deprecated: (Since version 2.2)Use iOChannelReadChars instead.

Reads data from a IOChannel.

readChars

iOChannelReadChars

Arguments

:: (HasCallStack, MonadIO m)

=> IOChannel

channel: a IOChannel

-> ByteString

buf: a buffer to read data into

-> m (IOStatus, ByteString, CSize)

Returns: the status of the operation. (Can throw GError)

Replacement for iOChannelRead with the new API.

readLine

iOChannelReadLine

Arguments

:: (HasCallStack, MonadIO m)

=> IOChannel

channel: a IOChannel

-> m (IOStatus, Text, CSize, CSize)

Returns: the status of the operation. (Can throw GError)

Reads a line, including the terminating character(s), from a IOChannel into a newly-allocated string. strReturn will contain allocated memory if the return is IOStatusNormal.

readToEnd

iOChannelReadToEnd

Arguments

:: (HasCallStack, MonadIO m)

=> IOChannel

channel: a IOChannel

-> m (IOStatus, ByteString)

Returns: IOStatusNormal on success. This function never returns IOStatusEof. (Can throw GError)

Reads all the remaining data from the file.

readUnichar

iOChannelReadUnichar

Arguments

:: (HasCallStack, MonadIO m)

=> IOChannel

channel: a IOChannel

-> m (IOStatus, Char)

Returns: a IOStatus (Can throw GError)

Reads a Unicode character from channel. This function cannot be called on a channel with Nothing encoding.

ref

iOChannelRef

Arguments

:: (HasCallStack, MonadIO m)

=> IOChannel

channel: a IOChannel

-> m IOChannel

Returns: the channel that was passed in (since 2.6)

Increments the reference count of a IOChannel.

seek

iOChannelSeek

Arguments

:: (HasCallStack, MonadIO m)

=> IOChannel

channel: a IOChannel

-> Int64

offset: an offset, in bytes, which is added to the position specified by type

-> SeekType

type: the position in the file, which can be SeekTypeCur (the current position), SeekTypeSet (the start of the file), or SeekTypeEnd (the end of the file)

-> m IOError

Returns: IOErrorNone if the operation was successful.

Deprecated: (Since version 2.2)Use iOChannelSeekPosition instead.

Sets the current position in the IOChannel, similar to the standard library function fseek().

seekPosition

iOChannelSeekPosition

Arguments

:: (HasCallStack, MonadIO m)

=> IOChannel

channel: a IOChannel

-> Int64

offset: The offset in bytes from the position specified by type

-> SeekType

type: a SeekType. The type SeekTypeCur is only allowed in those cases where a call to g_io_channel_set_encoding () is allowed. See the documentation for g_io_channel_set_encoding () for details.

-> m IOStatus

Returns: the status of the operation. (Can throw GError)

Replacement for iOChannelSeek with the new API.

setBufferSize

iOChannelSetBufferSize

Arguments

:: (HasCallStack, MonadIO m)

=> IOChannel

channel: a IOChannel

-> CSize

size: the size of the buffer, or 0 to let GLib pick a good size

-> m ()

Sets the buffer size.

setBuffered

iOChannelSetBuffered

Arguments

:: (HasCallStack, MonadIO m)

=> IOChannel

channel: a IOChannel

-> Bool

buffered: whether to set the channel buffered or unbuffered

-> m ()

The buffering state can only be set if the channel's encoding is Nothing. 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 IOStatusEof 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 SeekTypeCur 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.

setCloseOnUnref

iOChannelSetCloseOnUnref

Arguments

:: (HasCallStack, MonadIO m)

=> IOChannel

channel: a IOChannel

-> Bool

doClose: Whether to close the channel on the final unref of the GIOChannel data structure.

-> m ()

Whether to close the channel on the final unref of the IOChannel 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 IOChannel is dropped.

setEncoding

iOChannelSetEncoding

Arguments

:: (HasCallStack, MonadIO m)

=> IOChannel

channel: a IOChannel

-> Maybe Text

encoding: the encoding type

-> m IOStatus

Returns: IOStatusNormal if the encoding was successfully set (Can throw GError)

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 Nothing 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 iOChannelSeekPosition. (This flushes all the internal buffers.)
• The current encoding is Nothing or UTF-8.
• One of the (new API) read functions has just returned IOStatusEof (or, in the case of iOChannelReadToEnd, IOStatusNormal).
• One of the functions iOChannelReadChars or iOChannelReadUnichar has returned IOStatusAgain or IOStatusError. This may be useful in the case of ConvertErrorIllegalSequence. Returning one of these statuses from iOChannelReadLine, g_io_channel_read_line_string(), or iOChannelReadToEnd does not guarantee that the encoding can be changed.

Channels which do not meet one of the above conditions cannot call iOChannelSeekPosition with an offset of SeekTypeCur, and, if they are "seekable", cannot call iOChannelWriteChars after calling one of the API "read" functions.

setFlags

iOChannelSetFlags

Arguments

:: (HasCallStack, MonadIO m)

=> IOChannel

channel: a IOChannel

-> [IOFlags]

flags: the flags to set on the IO channel

-> m IOStatus

Returns: the status of the operation. (Can throw GError)

Sets the (writeable) flags in channel to (flags & IOFlagsSetMask).

setLineTerm

iOChannelSetLineTerm

Arguments

:: (HasCallStack, MonadIO m)

=> IOChannel

channel: a IOChannel

-> Maybe Text

lineTerm: The line termination string. Use Nothing for autodetect. Autodetection breaks on "\n", "\r\n", "\r", "\0", and the Unicode paragraph separator. Autodetection should not be used for anything other than file-based channels.

-> Int32

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.

-> m ()

This sets the string that IOChannel uses to determine where in the file a line break occurs.

shutdown

iOChannelShutdown

Arguments

:: (HasCallStack, MonadIO m)

=> IOChannel

channel: a IOChannel

-> Bool

flush: if True, flush pending

-> m IOStatus

Returns: the status of the operation. (Can throw GError)

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 iOChannelUnref.

unixGetFd

iOChannelUnixGetFd

Arguments

:: (HasCallStack, MonadIO m)

=> IOChannel

channel: a IOChannel, created with iOChannelUnixNew.

-> m Int32

Returns: the file descriptor of the IOChannel.

Returns the file descriptor of the IOChannel.

On Windows this function returns the file descriptor or socket of the IOChannel.

unixNew

iOChannelUnixNew

Arguments

:: (HasCallStack, MonadIO m)

=> Int32

fd: a file descriptor.

-> m IOChannel

Returns: a new IOChannel.

Creates a new IOChannel given a file descriptor. On UNIX systems this works for plain files, pipes, and sockets.

The returned IOChannel has a reference count of 1.

The default encoding for IOChannel 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 getCharset) with the iOChannelSetEncoding function. By default, the fd passed will not be closed when the final reference to the IOChannel data structure is dropped.

If you want to read raw binary data without interpretation, then call the iOChannelSetEncoding function with Nothing 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.

unref

iOChannelUnref

Arguments

:: (HasCallStack, MonadIO m)

=> IOChannel

channel: a IOChannel

-> m ()

Decrements the reference count of a IOChannel.

write

iOChannelWrite

Arguments

:: (HasCallStack, MonadIO m)

=> IOChannel

channel: a IOChannel

-> Text

buf: the buffer containing the data to write

-> CSize

count: the number of bytes to write

-> CSize

bytesWritten: the number of bytes actually written

-> m IOError

Returns: IOErrorNone if the operation was successful.

Deprecated: (Since version 2.2)Use iOChannelWriteChars instead.

Writes data to a IOChannel.

writeChars

iOChannelWriteChars

Arguments

:: (HasCallStack, MonadIO m)

=> IOChannel

channel: a IOChannel

-> Ptr Word8

buf: a buffer to write data from

-> Int64

count: the size of the buffer. If -1, the buffer is taken to be a nul-terminated string.

-> m (IOStatus, CSize)

Returns: the status of the operation. (Can throw GError)

Replacement for iOChannelWrite with the new API.

On seekable channels with encodings other than Nothing 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 ().

writeUnichar

iOChannelWriteUnichar

Arguments

:: (HasCallStack, MonadIO m)

=> IOChannel

channel: a IOChannel

-> Char

thechar: a character

-> m IOStatus

Returns: a IOStatus (Can throw GError)

Writes a Unicode character to channel. This function cannot be called on a channel with Nothing encoding.