File I/O

Detailed Description

Binary data files contain a sequence of objects.

Each object consists of a 12-byte header, followed by the data part. The data is stored in the internal format with the following differences:

• Packed rows (vectors) are truncated to their actual length. For example, on a machine with sizeof(long)=4, a row with 17 entries over GF(125) would occupy 20 bytes in memory but only 17 bytes in a data file.
• All integers, including the file header, are stored as 32-bit numbers with least significant byte first.

The object header consists of three integers. The first one, T, specifies which kind of object follows. The two other values, R and C, carry additional information about the object. Their exact meaning depends on the value of T.

T>1: Matrix over GF(T)

R is the number of rows, C is the number of columns.

T=-1: Permutations.

R is the degree, C is the number of permutations.

T=-2: Polynomial.

R is the field order, C is the degree.

T=-8: Integer Matrix.

R is the number of rows, C is the number of columns.

Functions
int	FfReadRows (FILE *f, PTR buf, int n)
	Read Rows This function reads 1 or more rows from a file. More...
int	FfWriteRows (FILE *f, PTR buf, int n)
	Write rows This function writes 1 or more rows to a file. More...
int	FfSeekRow (FILE *f, int pos)
	Move to a Row. More...
FILE *	FfReadHeader (const char *name, int *field, int *nor, int *noc)
	Open File and Read Header. More...
FILE *	FfWriteHeader (const char *name, int field, int nor, int noc)
	Open File and Write Header. More...

Function Documentation

FILE* FfReadHeader	(	const char *	name,
		int *	field,
		int *	nor,
		int *	noc
	)

Open File and Read Header.

This function opens a data file for input and reads the file header (3 integers). The exact meaning of the header values depends on the file type. For a matrix they are field order, number of rows and number of columns.

Parameters

name	File name.
field	Pointer to buffer for first header entry (usually the field order).
nor	Pointer to buffer for second header entry (usually the number of rows).
noc	Pointer to buffer for third header entry (usually the number of columns).

Returns

Pointer to open file, or 0 on error.

int FfReadRows	(	FILE *	f,
		PTR	buf,
		int	n
	)

Read Rows This function reads 1 or more rows from a file.

The row size must have been set before.

Parameters

f	Pointer to File.
buf	Pointer to data buffer.
n	Number of rows to read.

Returns

Number of rows that were actually read, or -1 on error.

int FfSeekRow	(	FILE *	f,
		int	pos
	)

Move to a Row.

This function sets the read/write pointer of file f to position pos. I.e., the next FfReadRows() or FfWriteRows() will start at the specified row. Note that row numbers start with 0. If pos is different from 0, the row size must have been set before with FfSetNoc().

You should always use FfSeekRow() rather than fseek() because FfSeekRow() knows about MeatAxe file headers and adjusts the file pointer appropriately.

Parameters

f	Pointer to File.
pos	Row number (0-based).

Returns

0 on success, -1 on error.

FILE* FfWriteHeader	(	const char *	name,
		int	field,
		int	nor,
		int	noc
	)

Open File and Write Header.

This function opens a data file for input and writes the the file header. If the file does not exist, a new file is created. If the file exists it is overwritten.

Parameters

name	File name.
field	First header entry (usually the field order).
nor	Second header entry (usually the number of rows).
noc	Third header entry (usually the number of columns).

Returns

Pointer to open file, or |NULL| on error.

int FfWriteRows	(	FILE *	f,
		PTR	buf,
		int	n
	)

Write rows This function writes 1 or more rows to a file.

The row size must have been set before.

Parameters

f	Pointer to File.
buf	Pointer to data buffer.
n	Number of rows to write.

Returns

The number of rows that were successully written. A return value different from |n| indicates an error.