stdio-like API and utilities More...

Functions
SquashFile *	squash_file_open (const char codec, const char filename, const char *mode,...)
	Open a file. More...

SquashFile *	squash_file_open_codec (SquashCodec codec, const char filename, const char *mode,...)
	Open a file using a codec instance. More...

SquashFile *	squash_file_open_with_options (const char codec, const char filename, const char mode, SquashOptions options)
	Open a file with the specified options. More...

SquashFile *	squash_file_open_codec_with_options (SquashCodec codec, const char filename, const char mode, SquashOptions options)
	Open a file using a codec instance with the specified options. More...

SquashFile *	squash_file_steal (const char codec, FILE fp,...)
	Open an existing stdio file. More...

SquashFile *	squash_file_steal_codec (SquashCodec codec, FILE fp,...)
	Open an existing stdio file using a codec instance. More...

SquashFile *	squash_file_steal_with_options (const char codec, FILE fp, SquashOptions *options)
	Open an existing stdio file with the specified options. More...

SquashFile *	squash_file_steal_codec_with_options (SquashCodec codec, FILE fp, SquashOptions *options)
	Open an existing stdio file using a codec instance with the specified options. More...

SquashStatus	squash_file_read (SquashFile file, size_t decompressed_length, uint8_t decompressed[SQUASH_ARRAY_PARAM(*decompressed_length)])
	Read from a compressed file. More...

SquashStatus	squash_file_write (SquashFile *file, size_t uncompressed_length, const uint8_t uncompressed[SQUASH_ARRAY_PARAM(uncompressed_length)])
	Write data to a compressed file. More...

SquashStatus	squash_file_flush (SquashFile *file)
	immediately write any buffered data to a file More...

bool	squash_file_eof (SquashFile *file)
	Determine whether the file has reached the end of file. More...

SquashStatus	squash_splice (const char codec, SquashStreamType stream_type, FILE fp_out, FILE *fp_in, size_t length,...)
	compress or decompress the contents of one file to another More...

SquashStatus	squash_splice_codec (SquashCodec codec, SquashStreamType stream_type, FILE fp_out, FILE *fp_in, size_t length,...)
	compress or decompress the contents of one file to another More...

SquashStatus	squash_splice_with_options (const char codec, SquashStreamType stream_type, FILE fp_out, FILE fp_in, size_t length, SquashOptions options)
	compress or decompress the contents of one file to another More...

SquashStatus	squash_splice_codec_with_options (SquashCodec codec, SquashStreamType stream_type, FILE fp_out, FILE fp_in, size_t length, SquashOptions options)
	compress or decompress the contents of one file to another More...

SquashStatus	squash_file_close (SquashFile *file)
	Close a file. More...

SquashStatus	squash_file_free (SquashFile file, FILE *fp)
	Free a file. More...

Detailed Description

stdio-like API and utilities

These functions provide an API which should be familiar for those used to dealing with the standard I/O functions.

Additionally, a splice function family is provided which is inspired by the Linux-specific splice(2) function.

Function Documentation

SquashStatus squash_file_close ( SquashFile * file )

Close a file.

If file is a compressor the stream will finish compressing, writing any buffered data. For codecs which do not provide a native streaming interface, all of the actual compression will take place during this call. In other words, it may block for a non-trivial period. If this is a problem please file a bug against Squash (including your use case), and we can discuss adding a function call which will simply abort compression.

In addition to freeing the SquashFile instance, this function will close the underlying FILE pointer. If you wish to continue using the FILE for something else, use squash_file_free instead.

Parameters

file	file to close

Returns: SQUASH_OK on success or a negative error code on failure

Definition at line 1003 of file file.c.

bool squash_file_eof ( SquashFile * file )

Determine whether the file has reached the end of file.

Parameters

file	file to check

Returns: TRUE if EOF was reached, FALSE otherwise

Definition at line 632 of file file.c.

SquashStatus squash_file_flush ( SquashFile * file )

immediately write any buffered data to a file

Note: This function only works for codecs which support flushing (see the SQUASH_CODEC_INFO_CAN_FLUSH flag in the return value of squash_codec_get_info).

Parameters

file	file to flush

Returns: TRUE if flushing succeeeded, FALSE if flushing is not supported or there was another error.

Definition at line 619 of file file.c.

SquashStatus squash_file_free	(	SquashFile *	file,
		FILE **	fp
	)

Free a file.

This function will free the SquashFile, but unlike squash_file_close it will not actually close the underlying FILE

pointer. Instead, it will return the value in the fp argument, allowing you to further manipulate it.

Parameters

	file	file to free
[out]	fp	location to store the underlying FILE pointer

Returns: SQUASH_OK on success or a negative error code on failure

Definition at line 1026 of file file.c.

SquashFile* squash_file_open	(	const char *	codec,
		const char *	filename,
		const char *	mode,
			...
	)

Open a file.

The mode parameter will be passed through to fopen, so the value must valid. Note that Squash may attempt to use mmap regardless of whether the m flag is passed.

The file is always assumed to be compressed—calling squash_file_write will always compress, and calling squash_file_read will always decompress. Note, however, that you cannot mix reading and writing to the same file as you can with a standard FILE.

Note: Error handling for this function is somewhat limited, and it may be difficult to determine the exact nature of problems such as an invalid codec, where errno is not set. If this is unacceptable you should call squash_get_codec and squash_options_parse yourself and pass the results to squash_file_open_codec_with_options (which will only fail due to the underlying fopen failing).

Parameters

filename	name of the file to open
mode	file mode
codec	codec to use
...	options

Returns: The opened file, or NULL on error

See also: squash_file_open_codec; squash_file_open_with_options; squash_file_open_codec_with_options

Definition at line 213 of file file.c.

SquashFile* squash_file_open_codec	(	SquashCodec *	codec,
		const char *	filename,
		const char *	mode,
			...
	)

Open a file using a codec instance.

Parameters

filename	name of the file to open
mode	file mode
codec	codec to use
...	options

Returns: The opened file, or NULL on error

See also: squash_file_open

Definition at line 244 of file file.c.

SquashFile* squash_file_open_codec_with_options	(	SquashCodec *	codec,
		const char *	filename,
		const char *	mode,
		SquashOptions *	options
	)

Open a file using a codec instance with the specified options.

Parameters

filename	name of the file to open
mode	file mode
codec	codec to use
options	options

Returns: The opened file, or NULL on error

See also: squash_file_open

Definition at line 293 of file file.c.

SquashFile* squash_file_open_with_options	(	const char *	codec,
		const char *	filename,
		const char *	mode,
		SquashOptions *	options
	)

Open a file with the specified options.

Parameters

filename	name of the file to open
mode	file mode
codec	codec to use
options	options

Returns: The opened file, or NULL on error

See also: squash_file_open

Definition at line 270 of file file.c.

SquashStatus squash_file_read	(	SquashFile *	file,
		size_t *	decompressed_length,
		uint8_t	decompressed[SQUASH_ARRAY_PARAM(*decompressed_length)]
	)

Read from a compressed file.

Attempt to read decompressed_length bytes of decompressed data into the decompressed buffer. The number of bytes of compressed data read from the input file may be significantly more, or less, than decompressed_length.

The number of decompressed bytes successfully read from the file will be stored in decompressed_read after this function is execute. This value will never be greater than decompressed_length, but it may be less if there was an error or the end of the input file was reached.

Parameters

file	the file to read from
decompressed_length	number of bytes to attempt to write to decompressed
decompressed	buffer to write the decompressed data to

Returns: the result of the operation

Return values

SQUASH_OK	successfully read some data
SQUASH_END_OF_STREAM	the end of the file was reached

Definition at line 439 of file file.c.

SquashFile* squash_file_steal	(	const char *	codec,
		FILE *	fp,
			...
	)

Open an existing stdio file.

Parameters

fp	the stdio file to use
codec	codec to use
...	options

Returns: The opened file, or NULL on error

See also: squash_file_steal_codec; squash_file_steal_with_options; squash_file_steal_codec_with_options

Definition at line 318 of file file.c.

SquashFile* squash_file_steal_codec	(	SquashCodec *	codec,
		FILE *	fp,
			...
	)

Open an existing stdio file using a codec instance.

Parameters

fp	the stdio file to use
codec	codec to use
...	options

Returns: The opened file, or NULL on error

See also: squash_file_steal_codec; squash_file_steal_with_options; squash_file_steal_codec_with_options

Definition at line 347 of file file.c.

SquashFile* squash_file_steal_codec_with_options	(	SquashCodec *	codec,
		FILE *	fp,
		SquashOptions *	options
	)

Open an existing stdio file using a codec instance with the specified options.

Parameters

fp	the stdio file to use
codec	codec to use
options	options

Returns: The opened file, or NULL on error

See also: squash_file_steal_codec; squash_file_steal_with_options; squash_file_steal_codec_with_options

Definition at line 396 of file file.c.

SquashFile* squash_file_steal_with_options	(	const char *	codec,
		FILE *	fp,
		SquashOptions *	options
	)

Open an existing stdio file with the specified options.

Parameters

fp	the stdio file to use
codec	codec to use
options	options

Returns: The opened file, or NULL on error

See also: squash_file_steal_codec; squash_file_steal_with_options; squash_file_steal_codec_with_options

Definition at line 373 of file file.c.

SquashStatus squash_file_write	(	SquashFile *	file,
		size_t	uncompressed_length,
		const uint8_t	uncompressed[SQUASH_ARRAY_PARAM(uncompressed_length)]
	)

Write data to a compressed file.

Attempt to write the compressed equivalent of uncompressed to a file. The number of bytes of compressed data written to the output file may be significantly more, or less, than the uncompressed_length.

Note: It is likely the compressed data will actually be buffered, not immediately written to the file. For codecs which support flushing you can use squash_file_flush to flush the data, otherwise the data may not be written until squash_file_close or squash_file_free is called.

Parameters

file	file to write to
uncompressed_length	number of bytes of uncompressed data in uncompressed to attempt to write
uncompressed	data to write

Returns: result of the operation

Definition at line 601 of file file.c.

SquashStatus squash_splice	(	const char *	codec,
		SquashStreamType	stream_type,
		FILE *	fp_out,
		FILE *	fp_in,
		size_t	length,
			...
	)

compress or decompress the contents of one file to another

This function will attempt to compress or decompress the contents of one file to another. It will attempt to use memory-mapped files in order to reduce memory usage and increase performance, and so should be preferred over writing similar code manually.

Parameters

fp_in	the input FILE pointer
fp_out	the output FILE pointer
length	number of bytes (uncompressed) to transfer from fp_in to fp_out, or 0 to transfer the entire file
stream_type	whether to compress or decompress the data
codec	the name of the codec to use
...	list of options (with a NULL sentinel)

Returns: SQUASH_OK on success, or a negative error code on failure

Definition at line 655 of file file.c.

SquashStatus squash_splice_codec	(	SquashCodec *	codec,
		SquashStreamType	stream_type,
		FILE *	fp_out,
		FILE *	fp_in,
		size_t	length,
			...
	)

compress or decompress the contents of one file to another

This function will attempt to compress or decompress the contents of one file to another. It will attempt to use memory-mapped files in order to reduce memory usage and increase performance, and so should be preferred over writing similar code manually.

Parameters

fp_in	the input FILE pointer
fp_out	the output FILE pointer
length	number of bytes (uncompressed) to transfer from fp_in to fp_out
stream_type	whether to compress or decompress the data
codec	codec to use
...	list of options (with a NULL sentinel)

Returns: SQUASH_OK on success, or a negative error code on failure

Definition at line 692 of file file.c.

SquashStatus squash_splice_codec_with_options	(	SquashCodec *	codec,
		SquashStreamType	stream_type,
		FILE *	fp_out,
		FILE *	fp_in,
		size_t	length,
		SquashOptions *	options
	)

compress or decompress the contents of one file to another

This function will attempt to compress or decompress the contents of one file to another. It will attempt to use memory-mapped files in order to reduce memory usage and increase performance, and so should be preferred over writing similar code manually.

Parameters

fp_in	the input FILE pointer
fp_out	the output FILE pointer
length	number of bytes (uncompressed) to transfer from fp_in to fp_out
stream_type	whether to compress or decompress the data
codec	codec to use
options	options to pass to the codec

Returns: SQUASH_OK on success, or a negative error code on failure

Definition at line 960 of file file.c.

SquashStatus squash_splice_with_options	(	const char *	codec,
		SquashStreamType	stream_type,
		FILE *	fp_out,
		FILE *	fp_in,
		size_t	length,
		SquashOptions *	options
	)

compress or decompress the contents of one file to another

This function will attempt to compress or decompress the contents of one file to another. It will attempt to use memory-mapped files in order to reduce memory usage and increase performance, and so should be preferred over writing similar code manually.

Parameters

fp_in	the input FILE pointer
fp_out	the output FILE pointer
length	number of bytes (uncompressed) to transfer from fp_in to fp_out
stream_type	whether to compress or decompress the data
codec	name of the codec to use
options	options to pass to the codec

Returns: SQUASH_OK on success, or a negative error code on failure

Definition at line 726 of file file.c.

Functions

Detailed Description

Function Documentation