Squash  0.7.0
Functions
SquashFile

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
filefile 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
filefile 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
filefile 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
filefile to free
[out]fplocation 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
filenamename of the file to open
modefile mode
codeccodec 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
filenamename of the file to open
modefile mode
codeccodec 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
filenamename of the file to open
modefile mode
codeccodec to use
optionsoptions
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
filenamename of the file to open
modefile mode
codeccodec to use
optionsoptions
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
filethe file to read from
decompressed_lengthnumber of bytes to attempt to write to decompressed
decompressedbuffer to write the decompressed data to
Returns
the result of the operation
Return values
SQUASH_OKsuccessfully read some data
SQUASH_END_OF_STREAMthe 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
fpthe stdio file to use
codeccodec 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
fpthe stdio file to use
codeccodec 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
fpthe stdio file to use
codeccodec to use
optionsoptions
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
fpthe stdio file to use
codeccodec to use
optionsoptions
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
filefile to write to
uncompressed_lengthnumber of bytes of uncompressed data in uncompressed to attempt to write
uncompresseddata 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_inthe input FILE pointer
fp_outthe output FILE pointer
lengthnumber of bytes (uncompressed) to transfer from fp_in to fp_out, or 0 to transfer the entire file
stream_typewhether to compress or decompress the data
codecthe 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_inthe input FILE pointer
fp_outthe output FILE pointer
lengthnumber of bytes (uncompressed) to transfer from fp_in to fp_out
stream_typewhether to compress or decompress the data
codeccodec 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_inthe input FILE pointer
fp_outthe output FILE pointer
lengthnumber of bytes (uncompressed) to transfer from fp_in to fp_out
stream_typewhether to compress or decompress the data
codeccodec to use
optionsoptions 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_inthe input FILE pointer
fp_outthe output FILE pointer
lengthnumber of bytes (uncompressed) to transfer from fp_in to fp_out
stream_typewhether to compress or decompress the data
codecname of the codec to use
optionsoptions 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.