compress.h File Reference

Headers for compress.c. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	tor_compress_free(st)   FREE_AND_NULL(tor_compress_state_t, tor_compress_free_, (st))

Typedefs
typedef struct tor_compress_state_t	tor_compress_state_t

Enumerations
enum	compress_method_t {   NO_METHOD =0, GZIP_METHOD =1, ZLIB_METHOD =2, LZMA_METHOD =3,   ZSTD_METHOD =4, UNKNOWN_METHOD =5 }
enum	compression_level_t { BEST_COMPRESSION, HIGH_COMPRESSION, MEDIUM_COMPRESSION, LOW_COMPRESSION }
enum	tor_compress_output_t { TOR_COMPRESS_OK, TOR_COMPRESS_DONE, TOR_COMPRESS_BUFFER_FULL, TOR_COMPRESS_ERROR }

Functions
int	tor_compress (char **out, size_t *out_len, const char *in, size_t in_len, compress_method_t method)
int	tor_uncompress (char **out, size_t *out_len, const char *in, size_t in_len, compress_method_t method, int complete_only, int protocol_warn_level)
compress_method_t	detect_compression_method (const char *in, size_t in_len)
	MOCK_DECL (int, tor_compress_is_compression_bomb,(size_t size_in, size_t size_out))
int	tor_compress_supports_method (compress_method_t method)
unsigned	tor_compress_get_supported_method_bitmask (void)
const char *	compression_method_get_name (compress_method_t method)
const char *	compression_method_get_human_name (compress_method_t method)
compress_method_t	compression_method_get_by_name (const char *name)
const char *	tor_compress_version_str (compress_method_t method)
const char *	tor_compress_header_version_str (compress_method_t method)
size_t	tor_compress_get_total_allocation (void)
tor_compress_state_t *	tor_compress_new (int compress, compress_method_t method, compression_level_t level)
tor_compress_output_t	tor_compress_process (tor_compress_state_t *state, char **out, size_t *out_len, const char **in, size_t *in_len, int finish)
void	tor_compress_free_ (tor_compress_state_t *state)
size_t	tor_compress_state_size (const tor_compress_state_t *state)
void	tor_compress_init (void)
void	tor_compress_log_init_warnings (void)

Detailed Description

Headers for compress.c.

Typedef Documentation

tor_compress_state_t

typedef struct tor_compress_state_t tor_compress_state_t

Internal state for an incremental compression/decompression.

Enumeration Type Documentation

compress_method_t

enum compress_method_t

Enumeration of what kind of compression to use. Only ZLIB_METHOD and GZIP_METHOD is guaranteed to be supported by the compress/uncompress functions here. Call tor_compress_supports_method() to check if a given compression schema is supported by Tor.

compression_level_t

enum compression_level_t

Enumeration to define tradeoffs between memory usage and compression level. BEST_COMPRESSION saves the most bandwidth; LOW_COMPRESSION saves the most memory.

tor_compress_output_t

enum tor_compress_output_t

Return values from tor_compress_process; see that function's documentation for details.

Function Documentation

compression_method_get_by_name()

compress_method_t compression_method_get_by_name

(

const char *

name

)

Return the compression method represented by the string name, or UNKNOWN_METHOD if the string isn't recognized.

compression_method_get_human_name()

const char* compression_method_get_human_name

(

compress_method_t

method

)

Return a human readable string representation of the compression method method, or NULL if the method isn't recognized.

compression_method_get_name()

const char* compression_method_get_name

(

compress_method_t

method

)

Return the canonical string representation of the compression method method, or NULL if the method isn't recognized.

detect_compression_method()

compress_method_t detect_compression_method	(	const char *	in,
		size_t	in_len
	)

Try to tell whether the in_len-byte string in in is likely to be compressed or not. If it is, return the likeliest compression method. Otherwise, return UNKNOWN_METHOD.

tor_compress()

int tor_compress	(	char **	out,
		size_t *	out_len,
		const char *	in,
		size_t	in_len,
		compress_method_t	method
	)

Given in_len bytes at in, compress them into a newly allocated buffer, using the method described in method. Store the compressed string in *out, and its length in *out_len. Return 0 on success, -1 on failure.

tor_compress_free_()

void tor_compress_free_

(

tor_compress_state_t *

state

)

Deallocate state.

tor_compress_get_supported_method_bitmask()

unsigned tor_compress_get_supported_method_bitmask

(

void

)

Return a bitmask of the supported compression types, where 1<<m is set in the bitmask if and only if compression with method m is supported.

tor_compress_get_total_allocation()

size_t tor_compress_get_total_allocation

(

void

)

Return the approximate number of bytes allocated for all supported compression schemas.

Here is the call graph for this function:

tor_compress_header_version_str()

const char* tor_compress_header_version_str

(

compress_method_t

method

)

Return a string representation of the version of the library, found at compile time, providing the compression method given in method. Returns NULL if method is unknown or unsupported.

tor_compress_init()

void tor_compress_init

(

void

)

Initialize all compression modules.

Here is the call graph for this function:

Here is the caller graph for this function:

tor_compress_log_init_warnings()

void tor_compress_log_init_warnings

(

void

)

Warn if we had any problems while setting up our compression libraries.

(This isn't part of tor_compress_init, since the logs aren't set up yet.)

Here is the call graph for this function:

tor_compress_new()

tor_compress_state_t* tor_compress_new	(	int	compress,
		compress_method_t	method,
		compression_level_t	compression_level
	)

Construct and return a tor_compress_state_t object using method. If compress, it's for compression; otherwise it's for decompression.

tor_compress_process()

tor_compress_output_t tor_compress_process	(	tor_compress_state_t *	state,
		char **	out,
		size_t *	out_len,
		const char **	in,
		size_t *	in_len,
		int	finish
	)

Compress/decompress some bytes using state. Read up to *in_len bytes from *in, and write up to *out_len bytes to *out, adjusting the values as we go. If finish is true, we've reached the end of the input.

Return TOR_COMPRESS_DONE if we've finished the entire compression/decompression. Return TOR_COMPRESS_OK if we're processed everything from the input. Return TOR_COMPRESS_BUFFER_FULL if we're out of space on out. Return TOR_COMPRESS_ERROR if the stream is corrupt.

Here is the caller graph for this function:

tor_compress_state_size()

size_t tor_compress_state_size

(

const tor_compress_state_t *

state

)

Return the approximate number of bytes allocated for state.

tor_compress_supports_method()

int tor_compress_supports_method

(

compress_method_t

method

)

Return 1 if a given method is supported; otherwise 0.

tor_compress_version_str()

const char* tor_compress_version_str

(

compress_method_t

method

)

Return a string representation of the version of the library providing the compression method given in method. Returns NULL if method is unknown or unsupported.

tor_uncompress()

int tor_uncompress	(	char **	out,
		size_t *	out_len,
		const char *	in,
		size_t	in_len,
		compress_method_t	method,
		int	complete_only,
		int	protocol_warn_level
	)

Given zero or more compressed strings of total length in_len bytes at in, uncompress them into a newly allocated buffer, using the method described in method. Store the uncompressed string in *out, and its length in *out_len. Return 0 on success, -1 on failure.

If any bytes are written to out, an extra byte NUL is always written at the end, but not counted in out_len. This is a safety feature to ensure that the output can be treated as a NUL-terminated string – though of course, callers should check out_len anyway.

If complete_only is true, we consider a truncated input as a failure; otherwise we decompress as much as we can. Warn about truncated or corrupt inputs at protocol_warn_level.