From c68324a58c889289a37e69ab27deff1b10cbbbf4 Mon Sep 17 00:00:00 2001 From: Sylvestre Ledru Date: Sat, 4 Mar 2023 13:27:20 +0100 Subject: [PATCH] md: improve the display for dd, expr and stat --- src/uu/dd/dd.md | 199 ++++++++++++++++++++++---------------------- src/uu/expr/expr.md | 49 +++++------ src/uu/stat/stat.md | 86 +++++++++---------- 3 files changed, 162 insertions(+), 172 deletions(-) diff --git a/src/uu/dd/dd.md b/src/uu/dd/dd.md index 72925b882..b60fc14fa 100644 --- a/src/uu/dd/dd.md +++ b/src/uu/dd/dd.md @@ -11,119 +11,116 @@ Copy, and optionally convert, a file system resource ## After Help -OPERANDS: +### Operands - bs=BYTES read and write up to BYTES bytes at a time (default: 512); - overwrites ibs and obs. - cbs=BYTES the 'conversion block size' in bytes. Applies to - the conv=block, and conv=unblock operations. - conv=CONVS a comma-separated list of conversion options or - (for legacy reasons) file flags. - count=N stop reading input after N ibs-sized read operations rather - than proceeding until EOF. See iflag=count_bytes if stopping - after N bytes is preferred - ibs=N the size of buffer used for reads (default: 512) - if=FILE the file used for input. When not specified, stdin is used instead - iflag=FLAGS a comma-separated list of input flags which specify how the input - source is treated. FLAGS may be any of the input-flags or - general-flags specified below. - skip=N (or iseek=N) skip N ibs-sized records into input before beginning - copy/convert operations. See iflag=seek_bytes if seeking N bytes - is preferred. - obs=N the size of buffer used for writes (default: 512) - of=FILE the file used for output. When not specified, stdout is used - instead - oflag=FLAGS comma separated list of output flags which specify how the output - source is treated. FLAGS may be any of the output flags or - general flags specified below - seek=N (or oseek=N) seeks N obs-sized records into output before - beginning copy/convert operations. See oflag=seek_bytes if - seeking N bytes is preferred - status=LEVEL controls whether volume and performance stats are written to - stderr. +- `Bs=BYTES` : read and write up to BYTES bytes at a time (default: 512); + overwrites `ibs` and `obs`. +- `cbs=BYTES` : the 'conversion block size' in bytes. Applies to the + `conv=block`, and `conv=unblock` operations. +- `conv=CONVS` : a comma-separated list of conversion options or (for legacy + reasons) file flags. +- `count=N` : stop reading input after N ibs-sized read operations rather + than proceeding until EOF. See `iflag=count_bytes` if stopping after N bytes + is preferred +- `ibs=N` : the size of buffer used for reads (default: 512) +- `if=FILE` : the file used for input. When not specified, stdin is used instead +- `iflag=FLAGS` : a comma-separated list of input flags which specify how the + input source is treated. FLAGS may be any of the input-flags or general-flags + specified below. +- `skip=N` (or `iseek=N`) : skip N ibs-sized records into input before beginning + copy/convert operations. See iflag=seek_bytes if seeking N bytes is preferred. +- `obs=N` : the size of buffer used for writes (default: 512) +- `of=FILE` : the file used for output. When not specified, stdout is used + instead +- `oflag=FLAGS` : comma separated list of output flags which specify how the + output source is treated. FLAGS may be any of the output flags or general + flags specified below +- `seek=N` (or `oseek=N`) : seeks N obs-sized records into output before + beginning copy/convert operations. See oflag=seek_bytes if seeking N bytes is + preferred +- `status=LEVEL` : controls whether volume and performance stats are written to + stderr. - When unspecified, dd will print stats upon completion. An - example is below. - 6+0 records in - 16+0 records out - 8192 bytes (8.2 kB, 8.0 KiB) copied, 0.00057009 s, - 14.4 MB/s - The first two lines are the 'volume' stats and the final line - is the 'performance' stats. - The volume stats indicate the number of complete and partial - ibs-sized reads, or obs-sized writes that took place during - the copy. The format of the volume stats is - +. If records have been truncated (see - conv=block), the volume stats will contain the number of - truncated records. + When unspecified, dd will print stats upon completion. An example is below. - Possible LEVEL values are: - progress: Print periodic performance stats as the copy - proceeds. - noxfer: Print final volume stats, but not performance stats. - none: Do not print any stats. + ```plain + 6+0 records in + 16+0 records out + 8192 bytes (8.2 kB, 8.0 KiB) copied, 0.00057009 s, + 14.4 MB/s + ``` - Printing performance stats is also triggered by the INFO signal - (where supported), or the USR1 signal. Setting the - POSIXLY_CORRECT environment variable to any value (including - an empty value) will cause the USR1 signal to be ignored. + The first two lines are the 'volume' stats and the final line is the + 'performance' stats. + The volume stats indicate the number of complete and partial ibs-sized reads, + or obs-sized writes that took place during the copy. The format of the volume + stats is `+`. If records have been truncated (see + `conv=block`), the volume stats will contain the number of truncated records. -CONVERSION OPTIONS: + Possible LEVEL values are: + - `progress` : Print periodic performance stats as the copy proceeds. + - `noxfer` : Print final volume stats, but not performance stats. + - `none` : Do not print any stats. - ascii convert from EBCDIC to ASCII. This is the inverse of the 'ebcdic' - option. Implies conv=unblock. - ebcdic convert from ASCII to EBCDIC. This is the inverse of the 'ascii' - option. Implies conv=block. - ibm convert from ASCII to EBCDIC, applying the conventions for '[', ']' - and '~' specified in POSIX. Implies conv=block. + Printing performance stats is also triggered by the INFO signal (where supported), + or the USR1 signal. Setting the POSIXLY_CORRECT environment variable to any value + (including an empty value) will cause the USR1 signal to be ignored. - ucase convert from lower-case to upper-case - lcase converts from upper-case to lower-case. +### Conversion Options - block for each newline less than the size indicated by cbs=BYTES, remove - the newline and pad with spaces up to cbs. Lines longer than cbs - are truncated. - unblock for each block of input of the size indicated by cbs=BYTES, remove - right-trailing spaces and replace with a newline character. +- `ascii` : convert from EBCDIC to ASCII. This is the inverse of the `ebcdic` + option. Implies `conv=unblock`. +- `ebcdic` : convert from ASCII to EBCDIC. This is the inverse of the `ascii` + option. Implies `conv=block`. +- `ibm` : convert from ASCII to EBCDIC, applying the conventions for `[`, `]` + and `~` specified in POSIX. Implies `conv=block`. - sparse attempts to seek the output when an obs-sized block consists of only - zeros. - swab swaps each adjacent pair of bytes. If an odd number of bytes is - present, the final byte is omitted. - sync pad each ibs-sided block with zeros. If 'block' or 'unblock' is - specified, pad with spaces instead. - excl the output file must be created. Fail if the output file is already - present. - nocreat the output file will not be created. Fail if the output file in not - already present. - notrunc the output file will not be truncated. If this option is not - present, output will be truncated when opened. - noerror all read errors will be ignored. If this option is not present, dd - will only ignore Error::Interrupted. - fdatasync data will be written before finishing. - fsync data and metadata will be written before finishing. +- `ucase` : convert from lower-case to upper-case. +- `lcase` : converts from upper-case to lower-case. -INPUT FLAGS: +- `block` : for each newline less than the size indicated by cbs=BYTES, remove + the newline and pad with spaces up to cbs. Lines longer than cbs are truncated. +- `unblock` : for each block of input of the size indicated by cbs=BYTES, remove + right-trailing spaces and replace with a newline character. - count_bytes a value to count=N will be interpreted as bytes. - skip_bytes a value to skip=N will be interpreted as bytes. - fullblock wait for ibs bytes from each read. zero-length reads are still - considered EOF. +- `sparse` : attempts to seek the output when an obs-sized block consists of + only zeros. +- `swab` : swaps each adjacent pair of bytes. If an odd number of bytes is + present, the final byte is omitted. +- `sync` : pad each ibs-sided block with zeros. If `block` or `unblock` is + specified, pad with spaces instead. +- `excl` : the output file must be created. Fail if the output file is already + present. +- `nocreat` : the output file will not be created. Fail if the output file in + not already present. +- `notrunc` : the output file will not be truncated. If this option is not + present, output will be truncated when opened. +- `noerror` : all read errors will be ignored. If this option is not present, + dd will only ignore Error::Interrupted. +- `fdatasync` : data will be written before finishing. +- `fsync` : data and metadata will be written before finishing. -OUTPUT FLAGS: +### Input flags - append open file in append mode. Consider setting conv=notrunc as well. - seek_bytes a value to seek=N will be interpreted as bytes. +- `count_bytes` : a value to `count=N` will be interpreted as bytes. +- `skip_bytes` : a value to `skip=N` will be interpreted as bytes. +- `fullblock` : wait for ibs bytes from each read. zero-length reads are still + considered EOF. -GENERAL FLAGS: +### Output flags - direct use direct I/O for data. - directory fail unless the given input (if used as an iflag) or output (if used - as an oflag) is a directory. - dsync use synchronized I/O for data. - sync use synchronized I/O for data and metadata. - nonblock use non-blocking I/O. - noatime do not update access time. - nocache request that OS drop cache. - noctty do not assign a controlling tty. - nofollow do not follow system links. +- `append` : open file in append mode. Consider setting conv=notrunc as well. +- `seek_bytes` : a value to seek=N will be interpreted as bytes. + +### General Flags + +- `Direct` : use direct I/O for data. +- `directory` : fail unless the given input (if used as an iflag) or + output (if used as an oflag) is a directory. +- `dsync` : use synchronized I/O for data. +- `sync` : use synchronized I/O for data and metadata. +- `nonblock` : use non-blocking I/O. +- `noatime` : do not update access time. +- `nocache` : request that OS drop cache. +- `noctty` : do not assign a controlling tty. +- `nofollow` : do not follow system links. diff --git a/src/uu/expr/expr.md b/src/uu/expr/expr.md index 51018167e..ab0824651 100644 --- a/src/uu/expr/expr.md +++ b/src/uu/expr/expr.md @@ -14,34 +14,27 @@ separates increasing precedence groups. `EXPRESSION` may be: - ARG1 | ARG2 ARG1 if it is neither null nor 0, otherwise ARG2 - - ARG1 & ARG2 ARG1 if neither argument is null or 0, otherwise 0 - - ARG1 < ARG2 ARG1 is less than ARG2 - ARG1 <= ARG2 ARG1 is less than or equal to ARG2 - ARG1 = ARG2 ARG1 is equal to ARG2 - ARG1 != ARG2 ARG1 is unequal to ARG2 - ARG1 >= ARG2 ARG1 is greater than or equal to ARG2 - ARG1 > ARG2 ARG1 is greater than ARG2 - - ARG1 + ARG2 arithmetic sum of ARG1 and ARG2 - ARG1 - ARG2 arithmetic difference of ARG1 and ARG2 - - ARG1 * ARG2 arithmetic product of ARG1 and ARG2 - ARG1 / ARG2 arithmetic quotient of ARG1 divided by ARG2 - ARG1 % ARG2 arithmetic remainder of ARG1 divided by ARG2 - - STRING : REGEXP anchored pattern match of REGEXP in STRING - - match STRING REGEXP same as STRING : REGEXP - substr STRING POS LENGTH substring of STRING, POS counted from 1 - index STRING CHARS index in STRING where any CHARS is found, or 0 - length STRING length of STRING - + TOKEN interpret TOKEN as a string, even if it is a - keyword like 'match' or an operator like '/' - - ( EXPRESSION ) value of EXPRESSION +- `ARG1 | ARG2`: `ARG1` if it is neither null nor 0, otherwise `ARG2` +- `ARG1 & ARG2`: `ARG1` if neither argument is null or 0, otherwise 0 +- `ARG1 < ARG2`: `ARG1` is less than `ARG2` +- `ARG1 <= ARG2`: `ARG1` is less than or equal to `ARG2` +- `ARG1 = ARG2`: `ARG1` is equal to `ARG2` +- `ARG1 != ARG2`: `ARG1` is unequal to `ARG2` +- `ARG1 >= ARG2`: `ARG1` is greater than or equal to `ARG2` +- `ARG1 > ARG2`: `ARG1` is greater than `ARG2` +- `ARG1 + ARG2`: arithmetic sum of `ARG1` and `ARG2` +- `ARG1 - ARG2`: arithmetic difference of `ARG1` and `ARG2` +- `ARG1 * ARG2`: arithmetic product of `ARG1` and `ARG2` +- `ARG1 / ARG2`: arithmetic quotient of `ARG1` divided by `ARG2` +- `ARG1 % ARG2`: arithmetic remainder of `ARG1` divided by `ARG2` +- `STRING : REGEXP`: anchored pattern match of `REGEXP` in `STRING` +- `match STRING REGEXP`: same as `STRING : REGEXP` +- `substr STRING POS LENGTH`: substring of `STRING`, `POS` counted from 1 +- `index STRING CHARS`: index in `STRING` where any `CHARS` is found, or 0 +- `length STRING`: length of `STRING` +- `+ TOKEN`: interpret `TOKEN` as a string, even if it is a keyword like `match` + or an operator like `/` +- `( EXPRESSION )`: value of `EXPRESSION` Beware that many operators need to be escaped or quoted for shells. Comparisons are arithmetic if both ARGs are numbers, else lexicographical. diff --git a/src/uu/stat/stat.md b/src/uu/stat/stat.md index 9228ba9dc..d91f2b01f 100644 --- a/src/uu/stat/stat.md +++ b/src/uu/stat/stat.md @@ -8,53 +8,53 @@ Display file or file system status. ## Long Usage -The valid format sequences for files (without `--file-system`): +Valid format sequences for files (without `--file-system`): - %a access rights in octal (note '#' and '0' printf flags) - %A access rights in human readable form - %b number of blocks allocated (see %B) - %B the size in bytes of each block reported by %b - %C SELinux security context string - %d device number in decimal - %D device number in hex - %f raw mode in hex - %F file type - %g group ID of owner - %G group name of owner - %h number of hard links - %i inode number - %m mount point - %n file name - %N quoted file name with dereference if symbolic link - %o optimal I/O transfer size hint - %s total size, in bytes - %t major device type in hex, for character/block device special files - %T minor device type in hex, for character/block device special files - %u user ID of owner - %U user name of owner - %w time of file birth, human-readable; - if unknown - %W time of file birth, seconds since Epoch; 0 if unknown - %x time of last access, human-readable - %X time of last access, seconds since Epoch - %y time of last data modification, human-readable - %Y time of last data modification, seconds since Epoch - %z time of last status change, human-readable - %Z time of last status change, seconds since Epoch +- `%a`: access rights in octal (note '#' and '0' printf flags) +- `%A`: access rights in human readable form +- `%b`: number of blocks allocated (see %B) +- `%B`: the size in bytes of each block reported by %b +- `%C`: SELinux security context string +- `%d`: device number in decimal +- `%D`: device number in hex +- `%f`: raw mode in hex +- `%F`: file type +- `%g`: group ID of owner +- `%G`: group name of owner +- `%h`: number of hard links +- `%i`: inode number +- `%m`: mount point +- `%n`: file name +- `%N`: quoted file name with dereference if symbolic link +- `%o`: optimal I/O transfer size hint +- `%s`: total size, in bytes +- `%t`: major device type in hex, for character/block device special files +- `%T`: minor device type in hex, for character/block device special files +- `%u`: user ID of owner +- `%U`: user name of owner +- `%w`: time of file birth, human-readable; - if unknown +- `%W`: time of file birth, seconds since Epoch; 0 if unknown +- `%x`: time of last access, human-readable +- `%X`: time of last access, seconds since Epoch +- `%y`: time of last data modification, human-readable +- `%Y`: time of last data modification, seconds since Epoch +- `%z`: time of last status change, human-readable +- `%Z`: time of last status change, seconds since Epoch Valid format sequences for file systems: - %a free blocks available to non-superuser - %b total data blocks in file system - %c total file nodes in file system - %d free file nodes in file system - %f free blocks in file system - %i file system ID in hex - %l maximum length of filenames - %n file name - %s block size (for faster transfers) - %S fundamental block size (for block counts) - %t file system type in hex - %T file system type in human readable form +- `%a`: free blocks available to non-superuser +- `%b`: total data blocks in file system +- `%c`: total file nodes in file system +- `%d`: free file nodes in file system +- `%f`: free blocks in file system +- `%i`: file system ID in hex +- `%l`: maximum length of filenames +- `%n`: file name +- `%s`: block size (for faster transfers) +- `%S`: fundamental block size (for block counts) +- `%t`: file system type in hex +- `%T`: file system type in human readable form NOTE: your shell may have its own version of stat, which usually supersedes the version described here. Please refer to your shell's documentation