tor  0.4.0.0-alpha-dev
Macros | Typedefs | Enumerations | Functions
compress.h File Reference
#include <stddef.h>
#include "lib/testsupport/testsupport.h"

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 enum compress_method_t compress_method_t
 
typedef enum compression_level_t compression_level_t
 
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_ttor_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)
 
int tor_compress_init (void)
 
void tor_compress_log_init_warnings (void)
 
int buf_add_compress (struct buf_t *buf, struct tor_compress_state_t *state, const char *data, size_t data_len, int done)
 

Detailed Description

Headers for compress.c.

Definition in file compress.h.

Typedef Documentation

◆ 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

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

◆ tor_compress_state_t

Internal state for an incremental compression/decompression.

Definition at line 76 of file compress.h.

Enumeration Type Documentation

◆ 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.

Definition at line 21 of file compress.h.

◆ 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.

Definition at line 35 of file compress.h.

◆ tor_compress_output_t

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

Definition at line 68 of file compress.h.

Function Documentation

◆ buf_add_compress()

int buf_add_compress ( buf_t *  buf,
tor_compress_state_t state,
const char *  data,
size_t  data_len,
const int  done 
)

Compress or uncompress the data_len bytes in data using the compression state state, appending the result to buf. If done is true, flush the data in the state and finish the compression/uncompression. Return -1 on failure, 0 on success.

Definition at line 31 of file compress_buf.c.

References buf_add_chunk_with_capacity(), and tor_compress_process().

Referenced by MOCK_IMPL().

◆ 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.

Definition at line 403 of file compress.c.

◆ 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.

Definition at line 390 of file compress.c.

◆ 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.

Definition at line 364 of file compress.c.

◆ 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.

Definition at line 284 of file compress.c.

◆ 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.

Definition at line 242 of file compress.c.

◆ tor_compress_free_()

void tor_compress_free_ ( tor_compress_state_t state)

Deallocate state.

Definition at line 610 of file compress.c.

References tor_compress_state_t::method.

◆ 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.

Definition at line 328 of file compress.c.

◆ 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.

Definition at line 458 of file compress.c.

References atomic_counter_get(), tor_lzma_get_total_allocation(), tor_zlib_get_total_allocation(), tor_zstd_get_total_allocation(), and total_compress_allocation.

◆ 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.

Definition at line 438 of file compress.c.

◆ tor_compress_init()

int tor_compress_init ( void  )

Initialize all compression modules.

Definition at line 666 of file compress.c.

References atomic_counter_init(), tor_lzma_init(), tor_zlib_init(), tor_zstd_init(), and total_compress_allocation.

◆ 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.)

Definition at line 682 of file compress.c.

References tor_zstd_warn_if_version_mismatched().

◆ 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.

Definition at line 481 of file compress.c.

◆ 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.

Definition at line 549 of file compress.c.

References tor_assert().

Referenced by buf_add_compress().

◆ 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.

Definition at line 639 of file compress.c.

References tor_compress_state_t::method, and tor_assert().

◆ tor_compress_supports_method()

int tor_compress_supports_method ( compress_method_t  method)

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

Definition at line 304 of file compress.c.

◆ 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.

Definition at line 417 of file compress.c.

◆ 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.

Definition at line 268 of file compress.c.