Signed-off-by: Nathan Sharp <nwsharp@xxxxxxxx>
---
meson.build | 1 +
misc-utils/Makemodule.am | 2 +
misc-utils/pipesz.1.adoc | 109 +++++++++++++++++++++++++++++++++++++++
3 files changed, 112 insertions(+)
create mode 100644 misc-utils/pipesz.1.adoc
diff --git a/meson.build b/meson.build
index 358572e..a94b02f 100644
--- a/meson.build
+++ b/meson.build
@@ -2688,6 +2688,7 @@ exe = executable(
install : true)
if opt and not is_disabler(exe)
exes += exe
+ manadocs += ['misc-utils/pipesz.1.adoc']
endif
exe = executable(
diff --git a/misc-utils/Makemodule.am b/misc-utils/Makemodule.am
index 60c7fe1..5e08c9a 100644
--- a/misc-utils/Makemodule.am
+++ b/misc-utils/Makemodule.am
@@ -269,6 +269,8 @@ endif
if BUILD_PIPESZ
bin_PROGRAMS += pipesz
+MANPAGES += misc-utils/pipesz.1
+dist_noinst_DATA += misc-utils/pipesz.1.adoc
pipesz_SOURCES = misc-utils/pipesz.c
pipesz_LDADD = $(LDADD) libcommon.la
pipesz_CFLAGS = $(AM_CFLAGS)
diff --git a/misc-utils/pipesz.1.adoc b/misc-utils/pipesz.1.adoc
new file mode 100644
index 0000000..a18d775
--- /dev/null
+++ b/misc-utils/pipesz.1.adoc
@@ -0,0 +1,109 @@
+//po4a: entry man manual
+= pipesz(1)
+:doctype: manpage
+:man manual: User Commands
+:man source: util-linux {release-version}
+:page-layout: base
+:command: pipesz
+
+== NAME
+
+pipesz - set or examine pipe and FIFO buffer sizes
+
+== SYNOPSIS
+
+*pipesz* [options] [--set _size_] [--] [_command_ [argument] ...]
+
+*pipesz* [options] --get
+
+== DESCRIPTION
+
+Pipes and FIFOs maintain an internal buffer used to transfer data between the read end and the write end. In some cases, the default size of this internal buffer may not be appropriate. This program provides facilities to set and examine the size of these buffers.
+
+The *--set* operation sets pipe buffer sizes. If it is specified, it must be specified with an explicit _size_. Otherwise, it is implied and the size is read from */proc/sys/fs/pipe-max-size*. The kernel may adjust _size_ as described in *fcntl*(2). To determine the actual buffer sizes set, use the *--verbose* option. If neither *--file* nor *--fd* are specified, *--set* acts on standard output.
+
+The *--set* operation permits an optional _command_ to execute after setting the pipe buffer sizes. This command is executed with the adjusted pipes.
+
+The *--get* operation outputs data in a tabular format. The first column is the name of the pipe as passed to *pipesz*. File descriptors are named as "fd _N_". The second column is the size, in bytes, of the pipe's internal buffer. The third column is the number of unread bytes currently in the pipe. The columns are separated by tabs ('\t', ASCII 09h). If *--verbose* is specified, a descriptive header is also emitted. If neither *--file* nor *--fd* are specified, *--get* acts on all file descriptors.
+
+Unless the *--check* option is specified, *pipesz* does _not_ exit if it encounters an error while manipulating a file or file descriptor. This allows *pipesz* to be used generically without fear of disrupting the execution of pipelines should the type of certain files be later changed. For minimal disruption, the *--quiet* option prevents warnings from being emitted in these cases.
+
+The kernel imposes limits on the amount of pipe buffer space unprivileged processes can use, though see *BUGS* below. The kernel will also refuse to shrink a pipe buffer if this would cause a loss of buffered data. See *pipe*(7) for additional details.
+
+*pipesz* supports specifying multiple short options consecutively, in the usual *getopt*(3) fashion. The first non-option argument is interpreted as _command_. If _command_ might begin with '-', use '--' to separate it from argument to *pipesz*. In shell scripts, it is good practice to use '--' when parameter expansion is involved. *pipesz* itself does not read from standard input and does not write to standard output unless *--get*, *--help*, or *--version* are specified.
+
+== OPTIONS
+
+*-g*, *--get*::
+Report the size of pipe buffers to standard output and exit. As a special behavior, if neither *--file* nor *--fd* are specified, *every* file descriptor passed to *pipesz* is examined. It is an error to specifiy this option in combination with *--set*.
+
+*-s*, *--set* _size_::
+Set the size of the pipe buffers, in bytes. This option may be suffixed by _K_, _M_, _G_, _KiB_, _MiB_, or _GiB_ to indicate multiples of 1024. Fractional values are supported in this case. Additional suffixes are supported but are unlikely to be useful. If this option is not specified, a default value is used, as described above. If this option is specified multiple times, a warning is emitted and only the last-specified value is used. It is an error to specify this option in combination with *--get*.
+
+*-f*, *--file* _path_::
+Set the buffer size of the FIFO or pipe at _path_, relative to the current working directory. You may specify this option multiple times to affect different files, and you may do so in combination with *--fd*. Generally, this option is used with FIFOs, but it will also operate on anonymous pipes such as those found in */proc/PID/fd*. Changes to the buffer size of FIFOs are not preserved across system restarts.
+
+*-n*, *--fd* _fd_::
+Set the buffer size of the pipe or FIFO passed to *pipesz* as the specified file descriptor number. You may specify this option multiple times to affect different file descriptors, and you may do so in combination with *--file*. Shorthand options are provided for the common cases of fd 0 (stdin), fd 1 (stdout), and fd 2 (stderr). These should suffice in most cases.
+
+*-i*, *--stdin*::
+Shorthand for *--fd 0*.
+
+*-o*, *--stdout*::
+Shorthand for *--fd 1*.
+
+*-e*, *--stderr*::
+Shorthand for *--fd 2*.
+
+*-c*, *--check*::
+Exit, without executing _command_, in case of any error while manipulating a file or file descriptor. The default behavior if this is not specified is to emit a warning to standard error and continue.
+
+*-q*, *--quiet*::
+Do not diagnose non-fatal errors to standard error. This option does not affect the normal output of *--get*, *--verbose*, *--help*, or *--version*.
+
+*-v*, *--verbose*::
+If specified with *--get*, *pipesz* will emit a descriptive header above the table. If specified with *--set*, *pipesz* will print the actual buffer sizes set by the kernel to standard error.
+
+include::man-common/help-version.adoc[]
+
+== EXAMPLES
+
+*pipesz* *dd* if=_file_ bs=1M | ...::
+Runs *dd*(1) with an expanded standard output pipe, allowing it to avoid context switches when piping around large blocks.
+
+*pipesz* -s1M -cf /run/my-service.fifo::
+Sets the pipe buffer size of a service FIFO to 1,048,576 bytes. If the buffer size could not be set, *pipesz* exits with an error.
+
+*echo* hello | *pipesz* -gi::
+Prints the size of pipe used by the shell to pass input to *pipesz*. Since *pipesz* does not read standard input, it may also report 6 unread bytes in the pipe, depending on relative timings.
+
+*find* /proc/_PID_/fd -exec *pipesz* -gqf '{}' ';'::
+Prints the size and number of unread bytes of all pipes in use by _PID_. If some pipes are routinely full, *pipesz* might be able to mitigate a processing bottleneck.
+
+== NOTES
+
+Linux supports adjusting the size of pipe buffers since kernel 2.6.35. This release also introduced */proc/sys/fs/pipe-max-size*.
+
+This program uses *fcntl*(2) *F_GETPIPE_SZ*/*F_SETPIPE_SZ* to get and set pipe buffer sizes.
+
+This program uses *ioctl*(2) *FIONREAD* to report the amount of unread data in pipes. If for some reason this fails, the amount of unread data is reported as 0.
+
+== BUGS
+
+Before Linux 4.9, some bugs affect how certain resource limits are enforced when setting pipe buffer sizes. See *pipe*(7) for details.
+
+== AUTHORS
+
+mailto:nwsharp@xxxxxxxx[Nathan Sharp]
+
+== SEE ALSO
+
+*pipe*(7)
+
+include::man-common/bugreports.adoc[]
+
+include::man-common/footer.adoc[]
+
+ifdef::translation[]
+include::man-common/translation.adoc[]
+endif::[]
--
2.35.1
