From 023cf22a596e183f6983fc6cdd9cdad9dc2b8489 Mon Sep 17 00:00:00 2001 From: Andrew Wood Date: Mon, 13 Oct 2025 21:26:24 +0100 Subject: [PATCH] Add --sparse / -O to the manual, to --help, and to option processing (#45). --- docs/pv.1 | 13 ++++++++++--- docs/pv.1.md | 17 ++++++++++++----- src/main/help.c | 3 +++ src/main/options.c | 8 +++++++- 4 files changed, 32 insertions(+), 9 deletions(-) diff --git a/docs/pv.1 b/docs/pv.1 index 09aa53f..2c89f55 100644 --- a/docs/pv.1 +++ b/docs/pv.1 @@ -273,9 +273,9 @@ from or to a pipe than regular \fBread\fR(2) and \fBwrite\fR(2), but means that the transfer buffer may not be used. This prevents \*(lq\fB\-\-buffer\-percent\fR\*(rq and \*(lq\fB\-\-last\-written\fR\*(rq from working, cannot work with -\*(lq\fB\-\-discard\fR\*(rq, and makes \*(lq\fB\-\-buffer\-size\fR\*(rq -redundant, so using any of those options automatically switches on -\*(lq\fB\-\-no\-splice\fR\*(rq. +\*(lq\fB\-\-sparse\fR\*(rq or \*(lq\fB\-\-discard\fR\*(rq, and makes +\*(lq\fB\-\-buffer\-size\fR\*(rq redundant, so using any of those options +automatically switches on \*(lq\fB\-\-no\-splice\fR\*(rq. Switching on this option results in a small loss of transfer efficiency. It has no effect on systems where \fBsplice\fR(2) is unavailable. .TP @@ -325,6 +325,13 @@ failures with an error of \*(lqInvalid argument\*(rq, especially if reading and writing files across a variety of filesystems in a single \fBpv\fR call. Use this option with caution. .TP +.B \-O, \-\-sparse +When writing null bytes, try to seek, producing a sparse output file. +Implies \*(lq\fB\-\-no\-splice\fR\*(rq. +On filesystems without sparse file support, or when the output is not +seekable, this option will have no effect other than to turn on +\*(lq\fB\-\-no\-splice\fR\*(rq. +.TP .B \-X, \-\-discard Instead of transferring input data to standard output, discard it. This is equivalent to redirecting standard output to \fI/dev/null\fR, diff --git a/docs/pv.1.md b/docs/pv.1.md index dedc28c..553dbbd 100644 --- a/docs/pv.1.md +++ b/docs/pv.1.md @@ -281,11 +281,11 @@ are explicitly switched on will be shown. data from or to a pipe than regular **read**(2) and **write**(2), but means that the transfer buffer may not be used. This prevents "**\--buffer-percent**" and "**\--last-written**" from working, - cannot work with "**\--discard**", and makes "**\--buffer-size**" - redundant, so using any of those options automatically switches on - "**\--no-splice**". Switching on this option results in a small loss - of transfer efficiency. It has no effect on systems where - **splice**(2) is unavailable. + cannot work with "**\--sparse**" or "**\--discard**", and makes + "**\--buffer-size**" redundant, so using any of those options + automatically switches on "**\--no-splice**". Switching on this + option results in a small loss of transfer efficiency. It has no + effect on systems where **splice**(2) is unavailable. **-E, \--skip-errors** @@ -336,6 +336,13 @@ are explicitly switched on will be shown. especially if reading and writing files across a variety of filesystems in a single **pv** call. Use this option with caution. +**-O, \--sparse** + +: When writing null bytes, try to seek, producing a sparse output + file. Implies "**\--no-splice**". On filesystems without sparse file + support, or when the output is not seekable, this option will have + no effect other than to turn on "**\--no-splice**". + **-X, \--discard** : Instead of transferring input data to standard output, discard it. diff --git a/src/main/help.c b/src/main/help.c index 633b4ae..32f32a0 100644 --- a/src/main/help.c +++ b/src/main/help.c @@ -351,6 +351,9 @@ void display_help(void) { "-K", "--direct-io", NULL, N_("use direct I/O to bypass cache"), { 0, 0, 0, 0} }, + { "-O", "--sparse", NULL, + N_("try to seek instead of writing null bytes"), + { 0, 0, 0, 0} }, { "-X", "--discard", NULL, N_("discard input instead of writing to output"), { 0, 0, 0, 0} }, diff --git a/src/main/options.c b/src/main/options.c index 13f27ed..c1b0671 100644 --- a/src/main/options.c +++ b/src/main/options.c @@ -612,6 +612,8 @@ opts_t opts_parse(unsigned int argc, char **argv) { "stop-at-size", 0, NULL, (int) 'S' }, { "sync", 0, NULL, (int) 'Y' }, { "direct-io", 0, NULL, (int) 'K' }, + { "sparse", 0, NULL, (int) 'O' }, + { "sparse-output", 0, NULL, (int) 'O' }, { "discard", 0, NULL, (int) 'X' }, { "store-and-forward", 1, NULL, (int) 'U' }, { "remote", 1, NULL, (int) 'R' }, @@ -627,7 +629,7 @@ opts_t opts_parse(unsigned int argc, char **argv) /*@+nullassign@ */ int option_index = 0; #endif /* HAVE_GETOPT_LONG */ - char *short_options = "hVpteIrab8kTA:fvnqcWD:s:gl0i:w:H:N:u:F:x:L:B:CEZ:SYKXU:R:P:d:m:o:" + char *short_options = "hVpteIrab8kTA:fvnqcWD:s:gl0i:w:H:N:u:F:x:L:B:CEZ:SYKOXU:R:P:d:m:o:" #ifdef ENABLE_DEBUGGING "!:" #endif @@ -972,6 +974,10 @@ opts_t opts_parse(unsigned int argc, char **argv) case 'K': opts->direct_io = true; break; + case 'O': + opts->sparse_output = true; + opts->no_splice = true; + break; case 'X': opts->discard_input = true; opts->no_splice = true;