The "pio" Package

These routines are meant to provide a high level means of converting C data types to the "network" data format (ie. big endian, IEEE 754). These routines transfer data between host memory and files/ connections. These routines are NOT recommended as a means to transfer the recursive, heirarchical data structure supported in Karma, use the dsxfr routines instead.

Library: karma
Link With: -lkarma

Functions

pio_write64	Write 64 bits of data to a channel object.
pio_read64	Read 64 bits of data from a channel object.
pio_write32	Write 32 bits of data to a channel object.
pio_read32	Read 32 bits of data from a channel object.
pio_write16	Write 16 bits of data to a channel object.
pio_read16	Read 16 bits of data from a channel object.
pio_write_float	Write a floating point number to a channel object.
pio_write_float_trap	Write a floating point data to a channel object, trapping blanks.
pio_read_float	Read a floating point number from a channel object.
pio_read_float_nantrap	Read floating point data from a channel object, trapping NaNs.
pio_read_floats	Read floating point data from a channel object, trapping NaNs.
pio_write_double	Write double precision floating point data to a channel object.
pio_write_double_trap	Write double precision floating point data to a channel object.
pio_read_double	Read double precision floating point data from a channel object.
pio_read_double_nantrap	Read floating point data from a channel object, trapping NaNs.
pio_read_doubles	Read double float data from a channel object, trapping NaNs.
pio_write32s	Write 32 bits of signed data to a channel object.
pio_read32s	Read 32 bits of signed data from a channel object.
pio_write16s	Write 16 bits of signed data to a channel object.
pio_read16s	Read 16 bits of signed data from a channel object.
pio_write_swap	Swap and write bytes to a channel object.
pio_read_swap	Read from a channel object and swap bytes.
pio_write_string	Write a string to a channel object.
pio_read_string	Read a string from a channel object.

Functions

flag pio_write64 (Channel channel, unsigned long data)

Write 64 bits of data to a channel object.

Parameters:

channel : The channel object.
data : The data. This must be in host natural byte order. The data will be converted to network byte order prior to writing.

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

flag pio_read64 (Channel channel, unsigned long *data)

Read 64 bits of data from a channel object.

Parameters:

channel : The channel object.
data : The data will be written here. This will be in host natural byte order. The data will be converted from network byte order after reading.

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

flag pio_write32 (Channel channel, unsigned long data)

Write 32 bits of data to a channel object.

Parameters:

channel : The channel object.
data : The data. This must be in host natural byte order. The data will be converted to network byte order prior to writing.

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

flag pio_read32 (Channel channel, unsigned long *data)

Read 32 bits of data from a channel object.

Parameters:

channel : The channel object.
data : The data will be written here. This will be in host natural byte order. The data will be converted from network byte order after reading.

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

flag pio_write16 (Channel channel, unsigned long data)

Write 16 bits of data to a channel object.

Parameters:

channel : The channel object.
data : The data. This must be in host natural byte order. The data will be converted to network byte order prior to writing.

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

flag pio_read16 (Channel channel, unsigned long *data)

Read 16 bits of data from a channel object.

Parameters:

channel : The channel object.
data : The data will be written here. This will be in host natural byte order. The data will be converted from network byte order after reading.

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

flag pio_write_float (Channel channel, float data)

Write a floating point number to a channel object.

Parameters:

channel : The channel object.
data : The data. This must be in host natural format. The data will be converted to IEEE network format prior to writing.

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

EXPERIMENTAL FUNCTION: subject to change without notice

flag pio_write_float_trap (Channel channel, float data, flag blanks_to_nans)

This routine will write a floating point number to a channel object and will optionally convert blank values (TOOBIGs) to IEEE Not-A-Number (NaN) values.

Parameters:

channel : The channel object.
data : The data. This must be in host natural format. The data will be converted to IEEE network format prior to writing.
blank_to_nans : If TRUE, TOOBIG values are converted to NaNs.

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

flag pio_read_float (Channel channel, float *data)

Read a floating point number from a channel object.

Parameters:

channel : The channel object.
data : The data will be written here. This will be written in host natural format. The data will be converted from IEEE network format prior to writing.

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

flag pio_read_float_nantrap (Channel channel, float *data, flag *was_nan)

This routine will read a floating point number from a channel object and will trap IEEE Not-A-Number (NaN) values.

Parameters:

channel : The channel object.
data : The data will be written here. This will be written in host natural format. The data will be converted from IEEE network format prior to writing.
was_nan : The value TRUE will be written here if the value was NaN, else FALSE is written here.

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

EXPERIMENTAL FUNCTION: subject to change without notice

uaddr pio_read_floats (Channel channel, uaddr num_values, float *data, uaddr *num_nan)

This routine will read many floating point numbers from a channel object and will optionally trap IEEE Not-A-Number (NaN) values. Trapped NaNs are converted to the TOOBIG value.

Parameters:

channel : The channel object.
num_values : The number of values to read.
data : The data will be written here. This will be written in host natural format. The data will be converted from IEEE network format prior to writing.
num_nan : The number of NaN values found will be written here. If this is NULL then NaN values are not trapped.

Returns: The number of values read and converted.
Multithreading Level: Unsafe

flag pio_write_double (Channel channel, double data)

Write double precision floating point data to a channel object.

Parameters:

channel : The channel object.
data : The data. This must be in host natural format. The data will be converted to IEEE network format prior to writing.

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

EXPERIMENTAL FUNCTION: subject to change without notice

flag pio_write_double_trap (Channel channel, double data, flag blanks_to_nans)

This routine will write a double precision floating point number to a channel object and will optionally convert blank values (TOOBIGs) to IEEE Not-A-Number (NaN) values.

Parameters:

channel : The channel object.
data : The data. This must be in host natural format. The data will be converted to IEEE network format prior to writing.
blank_to_nans : If TRUE, TOOBIG values are converted to NaNs.

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

flag pio_read_double (Channel channel, double *data)

Read double precision floating point data from a channel object.

Parameters:

channel : The channel object.
data : The data will be written here. This will be written in host natural format. The data will be converted from IEEE network format prior to writing.

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

flag pio_read_double_nantrap (Channel channel, double *data, flag *was_nan)

This routine will read a double precision floating point number from a channel object and will trap IEEE Not-A-Number (NaN) values.

Parameters:

channel : The channel object.
data : The data will be written here. This will be written in host natural format. The data will be converted from IEEE network format prior to writing.
was_nan : The value TRUE will be written here if the value was NaN, else FALSE is written here.

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

EXPERIMENTAL FUNCTION: subject to change without notice

uaddr pio_read_doubles (Channel channel, uaddr num_values, double *data, uaddr *num_nan)

This routine will read many double precision floating point numbers from a channel object and will optionally trap IEEE Not-A-Number (NaN) values. Trapped NaNs are converted to the TOOBIG value.

Parameters:

channel : The channel object.
num_values : The number of values to read.
data : The data will be written here. This will be written in host natural format. The data will be converted from IEEE network format prior to writing.
num_nan : The number of NaN values found will be written here. If this is NULL then NaN values are not trapped.

Returns: The number of values read and converted.
Multithreading Level: Unsafe

flag pio_write32s (Channel channel, long data)

Write 32 bits of signed data to a channel object.

Parameters:

channel : The channel object.
data : The data. This must be in host natural byte order. The data will be converted to network byte order prior to writing.

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

flag pio_read32s (Channel channel, long *data)

Read 32 bits of signed data from a channel object.

Parameters:

channel : The channel object.
data : The data will be written here. This will be in host natural byte order. The data will be converted from network byte order after reading.

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

flag pio_write16s (Channel channel, long data)

Write 16 bits of signed data to a channel object.

Parameters:

channel : The channel object.
data : The data. This must be in host natural byte order. The data will be converted to network byte order prior to writing.

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

flag pio_read16s (Channel channel, long *data)

Read 16 bits of signed data from a channel object.

Parameters:

channel : The channel object.
data : The data will be written here. This will be in host natural byte order. The data will be converted from network byte order after reading.

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

flag pio_write_swap (Channel channel, CONST char *data, unsigned int length)

Swap and write bytes to a channel object.

Parameters:

channel : The channel object.
data : A pointer to the data bytes.
length : The number of bytes to swap and then write.

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

flag pio_read_swap (Channel channel, char *data, unsigned int length)

Read from a channel object and swap bytes.

Parameters:

channel : The channel object.
data : The data bytes will be written here.
length : The number of bytes to read and then swap.

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

flag pio_write_string (Channel channel, CONST char *string)

Write a string to a channel object.

Parameters:

channel : The channel object.
string : The string. If this is NULL, a zero length string is written.

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

char * pio_read_string (Channel channel, unsigned int *length)

Read a string from a channel object.

Parameters:

channel : The channel object.
length : The length of the string will be written here. If this is NULL, nothing is written here.

Returns: A pointer to a dynamically allocated string on success, else NULL. If a zero length string was read, the returned buffer is one character long and contains the '\0' character.
Multithreading Level: Unsafe

Back to Karma Home Page

Contact: Richard Gooch
Web Development: Ariel Internet Services