Header file for the bdio-library. More...
#include <stdint.h>
#include <stdio.h>
Go to the source code of this file.
Data Structures | |
struct | BDIO |
bdio file descriptor More... | |
Macros | |
#define | BDIO_BIN_GENERIC 0x00 |
record format for binary data not covered by other formats | |
#define | BDIO_ASC_EXEC 0x01 |
record format for executable ASCII data like shell scripts | |
#define | BDIO_BIN_INT32BE 0x02 |
record format for 32bit integers with big endian byte ordering | |
#define | BDIO_BIN_INT32LE 0x03 |
record format for 32bit integers with little endian byte ordering | |
#define | BDIO_BIN_INT64BE 0x04 |
record format for 64bit (long) integers with big endian byte ordering | |
#define | BDIO_BIN_INT64LE 0x05 |
record format for 64bit (long) integers with little endian byte ordering | |
#define | BDIO_BIN_F32BE 0x06 |
record format for single precision floating point numbers with big endian byte ordering | |
#define | BDIO_BIN_F32LE 0x07 |
record format for single precision floating point numbers with little endian byte ordering | |
#define | BDIO_BIN_F64BE 0x08 |
record format for double precision floating point numbers with big endian byte ordering | |
#define | BDIO_BIN_F64LE 0x09 |
record format for double precision floating point numbers with little endian byte ordering | |
#define | BDIO_ASC_GENERIC 0x0A |
record format for generic ASCII data | |
#define | BDIO_ASC_XML 0x0B |
record format for XML data | |
#define | BDIO_BIN_INT32 0xF0 |
record format 32bit integers with unspecified byte order, which is determined automatically | |
#define | BDIO_BIN_INT64 0xF1 |
record format 64bit (long) integers with unspecified byte order, which is determined automatically | |
#define | BDIO_BIN_F32 0xF2 |
record format single precision floating point numbers with unspecified byte order, which is determined automatically | |
#define | BDIO_BIN_F64 0xF3 |
record format double precision floating point numbers with unspecified byte order, which is determined automatically | |
#define | BDIO_R_MODE 0 |
I/O mode: read. | |
#define | BDIO_W_MODE 1 |
I/O mode: write. | |
#define | BDIO_A_MODE 2 |
I/O mode: append. | |
#define | BDIO_H_STATE 1 |
BDIO.state: inside a header. | |
#define | BDIO_R_STATE 2 |
BDIO.state: inside a data record. | |
#define | BDIO_N_STATE 3 |
BDIO.state: neither in a header nor in a data record. | |
#define | BDIO_E_STATE 4 |
BDIO.state: in an error state. | |
#define | BDIO_LEND 0 |
little endian (least significant byte first ordering, e.g. intel) | |
#define | BDIO_BEND 1 |
big endian (most significant byte first ordering, e.g. bluegene) | |
Functions | |
void | bdio_perror (const char *s, BDIO *fh) |
Print an error string to BDIO.msg. More... | |
void | bdio_pferror (const char *s, BDIO *fh) |
Print an error string to BDIO.msg. More... | |
BDIO * | bdio_open (const char *file, const char *mode, char *protocol_info) |
Open a bdio file in mode 'r' (read), 'w' (write) or 'a' (append). More... | |
int | bdio_close (BDIO *fh) |
Close a bdio file. More... | |
void | bdio_set_dflt_msg (FILE *stream) |
Set the default stream for error messages. More... | |
int | bdio_set_msg (FILE *stream, BDIO *fh) |
Set the stream for error messages in fh to stream. More... | |
void | bdio_set_dflt_verbose (int v) |
Change the behavior for reporting of errors. More... | |
int | bdio_set_verbose (int v, BDIO *fh) |
Set bdio file fh to verbose (v>0) or silent (v==0) More... | |
char * | bdio_get_hchost (BDIO *fh) |
Get the host on which the last header was created. More... | |
char * | bdio_get_hcuser (BDIO *fh) |
Get the user name who created the last header. More... | |
char * | bdio_get_hmhost (BDIO *fh) |
Get the host on which the last header was most recently modified. More... | |
char * | bdio_get_hmuser (BDIO *fh) |
Get the user name who modified the last header most recently. More... | |
char * | bdio_get_hpinfo (BDIO *fh) |
Get the protocol info of the last header. More... | |
int | bdio_get_hcdate (BDIO *fh) |
Get the time of creation of the last header. More... | |
int | bdio_get_hmdate (BDIO *fh) |
Get the time of the most recent modification of the last header. More... | |
int | bdio_get_ruinfo (BDIO *fh) |
Get the user info of the current record. More... | |
int | bdio_get_hversion (BDIO *fh) |
Get version number in last header. More... | |
int | bdio_get_hcnt (BDIO *fh) |
Get number of headers read or written so far (including current) More... | |
int | bdio_get_rfmt (BDIO *fh) |
Get format of current record (written or read). More... | |
uint64_t | bdio_get_rlen (BDIO *fh) |
Get length of data content of current record (written or read). More... | |
int | bdio_get_rcnt (BDIO *fh) |
Get number of records read or written so far (including current) More... | |
int | bdio_is_in_record (BDIO *fh) |
Returns 1 if fh is in a record and 0 otherwise. More... | |
int | bdio_is_in_header (BDIO *fh) |
Returns 1 if fh is in a header and 0 otherwise. More... | |
int | bdio_seek_record (BDIO *fh) |
Position bdio stream to start of next record and read its header. More... | |
size_t | bdio_read (void *buf, size_t nb, BDIO *fh) |
Read nb bytes from fh into buf. More... | |
size_t | bdio_read_f32 (float *buf, size_t nb, BDIO *fh) |
brief Read nb bytes from fh into buf. nb must be a multiple of 4. More... | |
size_t | bdio_read_f64 (double *buf, size_t nb, BDIO *fh) |
brief Read nb bytes from fh into buf. nb must be a multiple of 8. More... | |
size_t | bdio_read_int32 (int32_t *buf, size_t nb, BDIO *fh) |
brief Read nb bytes from fh into buf. nb must be a multiple of 4. More... | |
size_t | bdio_read_int64 (int64_t *buf, size_t nb, BDIO *fh) |
brief Read nb bytes from fh into buf. nb must be a multiple of 8. More... | |
int | bdio_start_record (int fmt, int uinfo, BDIO *fh) |
Position bdio stream after the current record and start writing a new record with specified format and uinfo. More... | |
int | bdio_append_record (int fmt, int uinfo, BDIO *fh) |
If the last item in the file was a record: position the stream at the end of it. Otherwise EOF is returned. More... | |
size_t | bdio_write (void *ptr, size_t nb, BDIO *fh) |
Write nb bytes from ptr to fh. More... | |
size_t | bdio_write_f32 (float *ptr, size_t nb, BDIO *fh) |
Write nb bytes from ptr to fh. More... | |
size_t | bdio_write_f64 (double *ptr, size_t nb, BDIO *fh) |
Write nb bytes from ptr to fh. More... | |
size_t | bdio_write_int32 (int32_t *ptr, size_t nb, BDIO *fh) |
Write nb bytes from ptr to fh. More... | |
size_t | bdio_write_int64 (int64_t *ptr, size_t nb, BDIO *fh) |
Write nb bytes from ptr to fh. More... | |
int | bdio_flush_record (BDIO *fh) |
Finalize the current record and set fh to BDIO_N_STATE. More... | |
Header file for the bdio-library.
Details & license
int bdio_append_record | ( | int | fmt, |
int | uinfo, | ||
BDIO * | fh | ||
) |
If the last item in the file was a record: position the stream at the end of it. Otherwise EOF is returned.
The specified format and uinfo must match the last record's values.
fails if
[in] | fmt | Supported formats are
| ||||||||||||||||||||||||||||||||||
[in] | uinfo | is a number between 0 and 15 specified by the user. | ||||||||||||||||||||||||||||||||||
[in] | fh | pointer to a BDIO file descriptor structure. |
int bdio_close | ( | BDIO * | fh | ) |
Close a bdio file.
If the file has been opened in write or append mode this function must be called also to guarantee that the last written record is correctly flushed (update of the record length).
bdio_close fails if
In the last case bdio_close will close the file without flushing.
[in] | fh | pointer to a BDIO file descriptor structure |
int bdio_flush_record | ( | BDIO * | fh | ) |
Finalize the current record and set fh to BDIO_N_STATE.
If fh is open in write/append mode:
If state is BDIO_R_STATE, the current record is finalized by flushing, writing the length into the record-header, moving the file pointer to the end of the file and changing the state to BDIO_N_STATE
If state is BDIO_H_STATE, the header record is finalized by flushing and setting the state to BDIO_N_STATE
If state is BDIO_N_STATE, nothing is done
A call to this function is usually not necessary. A call is advised only before engaging in operations that may lead to a crash or early termination, But even then, calling bdio_close would be preferred.
Fails if
[in] | fh | pointer to a BDIO file descriptor structure. |
int bdio_get_hcdate | ( | BDIO * | fh | ) |
Get the time of creation of the last header.
Fails if fh is invalid or in error state
[in] | fh | pointer to a BDIO file descriptor structure. |
char * bdio_get_hchost | ( | BDIO * | fh | ) |
Get the host on which the last header was created.
Fails if fh is invalid or in error state
[in] | fh | pointer to a BDIO file descriptor structure. |
int bdio_get_hcnt | ( | BDIO * | fh | ) |
Get number of headers read or written so far (including current)
Fails if fh is a null pointer or if fh is in state BDIO_E_STATE
[in] | fh | pointer to a BDIO file descriptor structure. |
char * bdio_get_hcuser | ( | BDIO * | fh | ) |
Get the user name who created the last header.
Fails if fh is invalid or in error state
[in] | fh | pointer to a BDIO file descriptor structure. |
int bdio_get_hmdate | ( | BDIO * | fh | ) |
Get the time of the most recent modification of the last header.
Fails if fh is invalid or in error state
[in] | fh | pointer to a BDIO file descriptor structure. |
char * bdio_get_hmhost | ( | BDIO * | fh | ) |
Get the host on which the last header was most recently modified.
Fails if fh is invalid or in error state
[in] | fh | pointer to a BDIO file descriptor structure. |
char * bdio_get_hmuser | ( | BDIO * | fh | ) |
Get the user name who modified the last header most recently.
Fails if fh is invalid or in error state
[in] | fh | pointer to a BDIO file descriptor structure. |
char * bdio_get_hpinfo | ( | BDIO * | fh | ) |
Get the protocol info of the last header.
Fails if fh is invalid or in error state
[in] | fh | pointer to a BDIO file descriptor structure. |
int bdio_get_hversion | ( | BDIO * | fh | ) |
Get version number in last header.
Fails if fh is invalid or in error state
[in] | fh | pointer to a BDIO file descriptor structure. |
int bdio_get_rcnt | ( | BDIO * | fh | ) |
Get number of records read or written so far (including current)
Fails if fh is a null pointer or if fh is in state BDIO_E_STATE
[in] | fh | pointer to a BDIO file descriptor structure. |
int bdio_get_rfmt | ( | BDIO * | fh | ) |
Get format of current record (written or read).
Fails if fh is a null pointer or if fh is not in state BDIO_R_STATE
[in] | fh | pointer to a BDIO file descriptor structure. |
uint64_t bdio_get_rlen | ( | BDIO * | fh | ) |
Get length of data content of current record (written or read).
Fails if fh if is a null pointer or if fh is in state BDIO_E_STATE
[in] | fh | pointer to a BDIO file descriptor structure. |
int bdio_get_ruinfo | ( | BDIO * | fh | ) |
Get the user info of the current record.
Fails if fh is invalid or in error state
[in] | fh | pointer to a BDIO file descriptor structure. |
int bdio_is_in_header | ( | BDIO * | fh | ) |
Returns 1 if fh is in a header and 0 otherwise.
Fails if fh is invalid
[in] | fh | pointer to a BDIO file descriptor structure |
int bdio_is_in_record | ( | BDIO * | fh | ) |
Returns 1 if fh is in a record and 0 otherwise.
Fails if fh is invalid
[in] | fh | pointer to a BDIO file descriptor structure |
BDIO * bdio_open | ( | const char * | file, |
const char * | mode, | ||
char * | protocol_info | ||
) |
Open a bdio file in mode 'r' (read), 'w' (write) or 'a' (append).
In read mode, the header record is read and checked. The stream remains positioned in the header record, therefore bdio_seek_record must be called to enter the next record. protocol_info may be NULL, but if it is not NULL, it must match the protocol_info string of the first header.
In write mode, the header record is written. The stream remains positioned in the header record, therefore bdio_start_record must be called to start a new record. protocol_info must be a 0-terminated string (at least "").
In append mode, the header records are read and checked. The stream is positioned at the end of the last header or after the last record, therefore bdio_start_record or bdio_append_record (only possible if the last item was a record) must be called to start a new record. If the file is not empty, protocol_info may be NULL - if not NULL it must match the one of the last header. If the file is empty, protocol_info must be a 0-terminated string.
The maximal length protocol_info may have is: XXXX TODO <–
bdio_open fails if
[in] | file | 0-terminated string specifying the file name |
[in] | mode | a bdio file mode, can be BDIO_R_MODE, BDIO_W_MODE or BDIO_A_MODE |
[in] | protocol_info | 0-terminated string specifying the protocol-info |
void bdio_perror | ( | const char * | s, |
BDIO * | fh | ||
) |
Print an error string to BDIO.msg.
Print the string pointed to by s followed by the description of the last error that occured to BDIO.msg.
If s is NULL, only the description of the last error is printed.
The function fails if fh is invalid or if the error-stream associated with fh is invalid.
[in] | s | 0-terminated string with user-provided error message |
[in] | fh | pointer to a BDIO file descriptor structure |
void bdio_pferror | ( | const char * | s, |
BDIO * | fh | ||
) |
Print an error string to BDIO.msg.
Print the string pointed to by s followed by the description of the first error that occured to BDIO.msg.
If s is NULL, only the description of the first error is printed.
The function fails if fh is invalid or if the error-stream associated with fh is invalid.
[in] | s | 0-terminated string with user-provided error message |
[in] | fh | pointer to a BDIO file descriptor structure |
size_t bdio_read | ( | void * | buf, |
size_t | nb, | ||
BDIO * | fh | ||
) |
Read nb bytes from fh into buf.
Independent of the endiannes of the machine and the record type, exactly the bytes from the file are copied. If a byte-swap is necessary, the user is responsible for doing it.
Fails if -fh is a null pointer -fh is in state BDIO_E_STATE -fh is not in read mode -nb is too large -fread fails
[in] | buf | pointer to a location where the read data is copied to. |
[in] | nb | number of bytes to be read. |
[in] | fh | pointer to a BDIO file descriptor structure. |
size_t bdio_read_f32 | ( | float * | buf, |
size_t | nb, | ||
BDIO * | fh | ||
) |
brief Read nb bytes from fh into buf. nb must be a multiple of 4.
If the endianness of the machine differs from the one of the current record, the byte order of the read data is swapped. If this swapping is not desired the general bdio_read should be used.
Fails if
[in] | buf | float-pointer to a location where the read data is copied to. |
[in] | nb | number of bytes to be read (multiple of 4). |
[in] | fh | pointer to a BDIO file descriptor structure. |
size_t bdio_read_f64 | ( | double * | buf, |
size_t | nb, | ||
BDIO * | fh | ||
) |
brief Read nb bytes from fh into buf. nb must be a multiple of 8.
If the endianness of the machine differs from the one of the current record, the byte order of the read data is swapped. If this swapping is not desired the general bdio_read should be used.
Fails if
[in] | buf | double-pointer to a location where the read data is copied to. |
[in] | nb | number of bytes to be read (multiple of 8). |
[in] | fh | pointer to a BDIO file descriptor structure. |
size_t bdio_read_int32 | ( | int32_t * | buf, |
size_t | nb, | ||
BDIO * | fh | ||
) |
brief Read nb bytes from fh into buf. nb must be a multiple of 4.
If the endianness of the machine differs from the one of the current record, the byte order of the read data is swapped. If this swapping is not desired the general bdio_read should be used.
Fails if
[in] | buf | int32_t-pointer to a location where the read data is copied to. |
[in] | nb | number of bytes to be read (multiple of 4). |
[in] | fh | pointer to a BDIO file descriptor structure. |
size_t bdio_read_int64 | ( | int64_t * | buf, |
size_t | nb, | ||
BDIO * | fh | ||
) |
brief Read nb bytes from fh into buf. nb must be a multiple of 8.
If the endianness of the machine differs from the one of the current record, the byte order of the read data is swapped. If this swapping is not desired the general bdio_read should be used.
Fails if
[in] | buf | int64_t-pointer to a location where the read data is copied to. |
[in] | nb | number of bytes to be read (multiple of 8). |
[in] | fh | pointer to a BDIO file descriptor structure. |
int bdio_seek_record | ( | BDIO * | fh | ) |
Position bdio stream to start of next record and read its header.
fails if
[in] | fh | pointer to a BDIO file descriptor structure. |
void bdio_set_dflt_msg | ( | FILE * | stream | ) |
Set the default stream for error messages.
[in] | stream | pointer to a file into which error messages should be printed by default for any newly opened bdio file. |
void bdio_set_dflt_verbose | ( | int | v | ) |
Change the behavior for reporting of errors.
Set the default for newly opened bdio files to verbose (v !=0 ) or silent (v==0)
Fails if v is negative
[in] | v | new default behavior |
int bdio_set_msg | ( | FILE * | stream, |
BDIO * | fh | ||
) |
Set the stream for error messages in fh to stream.
Fails if fh is invalid or stream is NULL
[in] | stream | pointer to a file into which error messages associated with bdio file fh are printed |
[in] | fh | pointer to a BDIO file descriptor structure. |
int bdio_set_verbose | ( | int | v, |
BDIO * | fh | ||
) |
Set bdio file fh to verbose (v>0) or silent (v==0)
Fails if fh is invalid or in error state or v is negative
[in] | v | v==0 means silent mode and v>0 means verbose mode |
[in] | fh | pointer to a BDIO file descriptor structure. |
int bdio_start_record | ( | int | fmt, |
int | uinfo, | ||
BDIO * | fh | ||
) |
Position bdio stream after the current record and start writing a new record with specified format and uinfo.
Fails if
[in] | fmt | supported formats are
| ||||||||||||||||||||||||||||||||||
[in] | uinfo | is a number between 0 and 15 specified by the user. | ||||||||||||||||||||||||||||||||||
[in] | fh | pointer to a BDIO file descriptor structure. |
size_t bdio_write | ( | void * | ptr, |
size_t | nb, | ||
BDIO * | fh | ||
) |
Write nb bytes from ptr to fh.
nb must be a multiple of the record's data-type-size (e.g. multiple of 8 for BDIO_BIN_F64) Independent of the endianness of the current record, EXACTLY the data pointed to by ptr is written into the file. The user is responsible for the correct byte order. If automatic correct byte ordering is desired, the functions bdio_write_f32, bdio_write_f64, bdio_write_i32 and bdio_write_i64 should be used.
Fails if
[in] | ptr | pointer to data which is to be written. |
[in] | nb | number of bytes to be written. Must be a multiple of the size of the record's data-type. E.g. multiple of 4 for BDIO_BIN_F32 records. |
[in] | fh | pointer to a BDIO file descriptor structure. |
size_t bdio_write_f32 | ( | float * | ptr, |
size_t | nb, | ||
BDIO * | fh | ||
) |
Write nb bytes from ptr to fh.
nb must be a multiple of 4. If the endiannes of the machine differs from the one of the current record, the byte order of the data in ptr is swapped before writing. If this automatic swapping is not desired, the general bdio_write should be used.
Fails if
[in] | ptr | pointer to float data which is to be written. |
[in] | nb | number of bytes to be written. Must be a multiple of 4. |
[in] | fh | pointer to a BDIO file descriptor structure. |
size_t bdio_write_f64 | ( | double * | ptr, |
size_t | nb, | ||
BDIO * | fh | ||
) |
Write nb bytes from ptr to fh.
nb must be a multiple of 8. If the endiannes of the machine differs from the one of the current record, the byte order of the data in ptr is swapped before writing. If this automatic swapping is not desired, the general bdio_write should be used.
Fails if
[in] | ptr | pointer to double data which is to be written. |
[in] | nb | number of bytes to be written. Must be a multiple of 8. |
[in] | fh | pointer to a BDIO file descriptor structure. |
size_t bdio_write_int32 | ( | int32_t * | ptr, |
size_t | nb, | ||
BDIO * | fh | ||
) |
Write nb bytes from ptr to fh.
nb must be a multiple of 4. If the endiannes of the machine differs from the one of the current record, the byte order of the data in ptr is swapped before writing. If this automatic swapping is not desired, the general bdio_write should be used.
Fails if
[in] | ptr | pointer to int32_t data which is to be written. |
[in] | nb | number of bytes to be written. Must be a multiple of 4. |
[in] | fh | pointer to a BDIO file descriptor structure. |
size_t bdio_write_int64 | ( | int64_t * | ptr, |
size_t | nb, | ||
BDIO * | fh | ||
) |
Write nb bytes from ptr to fh.
nb must be a multiple of 8. If the endiannes of the machine differs from the one of the current record, the byte order of the data in ptr is swapped before writing. If this automatic swapping is not desired, the general bdio_write should be used.
Fails if
[in] | ptr | pointer to int64_t data which is to be written. |
[in] | nb | number of bytes to be written. Must be a multiple of 8. |
[in] | fh | pointer to a BDIO file descriptor structure. |