expand docs

[zpackage] / doc / zpm-stat.8

diff --git a/doc/zpm-stat.8 b/doc/zpm-stat.8
new file mode 100644 (file)
index 0000000..8b26d87
--- /dev/null
+++ b/doc/zpm-stat.8
@@ -0,0 +1,55 @@
+.TH zpm-stat 8 2019-02-14 "ZPM 0.3"
+.SH NAME
+zpm-stat \- run stat
+.SH SYNOPSIS
+.B zpm stat
+[
+.BI -f " format"
+]
+[
+.BI -t " timeformat"
+]
+[
+.B -l
+]
+.RI [ path ...]
+.SH DESCRIPTION
+\fBzpm-stat\fR
+prints information from stat(2) to stdout.  This program is needed because the
+output from stat(1) is not specified by posix and thus can't be portably parsed
+by shell scripts.  Thus zpm-stat provides a consistent interface for zpm
+scripts to use.
+.SH OPTIONS
+.TP
+\-f \fIformat\fR
+Specify an output format.  Format strings are printf style strings,
+where conversions are specified beginning with a % character, and %%
+is used to output a literal %.  %z will output a zero byte.  \\n and \\t
+escape sequences are also recognized.  Any other character preceeded
+by a \\ will be output as is.
+.IP
+Available format conversions are:
+y = mtime, s = file size, a = mode in octal, t = a file type string,
+u = numeric user id, U = username, g = numeric group id, G = groupname,
+and n = file name.
+.TP
+\-t \fIformat\fR
+When outputting mtime, pass the given format to strftime.  The default
+time format is "%s".
+.TP
+\-l
+Use lstat instead of stat.  That is, don't follow symlinks.
+.SH EXAMPLES
+.TP
+zpm stat /etc/passwd
+print the mtime of /etc/passwd in decimal to stdout.
+.SH EXIT STATUS
+0 on success non zero on failure
+.SH FILES
+None.
+.SH ENVIRONMENT
+None.
+.SH AUTHOR
+Nathan Wagner
+.SH SEE ALSO
+.BR zpm (8)