mirror of
https://github.com/freebsd/freebsd-src.git
synced 2026-10-31 04:45:39 +01:00
Garth Snyder
47bb43aab8
This PR makes several changes to the user-facing command line syntax and documentation: - The `decompress,` `drop_records,` and `recompress` subcommands now allow naming a stream file on the command line, bringing them into line with `dump` and `raw.` Reading from standard input remains an option. - Tests have been modified to exercise command-line specification of input files. - The man page has been updated and copy edited. - Subcommands are presented in a consistent (alphabetical) order in the man page, the usage message, and the source code. - The man page and usage message now use identical names and capitalization for options. - The `decompress` and `recompress` subcommands now use `zfs_prop_string_to_index()` from `libzfs` to parse compression specifiers. Wherever a compression type is required, users can specify any value accepted by the `compression` property except `on`, e.g., `zstd-10`. In previous versions, these subcommands had their own parsers. - The `-l` option to `recompress` (for specifying a zstd compression level) is now described as deprecated in the man page. It no longer appears in the usage message. For the most part, `-l` still works as before. However, it now prints a deprecation warning and tells you what to use instead. It's also more strict about insisting on being used only in combination with 'zstd'. Previously, the `-l` option was accepted but silently ignored when used with non-zstd compression methods. Various permutations of -l and compression specifiers are tested by ZTS. - Since it can accept more than one record specifier, the `drop_record` subcommand has been renamed `drop_records`. `drop_record` remains as an (undocumented) alias for `drop_records`. - `decompress` and `drop_records` now share a parser for record specifiers. - Since `decompress` and `drop_records` now accept a filename as their last command line argument, there is a potential ambiguity as to whether the last argument is a filename or a record specifier. This will likely be invisible to users because `object,offset` specifiers are distinctively spelled. Broadly speaking, if an argument is parsable as a record specifier, it's assumed to be a record specifier. Error messages may be blurry for the last command line argument, e.g., "invalid record specifier or input file '123,'". It is always possibile to take input from stdin if the command line parser won't read your stream file named `123,456`. - Hash table management for `decompress` and `drop_records` is now shared and moved into `zstream_util.c`. As of now this still uses hcreate() et al, but I have a hash table update coming that should obviate the need to convert to string keys. The full command line grammar is now: ``` zstream decompress [-v] [object,offset[,compress_type]...] [file] zstream drop_records [-v] [object,offset...] [file] zstream dump [-Cvd] [file] zstream raw [-v] [-b max_buffers] [-g fromguid] image|device [file] zstream recompress [-t num_threads] compress_type [file] zstream redup [-v] file zstream token resume_token ``` `decompress` and `drop_records` are the only two subcommands that operate on individual records. Arguably, they should be brought into closer alignment either by renaming `decompress` to `decompress_records` or renaming `drop_records` to `drop`. I rather like the `_records` suffix to mark record-specific operations, but `decompress_records` is long, and both renaming options seem more disruptive than they're worth. ## Does this break things that used to work? Only `recompress -l` when used with non-zstd compression methods. That shouldn't have been accepted in the past since it probably doesn't do what users expect. It now produces an error message. Reviewed-by: Brian Behlendorf <[email protected]> Signed-off-by: Garth Snyder <[email protected]> Closes #19109