The "ch" Package

These routines are meant to provide an alternative to the standard C library streams (FILE *). The channel package provides far more powerful channels (streams), especially when transferring data over connections.

Library: karma
Link With: -lkarma

Functions

ch_open_file	Open a file.
ch_map_disc	Map a disc file.
ch_open_connection	Open a connection.
ch_open_memory	Open a memory channel.
ch_accept_on_dock	Accept a connection.
ch_alloc_port	Allocate a port.
ch_close	Close a channel.
ch_flush	Flush the write buffer of a channel object.
ch_read	Read from a channel.
ch_write	Write to a channel.
ch_close_all_channels	Close all open channels.
ch_seek	Move read/write pointer.
ch_get_bytes_readable	Count unread bytes.
ch_get_descriptor	Get the file descriptor associated with a channel.
ch_open_stdin	Create starndard input channel.
ch_test_for_io	Test if I/O possible on channel.
ch_test_for_asynchronous	Test if a channel object is an asynchronous channel.
ch_test_for_connection	Test if a channel object is a connection channel.
ch_test_for_local_connection	Test if a connection channel object is a local connection.
ch_attach_to_asynchronous_descriptor	Create a channel object from an asynchronous descriptor.
ch_test_for_mmap	Test if a channel object is a memory mapped disc channel.
ch_tell	Get the read and write pointers for a channel.
ch_get_mmap_addr	Get memory mapped address.
ch_get_mmap_access_count	Get memory mapped access count.
ch_register_converter	Register channel converter function.
ch_unregister_converter	Unregister converter.
ch_create_pipe	Create a pipe.
ch_create_sink	Create data sink.
ch_tap_io_events	Register I/O tap function.
ch_open_and_fill_memory	Create and fill memory channel.
ch_gets	Read a line from a channel.
ch_getl	Read a line from a channel.
ch_puts	Write a character string to a channel.
ch_drain	Drain bytes from a channel.
ch_printf	Write formatted output to a channel.

Prototype Functions

CH_PROTO_size_func	Get number of bytes readable.
CH_PROTO_read_func	Read bytes.
CH_PROTO_write_func	Write bytes.
CH_PROTO_flush_func	Flush.
CH_PROTO_close_func	Close.
CH_PROTO_tap_func	Tap I/O callback.

Tables

CH_FILE_MODES	List of defined file modes
CH_MAP_CONTROLS	List of mapping control values

Functions

Channel ch_open_file (CONST char *filename, CONST char *type)

This routine will open a file channel. The file may be a regular disc file, a named FIFO, a character special device, a Unix domain connection or a TCP/IP connection. The channel may be later tested to determine what the true channel type is by calling routines such as: ch_test_for_asynchronous and ch_test_for_io.

Parameters:

filename : The pathname of the file to open. This parameter has the same meaning as the first parameter to open(2). Filenames of the form "//tcpIP/:" indicate a connection to a TCP/IP port on host hostname with raw port number port is requested.
type : The mode of the file. See CH_FILE_MODES for a list of allowable modes.

Returns: A channel object on success, else NULL.
Multithreading Level: Unsafe
Note:

For character special files and named FIFOs, these modes degenerate into read-write, read-only and write-only.

Channel ch_map_disc (CONST char *filename, unsigned int option, flag writeable, flag update_on_write)

This routine will open a memory channel with the memory pages being mapped from a disc file. The disc file must already exist.

Parameters:

filename : The pathname of the file to open.
option : Control value which determines whether the channel is opened as an ordinary disc file or is mapped. See CH_MAP_CONTROLS for legal values. If the file is not mapped then the routine will attempt to open an ordinary disc channel. If the file is opened as a disc channel the access mode is: "r".
writable : If the mapped pages are to be writeable, this must be TRUE. If this is FALSE and the memory pages are written to, a segmentation fault occurs.
update_on_write : If the disc file should be updated when the memory pages are written to, this must be TRUE. If this is FALSE, then a write to a memory page causes the page to be copied into swap space and the process retains a private copy of the page from this point on.

Returns: A channel object on success, else NULL.
Multithreading Level: Unsafe
Note:

If update_on_write is FALSE and writeable is TRUE, then some systems require the allocation of normal virtual memory equal to the size of the disc file at the time of mapping, while others will dynamically allocate memory from swap space as pages are written into. In the latter case, some systems will cause a segmentation fault if swap space is exhausted, while other systems wait for space to be freed.
The channel may be queried to determine if it has been memory mapped using the call ch_test_for_mmap.

Channel ch_open_connection (unsigned long host_addr, unsigned int port_number)

This routine will open a full-duplex connection channel to a server running on another host machine.

Parameters:

host_addr : The Internet address of the host machine. If this is 0 the connection is made to a server running on the same machine using the most efficient transport available.
port_number : The port number to connect to. This should not be confused with Internet port numbers.

Returns: A channel object on success, else NULL.
Multithreading Level: Unsafe
Note:

The use of this routine is not recommended, see the conn package for more powerful functionality.

Channel ch_open_memory (char *buffer, unsigned int size)

This routine will open a memory channel. A memory channel behaves like a disc channel with a limited (specified) file (device) size. Data is undefined when reading before writing has occurred.

Parameters:

buffer : The buffer to use. If this is NULL, the routine will allocate a buffer of the specified size which is automatically deallocated upon closure of the channel.
size : The size of the buffer to allocate.

Returns: A channel object on success, else NULL.
Multithreading Level: Unsafe

Channel ch_accept_on_dock (Channel dock, unsigned long *addr)

This routine will open a full-duplex connection channel to the first connection on a waiting dock.

Parameters:

dock : The dock.
addr : The address of the host connecting to the dock will be written here.

Returns: A channel object on success, else NULL.
Multithreading Level: Unsafe

Channel * ch_alloc_port (unsigned int *port_number, unsigned int retries, unsigned int *num_docks)

This routine will allocate a Karma port for the module so that it can operate as a server (able to receive network connections).

Parameters:

port_number : A pointer to the port number to allocate. The routine will write the actual port number allocated to this address. This must point to an address which lies on an int boundary.
retries : The number of succsessive port numbers to attempt to allocate before giving up. If this is 0, then the routine will give up immediately if the specified port number is in use.
num_docks : The routine will create a number of docks for one port. Each dock is an alternative access point for other modules to connect to this port. The number of docks allocated will be written here. This must point to an address which lies on an int boundary.

Returns: A pointer to an array of channel docks on success, else NULL.
Multithreading Level: Unsafe
Note:

The close-on-exec flags of the docks are set such that the docks will close on a call to execve(2V).
The docks are placed into blocking mode.

flag ch_close (Channel channel)

This routine will close a channel object. The write buffer will be flushed prior to closure.

Parameters:

channel : The channel object.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

flag ch_flush (Channel channel)

Flush the write buffer of a channel object.

Parameters:

channel : The channel object.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

unsigned int ch_read (Channel channel, char *buffer, unsigned int length)

This routine will read a number of bytes from a channel and places them into a buffer.

Parameters:

channel : The channel object.
buffer : The buffer to write the data into.
length : The number of bytes to write into the buffer.

Returns: The number of bytes read.
Multithreading Level: Unsafe
Note:

If the channel is a connection and the number of bytes readable from the connection is equal to or more than length the routine will NOT block.

unsigned int ch_write (Channel channel, CONST char *buffer,unsigned int length)

This routine will write a number of bytes from a buffer to a channel.

Parameters:

channel : The channel object.
buffer : The buffer to read the data from.
length : The number of bytes to read from the buffer and write to the channel.

Returns: The number of bytes written.
Multithreading Level: Unsafe

void ch_close_all_channels ()

The routine will close all open channels. The routine is meant to be called from the exit(3) function.

Parameters:

Returns: Nothing.
Multithreading Level: Unsafe

flag ch_seek (Channel channel, unsigned long position)

This routine will position the read and write pointers for a channel.

Parameters:

channel : The channel object.
position : The position (relative to the start of the channel data).

Returns: TRUE on success, else FALSE (indicating a seek request beyond the channel limits)
Multithreading Level: Unsafe
Note:

This routine cannot be used for connection channels.

int ch_get_bytes_readable (Channel channel)

This routine will determine the number of bytes currently readable on a connection channel. This is equal to the maximum number of bytes that could be read from the channel at this time without blocking waiting for more input to be transmitted from the other end of the connection.

Parameters:

channel : The channel object.

Returns: The number of bytes readable on success, else -1 indicating error
Multithreading Level: Unsafe

int ch_get_descriptor (Channel channel)

Get the file descriptor associated with a channel.

Parameters:

channel : The channel object.

Returns: The file descriptor on success, else -1 indicating error.
Multithreading Level: Unsafe

void ch_open_stdin ()

This routine will create a channel object for the standard input descriptor (typically 0 on Unix systems).

Parameters:

Returns: Nothing.
Multithreading Level: Unsafe
Note:

The standard input channel will be written to the external variable ch_stdin.

flag ch_test_for_io (Channel channel)

This routine will test if a channel object is capable of supporting reading and writing operations. Most channels fall under this category. The notable exceptions are the dock channel and channels created by a call to ch_attach_to_asynchronous_descriptor.

Parameters:

channel : The channel object.

Returns: TRUE if the channel is capable of reading and writing, else FALSE
Multithreading Level: Unsafe

flag ch_test_for_asynchronous (Channel channel)

This routine will test if a channel object is an asynchronous channel, i.e. a character special file, named FIFO, connection, a dock channel or one created by a call to ch_attach_to_asynchronous_descriptor or ch_create_pipe.

Parameters:

channel : The channel object.

Returns: TRUE if the channel is asynchronous, else FALSE.
Multithreading Level: Unsafe

flag ch_test_for_connection (Channel channel)

Test if a channel object is a connection channel.

Parameters:

channel : The channel object.

Returns: TRUE if the channel object is a connection, else FALSE.
Multithreading Level: Unsafe

flag ch_test_for_local_connection (Channel channel)

Test if a connection channel object is a local connection.

Parameters:

channel : The channel object.

Returns: TRUE if the channel object is a local connection, else FALSE.
Multithreading Level: Unsafe

Channel ch_attach_to_asynchronous_descriptor (int fd)

Create a channel object from an asynchronous descriptor.

Parameters:

fd : The descriptor.

Returns: A channel object on success, else NULL.
Multithreading Level: Unsafe

flag ch_test_for_mmap (Channel channel)

Test if a channel object is a memory mapped disc channel.

Parameters:

channel : The channel object.

Returns: TRUE if the channel object is memory mapped, else FALSE.
Multithreading Level: Unsafe

flag ch_tell (Channel channel, unsigned long *read_pos, unsigned long *write_pos)

Get the read and write pointers for a channel.

Parameters:

channel : The channel object.
read_pos : The read position (relative to the start of the channel data) will be written here.
write_pos : The write position (relative to the start of the channel data) will be written here.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

char * ch_get_mmap_addr (Channel channel)

This routine will get the starting address of the data for a memory mapped disc channel. The channel MUST be a memory mapped disc channel.

Parameters:

channel : The channel object.

Returns: The address of the memory mapped data.
Multithreading Level: Unsafe
Note:

If the memory mapped address space is read-only, any attempt to write to this address space will cause a segmentation fault.

unsigned int ch_get_mmap_access_count (Channel channel)

This routine will get the number of times a memory mapped disc channel has been queried for the mapping address using ch_get_mmap_addr

Parameters:

channel : The channel object.

Returns: The number of address queries.
Multithreading Level: Unsafe
Note:

The channel MUST be a memory mapped disc channel.

ChConverter ch_register_converter (Channel channel, unsigned int (*size_func) (), unsigned int (*read_func) (), unsigned int (*write_func) (), flag (*flush_func) (), void (*close_func) (), void *info)

This routine will register a set of converter functions which will be called when channel data is read or written. The operation of these routines is transparent. Converter functions are useful for automatic compression and encryption of data streams. It is permissable to register multiple converter functions with a channel. Converter functions are pushed down from the top (application) level. In other words, the last converter functions registered are called first.

Parameters:

channel : The channel object.
size_func : The function which will determine (approximately) how many bytes would be returned by the read_func. This routine is called when ch_get_bytes_readable is called for the channel. The prototype function is CH_PROTO_size_func.
read_func : The function which will convert data when reading. The prototype function is CH_PROTO_read_func.
write_func : The function which will convert data when writing. If this is NULL, no write conversion is performed. The prototype function is CH_PROTO_write_func.
flush_func : The function which is called when the channel is to be flushed The prototype function is CH_PROTO_flush_func.
close_func : The function which is called when the channel is closed. If this is NULL, no special action is taken upon channel closure. The prototype function is CH_PROTO_close_func.

Returns: A ChConverter object on success (which may be used in a call to ch_unregister_converter), else NULL.
Multithreading Level: Unsafe
Note:

Converters may only be registered for disc, connection, character special and FIFO channels (ie. those opened with ch_open_file), and impose restrictions on channel operations (ie. ch_seek cannot be called).
Converter functions are expected to provide their own buffering as needed.
The flush_func will be called prior to the close_func upon channel closure.
will be called prior to the close_func upon The sequence of events when the application level calls ch_write is: The last registered write converter is popped from the stack and called. This write converter may buffer some or all of the data. It may call ch_write with some converted data. When ch_write is called from a write converter, the next last registered write converter is popped from the stack and called. This sequence is continued until data is actually transferred into the channel write buffer. A similar sequence of events occurs when ch_read is called. The sequence of events when the application level calls ch_flush is: The last registered flush converter is popped from the stack and called. This flush converter MUST write all data in it's buffer using ch_write When ch_write is called from a flush converter, the next last registered write converter is popped from the stack and called. When the last registered flush converter returns, the sequence is repeated with the next last flush converter, and so on, until all data in all write buffers is flushed, including the channel write buffer.

void ch_unregister_converter (ChConverter converter)

This routine will unregister a set of converter functions previously registered with ch_register_converter. This will cause the registered flush and close functions to be called.

Parameters:

converter : The ChConverter object.

Returns: Nothing.
Multithreading Level: Unsafe

flag ch_create_pipe (Channel *read_ch, Channel *write_ch)

This routine will create an un-named pipe (see pipe(2) for details on un-named pipes).

Parameters:

read_ch : The channel corresponding to the read end of the pipe will be written here.
write_ch : The channel corresponding to the write end of the pipe will be written here.

Returns: TRUE on success, else FALSE and sets errno with the error code.
Multithreading Level: Unsafe

Channel ch_create_sink ()

This routine will create a data sink channel. All writes to the channel are discarded (and reported as having succeeded) and all reads return an End-Of-File condition. Read and write operations modify the absolute read and write pointers (obtainable with ch_tell) as expected.

Parameters:

Returns: The channel object on succes, else NULL.
Multithreading Level: Unsafe

KCallbackFunc ch_tap_io_events (void (*tap_func) (), void *info)

This routine will tap I/O events by calling a registered function whenever data is transferred to/from a disc, connection or FIFO channel. Reading and writing memory mapped or memory channels does *not* constitute an I/O event. Multiple tap functions may be registered, with the first one registered being the first one called upon a channel I/O event.

Parameters:

tap_func : The function which is called when I/O occurs. The prototype function is CH_PROTO_tap_func.
info : The arbitrary information passed to the tap function. This may be NULL.

Returns: A KCallbackFunc. On failure, the process aborts.
Multithreading Level: Unsafe

Channel ch_open_and_fill_memory (char **strings)

This routine will open a memory channel with sufficient space to contain a list of strings.

Parameters:

strings : The NULL terminated array of string pointers. The strings are written with a NEWLINE character to terminate the string. The NULL terminator character is not written.

Returns: A channel object on success, else NULL.
Multithreading Level: Unsafe

flag ch_gets (Channel channel, char *buffer, unsigned int length)

This routine will read a character string from a channel into a buffer.

Parameters:

channel : The channel object.
buffer : The buffer to write the data into. The routine will write a NULL terminator character at the end of the string.
length : The length of the buffer. If the buffer is not large enough to contain the string, then the remainder of the string is NOT read. See also the ch_getl routine.

Returns: TRUE on success, else FALSE (indicating end-of-file was encountered).
Multithreading Level: Unsafe
Note:

The newline chanacter '\n' is NOT copied into the buffer.

flag ch_getl (Channel channel, char *buffer, unsigned int length)

This routine will read a character string from a channel into a buffer.

Parameters:

channel : The channel object.
buffer : The buffer to write the data into. The routine will write a NULL terminator character at the end of the string.
length : The length of the buffer. If the buffer is not large enough to contain the string, then the remainder of the string (including the newline character) is read in and discarded and a warning message is displayed. See also the ch_gets routine.

Returns: TRUE on success, else FALSE (indicating end-of-file was encountered).
Multithreading Level: Unsafe
Note:

The newline chanacter '\n' is NOT copied into the buffer.

flag ch_puts (Channel channel, CONST char *string, flag newline)

Write a character string to a channel.

Parameters:

channel : The channel object.
string : The string.
newline : If TRUE, the routine will write a NEWLINE character after writing the string.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe
Note:

The routine will not write the NULL terminator character.

unsigned int ch_drain (Channel channel, unsigned int length)

This routine will drain (read) a specified number of bytes from a channel, ignoring the data.

Parameters:

channel : The Channel object.
length : The number of bytes to drain.

Returns: The number of bytes drained.
Multithreading Level: Unsafe

flag ch_printf (Channel channel, CONST char *format, ...)

Write formatted output to a channel.

Parameters:

channel : The channel object.
format : The format string. See fprintf.
... : The optional parameters. See fprintf.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

Prototype Functions

unsigned int CH_PROTO_size_func (Channel channel, void **info)

This routine will determine the approximate number of bytes that the read_func will return.

Parameters:

channel : The channel object.
info : A pointer to the arbitrary information pointer. This may be modified

Returns: The number of bytes the read_func will return.
Multithreading Level: Unsafe

unsigned int CH_PROTO_read_func (Channel channel, char *buffer, unsigned int length, void **info)

This routine will convert bytes being read from a channel object.

Parameters:

channel : The channel object. It is permissable for the routine to call ch_read with this channel. If this is done, this function will be bypassed.
buffer : The buffer to write the data into.
length : The number of bytes to write into the buffer.
info : A pointer to the arbitrary information pointer. This may be modified

Returns: The number of bytes actually written to the buffer.
Multithreading Level: Unsafe

unsigned int CH_PROTO_write_func (Channel channel, char *buffer, unsigned int length, void **info)

This routine will convert bytes being written to a channel object

Parameters:

channel : The channel object. It is permissable for the routine to call ch_write with this channel. If this is done, this function will be bypassed.
buffer : The buffer to read the data from. The contents of this buffer may be modified if needed.
length : The number of bytes to read from the buffer.
info : A pointer to the arbitrary information pointer. This may be modified

Returns: The number of bytes read from the buffer.
Multithreading Level: Unsafe

flag CH_PROTO_flush_func (Channel channel, void **info)

This routine will process a flush request for a channel object.

Parameters:

channel : The channel object. It is permissable for the routine to call ch_flush with this channel. If this is done, this function will be bypassed.
info : A pointer to the arbitrary information pointer. This may be modified

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

void CH_PROTO_close_func (void *info)

This routine is called when a channel is closed.

Parameters:

info : The arbitrary information pointer.

Returns: Nothing.
Multithreading Level: Unsafe

void CH_PROTO_tap_func (void *info)

This routine is called when I/O occurs.

Parameters:

info : The arbitrary information pointer.

Returns: Nothing.
Multithreading Level: Unsafe

Tables

CH_FILE_MODES

Mode Meaning
"r" open for reading
"w" open (truncate) or create for writing
"a" open or create for writing at end of file (append)
"r+" open for update (reading and writing)
"w+" open for reading and writing after truncation
"a+" open or create for update (reading and writing) at EOF
"W" open for writing

CH_MAP_CONTROLS

Control Meaning
K_CH_MAP_NEVER Never map
K_CH_MAP_LARGE_LOCAL Map if local filesystem and file size > 1MB
K_CH_MAP_LOCAL Map if local filesystem
K_CH_MAP_LARGE Map if file over 1 MByte
K_CH_MAP_IF_AVAILABLE Map if operating system supports it
K_CH_MAP_ALWAYS Always map, fail if not supported.

Contact: Richard Gooch
Web Development: Ariel Internet Services

Mode	Meaning
"r"	open for reading
"w"	open (truncate) or create for writing
"a"	open or create for writing at end of file (append)
"r+"	open for update (reading and writing)
"w+"	open for reading and writing after truncation
"a+"	open or create for update (reading and writing) at EOF
"W"	open for writing

Control	Meaning
K_CH_MAP_NEVER	Never map
K_CH_MAP_LARGE_LOCAL	Map if local filesystem and file size > 1MB
K_CH_MAP_LOCAL	Map if local filesystem
K_CH_MAP_LARGE	Map if file over 1 MByte
K_CH_MAP_IF_AVAILABLE	Map if operating system supports it
K_CH_MAP_ALWAYS	Always map, fail if not supported.