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_fileOpen a file.
ch_map_discMap a disc file.
ch_open_connectionOpen a connection.
ch_open_memoryOpen a memory channel.
ch_accept_on_dockAccept a connection.
ch_alloc_portAllocate a port.
ch_closeClose a channel.
ch_flushFlush the write buffer of a channel object.
ch_readRead from a channel.
ch_writeWrite to a channel.
ch_close_all_channelsClose all open channels.
ch_seekMove read/write pointer.
ch_get_bytes_readableCount unread bytes.
ch_get_descriptorGet the file descriptor associated with a channel.
ch_open_stdinCreate starndard input channel.
ch_test_for_ioTest if I/O possible on channel.
ch_test_for_asynchronousTest if a channel object is an asynchronous channel.
ch_test_for_connectionTest if a channel object is a connection channel.
ch_test_for_local_connectionTest if a connection channel object is a local connection.
ch_attach_to_asynchronous_descriptorCreate a channel object from an asynchronous descriptor.
ch_test_for_mmapTest if a channel object is a memory mapped disc channel.
ch_tellGet the read and write pointers for a channel.
ch_get_mmap_addrGet memory mapped address.
ch_get_mmap_access_countGet memory mapped access count.
ch_register_converterRegister channel converter function.
ch_unregister_converterUnregister converter.
ch_create_pipeCreate a pipe.
ch_create_sinkCreate data sink.
ch_tap_io_eventsRegister I/O tap function.
ch_open_and_fill_memoryCreate and fill memory channel.
ch_getsRead a line from a channel.
ch_getlRead a line from a channel.
ch_putsWrite a character string to a channel.
ch_drainDrain bytes from a channel.
ch_printfWrite formatted output to a channel.

Prototype Functions

CH_PROTO_size_funcGet number of bytes readable.
CH_PROTO_read_funcRead bytes.
CH_PROTO_write_funcWrite bytes.
CH_PROTO_flush_funcFlush.
CH_PROTO_close_funcClose.
CH_PROTO_tap_funcTap I/O callback.

Tables

CH_FILE_MODESList of defined file modes
CH_MAP_CONTROLSList 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:

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


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:

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


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:

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


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:

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:

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:

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


flag ch_close (Channel channel)

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

Parameters:

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


flag ch_flush (Channel channel)

Flush the write buffer of a channel object.

Parameters:

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:

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


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:

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:

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


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:

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:

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:


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:

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:

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:

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:

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:

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:

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:

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:

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


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:

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


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:

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


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:

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:

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:

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:

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:

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


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

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

Parameters:

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


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

Write a character string to a channel.

Parameters:

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


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:

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


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

Write formatted output to a channel.

Parameters:

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:

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:

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:

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:

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:

Returns: Nothing.
Multithreading Level: Unsafe


void CH_PROTO_tap_func (void *info)

This routine is called when I/O occurs.

Parameters:

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