Skip to content
Permalink
Browse files

doc: refresh man pages for v0.10

Signed-off-by: Adam Moody <moody20@llnl.gov>
  • Loading branch information
adammoody committed Dec 28, 2019
1 parent ae2cc8f commit 6ee98ce6de3a21cfd9b0b36e666d2f5aa677d3fd
Showing with 492 additions and 184 deletions.
  1. +22 −1 doc/README.md
  2. +2 −2 doc/rst/conf.py
  3. +2 −2 man/dbcast.1
  4. +13 −8 man/dbz2.1
  5. +31 −9 man/dchmod.1
  6. +18 −11 man/dcmp.1
  7. +19 −11 man/dcp.1
  8. +1 −1 man/ddup.1
  9. +54 −30 man/dfind.1
  10. +9 −2 man/dreln.1
  11. +32 −8 man/drm.1
  12. +13 −6 man/dstripe.1
  13. +30 −1 man/dsync.1
  14. +4 −4 man/dwalk.1
  15. +242 −88 man/mpifileutils.1
@@ -4,15 +4,36 @@ Edits should be made to the `.rst` files.
The documentation can be built with `make html` or `make man`.
The generated files will be found in the `build` directory.

## Installing Sphinx

Sphinx is used to generate man pages from the `.rst` files.
If Sphinx is not installed on the system, the following may be used to install Sphinx into a virtualenv.

``` shell
virtualenv --system-site-packages env
source env/bin/activate
pip install recommonmark
pip install guzzle_sphinx_theme
```

If using this method, then source the virtualenv before running the Makefile steps below:

``` shell
source env/bin/activate
```

## Man Pages

Since there is no guarantee of Sphinx on each system, the man pages for each release are committed directly to the repo.
This can be done with:

Be sure to update the version number in the `doc/rst/conf.py` file if needed,
then run Sphinx to generate the man pages from the `.rst` files.

``` shell
cd doc
make man
make install
```

Be sure to update the version number in the `doc/rst/conf.py` file as well.
@@ -54,9 +54,9 @@
# built documents.
#
# The short X.Y version.
version = u'0.9.1'
version = u'0.10'
# The full version, including alpha/beta/rc tags.
release = u'0.9.1'
release = u'0.10'

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "DBCAST" "1" "Apr 17, 2019" "0.9.1" "mpiFileUtils"
.TH "DBCAST" "1" "Dec 28, 2019" "0.10" "mpiFileUtils"
.SH NAME
dbcast \- distributed broadcast
.
@@ -53,7 +53,7 @@ number of MPI processes.
.TP
.B \-s, \-\-size SIZE
The chunk size in bytes used to segment files during the broadcast.
Units like "MB" and "GB" should be immediately follow the number
Units like “MB” and “GB” should be immediately follow the number
without spaces (ex. 2MB). The default size is 1MB. It is recommended
to use the stripe size of a file if this is known.
.UNINDENT
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "DBZ2" "1" "Apr 17, 2019" "0.9.1" "mpiFileUtils"
.TH "DBZ2" "1" "Dec 28, 2019" "0.10" "mpiFileUtils"
.SH NAME
dbz2 \- distributed bz2 compression
.
@@ -42,13 +42,13 @@ When decompressing, the .dbz2 extension will be dropped from the file name.
.SH OPTIONS
.INDENT 0.0
.TP
.B \-d, \-\-decompress
Decompress the file
.B \-z, \-\-compress
Compress the file
.UNINDENT
.INDENT 0.0
.TP
.B \-z, \-\-compress
Compress the file
.B \-d, \-\-decompress
Decompress the file
.UNINDENT
.INDENT 0.0
.TP
@@ -57,14 +57,14 @@ Keep the input file.
.UNINDENT
.INDENT 0.0
.TP
.B \-f, \-\-overwrite
.B \-f, \-\-force
Overwrite the output file, if it exists.
.UNINDENT
.INDENT 0.0
.TP
.B \-b, \-\-block SIZE
.B \-b, \-\-blocksize SIZE
Set the compression block size, from 1 to 9.
Where 1=100kB ... and 9=900kB. Default is 9.
Where 1=100kB and 9=900kB. Default is 9.
.UNINDENT
.INDENT 0.0
.TP
@@ -73,6 +73,11 @@ Verbose output (optional).
.UNINDENT
.INDENT 0.0
.TP
.B \-q, \-\-quiet
Quiet output
.UNINDENT
.INDENT 0.0
.TP
.B \-h, \-\-help
Print usage.
.UNINDENT
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "DCHMOD" "1" "Apr 17, 2019" "0.9.1" "mpiFileUtils"
.TH "DCHMOD" "1" "Dec 28, 2019" "0.10" "mpiFileUtils"
.SH NAME
dchmod \- distributed tool to set permissions and group
.
@@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
..
.SH SYNOPSIS
.sp
\fBdchmod [OPTION] PATH ...\fP
\fBdchmod [OPTION] PATH \fP
.SH DESCRIPTION
.sp
Parallel MPI application to recursively change permissions and/or group
@@ -51,23 +51,38 @@ from the mpiFileUtils suite.
.INDENT 0.0
.TP
.B \-u, \-\-owner USER
Change owner to specified USER name.
Change owner to specified USER name or numeric user id.
.UNINDENT
.INDENT 0.0
.TP
.B \-g, \-\-group GROUP
Change group to specified GROUP name.
Change group to specified GROUP name or numeric group id.
.UNINDENT
.INDENT 0.0
.TP
.B \-m, \-\-mode MODE
The mode to apply to each item. MODE may be octal or symbolic syntax
similar to \fBchmod(1)\fP\&. In symbolic notation, "ugoa" are supported
as are "rwxX". As with chmod, if no leading letter "ugoa" is provided,
similar to \fBchmod(1)\fP\&. In symbolic notation, ugoa are supported
as are rwxX. As with chmod, if no leading letter ugoa is provided,
mode bits are combined with umask to determine the actual mode.
.UNINDENT
.INDENT 0.0
.TP
.B \-f, \-\-force
Attempt to change every item. By default, dchmod avoids unncessary
chown and chmod calls, for example trying to change the group
on an item that already has the correct group, or trying to change
the group on an item that is not owned by the user running the tool.
With –force, dchmod executes chown/chmod calls on every item.
.UNINDENT
.INDENT 0.0
.TP
.B \-s, \-\-silent
Suppress EPERM error messages, which is useful when running dchmod
on large directories with files owned by other users.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-exclude REGEX
Do not modify items whose full path matches REGEX, processed by
\fBregexec(3)\fP\&.
@@ -80,12 +95,19 @@ Only modify items whose full path matches REGEX, processed by
.UNINDENT
.INDENT 0.0
.TP
.B \-\-name
Change \-\-exclude and \-\-match to apply to item name rather than its
.B \-n, \-\-name
Change exclude and match to apply to item name rather than its
full path.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-progress N
Print progress message to stdout approximately every N seconds.
The number of seconds must be a non\-negative integer.
A value of 0 disables progress messages.
.UNINDENT
.INDENT 0.0
.TP
.B \-v, \-\-verbose
Run in verbose mode. Prints a list of statistics including the
number of files walked, the number of levels there are in the
@@ -129,7 +151,7 @@ regex:
.sp
\fBmpirun \-np 128 dchmod \-\-name \-\-exclude ‘afilename’ \-\-mode u+rw /directory\fP
.sp
Note: You can use \-\-match to change file permissions on all of the
Note: You can use match to change file permissions on all of the
files/directories that match the regex.
.SH SEE ALSO
.sp
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "DCMP" "1" "Apr 17, 2019" "0.9.1" "mpiFileUtils"
.TH "DCMP" "1" "Dec 28, 2019" "0.10" "mpiFileUtils"
.SH NAME
dcmp \- distributed compare
.
@@ -54,12 +54,19 @@ in which case, each option should provide a different output file name.
.INDENT 0.0
.TP
.B \-t, \-\-text
Change \-\-output to write files in text format rather than binary.
Change output to write files in text format rather than binary.
.UNINDENT
.INDENT 0.0
.TP
.B \-b, \-\-base
Enable base checks and normal stdout results when \-\-output is used.
Enable base checks and normal stdout results when –output is used.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-progress N
Print progress message to stdout approximately every N seconds.
The number of seconds must be a non\-negative integer.
A value of 0 disables progress messages.
.UNINDENT
.INDENT 0.0
.TP
@@ -90,7 +97,7 @@ Print the command usage, and the list of options available.
.SH EXPRESSIONS
.sp
An expression is made up of one or more conditions, where each condition specifies a field and a state.
A single condition consists of a field name, an \(aq=\(aq sign, and a state name.
A single condition consists of a field name, an ‘=’ sign, and a state name.
.sp
Valid fields are listed below, along with the property of the entry that is checked.
.TS
@@ -183,13 +190,13 @@ Meaning
T}
_
T{
EXIST=SRC_ONLY
EXIST=ONLY_SRC
T} T{
entry exists only in source path
T}
_
T{
EXIST=DST_ONLY
EXIST=ONLY_DEST
T} T{
entry exists only in destination path
T}
@@ -230,7 +237,7 @@ For example, the following expression matches on entries which either (exist in
.sp
.nf
.ft C
EXIST=COMMON@TYPE=DIFFER,EXIST=SRC_ONLY
EXIST=COMMON@TYPE=DIFFER,EXIST=ONLY_SRC
.ft P
.fi
.UNINDENT
@@ -253,7 +260,7 @@ CONTENT=COMMON => EXISTS=COMMON@TYPE=COMMON@SIZE=COMMON@CONTENT=COMMON
.sp
A successful check on any other field also implies that EXIST=COMMON.
.sp
When used with the \-o option, one must also specify a file name at the end of the expression, separated with a \(aq:\(aq.
When used with the \-o option, one must also specify a file name at the end of the expression, separated with a ‘:’.
The list of any entries that match the expression are written to the named file.
For example, to list any entries matching the above expression to a file named outfile1,
one should use the following option:
@@ -268,7 +275,7 @@ one should use the following option:
.UNINDENT
.UNINDENT
.sp
If the \-\-base option is given or when no output option is specified,
If the base option is given or when no output option is specified,
the following expressions are checked and numeric results are reported to stdout:
.INDENT 0.0
.INDENT 3.5
@@ -303,13 +310,13 @@ Compare two directories with verbose output. The verbose output prints timing an
Write list of entries to outfile1 that are only in src1 or whose names exist in both src1 and src2 but whose types differ:
.UNINDENT
.sp
\fBmpirun \-np 128 dcmp \-o EXIST=COMMON@TYPE=DIFFER,EXIST=SRC_ONLY:outfile1 /src1 /src2\fP
\fBmpirun \-np 128 dcmp \-o EXIST=COMMON@TYPE=DIFFER,EXIST=ONLY_SRC:outfile1 /src1 /src2\fP
.INDENT 0.0
.IP 4. 3
Same as above but also write list of entries to outfile2 that exist in either src1 or src2 but not both:
.UNINDENT
.sp
\fBmpirun \-np 128 dcmp \-o EXIST=COMMON@TYPE=DIFFER,EXIST=SRC_ONLY:outfile1 \-o EXIST=DIFFER:outfile2 /src1 /src2\fP
\fBmpirun \-np 128 dcmp \-o EXIST=COMMON@TYPE=DIFFER,EXIST=ONLY_SRC:outfile1 \-o EXIST=DIFFER:outfile2 /src1 /src2\fP
.SH SEE ALSO
.sp
The mpiFileUtils source code and all documentation may be downloaded
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "DCP" "1" "Apr 17, 2019" "0.9.1" "mpiFileUtils"
.TH "DCP" "1" "Dec 28, 2019" "0.10" "mpiFileUtils"
.SH NAME
dcp \- distributed copy
.
@@ -37,16 +37,16 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
.sp
Parallel MPI application to recursively copy files and directories.
.sp
dcp is a file copy tool in the spirit of \fBcp(1)\fP that evenly distributes
the work of scanning the directory tree, and copuing file data across a
large cluster without any centralized state. It is designed for copying
files that are located on a distributed parallel file system, and will
split large file copies across multiple processes.
dcp is a file copy tool in the spirit of \fBcp(1)\fP that evenly
distributes the work of scanning the directory tree, and copying file
data across a large cluster without any centralized state. It is
designed for copying files that are located on a distributed parallel
file system, and it splits large file copies across multiple processes.
.SH OPTIONS
.INDENT 0.0
.TP
.B \-b, \-\-blocksize SIZE
Set the I/O buffer to be SIZE bytes. Units like "MB" and "GB" may
Set the I/O buffer to be SIZE bytes. Units like “MB” and “GB” may
immediately follow the number without spaces (eg. 8MB). The default
blocksize is 1MB.
.UNINDENT
@@ -60,8 +60,8 @@ from the mpiFileUtils suite.
.TP
.B \-k, \-\-chunksize SIZE
Split large files into chunks of SIZE bytes to be processed. Multiple
process ranks may copy a large file in parallel. Units like "MB" and
"GB" can immediately follow the number without spaces (eg. 64MB).
process ranks may copy a large file in parallel. Units like “MB” and
“GB” can immediately follow the number without spaces (eg. 64MB).
The default chunksize is 1MB.
.UNINDENT
.INDENT 0.0
@@ -72,12 +72,20 @@ Preserve permissions, group, timestamps, and extended attributes.
.INDENT 0.0
.TP
.B \-s, \-\-synchronous
Use synchronous read/write calls (open files with 0_DIRECT)
Use synchronous read/write calls (open files with O_DIRECT).
This also avoids caching the file data on the client nodes.
.UNINDENT
.INDENT 0.0
.TP
.B \-S, \-\-sparse
Create sparse files when possible (non\-functioning).
Create sparse files when possible.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-progress N
Print progress message to stdout approximately every N seconds.
The number of seconds must be a non\-negative integer.
A value of 0 disables progress messages.
.UNINDENT
.INDENT 0.0
.TP
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "DDUP" "1" "Apr 17, 2019" "0.9.1" "mpiFileUtils"
.TH "DDUP" "1" "Dec 28, 2019" "0.10" "mpiFileUtils"
.SH NAME
ddup \- report files with identical content
.

0 comments on commit 6ee98ce

Please sign in to comment.
You can’t perform that action at this time.