bit.h File Reference

Bit-wise file or memory access. More...

Data Structures
struct	t_bit_file
	Handle to a bit-stream file. More...
Functions
t_bit_file *	bit_open (char *name, const char *mode, int num_bits)
	Opens a file as a bit-stream.
int	bit_close (t_bit_file *f, unsigned char **mem)
	Close a bit-stream file opened with bit_open().
void	bit_free (unsigned char *mem)
	Frees an internally allocated memory buffer returned by bit_close().
unsigned int	bit_read (int num, t_bit_file *f)
	Reads the given number of bits from a bit-stream file.
unsigned int	bit_read_single (t_bit_file *f)
	Reads a single bit from a bit-stream file.
int	bit_write (const unsigned int bits, int num, t_bit_file *f)
	Writes the given number of bits to a bit-stream file.

---

Detailed Description

Bit-wise file or memory access.

---

Function Documentation

int bit_close	(	t_bit_file *	f,
		unsigned char **	mem
	)

Close a bit-stream file opened with bit_open().

This function flushes all writes to disk / memory (if applicable) and then deallocates the handle.

Parameters:

[in]	f	bit-stream file that is to be closed.
[out]	mem	when not NULL, it receives the pointer to the buffer (which is allocated automatically when writing to memory and NULL passed in originally).

Returns:

number of bits read or written

void bit_free

(

unsigned char *

mem

)

Frees an internally allocated memory buffer returned by bit_close().

Parameters:

[in]

mem

Pointer returned by bit_close() that was not originally provided by the user.

t_bit_file* bit_open	(	char *	name,
		const char *	mode,
		int	num_bits
	)

Opens a file as a bit-stream.

Reminiscient of fopen(), this function allows for reading and writing to files on a bit-level basis from either disk or memory.

Parameters:

[in]	name	filename of the file to be opened. Alternatively, for memory- based read-access (i.e. mode == "rm") pointer to the region to be read. When writing to memory and num_bits > 0, used as user-provided target buffer..
[in]	mode	string that specifies the operation. mode[0] = 'r' or 'w' (read or write), mode[1] = 'b' or 'm' (file or memory).
[in]	num_bits	is the number of bits available (or to be used from a file) when reading, or the maximum number of bits to write. Reads in excess of num_bits produces 0s, further writes are simply ignored.

Returns:

the bit-file handle, or NULL on failure.

unsigned int bit_read	(	int	num,
		t_bit_file *	f
	)

Reads the given number of bits from a bit-stream file.

The file has to be openened in read-mode for this to work.

Parameters:

[in]	num	is the number of bits to be read. This value can be larger than 32, but then earlier bits are lost as they are shifted out of the variable.
[in]	f	bit-stream file from which to read (read-mode).

Returns:

the bits as an unsigned integer (bits read first are in higher bit-positions).

unsigned int bit_read_single

(

t_bit_file *

f

)

Reads a single bit from a bit-stream file.

The file has to be openened in read-mode for this to work. This is slightly faster than using bit_read() for a single bit.

Parameters:

[in]

f

bit-stream file from which to read (read-mode).

Returns:

the next bit from f as an unsigned integer.

int bit_write	(	const unsigned int	bits,
		int	num,
		t_bit_file *	f
	)

Writes the given number of bits to a bit-stream file.

The file has to be openened in write-mode for this to work.

Parameters:

[in]	bits	are the bits to write. More significant bits are written before less significant ones.
[in]	num	is the number of bits to write. This value can be larger than 32, but the respective bits are obviously written as 0-bits.
[in]	f	bit-stream file to which to write (write-mode).

Returns:

the number of bits actually written.

---