CH(3)

PACKAGE
ch - Routines to manipulate channel objects

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

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.

TABLE 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

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

TABLE ch_ENVIRONMENT
List of environment variables
Variable Meaning
CH_MMAP_DISABLE Disable memory mapping

AUTHOR
Richard Gooch (rgooch@atnf.csiro.au)

AVAILABLITY
The Karma Distribution is available for anonymous ftp from: ftp://ftp.atnf.csiro.au/pub/software/karma/ ftp://wuarchive.wustl.edu/graphics/graphics/packages/karma/ ftp://ftp.pwr.wroc.pl/pub/karma/ The Karma Home Page is: http://www.atnf.csiro.au/karma/