# 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 a 64 bit integer to a channel object.
pio_read64 | Read a 64 bit integer from a channel object.
pio_le_read64 | Read a 64 bit little-endian integer from a channel object.
pio_write32 | Write a 32 bit integer to a channel object.
pio_read32 | Read a 32 bit integer from a channel object.
pio_le_read32 | Read a 32 bit little-endian integer from a channel object.
pio_write16 | Write a 16 bit integer to a channel object.
pio_read16 | Read a 16 bit integer from a channel object.
pio_le_read16 | Read a 16 bit little-endian integer 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_le_read_float | Read a little-endian 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_le_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_le_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_le_read_doubles | Read double float data from a channel object, trapping NaNs.
pio_write32s | Write a 32 bit signed integer to a channel object.
pio_read32s | Read a 32 bit signed integer from a channel object.
pio_le_read32s | Read a 32 bit little-endian signed integer from a channel object.
pio_write16s | Write a 16 bit signed integer to a channel object.
pio_read16s | Read a 16 bit signed integer from a channel object.
pio_le_read16s | Read a 16 bit little-endian signed integer 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 a 64 bit integer 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 a 64 bit integer 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

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag pio_le_read64 (Channel channel, unsigned long *data)

Read a 64 bit little-endian integer 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 little-endian byte order after reading.

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

flag pio_write32 (Channel channel, unsigned long data)

Write a 32 bit integer 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 a 32 bit integer 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

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag pio_le_read32 (Channel channel, unsigned long *data)

Read a 32 bit little-endian integer 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 little-endian byte order after reading.

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

flag pio_write16 (Channel channel, unsigned long data)

Write a 16 bit integer 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 a 16 bit integer 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 little-endian byte order after reading.

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

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag pio_le_read16 (Channel channel, unsigned long *data)

Read a 16 bit little-endian integer 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

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag pio_le_read_float (Channel channel, float *data)

Read a little-endian 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 little-endian 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. If this is NULL then NaN values are not trapped.

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

#### EXPERIMENTAL FUNCTION: subject to change without notice

uaddr pio_le_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 little-endian 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

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag pio_le_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 little-endian 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

#### EXPERIMENTAL FUNCTION: subject to change without notice

uaddr pio_le_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 little-endian 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 a 32 bit signed integer 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 a 32 bit signed integer 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

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag pio_le_read32s (Channel channel, long *data)

Read a 32 bit little-endian signed integer 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 little-endian byte order after reading.

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

flag pio_write16s (Channel channel, long data)

Write a 16 bit signed integer 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 a 16 bit signed integer 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

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag pio_le_read16s (Channel channel, long *data)

Read a 16 bit little-endian signed integer 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 little-endian 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