From 8a53533869defa1191b41f176a0312cb53a139e2 Mon Sep 17 00:00:00 2001 From: Jia Tan Date: Mon, 6 Feb 2023 21:35:06 +0800 Subject: liblzma: Improve documentation in filter.h. All functions now explicitly specify parameter and return values. The notes and code annotations were moved before the parameter and return value descriptions for consistency. Also, the description above lzma_filter_encoder_is_supported() about not being able to list available filters was removed since lzma_str_list_filters() will do this. --- src/liblzma/api/lzma/filter.h | 226 ++++++++++++++++++++++++++---------------- 1 file changed, 143 insertions(+), 83 deletions(-) (limited to 'src/liblzma') diff --git a/src/liblzma/api/lzma/filter.h b/src/liblzma/api/lzma/filter.h index 584ea463..e76daa19 100644 --- a/src/liblzma/api/lzma/filter.h +++ b/src/liblzma/api/lzma/filter.h @@ -69,12 +69,12 @@ typedef struct { /** * \brief Test if the given Filter ID is supported for encoding * - * Return true if the give Filter ID is supported for encoding by this - * liblzma build. Otherwise false is returned. + * \param id Filter ID * - * There is no way to list which filters are available in this particular - * liblzma version and build. It would be useless, because the application - * couldn't know what kind of options the filter would need. + * \return lzma_bool: + * - true if the Filter ID is supported for encoding by this + * liblzma build. + * - false otherwise. */ extern LZMA_API(lzma_bool) lzma_filter_encoder_is_supported(lzma_vli id) lzma_nothrow lzma_attr_const; @@ -83,8 +83,12 @@ extern LZMA_API(lzma_bool) lzma_filter_encoder_is_supported(lzma_vli id) /** * \brief Test if the given Filter ID is supported for decoding * - * Return true if the give Filter ID is supported for decoding by this - * liblzma build. Otherwise false is returned. + * \param id Filter ID + * + * \return lzma_bool: + * - true if the Filter ID is supported for decoding by this + * liblzma build. + * - false otherwise. */ extern LZMA_API(lzma_bool) lzma_filter_decoder_is_supported(lzma_vli id) lzma_nothrow lzma_attr_const; @@ -113,7 +117,14 @@ extern LZMA_API(lzma_bool) lzma_filter_decoder_is_supported(lzma_vli id) * array and leave its contents in an undefined state if an error occurs. * liblzma 5.2.7 and newer only modify the dest array when returning LZMA_OK. * - * \return - LZMA_OK + * \param src Array of filters terminated with + * .id == LZMA_VLI_UNKNOWN. + * \param[out] dest Destination filter array + * \param allocator lzma_allocator for custom allocator functions. + * Set to NULL to use malloc() and free(). + * + * \return Possible lzma_ret values: + * - LZMA_OK * - LZMA_MEM_ERROR * - LZMA_OPTIONS_ERROR: Unsupported Filter ID and its options * is not NULL. @@ -140,6 +151,11 @@ extern LZMA_API(lzma_ret) lzma_filters_copy( * * If filters is NULL, this does nothing but remember that this never frees * the filters array itself. + * + * \param filters Array of filters terminated with + * .id == LZMA_VLI_UNKNOWN. + * \param allocator lzma_allocator for custom allocator functions. + * Set to NULL to use malloc() and free(). */ extern LZMA_API(void) lzma_filters_free( lzma_filter *filters, const lzma_allocator *allocator) @@ -189,14 +205,16 @@ extern LZMA_API(uint64_t) lzma_raw_decoder_memusage(const lzma_filter *filters) * * This function may be useful when implementing custom file formats. * - * \param strm Pointer to properly prepared lzma_stream - * \param filters Array of lzma_filter structures. The end of the - * array must be marked with .id = LZMA_VLI_UNKNOWN. - * * The `action' with lzma_code() can be LZMA_RUN, LZMA_SYNC_FLUSH (if the * filter chain supports it), or LZMA_FINISH. * - * \return - LZMA_OK + * \param strm Pointer to lzma_stream that is at least + * initialized with LZMA_STREAM_INIT. + * \param filters Array of filters terminated with + * .id == LZMA_VLI_UNKNOWN. + * + * \return Possible lzma_ret values: + * - LZMA_OK * - LZMA_MEM_ERROR * - LZMA_OPTIONS_ERROR * - LZMA_PROG_ERROR @@ -214,7 +232,13 @@ extern LZMA_API(lzma_ret) lzma_raw_encoder( * The `action' with lzma_code() can be LZMA_RUN or LZMA_FINISH. Using * LZMA_FINISH is not required, it is supported just for convenience. * - * \return - LZMA_OK + * \param strm Pointer to lzma_stream that is at least + * initialized with LZMA_STREAM_INIT. + * \param filters Array of filters terminated with + * .id == LZMA_VLI_UNKNOWN. + * + * \return Possible lzma_ret values: + * - LZMA_OK * - LZMA_MEM_ERROR * - LZMA_OPTIONS_ERROR * - LZMA_PROG_ERROR @@ -250,7 +274,13 @@ extern LZMA_API(lzma_ret) lzma_raw_decoder( * as if LZMA_FULL_FLUSH (Stream encoders) or LZMA_SYNC_FLUSH (Raw or Block * encoder) had been used right before calling this function. * - * \return - LZMA_OK + * \param strm Pointer to lzma_stream that is at least + * initialized with LZMA_STREAM_INIT. + * \param filters Array of filters terminated with + * .id == LZMA_VLI_UNKNOWN. + * + * \return Possible lzma_ret values: + * - LZMA_OK * - LZMA_MEM_ERROR * - LZMA_MEMLIMIT_ERROR * - LZMA_OPTIONS_ERROR @@ -263,29 +293,30 @@ extern LZMA_API(lzma_ret) lzma_filters_update( /** * \brief Single-call raw encoder * - * \param filters Array of lzma_filter structures. The end of the - * array must be marked with .id = LZMA_VLI_UNKNOWN. + * \note There is no function to calculate how big output buffer + * would surely be big enough. (lzma_stream_buffer_bound() + * works only for lzma_stream_buffer_encode(); raw encoder + * won't necessarily meet that bound.) + * + * \param filters Array of filters terminated with + * .id == LZMA_VLI_UNKNOWN. * \param allocator lzma_allocator for custom allocator functions. * Set to NULL to use malloc() and free(). * \param in Beginning of the input buffer * \param in_size Size of the input buffer - * \param out Beginning of the output buffer - * \param out_pos The next byte will be written to out[*out_pos]. + * \param[out] out Beginning of the output buffer + * \param[out] out_pos The next byte will be written to out[*out_pos]. * *out_pos is updated only if encoding succeeds. * \param out_size Size of the out buffer; the first byte into * which no data is written to is out[out_size]. * - * \return - LZMA_OK: Encoding was successful. + * \return Possible lzma_ret values: + * - LZMA_OK: Encoding was successful. * - LZMA_BUF_ERROR: Not enough output buffer space. * - LZMA_OPTIONS_ERROR * - LZMA_MEM_ERROR * - LZMA_DATA_ERROR * - LZMA_PROG_ERROR - * - * \note There is no function to calculate how big output buffer - * would surely be big enough. (lzma_stream_buffer_bound() - * works only for lzma_stream_buffer_encode(); raw encoder - * won't necessarily meet that bound.) */ extern LZMA_API(lzma_ret) lzma_raw_buffer_encode( const lzma_filter *filters, const lzma_allocator *allocator, @@ -296,8 +327,8 @@ extern LZMA_API(lzma_ret) lzma_raw_buffer_encode( /** * \brief Single-call raw decoder * - * \param filters Array of lzma_filter structures. The end of the - * array must be marked with .id = LZMA_VLI_UNKNOWN. + * \param filters Array of filters terminated with + * .id == LZMA_VLI_UNKNOWN. * \param allocator lzma_allocator for custom allocator functions. * Set to NULL to use malloc() and free(). * \param in Beginning of the input buffer @@ -305,11 +336,19 @@ extern LZMA_API(lzma_ret) lzma_raw_buffer_encode( * *in_pos is updated only if decoding succeeds. * \param in_size Size of the input buffer; the first byte that * won't be read is in[in_size]. - * \param out Beginning of the output buffer - * \param out_pos The next byte will be written to out[*out_pos]. + * \param[out] out Beginning of the output buffer + * \param[out] out_pos The next byte will be written to out[*out_pos]. * *out_pos is updated only if encoding succeeds. * \param out_size Size of the out buffer; the first byte into * which no data is written to is out[out_size]. + * + * \return Possible lzma_ret values: + * - LZMA_OK: Decoding was successful. + * - LZMA_BUF_ERROR: Not enough output buffer space. + * - LZMA_OPTIONS_ERROR + * - LZMA_MEM_ERROR + * - LZMA_DATA_ERROR + * - LZMA_PROG_ERROR */ extern LZMA_API(lzma_ret) lzma_raw_buffer_decode( const lzma_filter *filters, const lzma_allocator *allocator, @@ -323,18 +362,19 @@ extern LZMA_API(lzma_ret) lzma_raw_buffer_decode( * This function may be useful when implementing custom file formats * using the raw encoder and decoder. * - * \param size Pointer to uint32_t to hold the size of the properties + * \note This function validates the Filter ID, but does not + * necessarily validate the options. Thus, it is possible + * that this returns LZMA_OK while the following call to + * lzma_properties_encode() returns LZMA_OPTIONS_ERROR. + * + * \param[out] size Pointer to uint32_t to hold the size of the properties * \param filter Filter ID and options (the size of the properties may * vary depending on the options) * - * \return - LZMA_OK + * \return Possible lzma_ret values: + * - LZMA_OK * - LZMA_OPTIONS_ERROR * - LZMA_PROG_ERROR - * - * \note This function validates the Filter ID, but does not - * necessarily validate the options. Thus, it is possible - * that this returns LZMA_OK while the following call to - * lzma_properties_encode() returns LZMA_OPTIONS_ERROR. */ extern LZMA_API(lzma_ret) lzma_properties_size( uint32_t *size, const lzma_filter *filter) lzma_nothrow; @@ -343,15 +383,6 @@ extern LZMA_API(lzma_ret) lzma_properties_size( /** * \brief Encode the Filter Properties field * - * \param filter Filter ID and options - * \param props Buffer to hold the encoded options. The size of - * buffer must have been already determined with - * lzma_properties_size(). - * - * \return - LZMA_OK - * - LZMA_OPTIONS_ERROR - * - LZMA_PROG_ERROR - * * \note Even this function won't validate more options than actually * necessary. Thus, it is possible that encoding the properties * succeeds but using the same options to initialize the encoder @@ -361,6 +392,15 @@ extern LZMA_API(lzma_ret) lzma_properties_size( * of the Filter Properties field is zero, calling * lzma_properties_encode() is not required, but it * won't do any harm either. + * + * \param filter Filter ID and options + * \param[out] props Buffer to hold the encoded options. The size of + * the buffer must have been already determined with + * lzma_properties_size(). + * + * \return Possible lzma_ret values: + * - LZMA_OK + * - LZMA_PROG_ERROR */ extern LZMA_API(lzma_ret) lzma_properties_encode( const lzma_filter *filter, uint8_t *props) lzma_nothrow; @@ -376,15 +416,16 @@ extern LZMA_API(lzma_ret) lzma_properties_encode( * it's application's responsibility to free it when * appropriate. filter->options is set to NULL if * there are no properties or if an error occurs. - * \param allocator Custom memory allocator used to allocate the - * options. Set to NULL to use the default malloc(), + * \param allocator lzma_allocator for custom allocator functions. + * Set to NULL to use malloc() and free(). * and in case of an error, also free(). * \param props Input buffer containing the properties. * \param props_size Size of the properties. This must be the exact * size; giving too much or too little input will * return LZMA_OPTIONS_ERROR. * - * \return - LZMA_OK + * \return Possible lzma_ret values: + * - LZMA_OK * - LZMA_OPTIONS_ERROR * - LZMA_MEM_ERROR */ @@ -399,18 +440,19 @@ extern LZMA_API(lzma_ret) lzma_properties_decode( * Knowing the size of Filter Flags is useful to know when allocating * memory to hold the encoded Filter Flags. * - * \param size Pointer to integer to hold the calculated size + * \note If you need to calculate size of List of Filter Flags, + * you need to loop over every lzma_filter entry. + * + * \param[out] size Pointer to integer to hold the calculated size * \param filter Filter ID and associated options whose encoded * size is to be calculated * - * \return - LZMA_OK: *size set successfully. Note that this doesn't + * \return Possible lzma_ret values: + * - LZMA_OK: *size set successfully. Note that this doesn't * guarantee that filter->options is valid, thus * lzma_filter_flags_encode() may still fail. * - LZMA_OPTIONS_ERROR: Unknown Filter ID or unsupported options. * - LZMA_PROG_ERROR: Invalid options - * - * \note If you need to calculate size of List of Filter Flags, - * you need to loop over every lzma_filter entry. */ extern LZMA_API(lzma_ret) lzma_filter_flags_size( uint32_t *size, const lzma_filter *filter) @@ -424,12 +466,13 @@ extern LZMA_API(lzma_ret) lzma_filter_flags_size( * This is due to how this function is used internally by liblzma. * * \param filter Filter ID and options to be encoded - * \param out Beginning of the output buffer - * \param out_pos out[*out_pos] is the next write position. This + * \param[out] out Beginning of the output buffer + * \param[out] out_pos out[*out_pos] is the next write position. This * is updated by the encoder. * \param out_size out[out_size] is the first byte to not write. * - * \return - LZMA_OK: Encoding was successful. + * \return Possible lzma_ret values: + * - LZMA_OK: Encoding was successful. * - LZMA_OPTIONS_ERROR: Invalid or unsupported options. * - LZMA_PROG_ERROR: Invalid options or not enough output * buffer space (you should have checked it with @@ -444,11 +487,26 @@ extern LZMA_API(lzma_ret) lzma_filter_flags_encode(const lzma_filter *filter, * \brief Decode Filter Flags from given buffer * * The decoded result is stored into *filter. The old value of - * filter->options is not free()d. + * filter->options is not free()d. If anything other than LZMA_OK + * is returned, filter->options is set to NULL. + * + * \param[out] filter Destination filter. The decoded Filter ID will + * be stored in filter->id. If options are needed + * they will be allocated and the pointer will be + * stored in filter->options. + * \param allocator lzma_allocator for custom allocator functions. + * Set to NULL to use malloc() and free(). + * \param in Beginning of the input buffer + * \param[out] in_pos The next byte will be read from in[*in_pos]. + * *in_pos is updated only if decoding succeeds. + * \param in_size Size of the input buffer; the first byte that + * won't be read is in[in_size]. * - * \return - LZMA_OK + * \return Possible lzma_ret values: + * - LZMA_OK * - LZMA_OPTIONS_ERROR * - LZMA_MEM_ERROR + * - LZMA_DATA_ERROR * - LZMA_PROG_ERROR */ extern LZMA_API(lzma_ret) lzma_filter_flags_decode( @@ -575,18 +633,36 @@ extern LZMA_API(lzma_ret) lzma_filter_flags_decode( * lzma_str_list_filters(). See the xz man page for the description * of filter names and options. * + * For command line applications, below is an example how an error message + * can be displayed. Note the use of an empty string for the field width. + * If "^" was used there it would create an off-by-one error except at + * the very beginning of the line. + * + * \code{.c} + * const char *str = ...; // From user + * lzma_filter filters[LZMA_FILTERS_MAX + 1]; + * int pos; + * const char *msg = lzma_str_to_filters(str, &pos, filters, 0, NULL); + * if (msg != NULL) { + * printf("%s: Error in XZ compression options:\n", argv[0]); + * printf("%s: %s\n", argv[0], str); + * printf("%s: %*s^\n", argv[0], errpos, ""); + * printf("%s: %s\n", argv[0], msg); + * } + * \endcode + * * \param str User-supplied string describing a preset or * a filter chain. If a default value is needed and * you don't know what would be good, use "6" since * that is the default preset in xz too. - * \param error_pos If this isn't NULL, this value will be set on + * \param[out] error_pos If this isn't NULL, this value will be set on * both success and on all errors. This tells the * location of the error in the string. This is * an int to make it straightforward to use this * as printf() field width. The value is guaranteed * to be in the range [0, INT_MAX] even if strlen(str) * somehow was greater than INT_MAX. - * \param filters An array of lzma_filter structures. There must + * \param[out] filters An array of lzma_filter structures. There must * be LZMA_FILTERS_MAX + 1 (that is, five) elements * in the array. The old contents are ignored so it * doesn't need to be initialized. This array is @@ -602,24 +678,6 @@ extern LZMA_API(lzma_ret) lzma_filter_flags_decode( * \return On success, NULL is returned. On error, a statically-allocated * error message is returned which together with the error_pos * should give some idea what is wrong. - * - * For command line applications, below is an example how an error message - * can be displayed. Note the use of an empty string for the field width. - * If "^" was used there it would create an off-by-one error except at - * the very beginning of the line. - * - * \code{.c} - * const char *str = ...; // From user - * lzma_filter filters[LZMA_FILTERS_MAX + 1]; - * int pos; - * const char *msg = lzma_str_to_filters(str, &pos, filters, 0, NULL); - * if (msg != NULL) { - * printf("%s: Error in XZ compression options:\n", argv[0]); - * printf("%s: %s\n", argv[0], str); - * printf("%s: %*s^\n", argv[0], errpos, ""); - * printf("%s: %s\n", argv[0], msg); - * } - * \endcode */ extern LZMA_API(const char *) lzma_str_to_filters( const char *str, int *error_pos, lzma_filter *filters, @@ -648,19 +706,20 @@ extern LZMA_API(const char *) lzma_str_to_filters( * specify "6" to lzma_str_to_filters() then lzma_str_from_filters() * will produce a string containing "lzma2". * - * \param str On success *str will be set to point to an + * \param[out] str On success *str will be set to point to an * allocated string describing the given filter * chain. Old value is ignored. On error *str is * always set to NULL. - * \param filters Array of 1-4 filters and a terminating element - * with .id = LZMA_VLI_UNKNOWN. + * \param filters Array of filters terminated with + * .id == LZMA_VLI_UNKNOWN. * \param flags Bitwise-or of zero or more of the flags * LZMA_STR_ENCODER, LZMA_STR_DECODER, * LZMA_STR_GETOPT_LONG, and LZMA_STR_NO_SPACES. * \param allocator lzma_allocator for custom allocator functions. * Set to NULL to use malloc() and free(). * - * \return - LZMA_OK + * \return Possible lzma_ret values: + * - LZMA_OK * - LZMA_OPTIONS_ERROR: Empty filter chain * (filters[0].id == LZMA_VLI_UNKNOWN) or the filter chain * includes a Filter ID that is not supported by this function. @@ -705,7 +764,8 @@ extern LZMA_API(lzma_ret) lzma_str_from_filters( * \param allocator lzma_allocator for custom allocator functions. * Set to NULL to use malloc() and free(). * - * \return - LZMA_OK + * \return Possible lzma_ret values: + * - LZMA_OK * - LZMA_OPTIONS_ERROR: Unsupported filter_id or flags * - LZMA_MEM_ERROR * - LZMA_PROG_ERROR -- cgit v1.2.3