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_open_connection	Open a connection to a Karma server.
ch_accept_on_dock	Accept a connection.
ch_alloc_port	Allocate a port.
ch_attach_to_asynchronous_descriptor	Create a channel object from an asynchronous descriptor.
ch_open_stdin	Create starndard input channel.
ch_open_stdout	Create starndard output channel.
ch_create_pipe	Create a pipe.
ch_create_socketpair	Create a pair of un-named connected sockets.
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_get_buffer_sizes	Get the read and write buffer sizes for a channel.
ch_set_buffer_sizes	Set the read and write buffer sizes for a channel.
ch_udp_alloc	Create a UDP socket and bind to a random port number.
ch_set_nodelay	Set the no-delay flag for a channel if appropriate.
ch_get_qos	Get the Quality of Service parameters for a connection.
ch_register_close_func	Register close callback.
ch_close	Close a channel.
ch_flush	Flush the write buffer of a channel object.
ch_read	Read from a channel.
ch_read2	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_test_for_io	Test if I/O possible on channel.
ch_test_for_converters	Test if a channel object has converters.
ch_tell	Get the read and write pointers for a channel.
ch_register_converter	Register channel converter function.
ch_unregister_converter	Unregister converter.
ch_tap_io_events	Register I/O tap function.
ch_test_valid	Test if a channel is valid.
ch_skip	Skip bytes in a channel, seeking if possible.
ch_get_descriptor	Get the file descriptor associated with a channel.
ch_map_disc	Map a disc file.
ch_map_fd	Map a disc file.
ch_open_memory	Open a memory channel.
ch_test_for_mmap	Test if a channel object is a memory mapped disc channel.
ch_get_mmap_addr	Get memory mapped address.
ch_get_memory_addr	Get memory address.
ch_get_mmap_access_count	Get memory mapped access count.
ch_get_mem_size	Get memory buffer size.
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_fill	Fill a channel with bytes.
ch_printf	Write formatted output to a channel.
ch_scanf	Read formatted input from a channel.
ch_drain_to_boundary	Drain bytes from a channel until a specified boundary.
ch_skip_to_boundary	Skip bytes from a channel until a specified boundary.
ch_fill_to_boundary	Write bytes to a channel until a specified boundary.
ch_read_and_swap_blocks	Read blocks from a channel and swap bytes.
ch_swap_and_write_blocks	Write blocks to a channel after swapping bytes.
ch_copy	Copy bytes from one channel to another in an optimal way.
ch_map_disc2	Attempt to map a disc file, fallback to reading.
ch_open_compressed_file	Open a file, with possible decompression.
ch_get_bytes_remaining_in_disc	Return the number of bytes remaining in a disc file.
ch_create_sink	Create data sink.
ch_create_zero	Create data source.

Prototype Functions

ch_PROTO_converter_size_func	Get number of bytes readable.
ch_PROTO_converter_read_func	Read bytes.
ch_PROTO_converter_write_func	Write bytes.
ch_PROTO_converter_flush_func	Flush.
ch_PROTO_converter_close_func	Close.
ch_PROTO_tap_func	Tap I/O callback.
ch_PROTO_close_func	Process a destroy event for an object.

Tables

ch_FILE_MODES	List of defined file modes
ch_MAP_CONTROLS	List of mapping control values
ch_ENVIRONMENT	List of environment variables

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/{hostname}:{port}" 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_open_connection (unsigned long host_addr, unsigned int port_number)

This routine will open a full-duplex connection channel to a Karma 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 Karma 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_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.

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

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.

EXPERIMENTAL FUNCTION: subject to change without notice

void ch_open_stdout ()

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

Parameters:

Returns: Nothing.
Multithreading Level: Unsafe
Note:

The standard output channel will be written to the external variable ch_stdout.

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

EXPERIMENTAL FUNCTION: subject to change without notice

flag ch_create_socketpair (Channel *ch1, Channel *ch2)

Create a pair of un-named connected sockets.

Parameters:

ch1 : The channel corresponding to one end of the pair is written here.
ch2 : The channel corresponding to the other end of the pair is written here.

Returns: TRUE on success, else FALSE and sets errno with the error code.
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

EXPERIMENTAL FUNCTION: subject to change without notice

flag ch_get_buffer_sizes (Channel channel, uaddr *read_size, uaddr *write_size)

Get the read and write buffer sizes for a channel.

Parameters:

channel : The channel object.
read_size : The read buffer size is written here.
write_size : The write buffer size is written here.

Returns: TRUE on success, else FALSE indicating the channel does not have read or write buffers.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

flag ch_set_buffer_sizes (Channel channel, unsigned long read_size, unsigned long write_size)

Set the read and write buffer sizes for a channel.

Parameters:

channel : The channel object.
read_size : The read buffer size.
write_size : The write buffer size.

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

EXPERIMENTAL FUNCTION: subject to change without notice

Channel ch_udp_alloc (unsigned int *port_number, flag want_to_read)

Create a UDP socket and bind to a random port number.

Parameters:

port_number : The port number the socket was bound to.
port_number : A pointer to the port number to bind to. If the port number is 0, a random port number is bound to, and this value is updated with that port number.
want_to_read : If TRUE, a read buffer is created and the channel will be readable.

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

EXPERIMENTAL FUNCTION: subject to change without notice

flag ch_set_nodelay (Channel channel)

Set the no-delay flag for a channel if appropriate.

Parameters:

channel : The channel object.

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

EXPERIMENTAL FUNCTION: subject to change without notice

void ch_get_qos (Channel channel, struct karma_qos *qos)

Get the Quality of Service parameters for a connection.

Parameters:

channel : The channel object.
qos : The QoS parameters will be written here.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

KCallbackFunc ch_register_close_func (Channel channel, void (*func) (), void *info)

This routine will register a close function for a channel. This is called when ch_close is called. Many close functions may be registered per channel. The first function registered is the first function called upon closure.

Parameters:

channel : The channel object.
func : The function that is called when the canvas is closed. The prototype function is ch_PROTO_close_func.
info : The arbitrary function information pointer.

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

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

uaddr ch_read (Channel channel, char *buffer, uaddr 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.

EXPERIMENTAL FUNCTION: subject to change without notice

uaddr ch_read2 (Channel channel, char *buffer, CONST char **newbuf, unsigned char alignment, uaddr length)

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

Parameters:

channel : The channel object.
buffer : A suggested buffer to write the data into.
newbuf : The buffer pointer used is written here. This may be a read-only buffer. If this is NULL, the suggested buffer is always used.
alignment : The number of bytes the buffer must be aligned to.
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.

uaddr ch_write (Channel channel, CONST char *buffer, uaddr 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

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

EXPERIMENTAL FUNCTION: subject to change without notice

flag ch_test_for_converters (Channel channel)

Test if a channel object has converters.

Parameters:

channel : The channel object.

Returns: TRUE if the channel object is has converters, 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

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_converter_size_func.
read_func : The function which will convert data when reading. The prototype function is ch_PROTO_converter_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_converter_write_func.
flush_func : The function which is called when the channel is to be flushed The prototype function is ch_PROTO_converter_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_converter_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 impose restrictions on channel operations (i.e. 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.
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

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

EXPERIMENTAL FUNCTION: subject to change without notice

flag ch_test_valid (Channel channel, CONST char *function_name)

Test if a channel is valid.

Parameters:

channel : The channel object.
function_name : If not NULL diagnostic messages are written to the standard error prepended with function_name.

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

Frequent use may degrade performance.

EXPERIMENTAL FUNCTION: subject to change without notice

flag ch_skip (Channel channel, uaddr num_bytes)

This function will skip a specified number of bytes in a channel, jumping to the desired point without reading (if possible). If the channel does not support seeking (jumping), then the specified number of bytes are read from the channel.

Parameters:

channel : The channel object.
num_bytes : The number of bytes to skip.

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

Seeking may change the write pointer. Use ch_drain instead if the write pointer must be left untouched.

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

Channel ch_map_disc (CONST char *filename, unsigned int option, flag writable, 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: "rz".
writable : If the mapped pages are to be writable, 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 writable 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.
If the "CH_MMAP_DISABLE" environment variable is defined, then memory mapping is disabled.

EXPERIMENTAL FUNCTION: subject to change without notice

Channel ch_map_fd (int fd, uaddr size, flag writable, 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:

fd : The file descriptor to map. This will be closed on error or when the channel closes.
size : The size of the region to map.
writable : If the mapped pages are to be writable, 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 writable 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_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

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

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.

EXPERIMENTAL FUNCTION: subject to change without notice

char * ch_get_memory_addr (Channel channel)

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

Parameters:

channel : The channel object.

Returns: The address of the memory.
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.

EXPERIMENTAL FUNCTION: subject to change without notice

uaddr ch_get_mem_size (Channel channel)

Get memory buffer size.

Parameters:

channel : The channel object.

Returns: The number of bytes in the memory channel.
Multithreading Level: Unsafe
Note:

The channel MUST be a memory channel.

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). Data is still written to the buffer and NULL terminated on EOF.
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). Data is still written to the buffer and NULL terminated on EOF.
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

unsigned int ch_fill (Channel channel, unsigned int length, char fill_value)

This routine will write a specified byte to a channel a number of times.

Parameters:

channel : The Channel object.
length : The number of bytes to write.
fill_value : The fill value.

Returns: The number of bytes written.
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

int ch_scanf (Channel channel, CONST char *format, ...)

Read formatted input from a channel.

Parameters:

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

Returns: The number of objects scanned.
Multithreading Level: Unsafe
Note:

This function requires the standard C library vsscanf function, which is not supported under Solaris 2.
This function will internally read a line at a time. Beware.

flag ch_drain_to_boundary (Channel channel, uaddr size)

This routine will drain (read) from a channel until the current read position is aligned with a boundary.

Parameters:

channel : The Channel object.
size : The size to align to.

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

EXPERIMENTAL FUNCTION: subject to change without notice

flag ch_skip_to_boundary (Channel channel, uaddr size)

This routine will skip bytes in a channel until the current read position is aligned with a boundary.

Parameters:

channel : The Channel object.
size : The size to align to.

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

This may change the write pointer. Use ch_drain_to_boundary instead if the write pointer must be left untouched.

flag ch_fill_to_boundary (Channel channel, uaddr size, char fill_value)

This routine will write bytes to a channel until the current write position is aligned with a boundary. channel, ignoring the data.

Parameters:

channel : The Channel object.
size : The size to align to.
fill_value : The value to fill with.

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

EXPERIMENTAL FUNCTION: subject to change without notice

uaddr ch_read_and_swap_blocks (Channel channel, char *buffer, uaddr num_blocks, uaddr block_size)

This routine will read a number of blocks from a channel and places them into a buffer after swapping (reversing the order).

Parameters:

channel : The channel object.
buffer : The buffer to write the data into.
num_blocks : The number of blocks to read.
block_size : The size (in bytes) of each block.

Returns: The number of bytes read. Errors may cause partial blocks to be 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 num_blocks * block_size the routine will NOT block.

EXPERIMENTAL FUNCTION: subject to change without notice

uaddr ch_swap_and_write_blocks (Channel channel, CONST char *buffer, uaddr num_blocks, uaddr block_size)

This routine will write a number of blocks to a channel after swapping the bytes.

Parameters:

channel : The channel object.
buffer : The buffer to read the data from.
num_blocks : The number of blocks to write.
block_size : The size (in bytes) of each block.

Returns: The number of bytes written. Errors may cause partial blocks to be written.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

uaddr ch_copy (Channel out, Channel in, uaddr num_bytes)

Copy bytes from one channel to another in an optimal way.

Parameters:

out : The output channel.
in : The input channel.
num_bytes : The number of bytes to copy. If this is 0, the remaining unread contents of in are copied.

Returns: The number of bytes copied. On error a message is generated and the number of bytes successfully copied is returned.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

Channel ch_map_disc2 (CONST char *filename, unsigned int option)

This routine will attempt to open a memory channel with the memory pages being mapped from a disc file. The disc file must already exist. If memory mapping cannot be performed, a normal memory channel is created and the data is read in.

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: "rz".

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

The channel may be queried to determine if it has been memory mapped using the call ch_test_for_mmap.
If the "CH_MMAP_DISABLE" environment variable is defined, then memory mapping is disabled.
Writing to the memory may cause a segmentation fault.

EXPERIMENTAL FUNCTION: subject to change without notice

Channel ch_open_compressed_file (CONST char *filename)

This routine will open a file channel for reading, automatically decompressing data as it is needed. Alternative filenames may be opened in an attempt to file a compressed variant of the base filename.

Parameters:

filename : The base pathname of the file to open.

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

EXPERIMENTAL FUNCTION: subject to change without notice

flag ch_get_bytes_remaining_in_disc (Channel channel, uaddr *length)

Return the number of bytes remaining in a disc file.

Parameters:

channel : The channel to test.
length : The number of bytes readable is written here.

Returns: TRUE on success, else FALSE indicating a non-disc channel or a converter is registered.
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

EXPERIMENTAL FUNCTION: subject to change without notice

Channel ch_create_zero ()

This routine will create a data source channel. All reads from the channel will yield values of zero. Write operations fail.

Parameters:

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

Prototype Functions

unsigned int ch_PROTO_converter_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_converter_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_converter_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_converter_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_converter_close_func (void *info, Channel channel)

This routine is called when a channel is closed.

Parameters:

info : The arbitrary information pointer.
channel : The channel object.

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

flag ch_PROTO_close_func (void *info)

Process a destroy event for an object.

Parameters:

info : An arbitrary function information pointer.

Returns: Nothing.
Multithreading Level: Unsafe

Tables

ch_FILE_MODES List of defined 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
"s" like "w", but create holes when writing zero blocks
"t" set the sticky bit
"z" uncompress if file was compressed (has ".gz" extension)
"l" lock the file, fail if lock not grabbed, unlock on close
"L" lock the file, waiting for lock, unlock on close

ch_MAP_CONTROLS List of mapping control values

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.

ch_ENVIRONMENT List of environment variables

Variable Meaning

CH_MMAP_DISABLE Disable memory mapping

Back to Karma Home Page

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
"s"	like "w", but create holes when writing zero blocks
"t"	set the sticky bit
"z"	uncompress if file was compressed (has ".gz" extension)
"l"	lock the file, fail if lock not grabbed, unlock on close
"L"	lock the file, waiting for lock, unlock on close

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.