A virtual jailed shell environment for Go apps backed by an io/fs#FS.
docs(posix2018): add POSIX 2018 spec docs and conformance audit
Add the docs/posix2018/ directory containing the POSIX 2018
spec text for 43 utilities plus CONFORMANCE.md - the first
audit pass identifying GNU coreutils compatibility gaps,
deviations, and required test coverage per command.
Assisted-by: Claude Opus 4.7 via Claude Code
Signed-off-by: Xe Iaso <me@xeiaso.net>
+17049
+1505
docs/posix2018/CONFORMANCE.md
+1505
docs/posix2018/CONFORMANCE.md
···
1
+
# POSIX 2018 Conformance Audit
2
+
3
+
> **Audit date:** 2026-04-30
4
+
> **Scope:** All 43 utilities documented under `docs/posix2018/*.md`
5
+
> plus the POSIX `tee` (registered without a local spec doc) and 17
6
+
> non-POSIX extras shipped under `command/internal/`.
7
+
> **Method:** read each spec doc, read the matching implementation
8
+
> in `command/internal/<pkg>/*.go`, read the matching `_test.go`,
9
+
> record deviations, test gaps, and notes with `file:line` and
10
+
> spec-section citations.
11
+
12
+
This document is a starting point, not a finished compliance
13
+
certification. Citations are precise enough that any reader can
14
+
re-derive each finding by opening the cited file and the cited spec
15
+
section. Findings are conservative: where the implementation is too
16
+
shallow to fully audit (e.g., `tr`, `ls`, `printf`), the entry says
17
+
so rather than claiming completeness.
18
+
19
+
The README already warns: *"Most of the commands have not been
20
+
audited for correctness or POSIX compliance."* This document is the
21
+
first audit pass.
22
+
23
+
## How to read this document
24
+
25
+
- **Severity** is one of:
26
+
- **None** — no deviations found.
27
+
- **Minor** — extensions beyond POSIX, or small behavioral
28
+
differences that don't affect typical usage.
29
+
- **Major** — missing required options, wrong behavior on
30
+
documented inputs, or output that breaks scripts depending on
31
+
the spec.
32
+
- **Missing** — utility is not implemented at all.
33
+
- **Spec options** lists every option the spec mentions plus any
34
+
*extra* options the impl ships. Tag each as `implemented`,
35
+
`missing`, `accepted-but-ignored`, or `extra (not-in-POSIX)`.
36
+
- **Required tests** are concrete enough that a reader can drop
37
+
each into a table-driven `_test.go` in under 10 minutes.
38
+
- **Citations**: `cat.go:44` is the implementation; `cat.md OPTIONS`
39
+
is the spec section header.
40
+
41
+
## Table of contents
42
+
43
+
1. [Summary table](#summary-table)
44
+
2. [Cross-cutting concerns](#cross-cutting-concerns)
45
+
3. [Missing commands](#missing-commands)
46
+
4. [Per-command deep dives](#per-command-deep-dives)
47
+
5. [Non-POSIX extras](#non-posix-extras)
48
+
6. [Recommendations](#recommendations)
49
+
50
+
---
51
+
52
+
## Summary table
53
+
54
+
Severity legend: ⬜ None · 🟡 Minor · 🟠 Major · ⛔ Missing.
55
+
"Tests" is rated against the deviations identified in the deep dive
56
+
(adequate ≈ exercises the major spec contract; partial ≈ covers
57
+
common path; none ≈ no test file at all).
58
+
59
+
| Command | Impl | Severity | Tests | Notes |
60
+
| --- | --- | --- | --- | --- |
61
+
| basename | yes | 🟠 | partial | Ships GNU `-a`/`-s` flags; spec OPTIONS = "None" |
62
+
| cal | **no** | ⛔ | n/a | Not registered |
63
+
| cat | yes | 🟠 | partial | Ships `-n` (POSIX RATIONALE explicitly omits); missing `-u`; hardcoded errors |
64
+
| chmod | **no** | ⛔ | n/a | Not registered. High-priority gap |
65
+
| cp | yes | 🟠 | partial | Missing `-i`, `-H`, `-L`, `-P`; `-p` accepted-but-ignored; modes hardcoded |
66
+
| cut | yes | 🟠 | adequate | Missing `-b` and `-n`; field deduplication bug |
67
+
| date | yes | 🟡 | partial | UTC-only by design (sandbox); `%E`/`%O` modifiers unsupported |
68
+
| df | **no** | ⛔ | n/a | Not registered |
69
+
| diff | yes | 🟠 | partial | Only `-u` truly works; `-c`/`-C`/`-e`/`-f`/`-r`/`-U`/`-b` missing or stub |
70
+
| dirname | yes | ⬜ | adequate | Conformant |
71
+
| du | yes | 🟠 | partial | Default unit is 1024 (spec is 512); `-H`/`-L`/`-x` missing |
72
+
| expand | yes | 🟠 | adequate | Ships GNU `-i`; tab-stop trailing rule wrong; not locale-aware |
73
+
| expr | yes | 🟡 | adequate | Regex is Go-flavored, not BRE; string compare not collation-aware |
74
+
| false | yes | 🟠 | **none** | Likely conforming but no test file |
75
+
| file | yes | 🟠 | partial | Extension-based only; `-M`/`-m` missing |
76
+
| fold | yes | 🟠 | adequate | CR handling wrong; tab-stop indexing wrong; not locale-aware |
77
+
| grep | **no** | ⛔ | n/a | Not registered. High-priority gap |
78
+
| head | yes | 🟡 | adequate | Ships GNU `-c`/`-q`/`-v` (POSIX RATIONALE omits `-c`); adds trailing newline |
79
+
| join | yes | ⬜ | adequate | Conformant |
80
+
| ln | **no** | ⛔ | n/a | Not registered |
81
+
| ls | yes | 🟠 | partial | Many options unimplemented or marked `_unused`; long-format incomplete |
82
+
| mkdir | yes | 🟠 | adequate | `-m mode` missing entirely; intermediate-dir mode logic missing |
83
+
| more | **no** | ⛔ | n/a | Not registered |
84
+
| mv | yes | 🟠 | adequate | `-i` missing; ships GNU `-n`; no same-file or cross-fs handling |
85
+
| nl | yes | 🟠 | adequate | Missing `-d`, `-f`, `-h`, `-l`, `-p`; logical pages not supported |
86
+
| od | yes | 🟠 | partial | `-t` parses only `c`/`x1`/`o*`; `-v`/`-j`/`-N` missing |
87
+
| paste | yes | 🟠 | adequate | No backslash-escape parsing in `-d list` |
88
+
| patch | **no** | ⛔ | n/a | Not registered |
89
+
| printf | yes | 🟡 | partial | Adds bash `-v VAR`; otherwise large/complete impl, edge cases unaudited |
90
+
| pwd | yes | ⬜ | adequate | Conformant (`-L`/`-P` both honored) |
91
+
| rm | yes | 🟡 | adequate | `-i` missing; otherwise correct |
92
+
| rmdir | yes | ⬜ | adequate | Conformant; ships GNU `-v` extension |
93
+
| sleep | yes | 🟡 | partial | Accepts fractional and `m`/`h`/`d` suffixes (GNU); caps at 1 hour |
94
+
| split | yes | ⬜ | adequate | Conformant |
95
+
| tail | yes | 🟡 | adequate | `-f` follow mode missing |
96
+
| tee | yes | 🟡 | adequate | `-i` (ignore SIGINT) missing. No local spec doc |
97
+
| time | yes | 🟠 | partial | GNU-style impl, not POSIX `time`; couples to registry |
98
+
| touch | yes | 🟠 | adequate | `-a`/`-m`/`-r`/`-t` accepted-but-ignored; create mode 0o644 (spec: 0o666) |
99
+
| tr | yes | 🟠 | partial | No octal/escape parsing; no `[=equiv=]`; no LC_COLLATE; `-c` vs `-C` not split |
100
+
| true | yes | 🟠 | **none** | Likely conforming but no test file |
101
+
| unexpand | yes | 🟡 | partial | `-a`/`-t` interaction unclear; backspace + last-tabstop edges untested |
102
+
| uniq | yes | 🟠 | partial | `-f`/`-s` missing; ships GNU `-i`; output-file operand unsupported |
103
+
| wc | yes | 🟠 | adequate | `-c`/`-m` conflated; ASCII-only word splitting; counts bytes for `-m` |
104
+
| zcat | yes | ⬜ | adequate | Conformant |
105
+
106
+
| Extra (non-POSIX) | Impl | Tests | Reference |
107
+
| --- | --- | --- | --- |
108
+
| base64 | yes | yes | GNU coreutils `base64(1)` |
109
+
| checksum (lib) | n/a | no | Internal helper for `md5sum`/`sha1sum`/`sha256sum`; not a registered command |
110
+
| clear | yes | yes | `terminfo`/`ncurses` `clear(1)` |
111
+
| column | yes | yes | BSD `column(1)` / `util-linux column(1)` |
112
+
| gunzip | yes | yes | RFC 1952 / GNU `gunzip(1)` |
113
+
| gzip | yes | yes | RFC 1952 / GNU `gzip(1)` |
114
+
| hostname | yes | no | BSD `hostname(1)` |
115
+
| md5sum | yes | yes | GNU coreutils `md5sum(1)` |
116
+
| python3 | yes (wasm) | no | Embedded `python.wasm`; not a coreutil. Not registered with the registry |
117
+
| readlink | yes | yes | GNU coreutils `readlink(1)` |
118
+
| seq | yes | yes | GNU coreutils `seq(1)` |
119
+
| sha1sum | yes | yes | GNU coreutils `sha1sum(1)` |
120
+
| sha256sum | yes | yes | GNU coreutils `sha256sum(1)` |
121
+
| stat | yes | yes | GNU coreutils `stat(1)` |
122
+
| tac | yes | yes | GNU coreutils `tac(1)` |
123
+
| tree | yes | yes | BSD/Steve Baker `tree(1)` |
124
+
| whoami | yes | yes | GNU coreutils `whoami(1)` |
125
+
126
+
---
127
+
128
+
## Cross-cutting concerns
129
+
130
+
These issues recur across many commands and are worth fixing once
131
+
in a shared layer rather than 36 times.
132
+
133
+
### 1. Locale awareness (none)
134
+
135
+
POSIX requires nearly every utility to honor `LC_CTYPE`,
136
+
`LC_COLLATE`, `LC_MESSAGES`, and `LC_ALL` (see ENVIRONMENT VARIABLES
137
+
in any spec doc). Not one implementation reads these env vars.
138
+
Concrete consequences:
139
+
140
+
- `wc.go:201` counts bytes for `-m` instead of characters.
141
+
- `wc.go:211` splits words on ASCII whitespace only.
142
+
- `expand.go` / `fold.go` / `unexpand.go` assume one byte = one
143
+
column; multibyte and combining-character widths are wrong.
144
+
- `tr.go` ranges and character classes ignore collation order.
145
+
- `expr.go:150` string compare uses byte equality, not
146
+
`LC_COLLATE`.
147
+
- `ls.go` date format and column padding ignore locale.
148
+
- `nl.go`, `cut.go` field counting use ASCII delimiters.
149
+
150
+
**Recommended approach:** add a `command/internal/locale` helper that
151
+
reads `ec.Environ` for `LC_*` keys and exposes:
152
+
153
+
- `IsSpace(r rune) bool` (LC_CTYPE-aware)
154
+
- `Width(r rune) int` (column width per LC_CTYPE; default to
155
+
`golang.org/x/text/width` rules)
156
+
- `Compare(a, b string) int` (LC_COLLATE-aware; default to
157
+
byte-wise, but pluggable)
158
+
159
+
Wire commands through it. A test fixture with multibyte input
160
+
exercises every consumer at once.
161
+
162
+
### 2. Hardcoded error messages
163
+
164
+
Several commands print a fixed string regardless of the underlying
165
+
errno:
166
+
167
+
- `cat.go:94`, `cat.go:100`: always says `"No such file or
168
+
directory"` even on EACCES, EISDIR.
169
+
- `wc.go:106`: same pattern.
170
+
171
+
POSIX is intentionally loose about diagnostic wording, but tests
172
+
break when the error doesn't reflect reality. Use
173
+
`fmt.Fprintf(stderr, "%s: %s: %s\n", prog, file, err)` with the
174
+
underlying error to surface the actual cause.
175
+
176
+
### 3. Help/usage output stream
177
+
178
+
GNU convention writes `--help` to **stdout** so it can be piped to
179
+
`less`. Most kefka impls write usage to **stderr** (e.g.,
180
+
`cat.go:42`). Pick a convention and apply it uniformly. Document
181
+
the choice in `command/command.go`.
182
+
183
+
### 4. `--` end-of-options handling
184
+
185
+
`getopt/v2` honors `--` automatically. Add at least one test per
186
+
command verifying that `cmd -- -file` treats `-file` as an operand
187
+
(important for files whose names start with `-`). Currently no
188
+
command tests this.
189
+
190
+
### 5. Stdin / `-` operand
191
+
192
+
POSIX many utilities treat `-` as stdin. The current impls vary:
193
+
194
+
- `cat`, `wc`, `head`, `tail`, `cut`, `paste`, `tr`, etc. all
195
+
accept `-`.
196
+
- POSIX `cat` specifically requires that stdin not be closed and
197
+
reopened on subsequent `-` operands. The impl reads all of stdin
198
+
on the first `-` and gets EOF afterwards (consistent), but no
199
+
test exercises this.
200
+
201
+
Add a shared test helper that, for every command accepting file
202
+
operands, runs the matrix `[file, -, file -]` against a known
203
+
stdin to lock the contract.
204
+
205
+
### 6. Exit status
206
+
207
+
Most utilities specify `0` and `>0`. Specific exit codes are
208
+
mandated for:
209
+
210
+
- `cmp`: 0 = same, 1 = differ, >1 = error. (Not implemented.)
211
+
- `diff`: 0 = same, 1 = differ, 2 = error. `diff.go:115` returns
212
+
1 on differences (correct).
213
+
- `expr`: 0 = nonzero/nonempty, 1 = zero/empty, 2 = invalid expr,
214
+
3 = other error. Verify the impl's mapping (`expr.go:57-59`,
215
+
276) — looks right but should be tested explicitly.
216
+
- `grep`: 0 = match, 1 = no match, 2 = error. Not implemented.
217
+
218
+
Add explicit "exit code on error" tests for these four (only two
219
+
are implemented today: `diff` and `expr`).
220
+
221
+
### 7. Unicode / rune vs byte
222
+
223
+
Several length/column-counting bugs share a root cause: code uses
224
+
`len(string)` (bytes) where the spec wants characters. Touched
225
+
commands: `wc -m`, `cut -c`, `fold -w`, `expand`, `unexpand`,
226
+
`tr`, `nl -w`. Fix as part of (1) above.
227
+
228
+
### 8. Help-flag convention
229
+
230
+
Most commands ship `--help` even when POSIX doesn't mention it.
231
+
This is harmless but should be documented in a "kefka extensions"
232
+
note next to each affected command, so reviewers don't keep
233
+
flagging it as a deviation.
234
+
235
+
---
236
+
237
+
## Missing commands
238
+
239
+
These POSIX 2018 utilities have spec docs in `docs/posix2018/` but
240
+
no corresponding implementation in `command/internal/` and no entry
241
+
in `command/registry/coreutils/coreutils.go`.
242
+
243
+
| Command | Spec size | Estimated effort | Why it matters |
244
+
| --- | --- | --- | --- |
245
+
| `cal` | small (~5KB) | 1–2 days | Calendar printing; rarely used by scripts |
246
+
| `chmod` | medium (~21KB) | 3–5 days | Permission management; **critical** for any shell environment. Octal *and* symbolic mode (`u=rwx,g+r`, etc.). |
247
+
| `df` | small (~6KB) | 1–2 days | Filesystem usage; partial-info OK in a virtual FS |
248
+
| `grep` | large (~15KB) | 1–2 weeks | Search via BRE/ERE; **critical** for scripts. `-E`, `-F`, `-c`, `-l`, `-q`, `-i`, `-n`, `-s`, `-v`, `-x`, `-e`, `-f` all required |
249
+
| `ln` | medium (~9KB) | 2–4 days | Hard and symbolic links; needs `billy.Symlink` capability |
250
+
| `more` | medium (~10KB) | 3–5 days | Pager. Interactive — possibly out of scope for a batch shell environment |
251
+
| `patch` | large (~25KB) | 1–2 weeks | Apply diff output. Complex format support (`-c`, `-u`, `-e`, `-l`, `-N`, `-R`) |
252
+
253
+
The two most consequential gaps are **`chmod`** and **`grep`** —
254
+
their absence means scripted shell workflows that touch
255
+
permissions or text search cannot run unmodified.
256
+
257
+
---
258
+
259
+
## Per-command deep dives
260
+
261
+
Sections are alphabetical. Trivially-conforming commands (e.g.,
262
+
`dirname`, `pwd`, `rmdir`) appear here only for completeness; their
263
+
deep dive is one paragraph.
264
+
265
+
### `basename`
266
+
267
+
**Implementation:** `command/internal/basename/basename.go` (95 lines)
268
+
**Test file:** `basename_test.go` (158 lines)
269
+
**Severity:** 🟠 Major (per strict POSIX) / ⬜ None (per GNU coreutils)
270
+
271
+
**Spec options:** spec `basename.md` OPTIONS section says **"None"**.
272
+
273
+
**Deviations:**
274
+
- Ships GNU `--multiple`/`-a` (`basename.go:45`). Cites: spec
275
+
`basename.md` OPTIONS.
276
+
- Ships GNU `--suffix`/`-s` (`basename.go:46`). Cites: spec
277
+
`basename.md` OPTIONS.
278
+
279
+
These are GNU coreutils standard but not in POSIX 2018. Decide
280
+
policy: keep (and document as kefka/GNU extension) or strip.
281
+
282
+
**Required tests:**
283
+
- `basename /usr/lib` → `lib` (POSIX example).
284
+
- `basename /usr/` → `usr` (trailing-slash handling, spec
285
+
DESCRIPTION step 3).
286
+
- `basename / ` → `/` (all-slash special case, spec step 2).
287
+
- `basename "" ` → `""` or `.` per spec step 1.
288
+
- `basename foo.c .c` → `foo` (positional suffix).
289
+
290
+
**Notes:**
291
+
- The two-positional-operand form `basename string suffix` works
292
+
per spec; the GNU extras add a multi-file mode that isn't in
293
+
POSIX.
294
+
295
+
### `cat`
296
+
297
+
**Implementation:** `command/internal/cat/cat.go` (148 lines)
298
+
**Test file:** `cat_test.go` (175 lines)
299
+
**Severity:** 🟠 Major
300
+
301
+
**Spec options:**
302
+
- `-u` (write without delay): **missing**
303
+
- `-n`/`--number`: **extra (not-in-POSIX)** — `cat.md` RATIONALE
304
+
explicitly: *"The **-n** option was omitted because similar
305
+
functionality can be obtained from the **-n** option of the
306
+
pr utility."*
307
+
308
+
**Deviations:**
309
+
- Missing `-u` (`cat.md` OPTIONS — the sole option POSIX requires).
310
+
- Ships `-n`/`--number` (`cat.go:44`).
311
+
- Hardcoded `"No such file or directory"` regardless of the
312
+
underlying errno (`cat.go:94`, `cat.go:100`). EACCES/EISDIR
313
+
cases mis-report.
314
+
315
+
**Required tests:**
316
+
- `cat -u file` is accepted (even if it's a no-op given Go's
317
+
unbuffered `io.Writer` writes).
318
+
- `cat -- -file` reads a file literally named `-file`.
319
+
- `printf foo | cat - -` → `foo` (second `-` produces no extra
320
+
output; spec OPERANDS).
321
+
- `cat <directory>` produces a diagnostic mentioning EISDIR-like
322
+
semantics, not "No such file or directory".
323
+
324
+
**Notes:**
325
+
- Stdout is already direct `io.Writer.Write`, so `-u` is naturally
326
+
honored — accept the flag as a no-op for spec compliance.
327
+
- Decide policy on `-n`: drop it, or keep as documented extension.
328
+
329
+
### `cp`
330
+
331
+
**Implementation:** `command/internal/cp/cp.go` (198 lines)
332
+
**Test file:** `cp_test.go` (298 lines)
333
+
**Severity:** 🟠 Major
334
+
335
+
**Spec options (cp.md):**
336
+
- `-f`: **missing** (the impl has GNU `-n` no-clobber instead)
337
+
- `-H`: **missing** (follow command-line symlinks only)
338
+
- `-L`: **missing** (follow all symlinks)
339
+
- `-P`: **missing** (don't follow any symlinks)
340
+
- `-i`: **missing** (interactive prompt before overwrite)
341
+
- `-p`: **accepted-but-ignored** (`cp.go:55`)
342
+
- `-R`: implemented
343
+
- `-r`: implemented (alias of `-R`)
344
+
345
+
**Deviations:**
346
+
- `-p` parsed but never preserves anything; mtime/atime/uid/gid/
347
+
mode are not applied to the destination (`cp.go:55`,
348
+
`cp.go:148`, `cp.go:171`).
349
+
- Directory creation uses `info.Mode().Perm()` (`cp.go:148`),
350
+
which is source mode — closer to spec, but still doesn't apply
351
+
the file mode creation mask the way `cp.md` step 2e prescribes.
352
+
- `copyFile` writes `0o644` (`cp.go:171`). Spec `cp.md` step 3b
353
+
requires source mode.
354
+
- `-i` (interactive) and `-f` (force-unlink) are not implemented;
355
+
the impl's `-n` is a GNU-coreutils inversion.
356
+
- Three-form synopsis (`cp [-Pfip] src dst`, `cp [-Pfip] src... dir`,
357
+
`cp -R [-H|-L|-P] [...] src... dir`) is not handled — the impl
358
+
collapses these.
359
+
- No same-file detection (spec step 1: "If source_file references
360
+
the same file as dest_file, cp may write a diagnostic and
361
+
exit unsuccessfully").
362
+
363
+
**Required tests:**
364
+
- `cp -p src dst` then stat: dst's mtime equals src's mtime.
365
+
- `cp -p src dst` then stat: dst's mode equals src's mode (not
366
+
0o644).
367
+
- `cp src dst` where `dst` exists: with `-i` should prompt; with
368
+
no flag should overwrite (current behavior).
369
+
- `cp -R dir1 dir2` where dir1 contains files with mode 0o600:
370
+
copies preserve mode.
371
+
- `cp src dst` where src and dst are the same file: emits
372
+
diagnostic, exits non-zero.
373
+
- `cp -- -src dst`: handles file named `-src`.
374
+
375
+
**Notes:**
376
+
- `billy.Filesystem` lacks rich symlink primitives in some
377
+
backends; `-H`/`-L`/`-P` are non-trivial to add and may need
378
+
capability detection on the FS.
379
+
- Pre-implementation: clarify policy on `-n` (keep as extension or
380
+
remove).
381
+
382
+
### `cut`
383
+
384
+
**Implementation:** `command/internal/cut/cut.go` (250 lines)
385
+
**Test file:** `cut_test.go` (233 lines)
386
+
**Severity:** 🟠 Major
387
+
388
+
**Spec options (cut.md):**
389
+
- `-b list`: **missing** (byte-cutting)
390
+
- `-c list`: implemented
391
+
- `-d delim`: implemented
392
+
- `-f list`: implemented
393
+
- `-n`: **missing** (multibyte safety modifier for `-b`)
394
+
- `-s`: implemented (as `--only-delimited`)
395
+
396
+
**Deviations:**
397
+
- No `-b` option; only `-c` and `-f` are usable selectors.
398
+
Cites: `cut.go:48-51`, spec `cut.md` OPTIONS.
399
+
- No `-n` option (would gate `-b` against splitting multibyte
400
+
sequences). Cites: spec `cut.md` OPTIONS lines 65-88.
401
+
- `-b`, `-c`, `-f` are mutually exclusive per spec; impl never
402
+
rejects conflicting selectors. Cites: `cut.go:64-81`.
403
+
- `extractByRanges` (`cut.go:169`) deduplicates by value via a
404
+
map. Spec EXTENDED DESCRIPTION says fields are output once per
405
+
selection and in input order; repeated selections (`-f 1,1`)
406
+
should still output the field once but not silently dedup
407
+
unrelated equal values across positions.
408
+
409
+
**Required tests:**
410
+
- `printf 'a\tb\tc' | cut -b 1-3` → first three bytes (currently:
411
+
not implemented, errors).
412
+
- `printf 'a\tb\tc' | cut -c 1` and `cut -f 1` together — should
413
+
reject as conflict.
414
+
- `printf 'aXa\n' | cut -d X -f 1,1` → `aXa` should not
415
+
collapse the two `a`s.
416
+
- `printf "λa\n" | cut -c 1` → `λ` (one character, two bytes).
417
+
418
+
**Notes:**
419
+
- `-b` and `-n` together are non-trivial; a clean
420
+
implementation needs locale-aware character iteration (see
421
+
cross-cutting #1).
422
+
423
+
### `date`
424
+
425
+
**Implementation:** `command/internal/date/date.go` (231 lines)
426
+
**Test file:** present
427
+
**Severity:** 🟡 Minor (deliberate sandbox choices)
428
+
429
+
**Spec options:** `-u` (UTC), `+FORMAT` (operand).
430
+
431
+
**Deviations:**
432
+
- `date.go:70-73` documents that the sandbox always renders UTC,
433
+
ignoring `TZ`. POSIX says `-u` makes the implementation use UTC;
434
+
by default, `TZ` controls. The impl's UTC-always policy is
435
+
reasonable for a sandbox but should be documented as a kefka
436
+
invariant, not a bug.
437
+
- Format modifiers `%E` and `%O` (locale alternatives) — POSIX
438
+
says they're optional; if unsupported, the unmodified spec
439
+
applies. Verify the impl falls back rather than erroring.
440
+
- XSI extension to set system time via positional `[mmddHHMM[CC]yy[.ss]]`
441
+
is not implemented (out of scope for a sandbox).
442
+
443
+
**Required tests:**
444
+
- `date -u +'%Y-%m-%d'` produces a parseable date string.
445
+
- `date +'%Z'` returns `UTC` (matches sandbox invariant).
446
+
- `date +'%E%Y'` does not error (locale modifier fallback).
447
+
- All conversion specs in spec `date.md` lines 65-240 produce
448
+
defined output.
449
+
450
+
**Notes:**
451
+
- The "always UTC" sandbox decision is fine if explicit. Add a
452
+
one-line comment in `date.go` linking to this audit so future
453
+
contributors don't "fix" it.
454
+
455
+
### `diff`
456
+
457
+
**Implementation:** `command/internal/diff/diff.go` (173 lines)
458
+
**Test file:** `diff_test.go` (207 lines)
459
+
**Severity:** 🟠 Major
460
+
461
+
**Spec options (diff.md):**
462
+
- `-b`: parsed (`diff.go:86`) but underscored-out (unused)
463
+
- `-c`: **missing**
464
+
- `-C n`: **missing**
465
+
- `-e`: **missing**
466
+
- `-f`: **missing**
467
+
- `-r`: **missing**
468
+
- `-u`: implemented (and made the de facto default — see below)
469
+
- `-U n`: **missing**
470
+
471
+
**Deviations:**
472
+
- The default output format (no format flag) should be the
473
+
traditional `Nc`, `Na`, `Nd` ed-style format. Impl always
474
+
outputs unified format (`diff.go:102-115`). Cites: spec
475
+
`diff.md` STDOUT.
476
+
- `-b` (ignore whitespace amount) is parsed but not applied
477
+
(`diff.go:86`).
478
+
- Recursive directory comparison (`-r`) is not implemented.
479
+
- `-q` (brief) and `-s` (report-identical) are GNU additions;
480
+
POSIX `diff.md` does specify `-q` indirectly through
481
+
exit-code semantics but not as a flag — however these are
482
+
widely accepted GNU extensions.
483
+
484
+
**Required tests:**
485
+
- `diff a b` with default output produces traditional format
486
+
(currently produces unified).
487
+
- `diff -c a b` produces context format.
488
+
- `diff -e a b` produces an `ed` script.
489
+
- `diff -b a b` ignores whitespace differences.
490
+
- Exit status: 0 = same, 1 = differ, 2 = error (`diff.md`
491
+
EXIT STATUS). Verify the 2-on-error path with a missing file.
492
+
493
+
**Notes:**
494
+
- The "default = unified" choice is convenient for humans but
495
+
breaks scripts piping diff output to `patch` (which expects
496
+
the traditional or `-c`/`-u` format explicitly).
497
+
498
+
### `dirname`
499
+
500
+
**Implementation:** `command/internal/dirname/dirname.go` (83 lines)
501
+
**Test file:** `dirname_test.go` (135 lines)
502
+
**Severity:** ⬜ None
503
+
504
+
**Notes:** correctly handles all five POSIX `dirname` transformation
505
+
steps. Add tests for the edge cases `dirname //`, `dirname ""`,
506
+
`dirname /usr/bin/` if not already present.
507
+
508
+
### `du`
509
+
510
+
**Implementation:** `command/internal/du/du.go` (230 lines)
511
+
**Test file:** present
512
+
**Severity:** 🟠 Major
513
+
514
+
**Spec options (du.md):**
515
+
- `-a`: implemented
516
+
- `-H`: **missing** (follow command-line symlinks)
517
+
- `-L`: **missing** (follow all symlinks)
518
+
- `-k`: implemented (1024-byte units; matches GNU default)
519
+
- `-s`: implemented
520
+
- `-x`: **missing** (skip files on different filesystems)
521
+
- `--max-depth`: **extra (GNU, not-in-POSIX)**
522
+
523
+
**Deviations:**
524
+
- Default unit is 1024 bytes (`du.go:194`); spec `du.md` line 33
525
+
says default is **512-byte units** (`-k` switches to 1024).
526
+
This is a behavioral break for any script parsing `du` output.
527
+
- `-H`, `-L`, `-x` missing entirely.
528
+
529
+
**Required tests:**
530
+
- `du file` (no `-k`) reports size in 512-byte units. (Today this
531
+
test would *fail* — the bug.)
532
+
- `du -k file` reports size in 1024-byte units.
533
+
- `du -H` follows only command-line symlinks.
534
+
535
+
**Notes:**
536
+
- The 512 vs 1024 default is the kind of cross-cutting "POSIX
537
+
vs GNU" choice that should be made explicitly: either honor
538
+
POSIX strictly, or ship a `BLOCKSIZE` env var (POSIX-allowed)
539
+
letting users pick.
540
+
541
+
### `expand`
542
+
543
+
**Implementation:** `command/internal/expand/expand.go` (233 lines)
544
+
**Test file:** `expand_test.go` (232 lines)
545
+
**Severity:** 🟠 Major
546
+
547
+
**Spec options (expand.md):**
548
+
- `-t tablist`: implemented
549
+
- `-i`/`--initial`: **extra (GNU, not-in-POSIX)**
550
+
551
+
**Deviations:**
552
+
- `-i` is a GNU addition (`expand.go:49`). spec OPTIONS lists
553
+
only `-t`.
554
+
- Tab-stop trailing rule is wrong: when input has tabs past the
555
+
last specified stop, spec says emit a **single space**;
556
+
`expand.go:121-129` extrapolates using the last interval.
557
+
- Column counting is byte-based (`expand.go:164-173`). Multibyte
558
+
characters and combining marks count incorrectly.
559
+
560
+
**Required tests:**
561
+
- `printf 'a\t\t\tx' | expand -t 4,8` → past column 8, each tab
562
+
becomes a single space, not an 8-wide tab.
563
+
- `printf 'λ\tx' | expand` → `λ` is one column (depending on
564
+
locale); the tab stop after it should land at column 8, not 9.
565
+
- `expand -i 'leading\tword\ttrailing'` should be rejected (or
566
+
documented as a kefka extension).
567
+
568
+
### `expr`
569
+
570
+
**Implementation:** `command/internal/expr/expr.go` (429 lines)
571
+
**Test file:** `expr_test.go` (318 lines)
572
+
**Severity:** 🟡 Minor
573
+
574
+
**Spec options:** none (all behavior is via operators).
575
+
576
+
**Deviations:**
577
+
- `:` (regex match) uses Go regex, not POSIX BRE. Cites:
578
+
`expr.go:266`, spec `expr.md` EXTENDED DESCRIPTION lines 173-188.
579
+
POSIX BRE differs from Go regex in: `\(`/`\)` for grouping
580
+
(Go uses `(...)`), `*` literal at start, `\{n,m\}` interval.
581
+
- String compare (`=`, `<`, `>`, etc.) uses byte equality, not
582
+
collation order (`expr.go:150`).
583
+
- Exit status mapping appears correct: 0 = nonzero/nonempty,
584
+
1 = zero/empty, 2 = invalid expression. Verify code 3 (other
585
+
error) is also present.
586
+
587
+
**Required tests:**
588
+
- `expr 'abc' : 'a\(b\)c'` → `b` (BRE grouping).
589
+
- `expr ' ' = ' '` (space vs tab) — collation-aware result
590
+
in locales where they sort differently.
591
+
- `expr 1 + 'foo'` → exit 2.
592
+
- `expr 0` → exit 1 (zero is "false" exit code).
593
+
- `expr ''` → exit 1.
594
+
595
+
**Notes:**
596
+
- The BRE→Go-regex translation could live in a shared helper
597
+
(also useful for the missing `grep` and for `sed` if ever
598
+
added).
599
+
600
+
### `false`
601
+
602
+
**Implementation:** `command/internal/falsecmd/falsecmd.go` (15 lines)
603
+
**Test file:** **none**
604
+
**Severity:** 🟠 Major (only because of test gap)
605
+
606
+
**Notes:**
607
+
- The implementation is correct: returns `interp.ExitStatus(1)`
608
+
unconditionally.
609
+
- The package is named `falsecmd` because `false` is reserved
610
+
in Go expressions; the registry name is still `false`
611
+
(`coreutils.go:74`).
612
+
- **Missing test file**. POSIX `false.md` says: ignore arguments,
613
+
exit non-zero, no output. Add a one-line test exercising this.
614
+
615
+
**Required tests:**
616
+
- `false` → exit 1, empty stdout, empty stderr.
617
+
- `false foo bar baz` → exit 1, empty stdout, empty stderr.
618
+
619
+
### `file`
620
+
621
+
**Implementation:** `command/internal/file/file.go` (sampled ~80 lines)
622
+
**Test file:** present
623
+
**Severity:** 🟠 Major
624
+
625
+
**Spec options (file.md):**
626
+
- `-d`: spec mentions; impl behavior unclear from sample
627
+
- `-h`: present, behavior on symlinks unclear
628
+
- `-i` (mime): present
629
+
- `-M file`: **missing**
630
+
- `-m file`: **missing**
631
+
632
+
**Deviations:**
633
+
- `-M` and `-m` (custom magic test files) are completely missing.
634
+
Spec `file.md` lines 74-94 define a layered system where
635
+
multiple `-M`/`-m`/`-d` may be passed, applied in order.
636
+
- Detection logic is essentially extension-based, not the
637
+
content-heuristic-based test sequence the spec mandates
638
+
(`file.md` DESCRIPTION steps 1-6).
639
+
640
+
**Required tests:**
641
+
- `file unknown.bin` (binary content, no extension) → reports
642
+
"data" or similar non-text classification.
643
+
- `file -i` (or `--mime`) returns MIME types per RFC 2046.
644
+
- `file -h symlink` does not dereference; `file symlink` does.
645
+
646
+
**Notes:**
647
+
- A truly POSIX-compliant `file` requires a magic-number engine.
648
+
This is a substantial body of work; consider documenting
649
+
kefka's `file` as best-effort and not POSIX-compliant.
650
+
651
+
### `fold`
652
+
653
+
**Implementation:** `command/internal/fold/fold.go` (235 lines)
654
+
**Test file:** `fold_test.go` (229 lines)
655
+
**Severity:** 🟠 Major
656
+
657
+
**Spec options (fold.md):** `-b` (bytes), `-s` (break at spaces),
658
+
`-w width`. All implemented.
659
+
660
+
**Deviations:**
661
+
- Carriage return handling: spec says `\r` resets the column
662
+
count to 0 (DESCRIPTION). Impl treats `\r` as decrement-by-1,
663
+
i.e. backspace semantics (`fold.go:167-170`).
664
+
- Tab-stop arithmetic uses `8 - (col % 8)` (`fold.go:168`,
665
+
0-indexed). Spec defines tab stops at columns where
666
+
`(col mod 8) == 1` (1-indexed): columns 1, 9, 17, ...
667
+
- Per-character width assumed to be 1 (`utf8.EncodeRune` returns
668
+
byte count but width is treated as 1 per rune). Multibyte and
669
+
combining characters wrong.
670
+
671
+
**Required tests:**
672
+
- `printf 'a\rb' | fold -w 5` → after `\r`, column resets to 0;
673
+
`b` is at column 0, total length under 5.
674
+
- `printf '\tab' | fold -w 4` → `\t` advances to column 8,
675
+
forcing a fold immediately. With current impl the off-by-one
676
+
produces a different fold point.
677
+
- Multibyte: `printf 'λλλ' | fold -w 3` (East-Asian wide chars)
678
+
folds after one or two characters depending on width definition.
679
+
680
+
### `head`
681
+
682
+
**Implementation:** `command/internal/head/head.go` (254 lines)
683
+
**Test file:** `head_test.go` (223 lines)
684
+
**Severity:** 🟡 Minor
685
+
686
+
**Spec options:** `-n number` (only POSIX option).
687
+
688
+
**Deviations:**
689
+
- `-c`/`--bytes` (`head.go:50`) is a GNU addition. spec `head.md`
690
+
RATIONALE explicitly: *"There is no -c option (as there is in
691
+
tail) because it is not historical practice."*
692
+
- `-q`/`--quiet` and `-v`/`--verbose` are GNU additions.
693
+
- `head` adds a trailing newline if the input lacks one
694
+
(`head.go:194`). Spec STDOUT says copy "in entirety" —
695
+
preserve the absence of a final newline.
696
+
697
+
**Required tests:**
698
+
- `printf 'a\nb\nc' | head -n 2` → `a\nb` (no trailing newline).
699
+
- `head -- -n2` reads a file named `-n2`.
700
+
701
+
**Notes:**
702
+
- `-c`/`-q`/`-v` are universally expected today; consider
703
+
documenting them as kefka extensions rather than removing.
704
+
705
+
### `join`
706
+
707
+
**Implementation:** `command/internal/join/join.go` (324 lines)
708
+
**Test file:** `join_test.go` (222 lines)
709
+
**Severity:** ⬜ None
710
+
711
+
**Notes:**
712
+
- All POSIX options (`-1`, `-2`, `-a`, `-e`, `-o`, `-t`, `-v`)
713
+
are implemented and tested. Spot-check: missing-field handling
714
+
with `-e` looks correct.
715
+
- Verify the spec-required behavior of refusing unsorted input
716
+
(`join.md` says behavior is unspecified if not sorted; impl
717
+
could continue silently, which is allowed).
718
+
719
+
### `ls`
720
+
721
+
**Implementation:** `command/internal/ls/ls.go` (large; sampled
722
+
first 100 lines)
723
+
**Test file:** present
724
+
**Severity:** 🟠 Major
725
+
726
+
**Spec options (ls.md is ~37KB, the longest spec):**
727
+
728
+
| Flag | Status | Notes |
729
+
| --- | --- | --- |
730
+
| `-A` | implemented | line 62 |
731
+
| `-C` | unimplemented | multi-column output |
732
+
| `-F` | implemented | type indicators `*/=>@` |
733
+
| `-H` | unimplemented | command-line symlink follow |
734
+
| `-L` | unimplemented | follow all symlinks |
735
+
| `-R` | implemented | line 68 |
736
+
| `-S` | implemented | sort by size |
737
+
| `-a` | implemented | line 61 |
738
+
| `-c` | unimplemented | use ctime |
739
+
| `-d` | implemented | line 63 |
740
+
| `-f` | unimplemented | unsorted, implies -a |
741
+
| `-h` | implemented | human-readable sizes |
742
+
| `-i` | unimplemented | inode |
743
+
| `-k` | unimplemented | 1024-byte blocks |
744
+
| `-l` | partially | long format incomplete |
745
+
| `-m` | unimplemented | comma-separated |
746
+
| `-n` | unimplemented | numeric uid/gid |
747
+
| `-o` | unimplemented | long without group |
748
+
| `-p` | unimplemented | type slash on dirs |
749
+
| `-q` | unimplemented | non-printable as `?` |
750
+
| `-r` | implemented | line 67 |
751
+
| `-s` | unimplemented | block count |
752
+
| `-t` | parsed but unused | `_` underscore (line 83) |
753
+
| `-u` | unimplemented | use atime |
754
+
| `-x` | unimplemented | column order |
755
+
| `-1` | parsed but unused | `_` underscore (line 84) |
756
+
757
+
**Deviations:**
758
+
- `sortByTime` and `onePerLine` are accepted at the flag layer
759
+
but never wired to behavior (`ls.go:83-84`). They look like
760
+
the work was started and not completed.
761
+
- Long format (`-l`) has incomplete implementations of the spec's
762
+
STDOUT format (file mode bits including suid/sgid `s`/`S` and
763
+
sticky `t`/`T`, the date format that switches between
764
+
`Mon DD HH:MM` and `Mon DD YYYY` based on age, locale-aware
765
+
date formatting).
766
+
767
+
**Required tests:**
768
+
- `ls -t` orders by mtime (currently unwired).
769
+
- `ls -1` outputs one entry per line.
770
+
- `ls -l` on a file with mode `04755` shows `-rwsr-xr-x`
771
+
(suid bit display).
772
+
- `ls -l` on a directory with sticky bit shows `t` or `T`.
773
+
- `ls -l` on a recently-modified file shows `Mon DD HH:MM`;
774
+
on a 1-year-old file shows `Mon DD YYYY`.
775
+
776
+
**Notes:**
777
+
- `ls` is the largest single-utility audit item. The cleanest
778
+
path is probably to (a) finish wiring the parsed-but-unused
779
+
flags first, then (b) tackle the `-l` long-format STDOUT
780
+
spec section by section.
781
+
782
+
### `mkdir`
783
+
784
+
**Implementation:** `command/internal/mkdir/mkdir.go` (123 lines)
785
+
**Test file:** `mkdir_test.go` (251 lines)
786
+
**Severity:** 🟠 Major
787
+
788
+
**Spec options (mkdir.md):**
789
+
- `-m mode`: **missing entirely**
790
+
- `-p`: implemented (line 48)
791
+
792
+
**Deviations:**
793
+
- `-m mode` is one of only two POSIX options and is missing.
794
+
Spec lines 35-43.
795
+
- Created directories use hardcoded `0o755` (`mkdir.go:88`);
796
+
spec says "absolute pathname's permissions modified by the
797
+
file mode creation mask".
798
+
- Intermediate directories (created via `-p`) have no
799
+
permissions logic. Spec mkdir.md line 49-51 / RATIONALE 168-173
800
+
prescribes intermediate-dir mode of `(S_IWUSR|S_IXUSR|~filemask)`
801
+
before they receive the final mode.
802
+
803
+
**Required tests:**
804
+
- `mkdir -m 0700 newdir`, then stat: mode is 0o700.
805
+
- `mkdir -m u=rwx,g=rx,o= newdir` (symbolic mode).
806
+
- `mkdir -p a/b/c` with restrictive umask: intermediates get
807
+
`u+wx` for traversal, leaf gets the requested mode.
808
+
- `mkdir existing_dir` exits non-zero with "File exists" error.
809
+
- `mkdir -p existing_dir` is silent and exits 0 (today: works).
810
+
811
+
**Notes:**
812
+
- Symbolic mode parsing is non-trivial (`u+rwx,g-w,o=`); shares
813
+
logic with the missing `chmod`. Implement once.
814
+
815
+
### `mv`
816
+
817
+
**Implementation:** `command/internal/mv/mv.go` (152 lines)
818
+
**Test file:** `mv_test.go` (299 lines)
819
+
**Severity:** 🟠 Major
820
+
821
+
**Spec options (mv.md):**
822
+
- `-f`: implemented (line 49)
823
+
- `-i`: **missing**
824
+
- `-n`: **extra (GNU, not-in-POSIX)** (line 50)
825
+
826
+
**Deviations:**
827
+
- `-i` (interactive prompt) missing. Spec `mv.md` DESCRIPTION
828
+
step 1 mandates a prompt when (a) destination exists and is
829
+
not writable, *and* stdin is a terminal, or (b) `-i` is set.
830
+
- "Same file" detection (spec DESCRIPTION step 2) missing —
831
+
`mv a b` where b hard-links to a should produce a diagnostic.
832
+
- Cross-filesystem move fallback (spec steps 4-7: copy hierarchy,
833
+
preserve metadata, then unlink source) is not implemented.
834
+
Impl just calls `Rename` (line 118), which fails across FSes.
835
+
- Mode/uid/gid preservation on cross-fs moves: not implemented.
836
+
- `mv.go:64-68` makes `-n` take precedence over `-f`. POSIX
837
+
`mv.md` says "the last specified shall take precedence";
838
+
`-n` is GNU so this is a kefka invariant, but document it.
839
+
840
+
**Required tests:**
841
+
- `mv -i src dst` with dst existing prompts y/n.
842
+
- `mv samefile linkedfile` (both same inode) emits diagnostic.
843
+
- Cross-fs mv: pre-populate two billy memfs roots and `mv`
844
+
across them; verify the file ends up at dst with src removed
845
+
and metadata preserved.
846
+
847
+
### `nl`
848
+
849
+
**Implementation:** `command/internal/nl/nl.go` (267 lines)
850
+
**Test file:** `nl_test.go` (225 lines)
851
+
**Severity:** 🟠 Major
852
+
853
+
**Spec options (nl.md):**
854
+
- `-b type`: implemented
855
+
- `-d delim`: **missing** (logical-page delimiters)
856
+
- `-f type`: **missing** (footer numbering)
857
+
- `-h type`: **missing** (header numbering)
858
+
- `-i incr`: implemented
859
+
- `-l num`: **missing** (consecutive-blank-line grouping)
860
+
- `-n format`: implemented
861
+
- `-p`: **missing** (don't reset numbering at page breaks)
862
+
- `-s sep`: implemented
863
+
- `-v startnum`: implemented
864
+
- `-w width`: implemented
865
+
866
+
**Deviations:**
867
+
- 5 of 11 spec options are missing.
868
+
- The "logical page" concept (header/body/footer separated by
869
+
`\:\:\:`, `\:\:`, `\:` markers) is unimplemented. Without it,
870
+
most of POSIX `nl`'s behavior cannot be exercised.
871
+
- Separator-suppression rule (when a line is not numbered, its
872
+
number-and-separator field should be blanks of the same width)
873
+
partially implemented (line 170 emits spaces + the separator
874
+
even when unnumbered).
875
+
876
+
**Required tests:**
877
+
- Input with `\:\:\:` (header), `\:\:` (body), `\:` (footer)
878
+
delimiters: numbering resets per section per `-h`/`-b`/`-f`.
879
+
- `-p` keeps numbering across page breaks.
880
+
- `-l 3` collapses 3+ consecutive empty lines into one numbered
881
+
unit.
882
+
- Unnumbered line: leading field is `width + sep_len` worth of
883
+
spaces, not `width` spaces + separator.
884
+
885
+
### `od`
886
+
887
+
**Implementation:** `command/internal/od/od.go` (223 lines)
888
+
**Test file:** present
889
+
**Severity:** 🟠 Major
890
+
891
+
**Spec options (od.md):**
892
+
- `-A` (address base): implemented
893
+
- `-t` (type spec): partial — only `c`, `x1`, `o*` parsed
894
+
(`od.go:74-78`)
895
+
- `-v` (verbose, no compression): **missing**
896
+
- `-j` (skip): **missing**
897
+
- `-N` (count): **missing**
898
+
- `-b`/`-c`/`-d`/`-o`/`-s`/`-x` (XSI shorthands): only `-c`
899
+
appears (`od.go:57`)
900
+
901
+
**Deviations:**
902
+
- `-t` accepts a tiny subset; full grammar (`a`, `c`, `d`, `f`,
903
+
`o`, `u`, `x`, with optional size suffix or `C`/`S`/`I`/`L`,
904
+
comma-separated lists) unsupported.
905
+
- Repeated identical 16-byte lines should be collapsed to a `*`
906
+
unless `-v` is given; impl always emits all lines (no
907
+
compression mode at all).
908
+
- 16-bytes-per-line layout hardcoded (`od.go:139`); spec allows
909
+
variable block sizes derived from `-t`.
910
+
911
+
**Required tests (extending the existing `od_test.go`):**
912
+
- `printf '%s' "AB" | od -t d2` → 2-byte signed decimal value.
913
+
- `printf 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' | od` → repeated
914
+
blocks collapsed to `*`.
915
+
- `od -j 4 -N 8 file` → skips 4 bytes, reads next 8.
916
+
- `od -A d` → addresses in decimal.
917
+
918
+
**Notes:**
919
+
- The existing test file likely covers only the small subset of
920
+
`-t` formats the impl supports; expand it as the
921
+
implementation grows.
922
+
923
+
### `paste`
924
+
925
+
**Implementation:** `command/internal/paste/paste.go` (214 lines)
926
+
**Test file:** `paste_test.go` (193 lines)
927
+
**Severity:** 🟠 Major
928
+
929
+
**Spec options (paste.md):** `-d list`, `-s`. Both implemented.
930
+
931
+
**Deviations:**
932
+
- `-d list` does not parse backslash escapes. Spec says `\n`,
933
+
`\t`, `\\`, `\0` are recognized (`paste.md` OPTIONS); impl
934
+
treats every char as literal (`paste.go:133-152`).
935
+
- Empty `-d ""` is silently accepted; spec says behavior with
936
+
empty list is unspecified — fine to allow but document.
937
+
- Circular reset of the delimiter list: spec says reset to first
938
+
element after each output line in non-`-s` mode, and after
939
+
each *file* in `-s` mode. The non-`-s` case is correct;
940
+
`-s` reset rule untested.
941
+
942
+
**Required tests:**
943
+
- `paste -d '\t' a b` outputs columns separated by literal
944
+
tab (currently outputs literal `\` + `t`).
945
+
- `paste -d 'a\nb' f1 f2 f3` cycles `a`, `\n`, `b`, then `a`,
946
+
...
947
+
- `paste -s -d 'X' f` joins f's lines with X; reset to X at
948
+
end-of-file when next file is processed.
949
+
950
+
### `printf`
951
+
952
+
**Implementation:** `command/internal/printf/printf.go` (1228 lines!)
953
+
**Test file:** present
954
+
**Severity:** 🟡 Minor
955
+
956
+
**Spec options:** none in POSIX. Impl ships bash's `-v VAR`
957
+
(target a variable instead of stdout) — that's a bash builtin
958
+
extension, not a POSIX `printf`(1) option.
959
+
960
+
**Deviations:**
961
+
- The `-v VAR` flag conflicts with POSIX `printf VAR ...` where
962
+
`VAR` would be a format string starting with `-`. Spec
963
+
recommends users prefix with `--` for unambiguous parsing —
964
+
verify this works.
965
+
- Format string reuse rule (`printf.md` lines 155-161: "format
966
+
shall be reused as often as necessary to satisfy the argument
967
+
operands") looks correct (`printf.go:96-110`).
968
+
- `%b` (escape interpretation per spec lines 123-149) and
969
+
`%c` (single-character) are the historical rough edges. Audit
970
+
with explicit tests.
971
+
972
+
**Required tests:**
973
+
- `printf '%b' '\\n'` → newline.
974
+
- `printf '%b' '\\c'` → terminate, no further output.
975
+
- `printf '%d %d\n' 1 2 3 4` → `1 2\n3 4\n` (format reuse).
976
+
- `printf '%5.3s' hello` → ` hel` (precision truncates).
977
+
- `printf '%(%Y)T' 0` → `1970` (POSIX strftime conversion;
978
+
optional but commonly supported).
979
+
- `printf -- '-v=stuff' ` (literal dash-v as format).
980
+
981
+
**Notes:**
982
+
- 1228 lines is large; most of the surface is likely correct.
983
+
Focus tests on `%b`, `%c`, width/precision, multi-arg reuse.
984
+
985
+
### `pwd`
986
+
987
+
**Implementation:** `command/internal/pwd/pwd.go` (136 lines)
988
+
**Test file:** present
989
+
**Severity:** ⬜ None
990
+
991
+
**Notes:**
992
+
- `-L` and `-P` both implemented (`pwd.go:45-46`).
993
+
- Realpath logic with symlink resolution at `pwd.go:99-135`.
994
+
- Verify `-L` falls back to physical when `$PWD` is invalid
995
+
(spec `pwd.md` DESCRIPTION step 1).
996
+
997
+
### `rm`
998
+
999
+
**Implementation:** `command/internal/rm/rm.go` (155 lines)
1000
+
**Test file:** `rm_test.go` (286 lines)
1001
+
**Severity:** 🟡 Minor
1002
+
1003
+
**Spec options:** `-f` (line 53), `-i` (**missing**), `-R` /
1004
+
`-r` (lines 51-52).
1005
+
1006
+
**Deviations:**
1007
+
- `-i` (interactive prompt) missing. POSIX `rm.md` step 2b
1008
+
requires a prompt when (file is not writable AND stdin is
1009
+
terminal) AND `-f` is not set; `-i` makes the prompt
1010
+
unconditional.
1011
+
- Symlink handling (`rm.md` step 2c says "shall not traverse
1012
+
directories by following symbolic links into other parts of
1013
+
the file hierarchy") looks correct (`rm.go:51`).
1014
+
1015
+
**Required tests:**
1016
+
- `rm -i file` prompts before removing.
1017
+
- `rm readonly_file` (no `-f`, stdin is terminal) prompts.
1018
+
- `rm -r dir_with_symlink_to_outside` does not follow the
1019
+
symlink.
1020
+
1021
+
### `rmdir`
1022
+
1023
+
**Implementation:** `command/internal/rmdir/rmdir.go` (154 lines)
1024
+
**Test file:** `rmdir_test.go` (282 lines)
1025
+
**Severity:** ⬜ None
1026
+
1027
+
**Notes:**
1028
+
- `-p` correctly removes parent dirs only when they become
1029
+
empty (`rmdir.go:48`, tested at `rmdir_test.go:130-182`).
1030
+
- GNU `-v` (verbose) is shipped; document as kefka extension.
1031
+
1032
+
### `sleep`
1033
+
1034
+
**Implementation:** `command/internal/sleep/sleep.go` (123 lines)
1035
+
**Test file:** present
1036
+
**Severity:** 🟡 Minor
1037
+
1038
+
**Spec options (sleep.md):** "None".
1039
+
1040
+
**Deviations:**
1041
+
- Accepts multiple operands and sums them (`sleep.go:62-76`).
1042
+
Spec `sleep.md` OPERANDS says one operand. Multiple is a GNU
1043
+
extension.
1044
+
- Accepts fractional seconds (`sleep.go:21` `\d+\.?\d*`). Spec
1045
+
says "non-negative decimal integer".
1046
+
- Accepts `m`/`h`/`d` suffixes. Spec says seconds only.
1047
+
- Caps sleep at one hour (`sleep.go:19` `maxSleep = time.Hour`).
1048
+
Spec RATIONALE says implementations must accept up to
1049
+
2147483647 seconds (~68 years). The cap is a kefka invariant —
1050
+
document it.
1051
+
1052
+
**Required tests:**
1053
+
- `sleep 0` returns immediately, exit 0.
1054
+
- `sleep abc` exits non-zero with diagnostic.
1055
+
- `sleep 1.5` — kefka extension, document.
1056
+
- `sleep 7200` (2 hours) — would currently cap at 1 hour. Either
1057
+
fix or document.
1058
+
1059
+
### `split`
1060
+
1061
+
**Implementation:** `command/internal/split/split.go` (345 lines)
1062
+
**Test file:** `split_test.go` (448 lines)
1063
+
**Severity:** ⬜ None
1064
+
1065
+
**Notes:**
1066
+
- Comprehensive impl; `-l`, `-a`, `-b` all present and tested.
1067
+
- `-` operand for stdin: verify.
1068
+
1069
+
### `tail`
1070
+
1071
+
**Implementation:** `command/internal/tail/tail.go` (291 lines)
1072
+
**Test file:** `tail_test.go` (238 lines)
1073
+
**Severity:** 🟡 Minor
1074
+
1075
+
**Spec options (tail.md):**
1076
+
- `-c number`: implemented
1077
+
- `-n number`: implemented
1078
+
- `-f`: **missing** (follow mode)
1079
+
1080
+
**Deviations:**
1081
+
- `-f` is the most-requested missing feature. POSIX `tail.md`
1082
+
says: "if the input file is a regular file or if the *file*
1083
+
operand specifies a FIFO, do not terminate after the last
1084
+
line of the input file has been copied, but read and copy
1085
+
further bytes from the input file when they become
1086
+
available."
1087
+
- Trailing-newline addition in fromLine mode (`tail.go:208-211`)
1088
+
mirrors the same bug as `head`. Preserve absence of final
1089
+
newline.
1090
+
1091
+
**Required tests:**
1092
+
- `tail -f file` continues reading as file grows (challenging
1093
+
to test deterministically; needs the harness to write to the
1094
+
file from another goroutine).
1095
+
- `printf 'a\nb\nc' | tail -n 1` → `c` (no trailing newline).
1096
+
1097
+
### `tee`
1098
+
1099
+
**Implementation:** `command/internal/tee/tee.go` (126 lines)
1100
+
**Test file:** `tee_test.go` (197 lines)
1101
+
**Severity:** 🟡 Minor
1102
+
1103
+
**Note:** **No local spec doc** at `docs/posix2018/tee.md`,
1104
+
even though POSIX 2018 includes `tee` (XCU §2.30, 9699919799).
1105
+
1106
+
**Spec options:** `-a` (append, implemented), `-i` (ignore SIGINT,
1107
+
**missing**).
1108
+
1109
+
**Deviations:**
1110
+
- No SIGINT handler (`tee.go` lacks `signal.Notify`). When the
1111
+
shell interrupts, tee dies with the rest; in real tee, `-i`
1112
+
causes it to keep running until stdin EOFs.
1113
+
1114
+
**Required tests:**
1115
+
- `tee -i file` continues to write after a simulated SIGINT.
1116
+
Harder than typical table-driven tests; consider a separate
1117
+
signal-handling test file.
1118
+
1119
+
**Action:** Add `docs/posix2018/tee.md` from upstream POSIX text
1120
+
and delete this "no spec doc" note.
1121
+
1122
+
### `time`
1123
+
1124
+
**Implementation:** `command/internal/time/time.go` (220+ lines)
1125
+
**Test file:** present
1126
+
**Severity:** 🟠 Major
1127
+
1128
+
**Spec options (time.md per spec):** `-p` portable format; the
1129
+
spec is short.
1130
+
1131
+
**Deviations:**
1132
+
- Impl ships `-f`, `-o`, `-a`, `-v` (GNU `/usr/bin/time` flags),
1133
+
not POSIX `time` (a shell-builtin spec).
1134
+
- `Impl` struct holds `Registry` (`time.go:23-26`) and dispatches
1135
+
to a registered command. POSIX `time COMMAND ARGS` invokes
1136
+
the command directly via `execvp`-style search. The registry
1137
+
coupling is fine for an in-process shell environment but
1138
+
diverges from any user expectation set by the spec.
1139
+
- A `time_test.go` file exists; verify it exercises the spec
1140
+
surface (real/user/sys reporting, `-p` portable format,
1141
+
exit-status propagation) and not just GNU extras.
1142
+
1143
+
**Required tests:**
1144
+
- `time true` writes a three-line `real`/`user`/`sys` summary to
1145
+
stderr (or, with `-p`, the portable format).
1146
+
- `time false`: exit status is 1 (propagated from `false`).
1147
+
- `time` with no command: behavior per spec is to print usage —
1148
+
what does the impl do? Verify.
1149
+
1150
+
### `touch`
1151
+
1152
+
**Implementation:** `command/internal/touch/touch.go` (167 lines)
1153
+
**Test file:** `touch_test.go` (306 lines)
1154
+
**Severity:** 🟠 Major
1155
+
1156
+
**Spec options (touch.md):**
1157
+
- `-a`: **accepted-but-ignored** (line 54)
1158
+
- `-c`: implemented (line 52)
1159
+
- `-d date`: implemented (line 53; lenient parser)
1160
+
- `-h`: not in spec; needed only on systems with symlinks
1161
+
- `-m`: **accepted-but-ignored** (line 55)
1162
+
- `-r ref_file`: **accepted-but-ignored** (line 56)
1163
+
- `-t [[CC]YY]MMDDhhmm[.SS]`: **accepted-but-ignored** (line 57)
1164
+
1165
+
**Deviations:**
1166
+
- `-a`/`-m` are no-ops; both atime and mtime are always set
1167
+
(`touch.go:110`).
1168
+
- `-r` and `-t` accept arguments but never consult them.
1169
+
- Default file creation mode is `0o644` (`touch.go:96`); spec
1170
+
says `S_IRUSR|S_IWUSR|S_IRGRP|S_IWGRP|S_IROTH|S_IWOTH` (0o666)
1171
+
modified by umask.
1172
+
- `-d` (`touch.go:127-143`) accepts RFC3339 etc., looser than
1173
+
spec lines 73-107 which define a strict
1174
+
`YYYY-MM-DDThh:mm:SS[.frac][tz]` format.
1175
+
1176
+
**Required tests:**
1177
+
- `touch -a file`, then stat: mtime unchanged, atime updated.
1178
+
- `touch -m file`, then stat: atime unchanged, mtime updated.
1179
+
- `touch -r ref new`, then stat: new's times equal ref's.
1180
+
- `touch -t 199501010100.30 new` parses to 1995-01-01 01:00:30.
1181
+
- New file created mode (umask 022): 0o644 today; should be
1182
+
0o644 (= 0o666 & ~0o022) — coincidentally correct under that
1183
+
umask, but wrong under others. Fix to compute from umask.
1184
+
1185
+
**Notes:**
1186
+
- The four accepted-but-ignored flags should either be wired
1187
+
up or removed (silently ignoring user intent is worse than
1188
+
rejecting the flag).
1189
+
1190
+
### `tr`
1191
+
1192
+
**Implementation:** `command/internal/tr/tr.go` (sampled ~80 lines;
1193
+
likely larger)
1194
+
**Test file:** present (sampled)
1195
+
**Severity:** 🟠 Major
1196
+
1197
+
**Spec options:** `-c` / `-C` (complement), `-d` (delete),
1198
+
`-s` (squeeze).
1199
+
1200
+
**Deviations:**
1201
+
- No octal escape parsing (`\nnn`); spec mandates these (`tr.md`
1202
+
EXTENDED DESCRIPTION).
1203
+
- No backslash-escape parsing (`\n`, `\t`, `\\`, `\r`, etc.).
1204
+
- `[=equiv=]` equivalence classes unsupported.
1205
+
- `[:class:]` character classes likely unsupported beyond a
1206
+
hardcoded set; LC_CTYPE not consulted.
1207
+
- Range expansion (`a-z`) is byte-based; spec says "characters
1208
+
in the current locale collation sequence" (LC_COLLATE).
1209
+
- `-c` and `-C` are not distinguished; `-c` complement is "by
1210
+
numeric byte value", `-C` is "by character per LC_CTYPE".
1211
+
1212
+
**Required tests:**
1213
+
- `printf 'A' | tr '\101' 'a'` → `a` (octal 101 = 'A').
1214
+
- `printf 'a\nb' | tr '\n' ' '` → `a b`.
1215
+
- `tr '[=e=]' E` (equivalence class) — locale-dependent.
1216
+
- `tr '[:lower:]' '[:upper:]'`.
1217
+
- `tr -c 'a-z' 'X'` (complement-by-value).
1218
+
- `tr -C 'a-z' 'X'` (complement-by-character — different in
1219
+
multibyte locales).
1220
+
1221
+
**Notes:**
1222
+
- A real `tr` is substantial work. Document current impl as
1223
+
"ASCII-only, GNU-compatible subset; not full POSIX".
1224
+
1225
+
### `true`
1226
+
1227
+
**Implementation:** `command/internal/truecmd/truecmd.go` (14 lines)
1228
+
**Test file:** **none**
1229
+
**Severity:** 🟠 Major (only because of test gap)
1230
+
1231
+
**Notes:**
1232
+
- Returns `nil` (zero exit). Correct per `true.md`.
1233
+
- Registered as `true` (`coreutils.go:106`).
1234
+
- **Missing test file**.
1235
+
1236
+
**Required tests:**
1237
+
- `true` → exit 0, empty stdout, empty stderr.
1238
+
- `true ignored args here` → still exit 0.
1239
+
1240
+
### `unexpand`
1241
+
1242
+
**Implementation:** `command/internal/unexpand/unexpand.go` (~100
1243
+
lines sampled)
1244
+
**Test file:** present
1245
+
**Severity:** 🟡 Minor
1246
+
1247
+
**Spec options (unexpand.md):**
1248
+
- `-a`: implemented (line 49)
1249
+
- `-t tablist`: implemented (line 50)
1250
+
1251
+
**Deviations:**
1252
+
- `-t` should *imply* `-a` per spec OPTIONS: "When `-t` is
1253
+
specified, the presence or absence of the `-a` option shall
1254
+
be ignored". Verify the impl does this — current code tracks
1255
+
the two flags independently.
1256
+
- Beyond-last-tabstop rule: spec says "no \<space\>-to-\<tab\>
1257
+
conversions shall occur for characters at positions beyond
1258
+
the last of those specified in a multiple tab-stop list".
1259
+
- Backspace handling: column never decrements below 1.
1260
+
1261
+
**Required tests:**
1262
+
- `unexpand -t 4` (no `-a`) on `' a b c'` converts
1263
+
every leading space-quad to a tab, even after non-blanks
1264
+
(spec's `-t` overrides leading-only behavior).
1265
+
- `unexpand -a -t 4 '...beyond_last_stop spaces...'` leaves
1266
+
trailing spaces untouched.
1267
+
- Backspace input never produces column < 1.
1268
+
1269
+
### `uniq`
1270
+
1271
+
**Implementation:** `command/internal/uniq/uniq.go` (~100 lines
1272
+
sampled)
1273
+
**Test file:** present
1274
+
**Severity:** 🟠 Major
1275
+
1276
+
**Spec options (uniq.md):**
1277
+
- `-c`: implemented
1278
+
- `-d`: implemented
1279
+
- `-f fields`: **missing**
1280
+
- `-s chars`: **missing**
1281
+
- `-u`: implemented
1282
+
- `-i`: **extra (GNU, not-in-POSIX)** (`uniq.go:50`)
1283
+
1284
+
**Deviations:**
1285
+
- `-f` (skip first N fields when comparing) and `-s` (skip first
1286
+
N chars) are core POSIX options and missing.
1287
+
- The `[input_file [output_file]]` operand pair is collapsed:
1288
+
impl treats both positionals as input files (`uniq.go:63-64`).
1289
+
Spec says the second operand is the output file.
1290
+
1291
+
**Required tests:**
1292
+
- `printf 'x foo\ny foo\n' | uniq -f 1` → `x foo\n` (treats
1293
+
as same line because field 1 is identical).
1294
+
- `printf 'AAfoo\nBBfoo\n' | uniq -s 2` → `AAfoo\n`.
1295
+
- `uniq input.txt output.txt` writes deduplicated content to
1296
+
output.txt.
1297
+
1298
+
### `wc`
1299
+
1300
+
**Implementation:** `command/internal/wc/wc.go` (268 lines)
1301
+
**Test file:** `wc_test.go` (225 lines)
1302
+
**Severity:** 🟠 Major
1303
+
1304
+
**Spec options (wc.md):** `-c` (bytes), `-l` (lines),
1305
+
`-m` (chars), `-w` (words). All accepted.
1306
+
1307
+
**Deviations:**
1308
+
- `-c` and `-m` are conflated: `showChars := *bytesFlag ||
1309
+
*charsFlag` (`wc.go:78`). Spec says they are independent;
1310
+
in a multibyte locale they differ.
1311
+
- `s.chars = len(content)` (`wc.go:201`) counts bytes, not
1312
+
characters, so `-m` returns the byte count.
1313
+
- Word splitting checks only ASCII whitespace `' '`, `'\t'`,
1314
+
`'\r'`, `'\n'` (`wc.go:211`). Spec says
1315
+
"characters defined by the LC_CTYPE category as white-space".
1316
+
1317
+
**Required tests:**
1318
+
- `printf 'λλλ' | wc -c` → 6 (bytes).
1319
+
- `printf 'λλλ' | wc -m` → 3 (characters).
1320
+
- `printf 'λλλ' | wc -c -m` → both shown distinctly. Today
1321
+
this would show the same number.
1322
+
- `wc -w` on input with no-break space (U+00A0): currently
1323
+
treated as part of a word; in en_US.UTF-8 locale, NBSP is
1324
+
whitespace.
1325
+
1326
+
### `zcat`
1327
+
1328
+
**Implementation:** `command/internal/zcat/zcat.go` (248 lines)
1329
+
**Test file:** `zcat_test.go` (255 lines)
1330
+
**Severity:** ⬜ None
1331
+
1332
+
**Notes:**
1333
+
- Decompresses gzip; correct for the tiny POSIX `zcat.md`
1334
+
surface area (which is essentially `gunzip -c`).
1335
+
- GNU extras (`-f`, `-l`, `-q`, `-S`, `-t`, `-v`) are
1336
+
conventionally accepted.
1337
+
1338
+
---
1339
+
1340
+
## Non-POSIX extras
1341
+
1342
+
These commands have no POSIX 2018 spec; the audit is against the
1343
+
de-facto reference for each.
1344
+
1345
+
### `base64` (376 lines, tested)
1346
+
Reference: GNU coreutils `base64(1)`. Standard `-d`/`--decode`,
1347
+
`-w`/`--wrap`. No deep audit performed; implementation looks
1348
+
straightforward (uses `encoding/base64`).
1349
+
1350
+
### `checksum` (222 lines, **no test file**, **not registered**)
1351
+
Internal helper module shared by `md5sum`, `sha1sum`,
1352
+
`sha256sum`. Not exposed to the registry. The shared parser of
1353
+
the `<hash> <file>` BSD-tag and GNU formats is the obvious
1354
+
test target.
1355
+
1356
+
### `clear` (142 lines, tested)
1357
+
Reference: `terminfo`/ncurses `clear(1)`. Likely emits a fixed
1358
+
ANSI sequence; there's no deep spec.
1359
+
1360
+
### `column` (505 lines, tested)
1361
+
Reference: BSD `column(1)` / `util-linux column(1)`. Behavior
1362
+
between BSD and util-linux differs (`-t`, `-s`, `-c`, `-x`).
1363
+
Pick one and document it.
1364
+
1365
+
### `gunzip` (702 lines, tested)
1366
+
Reference: RFC 1952 + GNU `gunzip(1)`. `gzip` and `gunzip`
1367
+
are the largest extras. Verify multi-member gzip handling.
1368
+
1369
+
### `gzip` (920 lines, tested)
1370
+
Reference: RFC 1952 + GNU `gzip(1)`. Largest single extra. The
1371
+
RFC defines the byte format precisely; GNU adds many CLI flags.
1372
+
1373
+
### `hostname` (17 lines, **no test file**)
1374
+
Reference: BSD `hostname(1)`. Probably just returns
1375
+
`os.Hostname()` — verify. No tests.
1376
+
1377
+
### `md5sum` (298 lines, tested)
1378
+
Reference: GNU coreutils `md5sum(1)`. Uses `command/internal/checksum`.
1379
+
1380
+
### `python3` (65 lines + `python.wasm`, **no test file**, **not
1381
+
registered**)
1382
+
A wasm shim. Not part of POSIX or GNU coreutils; out of scope
1383
+
for the conformance audit. Confirm whether it should be exposed
1384
+
via the registry — currently it isn't.
1385
+
1386
+
### `readlink` (377 lines, tested)
1387
+
Reference: GNU coreutils `readlink(1)` (BSD's is simpler).
1388
+
Verify `-f` (canonicalize), `-e`, `-m`, `-n` semantics match
1389
+
the GNU variant the size suggests.
1390
+
1391
+
### `seq` (388 lines, tested)
1392
+
Reference: GNU coreutils `seq(1)`. Common script tool;
1393
+
not in POSIX. `-f format`, `-s separator`, `-w` (equal width).
1394
+
1395
+
### `sha1sum` (104 lines, tested)
1396
+
Reference: GNU coreutils `sha1sum(1)`. Thin wrapper around
1397
+
`checksum`.
1398
+
1399
+
### `sha256sum` (104 lines, tested)
1400
+
Reference: GNU coreutils `sha256sum(1)`. Thin wrapper around
1401
+
`checksum`.
1402
+
1403
+
### `stat` (419 lines, tested)
1404
+
Reference: GNU coreutils `stat(1)` (BSD `stat(1)` differs
1405
+
substantially). Format string `-c`/`--format` and `--printf`
1406
+
are GNU-specific. Document which variant is targeted.
1407
+
1408
+
### `tac` (304 lines, tested)
1409
+
Reference: GNU coreutils `tac(1)` (cat reversed). `-r`, `-s`,
1410
+
`-b` are non-trivial to implement correctly — verify.
1411
+
1412
+
### `tree` (488 lines, tested)
1413
+
Reference: Steve Baker's `tree(1)`. Many flags (`-L`, `-d`,
1414
+
`-f`, `-a`, `-J`, `-X`, etc.); audit against the upstream
1415
+
man page if conformance matters.
1416
+
1417
+
### `whoami` (150 lines, tested)
1418
+
Reference: GNU coreutils `whoami(1)`. Small surface; the impl
1419
+
is 56 lines, the test 94 lines.
1420
+
1421
+
---
1422
+
1423
+
## Recommendations
1424
+
1425
+
In priority order:
1426
+
1427
+
1. **Add tests for `true` and `false`** — these are the only
1428
+
implementations with no `_test.go` at all. Even a one-line
1429
+
"exits 0/1 with no output" test prevents regressions.
1430
+
1431
+
2. **Decide and document the GNU-extension policy.** Many
1432
+
commands ship GNU-coreutils options that POSIX doesn't list
1433
+
(`cat -n`, `head -c`/`-q`/`-v`, `uniq -i`, `mv -n`,
1434
+
`basename -a`/`-s`, `sleep` fractional, etc.). Three options:
1435
+
1. Strip them (strict POSIX).
1436
+
2. Keep them, add a `## kefka extensions` section in each
1437
+
relevant docs/posix2018 doc.
1438
+
3. Track them in a single `EXTENSIONS.md` next to this file.
1439
+
1440
+
Whichever you pick, do it once, uniformly.
1441
+
1442
+
3. **Fix `wc` and `du` defaults** — these are the "scripts will
1443
+
break" tier:
1444
+
- `wc -m` must count characters, not bytes
1445
+
(`wc.go:201`).
1446
+
- `wc -c` and `-m` must be independent
1447
+
(`wc.go:78`).
1448
+
- `du` default block size must be 512, not 1024
1449
+
(`du.go:194`). Or expose `BLOCKSIZE` env var.
1450
+
1451
+
4. **Implement `chmod` and `grep`** — the two missing utilities
1452
+
that scripts rely on most. `grep` needs a BRE↔Go-regex
1453
+
translator that `expr` could share.
1454
+
1455
+
5. **Wire up accepted-but-ignored flags or remove them.**
1456
+
`touch -a`/`-m`/`-r`/`-t`, `cp -p`, `diff -b` all silently
1457
+
ignore user intent today. Either implement or reject.
1458
+
1459
+
6. **Build a shared `command/internal/locale` helper** (see
1460
+
cross-cutting #1) and route `wc`, `tr`, `expand`, `unexpand`,
1461
+
`fold`, `cut`, `nl`, `expr` through it.
1462
+
1463
+
7. **Build a `command/posixtest` shared harness** that, for any
1464
+
registered command accepting file operands, runs the
1465
+
`[--, -, multiple --]` matrix automatically. Catches
1466
+
end-of-options and stdin-`-` regressions across the whole
1467
+
coreutils set.
1468
+
1469
+
8. **Document the sandbox invariants explicitly** — the "always
1470
+
UTC" choice in `date.go:70-73` and the "1-hour cap" in
1471
+
`sleep.go:19` are real product decisions that future
1472
+
contributors will otherwise mistake for bugs.
1473
+
1474
+
9. **Add `docs/posix2018/tee.md`** — `tee` is in POSIX 2018
1475
+
but has no local spec doc.
1476
+
1477
+
10. **Consider exit-code semantics for `expr`** — verify
1478
+
`expr.go` returns code 1 (not 0) when the result is the
1479
+
string `"0"` or empty. The current logic looks right
1480
+
(`expr.go:57-59`) but lacks an explicit test.
1481
+
1482
+
---
1483
+
1484
+
## Appendix: methodology checklist
1485
+
1486
+
When adding a new command to `command/internal/`, the following
1487
+
checklist would prevent the recurrent issues found here:
1488
+
1489
+
- [ ] Read every section of the POSIX spec doc, especially
1490
+
RATIONALE (which calls out historical options POSIX
1491
+
*omitted*).
1492
+
- [ ] Implement every option in OPTIONS or document its absence
1493
+
in this file.
1494
+
- [ ] Do not add GNU options without a comment explaining
1495
+
why and a corresponding entry in the kefka-extensions
1496
+
doc.
1497
+
- [ ] Use locale-aware character/whitespace/collation helpers,
1498
+
not byte-level operations.
1499
+
- [ ] Surface the actual error (`%w` it through), not a
1500
+
hardcoded "No such file or directory".
1501
+
- [ ] Write a test for: zero operands, multiple operands, `-`
1502
+
stdin operand, `--` end-of-options, and the spec's
1503
+
EXIT STATUS section.
1504
+
- [ ] If a flag is accepted but not implemented, return an
1505
+
error rather than silently ignoring it.
+242
docs/posix2018/basename.md
+242
docs/posix2018/basename.md
···
1
+
#### []{#tag_20_07_01}NAME {#name .mansect}
2
+
3
+
> basename - return non-directory portion of a pathname
4
+
5
+
#### []{#tag_20_07_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `basename`` `*`string`*` `**`[`***`suffix`***`]`**
8
+
9
+
#### []{#tag_20_07_03}DESCRIPTION {#description .mansect}
10
+
11
+
> The *string* operand shall be treated as a pathname, as defined in XBD
12
+
> [*Pathname*](../basedefs/V1_chap03.html#tag_03_271). The string
13
+
> *string* shall be converted to the filename corresponding to the last
14
+
> pathname component in *string* and then the suffix string *suffix*, if
15
+
> present, shall be removed. This shall be done by performing actions
16
+
> equivalent to the following steps in order:
17
+
>
18
+
> 1. If *string* is a null string, it is unspecified whether the
19
+
> resulting string is `'.'` or a null string. In either case, skip
20
+
> steps 2 through 6.
21
+
>
22
+
> 2. If *string* is `"//"`, it is implementation-defined whether steps
23
+
> 3 to 6 are skipped or processed.
24
+
>
25
+
> 3. If *string* consists entirely of \<slash\> characters, *string*
26
+
> shall be set to a single \<slash\> character. In this case, skip
27
+
> steps 4 to 6.
28
+
>
29
+
> 4. If there are any trailing \<slash\> characters in *string*, they
30
+
> shall be removed.
31
+
>
32
+
> 5. If there are any \<slash\> characters remaining in *string*, the
33
+
> prefix of *string* up to and including the last \<slash\>
34
+
> character in *string* shall be removed.
35
+
>
36
+
> 6. If the *suffix* operand is present, is not identical to the
37
+
> characters remaining in *string*, and is identical to a suffix of
38
+
> the characters remaining in *string*, the suffix *suffix* shall be
39
+
> removed from *string*. Otherwise, *string* is not modified by this
40
+
> step. It shall not be considered an error if *suffix* is not found
41
+
> in *string*.
42
+
>
43
+
> The resulting string shall be written to standard output.
44
+
45
+
#### []{#tag_20_07_04}OPTIONS {#options .mansect}
46
+
47
+
> None.
48
+
49
+
#### []{#tag_20_07_05}OPERANDS {#operands .mansect}
50
+
51
+
> The following operands shall be supported:
52
+
>
53
+
> *string*
54
+
> : A string.
55
+
>
56
+
> *suffix*
57
+
> : A string.
58
+
59
+
#### []{#tag_20_07_06}STDIN {#stdin .mansect}
60
+
61
+
> Not used.
62
+
63
+
#### []{#tag_20_07_07}INPUT FILES {#input-files .mansect}
64
+
65
+
> None.
66
+
67
+
#### []{#tag_20_07_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
68
+
69
+
> The following environment variables shall affect the execution of
70
+
> *basename*:
71
+
>
72
+
> *LANG*
73
+
> : Provide a default value for the internationalization variables
74
+
> that are unset or null. (See XBD [*Internationalization
75
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
76
+
> precedence of internationalization variables used to determine the
77
+
> values of locale categories.)
78
+
>
79
+
> *LC_ALL*
80
+
> : If set to a non-empty string value, override the values of all the
81
+
> other internationalization variables.
82
+
>
83
+
> *LC_CTYPE*
84
+
> : Determine the locale for the interpretation of sequences of bytes
85
+
> of text data as characters (for example, single-byte as opposed to
86
+
> multi-byte characters in arguments).
87
+
>
88
+
> *LC_MESSAGES*
89
+
> : Determine the locale that should be used to affect the format and
90
+
> contents of diagnostic messages written to standard error.
91
+
>
92
+
> *NLSPATH*
93
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
94
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
95
+
> location of message catalogs for the processing of *LC_MESSAGES.*
96
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
97
+
98
+
#### []{#tag_20_07_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
99
+
100
+
> Default.
101
+
102
+
#### []{#tag_20_07_10}STDOUT {#stdout .mansect}
103
+
104
+
> The *basename* utility shall write a line to the standard output in
105
+
> the following format:
106
+
>
107
+
>
108
+
> "%s\n", <resulting string>
109
+
110
+
#### []{#tag_20_07_11}STDERR {#stderr .mansect}
111
+
112
+
> The standard error shall be used only for diagnostic messages.
113
+
114
+
#### []{#tag_20_07_12}OUTPUT FILES {#output-files .mansect}
115
+
116
+
> None.
117
+
118
+
#### []{#tag_20_07_13}EXTENDED DESCRIPTION {#extended-description .mansect}
119
+
120
+
> None.
121
+
122
+
#### []{#tag_20_07_14}EXIT STATUS {#exit-status .mansect}
123
+
124
+
> The following exit values shall be returned:
125
+
>
126
+
> 0
127
+
> : Successful completion.
128
+
>
129
+
> \>0
130
+
> : An error occurred.
131
+
132
+
#### []{#tag_20_07_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
133
+
134
+
> Default.
135
+
136
+
------------------------------------------------------------------------
137
+
138
+
::: box
139
+
*The following sections are informative.*
140
+
:::
141
+
142
+
#### []{#tag_20_07_16}APPLICATION USAGE {#application-usage .mansect}
143
+
144
+
> The definition of *pathname* specifies implementation-defined behavior
145
+
> for pathnames starting with two \<slash\> characters. Therefore,
146
+
> applications shall not arbitrarily add \<slash\> characters to the
147
+
> beginning of a pathname unless they can ensure that there are more or
148
+
> less than two or are prepared to deal with the implementation-defined
149
+
> consequences.
150
+
151
+
#### []{#tag_20_07_17}EXAMPLES {#examples .mansect}
152
+
153
+
> If the string *string* is a valid pathname:
154
+
>
155
+
>
156
+
> $(basename -- "string")
157
+
>
158
+
> produces a filename that could be used to open the file named by
159
+
> *string* in the directory returned by:
160
+
>
161
+
>
162
+
> $(dirname -- "string")
163
+
>
164
+
> If the string *string* is not a valid pathname, the same algorithm is
165
+
> used, but the result need not be a valid filename. The *basename*
166
+
> utility is not expected to make any judgements about the validity of
167
+
> *string* as a pathname; it just follows the specified algorithm to
168
+
> produce a result string.
169
+
>
170
+
> The following shell script compiles **/usr/src/cmd/cat.c** and moves
171
+
> the output to a file named **cat** in the current directory when
172
+
> invoked with the argument **/usr/src/cmd/cat** or with the argument
173
+
> **/usr/src/cmd/cat.c**:
174
+
>
175
+
>
176
+
> c99 -- "$(dirname -- "$1")/$(basename -- "$1" .c).c" &&
177
+
> mv a.out "$(basename -- "$1" .c)"
178
+
>
179
+
> The EXAMPLES section of the [*basename*()](../functions/basename.html)
180
+
> function (see XSH [*basename*](../functions/basename.html#tag_16_32))
181
+
> includes a table showing examples of the results of processing several
182
+
> sample pathnames by the [*basename*()](../functions/basename.html) and
183
+
> [*dirname*()](../functions/dirname.html) functions and by the
184
+
> *basename* and [*dirname*](../utilities/dirname.html) utilities.
185
+
186
+
#### []{#tag_20_07_18}RATIONALE {#rationale .mansect}
187
+
188
+
> The behaviors of *basename* and [*dirname*](../utilities/dirname.html)
189
+
> have been coordinated so that when *string* is a valid pathname:
190
+
>
191
+
>
192
+
> $(basename -- "string")
193
+
>
194
+
> would be a valid filename for the file in the directory:
195
+
>
196
+
>
197
+
> $(dirname -- "string")
198
+
>
199
+
> This would not work for the early proposal versions of these utilities
200
+
> due to the way it specified handling of trailing \<slash\> characters.
201
+
>
202
+
> Since the definition of *pathname* specifies implementation-defined
203
+
> behavior for pathnames starting with two \<slash\> characters, this
204
+
> volume of POSIX.1-2017 specifies similar implementation-defined
205
+
> behavior for the *basename* and [*dirname*](../utilities/dirname.html)
206
+
> utilities.
207
+
208
+
#### []{#tag_20_07_19}FUTURE DIRECTIONS {#future-directions .mansect}
209
+
210
+
> None.
211
+
212
+
#### []{#tag_20_07_20}SEE ALSO {#see-also .mansect}
213
+
214
+
> [*Parameters and Variables*](../utilities/V3_chap02.html#tag_18_05),
215
+
> [*dirname*](../utilities/dirname.html#tag_20_35)
216
+
>
217
+
> XBD [*Pathname*](../basedefs/V1_chap03.html#tag_03_271), [*Environment
218
+
> Variables*](../basedefs/V1_chap08.html#tag_08)
219
+
>
220
+
> XSH [*basename*](../functions/basename.html#tag_16_32),
221
+
> [*dirname*](../functions/dirname.html#tag_16_91)
222
+
223
+
#### []{#tag_20_07_21}CHANGE HISTORY {#change-history .mansect}
224
+
225
+
> First released in Issue 2.
226
+
227
+
#### []{#tag_20_07_22}Issue 6 {#issue-6 .mansect}
228
+
229
+
> IEEE PASC Interpretation 1003.2 #164 is applied.
230
+
>
231
+
> The normative text is reworded to avoid use of the term \"must\" for
232
+
> application requirements.
233
+
234
+
#### []{#tag_20_07_23}Issue 7 {#issue-7 .mansect}
235
+
236
+
> POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0065 \[192,538\],
237
+
> XCU/TC1-2008/0066 \[192,538\], and XCU/TC1-2008/0067 \[192,430,538\]
238
+
> are applied.
239
+
>
240
+
> POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0065 \[612\] is
241
+
> applied.
242
+
+180
docs/posix2018/cal.md
+180
docs/posix2018/cal.md
···
1
+
#### []{#tag_20_12_01}NAME {#name .mansect}
2
+
3
+
> cal - print a calendar
4
+
5
+
#### []{#tag_20_12_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> ::: box
8
+
> ^`[`[`XSI`](javascript:open_code('XSI'))`]`^` `![`[Option Start]`](../images/opt-start.gif){border="0"}` cal`` `**`[[`***`month`***`]`**` `*`year`***`]`**![`[Option End]`](../images/opt-end.gif){border="0"}
9
+
> :::
10
+
11
+
#### []{#tag_20_12_03}DESCRIPTION {#description .mansect}
12
+
13
+
> The *cal* utility shall write a calendar to standard output using the
14
+
> Julian calendar for dates from January 1, 1 through September 2, 1752
15
+
> and the Gregorian calendar for dates from September 14, 1752 through
16
+
> December 31, 9999 as though the Gregorian calendar had been adopted on
17
+
> September 14, 1752.
18
+
>
19
+
> If no operands are given, *cal* shall produce a one-month calendar for
20
+
> the current month in the current year. If only the *year* operand is
21
+
> given, *cal* shall produce a calendar for all twelve months in the
22
+
> given calendar year. If both *month* and *year* operands are given,
23
+
> *cal* shall produce a one-month calendar for the given month in the
24
+
> given year.
25
+
26
+
#### []{#tag_20_12_04}OPTIONS {#options .mansect}
27
+
28
+
> None.
29
+
30
+
#### []{#tag_20_12_05}OPERANDS {#operands .mansect}
31
+
32
+
> The following operands shall be supported:
33
+
>
34
+
> *month*
35
+
> : Specify the month to be displayed, represented as a decimal
36
+
> integer from 1 (January) to 12 (December).
37
+
>
38
+
> *year*
39
+
> : Specify the year for which the calendar is displayed, represented
40
+
> as a decimal integer from 1 to 9999.
41
+
42
+
#### []{#tag_20_12_06}STDIN {#stdin .mansect}
43
+
44
+
> Not used.
45
+
46
+
#### []{#tag_20_12_07}INPUT FILES {#input-files .mansect}
47
+
48
+
> None.
49
+
50
+
#### []{#tag_20_12_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
51
+
52
+
> The following environment variables shall affect the execution of
53
+
> *cal*:
54
+
>
55
+
> *LANG*
56
+
> : Provide a default value for the internationalization variables
57
+
> that are unset or null. (See XBD [*Internationalization
58
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
59
+
> precedence of internationalization variables used to determine the
60
+
> values of locale categories.)
61
+
>
62
+
> *LC_ALL*
63
+
> : If set to a non-empty string value, override the values of all the
64
+
> other internationalization variables.
65
+
>
66
+
> *LC_CTYPE*
67
+
> : Determine the locale for the interpretation of sequences of bytes
68
+
> of text data as characters (for example, single-byte as opposed to
69
+
> multi-byte characters in arguments).
70
+
>
71
+
> *LC_MESSAGES*
72
+
> : Determine the locale that should be used to affect the format and
73
+
> contents of diagnostic messages written to standard error, and
74
+
> informative messages written to standard output.
75
+
>
76
+
> *LC_TIME*
77
+
> : Determine the format and contents of the calendar.
78
+
>
79
+
> *NLSPATH*
80
+
> : Determine the location of message catalogs for the processing of
81
+
> *LC_MESSAGES.*
82
+
>
83
+
> *TZ*
84
+
> : Determine the timezone used to calculate the value of the current
85
+
> month.
86
+
87
+
#### []{#tag_20_12_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
88
+
89
+
> Default.
90
+
91
+
#### []{#tag_20_12_10}STDOUT {#stdout .mansect}
92
+
93
+
> The standard output shall be used to display the calendar, in an
94
+
> unspecified format.
95
+
96
+
#### []{#tag_20_12_11}STDERR {#stderr .mansect}
97
+
98
+
> The standard error shall be used only for diagnostic messages.
99
+
100
+
#### []{#tag_20_12_12}OUTPUT FILES {#output-files .mansect}
101
+
102
+
> None.
103
+
104
+
#### []{#tag_20_12_13}EXTENDED DESCRIPTION {#extended-description .mansect}
105
+
106
+
> None.
107
+
108
+
#### []{#tag_20_12_14}EXIT STATUS {#exit-status .mansect}
109
+
110
+
> The following exit values shall be returned:
111
+
>
112
+
> 0
113
+
> : Successful completion.
114
+
>
115
+
> \>0
116
+
> : An error occurred.
117
+
118
+
#### []{#tag_20_12_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
119
+
120
+
> Default.
121
+
122
+
------------------------------------------------------------------------
123
+
124
+
::: box
125
+
*The following sections are informative.*
126
+
:::
127
+
128
+
#### []{#tag_20_12_16}APPLICATION USAGE {#application-usage .mansect}
129
+
130
+
> Note that:
131
+
>
132
+
>
133
+
> cal 83
134
+
>
135
+
> refers to A.D. 83, not 1983.
136
+
137
+
#### []{#tag_20_12_17}EXAMPLES {#examples .mansect}
138
+
139
+
> None.
140
+
141
+
#### []{#tag_20_12_18}RATIONALE {#rationale .mansect}
142
+
143
+
> Earlier versions of this standard incorrectly required that the
144
+
> command:
145
+
>
146
+
>
147
+
> cal 2000
148
+
>
149
+
> write a one-month calendar for the current calendar month (no matter
150
+
> what the current year is) in the year 2000 to standard output. This
151
+
> did not match historic practice in any known version of the *cal*
152
+
> utility. The description has been updated to match historic practice.
153
+
> When only the *year* operand is given, *cal* writes a twelve-month
154
+
> calendar for the specified year.
155
+
156
+
#### []{#tag_20_12_19}FUTURE DIRECTIONS {#future-directions .mansect}
157
+
158
+
> A future version of this standard may support locale-specific
159
+
> recognition of the date of adoption of the Gregorian calendar.
160
+
161
+
#### []{#tag_20_12_20}SEE ALSO {#see-also .mansect}
162
+
163
+
> XBD [*Environment Variables*](../basedefs/V1_chap08.html#tag_08)
164
+
165
+
#### []{#tag_20_12_21}CHANGE HISTORY {#change-history .mansect}
166
+
167
+
> First released in Issue 2.
168
+
169
+
#### []{#tag_20_12_22}Issue 6 {#issue-6 .mansect}
170
+
171
+
> The DESCRIPTION is updated to allow for traditional behavior for years
172
+
> before the adoption of the Gregorian calendar.
173
+
174
+
#### []{#tag_20_12_23}Issue 7 {#issue-7 .mansect}
175
+
176
+
> SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.
177
+
>
178
+
> POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0074 \[56\] and
179
+
> XCU/TC1-2008/0075 \[56\] are applied.
180
+
+269
docs/posix2018/cat.md
+269
docs/posix2018/cat.md
···
1
+
#### []{#tag_20_13_01}NAME {#name .mansect}
2
+
3
+
> cat - concatenate and print files
4
+
5
+
#### []{#tag_20_13_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `cat`` `**`[`**`-u`**`] [`***`file`*`...`**`]`**
8
+
9
+
#### []{#tag_20_13_03}DESCRIPTION {#description .mansect}
10
+
11
+
> The *cat* utility shall read files in sequence and shall write their
12
+
> contents to the standard output in the same sequence.
13
+
14
+
#### []{#tag_20_13_04}OPTIONS {#options .mansect}
15
+
16
+
> The *cat* utility shall conform to XBD [*Utility Syntax
17
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02) .
18
+
>
19
+
> The following option shall be supported:
20
+
>
21
+
> **-u**
22
+
> : Write bytes from the input file to the standard output without
23
+
> delay as each is read.
24
+
25
+
#### []{#tag_20_13_05}OPERANDS {#operands .mansect}
26
+
27
+
> The following operand shall be supported:
28
+
>
29
+
> *file*
30
+
> : A pathname of an input file. If no *file* operands are specified,
31
+
> the standard input shall be used. If a *file* is `'-'`, the *cat*
32
+
> utility shall read from the standard input at that point in the
33
+
> sequence. The *cat* utility shall not close and reopen standard
34
+
> input when it is referenced in this way, but shall accept multiple
35
+
> occurrences of `'-'` as a *file* operand.
36
+
37
+
#### []{#tag_20_13_06}STDIN {#stdin .mansect}
38
+
39
+
> The standard input shall be used only if no *file* operands are
40
+
> specified, or if a *file* operand is `'-'`. See the INPUT FILES
41
+
> section.
42
+
43
+
#### []{#tag_20_13_07}INPUT FILES {#input-files .mansect}
44
+
45
+
> The input files can be any file type.
46
+
47
+
#### []{#tag_20_13_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
48
+
49
+
> The following environment variables shall affect the execution of
50
+
> *cat*:
51
+
>
52
+
> *LANG*
53
+
> : Provide a default value for the internationalization variables
54
+
> that are unset or null. (See XBD [*Internationalization
55
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
56
+
> precedence of internationalization variables used to determine the
57
+
> values of locale categories.)
58
+
>
59
+
> *LC_ALL*
60
+
> : If set to a non-empty string value, override the values of all the
61
+
> other internationalization variables.
62
+
>
63
+
> *LC_CTYPE*
64
+
> : Determine the locale for the interpretation of sequences of bytes
65
+
> of text data as characters (for example, single-byte as opposed to
66
+
> multi-byte characters in arguments).
67
+
>
68
+
> *LC_MESSAGES*
69
+
> : Determine the locale that should be used to affect the format and
70
+
> contents of diagnostic messages written to standard error.
71
+
>
72
+
> *NLSPATH*
73
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
74
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
75
+
> location of message catalogs for the processing of *LC_MESSAGES.*
76
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
77
+
78
+
#### []{#tag_20_13_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
79
+
80
+
> Default.
81
+
82
+
#### []{#tag_20_13_10}STDOUT {#stdout .mansect}
83
+
84
+
> The standard output shall contain the sequence of bytes read from the
85
+
> input files. Nothing else shall be written to the standard output. If
86
+
> the standard output is a regular file, and is the same file as any of
87
+
> the input file operands, the implementation may treat this as an
88
+
> error.
89
+
90
+
#### []{#tag_20_13_11}STDERR {#stderr .mansect}
91
+
92
+
> The standard error shall be used only for diagnostic messages.
93
+
94
+
#### []{#tag_20_13_12}OUTPUT FILES {#output-files .mansect}
95
+
96
+
> None.
97
+
98
+
#### []{#tag_20_13_13}EXTENDED DESCRIPTION {#extended-description .mansect}
99
+
100
+
> None.
101
+
102
+
#### []{#tag_20_13_14}EXIT STATUS {#exit-status .mansect}
103
+
104
+
> The following exit values shall be returned:
105
+
>
106
+
> 0
107
+
> : All input files were output successfully.
108
+
>
109
+
> \>0
110
+
> : An error occurred.
111
+
112
+
#### []{#tag_20_13_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
113
+
114
+
> Default.
115
+
116
+
------------------------------------------------------------------------
117
+
118
+
::: box
119
+
*The following sections are informative.*
120
+
:::
121
+
122
+
#### []{#tag_20_13_16}APPLICATION USAGE {#application-usage .mansect}
123
+
124
+
> The **-u** option has value in prototyping non-blocking reads from
125
+
> FIFOs. The intent is to support the following sequence:
126
+
>
127
+
>
128
+
> mkfifo foo
129
+
> cat -u foo > /dev/tty13 &
130
+
> cat -u > foo
131
+
>
132
+
> It is unspecified whether standard output is or is not buffered in the
133
+
> default case. This is sometimes of interest when standard output is
134
+
> associated with a terminal, since buffering may delay the output. The
135
+
> presence of the **-u** option guarantees that unbuffered I/O is
136
+
> available. It is implementation-defined whether the *cat* utility
137
+
> buffers output if the **-u** option is not specified. Traditionally,
138
+
> the **-u** option is implemented using the equivalent of the
139
+
> [*setvbuf*()](../functions/setvbuf.html) function defined in the
140
+
> System Interfaces volume of POSIX.1-2017.
141
+
142
+
#### []{#tag_20_13_17}EXAMPLES {#examples .mansect}
143
+
144
+
> The following command:
145
+
>
146
+
>
147
+
> cat myfile
148
+
>
149
+
> writes the contents of the file **myfile** to standard output.
150
+
>
151
+
> The following command:
152
+
>
153
+
>
154
+
> cat doc1 doc2 > doc.all
155
+
>
156
+
> concatenates the files **doc1** and **doc2** and writes the result to
157
+
> **doc.all**.
158
+
>
159
+
> Because of the shell language mechanism used to perform output
160
+
> redirection, a command such as this:
161
+
>
162
+
>
163
+
> cat doc doc.end > doc
164
+
>
165
+
> causes the original data in **doc** to be lost before *cat* even
166
+
> begins execution. This is true whether the *cat* command fails with an
167
+
> error or silently succeeds (the specification allows both behaviors).
168
+
> In order to append the contents of **doc.end** without losing the
169
+
> original contents of **doc**, this command should be used instead:
170
+
>
171
+
>
172
+
> cat doc.end >> doc
173
+
>
174
+
> The command:
175
+
>
176
+
>
177
+
> cat start - middle - end > file
178
+
>
179
+
> when standard input is a terminal, gets two arbitrary pieces of input
180
+
> from the terminal with a single invocation of *cat*. Note, however,
181
+
> that if standard input is a regular file, this would be equivalent to
182
+
> the command:
183
+
>
184
+
>
185
+
> cat start - middle /dev/null end > file
186
+
>
187
+
> because the entire contents of the file would be consumed by *cat* the
188
+
> first time `'-'` was used as a *file* operand and an end-of-file
189
+
> condition would be detected immediately when `'-'` was referenced the
190
+
> second time.
191
+
192
+
#### []{#tag_20_13_18}RATIONALE {#rationale .mansect}
193
+
194
+
> Historical versions of the *cat* utility include the **-e**, **-t**,
195
+
> and **-v**, options which permit the ends of lines, \<tab\>
196
+
> characters, and invisible characters, respectively, to be rendered
197
+
> visible in the output. The standard developers omitted these options
198
+
> because they provide too fine a degree of control over what is made
199
+
> visible, and similar output can be obtained using a command such as:
200
+
>
201
+
>
202
+
> sed -n l pathname
203
+
>
204
+
> The latter also has the advantage that its output is unambiguous,
205
+
> whereas the output of historical *cat* **-etv** is not.
206
+
>
207
+
> The **-s** option was omitted because it corresponds to different
208
+
> functions in BSD and System V-based systems. The BSD **-s** option to
209
+
> squeeze blank lines can be accomplished by the shell script shown in
210
+
> the following example:
211
+
>
212
+
>
213
+
> sed -n '
214
+
> # Write non-empty lines.
215
+
> /./ {
216
+
> p
217
+
> d
218
+
> }
219
+
> # Write a single empty line, then look for more empty lines.
220
+
> /^$/ p
221
+
> # Get next line, discard the held <newline> (empty line),
222
+
> # and look for more empty lines.
223
+
> :Empty
224
+
> /^$/ {
225
+
> N
226
+
> s/.//
227
+
> b Empty
228
+
> }
229
+
> # Write the non-empty line before going back to search
230
+
> # for the first in a set of empty lines.
231
+
> p
232
+
> '
233
+
>
234
+
> The System V **-s** option to silence error messages can be
235
+
> accomplished by redirecting the standard error. Note that the BSD
236
+
> documentation for *cat* uses the term \"blank line\" to mean the same
237
+
> as the POSIX \"empty line\'\': a line consisting only of a
238
+
> \<newline\>.
239
+
>
240
+
> The BSD **-n** option was omitted because similar functionality can be
241
+
> obtained from the **-n** option of the [*pr*](../utilities/pr.html)
242
+
> utility.
243
+
244
+
#### []{#tag_20_13_19}FUTURE DIRECTIONS {#future-directions .mansect}
245
+
246
+
> None.
247
+
248
+
#### []{#tag_20_13_20}SEE ALSO {#see-also .mansect}
249
+
250
+
> [*more*](../utilities/more.html#)
251
+
>
252
+
> XBD [*Environment Variables*](../basedefs/V1_chap08.html#tag_08),
253
+
> [*Utility Syntax Guidelines*](../basedefs/V1_chap12.html#tag_12_02)
254
+
>
255
+
> XSH [*setvbuf*](../functions/setvbuf.html#)
256
+
257
+
#### []{#tag_20_13_21}CHANGE HISTORY {#change-history .mansect}
258
+
259
+
> First released in Issue 2.
260
+
261
+
#### []{#tag_20_13_22}Issue 7 {#issue-7 .mansect}
262
+
263
+
> SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.
264
+
>
265
+
> SD5-XCU-ERN-174 is applied, changing the RATIONALE.
266
+
>
267
+
> POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0073 \[876\] is
268
+
> applied.
269
+
+507
docs/posix2018/chmod.md
+507
docs/posix2018/chmod.md
···
1
+
#### []{#tag_20_17_01}NAME {#name .mansect}
2
+
3
+
> chmod - change the file modes
4
+
5
+
#### []{#tag_20_17_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `chmod`` `**`[`**`-R`**`]`**` `*`mode file`*`...`
8
+
9
+
#### []{#tag_20_17_03}DESCRIPTION {#description .mansect}
10
+
11
+
> The *chmod* utility shall change any or all of the file mode bits of
12
+
> the file named by each *file* operand in the way specified by the
13
+
> *mode* operand.
14
+
>
15
+
> It is implementation-defined whether and how the *chmod* utility
16
+
> affects any alternate or additional file access control mechanism (see
17
+
> XBD [*File Access Permissions*](../basedefs/V1_chap04.html#tag_04_05))
18
+
> being used for the specified file.
19
+
>
20
+
> Only a process whose effective user ID matches the user ID of the
21
+
> file, or a process with appropriate privileges, shall be permitted to
22
+
> change the file mode bits of a file.
23
+
>
24
+
> Upon successfully changing the file mode bits of a file, the *chmod*
25
+
> utility shall mark for update the last file status change timestamp of
26
+
> the file.
27
+
28
+
#### []{#tag_20_17_04}OPTIONS {#options .mansect}
29
+
30
+
> The *chmod* utility shall conform to XBD [*Utility Syntax
31
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02).
32
+
>
33
+
> The following option shall be supported:
34
+
>
35
+
> **-R**
36
+
> : Recursively change file mode bits. For each *file* operand that
37
+
> names a directory, *chmod* shall change the file mode bits of the
38
+
> directory and all files in the file hierarchy below it.
39
+
40
+
#### []{#tag_20_17_05}OPERANDS {#operands .mansect}
41
+
42
+
> The following operands shall be supported:
43
+
>
44
+
> *mode*
45
+
> : Represents the change to be made to the file mode bits of each
46
+
> file named by one of the *file* operands; see the EXTENDED
47
+
> DESCRIPTION section.
48
+
>
49
+
> *file*
50
+
> : A pathname of a file whose file mode bits shall be modified.
51
+
52
+
#### []{#tag_20_17_06}STDIN {#stdin .mansect}
53
+
54
+
> Not used.
55
+
56
+
#### []{#tag_20_17_07}INPUT FILES {#input-files .mansect}
57
+
58
+
> None.
59
+
60
+
#### []{#tag_20_17_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
61
+
62
+
> The following environment variables shall affect the execution of
63
+
> *chmod*:
64
+
>
65
+
> *LANG*
66
+
> : Provide a default value for the internationalization variables
67
+
> that are unset or null. (See XBD [*Internationalization
68
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
69
+
> precedence of internationalization variables used to determine the
70
+
> values of locale categories.)
71
+
>
72
+
> *LC_ALL*
73
+
> : If set to a non-empty string value, override the values of all the
74
+
> other internationalization variables.
75
+
>
76
+
> *LC_CTYPE*
77
+
> : Determine the locale for the interpretation of sequences of bytes
78
+
> of text data as characters (for example, single-byte as opposed to
79
+
> multi-byte characters in arguments).
80
+
>
81
+
> *LC_MESSAGES*
82
+
> : Determine the locale that should be used to affect the format and
83
+
> contents of diagnostic messages written to standard error.
84
+
>
85
+
> *NLSPATH*
86
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
87
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
88
+
> location of message catalogs for the processing of *LC_MESSAGES.*
89
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
90
+
91
+
#### []{#tag_20_17_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
92
+
93
+
> Default.
94
+
95
+
#### []{#tag_20_17_10}STDOUT {#stdout .mansect}
96
+
97
+
> Not used.
98
+
99
+
#### []{#tag_20_17_11}STDERR {#stderr .mansect}
100
+
101
+
> The standard error shall be used only for diagnostic messages.
102
+
103
+
#### []{#tag_20_17_12}OUTPUT FILES {#output-files .mansect}
104
+
105
+
> None.
106
+
107
+
#### []{#tag_20_17_13}EXTENDED DESCRIPTION {#extended-description .mansect}
108
+
109
+
> The *mode* operand shall be either a *symbolic_mode* expression or a
110
+
> non-negative octal integer. The *symbolic_mode* form is described by
111
+
> the grammar later in this section.
112
+
>
113
+
> Each **clause** shall specify an operation to be performed on the
114
+
> current file mode bits of each *file*. The operations shall be
115
+
> performed on each *file* in the order in which the **clause**s are
116
+
> specified.
117
+
>
118
+
> The **who** symbols **u**, **g**, and **o** shall specify the *user*,
119
+
> *group*, and *other* parts of the file mode bits, respectively. A
120
+
> **who** consisting of the symbol **a** shall be equivalent to **ugo**.
121
+
>
122
+
> The **perm** symbols **r**, **w**, and **x** represent the *read*,
123
+
> *write*, and *execute*/ *search* portions of file mode bits,
124
+
> respectively. The **perm** symbol **s** shall represent the
125
+
> *set-user-ID-on-execution* (when **who** contains or implies **u**)
126
+
> and *set-group-ID-on-execution* (when **who** contains or implies
127
+
> **g**) bits.
128
+
>
129
+
> The **perm** symbol **X** shall represent the execute/search portion
130
+
> of the file mode bits if the file is a directory or if the current
131
+
> (unmodified) file mode bits have at least one of the execute bits
132
+
> (S_IXUSR, S_IXGRP, or S_IXOTH) set. It shall be ignored if the file is
133
+
> not a directory and none of the execute bits are set in the current
134
+
> file mode bits.
135
+
>
136
+
> The **permcopy** symbols **u**, **g**, and **o** shall represent the
137
+
> current permissions associated with the user, group, and other parts
138
+
> of the file mode bits, respectively. For the remainder of this
139
+
> section, **perm** refers to the non-terminals **perm** and
140
+
> **permcopy** in the grammar.
141
+
>
142
+
> If multiple **actionlist**s are grouped with a single **wholist** in
143
+
> the grammar, each **actionlist** shall be applied in the order
144
+
> specified with that **wholist**. The *op* symbols shall represent the
145
+
> operation performed, as follows:
146
+
>
147
+
> `+`
148
+
>
149
+
> : If **perm** is not specified, the `'+'` operation shall not change
150
+
> the file mode bits.
151
+
>
152
+
> If **who** is not specified, the file mode bits represented by
153
+
> **perm** for the owner, group, and other permissions, except for
154
+
> those with corresponding bits in the file mode creation mask of
155
+
> the invoking process, shall be set.
156
+
>
157
+
> Otherwise, the file mode bits represented by the specified **who**
158
+
> and **perm** values shall be set.
159
+
>
160
+
> `-`
161
+
>
162
+
> : If **perm** is not specified, the `'-'` operation shall not change
163
+
> the file mode bits.
164
+
>
165
+
> If **who** is not specified, the file mode bits represented by
166
+
> **perm** for the owner, group, and other permissions, except for
167
+
> those with corresponding bits in the file mode creation mask of
168
+
> the invoking process, shall be cleared.
169
+
>
170
+
> Otherwise, the file mode bits represented by the specified **who**
171
+
> and **perm** values shall be cleared.
172
+
>
173
+
> `=`
174
+
>
175
+
> : Clear the file mode bits specified by the **who** value, or, if no
176
+
> **who** value is specified, all of the file mode bits specified in
177
+
> this volume of POSIX.1-2017.
178
+
>
179
+
> If **perm** is not specified, the `'='` operation shall make no
180
+
> further modifications to the file mode bits.
181
+
>
182
+
> If **who** is not specified, the file mode bits represented by
183
+
> **perm** for the owner, group, and other permissions, except for
184
+
> those with corresponding bits in the file mode creation mask of
185
+
> the invoking process, shall be set.
186
+
>
187
+
> Otherwise, the file mode bits represented by the specified **who**
188
+
> and **perm** values shall be set.
189
+
>
190
+
> When using the symbolic mode form on a regular file, it is
191
+
> implementation-defined whether or not:
192
+
>
193
+
> - Requests to set the set-user-ID-on-execution or
194
+
> set-group-ID-on-execution bit when all execute bits are currently
195
+
> clear and none are being set are ignored.
196
+
>
197
+
> - Requests to clear all execute bits also clear the
198
+
> set-user-ID-on-execution and set-group-ID-on-execution bits.
199
+
>
200
+
> - Requests to clear the set-user-ID-on-execution or
201
+
> set-group-ID-on-execution bits when all execute bits are currently
202
+
> clear are ignored. However, if the command
203
+
> [*ls*](../utilities/ls.html) **-l** *file* writes an *s* in the
204
+
> position indicating that the set-user-ID-on-execution or
205
+
> set-group-ID-on-execution is set, the commands *chmod* **u-s**
206
+
> *file* or *chmod* **g-s** *file*, respectively, shall not be
207
+
> ignored.
208
+
>
209
+
> When using the symbolic mode form on other file types, it is
210
+
> implementation-defined whether or not requests to set or clear the
211
+
> set-user-ID-on-execution or set-group-ID-on-execution bits are
212
+
> honored.
213
+
>
214
+
> If the **who** symbol **o** is used in conjunction with the **perm**
215
+
> symbol **s** with no other **who** symbols being specified, the
216
+
> set-user-ID-on-execution and set-group-ID-on-execution bits shall not
217
+
> be modified. It shall not be an error to specify the **who** symbol
218
+
> **o** in conjunction with the **perm** symbol **s**.
219
+
>
220
+
> ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
221
+
> Start\]](../images/opt-start.gif){border="0"} The **perm** symbol
222
+
> **t** shall specify the S_ISVTX bit. When used with a file of type
223
+
> directory, it can be used with the **who** symbol **a**, or with no
224
+
> **who** symbol. It shall not be an error to specify a **who** symbol
225
+
> of **u**, **g**, or **o** in conjunction with the **perm** symbol
226
+
> **t**, but the meaning of these combinations is unspecified. The
227
+
> effect when using the **perm** symbol **t** with any file type other
228
+
> than directory is unspecified. ![\[Option
229
+
> End\]](../images/opt-end.gif){border="0"}
230
+
>
231
+
> For an octal integer *mode* operand, the file mode bits shall be set
232
+
> absolutely.
233
+
>
234
+
> For each bit set in the octal number, the corresponding file
235
+
> permission bit shown in the following table shall be set; all other
236
+
> file permission bits shall be cleared. For regular files, for each bit
237
+
> set in the octal number corresponding to the set-user-ID-on-execution
238
+
> or the set-group-ID-on-execution, bits shown in the following table
239
+
> shall be set; if these bits are not set in the octal number, they are
240
+
> cleared. For other file types, it is implementation-defined whether or
241
+
> not requests to set or clear the set-user-ID-on-execution or
242
+
> set-group-ID-on-execution bits are honored.
243
+
>
244
+
> **Octal** **Mode Bit** **Octal** **Mode Bit** **Octal** **Mode Bit** **Octal** **Mode Bit**
245
+
> -------------------------------------------------- ----------------------------------------------- ----------- -------------- ----------- -------------- ----------- --------------
246
+
> **4000** S_ISUID **0400** S_IRUSR **0040** S_IRGRP **0004** S_IROTH
247
+
> **2000** S_ISGID **0200** S_IWUSR **0020** S_IWGRP **0002** S_IWOTH
248
+
> **{border="0"}1000** S_ISVTX{border="0"} **0100** S_IXUSR **0010** S_IXGRP **0001** S_IXOTH
249
+
>
250
+
> When bits are set in the octal number other than those listed in the
251
+
> table above, the behavior is unspecified.
252
+
>
253
+
> ##### []{#tag_20_17_13_01}Grammar for chmod
254
+
>
255
+
> The grammar and lexical conventions in this section describe the
256
+
> syntax for the *symbolic_mode* operand. The general conventions for
257
+
> this style of grammar are described in [*Grammar
258
+
> Conventions*](../utilities/V3_chap01.html#tag_17_03). A valid
259
+
> *symbolic_mode* can be represented as the non-terminal symbol
260
+
> *symbolic_mode* in the grammar. This formal syntax shall take
261
+
> precedence over the preceding text syntax description.
262
+
>
263
+
> The lexical processing is based entirely on single characters.
264
+
> Implementations need not allow \<blank\> characters within the single
265
+
> argument being processed.
266
+
>
267
+
>
268
+
> %start symbolic_mode
269
+
> %%
270
+
>
271
+
>
272
+
> symbolic_mode : clause
273
+
> | symbolic_mode ',' clause
274
+
> ;
275
+
>
276
+
>
277
+
> clause : actionlist
278
+
> | wholist actionlist
279
+
> ;
280
+
>
281
+
>
282
+
> wholist : who
283
+
> | wholist who
284
+
> ;
285
+
>
286
+
>
287
+
> who : 'u' | 'g' | 'o' | 'a'
288
+
> ;
289
+
>
290
+
>
291
+
> actionlist : action
292
+
> | actionlist action
293
+
> ;
294
+
>
295
+
>
296
+
> action : op
297
+
> | op permlist
298
+
> | op permcopy
299
+
> ;
300
+
>
301
+
>
302
+
> permcopy : 'u' | 'g' | 'o'
303
+
> ;
304
+
>
305
+
>
306
+
> op : '+' | '-' | '='
307
+
> ;
308
+
>
309
+
>
310
+
> permlist : perm
311
+
> | perm permlist
312
+
> ;
313
+
>
314
+
>
315
+
> [XSI]
316
+
> perm : 'r' | 'w' | 'x' | 'X' | 's' | 't'
317
+
> ;
318
+
319
+
#### []{#tag_20_17_14}EXIT STATUS {#exit-status .mansect}
320
+
321
+
> The following exit values shall be returned:
322
+
>
323
+
> 0
324
+
> : The utility executed successfully and all requested changes were
325
+
> made.
326
+
>
327
+
> \>0
328
+
> : An error occurred.
329
+
330
+
#### []{#tag_20_17_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
331
+
332
+
> Default.
333
+
334
+
------------------------------------------------------------------------
335
+
336
+
::: box
337
+
*The following sections are informative.*
338
+
:::
339
+
340
+
#### []{#tag_20_17_16}APPLICATION USAGE {#application-usage .mansect}
341
+
342
+
> Some implementations of the *chmod* utility change the mode of a
343
+
> directory before the files in the directory when performing a
344
+
> recursive (**-R** option) change; others change the directory mode
345
+
> after the files in the directory. If an application tries to remove
346
+
> read or search permission for a file hierarchy, the removal attempt
347
+
> fails if the directory is changed first; on the other hand, trying to
348
+
> re-enable permissions to a restricted hierarchy fails if directories
349
+
> are changed last. Users should not try to make a hierarchy
350
+
> inaccessible to themselves.
351
+
>
352
+
> Some implementations of *chmod* never used the
353
+
> [*umask*](../utilities/umask.html) of the process when changing modes;
354
+
> systems conformant with this volume of POSIX.1-2017 do so when **who**
355
+
> is not specified. Note the difference between:
356
+
>
357
+
>
358
+
> chmod a-w file
359
+
>
360
+
> which removes all write permissions, and:
361
+
>
362
+
>
363
+
> chmod -- -w file
364
+
>
365
+
> which removes write permissions that would be allowed if **file** was
366
+
> created with the same [*umask*](../utilities/umask.html).
367
+
>
368
+
> Conforming applications should never assume that they know how the
369
+
> set-user-ID and set-group-ID bits on directories are interpreted.
370
+
371
+
#### []{#tag_20_17_17}EXAMPLES {#examples .mansect}
372
+
373
+
>
374
+
> **Mode** **Results**
375
+
> ------------- -------------------------------------------------------------------------------------------------------
376
+
> *a*+= Equivalent to *a*+, *a*=; clears all file mode bits.
377
+
> *go*+-w Equivalent to *go*+, *go*- *w*; clears group and other write bits.
378
+
> *g*=*o*-*w* Equivalent to *g*= *o*, *g*- *w*; sets group bit to match other bits and then clears group write bit.
379
+
> *g*-*r*+*w* Equivalent to *g*- *r*, *g*+ *w*; clears group read bit and sets group write bit.
380
+
> *uo*=*g* Sets owner bits to match group bits and sets other bits to match group bits.
381
+
382
+
#### []{#tag_20_17_18}RATIONALE {#rationale .mansect}
383
+
384
+
> The functionality of *chmod* is described substantially through
385
+
> references to concepts defined in the System Interfaces volume of
386
+
> POSIX.1-2017. In this way, there is less duplication of effort
387
+
> required for describing the interactions of permissions. However, the
388
+
> behavior of this utility is not described in terms of the
389
+
> [*chmod*()](../functions/chmod.html) function from the System
390
+
> Interfaces volume of POSIX.1-2017 because that specification requires
391
+
> certain side-effects upon alternate file access control mechanisms
392
+
> that might not be appropriate, depending on the implementation.
393
+
>
394
+
> Implementations that support mandatory file and record locking as
395
+
> specified by the 1984 /usr/group standard historically used the
396
+
> combination of set-group-ID bit set and group execute bit clear to
397
+
> indicate mandatory locking. This condition is usually set or cleared
398
+
> with the symbolic mode **perm** symbol **l** instead of the **perm**
399
+
> symbols **s** and **x** so that the mandatory locking mode is not
400
+
> changed without explicit indication that that was what the user
401
+
> intended. Therefore, the details on how the implementation treats
402
+
> these conditions must be defined in the documentation. This volume of
403
+
> POSIX.1-2017 does not require mandatory locking (nor does the System
404
+
> Interfaces volume of POSIX.1-2017), but does allow it as an extension.
405
+
> However, this volume of POSIX.1-2017 does require that the
406
+
> [*ls*](../utilities/ls.html) and *chmod* utilities work consistently
407
+
> in this area. If [*ls*](../utilities/ls.html) **-l** *file* indicates
408
+
> that the set-group-ID bit is set, *chmod* **g-s** *file* must clear it
409
+
> (assuming appropriate privileges exist to change modes).
410
+
>
411
+
> The System V and BSD versions use different exit status codes. Some
412
+
> implementations used the exit status as a count of the number of
413
+
> errors that occurred; this practice is unworkable since it can
414
+
> overflow the range of valid exit status values. This problem is
415
+
> avoided here by specifying only 0 and \>0 as exit values.
416
+
>
417
+
> The System Interfaces volume of POSIX.1-2017 indicates that
418
+
> implementation-defined restrictions may cause the S_ISUID and S_ISGID
419
+
> bits to be ignored. This volume of POSIX.1-2017 allows the *chmod*
420
+
> utility to choose to modify these bits before calling
421
+
> [*chmod*()](../functions/chmod.html) (or some function providing
422
+
> equivalent capabilities) for non-regular files. Among other things,
423
+
> this allows implementations that use the set-user-ID and set-group-ID
424
+
> bits on directories to enable extended features to handle these
425
+
> extensions in an intelligent manner.
426
+
>
427
+
> The **X** **perm** symbol was adopted from BSD-based systems because
428
+
> it provides commonly desired functionality when doing recursive
429
+
> (**-R** option) modifications. Similar functionality is not provided
430
+
> by the [*find*](../utilities/find.html) utility. Historical BSD
431
+
> versions of *chmod*, however, only supported **X** with *op*+; it has
432
+
> been extended in this volume of POSIX.1-2017 because it is also useful
433
+
> with *op*=. (It has also been added for *op*- even though it
434
+
> duplicates **x**, in this case, because it is intuitive and easier to
435
+
> explain.)
436
+
>
437
+
> The grammar was extended with the *permcopy* non-terminal to allow
438
+
> historical-practice forms of symbolic modes like **o**= **u** **-g**
439
+
> (that is, set the \"other\" permissions to the permissions of
440
+
> \"owner\" minus the permissions of \"group\").
441
+
442
+
#### []{#tag_20_17_19}FUTURE DIRECTIONS {#future-directions .mansect}
443
+
444
+
> None.
445
+
446
+
#### []{#tag_20_17_20}SEE ALSO {#see-also .mansect}
447
+
448
+
> [*ls*](../utilities/ls.html#),
449
+
> [*umask*](../utilities/umask.html#tag_20_138)
450
+
>
451
+
> XBD [*File Access Permissions*](../basedefs/V1_chap04.html#tag_04_05),
452
+
> [*Environment Variables*](../basedefs/V1_chap08.html#tag_08),
453
+
> [*Utility Syntax Guidelines*](../basedefs/V1_chap12.html#tag_12_02)
454
+
>
455
+
> XSH [*chmod*](../functions/chmod.html#tag_16_58)
456
+
457
+
#### []{#tag_20_17_21}CHANGE HISTORY {#change-history .mansect}
458
+
459
+
> First released in Issue 2.
460
+
461
+
#### []{#tag_20_17_22}Issue 6 {#issue-6 .mansect}
462
+
463
+
> The following new requirements on POSIX implementations derive from
464
+
> alignment with the Single UNIX Specification:
465
+
>
466
+
> - Octal modes have been kept and made mandatory despite being marked
467
+
> obsolescent in the ISO POSIX-2:1993 standard.
468
+
>
469
+
> IEEE PASC Interpretation 1003.2 #172 is applied, changing the
470
+
> CONSEQUENCES OF ERRORS section to \"Default.\".
471
+
>
472
+
> The Open Group Base Resolution bwg2001-010 is applied, adding the
473
+
> description of the S_ISVTX bit and the **t perm** symbol as part of
474
+
> the XSI option.
475
+
>
476
+
> IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/16 is applied,
477
+
> changing the XSI shaded text in the EXTENDED DESCRIPTION from:
478
+
>
479
+
> > \`\`The **perm** symbol **t** shall specify the S_ISVTX bit and
480
+
> > shall apply to directories only. The effect when using it with any
481
+
> > other file type is unspecified. It can be used with the **who**
482
+
> > symbols **o**, **a**, or with no **who** symbol. It shall not be an
483
+
> > error to specify a **who** symbol of **u** or **g** in conjunction
484
+
> > with the **perm** symbol **t**; it shall be ignored for **u** and
485
+
> > **g**.\"
486
+
>
487
+
> to:
488
+
>
489
+
> > \`\`The **perm** symbol **t** shall specify the S_ISVTX bit. When
490
+
> > used with a file of type directory, it can be used with the **who**
491
+
> > symbol **a**, or with no **who** symbol. It shall not be an error to
492
+
> > specify a **who** symbol of **u**, **g**, or **o** in conjunction
493
+
> > with the **perm** symbol **t**, but the meaning of these
494
+
> > combinations is unspecified. The effect when using the **perm**
495
+
> > symbol **t** with any file type other than directory is
496
+
> > unspecified.\"
497
+
>
498
+
> This change is to permit historical behavior.
499
+
500
+
#### []{#tag_20_17_23}Issue 7 {#issue-7 .mansect}
501
+
502
+
> SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.
503
+
>
504
+
> Austin Group Interpretation 1003.1-2001 #130 is applied, adding text
505
+
> to the DESCRIPTION about about marking for update the last file status
506
+
> change timestamp of the file.
507
+
+598
docs/posix2018/cp.md
+598
docs/posix2018/cp.md
···
1
+
#### []{#tag_20_24_01}NAME {#name .mansect}
2
+
3
+
> cp - copy files
4
+
5
+
#### []{#tag_20_24_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `cp`` `**`[`**`-Pfip`**`]`**` `*`source_file target_file`*\
8
+
> \
9
+
> `cp`` `**`[`**`-Pfip`**`]`**` `*`source_file`*`...`` `*`target`*\
10
+
> \
11
+
> `cp -R`` `**`[`**`-H|-L|-P`**`] [`**`-fip`**`]`**` `*`source_file`*`...`` `*`target`*\
12
+
13
+
#### []{#tag_20_24_03}DESCRIPTION {#description .mansect}
14
+
15
+
> The first synopsis form is denoted by two operands, neither of which
16
+
> are existing files of type directory. The *cp* utility shall copy the
17
+
> contents of *source_file* (or, if *source_file* is a file of type
18
+
> symbolic link, the contents of the file referenced by *source_file*)
19
+
> to the destination path named by *target_file.*
20
+
>
21
+
> The second synopsis form is denoted by two or more operands where the
22
+
> **-R** option is not specified and the first synopsis form is not
23
+
> applicable. It shall be an error if any *source_file* is a file of
24
+
> type directory, if *target* does not exist, or if *target* does not
25
+
> name a directory. The *cp* utility shall copy the contents of each
26
+
> *source_file* (or, if *source_file* is a file of type symbolic link,
27
+
> the contents of the file referenced by *source_file*) to the
28
+
> destination path named by the concatenation of *target*, a single
29
+
> \<slash\> character if *target* did not end in a \<slash\>, and the
30
+
> last component of *source_file*.
31
+
>
32
+
> The third synopsis form is denoted by two or more operands where the
33
+
> **-R** option is specified. The *cp* utility shall copy each file in
34
+
> the file hierarchy rooted in each *source_file* to a destination path
35
+
> named as follows:
36
+
>
37
+
> - If *target* exists and names an existing directory, the name of the
38
+
> corresponding destination path for each file in the file hierarchy
39
+
> shall be the concatenation of *target*, a single \<slash\> character
40
+
> if *target* did not end in a \<slash\>, and the pathname of the file
41
+
> relative to the directory containing *source_file*.
42
+
>
43
+
> - If *target* does not exist and two operands are specified, the name
44
+
> of the corresponding destination path for *source_file* shall be
45
+
> *target*; the name of the corresponding destination path for all
46
+
> other files in the file hierarchy shall be the concatenation of
47
+
> *target*, a \<slash\> character, and the pathname of the file
48
+
> relative to *source_file*.
49
+
>
50
+
> It shall be an error if *target* does not exist and more than two
51
+
> operands are specified, or if *target* exists and does not name a
52
+
> directory.
53
+
>
54
+
> In the following description, the term *dest_file* refers to the file
55
+
> named by the destination path. The term *source_file* refers to the
56
+
> file that is being copied, whether specified as an operand or a file
57
+
> in a file hierarchy rooted in a *source_file* operand. If
58
+
> *source_file* is a file of type symbolic link:
59
+
>
60
+
> - If the **-R** option was not specified, *cp* shall take actions
61
+
> based on the type and contents of the file referenced by the
62
+
> symbolic link, and not by the symbolic link itself, unless the
63
+
> **-P** option was specified.
64
+
>
65
+
> - If the **-R** option was specified:
66
+
>
67
+
> - If none of the options **-H**, **-L**, nor **-P** were specified,
68
+
> it is unspecified which of **-H**, **-L**, or **-P** will be used
69
+
> as a default.
70
+
>
71
+
> - If the **-H** option was specified, *cp* shall take actions based
72
+
> on the type and contents of the file referenced by any symbolic
73
+
> link specified as a *source_file* operand.
74
+
>
75
+
> - If the **-L** option was specified, *cp* shall take actions based
76
+
> on the type and contents of the file referenced by any symbolic
77
+
> link specified as a *source_file* operand or any symbolic links
78
+
> encountered during traversal of a file hierarchy.
79
+
>
80
+
> - If the **-P** option was specified, *cp* shall copy any symbolic
81
+
> link specified as a *source_file* operand and any symbolic links
82
+
> encountered during traversal of a file hierarchy, and shall not
83
+
> follow any symbolic links.
84
+
>
85
+
> For each *source_file*, the following steps shall be taken:
86
+
>
87
+
> 1. If *source_file* references the same file as *dest_file*, *cp* may
88
+
> write a diagnostic message to standard error; it shall do nothing
89
+
> more with *source_file* and shall go on to any remaining files.
90
+
>
91
+
> 2. If *source_file* is of type directory, the following steps shall
92
+
> be taken:
93
+
>
94
+
> a. If the **-R** option was not specified, *cp* shall write a
95
+
> diagnostic message to standard error, do nothing more with
96
+
> *source_file*, and go on to any remaining files.
97
+
>
98
+
> b. If *source_file* was not specified as an operand and
99
+
> *source_file* is dot or dot-dot, *cp* shall do nothing more
100
+
> with *source_file* and go on to any remaining files.
101
+
>
102
+
> c. If *dest_file* exists and it is a file type not specified by
103
+
> the System Interfaces volume of POSIX.1-2017, the behavior is
104
+
> implementation-defined.
105
+
>
106
+
> d. If *dest_file* exists and it is not of type directory, *cp*
107
+
> shall write a diagnostic message to standard error, do nothing
108
+
> more with *source_file* or any files below *source_file* in
109
+
> the file hierarchy, and go on to any remaining files.
110
+
>
111
+
> e. If the directory *dest_file* does not exist, it shall be
112
+
> created with file permission bits set to the same value as
113
+
> those of *source_file*, modified by the file creation mask of
114
+
> the user if the **-p** option was not specified, and then
115
+
> bitwise-inclusively OR\'ed with S_IRWXU. If *dest_file* cannot
116
+
> be created, *cp* shall write a diagnostic message to standard
117
+
> error, do nothing more with *source_file*, and go on to any
118
+
> remaining files. It is unspecified if *cp* attempts to copy
119
+
> files in the file hierarchy rooted in *source_file*.
120
+
>
121
+
> f. The files in the directory *source_file* shall be copied to
122
+
> the directory *dest_file*, taking the four steps (1 to 4)
123
+
> listed here with the files as *source_file*s.
124
+
>
125
+
> g. If *dest_file* was created, its file permission bits shall be
126
+
> changed (if necessary) to be the same as those of
127
+
> *source_file*, modified by the file creation mask of the user
128
+
> if the **-p** option was not specified.
129
+
>
130
+
> h. The *cp* utility shall do nothing more with *source_file* and
131
+
> go on to any remaining files.
132
+
>
133
+
> 3. If *source_file* is of type regular file, the following steps
134
+
> shall be taken:
135
+
>
136
+
> a. The behavior is unspecified if *dest_file* exists and was
137
+
> written by a previous step. Otherwise, if *dest_file* exists,
138
+
> the following steps shall be taken:
139
+
>
140
+
> i. If the **-i** option is in effect, the *cp* utility shall
141
+
> write a prompt to the standard error and read a line from
142
+
> the standard input. If the response is not affirmative,
143
+
> *cp* shall do nothing more with *source_file* and go on to
144
+
> any remaining files.
145
+
>
146
+
> ii. A file descriptor for *dest_file* shall be obtained by
147
+
> performing actions equivalent to the
148
+
> [*open*()](../functions/open.html) function defined in the
149
+
> System Interfaces volume of POSIX.1-2017 called using
150
+
> *dest_file* as the *path* argument, and the
151
+
> bitwise-inclusive OR of O_WRONLY and O_TRUNC as the
152
+
> *oflag* argument.
153
+
>
154
+
> iii. If the attempt to obtain a file descriptor fails and the
155
+
> **-f** option is in effect, *cp* shall attempt to remove
156
+
> the file by performing actions equivalent to the
157
+
> [*unlink*()](../functions/unlink.html) function defined
158
+
> in the System Interfaces volume of POSIX.1-2017 called
159
+
> using *dest_file* as the *path* argument. If this attempt
160
+
> succeeds, *cp* shall continue with step 3b.
161
+
>
162
+
> b. If *dest_file* does not exist, a file descriptor shall be
163
+
> obtained by performing actions equivalent to the
164
+
> [*open*()](../functions/open.html) function defined in the
165
+
> System Interfaces volume of POSIX.1-2017 called using
166
+
> *dest_file* as the *path* argument, and the bitwise-inclusive
167
+
> OR of O_WRONLY and O_CREAT as the *oflag* argument. The file
168
+
> permission bits of *source_file* shall be the *mode* argument.
169
+
>
170
+
> c. If the attempt to obtain a file descriptor fails, *cp* shall
171
+
> write a diagnostic message to standard error, do nothing more
172
+
> with *source_file*, and go on to any remaining files.
173
+
>
174
+
> d. The contents of *source_file* shall be written to the file
175
+
> descriptor. Any write errors shall cause *cp* to write a
176
+
> diagnostic message to standard error and continue to step 3e.
177
+
>
178
+
> e. The file descriptor shall be closed.
179
+
>
180
+
> f. The *cp* utility shall do nothing more with *source_file*. If
181
+
> a write error occurred in step 3d, it is unspecified if *cp*
182
+
> continues with any remaining files. If no write error occurred
183
+
> in step 3d, *cp* shall go on to any remaining files.
184
+
>
185
+
> 4. Otherwise, the **-R** option was specified, and the following
186
+
> steps shall be taken:
187
+
>
188
+
> a. The *dest_file* shall be created with the same file type as
189
+
> *source_file*.
190
+
>
191
+
> b. If *source_file* is a file of type FIFO, the file permission
192
+
> bits shall be the same as those of *source_file,* modified by
193
+
> the file creation mask of the user if the **-p** option was
194
+
> not specified. Otherwise, the permissions, owner ID, and group
195
+
> ID of *dest_file* are implementation-defined.
196
+
>
197
+
> If this creation fails for any reason, *cp* shall write a
198
+
> diagnostic message to standard error, do nothing more with
199
+
> *source_file*, and go on to any remaining files.
200
+
>
201
+
> c. If *source_file* is a file of type symbolic link, and the
202
+
> options require the symbolic link itself to be acted upon, the
203
+
> pathname contained in *dest_file* shall be the same as the
204
+
> pathname contained in *source_file*.
205
+
>
206
+
> If this fails for any reason, *cp* shall write a diagnostic
207
+
> message to standard error, do nothing more with *source_file*,
208
+
> and go on to any remaining files.
209
+
>
210
+
> If the implementation provides additional or alternate access control
211
+
> mechanisms (see XBD [*File Access
212
+
> Permissions*](../basedefs/V1_chap04.html#tag_04_05)), their effect on
213
+
> copies of files is implementation-defined.
214
+
215
+
#### []{#tag_20_24_04}OPTIONS {#options .mansect}
216
+
217
+
> The *cp* utility shall conform to XBD [*Utility Syntax
218
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02) .
219
+
>
220
+
> The following options shall be supported:
221
+
>
222
+
> **-f**
223
+
> : If a file descriptor for a destination file cannot be obtained, as
224
+
> described in step 3.a.ii., attempt to unlink the destination file
225
+
> and proceed.
226
+
>
227
+
> **-H**
228
+
> : Take actions based on the type and contents of the file referenced
229
+
> by any symbolic link specified as a *source_file* operand.
230
+
>
231
+
> **-i**
232
+
> : Write a prompt to standard error before copying to any existing
233
+
> non-directory destination file. If the response from the standard
234
+
> input is affirmative, the copy shall be attempted; otherwise, it
235
+
> shall not.
236
+
>
237
+
> **-L**
238
+
> : Take actions based on the type and contents of the file referenced
239
+
> by any symbolic link specified as a *source_file* operand or any
240
+
> symbolic links encountered during traversal of a file hierarchy.
241
+
>
242
+
> **-P**
243
+
> : Take actions on any symbolic link specified as a *source_file*
244
+
> operand or any symbolic link encountered during traversal of a
245
+
> file hierarchy.
246
+
>
247
+
> **-p**
248
+
>
249
+
> : Duplicate the following characteristics of each source file in the
250
+
> corresponding destination file:
251
+
>
252
+
> 1. The time of last data modification and time of last access. If
253
+
> this duplication fails for any reason, *cp* shall write a
254
+
> diagnostic message to standard error.
255
+
>
256
+
> 2. The user ID and group ID. If this duplication fails for any
257
+
> reason, it is unspecified whether *cp* writes a diagnostic
258
+
> message to standard error.
259
+
>
260
+
> 3. The file permission bits and the S_ISUID and S_ISGID bits.
261
+
> Other, implementation-defined, bits may be duplicated as well.
262
+
> If this duplication fails for any reason, *cp* shall write a
263
+
> diagnostic message to standard error.
264
+
>
265
+
> If the user ID or the group ID cannot be duplicated, the file
266
+
> permission bits S_ISUID and S_ISGID shall be cleared. If these
267
+
> bits are present in the source file but are not duplicated in the
268
+
> destination file, it is unspecified whether *cp* writes a
269
+
> diagnostic message to standard error.
270
+
>
271
+
> The order in which the preceding characteristics are duplicated is
272
+
> unspecified. The *dest_file* shall not be deleted if these
273
+
> characteristics cannot be preserved.
274
+
>
275
+
> **-R**
276
+
> : Copy file hierarchies.
277
+
>
278
+
> Specifying more than one of the mutually-exclusive options **-H**,
279
+
> **-L**, and **-P** shall not be considered an error. The last option
280
+
> specified shall determine the behavior of the utility.
281
+
282
+
#### []{#tag_20_24_05}OPERANDS {#operands .mansect}
283
+
284
+
> The following operands shall be supported:
285
+
>
286
+
> *source_file*
287
+
> : A pathname of a file to be copied. If a *source_file* operand is
288
+
> `'-'`, it shall refer to a file named **-**; implementations shall
289
+
> not treat it as meaning standard input.
290
+
>
291
+
> *target_file*
292
+
> : A pathname of an existing or nonexistent file, used for the output
293
+
> when a single file is copied. If a *target_file* operand is `'-'`,
294
+
> it shall refer to a file named **-**; implementations shall not
295
+
> treat it as meaning standard output.
296
+
>
297
+
> *target*
298
+
> : A pathname of a directory to contain the copied files.
299
+
300
+
#### []{#tag_20_24_06}STDIN {#stdin .mansect}
301
+
302
+
> The standard input shall be used to read an input line in response to
303
+
> each prompt specified in the STDERR section. Otherwise, the standard
304
+
> input shall not be used.
305
+
306
+
#### []{#tag_20_24_07}INPUT FILES {#input-files .mansect}
307
+
308
+
> The input files specified as operands may be of any file type.
309
+
310
+
#### []{#tag_20_24_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
311
+
312
+
> The following environment variables shall affect the execution of
313
+
> *cp*:
314
+
>
315
+
> *LANG*
316
+
> : Provide a default value for the internationalization variables
317
+
> that are unset or null. (See XBD [*Internationalization
318
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
319
+
> precedence of internationalization variables used to determine the
320
+
> values of locale categories.)
321
+
>
322
+
> *LC_ALL*
323
+
> : If set to a non-empty string value, override the values of all the
324
+
> other internationalization variables.
325
+
>
326
+
> *LC_COLLATE*
327
+
> : Determine the locale for the behavior of ranges, equivalence
328
+
> classes, and multi-character collating elements used in the
329
+
> extended regular expression defined for the **yesexpr** locale
330
+
> keyword in the *LC_MESSAGES* category.
331
+
>
332
+
> *LC_CTYPE*
333
+
> : Determine the locale for the interpretation of sequences of bytes
334
+
> of text data as characters (for example, single-byte as opposed to
335
+
> multi-byte characters in arguments and input files) and the
336
+
> behavior of character classes used in the extended regular
337
+
> expression defined for the **yesexpr** locale keyword in the
338
+
> *LC_MESSAGES* category.
339
+
>
340
+
> *LC_MESSAGES*
341
+
> : Determine the locale used to process affirmative responses, and
342
+
> the locale used to affect the format and contents of diagnostic
343
+
> messages and prompts written to standard error.
344
+
>
345
+
> *NLSPATH*
346
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
347
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
348
+
> location of message catalogs for the processing of *LC_MESSAGES.*
349
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
350
+
351
+
#### []{#tag_20_24_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
352
+
353
+
> Default.
354
+
355
+
#### []{#tag_20_24_10}STDOUT {#stdout .mansect}
356
+
357
+
> Not used.
358
+
359
+
#### []{#tag_20_24_11}STDERR {#stderr .mansect}
360
+
361
+
> A prompt shall be written to standard error under the conditions
362
+
> specified in the DESCRIPTION section. The prompt shall contain the
363
+
> destination pathname, but its format is otherwise unspecified.
364
+
> Otherwise, the standard error shall be used only for diagnostic
365
+
> messages.
366
+
367
+
#### []{#tag_20_24_12}OUTPUT FILES {#output-files .mansect}
368
+
369
+
> The output files may be of any type.
370
+
371
+
#### []{#tag_20_24_13}EXTENDED DESCRIPTION {#extended-description .mansect}
372
+
373
+
> None.
374
+
375
+
#### []{#tag_20_24_14}EXIT STATUS {#exit-status .mansect}
376
+
377
+
> The following exit values shall be returned:
378
+
>
379
+
> 0
380
+
> : All files were copied successfully.
381
+
>
382
+
> \>0
383
+
> : An error occurred.
384
+
385
+
#### []{#tag_20_24_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
386
+
387
+
> If *cp* is prematurely terminated by a signal or error, files or file
388
+
> hierarchies may be only partially copied and files and directories may
389
+
> have incorrect permissions or access and modification times.
390
+
391
+
------------------------------------------------------------------------
392
+
393
+
::: box
394
+
*The following sections are informative.*
395
+
:::
396
+
397
+
#### []{#tag_20_24_16}APPLICATION USAGE {#application-usage .mansect}
398
+
399
+
> The set-user-ID and set-group-ID bits are explicitly cleared when
400
+
> files are created. This is to prevent users from creating programs
401
+
> that are set-user-ID or set-group-ID to them when copying files or to
402
+
> make set-user-ID or set-group-ID files accessible to new groups of
403
+
> users. For example, if a file is set-user-ID and the copy has a
404
+
> different group ID than the source, a new group of users has execute
405
+
> permission to a set-user-ID program than did previously. In
406
+
> particular, this is a problem for superusers copying users\' trees.
407
+
408
+
#### []{#tag_20_24_17}EXAMPLES {#examples .mansect}
409
+
410
+
> None.
411
+
412
+
#### []{#tag_20_24_18}RATIONALE {#rationale .mansect}
413
+
414
+
> The **-i** option exists on BSD systems, giving applications and users
415
+
> a way to avoid accidentally removing files when copying. Although the
416
+
> 4.3 BSD version does not prompt if the standard input is not a
417
+
> terminal, the standard developers decided that use of **-i** is a
418
+
> request for interaction, so when the destination path exists, the
419
+
> utility takes instructions from whatever responds on standard input.
420
+
>
421
+
> The exact format of the interactive prompts is unspecified. Only the
422
+
> general nature of the contents of prompts are specified because
423
+
> implementations may desire more descriptive prompts than those used on
424
+
> historical implementations. Therefore, an application using the **-i**
425
+
> option relies on the system to provide the most suitable dialog
426
+
> directly with the user, based on the behavior specified.
427
+
>
428
+
> The **-p** option is historical practice on BSD systems, duplicating
429
+
> the time of last data modification and time of last access. This
430
+
> volume of POSIX.1-2017 extends it to preserve the user and group IDs,
431
+
> as well as the file permissions. This requirement has obvious problems
432
+
> in that the directories are almost certainly modified after being
433
+
> copied. This volume of POSIX.1-2017 requires that the modification
434
+
> times be preserved. The statement that the order in which the
435
+
> characteristics are duplicated is unspecified is to permit
436
+
> implementations to provide the maximum amount of security for the
437
+
> user. Implementations should take into account the obvious security
438
+
> issues involved in setting the owner, group, and mode in the wrong
439
+
> order or creating files with an owner, group, or mode different from
440
+
> the final value.
441
+
>
442
+
> It is unspecified whether *cp* writes diagnostic messages when the
443
+
> user and group IDs cannot be set due to the widespread practice of
444
+
> users using **-p** to duplicate some portion of the file
445
+
> characteristics, indifferent to the duplication of others. Historic
446
+
> implementations only write diagnostic messages on errors other than
447
+
> \[EPERM\].
448
+
>
449
+
> Earlier versions of this standard included support for the **-r**
450
+
> option to copy file hierarchies. The **-r** option is historical
451
+
> practice on BSD and BSD-derived systems. This option is no longer
452
+
> specified by POSIX.1-2017 but may be present in some implementations.
453
+
> The **-R** option was added as a close synonym to the **-r** option,
454
+
> selected for consistency with all other options in this volume of
455
+
> POSIX.1-2017 that do recursive directory descent.
456
+
>
457
+
> The difference between **-R** and the removed **-r** option is in the
458
+
> treatment by *cp* of file types other than regular and directory. It
459
+
> was implementation-defined how the **-** option treated special files
460
+
> to allow both historical implementations and those that chose to
461
+
> support **-r** with the same abilities as **-R** defined by this
462
+
> volume of POSIX.1-2017. The original **-r** flag, for historic
463
+
> reasons, did not handle special files any differently from regular
464
+
> files, but always read the file and copied its contents. This had
465
+
> obvious problems in the presence of special file types; for example,
466
+
> character devices, FIFOs, and sockets.
467
+
>
468
+
> When a failure occurs during the copying of a file hierarchy, *cp* is
469
+
> required to attempt to copy files that are on the same level in the
470
+
> hierarchy or above the file where the failure occurred. It is
471
+
> unspecified if *cp* shall attempt to copy files below the file where
472
+
> the failure occurred (which cannot succeed in any case).
473
+
>
474
+
> Permissions, owners, and groups of created special file types have
475
+
> been deliberately left as implementation-defined. This is to allow
476
+
> systems to satisfy special requirements (for example, allowing users
477
+
> to create character special devices, but requiring them to be owned by
478
+
> a certain group). In general, it is strongly suggested that the
479
+
> permissions, owner, and group be the same as if the user had run the
480
+
> historical *mknod*, [*ln*](../utilities/ln.html), or other utility to
481
+
> create the file. It is also probable that additional privileges are
482
+
> required to create block, character, or other implementation-defined
483
+
> special file types.
484
+
>
485
+
> Additionally, the **-p** option explicitly requires that all
486
+
> set-user-ID and set-group-ID permissions be discarded if any of the
487
+
> owner or group IDs cannot be set. This is to keep users from
488
+
> unintentionally giving away special privilege when copying programs.
489
+
>
490
+
> When creating regular files, historical versions of *cp* use the mode
491
+
> of the source file as modified by the file mode creation mask. Other
492
+
> choices would have been to use the mode of the source file unmodified
493
+
> by the creation mask or to use the same mode as would be given to a
494
+
> new file created by the user (plus the execution bits of the source
495
+
> file) and then modify it by the file mode creation mask. In the
496
+
> absence of any strong reason to change historic practice, it was in
497
+
> large part retained.
498
+
>
499
+
> When creating directories, historical versions of *cp* use the mode of
500
+
> the source directory, plus read, write, and search bits for the owner,
501
+
> as modified by the file mode creation mask. This is done so that *cp*
502
+
> can copy trees where the user has read permission, but the owner does
503
+
> not. A side-effect is that if the file creation mask denies the owner
504
+
> permissions, *cp* fails. Also, once the copy is done, historical
505
+
> versions of *cp* set the permissions on the created directory to be
506
+
> the same as the source directory, unmodified by the file creation
507
+
> mask.
508
+
>
509
+
> This behavior has been modified so that *cp* is always able to create
510
+
> the contents of the directory, regardless of the file creation mask.
511
+
> After the copy is done, the permissions are set to be the same as the
512
+
> source directory, as modified by the file creation mask. This latter
513
+
> change from historical behavior is to prevent users from accidentally
514
+
> creating directories with permissions beyond those they would normally
515
+
> set and for consistency with the behavior of *cp* in creating files.
516
+
>
517
+
> It is not a requirement that *cp* detect attempts to copy a file to
518
+
> itself; however, implementations are strongly encouraged to do so.
519
+
> Historical implementations have detected the attempt in most cases.
520
+
>
521
+
> There are two methods of copying subtrees in this volume of
522
+
> POSIX.1-2017. The other method is described as part of the
523
+
> [*pax*](../utilities/pax.html) utility (see
524
+
> [*pax*](../utilities/pax.html#)). Both methods are historical
525
+
> practice. The *cp* utility provides a simpler, more intuitive
526
+
> interface, while [*pax*](../utilities/pax.html) offers a finer
527
+
> granularity of control. Each provides additional functionality to the
528
+
> other; in particular, [*pax*](../utilities/pax.html) maintains the
529
+
> hard-link structure of the hierarchy, while *cp* does not. It is the
530
+
> intention of the standard developers that the results be similar
531
+
> (using appropriate option combinations in both utilities). The results
532
+
> are not required to be identical; there seemed insufficient gain to
533
+
> applications to balance the difficulty of implementations having to
534
+
> guarantee that the results would be exactly identical.
535
+
>
536
+
> The wording allowing *cp* to copy a directory to
537
+
> implementation-defined file types not specified by the System
538
+
> Interfaces volume of POSIX.1-2017 is provided so that implementations
539
+
> supporting symbolic links are not required to prohibit copying
540
+
> directories to symbolic links. Other extensions to the System
541
+
> Interfaces volume of POSIX.1-2017 file types may need to use this
542
+
> loophole as well.
543
+
544
+
#### []{#tag_20_24_19}FUTURE DIRECTIONS {#future-directions .mansect}
545
+
546
+
> None.
547
+
548
+
#### []{#tag_20_24_20}SEE ALSO {#see-also .mansect}
549
+
550
+
> [*mv*](../utilities/mv.html#), [*find*](../utilities/find.html#),
551
+
> [*ln*](../utilities/ln.html#), [*pax*](../utilities/pax.html#)
552
+
>
553
+
> XBD [*File Access Permissions*](../basedefs/V1_chap04.html#tag_04_05),
554
+
> [*Environment Variables*](../basedefs/V1_chap08.html#tag_08),
555
+
> [*Utility Syntax Guidelines*](../basedefs/V1_chap12.html#tag_12_02)
556
+
>
557
+
> XSH [*open*](../functions/open.html#),
558
+
> [*unlink*](../functions/unlink.html#tag_16_635)
559
+
560
+
#### []{#tag_20_24_21}CHANGE HISTORY {#change-history .mansect}
561
+
562
+
> First released in Issue 2.
563
+
564
+
#### []{#tag_20_24_22}Issue 6 {#issue-6 .mansect}
565
+
566
+
> The **-r** option is marked obsolescent.
567
+
>
568
+
> The new options **-H**, **-L**, and **-P** are added to align with the
569
+
> IEEE P1003.2b draft standard. These options affect the processing of
570
+
> symbolic links.
571
+
>
572
+
> IEEE PASC Interpretation 1003.2 #194 is applied, adding a description
573
+
> of the **-P** option.
574
+
>
575
+
> IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/18 is applied,
576
+
> correcting an error in the SEE ALSO section.
577
+
578
+
#### []{#tag_20_24_23}Issue 7 {#issue-7 .mansect}
579
+
580
+
> Austin Group Interpretation 1003.1-2001 #126 is applied, changing the
581
+
> description of the *LC_MESSAGES* environment variable.
582
+
>
583
+
> Austin Group Interpretations 1003.1-2001 #092, #164, #165, and #168
584
+
> are applied.
585
+
>
586
+
> SD5-XCU-ERN-31 and SD5-XCU-ERN-42 are applied, updating the
587
+
> DESCRIPTION.
588
+
>
589
+
> SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.
590
+
>
591
+
> SD5-XCU-ERN-102 is applied, clarifying the **-i** option within the
592
+
> OPTIONS section.
593
+
>
594
+
> The obsolescent **-r** option is removed.
595
+
>
596
+
> The **-P** option is added to the SYNOPSIS and to the DESCRIPTION with
597
+
> respect to the **-R** option.
598
+
+353
docs/posix2018/cut.md
+353
docs/posix2018/cut.md
···
1
+
#### []{#tag_20_28_01}NAME {#name .mansect}
2
+
3
+
> cut - cut out selected fields of each line of a file
4
+
5
+
#### []{#tag_20_28_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `cut -b`` `*`list`*` `**`[`**`-n`**`] [`***`file`*`...`**`]`**\
8
+
> \
9
+
> `cut -c`` `*`list`*` `**`[`***`file`*`...`**`]`**\
10
+
> \
11
+
> `cut -f`` `*`list`*` `**`[`**`-d`` `*`delim`***`] [`**`-s`**`] [`***`file`*`...`**`]`**\
12
+
13
+
#### []{#tag_20_28_03}DESCRIPTION {#description .mansect}
14
+
15
+
> The *cut* utility shall cut out bytes (**-b** option), characters
16
+
> (**-c** option), or character-delimited fields ( **-f** option) from
17
+
> each line in one or more files, concatenate them, and write them to
18
+
> standard output.
19
+
20
+
#### []{#tag_20_28_04}OPTIONS {#options .mansect}
21
+
22
+
> The *cut* utility shall conform to XBD [*Utility Syntax
23
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02) .
24
+
>
25
+
> The application shall ensure that the option-argument *list* (see
26
+
> options **-b**, **-c**, and **-f** below) is a \<comma\>-separated
27
+
> list or \<blank\>-separated list of positive numbers and ranges.
28
+
> Ranges can be in three forms. The first is two positive numbers
29
+
> separated by a \<hyphen-minus\> (*low*- *high*), which represents all
30
+
> fields from the first number to the second number. The second is a
31
+
> positive number preceded by a \<hyphen-minus\> (- *high*), which
32
+
> represents all fields from field number 1 to that number. The third is
33
+
> a positive number followed by a \<hyphen-minus\> ( *low*-), which
34
+
> represents that number to the last field, inclusive. The elements in
35
+
> *list* can be repeated, can overlap, and can be specified in any
36
+
> order, but the bytes, characters, or fields selected shall be written
37
+
> in the order of the input data. If an element appears in the selection
38
+
> list more than once, it shall be written exactly once.
39
+
>
40
+
> The following options shall be supported:
41
+
>
42
+
> **-b ** *list*
43
+
> : Cut based on a *list* of bytes. Each selected byte shall be output
44
+
> unless the **-n** option is also specified. It shall not be an
45
+
> error to select bytes not present in the input line.
46
+
>
47
+
> **-c ** *list*
48
+
> : Cut based on a *list* of characters. Each selected character shall
49
+
> be output. It shall not be an error to select characters not
50
+
> present in the input line.
51
+
>
52
+
> **-d ** *delim*
53
+
> : Set the field delimiter to the character *delim*. The default is
54
+
> the \<tab\>.
55
+
>
56
+
> **-f ** *list*
57
+
> : Cut based on a *list* of fields, assumed to be separated in the
58
+
> file by a delimiter character (see **-d**). Each selected field
59
+
> shall be output. Output fields shall be separated by a single
60
+
> occurrence of the field delimiter character. Lines with no field
61
+
> delimiters shall be passed through intact, unless **-s** is
62
+
> specified. It shall not be an error to select fields not present
63
+
> in the input line.
64
+
>
65
+
> **-n**
66
+
>
67
+
> : Do not split characters. When specified with the **-b** option,
68
+
> each element in *list* of the form *low*- *high* (
69
+
> \<hyphen-minus\>-separated numbers) shall be modified as follows:
70
+
>
71
+
> - If the byte selected by *low* is not the first byte of a
72
+
> character, *low* shall be decremented to select the first byte
73
+
> of the character originally selected by *low*. If the byte
74
+
> selected by *high* is not the last byte of a character, *high*
75
+
> shall be decremented to select the last byte of the character
76
+
> prior to the character originally selected by *high*, or zero if
77
+
> there is no prior character. If the resulting range element has
78
+
> *high* equal to zero or *low* greater than *high*, the list
79
+
> element shall be dropped from *list* for that input line without
80
+
> causing an error.
81
+
>
82
+
> Each element in *list* of the form *low*- shall be treated as
83
+
> above with *high* set to the number of bytes in the current line,
84
+
> not including the terminating \<newline\>. Each element in *list*
85
+
> of the form - *high* shall be treated as above with *low* set
86
+
> to 1. Each element in *list* of the form *num* (a single number)
87
+
> shall be treated as above with *low* set to *num* and *high* set
88
+
> to *num*.
89
+
>
90
+
> **-s**
91
+
> : Suppress lines with no delimiter characters, when used with the
92
+
> **-f** option. Unless specified, lines with no delimiters shall be
93
+
> passed through untouched.
94
+
95
+
#### []{#tag_20_28_05}OPERANDS {#operands .mansect}
96
+
97
+
> The following operand shall be supported:
98
+
>
99
+
> *file*
100
+
> : A pathname of an input file. If no *file* operands are specified,
101
+
> or if a *file* operand is `'-'`, the standard input shall be used.
102
+
103
+
#### []{#tag_20_28_06}STDIN {#stdin .mansect}
104
+
105
+
> The standard input shall be used only if no *file* operands are
106
+
> specified, or if a *file* operand is `'-'`. See the INPUT FILES
107
+
> section.
108
+
109
+
#### []{#tag_20_28_07}INPUT FILES {#input-files .mansect}
110
+
111
+
> The input files shall be text files, except that line lengths shall be
112
+
> unlimited.
113
+
114
+
#### []{#tag_20_28_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
115
+
116
+
> The following environment variables shall affect the execution of
117
+
> *cut*:
118
+
>
119
+
> *LANG*
120
+
> : Provide a default value for the internationalization variables
121
+
> that are unset or null. (See XBD [*Internationalization
122
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
123
+
> precedence of internationalization variables used to determine the
124
+
> values of locale categories.)
125
+
>
126
+
> *LC_ALL*
127
+
> : If set to a non-empty string value, override the values of all the
128
+
> other internationalization variables.
129
+
>
130
+
> *LC_CTYPE*
131
+
> : Determine the locale for the interpretation of sequences of bytes
132
+
> of text data as characters (for example, single-byte as opposed to
133
+
> multi-byte characters in arguments and input files).
134
+
>
135
+
> *LC_MESSAGES*
136
+
> : Determine the locale that should be used to affect the format and
137
+
> contents of diagnostic messages written to standard error.
138
+
>
139
+
> *NLSPATH*
140
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
141
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
142
+
> location of message catalogs for the processing of *LC_MESSAGES.*
143
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
144
+
145
+
#### []{#tag_20_28_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
146
+
147
+
> Default.
148
+
149
+
#### []{#tag_20_28_10}STDOUT {#stdout .mansect}
150
+
151
+
> The *cut* utility output shall be a concatenation of the selected
152
+
> bytes, characters, or fields (one of the following):
153
+
>
154
+
>
155
+
> "%s\n", <concatenation of bytes>
156
+
>
157
+
>
158
+
> "%s\n", <concatenation of characters>
159
+
>
160
+
>
161
+
> "%s\n", <concatenation of fields and field delimiters>
162
+
163
+
#### []{#tag_20_28_11}STDERR {#stderr .mansect}
164
+
165
+
> The standard error shall be used only for diagnostic messages.
166
+
167
+
#### []{#tag_20_28_12}OUTPUT FILES {#output-files .mansect}
168
+
169
+
> None.
170
+
171
+
#### []{#tag_20_28_13}EXTENDED DESCRIPTION {#extended-description .mansect}
172
+
173
+
> None.
174
+
175
+
#### []{#tag_20_28_14}EXIT STATUS {#exit-status .mansect}
176
+
177
+
> The following exit values shall be returned:
178
+
>
179
+
> 0
180
+
> : All input files were output successfully.
181
+
>
182
+
> \>0
183
+
> : An error occurred.
184
+
185
+
#### []{#tag_20_28_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
186
+
187
+
> Default.
188
+
189
+
------------------------------------------------------------------------
190
+
191
+
::: box
192
+
*The following sections are informative.*
193
+
:::
194
+
195
+
#### []{#tag_20_28_16}APPLICATION USAGE {#application-usage .mansect}
196
+
197
+
> The *cut* and [*fold*](../utilities/fold.html) utilities can be used
198
+
> to create text files out of files with arbitrary line lengths. The
199
+
> *cut* utility should be used when the number of lines (or records)
200
+
> needs to remain constant. The [*fold*](../utilities/fold.html) utility
201
+
> should be used when the contents of long lines need to be kept
202
+
> contiguous.
203
+
>
204
+
> Earlier versions of the *cut* utility worked in an environment where
205
+
> bytes and characters were considered equivalent (modulo \<backspace\>
206
+
> and \<tab\> processing in some implementations). In the extended world
207
+
> of multi-byte characters, the new **-b** option has been added. The
208
+
> **-n** option (used with **-b**) allows it to be used to act on bytes
209
+
> rounded to character boundaries. The algorithm specified for **-n**
210
+
> guarantees that:
211
+
>
212
+
>
213
+
> cut -b 1-500 -n file > file1
214
+
> cut -b 501- -n file > file2
215
+
>
216
+
> ends up with all the characters in **file** appearing exactly once in
217
+
> **file1** or **file2**. (There is, however, a \<newline\> in both
218
+
> **file1** and **file2** for each \<newline\> in **file**.)
219
+
220
+
#### []{#tag_20_28_17}EXAMPLES {#examples .mansect}
221
+
222
+
> Examples of the option qualifier list:
223
+
>
224
+
> 1,4,7
225
+
> : Select the first, fourth, and seventh bytes, characters, or fields
226
+
> and field delimiters.
227
+
>
228
+
> 1-3,8
229
+
> : Equivalent to 1,2,3,8.
230
+
>
231
+
> -5,10
232
+
> : Equivalent to 1,2,3,4,5,10.
233
+
>
234
+
> 3-
235
+
> : Equivalent to third to last, inclusive.
236
+
>
237
+
> The *low*- *high* forms are not always equivalent when used with
238
+
> **-b** and **-n** and multi-byte characters; see the description of
239
+
> **-n**.
240
+
>
241
+
> The following command:
242
+
>
243
+
>
244
+
> cut -d : -f 1,6 /etc/passwd
245
+
>
246
+
> reads the System V password file (user database) and produces lines of
247
+
> the form:
248
+
>
249
+
>
250
+
> <user ID>:<home directory>
251
+
>
252
+
> Most utilities in this volume of POSIX.1-2017 work on text files. The
253
+
> *cut* utility can be used to turn files with arbitrary line lengths
254
+
> into a set of text files containing the same data. The
255
+
> [*paste*](../utilities/paste.html) utility can be used to create (or
256
+
> recreate) files with arbitrary line lengths. For example, if **file**
257
+
> contains long lines:
258
+
>
259
+
>
260
+
> cut -b 1-500 -n file > file1
261
+
> cut -b 501- -n file > file2
262
+
>
263
+
> creates **file1** (a text file) with lines no longer than 500 bytes
264
+
> (plus the \<newline\>) and **file2** that contains the remainder of
265
+
> the data from **file**. (Note that **file2** is not a text file if
266
+
> there are lines in **file** that are longer than 500 + {LINE_MAX}
267
+
> bytes.) The original file can be recreated from **file1** and
268
+
> **file2** using the command:
269
+
>
270
+
>
271
+
> paste -d "\0" file1 file2 > file
272
+
273
+
#### []{#tag_20_28_18}RATIONALE {#rationale .mansect}
274
+
275
+
> Some historical implementations do not count \<backspace\> characters
276
+
> in determining character counts with the **-c** option. This may be
277
+
> useful for using *cut* for processing *nroff* output. It was
278
+
> deliberately decided not to have the **-c** option treat either
279
+
> \<backspace\> or \<tab\> characters in any special fashion. The
280
+
> [*fold*](../utilities/fold.html) utility does treat these characters
281
+
> specially.
282
+
>
283
+
> Unlike other utilities, some historical implementations of *cut* exit
284
+
> after not finding an input file, rather than continuing to process the
285
+
> remaining *file* operands. This behavior is prohibited by this volume
286
+
> of POSIX.1-2017, where only the exit status is affected by this
287
+
> problem.
288
+
>
289
+
> The behavior of *cut* when provided with either mutually-exclusive
290
+
> options or options that do not work logically together has been
291
+
> deliberately left unspecified in favor of global wording in [*Utility
292
+
> Description Defaults*](../utilities/V3_chap01.html#tag_17_04).
293
+
>
294
+
> The OPTIONS section was changed in response to IEEE PASC
295
+
> Interpretation 1003.2 #149. The change represents historical practice
296
+
> on all known systems. The original standard was ambiguous on the
297
+
> nature of the output.
298
+
>
299
+
> The *list* option-arguments are historically used to select the
300
+
> portions of the line to be written, but do not affect the order of the
301
+
> data. For example:
302
+
>
303
+
>
304
+
> echo abcdefghi | cut -c6,2,4-7,1
305
+
>
306
+
> yields `"abdefg"`.
307
+
>
308
+
> A proposal to enhance *cut* with the following option:
309
+
>
310
+
> **-o**
311
+
> : Preserve the selected field order. When this option is specified,
312
+
> each byte, character, or field (or ranges of such) shall be
313
+
> written in the order specified by the *list* option-argument, even
314
+
> if this requires multiple outputs of the same bytes, characters,
315
+
> or fields.
316
+
>
317
+
> was rejected because this type of enhancement is outside the scope of
318
+
> the IEEE P1003.2b draft standard.
319
+
320
+
#### []{#tag_20_28_19}FUTURE DIRECTIONS {#future-directions .mansect}
321
+
322
+
> None.
323
+
324
+
#### []{#tag_20_28_20}SEE ALSO {#see-also .mansect}
325
+
326
+
> [*Parameters and Variables*](../utilities/V3_chap02.html#tag_18_05),
327
+
> [*fold*](../utilities/fold.html#), [*grep*](../utilities/grep.html#),
328
+
> [*paste*](../utilities/paste.html#)
329
+
>
330
+
> XBD [*Environment Variables*](../basedefs/V1_chap08.html#tag_08),
331
+
> [*Utility Syntax Guidelines*](../basedefs/V1_chap12.html#tag_12_02)
332
+
333
+
#### []{#tag_20_28_21}CHANGE HISTORY {#change-history .mansect}
334
+
335
+
> First released in Issue 2.
336
+
337
+
#### []{#tag_20_28_22}Issue 6 {#issue-6 .mansect}
338
+
339
+
> The OPTIONS section is changed to align with the IEEE P1003.2b draft
340
+
> standard.
341
+
>
342
+
> The normative text is reworded to avoid use of the term \"must\" for
343
+
> application requirements.
344
+
345
+
#### []{#tag_20_28_23}Issue 7 {#issue-7 .mansect}
346
+
347
+
> SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.
348
+
>
349
+
> SD5-XCU-ERN-171 is applied, adding APPLICATION USAGE.
350
+
>
351
+
> POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0080 \[584\] is
352
+
> applied.
353
+
+565
docs/posix2018/date.md
+565
docs/posix2018/date.md
···
1
+
#### []{#tag_20_30_01}NAME {#name .mansect}
2
+
3
+
> date - write the date and time
4
+
5
+
#### []{#tag_20_30_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `date`` `**`[`**`-u`**`] [`**`+`*`format`***`]`**\
8
+
> \
9
+
>
10
+
> ::: box
11
+
> ^`[`[`XSI`](javascript:open_code('XSI'))`]`^` `![`[Option Start]`](../images/opt-start.gif){border="0"}` date`` `**`[`**`-u`**`]`**` `*`mmddhhmm`***`[[`***`cc`***`]`***`yy`***`]`**![`[Option End]`](../images/opt-end.gif){border="0"}
12
+
> :::
13
+
>
14
+
> \
15
+
16
+
#### []{#tag_20_30_03}DESCRIPTION {#description .mansect}
17
+
18
+
> The *date* utility shall write the date and time to standard output
19
+
> ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
20
+
> Start\]](../images/opt-start.gif){border="0"} or attempt to set the
21
+
> system date and time. ![\[Option
22
+
> End\]](../images/opt-end.gif){border="0"} By default, the current date
23
+
> and time shall be written. If an operand beginning with `'+'` is
24
+
> specified, the output format of *date* shall be controlled by the
25
+
> conversion specifications and other text in the operand.
26
+
27
+
#### []{#tag_20_30_04}OPTIONS {#options .mansect}
28
+
29
+
> The *date* utility shall conform to XBD [*Utility Syntax
30
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02) .
31
+
>
32
+
> The following option shall be supported:
33
+
>
34
+
> **-u**
35
+
> : Perform operations as if the *TZ* environment variable was set to
36
+
> the string `"UTC0"`, or its equivalent historical value of
37
+
> `"GMT0"`. Otherwise, *date* shall use the timezone indicated by
38
+
> the *TZ* environment variable or the system default if that
39
+
> variable is unset or null.
40
+
41
+
#### []{#tag_20_30_05}OPERANDS {#operands .mansect}
42
+
43
+
> The following operands shall be supported:
44
+
>
45
+
> \+*format*
46
+
> : When the format is specified, each conversion specifier shall be
47
+
> replaced in the standard output by its corresponding value. All
48
+
> other characters shall be copied to the output without change. The
49
+
> output shall always be terminated with a \<newline\>.
50
+
>
51
+
> ##### []{#tag_20_30_05_01}Conversion Specifications
52
+
>
53
+
> `%a`
54
+
> : Locale\'s abbreviated weekday name.
55
+
>
56
+
> `%A`
57
+
> : Locale\'s full weekday name.
58
+
>
59
+
> `%b`
60
+
> : Locale\'s abbreviated month name.
61
+
>
62
+
> `%B`
63
+
> : Locale\'s full month name.
64
+
>
65
+
> `%c`
66
+
> : Locale\'s appropriate date and time representation.
67
+
>
68
+
> `%C`
69
+
> : Century (a year divided by 100 and truncated to an integer) as a
70
+
> decimal number \[00,99\].
71
+
>
72
+
> `%d`
73
+
> : Day of the month as a decimal number \[01,31\].
74
+
>
75
+
> `%D`
76
+
> : Date in the format *mm*/*dd*/*yy*.
77
+
>
78
+
> `%e`
79
+
> : Day of the month as a decimal number \[1,31\] in a two-digit field
80
+
> with leading \<space\> character fill.
81
+
>
82
+
> `%h`
83
+
> : A synonym for `%b`.
84
+
>
85
+
> `%H`
86
+
> : Hour (24-hour clock) as a decimal number \[00,23\].
87
+
>
88
+
> `%I`
89
+
> : Hour (12-hour clock) as a decimal number \[01,12\].
90
+
>
91
+
> `%j`
92
+
> : Day of the year as a decimal number \[001,366\].
93
+
>
94
+
> `%m`
95
+
> : Month as a decimal number \[01,12\].
96
+
>
97
+
> `%M`
98
+
> : Minute as a decimal number \[00,59\].
99
+
>
100
+
> `%n`
101
+
> : A \<newline\>.
102
+
>
103
+
> `%p`
104
+
> : Locale\'s equivalent of either AM or PM.
105
+
>
106
+
> `%r`
107
+
> : 12-hour clock time \[01,12\] using the AM/PM notation; in the
108
+
> POSIX locale, this shall be equivalent to `%I` : `%M` : `%S` `%p`.
109
+
>
110
+
> `%S`
111
+
> : Seconds as a decimal number \[00,60\].
112
+
>
113
+
> `%t`
114
+
> : A \<tab\>.
115
+
>
116
+
> `%T`
117
+
> : 24-hour clock time \[00,23\] in the format *HH*:*MM*:*SS*.
118
+
>
119
+
> `%u`
120
+
> : Weekday as a decimal number \[1,7\] (1=Monday).
121
+
>
122
+
> `%U`
123
+
> : Week of the year (Sunday as the first day of the week) as a
124
+
> decimal number \[00,53\]. All days in a new year preceding the
125
+
> first Sunday shall be considered to be in week 0.
126
+
>
127
+
> `%V`
128
+
> : Week of the year (Monday as the first day of the week) as a
129
+
> decimal number \[01,53\]. If the week containing January 1 has
130
+
> four or more days in the new year, then it shall be considered
131
+
> week 1; otherwise, it shall be the last week of the previous year,
132
+
> and the next week shall be week 1.
133
+
>
134
+
> `%w`
135
+
> : Weekday as a decimal number \[0,6\] (0=Sunday).
136
+
>
137
+
> `%W`
138
+
> : Week of the year (Monday as the first day of the week) as a
139
+
> decimal number \[00,53\]. All days in a new year preceding the
140
+
> first Monday shall be considered to be in week 0.
141
+
>
142
+
> `%x`
143
+
> : Locale\'s appropriate date representation.
144
+
>
145
+
> `%X`
146
+
> : Locale\'s appropriate time representation.
147
+
>
148
+
> `%y`
149
+
> : Year within century \[00,99\].
150
+
>
151
+
> `%Y`
152
+
> : Year with century as a decimal number.
153
+
>
154
+
> `%Z`
155
+
> : Timezone name, or no characters if no timezone is determinable.
156
+
>
157
+
> `%%`
158
+
> : A \<percent-sign\> character.
159
+
>
160
+
> See XBD [*LC_TIME*](../basedefs/V1_chap07.html#tag_07_03_05) for the
161
+
> conversion specifier values in the POSIX locale.
162
+
>
163
+
> ##### []{#tag_20_30_05_02}Modified Conversion Specifications
164
+
>
165
+
> Some conversion specifiers can be modified by the `E` and `O` modifier
166
+
> characters to indicate a different format or specification as
167
+
> specified in the *LC_TIME* locale description (see XBD
168
+
> [*LC_TIME*](../basedefs/V1_chap07.html#tag_07_03_05)). If the
169
+
> corresponding keyword (see **era**, **era_year**, **era_d_fmt**, and
170
+
> **alt_digits** in XBD
171
+
> [*LC_TIME*](../basedefs/V1_chap07.html#tag_07_03_05)) is not specified
172
+
> or not supported for the current locale, the unmodified conversion
173
+
> specifier value shall be used.
174
+
>
175
+
> `%Ec`
176
+
> : Locale\'s alternative appropriate date and time representation.
177
+
>
178
+
> `%EC`
179
+
> : The name of the base year (period) in the locale\'s alternative
180
+
> representation.
181
+
>
182
+
> `%Ex`
183
+
> : Locale\'s alternative date representation.
184
+
>
185
+
> `%EX`
186
+
> : Locale\'s alternative time representation.
187
+
>
188
+
> `%Ey`
189
+
> : Offset from `%EC` (year only) in the locale\'s alternative
190
+
> representation.
191
+
>
192
+
> `%EY`
193
+
> : Full alternative year representation.
194
+
>
195
+
> `%Od`
196
+
> : Day of month using the locale\'s alternative numeric symbols.
197
+
>
198
+
> `%Oe`
199
+
> : Day of month using the locale\'s alternative numeric symbols.
200
+
>
201
+
> `%OH`
202
+
> : Hour (24-hour clock) using the locale\'s alternative numeric
203
+
> symbols.
204
+
>
205
+
> `%OI`
206
+
> : Hour (12-hour clock) using the locale\'s alternative numeric
207
+
> symbols.
208
+
>
209
+
> `%Om`
210
+
> : Month using the locale\'s alternative numeric symbols.
211
+
>
212
+
> `%OM`
213
+
> : Minutes using the locale\'s alternative numeric symbols.
214
+
>
215
+
> `%OS`
216
+
> : Seconds using the locale\'s alternative numeric symbols.
217
+
>
218
+
> `%Ou`
219
+
> : Weekday as a number in the locale\'s alternative representation
220
+
> (Monday = 1).
221
+
>
222
+
> `%OU`
223
+
> : Week number of the year (Sunday as the first day of the week)
224
+
> using the locale\'s alternative numeric symbols.
225
+
>
226
+
> `%OV`
227
+
> : Week number of the year (Monday as the first day of the week,
228
+
> rules corresponding to `%V` ), using the locale\'s alternative
229
+
> numeric symbols.
230
+
>
231
+
> `%Ow`
232
+
> : Weekday as a number in the locale\'s alternative representation
233
+
> (Sunday = 0).
234
+
>
235
+
> `%OW`
236
+
> : Week number of the year (Monday as the first day of the week)
237
+
> using the locale\'s alternative numeric symbols.
238
+
>
239
+
> `%Oy`
240
+
> : Year (offset from `%C` ) in alternative representation.
241
+
>
242
+
> \
243
+
>
244
+
> *mmddhhmm***\[\[***cc***\]***yy***\]**
245
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
246
+
> Start\]](../images/opt-start.gif){border="0"}\
247
+
> Attempt to set the system date and time from the value given in
248
+
> the operand. This is only possible if the user has appropriate
249
+
> privileges and the system permits the setting of the system date
250
+
> and time. The first *mm* is the month (number); *dd* is the day
251
+
> (number); *hh* is the hour (number, 24-hour system); the second
252
+
> *mm* is the minute (number); *cc* is the century and is the first
253
+
> two digits of the year (this is optional); *yy* is the last two
254
+
> digits of the year and is optional. If century is not specified,
255
+
> then values in the range \[69,99\] shall refer to years 1969 to
256
+
> 1999 inclusive, and values in the range \[00,68\] shall refer to
257
+
> years 2000 to 2068 inclusive. The current year is the default if
258
+
> *yy* is omitted. ![\[Option
259
+
> End\]](../images/opt-end.gif){border="0"}
260
+
>
261
+
> **Note:**
262
+
> : It is expected that in a future version of this standard the
263
+
> default century inferred from a 2-digit year will change.
264
+
> (This would apply to all commands accepting a 2-digit year as
265
+
> input.)
266
+
267
+
#### []{#tag_20_30_06}STDIN {#stdin .mansect}
268
+
269
+
> Not used.
270
+
271
+
#### []{#tag_20_30_07}INPUT FILES {#input-files .mansect}
272
+
273
+
> None.
274
+
275
+
#### []{#tag_20_30_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
276
+
277
+
> The following environment variables shall affect the execution of
278
+
> *date*:
279
+
>
280
+
> *LANG*
281
+
> : Provide a default value for the internationalization variables
282
+
> that are unset or null. (See XBD [*Internationalization
283
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
284
+
> precedence of internationalization variables used to determine the
285
+
> values of locale categories.)
286
+
>
287
+
> *LC_ALL*
288
+
> : If set to a non-empty string value, override the values of all the
289
+
> other internationalization variables.
290
+
>
291
+
> *LC_CTYPE*
292
+
> : Determine the locale for the interpretation of sequences of bytes
293
+
> of text data as characters (for example, single-byte as opposed to
294
+
> multi-byte characters in arguments).
295
+
>
296
+
> *LC_MESSAGES*
297
+
> : Determine the locale that should be used to affect the format and
298
+
> contents of diagnostic messages written to standard error.
299
+
>
300
+
> *LC_TIME*
301
+
> : Determine the format and contents of date and time strings written
302
+
> by *date*.
303
+
>
304
+
> *NLSPATH*
305
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
306
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
307
+
> location of message catalogs for the processing of *LC_MESSAGES.*
308
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
309
+
>
310
+
> *TZ*
311
+
> : Determine the timezone in which the time and date are written,
312
+
> unless the **-u** option is specified. If the *TZ* variable is
313
+
> unset or null and **-u** is not specified, an unspecified system
314
+
> default timezone is used.
315
+
316
+
#### []{#tag_20_30_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
317
+
318
+
> Default.
319
+
320
+
#### []{#tag_20_30_10}STDOUT {#stdout .mansect}
321
+
322
+
> When no formatting operand is specified, the output in the POSIX
323
+
> locale shall be equivalent to specifying:
324
+
>
325
+
>
326
+
> date "+%a %b %e %H:%M:%S %Z %Y"
327
+
328
+
#### []{#tag_20_30_11}STDERR {#stderr .mansect}
329
+
330
+
> The standard error shall be used only for diagnostic messages.
331
+
332
+
#### []{#tag_20_30_12}OUTPUT FILES {#output-files .mansect}
333
+
334
+
> None.
335
+
336
+
#### []{#tag_20_30_13}EXTENDED DESCRIPTION {#extended-description .mansect}
337
+
338
+
> None.
339
+
340
+
#### []{#tag_20_30_14}EXIT STATUS {#exit-status .mansect}
341
+
342
+
> The following exit values shall be returned:
343
+
>
344
+
> 0
345
+
> : The date was written successfully.
346
+
>
347
+
> \>0
348
+
> : An error occurred.
349
+
350
+
#### []{#tag_20_30_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
351
+
352
+
> Default.
353
+
354
+
------------------------------------------------------------------------
355
+
356
+
::: box
357
+
*The following sections are informative.*
358
+
:::
359
+
360
+
#### []{#tag_20_30_16}APPLICATION USAGE {#application-usage .mansect}
361
+
362
+
> Conversion specifiers are of unspecified format when not in the POSIX
363
+
> locale. Some of them can contain \<newline\> characters in some
364
+
> locales, so it may be difficult to use the format shown in standard
365
+
> output for parsing the output of *date* in those locales.
366
+
>
367
+
> The range of values for `%S` extends from 0 to 60 seconds to
368
+
> accommodate the occasional leap second.
369
+
>
370
+
> Although certain of the conversion specifiers in the POSIX locale
371
+
> (such as the name of the month) are shown with initial capital
372
+
> letters, this need not be the case in other locales. Programs using
373
+
> these fields may need to adjust the capitalization if the output is
374
+
> going to be used at the beginning of a sentence.
375
+
>
376
+
> The date string formatting capabilities are intended for use in
377
+
> Gregorian-style calendars, possibly with a different starting year (or
378
+
> years). The `%x` and `%c` conversion specifications, however, are
379
+
> intended for local representation; these may be based on a different,
380
+
> non-Gregorian calendar.
381
+
>
382
+
> The `%C` conversion specification was introduced to allow a fallback
383
+
> for the `%EC` (alternative year format base year); it can be viewed as
384
+
> the base of the current subdivision in the Gregorian calendar. The
385
+
> century number is calculated as the year divided by 100 and truncated
386
+
> to an integer; it should not be confused with the use of ordinal
387
+
> numbers for centuries (for example, \"twenty-first century\".) Both
388
+
> the `%Ey` and `%y` can then be viewed as the offset from `%EC` and
389
+
> `%C`, respectively.
390
+
>
391
+
> The `E` and `O` modifiers modify the traditional conversion
392
+
> specifiers, so that they can always be used, even if the
393
+
> implementation (or the current locale) does not support the modifier.
394
+
>
395
+
> The `E` modifier supports alternative date formats, such as the
396
+
> Japanese Emperor\'s Era, as long as these are based on the Gregorian
397
+
> calendar system. Extending the `E` modifiers to other date elements
398
+
> may provide an implementation-defined extension capable of supporting
399
+
> other calendar systems, especially in combination with the `O`
400
+
> modifier.
401
+
>
402
+
> The `O` modifier supports time and date formats using the locale\'s
403
+
> alternative numerical symbols, such as Kanji or Hindi digits or
404
+
> ordinal number representation.
405
+
>
406
+
> Non-European locales, whether they use Latin digits in computational
407
+
> items or not, often have local forms of the digits for use in date
408
+
> formats. This is not totally unknown even in Europe; a variant of
409
+
> dates uses Roman numerals for the months: the third day of September
410
+
> 1991 would be written as 3.IX.1991. In Japan, Kanji digits are
411
+
> regularly used for dates; in Arabic-speaking countries, Hindi digits
412
+
> are used. The `%d`, `%e`, `%H`, `%I`, `%m`, `%S`, `%U`, `%w`, `%W`,
413
+
> and `%y` conversion specifications always return the date and time
414
+
> field in Latin digits (that is, 0 to 9). The `%O` modifier was
415
+
> introduced to support the use for display purposes of non-Latin
416
+
> digits. In the *LC_TIME* category in
417
+
> [*localedef*](../utilities/localedef.html), the optional
418
+
> **alt_digits** keyword is intended for this purpose. As an example,
419
+
> assume the following (partial)
420
+
> [*localedef*](../utilities/localedef.html) source:
421
+
>
422
+
>
423
+
> alt_digits "";"I";"II";"III";"IV";"V";"VI";"VII";"VIII" \
424
+
> "IX";"X";"XI";"XII"
425
+
> d_fmt "%e.%Om.%Y"
426
+
>
427
+
> With the above date, the command:
428
+
>
429
+
>
430
+
> date "+%x"
431
+
>
432
+
> would yield 3.IX.1991. With the same **d_fmt**, but without the
433
+
> **alt_digits**, the command would yield 3.9.1991.
434
+
435
+
#### []{#tag_20_30_17}EXAMPLES {#examples .mansect}
436
+
437
+
> 1. The following are input/output examples of *date* used at
438
+
> arbitrary times in the POSIX locale:
439
+
>
440
+
>
441
+
> $ date
442
+
> Tue Jun 26 09:58:10 PDT 1990
443
+
>
444
+
>
445
+
> $ date "+DATE: %m/%d/%y%nTIME: %H:%M:%S"
446
+
> DATE: 11/02/91
447
+
> TIME: 13:36:16
448
+
>
449
+
>
450
+
> $ date "+TIME: %r"
451
+
> TIME: 01:36:32 PM
452
+
>
453
+
> 2. Examples for Denmark, where the default date and time format is
454
+
> `%a` `%d` `%b` `%Y` `%T` `%Z` :
455
+
>
456
+
>
457
+
> $ LANG=da_DK.iso_8859-1 date
458
+
> ons 02 okt 1991 15:03:32 CET
459
+
>
460
+
>
461
+
> $ LANG=da_DK.iso_8859-1 \
462
+
> date "+DATO: %A den %e. %B %Y%nKLOKKEN: %H:%M:%S"
463
+
> DATO: onsdag den 2. oktober 1991
464
+
> KLOKKEN: 15:03:56
465
+
>
466
+
> 3. Examples for Germany, where the default date and time format is
467
+
> `%a` `%d`. `%h`. `%Y`, `%T` `%Z` :
468
+
>
469
+
>
470
+
> $ LANG=De_DE.88591 date
471
+
> Mi 02.Okt.1991, 15:01:21 MEZ
472
+
>
473
+
>
474
+
> $ LANG=De_DE.88591 date "+DATUM: %A, %d. %B %Y%nZEIT: %H:%M:%S"
475
+
> DATUM: Mittwoch, 02. Oktober 1991
476
+
> ZEIT: 15:02:02
477
+
>
478
+
> 4. Examples for France, where the default date and time format is
479
+
> `%a` `%d` `%h` `%Y` `%Z` `%T` :
480
+
>
481
+
>
482
+
> $ LANG=Fr_FR.88591 date
483
+
> Mer 02 oct 1991 MET 15:03:32
484
+
>
485
+
>
486
+
> $ LANG=Fr_FR.88591 date "+JOUR: %A %d %B %Y%nHEURE: %H:%M:%S"
487
+
> JOUR: Mercredi 02 octobre 1991
488
+
> HEURE: 15:03:56
489
+
490
+
#### []{#tag_20_30_18}RATIONALE {#rationale .mansect}
491
+
492
+
> Some of the new options for formatting are from the ISO C standard.
493
+
> The **-u** option was introduced to allow portable access to
494
+
> Coordinated Universal Time (UTC). The string `"GMT0"` is allowed as an
495
+
> equivalent *TZ* value to be compatible with all of the systems using
496
+
> the BSD implementation, where this option originated.
497
+
>
498
+
> The `%e` format conversion specification (adopted from System V) was
499
+
> added because the ISO C standard conversion specifications did not
500
+
> provide any way to produce the historical default *date* output during
501
+
> the first nine days of any month.
502
+
>
503
+
> There are two varieties of day and week numbering supported (in
504
+
> addition to any others created with the locale-dependent `%E` and `%O`
505
+
> modifier characters):
506
+
>
507
+
> - The historical variety in which Sunday is the first day of the week
508
+
> and the weekdays preceding the first Sunday of the year are
509
+
> considered week 0. These are represented by `%w` and `%U`. A variant
510
+
> of this is `%W`, using Monday as the first day of the week, but
511
+
> still referring to week 0. This view of the calendar was retained
512
+
> because so many historical applications depend on it and the ISO C
513
+
> standard [*strftime*()](../functions/strftime.html) function, on
514
+
> which many *date* implementations are based, was defined in this
515
+
> way.
516
+
>
517
+
> - The international standard, based on the ISO 8601:2000 standard
518
+
> where Monday is the first weekday and the algorithm for the first
519
+
> week number is more complex: If the week (Monday to Sunday)
520
+
> containing January 1 has four or more days in the new year, then it
521
+
> is week 1; otherwise, it is week 53 of the previous year, and the
522
+
> next week is week 1. These are represented by the new conversion
523
+
> specifications `%u` and `%V`, added as a result of international
524
+
> comments.
525
+
526
+
#### []{#tag_20_30_19}FUTURE DIRECTIONS {#future-directions .mansect}
527
+
528
+
> None.
529
+
530
+
#### []{#tag_20_30_20}SEE ALSO {#see-also .mansect}
531
+
532
+
> XBD [*LC_TIME*](../basedefs/V1_chap07.html#tag_07_03_05),
533
+
> [*Environment Variables*](../basedefs/V1_chap08.html#tag_08),
534
+
> [*Utility Syntax Guidelines*](../basedefs/V1_chap12.html#tag_12_02)
535
+
>
536
+
> XSH [*fprintf*](../functions/fprintf.html#),
537
+
> [*strftime*](../functions/strftime.html#)
538
+
539
+
#### []{#tag_20_30_21}CHANGE HISTORY {#change-history .mansect}
540
+
541
+
> First released in Issue 2.
542
+
543
+
#### []{#tag_20_30_22}Issue 5 {#issue-5 .mansect}
544
+
545
+
> Changes are made for Year 2000 alignment.
546
+
547
+
#### []{#tag_20_30_23}Issue 6 {#issue-6 .mansect}
548
+
549
+
> The following new requirements on POSIX implementations derive from
550
+
> alignment with the Single UNIX Specification:
551
+
>
552
+
> - The `%EX` modified conversion specification is added.
553
+
>
554
+
> The Open Group Corrigendum U048/2 is applied, correcting the examples.
555
+
>
556
+
> The DESCRIPTION is updated to refer to conversion specifications,
557
+
> instead of field descriptors for consistency with the *LC_TIME*
558
+
> category.
559
+
>
560
+
> A clarification is made such that the current year is the default if
561
+
> the *yy* argument is omitted when setting the system date and time.
562
+
>
563
+
> IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/19 is applied,
564
+
> correcting the CHANGE HISTORY section.
565
+
+304
docs/posix2018/df.md
+304
docs/posix2018/df.md
···
1
+
#### []{#tag_20_33_01}NAME {#name .mansect}
2
+
3
+
> df - report free disk space
4
+
5
+
#### []{#tag_20_33_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> ^`[`[`XSI`](javascript:open_code('XSI'))`]`^` df`` `**`[`**`-k`**`] [`**`-P|`{border="0"}`-t`**{border="0"}`] [`***`file`*`...`**`]`**
8
+
9
+
#### []{#tag_20_33_03}DESCRIPTION {#description .mansect}
10
+
11
+
> The *df* utility shall write the amount of available space
12
+
> ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
13
+
> Start\]](../images/opt-start.gif){border="0"} and file slots
14
+
> ![\[Option End\]](../images/opt-end.gif){border="0"} for file systems
15
+
> on which the invoking user has appropriate read access. File systems
16
+
> shall be specified by the *file* operands; when none are specified,
17
+
> information shall be written for all file systems. The format of the
18
+
> default output from *df* is unspecified, but all space figures are
19
+
> reported in 512-byte units, unless the **-k** option is specified.
20
+
> This output shall contain at least the file system names, amount of
21
+
> available space on each of these file systems,
22
+
> ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
23
+
> Start\]](../images/opt-start.gif){border="0"} and, if no options
24
+
> other than **-t** are specified, the number of free file slots, or
25
+
> *inode*s, available; when **-t** is specified, the output shall
26
+
> contain the total allocated space as well. ![\[Option
27
+
> End\]](../images/opt-end.gif){border="0"}
28
+
29
+
#### []{#tag_20_33_04}OPTIONS {#options .mansect}
30
+
31
+
> The *df* utility shall conform to XBD [*Utility Syntax
32
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02) .
33
+
>
34
+
> The following options shall be supported:
35
+
>
36
+
> **-k**
37
+
> : Use 1024-byte units, instead of the default 512-byte units, when
38
+
> writing space figures.
39
+
>
40
+
> **-P**
41
+
> : Produce output in the format described in the STDOUT section.
42
+
>
43
+
> **-t**
44
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
45
+
> Start\]](../images/opt-start.gif){border="0"} Include total
46
+
> allocated-space figures in the output. ![\[Option
47
+
> End\]](../images/opt-end.gif){border="0"}
48
+
49
+
#### []{#tag_20_33_05}OPERANDS {#operands .mansect}
50
+
51
+
> The following operand shall be supported:
52
+
>
53
+
> *file*
54
+
> : A pathname of a file within the hierarchy of the desired file
55
+
> system. If a file other than a FIFO, a regular file, a directory,
56
+
> ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
57
+
> Start\]](../images/opt-start.gif){border="0"} or a special file
58
+
> representing the device containing the file system (for example,
59
+
> **/dev/dsk/0s1**) ![\[Option
60
+
> End\]](../images/opt-end.gif){border="0"} is specified, the
61
+
> results are unspecified. If the *file* operand names a file other
62
+
> than a special file containing a file system, *df* shall write the
63
+
> amount of free space in the file system containing the specified
64
+
> *file* operand. ^\[[XSI](javascript:open_code('XSI'))\]^
65
+
> ![\[Option Start\]](../images/opt-start.gif){border="0"}
66
+
> Otherwise, *df* shall write the amount of free space in that file
67
+
> system. ![\[Option End\]](../images/opt-end.gif){border="0"}
68
+
69
+
#### []{#tag_20_33_06}STDIN {#stdin .mansect}
70
+
71
+
> Not used.
72
+
73
+
#### []{#tag_20_33_07}INPUT FILES {#input-files .mansect}
74
+
75
+
> None.
76
+
77
+
#### []{#tag_20_33_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
78
+
79
+
> The following environment variables shall affect the execution of
80
+
> *df*:
81
+
>
82
+
> *LANG*
83
+
> : Provide a default value for the internationalization variables
84
+
> that are unset or null. (See XBD [*Internationalization
85
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
86
+
> precedence of internationalization variables used to determine the
87
+
> values of locale categories.)
88
+
>
89
+
> *LC_ALL*
90
+
> : If set to a non-empty string value, override the values of all the
91
+
> other internationalization variables.
92
+
>
93
+
> *LC_CTYPE*
94
+
> : Determine the locale for the interpretation of sequences of bytes
95
+
> of text data as characters (for example, single-byte as opposed to
96
+
> multi-byte characters in arguments).
97
+
>
98
+
> *LC_MESSAGES*
99
+
> : Determine the locale that should be used to affect the format and
100
+
> contents of diagnostic messages written to standard error and
101
+
> informative messages written to standard output.
102
+
>
103
+
> *NLSPATH*
104
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
105
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
106
+
> location of message catalogs for the processing of *LC_MESSAGES.*
107
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
108
+
109
+
#### []{#tag_20_33_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
110
+
111
+
> Default.
112
+
113
+
#### []{#tag_20_33_10}STDOUT {#stdout .mansect}
114
+
115
+
> When both the **-k** and **-P** options are specified, the following
116
+
> header line shall be written (in the POSIX locale):
117
+
>
118
+
>
119
+
> "Filesystem 1024-blocks Used Available Capacity Mounted on\n"
120
+
>
121
+
> When the **-P** option is specified without the **-k** option, the
122
+
> following header line shall be written (in the POSIX locale):
123
+
>
124
+
>
125
+
> "Filesystem 512-blocks Used Available Capacity Mounted on\n"
126
+
>
127
+
> The implementation may adjust the spacing of the header line and the
128
+
> individual data lines so that the information is presented in orderly
129
+
> columns.
130
+
>
131
+
> The remaining output with **-P** shall consist of one line of
132
+
> information for each specified file system. These lines shall be
133
+
> formatted as follows:
134
+
>
135
+
>
136
+
> "%s %d %d %d %d%% %s\n", <file system name>, <total space>,
137
+
> <space used>, <space free>, <percentage used>,
138
+
> <file system root>
139
+
>
140
+
> In the following list, all quantities expressed in 512-byte units
141
+
> (1024-byte when **-k** is specified) shall be rounded up to the next
142
+
> higher unit. The fields are:
143
+
>
144
+
> \<*file system name*\>
145
+
> : The name of the file system, in an implementation-defined format.
146
+
>
147
+
> \<*total space*\>
148
+
> : The total size of the file system in 512-byte units. The exact
149
+
> meaning of this figure is implementation-defined, but should
150
+
> include \<*space used*\>, \<*space free*\>, plus any space
151
+
> reserved by the system not normally available to a user.
152
+
>
153
+
> \<*space used*\>
154
+
> : The total amount of space allocated to existing files in the file
155
+
> system, in 512-byte units.
156
+
>
157
+
> \<*space free*\>
158
+
> : The total amount of space available within the file system for the
159
+
> creation of new files by unprivileged users, in 512-byte units.
160
+
> When this figure is less than or equal to zero, it shall not be
161
+
> possible to create any new files on the file system without first
162
+
> deleting others, unless the process has appropriate privileges.
163
+
> The figure written may be less than zero.
164
+
>
165
+
> \<*percentage used*\>
166
+
>
167
+
> : The percentage of the normally available space that is currently
168
+
> allocated to all files on the file system. This shall be
169
+
> calculated using the fraction:
170
+
>
171
+
>
172
+
> <space used>/( <space used>+ <space free>)
173
+
>
174
+
> expressed as a percentage. This percentage may be greater than 100
175
+
> if \<*space free*\> is less than zero. The percentage value shall
176
+
> be expressed as a positive integer, with any fractional result
177
+
> causing it to be rounded to the next highest integer.
178
+
>
179
+
> \<*file system root*\>
180
+
> : The directory below which the file system hierarchy appears.
181
+
>
182
+
> ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
183
+
> Start\]](../images/opt-start.gif){border="0"} The output format is
184
+
> unspecified when **-t** is used. ![\[Option
185
+
> End\]](../images/opt-end.gif){border="0"}
186
+
187
+
#### []{#tag_20_33_11}STDERR {#stderr .mansect}
188
+
189
+
> The standard error shall be used only for diagnostic messages.
190
+
191
+
#### []{#tag_20_33_12}OUTPUT FILES {#output-files .mansect}
192
+
193
+
> None.
194
+
195
+
#### []{#tag_20_33_13}EXTENDED DESCRIPTION {#extended-description .mansect}
196
+
197
+
> None.
198
+
199
+
#### []{#tag_20_33_14}EXIT STATUS {#exit-status .mansect}
200
+
201
+
> The following exit values shall be returned:
202
+
>
203
+
> 0
204
+
> : Successful completion.
205
+
>
206
+
> \>0
207
+
> : An error occurred.
208
+
209
+
#### []{#tag_20_33_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
210
+
211
+
> Default.
212
+
213
+
------------------------------------------------------------------------
214
+
215
+
::: box
216
+
*The following sections are informative.*
217
+
:::
218
+
219
+
#### []{#tag_20_33_16}APPLICATION USAGE {#application-usage .mansect}
220
+
221
+
> On most systems, the \"name of the file system, in an
222
+
> implementation-defined format\" is the special file on which the file
223
+
> system is mounted.
224
+
>
225
+
> On large file systems, the calculation specified for percentage used
226
+
> can create huge rounding errors.
227
+
228
+
#### []{#tag_20_33_17}EXAMPLES {#examples .mansect}
229
+
230
+
> 1. The following example writes portable information about the
231
+
> **/usr** file system:
232
+
>
233
+
>
234
+
> df -P /usr
235
+
>
236
+
> 2. Assuming that **/usr/src** is part of the **/usr** file system,
237
+
> the following produces the same output as the previous example:
238
+
>
239
+
>
240
+
> df -P /usr/src
241
+
242
+
#### []{#tag_20_33_18}RATIONALE {#rationale .mansect}
243
+
244
+
> The behavior of *df* with the **-P** option is the default action of
245
+
> the 4.2 BSD *df* utility. The uppercase **-P** was selected to avoid
246
+
> collision with a known industry extension using **-p**.
247
+
>
248
+
> Historical *df* implementations vary considerably in their default
249
+
> output. It was therefore necessary to describe the default output in a
250
+
> loose manner to accommodate all known historical implementations and
251
+
> to add a portable option (**-P**) to provide information in a portable
252
+
> format.
253
+
>
254
+
> The use of 512-byte units is historical practice and maintains
255
+
> compatibility with [*ls*](../utilities/ls.html) and other utilities in
256
+
> this volume of POSIX.1-2017. This does not mandate that the file
257
+
> system itself be based on 512-byte blocks. The **-k** option was added
258
+
> as a compromise measure. It was agreed by the standard developers that
259
+
> 512 bytes was the best default unit because of its complete historical
260
+
> consistency on System V (*versus* the mixed 512/1024-byte usage on BSD
261
+
> systems), and that a **-k** option to switch to 1024-byte units was a
262
+
> good compromise. Users who prefer the more logical 1024-byte quantity
263
+
> can easily alias *df* to *df* **-k** without breaking many historical
264
+
> scripts relying on the 512-byte units.
265
+
>
266
+
> It was suggested that *df* and the various related utilities be
267
+
> modified to access a *BLOCKSIZE* environment variable to achieve
268
+
> consistency and user acceptance. Since this is not historical practice
269
+
> on any system, it is left as a possible area for system extensions and
270
+
> will be re-evaluated in a future version if it is widely implemented.
271
+
272
+
#### []{#tag_20_33_19}FUTURE DIRECTIONS {#future-directions .mansect}
273
+
274
+
> None.
275
+
276
+
#### []{#tag_20_33_20}SEE ALSO {#see-also .mansect}
277
+
278
+
> [*find*](../utilities/find.html#)
279
+
>
280
+
> XBD [*Environment Variables*](../basedefs/V1_chap08.html#tag_08),
281
+
> [*Utility Syntax Guidelines*](../basedefs/V1_chap12.html#tag_12_02)
282
+
283
+
#### []{#tag_20_33_21}CHANGE HISTORY {#change-history .mansect}
284
+
285
+
> First released in Issue 2.
286
+
287
+
#### []{#tag_20_33_22}Issue 6 {#issue-6 .mansect}
288
+
289
+
> This utility is marked as part of the User Portability Utilities
290
+
> option.
291
+
292
+
#### []{#tag_20_33_23}Issue 7 {#issue-7 .mansect}
293
+
294
+
> Austin Group Interpretation 1003.1-2001 #099 is applied.
295
+
>
296
+
> The *df* utility is removed from the User Portability Utilities
297
+
> option. User Portability Utilities is now an option for interactive
298
+
> utilities.
299
+
>
300
+
> SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.
301
+
>
302
+
> POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0082 \[156\] is
303
+
> applied.
304
+
+702
docs/posix2018/diff.md
+702
docs/posix2018/diff.md
···
1
+
#### []{#tag_20_34_01}NAME {#name .mansect}
2
+
3
+
> diff - compare two files
4
+
5
+
#### []{#tag_20_34_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `diff`` `**`[`**`-c|-e|-f|-u|-C`` `*`n`*`|-U`` `*`n`***`] [`**`-br`**`]`**` `*`file1 file2`*
8
+
9
+
#### []{#tag_20_34_03}DESCRIPTION {#description .mansect}
10
+
11
+
> The *diff* utility shall compare the contents of *file1* and *file2*
12
+
> and write to standard output a list of changes necessary to convert
13
+
> *file1* into *file2*. This list should be minimal. No output shall be
14
+
> produced if the files are identical.
15
+
16
+
#### []{#tag_20_34_04}OPTIONS {#options .mansect}
17
+
18
+
> The *diff* utility shall conform to XBD [*Utility Syntax
19
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02) .
20
+
>
21
+
> The following options shall be supported:
22
+
>
23
+
> **-b**
24
+
> : Cause any amount of white space at the end of a line to be treated
25
+
> as a single \<newline\> (that is, the white-space characters
26
+
> preceding the \<newline\> are ignored) and other strings of
27
+
> white-space characters, not including \<newline\> characters, to
28
+
> compare equal.
29
+
>
30
+
> **-c**
31
+
> : Produce output in a form that provides three lines of copied
32
+
> context.
33
+
>
34
+
> **-C ** *n*
35
+
> : Produce output in a form that provides *n* lines of copied context
36
+
> (where *n* shall be interpreted as a positive decimal integer).
37
+
>
38
+
> **-e**
39
+
> : Produce output in a form suitable as input for the
40
+
> [*ed*](../utilities/ed.html) utility, which can then be used to
41
+
> convert *file1* into *file2*.
42
+
>
43
+
> **-f**
44
+
> : Produce output in an alternative form, similar in format to
45
+
> **-e**, but not intended to be suitable as input for the
46
+
> [*ed*](../utilities/ed.html) utility, and in the opposite order.
47
+
>
48
+
> **-r**
49
+
>
50
+
> : Apply *diff* recursively to files and directories of the same name
51
+
> when *file1* and *file2* are both directories.
52
+
>
53
+
> The *diff* utility shall detect infinite loops; that is, entering
54
+
> a previously visited directory that is an ancestor of the last
55
+
> file encountered. When it detects an infinite loop, *diff* shall
56
+
> write a diagnostic message to standard error and shall either
57
+
> recover its position in the hierarchy or terminate.
58
+
>
59
+
> **-u**
60
+
> : Produce output in a form that provides three lines of unified
61
+
> context.
62
+
>
63
+
> **-U ** *n*
64
+
> : Produce output in a form that provides *n* lines of unified
65
+
> context (where *n* shall be interpreted as a non-negative decimal
66
+
> integer).
67
+
68
+
#### []{#tag_20_34_05}OPERANDS {#operands .mansect}
69
+
70
+
> The following operands shall be supported:
71
+
>
72
+
> *file1*, *file2*
73
+
> : A pathname of a file to be compared. If either the *file1* or
74
+
> *file2* operand is `'-'`, the standard input shall be used in its
75
+
> place.
76
+
>
77
+
> If both *file1* and *file2* are directories, *diff* shall not compare
78
+
> block special files, character special files, or FIFO special files to
79
+
> any files and shall not compare regular files to directories. Further
80
+
> details are as specified in [Diff Directory Comparison
81
+
> Format](#tag_20_34_10_01). The behavior of *diff* on other file types
82
+
> is implementation-defined when found in directories.
83
+
>
84
+
> If only one of *file1* and *file2* is a directory, *diff* shall be
85
+
> applied to the non-directory file and the file contained in the
86
+
> directory file with a filename that is the same as the last component
87
+
> of the non-directory file.
88
+
89
+
#### []{#tag_20_34_06}STDIN {#stdin .mansect}
90
+
91
+
> The standard input shall be used only if one of the *file1* or *file2*
92
+
> operands references standard input. See the INPUT FILES section.
93
+
94
+
#### []{#tag_20_34_07}INPUT FILES {#input-files .mansect}
95
+
96
+
> The input files may be of any type.
97
+
98
+
#### []{#tag_20_34_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
99
+
100
+
> The following environment variables shall affect the execution of
101
+
> *diff*:
102
+
>
103
+
> *LANG*
104
+
> : Provide a default value for the internationalization variables
105
+
> that are unset or null. (See XBD [*Internationalization
106
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
107
+
> precedence of internationalization variables used to determine the
108
+
> values of locale categories.)
109
+
>
110
+
> *LC_ALL*
111
+
> : If set to a non-empty string value, override the values of all the
112
+
> other internationalization variables.
113
+
>
114
+
> *LC_CTYPE*
115
+
> : Determine the locale for the interpretation of sequences of bytes
116
+
> of text data as characters (for example, single-byte as opposed to
117
+
> multi-byte characters in arguments and input files).
118
+
>
119
+
> *LC_MESSAGES*
120
+
> : Determine the locale that should be used to affect the format and
121
+
> contents of diagnostic messages written to standard error and
122
+
> informative messages written to standard output.
123
+
>
124
+
> *LC_TIME*
125
+
> : Determine the locale for affecting the format of file timestamps
126
+
> written with the **-C** and **-c** options.
127
+
>
128
+
> *NLSPATH*
129
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
130
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
131
+
> location of message catalogs for the processing of *LC_MESSAGES.*
132
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
133
+
>
134
+
> *TZ*
135
+
> : Determine the timezone used for calculating file timestamps
136
+
> written with a context format. If *TZ* is unset or null, an
137
+
> unspecified default timezone shall be used.
138
+
139
+
#### []{#tag_20_34_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
140
+
141
+
> Default.
142
+
143
+
#### []{#tag_20_34_10}STDOUT {#stdout .mansect}
144
+
145
+
> ##### []{#tag_20_34_10_01}Diff Directory Comparison Format
146
+
>
147
+
> If both *file1* and *file2* are directories, the following output
148
+
> formats shall be used.
149
+
>
150
+
> In the POSIX locale, each file that is present in only one directory
151
+
> shall be reported using the following format:
152
+
>
153
+
>
154
+
> "Only in %s: %s\n", <directory pathname>, <filename>
155
+
>
156
+
> In the POSIX locale, subdirectories that are common to the two
157
+
> directories may be reported with the following format:
158
+
>
159
+
>
160
+
> "Common subdirectories: %s and %s\n", <directory1 pathname>,
161
+
> <directory2 pathname>
162
+
>
163
+
> For each file common to the two directories, if the two files are not
164
+
> to be compared: if the two files have the same device ID and file
165
+
> serial number, or are both block special files that refer to the same
166
+
> device, or are both character special files that refer to the same
167
+
> device, in the POSIX locale the output format is unspecified.
168
+
> Otherwise, in the POSIX locale an unspecified format shall be used
169
+
> that contains the pathnames of the two files.
170
+
>
171
+
> For each file common to the two directories, if the files are compared
172
+
> and are identical, no output shall be written. If the two files
173
+
> differ, the following format is written:
174
+
>
175
+
>
176
+
> "diff %s %s %s\n", <diff_options>, <filename1>, <filename2>
177
+
>
178
+
> where \<*diff_options*\> are the options as specified on the command
179
+
> line.
180
+
>
181
+
> All directory pathnames listed in this section shall be relative to
182
+
> the original command line arguments. All other names of files listed
183
+
> in this section shall be filenames (pathname components).
184
+
>
185
+
> ##### []{#tag_20_34_10_02}Diff Binary Output Format
186
+
>
187
+
> In the POSIX locale, if one or both of the files being compared are
188
+
> not text files, it is implementation-defined whether *diff* uses the
189
+
> binary file output format or the other formats as specified below. The
190
+
> binary file output format shall contain the pathnames of two files
191
+
> being compared and the string `"differ"`.
192
+
>
193
+
> If both files being compared are text files, depending on the options
194
+
> specified, one of the following formats shall be used to write the
195
+
> differences.
196
+
>
197
+
> ##### []{#tag_20_34_10_03}Diff Default Output Format
198
+
>
199
+
> The default (without **-e**, **-f**, **-c**, **-C**, **-u**, or **-U**
200
+
> options) *diff* utility output shall contain lines of these forms:
201
+
>
202
+
>
203
+
> "%da%d\n", <num1>, <num2>
204
+
>
205
+
>
206
+
> "%da%d,%d\n", <num1>, <num2>, <num3>
207
+
>
208
+
>
209
+
> "%dd%d\n", <num1>, <num2>
210
+
>
211
+
>
212
+
> "%d,%dd%d\n", <num1>, <num2>, <num3>
213
+
>
214
+
>
215
+
> "%dc%d\n", <num1>, <num2>
216
+
>
217
+
>
218
+
> "%d,%dc%d\n", <num1>, <num2>, <num3>
219
+
>
220
+
>
221
+
> "%dc%d,%d\n", <num1>, <num2>, <num3>
222
+
>
223
+
>
224
+
> "%d,%dc%d,%d\n", <num1>, <num2>, <num3>, <num4>
225
+
>
226
+
> These lines resemble [*ed*](../utilities/ed.html) subcommands to
227
+
> convert *file1* into *file2*. The line numbers before the action
228
+
> letters shall pertain to *file1*; those after shall pertain to
229
+
> *file2*. Thus, by exchanging *a* for *d* and reading the line in
230
+
> reverse order, one can also determine how to convert *file2* into
231
+
> *file1*. As in [*ed*](../utilities/ed.html), identical pairs (where
232
+
> *num1*= *num2*) are abbreviated as a single number.
233
+
>
234
+
> Following each of these lines, *diff* shall write to standard output
235
+
> all lines affected in the first file using the format:
236
+
>
237
+
>
238
+
> "<%s", <line>
239
+
>
240
+
> and all lines affected in the second file using the format:
241
+
>
242
+
>
243
+
> ">%s", <line>
244
+
>
245
+
> If there are lines affected in both *file1* and *file2* (as with the
246
+
> **c** subcommand), the changes are separated with a line consisting of
247
+
> three \<hyphen-minus\> characters:
248
+
>
249
+
>
250
+
> "---\n"
251
+
>
252
+
> ##### []{#tag_20_34_10_04}Diff -e Output Format
253
+
>
254
+
> With the **-e** option, a script shall be produced that shall, when
255
+
> provided as input to [*ed*](../utilities/ed.html), along with an
256
+
> appended **w** (write) command, convert *file1* into *file2*. Only the
257
+
> **a** (append), **c** (change), **d** (delete), **i** (insert), and
258
+
> **s** (substitute) commands of [*ed*](../utilities/ed.html) shall be
259
+
> used in this script. Text lines, except those consisting of the single
260
+
> character \<period\> ( `'.'` ), shall be output as they appear in the
261
+
> file.
262
+
>
263
+
> ##### []{#tag_20_34_10_05}Diff -f Output Format
264
+
>
265
+
> With the **-f** option, an alternative format of script shall be
266
+
> produced. It is similar to that produced by **-e**, with the following
267
+
> differences:
268
+
>
269
+
> 1. It is expressed in reverse sequence; the output of **-e** orders
270
+
> changes from the end of the file to the beginning; the **-f** from
271
+
> beginning to end.
272
+
>
273
+
> 2. The command form \<*lines*\> \<*command-letter*\> used by **-e**
274
+
> is reversed. For example, 10*c* with **-e** would be *c*10 with
275
+
> **-f**.
276
+
>
277
+
> 3. The form used for ranges of line numbers is \<space\>-separated,
278
+
> rather than \<comma\>-separated.
279
+
>
280
+
> ##### []{#tag_20_34_10_06}Diff -c or -C Output Format
281
+
>
282
+
> With the **-c** or **-C** option, the output format shall consist of
283
+
> affected lines along with surrounding lines of context. The affected
284
+
> lines shall show which ones need to be deleted or changed in *file1*,
285
+
> and those added from *file2*. With the **-c** option, three lines of
286
+
> context, if available, shall be written before and after the affected
287
+
> lines. With the **-C** option, the user can specify how many lines of
288
+
> context are written. The exact format follows.
289
+
>
290
+
> The name and last modification time of each file shall be output in
291
+
> the following format:
292
+
>
293
+
>
294
+
> "*** %s %s\n", file1, <file1 timestamp>
295
+
> "--- %s %s\n", file2, <file2 timestamp>
296
+
>
297
+
> Each \<*file*\> field shall be the pathname of the corresponding file
298
+
> being compared. The pathname written for standard input is
299
+
> unspecified.
300
+
>
301
+
> In the POSIX locale, each \<*timestamp*\> field shall be equivalent to
302
+
> the output from the following command:
303
+
>
304
+
>
305
+
> date "+%a %b %e %T %Y"
306
+
>
307
+
> without the trailing \<newline\>, executed at the time of last
308
+
> modification of the corresponding file (or the current time, if the
309
+
> file is standard input).
310
+
>
311
+
> Then, the following output formats shall be applied for every set of
312
+
> changes.
313
+
>
314
+
> First, a line shall be written in the following format:
315
+
>
316
+
>
317
+
> "***************\n"
318
+
>
319
+
> Next, the range of lines in *file1* shall be written in the following
320
+
> format if the range contains two or more lines:
321
+
>
322
+
>
323
+
> "*** %d,%d ****\n", <beginning line number>, <ending line number>
324
+
>
325
+
> and the following format otherwise:
326
+
>
327
+
>
328
+
> "*** %d ****\n", <ending line number>
329
+
>
330
+
> The ending line number of an empty range shall be the number of the
331
+
> preceding line, or 0 if the range is at the start of the file.
332
+
>
333
+
> Next, the affected lines along with lines of context (unaffected
334
+
> lines) shall be written. Unaffected lines shall be written in the
335
+
> following format:
336
+
>
337
+
>
338
+
> "%s", <unaffected_line>
339
+
>
340
+
> Deleted lines shall be written as:
341
+
>
342
+
>
343
+
> "-%s", <deleted_line>
344
+
>
345
+
> Changed lines shall be written as:
346
+
>
347
+
>
348
+
> "!%s", <changed_line>
349
+
>
350
+
> Next, the range of lines in *file2* shall be written in the following
351
+
> format if the range contains two or more lines:
352
+
>
353
+
>
354
+
> "--- %d,%d ----\n", <beginning line number>, <ending line number>
355
+
>
356
+
> and the following format otherwise:
357
+
>
358
+
>
359
+
> "--- %d ----\n", <ending line number>
360
+
>
361
+
> Then, lines of context and changed lines shall be written as described
362
+
> in the previous formats. Lines added from *file2* shall be written in
363
+
> the following format:
364
+
>
365
+
>
366
+
> "+%s", <added_line>
367
+
>
368
+
> ##### []{#tag_20_34_10_07}Diff -u or -U Output Format
369
+
>
370
+
> The **-u** or **-U** options behave like the **-c** or **-C** options,
371
+
> except that the context lines are not repeated; instead, the context,
372
+
> deleted, and added lines are shown together, interleaved. The exact
373
+
> format follows.
374
+
>
375
+
> The name and last modification time of each file shall be output in
376
+
> the following format:
377
+
>
378
+
>
379
+
> "---%s\t%s%s%s\n", file1, <file1 timestamp>, <file1 frac>, <file1 zone>
380
+
> "+++%s\t%s%s%s\n", file2, <file2 timestamp>, <file2 frac>, <file2 zone>
381
+
>
382
+
> Each \<*file*\> field shall be the pathname of the corresponding file
383
+
> being compared, or the single character `'-'` if standard input is
384
+
> being compared. However, if the pathname contains a \<tab\> or a
385
+
> \<newline\>, or if it does not consist entirely of characters taken
386
+
> from the portable character set, the behavior is
387
+
> implementation-defined.
388
+
>
389
+
> Each \<*timestamp*\> field shall be equivalent to the output from the
390
+
> following command:
391
+
>
392
+
>
393
+
> date '+%Y-%m-%d%H:%M:%S'
394
+
>
395
+
> without the trailing \<newline\>, executed at the time of last
396
+
> modification of the corresponding file (or the current time, if the
397
+
> file is standard input).
398
+
>
399
+
> Each \<*frac*\> field shall be either empty, or a decimal point
400
+
> followed by at least one decimal digit, indicating the
401
+
> fractional-seconds part (if any) of the file timestamp. The number of
402
+
> fractional digits shall be at least the number needed to represent the
403
+
> file\'s timestamp without loss of information.
404
+
>
405
+
> Each \<*zone*\> field shall be of the form `"shhmm"`, where `"shh"` is
406
+
> a signed two-digit decimal number in the range -24 through +25, and
407
+
> `"mm"` is an unsigned two-digit decimal number in the range 00 through
408
+
> 59. It represents the timezone of the timestamp as the number of hours
409
+
> (hh) and minutes (mm) east (+) or west (-) of UTC for the timestamp.
410
+
> If the hours and minutes are both zero, the sign shall be `'+'`.
411
+
> However, if the timezone is not an integral number of minutes away
412
+
> from UTC, the \<*zone*\> field is implementation-defined.
413
+
>
414
+
> Then, the following output formats shall be applied for every set of
415
+
> changes.
416
+
>
417
+
> First, the range of lines in each file shall be written in the
418
+
> following format:
419
+
>
420
+
>
421
+
> "@@-%s+%s@@", <file1 range>, <file2 range>
422
+
>
423
+
> Each \<*range*\> field shall be of the form:
424
+
>
425
+
>
426
+
> "%1d", <beginning line number>
427
+
>
428
+
> or:
429
+
>
430
+
>
431
+
> "%1d,1", <beginning line number>
432
+
>
433
+
> if the range contains exactly one line, and:
434
+
>
435
+
>
436
+
> "%1d,%1d", <beginning line number>, <number of lines>
437
+
>
438
+
> otherwise. If a range is empty, its beginning line number shall be the
439
+
> number of the line just before the range, or 0 if the empty range
440
+
> starts the file.
441
+
>
442
+
> Next, the affected lines along with lines of context shall be written.
443
+
> Each non-empty unaffected line shall be written in the following
444
+
> format:
445
+
>
446
+
>
447
+
> "%s", <unaffected_line>
448
+
>
449
+
> where the contents of the unaffected line shall be taken from *file1*.
450
+
> It is implementation-defined whether an empty unaffected line is
451
+
> written as an empty line or a line containing a single \<space\>
452
+
> character. This line also represents the same line of *file2*, even
453
+
> though *file2*\'s line may contain different contents due to the
454
+
> **-b**. Deleted lines shall be written as:
455
+
>
456
+
>
457
+
> "-%s", <deleted_line>
458
+
>
459
+
> Added lines shall be written as:
460
+
>
461
+
>
462
+
> "+%s", <added_line>
463
+
>
464
+
> The order of lines written shall be the same as that of the
465
+
> corresponding file. A deleted line shall never be written immediately
466
+
> after an added line.
467
+
>
468
+
> If **-U** *n* is specified, the output shall contain no more than 2
469
+
> *n* consecutive unaffected lines; and if the output contains an
470
+
> affected line and this line is adjacent to up to *n* consecutive
471
+
> unaffected lines in the corresponding file, the output shall contain
472
+
> these unaffected lines. **-u** shall act like **-U**3.
473
+
474
+
#### []{#tag_20_34_11}STDERR {#stderr .mansect}
475
+
476
+
> The standard error shall be used only for diagnostic messages.
477
+
478
+
#### []{#tag_20_34_12}OUTPUT FILES {#output-files .mansect}
479
+
480
+
> None.
481
+
482
+
#### []{#tag_20_34_13}EXTENDED DESCRIPTION {#extended-description .mansect}
483
+
484
+
> None.
485
+
486
+
#### []{#tag_20_34_14}EXIT STATUS {#exit-status .mansect}
487
+
488
+
> The following exit values shall be returned:
489
+
>
490
+
> 0
491
+
> : No differences were found.
492
+
>
493
+
> 1
494
+
> : Differences were found.
495
+
>
496
+
> \>1
497
+
> : An error occurred.
498
+
499
+
#### []{#tag_20_34_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
500
+
501
+
> Default.
502
+
503
+
------------------------------------------------------------------------
504
+
505
+
::: box
506
+
*The following sections are informative.*
507
+
:::
508
+
509
+
#### []{#tag_20_34_16}APPLICATION USAGE {#application-usage .mansect}
510
+
511
+
> If lines at the end of a file are changed and other lines are added,
512
+
> *diff* output may show this as a delete and add, as a change, or as a
513
+
> change and add; *diff* is not expected to know which happened and
514
+
> users should not care about the difference in output as long as it
515
+
> clearly shows the differences between the files.
516
+
517
+
#### []{#tag_20_34_17}EXAMPLES {#examples .mansect}
518
+
519
+
> If **dir1** is a directory containing a directory named **x**,
520
+
> **dir2** is a directory containing a directory named **x**, **dir1/x**
521
+
> and **dir2/x** both contain files named **date.out**, and **dir2/x**
522
+
> contains a file named **y**, the command:
523
+
>
524
+
>
525
+
> diff -r dir1 dir2
526
+
>
527
+
> could produce output similar to:
528
+
>
529
+
>
530
+
> Common subdirectories: dir1/x and dir2/x
531
+
> Only in dir2/x: y
532
+
> diff -r dir1/x/date.out dir2/x/date.out
533
+
> 1c1
534
+
> < Mon Jul 2 13:12:16 PDT 1990
535
+
> ---
536
+
> > Tue Jun 19 21:41:39 PDT 1990
537
+
538
+
#### []{#tag_20_34_18}RATIONALE {#rationale .mansect}
539
+
540
+
> The **-h** option was omitted because it was insufficiently specified
541
+
> and does not add to applications portability.
542
+
>
543
+
> Historical implementations employ algorithms that do not always
544
+
> produce a minimum list of differences; the current language about
545
+
> making every effort is the best this volume of POSIX.1-2017 can do, as
546
+
> there is no metric that could be employed to judge the quality of
547
+
> implementations against any and all file contents. The statement
548
+
> \"This list should be minimal\" clearly implies that implementations
549
+
> are not expected to provide the following output when comparing two
550
+
> 100-line files that differ in only one character on a single line:
551
+
>
552
+
>
553
+
> 1,100c1,100
554
+
> all 100 lines from file1 preceded with "< "
555
+
> ---
556
+
> all 100 lines from file2 preceded with "> "
557
+
>
558
+
> The \"Only in\" messages required when the **-r** option is specified
559
+
> are not used by most historical implementations if the **-e** option
560
+
> is also specified. It is required here because it provides useful
561
+
> information that must be provided to update a target directory
562
+
> hierarchy to match a source hierarchy. The \"Common subdirectories\"
563
+
> messages are written by System V and 4.3 BSD when the **-r** option is
564
+
> specified. They are allowed here but are not required because they are
565
+
> reporting on something that is the same, not reporting a difference,
566
+
> and are not needed to update a target hierarchy.
567
+
>
568
+
> The **-c** option, which writes output in a format using lines of
569
+
> context, has been included. The format is useful for a variety of
570
+
> reasons, among them being much improved readability and the ability to
571
+
> understand difference changes when the target file has line numbers
572
+
> that differ from another similar, but slightly different, copy. The
573
+
> [*patch*](../utilities/patch.html) utility is most valuable when
574
+
> working with difference listings using a context format. The BSD
575
+
> version of **-c** takes an optional argument specifying the amount of
576
+
> context. Rather than overloading **-c** and breaking the Utility
577
+
> Syntax Guidelines for *diff*, the standard developers decided to add a
578
+
> separate option for specifying a context diff with a specified amount
579
+
> of context (**-C**). Also, the format for context *diff*s was extended
580
+
> slightly in 4.3 BSD to allow multiple changes that are within context
581
+
> lines from each other to be merged together. The output format
582
+
> contains an additional four \<asterisk\> characters after the range of
583
+
> affected lines in the first filename. This was to provide a flag for
584
+
> old programs (like old versions of [*patch*](../utilities/patch.html))
585
+
> that only understand the old context format. The version of context
586
+
> described here does not require that multiple changes within context
587
+
> lines be merged, but it does not prohibit it either. The extension is
588
+
> upwards-compatible, so any vendors that wish to retain the old version
589
+
> of *diff* can do so by adding the extra four \<asterisk\> characters
590
+
> (that is, utilities that currently use *diff* and understand the new
591
+
> merged format will also understand the old unmerged format, but not
592
+
> *vice versa*).
593
+
>
594
+
> The **-u** and **-U** options of GNU *diff* have been included. Their
595
+
> output format, designed by Wayne Davison, takes up less space than
596
+
> **-c** and **-C** format, and in many cases is easier to read. The
597
+
> format\'s timestamps do not vary by locale, so *LC_TIME* does not
598
+
> affect it. The format\'s line numbers are rendered with the `%1d`
599
+
> format, not `%d` , because the file format notation rules would allow
600
+
> extra \<blank\> characters to appear around the numbers.
601
+
>
602
+
> The substitute command was added as an additional format for the
603
+
> **-e** option. This was added to provide implementations with a way to
604
+
> fix the classic \"dot alone on a line\" bug present in many versions
605
+
> of *diff*. Since many implementations have fixed this bug, the
606
+
> standard developers decided not to standardize broken behavior, but
607
+
> rather to provide the necessary tool for fixing the bug. One way to
608
+
> fix this bug is to output two periods whenever a lone period is
609
+
> needed, then terminate the append command with a period, and then use
610
+
> the substitute command to convert the two periods into one period.
611
+
>
612
+
> The BSD-derived **-r** option was added to provide a mechanism for
613
+
> using *diff* to compare two file system trees. This behavior is
614
+
> useful, is standard practice on all BSD-derived systems, and is not
615
+
> easily reproducible with the [*find*](../utilities/find.html) utility.
616
+
>
617
+
> The requirement that *diff* not compare files in some circumstances,
618
+
> even though they have the same name, is based on the actual output of
619
+
> historical implementations. The specified behavior precludes the
620
+
> problems arising from running into FIFOs and other files that would
621
+
> cause *diff* to hang waiting for input with no indication to the user
622
+
> that *diff* was hung. An earlier version of this standard specified
623
+
> the output format more precisely, but in practice this requirement was
624
+
> widely ignored and the benefit of standardization seemed small, so it
625
+
> is now unspecified. In most common usage, *diff* **-r** should
626
+
> indicate differences in the file hierarchies, not the difference of
627
+
> contents of devices pointed to by the hierarchies.
628
+
>
629
+
> Many early implementations of *diff* require seekable files. Since the
630
+
> System Interfaces volume of POSIX.1-2017 supports named pipes, the
631
+
> standard developers decided that such a restriction was unreasonable.
632
+
> Note also that the allowed filename **-** almost always refers to a
633
+
> pipe.
634
+
>
635
+
> No directory search order is specified for *diff*. The historical
636
+
> ordering is, in fact, not optimal, in that it prints out all of the
637
+
> differences at the current level, including the statements about all
638
+
> common subdirectories before recursing into those subdirectories.
639
+
>
640
+
> The message:
641
+
>
642
+
>
643
+
> "diff %s %s %s\n", <diff_options>, <filename1>, <filename2>
644
+
>
645
+
> does not vary by locale because it is the representation of a command,
646
+
> not an English sentence.
647
+
648
+
#### []{#tag_20_34_19}FUTURE DIRECTIONS {#future-directions .mansect}
649
+
650
+
> None.
651
+
652
+
#### []{#tag_20_34_20}SEE ALSO {#see-also .mansect}
653
+
654
+
> [*cmp*](../utilities/cmp.html#), [*comm*](../utilities/comm.html#),
655
+
> [*ed*](../utilities/ed.html#), [*find*](../utilities/find.html#)
656
+
>
657
+
> XBD [*Environment Variables*](../basedefs/V1_chap08.html#tag_08),
658
+
> [*Utility Syntax Guidelines*](../basedefs/V1_chap12.html#tag_12_02)
659
+
660
+
#### []{#tag_20_34_21}CHANGE HISTORY {#change-history .mansect}
661
+
662
+
> First released in Issue 2.
663
+
664
+
#### []{#tag_20_34_22}Issue 5 {#issue-5 .mansect}
665
+
666
+
> The FUTURE DIRECTIONS section is added.
667
+
668
+
#### []{#tag_20_34_23}Issue 6 {#issue-6 .mansect}
669
+
670
+
> The following new requirements on POSIX implementations derive from
671
+
> alignment with the Single UNIX Specification:
672
+
>
673
+
> - The **-f** option is added.
674
+
>
675
+
> The output format for **-c** or **-C** format is changed to align with
676
+
> changes to the IEEE P1003.2b draft standard resulting from IEEE PASC
677
+
> Interpretation 1003.2 #71.
678
+
>
679
+
> The normative text is reworded to avoid use of the term \"must\" for
680
+
> application requirements.
681
+
>
682
+
> IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/20 is applied,
683
+
> changing the STDOUT section. This changes the specification of *diff*
684
+
> **-c** so that it agrees with existing practice when contexts contain
685
+
> zero lines or one line.
686
+
687
+
#### []{#tag_20_34_24}Issue 7 {#issue-7 .mansect}
688
+
689
+
> Austin Group Interpretations 1003.1-2001 #115 and #114 are applied.
690
+
>
691
+
> Austin Group Interpretation 1003.1-2001 #192 is applied, clarifying
692
+
> the behavior if both files are non-text files.
693
+
>
694
+
> SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.
695
+
>
696
+
> SD5-XCU-ERN-103 and SD5-XCU-ERN-120 are applied, adding the **-u**
697
+
> option.
698
+
>
699
+
> POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0082 \[584\],
700
+
> XCU/TC2-2008/0083 \[950\], XCU/TC2-2008/0084 \[969\], and
701
+
> XCU/TC2-2008/0085 \[929\] are applied.
702
+
+209
docs/posix2018/dirname.md
+209
docs/posix2018/dirname.md
···
1
+
#### []{#tag_20_35_01}NAME {#name .mansect}
2
+
3
+
> dirname - return the directory portion of a pathname
4
+
5
+
#### []{#tag_20_35_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `dirname`` `*`string`*
8
+
9
+
#### []{#tag_20_35_03}DESCRIPTION {#description .mansect}
10
+
11
+
> The *string* operand shall be treated as a pathname, as defined in XBD
12
+
> [*Pathname*](../basedefs/V1_chap03.html#tag_03_271). The string
13
+
> *string* shall be converted to the name of the directory containing
14
+
> the filename corresponding to the last pathname component in *string*,
15
+
> performing actions equivalent to the following steps in order:
16
+
>
17
+
> 1. If *string* is **//**, skip steps 2 to 5.
18
+
>
19
+
> 2. If *string* consists entirely of \<slash\> characters, *string*
20
+
> shall be set to a single \<slash\> character. In this case, skip
21
+
> steps 3 to 8.
22
+
>
23
+
> 3. If there are any trailing \<slash\> characters in *string*, they
24
+
> shall be removed.
25
+
>
26
+
> 4. If there are no \<slash\> characters remaining in *string*,
27
+
> *string* shall be set to a single \<period\> character. In this
28
+
> case, skip steps 5 to 8.
29
+
>
30
+
> 5. If there are any trailing non- \<slash\> characters in *string*,
31
+
> they shall be removed.
32
+
>
33
+
> 6. If the remaining *string* is **//**, it is implementation-defined
34
+
> whether steps 7 and 8 are skipped or processed.
35
+
>
36
+
> 7. If there are any trailing \<slash\> characters in *string*, they
37
+
> shall be removed.
38
+
>
39
+
> 8. If the remaining *string* is empty, *string* shall be set to a
40
+
> single \<slash\> character.
41
+
>
42
+
> The resulting string shall be written to standard output.
43
+
44
+
#### []{#tag_20_35_04}OPTIONS {#options .mansect}
45
+
46
+
> None.
47
+
48
+
#### []{#tag_20_35_05}OPERANDS {#operands .mansect}
49
+
50
+
> The following operand shall be supported:
51
+
>
52
+
> *string*
53
+
> : A string.
54
+
55
+
#### []{#tag_20_35_06}STDIN {#stdin .mansect}
56
+
57
+
> Not used.
58
+
59
+
#### []{#tag_20_35_07}INPUT FILES {#input-files .mansect}
60
+
61
+
> None.
62
+
63
+
#### []{#tag_20_35_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
64
+
65
+
> The following environment variables shall affect the execution of
66
+
> *dirname*:
67
+
>
68
+
> *LANG*
69
+
> : Provide a default value for the internationalization variables
70
+
> that are unset or null. (See XBD [*Internationalization
71
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
72
+
> precedence of internationalization variables used to determine the
73
+
> values of locale categories.)
74
+
>
75
+
> *LC_ALL*
76
+
> : If set to a non-empty string value, override the values of all the
77
+
> other internationalization variables.
78
+
>
79
+
> *LC_CTYPE*
80
+
> : Determine the locale for the interpretation of sequences of bytes
81
+
> of text data as characters (for example, single-byte as opposed to
82
+
> multi-byte characters in arguments).
83
+
>
84
+
> *LC_MESSAGES*
85
+
> : Determine the locale that should be used to affect the format and
86
+
> contents of diagnostic messages written to standard error.
87
+
>
88
+
> *NLSPATH*
89
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
90
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
91
+
> location of message catalogs for the processing of *LC_MESSAGES.*
92
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
93
+
94
+
#### []{#tag_20_35_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
95
+
96
+
> Default.
97
+
98
+
#### []{#tag_20_35_10}STDOUT {#stdout .mansect}
99
+
100
+
> The *dirname* utility shall write a line to the standard output in the
101
+
> following format:
102
+
>
103
+
>
104
+
> "%s\n", <resulting string>
105
+
106
+
#### []{#tag_20_35_11}STDERR {#stderr .mansect}
107
+
108
+
> The standard error shall be used only for diagnostic messages.
109
+
110
+
#### []{#tag_20_35_12}OUTPUT FILES {#output-files .mansect}
111
+
112
+
> None.
113
+
114
+
#### []{#tag_20_35_13}EXTENDED DESCRIPTION {#extended-description .mansect}
115
+
116
+
> None.
117
+
118
+
#### []{#tag_20_35_14}EXIT STATUS {#exit-status .mansect}
119
+
120
+
> The following exit values shall be returned:
121
+
>
122
+
> 0
123
+
> : Successful completion.
124
+
>
125
+
> \>0
126
+
> : An error occurred.
127
+
128
+
#### []{#tag_20_35_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
129
+
130
+
> Default.
131
+
132
+
------------------------------------------------------------------------
133
+
134
+
::: box
135
+
*The following sections are informative.*
136
+
:::
137
+
138
+
#### []{#tag_20_35_16}APPLICATION USAGE {#application-usage .mansect}
139
+
140
+
> The definition of *pathname* specifies implementation-defined behavior
141
+
> for pathnames starting with two \<slash\> characters. Therefore,
142
+
> applications shall not arbitrarily add \<slash\> characters to the
143
+
> beginning of a pathname unless they can ensure that there are more or
144
+
> less than two or are prepared to deal with the implementation-defined
145
+
> consequences.
146
+
147
+
#### []{#tag_20_35_17}EXAMPLES {#examples .mansect}
148
+
149
+
> The EXAMPLES section of the [*basename*()](../functions/basename.html)
150
+
> function (see XSH [*basename*](../functions/basename.html#tag_16_32))
151
+
> includes a table showing examples of the results of processing several
152
+
> sample pathnames by the [*basename*()](../functions/basename.html) and
153
+
> [*dirname*()](../functions/dirname.html) functions and by the
154
+
> [*basename*](../utilities/basename.html) and *dirname* utilities.
155
+
>
156
+
> See also the examples for the [*basename*](../utilities/basename.html)
157
+
> utility.
158
+
159
+
#### []{#tag_20_35_18}RATIONALE {#rationale .mansect}
160
+
161
+
> The behaviors of [*basename*](../utilities/basename.html) and
162
+
> *dirname* in this volume of POSIX.1-2017 have been coordinated so that
163
+
> when *string* is a valid pathname:
164
+
>
165
+
>
166
+
> $(basename -- "string")
167
+
>
168
+
> would be a valid filename for the file in the directory:
169
+
>
170
+
>
171
+
> $(dirname -- "string")
172
+
>
173
+
> This would not work for the versions of these utilities in early
174
+
> proposals due to the way processing of trailing \<slash\> characters
175
+
> was specified. Consideration was given to leaving processing
176
+
> unspecified if there were trailing \<slash\> characters, but this
177
+
> cannot be done; XBD
178
+
> [*Pathname*](../basedefs/V1_chap03.html#tag_03_271) allows trailing
179
+
> \<slash\> characters. The [*basename*](../utilities/basename.html) and
180
+
> *dirname* utilities have to specify consistent handling for all valid
181
+
> pathnames.
182
+
183
+
#### []{#tag_20_35_19}FUTURE DIRECTIONS {#future-directions .mansect}
184
+
185
+
> None.
186
+
187
+
#### []{#tag_20_35_20}SEE ALSO {#see-also .mansect}
188
+
189
+
> [*Parameters and Variables*](../utilities/V3_chap02.html#tag_18_05),
190
+
> [*basename*](../utilities/basename.html#tag_20_07)
191
+
>
192
+
> XBD [*Pathname*](../basedefs/V1_chap03.html#tag_03_271), [*Environment
193
+
> Variables*](../basedefs/V1_chap08.html#tag_08)
194
+
>
195
+
> XSH [*basename*](../functions/basename.html#tag_16_32),
196
+
> [*dirname*](../functions/dirname.html#tag_16_91)
197
+
198
+
#### []{#tag_20_35_21}CHANGE HISTORY {#change-history .mansect}
199
+
200
+
> First released in Issue 2.
201
+
202
+
#### []{#tag_20_35_22}Issue 7 {#issue-7 .mansect}
203
+
204
+
> POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0083 \[192,430\],
205
+
> XCU/TC1-2008/0084 \[192\], and XCU/TC1-2008/0085 \[192\] are applied.
206
+
>
207
+
> POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0086 \[612\],
208
+
> XCU/TC2-2008/0087 \[620\], and XCU/TC2-2008/0088 \[612\] are applied.
209
+
+279
docs/posix2018/du.md
+279
docs/posix2018/du.md
···
1
+
#### []{#tag_20_36_01}NAME {#name .mansect}
2
+
3
+
> du - estimate file space usage
4
+
5
+
#### []{#tag_20_36_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `du`` `**`[`**`-a|-s`**`] [`**`-kx`**`] [`**`-H|-L`**`] [`***`file`*`...`**`]`**
8
+
9
+
#### []{#tag_20_36_03}DESCRIPTION {#description .mansect}
10
+
11
+
> By default, the *du* utility shall write to standard output the size
12
+
> of the file space allocated to, and the size of the file space
13
+
> allocated to each subdirectory of, the file hierarchy rooted in each
14
+
> of the specified files. By default, when a symbolic link is
15
+
> encountered on the command line or in the file hierarchy, *du* shall
16
+
> count the size of the symbolic link (rather than the file referenced
17
+
> by the link), and shall not follow the link to another portion of the
18
+
> file hierarchy. The size of the file space allocated to a file of type
19
+
> directory shall be defined as the sum total of space allocated to all
20
+
> files in the file hierarchy rooted in the directory plus the space
21
+
> allocated to the directory itself.
22
+
>
23
+
> When *du* cannot [*stat*()](../functions/stat.html) files or
24
+
> [*stat*()](../functions/stat.html) or read directories, it shall
25
+
> report an error condition and the final exit status is affected. A
26
+
> file that occurs multiple times under one file operand and that has a
27
+
> link count greater than 1 shall be counted and written for only one
28
+
> entry. It is implementation-defined whether a file that has a link
29
+
> count no greater than 1 is counted and written just once, or is
30
+
> counted and written for each occurrence. It is implementation-defined
31
+
> whether a file that occurs under one file operand is counted for other
32
+
> file operands. The directory entry that is selected in the report is
33
+
> unspecified. By default, file sizes shall be written in 512-byte
34
+
> units, rounded up to the next 512-byte unit.
35
+
36
+
#### []{#tag_20_36_04}OPTIONS {#options .mansect}
37
+
38
+
> The *du* utility shall conform to XBD [*Utility Syntax
39
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02) .
40
+
>
41
+
> The following options shall be supported:
42
+
>
43
+
> **-a**
44
+
> : In addition to the default output, report the size of each file
45
+
> not of type directory in the file hierarchy rooted in the
46
+
> specified file. The **-a** option shall not affect whether
47
+
> non-directories given as *file* operands are listed.
48
+
>
49
+
> **-H**
50
+
> : If a symbolic link is specified on the command line, *du* shall
51
+
> count the size of the file or file hierarchy referenced by the
52
+
> link.
53
+
>
54
+
> **-k**
55
+
> : Write the files sizes in units of 1024 bytes, rather than the
56
+
> default 512-byte units.
57
+
>
58
+
> **-L**
59
+
> : If a symbolic link is specified on the command line or encountered
60
+
> during the traversal of a file hierarchy, *du* shall count the
61
+
> size of the file or file hierarchy referenced by the link.
62
+
>
63
+
> **-s**
64
+
> : Instead of the default output, report only the total sum for each
65
+
> of the specified files.
66
+
>
67
+
> **-x**
68
+
> : When evaluating file sizes, evaluate only those files that have
69
+
> the same device as the file specified by the *file* operand.
70
+
>
71
+
> Specifying more than one of the mutually-exclusive options **-H** and
72
+
> **-L** shall not be considered an error. The last option specified
73
+
> shall determine the behavior of the utility.
74
+
75
+
#### []{#tag_20_36_05}OPERANDS {#operands .mansect}
76
+
77
+
> The following operand shall be supported:
78
+
>
79
+
> *file*
80
+
> : The pathname of a file whose size is to be written. If no *file*
81
+
> is specified, the current directory shall be used.
82
+
83
+
#### []{#tag_20_36_06}STDIN {#stdin .mansect}
84
+
85
+
> Not used.
86
+
87
+
#### []{#tag_20_36_07}INPUT FILES {#input-files .mansect}
88
+
89
+
> None.
90
+
91
+
#### []{#tag_20_36_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
92
+
93
+
> The following environment variables shall affect the execution of
94
+
> *du*:
95
+
>
96
+
> *LANG*
97
+
> : Provide a default value for the internationalization variables
98
+
> that are unset or null. (See XBD [*Internationalization
99
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
100
+
> precedence of internationalization variables used to determine the
101
+
> values of locale categories.)
102
+
>
103
+
> *LC_ALL*
104
+
> : If set to a non-empty string value, override the values of all the
105
+
> other internationalization variables.
106
+
>
107
+
> *LC_CTYPE*
108
+
> : Determine the locale for the interpretation of sequences of bytes
109
+
> of text data as characters (for example, single-byte as opposed to
110
+
> multi-byte characters in arguments).
111
+
>
112
+
> *LC_MESSAGES*
113
+
> : Determine the locale that should be used to affect the format and
114
+
> contents of diagnostic messages written to standard error.
115
+
>
116
+
> *NLSPATH*
117
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
118
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
119
+
> location of message catalogs for the processing of *LC_MESSAGES.*
120
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
121
+
122
+
#### []{#tag_20_36_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
123
+
124
+
> Default.
125
+
126
+
#### []{#tag_20_36_10}STDOUT {#stdout .mansect}
127
+
128
+
> The output from *du* shall consist of the amount of space allocated to
129
+
> a file and the name of the file, in the following format:
130
+
>
131
+
>
132
+
> "%d %s\n", <size>, <pathname>
133
+
134
+
#### []{#tag_20_36_11}STDERR {#stderr .mansect}
135
+
136
+
> The standard error shall be used only for diagnostic messages.
137
+
138
+
#### []{#tag_20_36_12}OUTPUT FILES {#output-files .mansect}
139
+
140
+
> None.
141
+
142
+
#### []{#tag_20_36_13}EXTENDED DESCRIPTION {#extended-description .mansect}
143
+
144
+
> None.
145
+
146
+
#### []{#tag_20_36_14}EXIT STATUS {#exit-status .mansect}
147
+
148
+
> The following exit values shall be returned:
149
+
>
150
+
> 0
151
+
> : Successful completion.
152
+
>
153
+
> \>0
154
+
> : An error occurred.
155
+
156
+
#### []{#tag_20_36_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
157
+
158
+
> Default.
159
+
160
+
------------------------------------------------------------------------
161
+
162
+
::: box
163
+
*The following sections are informative.*
164
+
:::
165
+
166
+
#### []{#tag_20_36_16}APPLICATION USAGE {#application-usage .mansect}
167
+
168
+
> None.
169
+
170
+
#### []{#tag_20_36_17}EXAMPLES {#examples .mansect}
171
+
172
+
> None.
173
+
174
+
#### []{#tag_20_36_18}RATIONALE {#rationale .mansect}
175
+
176
+
> The use of 512-byte units is historical practice and maintains
177
+
> compatibility with [*ls*](../utilities/ls.html) and other utilities in
178
+
> this volume of POSIX.1-2017. This does not mandate that the file
179
+
> system itself be based on 512-byte blocks. The **-k** option was added
180
+
> as a compromise measure. It was agreed by the standard developers that
181
+
> 512 bytes was the best default unit because of its complete historical
182
+
> consistency on System V (*versus* the mixed 512/1024-byte usage on BSD
183
+
> systems), and that a **-k** option to switch to 1024-byte units was a
184
+
> good compromise. Users who prefer the 1024-byte quantity can easily
185
+
> alias *du* to *du* **-k** without breaking the many historical scripts
186
+
> relying on the 512-byte units.
187
+
>
188
+
> The **-b** option was added to an early proposal to provide a
189
+
> resolution to the situation where System V and BSD systems give
190
+
> figures for file sizes in *blocks*, which is an implementation-defined
191
+
> concept. (In common usage, the block size is 512 bytes for System V
192
+
> and 1024 bytes for BSD systems.) However, **-b** was later deleted,
193
+
> since the default was eventually decided as 512-byte units.
194
+
>
195
+
> Historical file systems provided no way to obtain exact figures for
196
+
> the space allocation given to files. There are two known areas of
197
+
> inaccuracies in historical file systems: cases of *indirect blocks*
198
+
> being used by the file system or *sparse* files yielding incorrectly
199
+
> high values. An indirect block is space used by the file system in the
200
+
> storage of the file, but that need not be counted in the space
201
+
> allocated to the file. A *sparse* file is one in which an
202
+
> [*lseek*()](../functions/lseek.html) call has been made to a position
203
+
> beyond the end of the file and data has subsequently been written at
204
+
> that point. A file system need not allocate all the intervening
205
+
> zero-filled blocks to such a file. It is up to the implementation to
206
+
> define exactly how accurate its methods are.
207
+
>
208
+
> The **-a** and **-s** options were mutually-exclusive in the original
209
+
> version of *du*. The POSIX Shell and Utilities description is implied
210
+
> by the language in the SVID where **-s** is described as causing
211
+
> \"only the grand total\" to be reported. Some systems may produce
212
+
> output for **-sa**, but a Strictly Conforming POSIX Shell and
213
+
> Utilities Application cannot use that combination.
214
+
>
215
+
> The **-a** and **-s** options were adopted from the SVID except that
216
+
> the System V behavior of not listing non-directories explicitly given
217
+
> as operands, unless the **-a** option is specified, was considered a
218
+
> bug; the BSD-based behavior (report for all operands) is mandated. The
219
+
> default behavior of *du* in the SVID with regard to reporting the
220
+
> failure to read files (it produces no messages) was considered
221
+
> counter-intuitive, and thus it was specified that the POSIX Shell and
222
+
> Utilities default behavior shall be to produce such messages. These
223
+
> messages can be turned off with shell redirection to achieve the
224
+
> System V behavior.
225
+
>
226
+
> The **-x** option is historical practice on recent BSD systems. It has
227
+
> been adopted by this volume of POSIX.1-2017 because there was no other
228
+
> historical method of limiting the *du* search to a single file
229
+
> hierarchy. This limitation of the search is necessary to make it
230
+
> possible to obtain file space usage information about a file system on
231
+
> which other file systems are mounted, without having to resort to a
232
+
> lengthy [*find*](../utilities/find.html) and
233
+
> [*awk*](../utilities/awk.html) script.
234
+
235
+
#### []{#tag_20_36_19}FUTURE DIRECTIONS {#future-directions .mansect}
236
+
237
+
> A future version of this standard may require that a file that occurs
238
+
> multiple times shall be counted and written for only one entry, even
239
+
> if the occurrences are under different file operands.
240
+
241
+
#### []{#tag_20_36_20}SEE ALSO {#see-also .mansect}
242
+
243
+
> [*ls*](../utilities/ls.html#)
244
+
>
245
+
> XBD [*Environment Variables*](../basedefs/V1_chap08.html#tag_08),
246
+
> [*Utility Syntax Guidelines*](../basedefs/V1_chap12.html#tag_12_02)
247
+
>
248
+
> XSH [*fstatat*](../functions/fstatat.html#)
249
+
250
+
#### []{#tag_20_36_21}CHANGE HISTORY {#change-history .mansect}
251
+
252
+
> First released in Issue 2.
253
+
254
+
#### []{#tag_20_36_22}Issue 6 {#issue-6 .mansect}
255
+
256
+
> This utility is marked as part of the User Portability Utilities
257
+
> option.
258
+
>
259
+
> The APPLICATION USAGE section is added.
260
+
>
261
+
> The obsolescent **-r** option is removed.
262
+
>
263
+
> The Open Group Corrigendum U025/3 is applied. The *du* utility is
264
+
> reinstated, as it had incorrectly been marked LEGACY in Issue 5.
265
+
>
266
+
> The **-H** and **-L** options for symbolic links are added as
267
+
> described in the IEEE P1003.2b draft standard.
268
+
269
+
#### []{#tag_20_36_23}Issue 7 {#issue-7 .mansect}
270
+
271
+
> The *du* utility is moved from the User Portability Utilities option
272
+
> to the Base. User Portability Utilities is now an option for
273
+
> interactive utilities.
274
+
>
275
+
> SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.
276
+
>
277
+
> POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0089 \[527\] is
278
+
> applied.
279
+
+211
docs/posix2018/expand.md
+211
docs/posix2018/expand.md
···
1
+
#### []{#tag_20_41_01}NAME {#name .mansect}
2
+
3
+
> expand - convert tabs to spaces
4
+
5
+
#### []{#tag_20_41_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `expand`` `**`[`**`-t`` `*`tablist`***`] [`***`file`*`...`**`]`**
8
+
9
+
#### []{#tag_20_41_03}DESCRIPTION {#description .mansect}
10
+
11
+
> The *expand* utility shall write files or the standard input to the
12
+
> standard output with \<tab\> characters replaced with one or more
13
+
> \<space\> characters needed to pad to the next tab stop. Any
14
+
> \<backspace\> characters shall be copied to the output and cause the
15
+
> column position count for tab stop calculations to be decremented; the
16
+
> column position count shall not be decremented below zero.
17
+
18
+
#### []{#tag_20_41_04}OPTIONS {#options .mansect}
19
+
20
+
> The *expand* utility shall conform to XBD [*Utility Syntax
21
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02).
22
+
>
23
+
> The following option shall be supported:
24
+
>
25
+
> **-t ** *tablist*
26
+
>
27
+
> : Specify the tab stops. The application shall ensure that the
28
+
> argument *tablist* consists of either a single positive decimal
29
+
> integer or a list of tabstops. If a single number is given, tabs
30
+
> shall be set that number of column positions apart instead of the
31
+
> default 8.
32
+
>
33
+
> If a list of tabstops is given, the application shall ensure that
34
+
> it consists of a list of two or more positive decimal integers,
35
+
> separated by \<blank\> or \<comma\> characters, in ascending
36
+
> order. The \<tab\> characters shall be set at those specific
37
+
> column positions. Each tab stop *N* shall be an integer value
38
+
> greater than zero, and the list is in strictly ascending order.
39
+
> This is taken to mean that, from the start of a line of output,
40
+
> tabbing to position *N* shall cause the next character output to
41
+
> be in the (*N*+1)th column position on that line.
42
+
>
43
+
> In the event of *expand* having to process a \<tab\> at a position
44
+
> beyond the last of those specified in a multiple tab-stop list,
45
+
> the \<tab\> shall be replaced by a single \<space\> in the output.
46
+
47
+
#### []{#tag_20_41_05}OPERANDS {#operands .mansect}
48
+
49
+
> The following operand shall be supported:
50
+
>
51
+
> *file*
52
+
> : The pathname of a text file to be used as input.
53
+
54
+
#### []{#tag_20_41_06}STDIN {#stdin .mansect}
55
+
56
+
> See the INPUT FILES section.
57
+
58
+
#### []{#tag_20_41_07}INPUT FILES {#input-files .mansect}
59
+
60
+
> Input files shall be text files.
61
+
62
+
#### []{#tag_20_41_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
63
+
64
+
> The following environment variables shall affect the execution of
65
+
> *expand*:
66
+
>
67
+
> *LANG*
68
+
> : Provide a default value for the internationalization variables
69
+
> that are unset or null. (See XBD [*Internationalization
70
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
71
+
> precedence of internationalization variables used to determine the
72
+
> values of locale categories.)
73
+
>
74
+
> *LC_ALL*
75
+
> : If set to a non-empty string value, override the values of all the
76
+
> other internationalization variables.
77
+
>
78
+
> *LC_CTYPE*
79
+
> : Determine the locale for the interpretation of sequences of bytes
80
+
> of text data as characters (for example, single-byte as opposed to
81
+
> multi-byte characters in arguments and input files), the
82
+
> processing of \<tab\> and \<space\> characters, and for the
83
+
> determination of the width in column positions each character
84
+
> would occupy on an output device.
85
+
>
86
+
> *LC_MESSAGES*
87
+
> : Determine the locale that should be used to affect the format and
88
+
> contents of diagnostic messages written to standard error.
89
+
>
90
+
> *NLSPATH*
91
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
92
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
93
+
> location of message catalogs for the processing of *LC_MESSAGES.*
94
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
95
+
96
+
#### []{#tag_20_41_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
97
+
98
+
> Default.
99
+
100
+
#### []{#tag_20_41_10}STDOUT {#stdout .mansect}
101
+
102
+
> The standard output shall be equivalent to the input files with
103
+
> \<tab\> characters converted into the appropriate number of \<space\>
104
+
> characters.
105
+
106
+
#### []{#tag_20_41_11}STDERR {#stderr .mansect}
107
+
108
+
> The standard error shall be used only for diagnostic messages.
109
+
110
+
#### []{#tag_20_41_12}OUTPUT FILES {#output-files .mansect}
111
+
112
+
> None.
113
+
114
+
#### []{#tag_20_41_13}EXTENDED DESCRIPTION {#extended-description .mansect}
115
+
116
+
> None.
117
+
118
+
#### []{#tag_20_41_14}EXIT STATUS {#exit-status .mansect}
119
+
120
+
> The following exit values shall be returned:
121
+
>
122
+
> 0
123
+
> : Successful completion
124
+
>
125
+
> \>0
126
+
> : An error occurred.
127
+
128
+
#### []{#tag_20_41_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
129
+
130
+
> The *expand* utility shall terminate with an error message and
131
+
> non-zero exit status upon encountering difficulties accessing one of
132
+
> the *file* operands.
133
+
134
+
------------------------------------------------------------------------
135
+
136
+
::: box
137
+
*The following sections are informative.*
138
+
:::
139
+
140
+
#### []{#tag_20_41_16}APPLICATION USAGE {#application-usage .mansect}
141
+
142
+
> None.
143
+
144
+
#### []{#tag_20_41_17}EXAMPLES {#examples .mansect}
145
+
146
+
> None.
147
+
148
+
#### []{#tag_20_41_18}RATIONALE {#rationale .mansect}
149
+
150
+
> The *expand* utility is useful for preprocessing text files (before
151
+
> sorting, looking at specific columns, and so on) that contain \<tab\>
152
+
> characters.
153
+
>
154
+
> See XBD [*Column Position*](../basedefs/V1_chap03.html#tag_03_103).
155
+
>
156
+
> The *tablist* option-argument consists of integers in ascending order.
157
+
> Utility Syntax Guideline 8 mandates that *expand* shall accept the
158
+
> integers (within the single argument) separated using either \<comma\>
159
+
> or \<blank\> characters.
160
+
>
161
+
> Earlier versions of this standard allowed the following form in the
162
+
> SYNOPSIS:
163
+
>
164
+
>
165
+
> expand [-tabstop][-tab1,tab2,...,tabn][file ...]
166
+
>
167
+
> This form is no longer specified by POSIX.1-2017 but may be present in
168
+
> some implementations.
169
+
170
+
#### []{#tag_20_41_19}FUTURE DIRECTIONS {#future-directions .mansect}
171
+
172
+
> None.
173
+
174
+
#### []{#tag_20_41_20}SEE ALSO {#see-also .mansect}
175
+
176
+
> [*tabs*](../utilities/tabs.html#),
177
+
> [*unexpand*](../utilities/unexpand.html#)
178
+
>
179
+
> XBD [*Column Position*](../basedefs/V1_chap03.html#tag_03_103),
180
+
> [*Environment Variables*](../basedefs/V1_chap08.html#tag_08),
181
+
> [*Utility Syntax Guidelines*](../basedefs/V1_chap12.html#tag_12_02)
182
+
183
+
#### []{#tag_20_41_21}CHANGE HISTORY {#change-history .mansect}
184
+
185
+
> First released in Issue 4.
186
+
187
+
#### []{#tag_20_41_22}Issue 6 {#issue-6 .mansect}
188
+
189
+
> This utility is marked as part of the User Portability Utilities
190
+
> option.
191
+
>
192
+
> The APPLICATION USAGE section is added.
193
+
>
194
+
> The obsolescent SYNOPSIS is removed.
195
+
>
196
+
> The *LC_CTYPE* environment variable description is updated to align
197
+
> with the IEEE P1003.2b draft standard.
198
+
>
199
+
> The normative text is reworded to avoid use of the term \"must\" for
200
+
> application requirements.
201
+
202
+
#### []{#tag_20_41_23}Issue 7 {#issue-7 .mansect}
203
+
204
+
> Austin Group Interpretation 1003.1-2001 #027 is applied.
205
+
>
206
+
> SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.
207
+
>
208
+
> The *expand* utility is moved from the User Portability Utilities
209
+
> option to the Base. User Portability Utilities is now an option for
210
+
> interactive utilities.
211
+
+383
docs/posix2018/expr.md
+383
docs/posix2018/expr.md
···
1
+
#### []{#tag_20_42_01}NAME {#name .mansect}
2
+
3
+
> expr - evaluate arguments as an expression
4
+
5
+
#### []{#tag_20_42_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `expr`` `*`operand`*`...`
8
+
9
+
#### []{#tag_20_42_03}DESCRIPTION {#description .mansect}
10
+
11
+
> The *expr* utility shall evaluate an expression and write the result
12
+
> to standard output.
13
+
14
+
#### []{#tag_20_42_04}OPTIONS {#options .mansect}
15
+
16
+
> None.
17
+
18
+
#### []{#tag_20_42_05}OPERANDS {#operands .mansect}
19
+
20
+
> The single expression evaluated by *expr* shall be formed from the
21
+
> *operand* operands, as described in the EXTENDED DESCRIPTION section.
22
+
> The application shall ensure that each of the expression operator
23
+
> symbols:
24
+
>
25
+
>
26
+
> ( ) | & = > >= < <= != + - * / % :
27
+
>
28
+
> and the symbols *integer* and *string* in the table are provided as
29
+
> separate arguments to *expr*.
30
+
31
+
#### []{#tag_20_42_06}STDIN {#stdin .mansect}
32
+
33
+
> Not used.
34
+
35
+
#### []{#tag_20_42_07}INPUT FILES {#input-files .mansect}
36
+
37
+
> None.
38
+
39
+
#### []{#tag_20_42_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
40
+
41
+
> The following environment variables shall affect the execution of
42
+
> *expr*:
43
+
>
44
+
> *LANG*
45
+
> : Provide a default value for the internationalization variables
46
+
> that are unset or null. (See XBD [*Internationalization
47
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
48
+
> precedence of internationalization variables used to determine the
49
+
> values of locale categories.)
50
+
>
51
+
> *LC_ALL*
52
+
> : If set to a non-empty string value, override the values of all the
53
+
> other internationalization variables.
54
+
>
55
+
> *LC_COLLATE*
56
+
> : Determine the locale for the behavior of ranges, equivalence
57
+
> classes, and multi-character collating elements within regular
58
+
> expressions and by the string comparison operators.
59
+
>
60
+
> *LC_CTYPE*
61
+
> : Determine the locale for the interpretation of sequences of bytes
62
+
> of text data as characters (for example, single-byte as opposed to
63
+
> multi-byte characters in arguments) and the behavior of character
64
+
> classes within regular expressions.
65
+
>
66
+
> *LC_MESSAGES*
67
+
> : Determine the locale that should be used to affect the format and
68
+
> contents of diagnostic messages written to standard error.
69
+
>
70
+
> *NLSPATH*
71
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
72
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
73
+
> location of message catalogs for the processing of *LC_MESSAGES.*
74
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
75
+
76
+
#### []{#tag_20_42_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
77
+
78
+
> Default.
79
+
80
+
#### []{#tag_20_42_10}STDOUT {#stdout .mansect}
81
+
82
+
> The *expr* utility shall evaluate the expression and write the result,
83
+
> followed by a \<newline\>, to standard output.
84
+
85
+
#### []{#tag_20_42_11}STDERR {#stderr .mansect}
86
+
87
+
> The standard error shall be used only for diagnostic messages.
88
+
89
+
#### []{#tag_20_42_12}OUTPUT FILES {#output-files .mansect}
90
+
91
+
> None.
92
+
93
+
#### []{#tag_20_42_13}EXTENDED DESCRIPTION {#extended-description .mansect}
94
+
95
+
> The formation of the expression to be evaluated is shown in the
96
+
> following table. The symbols *expr*, *expr1*, and *expr2* represent
97
+
> expressions formed from *integer* and *string* symbols and the
98
+
> expression operator symbols (all separate arguments) by recursive
99
+
> application of the constructs described in the table. The expressions
100
+
> are listed in order of decreasing precedence, with equal-precedence
101
+
> operators grouped between horizontal lines. All of the operators shall
102
+
> be left-associative.
103
+
>
104
+
> +-----------------------------------+-----------------------------------+
105
+
> | **Expression** | **Description** |
106
+
> +:==================================+:==================================+
107
+
> | *integer* | An argument consisting only of an |
108
+
> | | (optional) unary minus followed |
109
+
> | *string* | by digits. |
110
+
> | | |
111
+
> | | A string argument; see below. |
112
+
> +-----------------------------------+-----------------------------------+
113
+
> | ( *expr* ) | Grouping symbols. Any expression |
114
+
> | | can be placed within parentheses. |
115
+
> | | Parentheses can be nested to a |
116
+
> | | depth of {EXPR_NEST_MAX}. |
117
+
> +-----------------------------------+-----------------------------------+
118
+
> | *expr1* : *expr2* | Matching expression; see below. |
119
+
> +-----------------------------------+-----------------------------------+
120
+
> | *expr1* \* *expr2* | Multiplication of decimal |
121
+
> | | integer-valued arguments. |
122
+
> | *expr1* / *expr2* | |
123
+
> | | Integer division of decimal |
124
+
> | *expr1* % *expr2* | integer-valued arguments, |
125
+
> | | producing an integer result. |
126
+
> | | |
127
+
> | | Remainder of integer division of |
128
+
> | | decimal integer-valued arguments. |
129
+
> +-----------------------------------+-----------------------------------+
130
+
> | *expr1* + *expr2* | Addition of decimal |
131
+
> | | integer-valued arguments. |
132
+
> | *expr1* - *expr2* | |
133
+
> | | Subtraction of decimal |
134
+
> | | integer-valued arguments. |
135
+
> +-----------------------------------+-----------------------------------+
136
+
> | \ | Returns the result of a decimal |
137
+
> | | integer comparison if both |
138
+
> | | arguments are integers; |
139
+
> | *expr1* = *expr2* | otherwise, returns the result of |
140
+
> | | a string comparison using the |
141
+
> | *expr1* \> *expr2* | locale-specific collation |
142
+
> | | sequence. The result of each |
143
+
> | *expr1* \>= *expr2* | comparison is 1 if the specified |
144
+
> | | relationship is true, or 0 if the |
145
+
> | *expr1* \< *expr2* | relationship is false. |
146
+
> | | |
147
+
> | *expr1* \<= *expr2* | Equal. |
148
+
> | | |
149
+
> | *expr1* != *expr2* | Greater than. |
150
+
> | | |
151
+
> | | Greater than or equal. |
152
+
> | | |
153
+
> | | Less than. |
154
+
> | | |
155
+
> | | Less than or equal. |
156
+
> | | |
157
+
> | | Not equal. |
158
+
> +-----------------------------------+-----------------------------------+
159
+
> | *expr1* & *expr2* | Returns the evaluation of *expr1* |
160
+
> | | if neither expression evaluates |
161
+
> | | to null or zero; otherwise, |
162
+
> | | returns zero. |
163
+
> +-----------------------------------+-----------------------------------+
164
+
> | *expr1* \| *expr2* | Returns the evaluation of *expr1* |
165
+
> | | if it is neither null nor zero; |
166
+
> | | otherwise, returns the evaluation |
167
+
> | | of *expr2* if it is not null; |
168
+
> | | otherwise, zero. |
169
+
> +-----------------------------------+-----------------------------------+
170
+
>
171
+
> ##### []{#tag_20_42_13_01}Matching Expression
172
+
>
173
+
> The `':'` matching operator shall compare the string resulting from
174
+
> the evaluation of *expr1* with the regular expression pattern
175
+
> resulting from the evaluation of *expr2*. Regular expression syntax
176
+
> shall be that defined in XBD [*Basic Regular
177
+
> Expressions*](../basedefs/V1_chap09.html#tag_09_03), except that all
178
+
> patterns are anchored to the beginning of the string (that is, only
179
+
> sequences starting at the first character of a string are matched by
180
+
> the regular expression) and, therefore, it is unspecified whether
181
+
> `'^'` is a special character in that context. Usually, the matching
182
+
> operator shall return a string representing the number of characters
183
+
> matched ( `'0'` on failure). Alternatively, if the pattern contains at
184
+
> least one regular expression subexpression `"[\(...\)]"`, the string
185
+
> matched by the back-reference expression `"\1"` shall be returned. If
186
+
> the back-reference expression `"\1"` does not match, then the null
187
+
> string shall be returned.
188
+
>
189
+
> ##### []{#tag_20_42_13_02}Identification as Integer or String
190
+
>
191
+
> An argument or the value of a subexpression that consists only of an
192
+
> optional unary minus followed by digits is a candidate for treatment
193
+
> as an integer if it is used as the left argument to the `|` operator
194
+
> or as either argument to any of the following operators:
195
+
> `& = > >= < <= != + - * / %`. Otherwise, the argument or subexpression
196
+
> value shall be treated as a string.
197
+
>
198
+
> The use of string arguments **length**, **substr**, **index**, or
199
+
> **match** produces unspecified results.
200
+
201
+
#### []{#tag_20_42_14}EXIT STATUS {#exit-status .mansect}
202
+
203
+
> The following exit values shall be returned:
204
+
>
205
+
> 0
206
+
> : The *expression* evaluates to neither null nor zero.
207
+
>
208
+
> 1
209
+
> : The *expression* evaluates to null or zero.
210
+
>
211
+
> 2
212
+
> : Invalid *expression*.
213
+
>
214
+
> \>2
215
+
> : An error occurred.
216
+
217
+
#### []{#tag_20_42_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
218
+
219
+
> Default.
220
+
221
+
------------------------------------------------------------------------
222
+
223
+
::: box
224
+
*The following sections are informative.*
225
+
:::
226
+
227
+
#### []{#tag_20_42_16}APPLICATION USAGE {#application-usage .mansect}
228
+
229
+
> The *expr* utility has a rather difficult syntax:
230
+
>
231
+
> - Many of the operators are also shell control operators or reserved
232
+
> words, so they have to be escaped on the command line.
233
+
>
234
+
> - Each part of the expression is composed of separate arguments, so
235
+
> liberal usage of \<blank\> characters is required. For example:
236
+
>
237
+
> **Invalid** **Valid**
238
+
> ---------------------- ---------------------------
239
+
> *expr* `1+2` *expr* `1 + 2`
240
+
> *expr* `"1 + 2"` *expr* `1 + 2`
241
+
> *expr* `1 + (2 * 3)` *expr* `1 + \( 2 \* 3 \)`
242
+
>
243
+
> In many cases, the arithmetic and string features provided as part of
244
+
> the shell command language are easier to use than their equivalents in
245
+
> *expr*. Newly written scripts should avoid *expr* in favor of the new
246
+
> features within the shell; see [*Parameters and
247
+
> Variables*](../utilities/V3_chap02.html#tag_18_05) and [*Arithmetic
248
+
> Expansion*](../utilities/V3_chap02.html#tag_18_06_04).
249
+
>
250
+
> After argument processing by the shell, *expr* is not required to be
251
+
> able to tell the difference between an operator and an operand except
252
+
> by the value. If `"$a"` is `'='`, the command:
253
+
>
254
+
>
255
+
> expr "$a" = '='
256
+
>
257
+
> looks like:
258
+
>
259
+
>
260
+
> expr = = =
261
+
>
262
+
> as the arguments are passed to *expr* (and they all may be taken as
263
+
> the `'='` operator). The following works reliably:
264
+
>
265
+
>
266
+
> expr "X$a" = X=
267
+
>
268
+
> Also note that this volume of POSIX.1-2017 permits implementations to
269
+
> extend utilities. The *expr* utility permits the integer arguments to
270
+
> be preceded with a unary minus. This means that an integer argument
271
+
> could look like an option. Therefore, the conforming application must
272
+
> employ the `"--"` construct of Guideline 10 of XBD [*Utility Syntax
273
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02) to protect its
274
+
> operands if there is any chance the first operand might be a negative
275
+
> integer (or any string with a leading minus).
276
+
>
277
+
> For testing string equality the [*test*](../utilities/test.html)
278
+
> utility is preferred over *expr*, as it is usually implemented as a
279
+
> shell built-in. However, the functionality is not quite the same
280
+
> because the *expr* `=` and `!=` operators check whether strings
281
+
> collate equally, whereas [*test*](../utilities/test.html) checks
282
+
> whether they are identical. Therefore, they can produce different
283
+
> results in locales where the collation sequence does not have a total
284
+
> ordering of all characters (see XBD
285
+
> [*LC_COLLATE*](../basedefs/V1_chap07.html#tag_07_03_02)).\
286
+
287
+
#### []{#tag_20_42_17}EXAMPLES {#examples .mansect}
288
+
289
+
> The following command:
290
+
>
291
+
>
292
+
> a=$(expr "$a" + 1)
293
+
>
294
+
> adds 1 to the variable *a*.
295
+
>
296
+
> The following command, for `"$a"` equal to either **/usr/abc/file** or
297
+
> just **file**:
298
+
>
299
+
>
300
+
> expr $a : '.*/\(.*\)' \| $a
301
+
>
302
+
> returns the last segment of a pathname (that is, **file**).
303
+
> Applications should avoid the character `'/'` used alone as an
304
+
> argument; *expr* may interpret it as the division operator.
305
+
>
306
+
> The following command:
307
+
>
308
+
>
309
+
> expr "//$a" : '.*/\(.*\)'
310
+
>
311
+
> is a better representation of the previous example. The addition of
312
+
> the `"//"` characters eliminates any ambiguity about the division
313
+
> operator and simplifies the whole expression. Also note that pathnames
314
+
> may contain characters contained in the *IFS* variable and should be
315
+
> quoted to avoid having `"$a"` expand into multiple arguments.
316
+
>
317
+
> The following command:
318
+
>
319
+
>
320
+
> expr "X$VAR" : '.*' - 1
321
+
>
322
+
> returns the number of characters in *VAR*.
323
+
324
+
#### []{#tag_20_42_18}RATIONALE {#rationale .mansect}
325
+
326
+
> In an early proposal, EREs were used in the matching expression
327
+
> syntax. This was changed to BREs to avoid breaking historical
328
+
> applications.
329
+
>
330
+
> The use of a leading \<circumflex\> in the BRE is unspecified because
331
+
> many historical implementations have treated it as a special
332
+
> character, despite their system documentation. For example:
333
+
>
334
+
>
335
+
> expr foo : ^foo expr ^foo : ^foo
336
+
>
337
+
> return 3 and 0, respectively, on those systems; their documentation
338
+
> would imply the reverse. Thus, the anchoring condition is left
339
+
> unspecified to avoid breaking historical scripts relying on this
340
+
> undocumented feature.
341
+
342
+
#### []{#tag_20_42_19}FUTURE DIRECTIONS {#future-directions .mansect}
343
+
344
+
> None.
345
+
346
+
#### []{#tag_20_42_20}SEE ALSO {#see-also .mansect}
347
+
348
+
> [*Parameters and Variables*](../utilities/V3_chap02.html#tag_18_05),
349
+
> [*Arithmetic Expansion*](../utilities/V3_chap02.html#tag_18_06_04)
350
+
>
351
+
> XBD [*LC_COLLATE*](../basedefs/V1_chap07.html#tag_07_03_02),
352
+
> [*Environment Variables*](../basedefs/V1_chap08.html#tag_08), [*Basic
353
+
> Regular Expressions*](../basedefs/V1_chap09.html#tag_09_03), [*Utility
354
+
> Syntax Guidelines*](../basedefs/V1_chap12.html#tag_12_02)
355
+
356
+
#### []{#tag_20_42_21}CHANGE HISTORY {#change-history .mansect}
357
+
358
+
> First released in Issue 2.
359
+
360
+
#### []{#tag_20_42_22}Issue 5 {#issue-5 .mansect}
361
+
362
+
> The FUTURE DIRECTIONS section is added.
363
+
364
+
#### []{#tag_20_42_23}Issue 6 {#issue-6 .mansect}
365
+
366
+
> The *expr* utility is aligned with the IEEE P1003.2b draft standard,
367
+
> to include resolution of IEEE PASC Interpretation 1003.2 #104.
368
+
>
369
+
> The normative text is reworded to avoid use of the term \"must\" for
370
+
> application requirements.
371
+
372
+
#### []{#tag_20_42_24}Issue 7 {#issue-7 .mansect}
373
+
374
+
> Austin Group Interpretation 1003.1-2001 #036 is applied, clarifying
375
+
> the behavior for BREs.
376
+
>
377
+
> The SYNOPSIS and OPERANDS sections are revised to explicitly state
378
+
> that the name of each of the operands is *operand*.
379
+
>
380
+
> POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0094 \[942\],
381
+
> XCU/TC2-2008/0095 \[709\], XCU/TC2-2008/0096 \[942\],
382
+
> XCU/TC2-2008/0097 \[963\], and XCU/TC2-2008/0098 \[942\] are applied.
383
+
+97
docs/posix2018/false.md
+97
docs/posix2018/false.md
···
1
+
#### []{#tag_20_43_01}NAME {#name .mansect}
2
+
3
+
> false - return false value
4
+
5
+
#### []{#tag_20_43_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `false`
8
+
9
+
#### []{#tag_20_43_03}DESCRIPTION {#description .mansect}
10
+
11
+
> The *false* utility shall return with a non-zero exit code.
12
+
13
+
#### []{#tag_20_43_04}OPTIONS {#options .mansect}
14
+
15
+
> None.
16
+
17
+
#### []{#tag_20_43_05}OPERANDS {#operands .mansect}
18
+
19
+
> None.
20
+
21
+
#### []{#tag_20_43_06}STDIN {#stdin .mansect}
22
+
23
+
> Not used.
24
+
25
+
#### []{#tag_20_43_07}INPUT FILES {#input-files .mansect}
26
+
27
+
> None.
28
+
29
+
#### []{#tag_20_43_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
30
+
31
+
> None.
32
+
33
+
#### []{#tag_20_43_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
34
+
35
+
> Default.
36
+
37
+
#### []{#tag_20_43_10}STDOUT {#stdout .mansect}
38
+
39
+
> Not used.
40
+
41
+
#### []{#tag_20_43_11}STDERR {#stderr .mansect}
42
+
43
+
> Not used.
44
+
45
+
#### []{#tag_20_43_12}OUTPUT FILES {#output-files .mansect}
46
+
47
+
> None.
48
+
49
+
#### []{#tag_20_43_13}EXTENDED DESCRIPTION {#extended-description .mansect}
50
+
51
+
> None.
52
+
53
+
#### []{#tag_20_43_14}EXIT STATUS {#exit-status .mansect}
54
+
55
+
> The *false* utility shall always exit with a value other than zero.
56
+
57
+
#### []{#tag_20_43_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
58
+
59
+
> Default.
60
+
61
+
------------------------------------------------------------------------
62
+
63
+
::: box
64
+
*The following sections are informative.*
65
+
:::
66
+
67
+
#### []{#tag_20_43_16}APPLICATION USAGE {#application-usage .mansect}
68
+
69
+
> None.
70
+
71
+
#### []{#tag_20_43_17}EXAMPLES {#examples .mansect}
72
+
73
+
> None.
74
+
75
+
#### []{#tag_20_43_18}RATIONALE {#rationale .mansect}
76
+
77
+
> None.
78
+
79
+
#### []{#tag_20_43_19}FUTURE DIRECTIONS {#future-directions .mansect}
80
+
81
+
> None.
82
+
83
+
#### []{#tag_20_43_20}SEE ALSO {#see-also .mansect}
84
+
85
+
> [*true*](../utilities/true.html#)
86
+
87
+
#### []{#tag_20_43_21}CHANGE HISTORY {#change-history .mansect}
88
+
89
+
> First released in Issue 2.
90
+
91
+
#### []{#tag_20_43_22}Issue 6 {#issue-6 .mansect}
92
+
93
+
> IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/24 is applied,
94
+
> changing the STDERR section from \`\`None.\'\' to \`\`Not used.\'\'
95
+
> for alignment with [*Utility Description
96
+
> Defaults*](../utilities/V3_chap01.html#tag_17_04).
97
+
+611
docs/posix2018/file.md
+611
docs/posix2018/file.md
···
1
+
#### []{#tag_20_46_01}NAME {#name .mansect}
2
+
3
+
> file - determine file type
4
+
5
+
#### []{#tag_20_46_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `file`` `**`[`**`-dh`**`] [`**`-M`` `*`file`***`] [`**`-m`` `*`file`***`]`**` `*`file`*`...`\
8
+
> \
9
+
> `file -i`` `**`[`**`-h`**`]`**` `*`file`*`...`\
10
+
11
+
#### []{#tag_20_46_03}DESCRIPTION {#description .mansect}
12
+
13
+
> The *file* utility shall perform a series of tests in sequence on each
14
+
> specified *file* in an attempt to classify it:
15
+
>
16
+
> 1. If *file* does not exist, cannot be read, or its file status could
17
+
> not be determined, the output shall indicate that the file was
18
+
> processed, but that its type could not be determined.
19
+
>
20
+
> 2. If the file is not a regular file, its file type shall be
21
+
> identified. The file types directory, FIFO, socket, block special,
22
+
> and character special shall be identified as such. Other
23
+
> implementation-defined file types may also be identified. If
24
+
> *file* is a symbolic link, by default the link shall be resolved
25
+
> and *file* shall test the type of file referenced by the symbolic
26
+
> link. (See the **-h** and **-i** options below.)
27
+
>
28
+
> 3. If the length of *file* is zero, it shall be identified as an
29
+
> empty file.
30
+
>
31
+
> 4. The *file* utility shall examine an initial segment of *file* and
32
+
> shall make a guess at identifying its contents based on
33
+
> position-sensitive tests. (The answer is not guaranteed to be
34
+
> correct; see the **-d**, **-M**, and **-m** options below.)
35
+
>
36
+
> 5. The *file* utility shall examine *file* and make a guess at
37
+
> identifying its contents based on context-sensitive default system
38
+
> tests. (The answer is not guaranteed to be correct.)
39
+
>
40
+
> 6. The file shall be identified as a data file.
41
+
>
42
+
> If *file* does not exist, cannot be read, or its file status could not
43
+
> be determined, the output shall indicate that the file was processed,
44
+
> but that its type could not be determined.
45
+
>
46
+
> If *file* is a symbolic link, by default the link shall be resolved
47
+
> and *file* shall test the type of file referenced by the symbolic
48
+
> link.
49
+
50
+
#### []{#tag_20_46_04}OPTIONS {#options .mansect}
51
+
52
+
> The *file* utility shall conform to XBD [*Utility Syntax
53
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02) , except that the
54
+
> order of the **-m**, **-d**, and **-M** options shall be significant.
55
+
>
56
+
> The following options shall be supported by the implementation:
57
+
>
58
+
> **-d**
59
+
> : Apply any position-sensitive default system tests and
60
+
> context-sensitive default system tests to the file. This is the
61
+
> default if no **-M** or **-m** option is specified.
62
+
>
63
+
> **-h**
64
+
> : When a symbolic link is encountered, identify the file as a
65
+
> symbolic link. If **-h** is not specified and *file* is a symbolic
66
+
> link that refers to a nonexistent file, *file* shall identify the
67
+
> file as a symbolic link, as if **-h** had been specified.
68
+
>
69
+
> **-i**
70
+
> : If a file is a regular file, do not attempt to classify the type
71
+
> of the file further, but identify the file as specified in the
72
+
> STDOUT section.
73
+
>
74
+
> **-M ** *file*
75
+
> : Specify the name of a file containing position-sensitive tests
76
+
> that shall be applied to a file in order to classify it (see the
77
+
> EXTENDED DESCRIPTION). No position-sensitive default system tests
78
+
> nor context-sensitive default system tests shall be applied unless
79
+
> the **-d** option is also specified.
80
+
>
81
+
> **-m ** *file*
82
+
> : Specify the name of a file containing position-sensitive tests
83
+
> that shall be applied to a file in order to classify it (see the
84
+
> EXTENDED DESCRIPTION).
85
+
>
86
+
> If the **-m** option is specified without specifying the **-d** option
87
+
> or the **-M** option, position-sensitive default system tests shall be
88
+
> applied after the position-sensitive tests specified by the **-m**
89
+
> option. If the **-M** option is specified with the **-d** option, the
90
+
> **-m** option, or both, or the **-m** option is specified with the
91
+
> **-d** option, the concatenation of the position-sensitive tests
92
+
> specified by these options shall be applied in the order specified by
93
+
> the appearance of these options. If a **-M** or **-m** *file*
94
+
> option-argument is **-**, the results are unspecified.
95
+
96
+
#### []{#tag_20_46_05}OPERANDS {#operands .mansect}
97
+
98
+
> The following operand shall be supported:
99
+
>
100
+
> *file*
101
+
> : A pathname of a file to be tested.
102
+
103
+
#### []{#tag_20_46_06}STDIN {#stdin .mansect}
104
+
105
+
> The standard input shall be used if a *file* operand is `'-'` and the
106
+
> implementation treats the `'-'` as meaning standard input. Otherwise,
107
+
> the standard input shall not be used.
108
+
109
+
#### []{#tag_20_46_07}INPUT FILES {#input-files .mansect}
110
+
111
+
> The *file* can be any file type.
112
+
113
+
#### []{#tag_20_46_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
114
+
115
+
> The following environment variables shall affect the execution of
116
+
> *file*:
117
+
>
118
+
> *LANG*
119
+
> : Provide a default value for the internationalization variables
120
+
> that are unset or null. (See XBD [*Internationalization
121
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
122
+
> precedence of internationalization variables used to determine the
123
+
> values of locale categories.)
124
+
>
125
+
> *LC_ALL*
126
+
> : If set to a non-empty string value, override the values of all the
127
+
> other internationalization variables.
128
+
>
129
+
> *LC_CTYPE*
130
+
> : Determine the locale for the interpretation of sequences of bytes
131
+
> of text data as characters (for example, single-byte as opposed to
132
+
> multi-byte characters in arguments and input files).
133
+
>
134
+
> *LC_MESSAGES*
135
+
> : Determine the locale that should be used to affect the format and
136
+
> contents of diagnostic messages written to standard error and
137
+
> informative messages written to standard output.
138
+
>
139
+
> *NLSPATH*
140
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
141
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
142
+
> location of message catalogs for the processing of *LC_MESSAGES.*
143
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
144
+
145
+
#### []{#tag_20_46_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
146
+
147
+
> Default.
148
+
149
+
#### []{#tag_20_46_10}STDOUT {#stdout .mansect}
150
+
151
+
> In the POSIX locale, the following format shall be used to identify
152
+
> each operand, *file* specified:
153
+
>
154
+
>
155
+
> "%s: %s\n", <file>, <type>
156
+
>
157
+
> The values for \<*type*\> are unspecified, except that in the POSIX
158
+
> locale, if *file* is identified as one of the types listed in the
159
+
> following table, \<*type*\> shall contain (but is not limited to) the
160
+
> corresponding string, unless the file is identified by a
161
+
> position-sensitive test specified by a **-M** or **-m** option. Each
162
+
> \<space\> shown in the strings shall be exactly one \<space\>.\
163
+
>
164
+
> **[]{#tagtcjh_27} Table: File Utility Output Strings**
165
+
>
166
+
> **If *file* is:** **\<*type*\> shall contain the string:** **Notes**
167
+
> ------------------------------------------------ ------------------------------------------ -----------
168
+
> Nonexistent cannot open
169
+
> Block special block special 1
170
+
> Character special character special 1
171
+
> Directory directory 1
172
+
> FIFO fifo 1
173
+
> Socket socket 1
174
+
> Symbolic link symbolic link to 1
175
+
> Regular file regular file 1,2
176
+
> Empty regular file empty 3
177
+
> Regular file that cannot be read cannot open 3
178
+
> Executable binary executable 3,4,6
179
+
> *ar* archive library (see *ar*) archive 3,4,6
180
+
> Extended *cpio* format (see *pax*) cpio archive 3,4,6
181
+
> Extended *tar* format (see **ustar** in *pax*) tar archive 3,4,6
182
+
> Shell script commands text 3,5,6
183
+
> C-language source c program text 3,5,6
184
+
> FORTRAN source fortran program text 3,5,6
185
+
> Regular file whose type cannot be determined data 3
186
+
>
187
+
> **Notes:**
188
+
>
189
+
> : 1. This is a file type test.
190
+
>
191
+
> 2. This test is applied only if the **-i** option is specified.
192
+
>
193
+
> 3. This test is applied only if the **-i** option is not
194
+
> specified.
195
+
>
196
+
> 4. This is a position-sensitive default system test.
197
+
>
198
+
> 5. This is a context-sensitive default system test.
199
+
>
200
+
> 6. Position-sensitive default system tests and context-sensitive
201
+
> default system tests are not applied if the **-M** option is
202
+
> specified unless the **-d** option is also specified.
203
+
>
204
+
> In the POSIX locale, if *file* is identified as a symbolic link (see
205
+
> the **-h** option), the following alternative output format shall be
206
+
> used:
207
+
>
208
+
>
209
+
> "%s: %s %s\n", <file>, <type>, <contents of link>"
210
+
>
211
+
> If the file named by the *file* operand does not exist, cannot be
212
+
> read, or the type of the file named by the *file* operand cannot be
213
+
> determined, this shall not be considered an error that affects the
214
+
> exit status.
215
+
216
+
#### []{#tag_20_46_11}STDERR {#stderr .mansect}
217
+
218
+
> The standard error shall be used only for diagnostic messages.
219
+
220
+
#### []{#tag_20_46_12}OUTPUT FILES {#output-files .mansect}
221
+
222
+
> None.
223
+
224
+
#### []{#tag_20_46_13}EXTENDED DESCRIPTION {#extended-description .mansect}
225
+
226
+
> A file specified as an option-argument to the **-m** or **-M** options
227
+
> shall contain one position-sensitive test per line, which shall be
228
+
> applied to the file. If the test succeeds, the message field of the
229
+
> line shall be printed and no further tests shall be applied, with the
230
+
> exception that tests on immediately following lines beginning with a
231
+
> single `'>'` character shall be applied.
232
+
>
233
+
> Each line shall be composed of the following four \<tab\>-separated
234
+
> fields. (Implementations may allow any combination of one or more
235
+
> white-space characters other than \<newline\> to act as field
236
+
> separators.)
237
+
>
238
+
> *offset*
239
+
>
240
+
> : An unsigned number (optionally preceded by a single `'>'`
241
+
> character) specifying the *offset*, in bytes, of the value in the
242
+
> file that is to be compared against the *value* field of the line.
243
+
> If the file is shorter than the specified offset, the test shall
244
+
> fail.
245
+
>
246
+
> If the *offset* begins with the character `'>'`, the test
247
+
> contained in the line shall not be applied to the file unless the
248
+
> test on the last line for which the *offset* did not begin with a
249
+
> `'>'` was successful. By default, the *offset* shall be
250
+
> interpreted as an unsigned decimal number. With a leading 0x or
251
+
> 0X, the *offset* shall be interpreted as a hexadecimal number;
252
+
> otherwise, with a leading 0, the *offset* shall be interpreted as
253
+
> an octal number.
254
+
>
255
+
> *type*
256
+
>
257
+
> : The type of the value in the file to be tested. The type shall
258
+
> consist of the type specification characters `d`, `s`, and `u`,
259
+
> specifying signed decimal, string, and unsigned decimal,
260
+
> respectively.
261
+
>
262
+
> The *type* string shall be interpreted as the bytes from the file
263
+
> starting at the specified *offset* and including the same number
264
+
> of bytes specified by the *value* field. If insufficient bytes
265
+
> remain in the file past the *offset* to match the *value* field,
266
+
> the test shall fail.
267
+
>
268
+
> The type specification characters `d` and `u` can be followed by
269
+
> an optional unsigned decimal integer that specifies the number of
270
+
> bytes represented by the type. The type specification characters
271
+
> `d` and `u` can be followed by an optional `C`, `S`, `I`, or `L`,
272
+
> indicating that the value is of type **char**, **short**, **int**,
273
+
> or **long**, respectively.
274
+
>
275
+
> The default number of bytes represented by the type specifiers
276
+
> `d`, `f`, and `u` shall correspond to their respective C-language
277
+
> types as follows. If the system claims conformance to the
278
+
> C-Language Development Utilities option, those specifiers shall
279
+
> correspond to the default sizes used in the
280
+
> [*c99*](../utilities/c99.html) utility. Otherwise, the default
281
+
> sizes shall be implementation-defined.
282
+
>
283
+
> For the type specifier characters `d` and `u`, the default number
284
+
> of bytes shall correspond to the size of a basic integer type of
285
+
> the implementation. For these specifier characters, the
286
+
> implementation shall support values of the optional number of
287
+
> bytes to be converted corresponding to the number of bytes in the
288
+
> C-language types **char**, **short**, **int**, or **long**. These
289
+
> numbers can also be specified by an application as the characters
290
+
> `C`, `S`, `I`, and `L`, respectively. The byte order used when
291
+
> interpreting numeric values is implementation-defined, but shall
292
+
> correspond to the order in which a constant of the corresponding
293
+
> type is stored in memory on the system.
294
+
>
295
+
> All type specifiers, except for `s`, can be followed by a mask
296
+
> specifier of the form &*number*. The mask value shall be AND\'ed
297
+
> with the value of the input file before the comparison with the
298
+
> *value* field of the line is made. By default, the mask shall be
299
+
> interpreted as an unsigned decimal number. With a leading 0x or
300
+
> 0X, the mask shall be interpreted as an unsigned hexadecimal
301
+
> number; otherwise, with a leading 0, the mask shall be interpreted
302
+
> as an unsigned octal number.
303
+
>
304
+
> The strings **byte**, **short**, **long**, and **string** shall
305
+
> also be supported as type fields, being interpreted as `dC`, `dS`,
306
+
> `dL`, and `s`, respectively.
307
+
>
308
+
> *value*
309
+
>
310
+
> : The *value* to be compared with the value from the file.
311
+
>
312
+
> If the specifier from the type field is `s` or **string**, then
313
+
> interpret the value as a string. Otherwise, interpret it as a
314
+
> number. If the value is a string, then the test shall succeed only
315
+
> when a string value exactly matches the bytes from the file.
316
+
>
317
+
> If the *value* is a string, it can contain the following
318
+
> sequences:
319
+
>
320
+
> \\*character*
321
+
> : The \<backslash\>-escape sequences as specified in XBD
322
+
> [*Escape Sequences and Associated
323
+
> Actions*](../basedefs/V1_chap05.html#tagtcjh_2) ( `'\\'`,
324
+
> `'\a'`, `'\b'`, `'\f'`, `'\n'`, `'\r'`, `'\t'`, `'\v'` ). In
325
+
> addition, the escape sequence `'\ '` (the \<backslash\>
326
+
> character followed by a \<space\> character) shall be
327
+
> recognized to represent a \<space\> character. The results of
328
+
> using any other character, other than an octal digit,
329
+
> following the \<backslash\> are unspecified.
330
+
>
331
+
> \\*octal*
332
+
> : Octal sequences that can be used to represent characters with
333
+
> specific coded values. An octal sequence shall consist of a
334
+
> \<backslash\> followed by the longest sequence of one, two, or
335
+
> three octal-digit characters (01234567).
336
+
>
337
+
> By default, any value that is not a string shall be interpreted as
338
+
> a signed decimal number. Any such value, with a leading 0x or 0X,
339
+
> shall be interpreted as an unsigned hexadecimal number; otherwise,
340
+
> with a leading zero, the value shall be interpreted as an unsigned
341
+
> octal number.
342
+
>
343
+
> If the value is not a string, it can be preceded by a character
344
+
> indicating the comparison to be performed. Permissible characters
345
+
> and the comparisons they specify are as follows:
346
+
>
347
+
> `=`
348
+
> : The test shall succeed if the value from the file equals the
349
+
> *value* field.
350
+
>
351
+
> `<`
352
+
> : The test shall succeed if the value from the file is less than
353
+
> the *value* field.
354
+
>
355
+
> `>`
356
+
> : The test shall succeed if the value from the file is greater
357
+
> than the *value* field.
358
+
>
359
+
> `&`
360
+
> : The test shall succeed if all of the set bits in the *value*
361
+
> field are set in the value from the file.
362
+
>
363
+
> `^`
364
+
> : The test shall succeed if at least one of the set bits in the
365
+
> *value* field is not set in the value from the file.
366
+
>
367
+
> `x`
368
+
> : The test shall succeed if the file is large enough to contain
369
+
> a value of the type specified starting at the offset
370
+
> specified.
371
+
>
372
+
> *message*
373
+
> : The *message* to be printed if the test succeeds. The *message*
374
+
> shall be interpreted using the notation for the
375
+
> [*printf*](../utilities/printf.html) formatting specification; see
376
+
> [*printf*](../utilities/printf.html). If the *value* field was a
377
+
> string, then the value from the file shall be the argument for the
378
+
> [*printf*](../utilities/printf.html) formatting specification;
379
+
> otherwise, the value from the file shall be the argument.
380
+
>
381
+
> \
382
+
383
+
#### []{#tag_20_46_14}EXIT STATUS {#exit-status .mansect}
384
+
385
+
> The following exit values shall be returned:
386
+
>
387
+
> 0
388
+
> : Successful completion.
389
+
>
390
+
> \>0
391
+
> : An error occurred.
392
+
393
+
#### []{#tag_20_46_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
394
+
395
+
> Default.
396
+
397
+
------------------------------------------------------------------------
398
+
399
+
::: box
400
+
*The following sections are informative.*
401
+
:::
402
+
403
+
#### []{#tag_20_46_16}APPLICATION USAGE {#application-usage .mansect}
404
+
405
+
> The *file* utility can only be required to guess at many of the file
406
+
> types because only exhaustive testing can determine some types with
407
+
> certainty. For example, binary data on some implementations might
408
+
> match the initial segment of an executable or a *tar* archive.
409
+
>
410
+
> Note that the table indicates that the output contains the stated
411
+
> string. Systems may add text before or after the string. For
412
+
> executables, as an example, the machine architecture and various facts
413
+
> about how the file was link-edited may be included. Note also that on
414
+
> systems that recognize shell script files starting with `"#!"` as
415
+
> executable files, these may be identified as executable binary files
416
+
> rather than as shell scripts.
417
+
418
+
#### []{#tag_20_46_17}EXAMPLES {#examples .mansect}
419
+
420
+
> Determine whether an argument is a binary executable file:
421
+
>
422
+
>
423
+
> file -- "$1" | grep -q ':.*executable' &&
424
+
> printf "%s is executable.\n" "$1"
425
+
426
+
#### []{#tag_20_46_18}RATIONALE {#rationale .mansect}
427
+
428
+
> The **-f** option was omitted because the same effect can (and should)
429
+
> be obtained using the [*xargs*](../utilities/xargs.html) utility.
430
+
>
431
+
> Historical versions of the *file* utility attempt to identify the
432
+
> following types of files: symbolic link, directory, character special,
433
+
> block special, socket, *tar* archive, *cpio* archive, SCCS archive,
434
+
> archive library, empty, [*compress*](../utilities/compress.html)
435
+
> output, *pack* output, binary data, C source, FORTRAN source,
436
+
> assembler source, *nroff*/ *troff*/ *eqn*/ *tbl* source *troff*
437
+
> output, shell script, C shell script, English text, ASCII text,
438
+
> various executables, APL workspace, compiled terminfo entries, and
439
+
> CURSES screen images. Only those types that are reasonably well
440
+
> specified in POSIX or are directly related to POSIX utilities are
441
+
> listed in the table.
442
+
>
443
+
> Historical systems have used a \"magic file\" named **/etc/magic** to
444
+
> help identify file types. Because it is generally useful for users and
445
+
> scripts to be able to identify special file types, the **-m** flag and
446
+
> a portable format for user-created magic files has been specified. No
447
+
> requirement is made that an implementation of *file* use this method
448
+
> of identifying files, only that users be permitted to add their own
449
+
> classifying tests.
450
+
>
451
+
> In addition, three options have been added to historical practice. The
452
+
> **-d** flag has been added to permit users to cause their tests to
453
+
> follow any default system tests. The **-i** flag has been added to
454
+
> permit users to test portably for regular files in shell scripts. The
455
+
> **-M** flag has been added to permit users to ignore any default
456
+
> system tests.
457
+
>
458
+
> The POSIX.1-2017 description of default system tests and the
459
+
> interaction between the **-d**, **-M**, and **-m** options did not
460
+
> clearly indicate that there were two types of \"default system
461
+
> tests\". The \"position-sensitive tests\" determine file types by
462
+
> looking for certain string or binary values at specific offsets in the
463
+
> file being examined. These position-sensitive tests were implemented
464
+
> in historical systems using the magic file described above. Some of
465
+
> these tests are now built into the *file* utility itself on some
466
+
> implementations so the output can provide more detail than can be
467
+
> provided by magic files. For example, a magic file can easily identify
468
+
> a **core** file on most implementations, but cannot name the program
469
+
> file that dropped the core. A magic file could produce output such as:
470
+
>
471
+
>
472
+
> /home/dwc/core: ELF 32-bit MSB core file SPARC Version 1
473
+
>
474
+
> but by building the test into the *file* utility, you could get output
475
+
> such as:
476
+
>
477
+
>
478
+
> /home/dwc/core: ELF 32-bit MSB core file SPARC Version 1, from 'testprog'
479
+
>
480
+
> These extended built-in tests are still to be treated as
481
+
> position-sensitive default system tests even if they are not listed in
482
+
> **/etc/magic** or any other magic file.
483
+
>
484
+
> The context-sensitive default system tests were always built into the
485
+
> *file* utility. These tests looked for language constructs in text
486
+
> files trying to identify shell scripts, C, FORTRAN, and other computer
487
+
> language source files, and even plain text files. With the addition of
488
+
> the **-m** and **-M** options the distinction between
489
+
> position-sensitive and context-sensitive default system tests became
490
+
> important because the order of testing is important. The
491
+
> context-sensitive system default tests should never be applied before
492
+
> any position-sensitive tests even if the **-d** option is specified
493
+
> before a **-m** option or **-M** option due to the high probability
494
+
> that the context-sensitive system default tests will incorrectly
495
+
> identify arbitrary text files as text files before position-sensitive
496
+
> tests specified by the **-m** or **-M** option would be applied to
497
+
> give a more accurate identification.
498
+
>
499
+
> Leaving the meaning of **-M -** and **-m -** unspecified allows an
500
+
> existing prototype of these options to continue to work in a
501
+
> backwards-compatible manner. (In that implementation, **-M -** was
502
+
> roughly equivalent to **-d** in POSIX.1-2017.)
503
+
>
504
+
> The historical **-c** option was omitted as not particularly useful to
505
+
> users or portable shell scripts. In addition, a reasonable
506
+
> implementation of the *file* utility would report any errors found
507
+
> each time the magic file is read.
508
+
>
509
+
> The historical format of the magic file was the same as that specified
510
+
> by the Rationale in the ISO POSIX-2:1993 standard for the *offset*,
511
+
> *value*, and *message* fields; however, it used less precise type
512
+
> fields than the format specified by the current normative text. The
513
+
> new type field values are a superset of the historical ones.
514
+
>
515
+
> The following is an example magic file:
516
+
>
517
+
>
518
+
> 0 short 070707 cpio archive
519
+
> 0 short 0143561 Byte-swapped cpio archive
520
+
> 0 string 070707 ASCII cpio archive
521
+
> 0 long 0177555 Very old archive
522
+
> 0 short 0177545 Old archive
523
+
> 0 short 017437 Old packed data
524
+
> 0 string \037\036 Packed data
525
+
> 0 string \377\037 Compacted data
526
+
> 0 string \037\235 Compressed data
527
+
> >2 byte&0x80 >0 Block compressed
528
+
> >2 byte&0x1f x %d bits
529
+
> 0 string \032\001 Compiled Terminfo Entry
530
+
> 0 short 0433 Curses screen image
531
+
> 0 short 0434 Curses screen image
532
+
> 0 string <ar> System V Release 1 archive
533
+
> 0 string !<arch>\n__.SYMDEF Archive random library
534
+
> 0 string !<arch> Archive
535
+
> 0 string ARF_BEGARF PHIGS clear text archive
536
+
> 0 long 0x137A2950 Scalable OpenFont binary
537
+
> 0 long 0x137A2951 Encrypted scalable OpenFont binary
538
+
>
539
+
> The use of a basic integer data type is intended to allow the
540
+
> implementation to choose a word size commonly used by applications on
541
+
> that architecture.
542
+
>
543
+
> Earlier versions of this standard allowed for implementations with
544
+
> bytes other than eight bits, but this has been modified in this
545
+
> version.
546
+
547
+
#### []{#tag_20_46_19}FUTURE DIRECTIONS {#future-directions .mansect}
548
+
549
+
> None.
550
+
551
+
#### []{#tag_20_46_20}SEE ALSO {#see-also .mansect}
552
+
553
+
> [*ar*](../utilities/ar.html#), [*ls*](../utilities/ls.html#),
554
+
> [*pax*](../utilities/pax.html#),
555
+
> [*printf*](../utilities/printf.html#tag_20_94)
556
+
>
557
+
> XBD [*Escape Sequences and Associated
558
+
> Actions*](../basedefs/V1_chap05.html#tagtcjh_2), [*Environment
559
+
> Variables*](../basedefs/V1_chap08.html#tag_08), [*Utility Syntax
560
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02)
561
+
562
+
#### []{#tag_20_46_21}CHANGE HISTORY {#change-history .mansect}
563
+
564
+
> First released in Issue 4.
565
+
566
+
#### []{#tag_20_46_22}Issue 6 {#issue-6 .mansect}
567
+
568
+
> This utility is marked as part of the User Portability Utilities
569
+
> option.
570
+
>
571
+
> Options and an EXTENDED DESCRIPTION are added as specified in the
572
+
> IEEE P1003.2b draft standard.
573
+
>
574
+
> IEEE PASC Interpretations 1003.2 #192 and #178 are applied.
575
+
>
576
+
> IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/25 is applied, making
577
+
> major changes to address ambiguities raised in defect reports.
578
+
>
579
+
> IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/26 is applied, making
580
+
> it clear in the OPTIONS section that the **-m**, **-d**, and **-M**
581
+
> options do not comply with Guideline 11 of the Utility Syntax
582
+
> Guidelines.
583
+
>
584
+
> IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/10 is applied,
585
+
> clarifying the specification characters.
586
+
>
587
+
> IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/11 is applied,
588
+
> allowing application developers to create portable magic files that
589
+
> can match characters in strings, and allowing common extensions found
590
+
> in existing implementations.
591
+
>
592
+
> IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/12 is applied,
593
+
> removing text describing behavior on systems with bytes consisting of
594
+
> more than eight bits.
595
+
596
+
#### []{#tag_20_46_23}Issue 7 {#issue-7 .mansect}
597
+
598
+
> Austin Group Interpretation 1003.1-2001 #092 is applied.
599
+
>
600
+
> SD5-XCU-ERN-4 is applied, adding further entries in the Notes column
601
+
> in [File Utility Output Strings](#tagtcjh_27) .
602
+
>
603
+
> SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.
604
+
>
605
+
> The *file* utility is moved from the User Portability Utilities option
606
+
> to the Base. User Portability Utilities is now an option for
607
+
> interactive utilities.
608
+
>
609
+
> The EXAMPLES section is revised to correct an error with the pathname
610
+
> `"$1"`.
611
+
+246
docs/posix2018/fold.md
+246
docs/posix2018/fold.md
···
1
+
#### []{#tag_20_48_01}NAME {#name .mansect}
2
+
3
+
> fold - filter for folding lines
4
+
5
+
#### []{#tag_20_48_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `fold`` `**`[`**`-bs`**`] [`**`-w`` `*`width`***`] [`***`file`*`...`**`]`**
8
+
9
+
#### []{#tag_20_48_03}DESCRIPTION {#description .mansect}
10
+
11
+
> The *fold* utility is a filter that shall fold lines from its input
12
+
> files, breaking the lines to have a maximum of *width* column
13
+
> positions (or bytes, if the **-b** option is specified). Lines shall
14
+
> be broken by the insertion of a \<newline\> such that each output line
15
+
> (referred to later in this section as a *segment*) is the maximum
16
+
> width possible that does not exceed the specified number of column
17
+
> positions (or bytes). A line shall not be broken in the middle of a
18
+
> character. The behavior is undefined if *width* is less than the
19
+
> number of columns any single character in the input would occupy.
20
+
>
21
+
> If the \<carriage-return\>, \<backspace\>, or \<tab\> characters are
22
+
> encountered in the input, and the **-b** option is not specified, they
23
+
> shall be treated specially:
24
+
>
25
+
> \<backspace\>
26
+
> : The current count of line width shall be decremented by one,
27
+
> although the count never shall become negative. The *fold* utility
28
+
> shall not insert a \<newline\> immediately before or after any
29
+
> \<backspace\>, unless the following character has a width greater
30
+
> than 1 and would cause the line width to exceed *width*.
31
+
>
32
+
> \<carriage-return\>
33
+
> : The current count of line width shall be set to zero. The *fold*
34
+
> utility shall not insert a \<newline\> immediately before or after
35
+
> any \<carriage-return\>.
36
+
>
37
+
> \<tab\>
38
+
> : Each \<tab\> encountered shall advance the column position pointer
39
+
> to the next tab stop. Tab stops shall be at each column position
40
+
> *n* such that *n* modulo 8 equals 1.
41
+
42
+
#### []{#tag_20_48_04}OPTIONS {#options .mansect}
43
+
44
+
> The *fold* utility shall conform to XBD [*Utility Syntax
45
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02) .
46
+
>
47
+
> The following options shall be supported:
48
+
>
49
+
> **-b**
50
+
> : Count *width* in bytes rather than column positions.
51
+
>
52
+
> **-s**
53
+
> : If a segment of a line contains a \<blank\> within the first
54
+
> *width* column positions (or bytes), break the line after the last
55
+
> such \<blank\> meeting the width constraints. If there is no
56
+
> \<blank\> meeting the requirements, the **-s** option shall have
57
+
> no effect for that output segment of the input line.
58
+
>
59
+
> **-w ** *width*
60
+
> : Specify the maximum line length, in column positions (or bytes if
61
+
> **-b** is specified). The results are unspecified if *width* is
62
+
> not a positive decimal number. The default value shall be 80.
63
+
64
+
#### []{#tag_20_48_05}OPERANDS {#operands .mansect}
65
+
66
+
> The following operand shall be supported:
67
+
>
68
+
> *file*
69
+
> : A pathname of a text file to be folded. If no *file* operands are
70
+
> specified, the standard input shall be used.
71
+
72
+
#### []{#tag_20_48_06}STDIN {#stdin .mansect}
73
+
74
+
> The standard input shall be used if no *file* operands are specified,
75
+
> and shall be used if a *file* operand is `'-'` and the implementation
76
+
> treats the `'-'` as meaning standard input. Otherwise, the standard
77
+
> input shall not be used. See the INPUT FILES section.
78
+
79
+
#### []{#tag_20_48_07}INPUT FILES {#input-files .mansect}
80
+
81
+
> If the **-b** option is specified, the input files shall be text files
82
+
> except that the lines are not limited to {LINE_MAX} bytes in length.
83
+
> If the **-b** option is not specified, the input files shall be text
84
+
> files.
85
+
86
+
#### []{#tag_20_48_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
87
+
88
+
> The following environment variables shall affect the execution of
89
+
> *fold*:
90
+
>
91
+
> *LANG*
92
+
> : Provide a default value for the internationalization variables
93
+
> that are unset or null. (See XBD [*Internationalization
94
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
95
+
> precedence of internationalization variables used to determine the
96
+
> values of locale categories.)
97
+
>
98
+
> *LC_ALL*
99
+
> : If set to a non-empty string value, override the values of all the
100
+
> other internationalization variables.
101
+
>
102
+
> *LC_CTYPE*
103
+
> : Determine the locale for the interpretation of sequences of bytes
104
+
> of text data as characters (for example, single-byte as opposed to
105
+
> multi-byte characters in arguments and input files), and for the
106
+
> determination of the width in column positions each character
107
+
> would occupy on a constant-width font output device.
108
+
>
109
+
> *LC_MESSAGES*
110
+
> : Determine the locale that should be used to affect the format and
111
+
> contents of diagnostic messages written to standard error.
112
+
>
113
+
> *NLSPATH*
114
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
115
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
116
+
> location of message catalogs for the processing of *LC_MESSAGES.*
117
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
118
+
119
+
#### []{#tag_20_48_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
120
+
121
+
> Default.
122
+
123
+
#### []{#tag_20_48_10}STDOUT {#stdout .mansect}
124
+
125
+
> The standard output shall be a file containing a sequence of
126
+
> characters whose order shall be preserved from the input files,
127
+
> possibly with inserted \<newline\> characters.
128
+
129
+
#### []{#tag_20_48_11}STDERR {#stderr .mansect}
130
+
131
+
> The standard error shall be used only for diagnostic messages.
132
+
133
+
#### []{#tag_20_48_12}OUTPUT FILES {#output-files .mansect}
134
+
135
+
> None.
136
+
137
+
#### []{#tag_20_48_13}EXTENDED DESCRIPTION {#extended-description .mansect}
138
+
139
+
> None.
140
+
141
+
#### []{#tag_20_48_14}EXIT STATUS {#exit-status .mansect}
142
+
143
+
> The following exit values shall be returned:
144
+
>
145
+
> 0
146
+
> : All input files were processed successfully.
147
+
>
148
+
> \>0
149
+
> : An error occurred.
150
+
151
+
#### []{#tag_20_48_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
152
+
153
+
> Default.
154
+
155
+
------------------------------------------------------------------------
156
+
157
+
::: box
158
+
*The following sections are informative.*
159
+
:::
160
+
161
+
#### []{#tag_20_48_16}APPLICATION USAGE {#application-usage .mansect}
162
+
163
+
> The [*cut*](../utilities/cut.html) and *fold* utilities can be used to
164
+
> create text files out of files with arbitrary line lengths. The
165
+
> [*cut*](../utilities/cut.html) utility should be used when the number
166
+
> of lines (or records) needs to remain constant. The *fold* utility
167
+
> should be used when the contents of long lines need to be kept
168
+
> contiguous.
169
+
>
170
+
> The *fold* utility is frequently used to send text files to printers
171
+
> that truncate, rather than fold, lines wider than the printer is able
172
+
> to print (usually 80 or 132 column positions).
173
+
174
+
#### []{#tag_20_48_17}EXAMPLES {#examples .mansect}
175
+
176
+
> An example invocation that submits a file of possibly long lines to
177
+
> the printer (under the assumption that the user knows the line width
178
+
> of the printer to be assigned by [*lp*](../utilities/lp.html)):
179
+
>
180
+
>
181
+
> fold -w 132 bigfile | lp
182
+
183
+
#### []{#tag_20_48_18}RATIONALE {#rationale .mansect}
184
+
185
+
> Although terminal input in canonical processing mode requires the
186
+
> erase character (frequently set to \<backspace\>) to erase the
187
+
> previous character (not byte or column position), terminal output is
188
+
> not buffered and is extremely difficult, if not impossible, to parse
189
+
> correctly; the interpretation depends entirely on the physical device
190
+
> that actually displays/prints/stores the output. In all known
191
+
> internationalized implementations, the utilities producing output for
192
+
> mixed column-width output assume that a \<backspace\> character backs
193
+
> up one column position and outputs enough \<backspace\> characters to
194
+
> return to the start of the character when \<backspace\> is used to
195
+
> provide local line motions to support underlining and emboldening
196
+
> operations. Since *fold* without the **-b** option is dealing with
197
+
> these same constraints, \<backspace\> is always treated as backing up
198
+
> one column position rather than backing up one character.
199
+
>
200
+
> Historical versions of the *fold* utility assumed 1 byte was one
201
+
> character and occupied one column position when written out. This is
202
+
> no longer always true. Since the most common usage of *fold* is
203
+
> believed to be folding long lines for output to limited-length output
204
+
> devices, this capability was preserved as the default case. The **-b**
205
+
> option was added so that applications could *fold* files with
206
+
> arbitrary length lines into text files that could then be processed by
207
+
> the standard utilities. Note that although the width for the **-b**
208
+
> option is in bytes, a line is never split in the middle of a
209
+
> character. (It is unspecified what happens if a width is specified
210
+
> that is too small to hold a single character found in the input
211
+
> followed by a \<newline\>.)
212
+
>
213
+
> The tab stops are hardcoded to be every eighth column to meet
214
+
> historical practice. No new method of specifying other tab stops was
215
+
> invented.
216
+
217
+
#### []{#tag_20_48_19}FUTURE DIRECTIONS {#future-directions .mansect}
218
+
219
+
> None.
220
+
221
+
#### []{#tag_20_48_20}SEE ALSO {#see-also .mansect}
222
+
223
+
> [*cut*](../utilities/cut.html#)
224
+
>
225
+
> XBD [*Environment Variables*](../basedefs/V1_chap08.html#tag_08),
226
+
> [*Utility Syntax Guidelines*](../basedefs/V1_chap12.html#tag_12_02)
227
+
228
+
#### []{#tag_20_48_21}CHANGE HISTORY {#change-history .mansect}
229
+
230
+
> First released in Issue 4.
231
+
232
+
#### []{#tag_20_48_22}Issue 6 {#issue-6 .mansect}
233
+
234
+
> The normative text is reworded to avoid use of the term \"must\" for
235
+
> application requirements.
236
+
237
+
#### []{#tag_20_48_23}Issue 7 {#issue-7 .mansect}
238
+
239
+
> Austin Group Interpretation 1003.1-2001 #092 is applied.\
240
+
>
241
+
> Austin Group Interpretation 1003.1-2001 #204 is applied, updating the
242
+
> DESCRIPTION to clarify when a \<newline\> can be inserted before or
243
+
> after a \<backspace\>.
244
+
>
245
+
> SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.
246
+
+406
docs/posix2018/grep.md
+406
docs/posix2018/grep.md
···
1
+
#### []{#tag_20_55_01}NAME {#name .mansect}
2
+
3
+
> grep - search a file for a pattern
4
+
5
+
#### []{#tag_20_55_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `grep`` `**`[`**`-E|-F`**`] [`**`-c|-l|-q`**`] [`**`-insvx`**`]`**` ``-e`` `*`pattern_list`\*
8
+
> ` `` `` `**`[`**`-e`` `*`pattern_list`***`]`**`...`` `**`[`**`-f`` `*`pattern_file`***`]`**`...`` `**`[`***`file`*`...`**`]`**\
9
+
> \
10
+
> `grep`` `**`[`**`-E|-F`**`] [`**`-c|-l|-q`**`] [`**`-insvx`**`] [`**`-e`` `*`pattern_list`***`]...`\**
11
+
> ` `` `` ``-f`` `*`pattern_file`*` `**`[`**`-f`` `*`pattern_file`***`]`**`...`` `**`[`***`file`*`...`**`]`**\
12
+
> \
13
+
> `grep`` `**`[`**`-E|-F`**`] [`**`-c|-l|-q`**`] [`**`-insvx`**`]`**` `*`pattern_list`*` `**`[`***`file`*`...`**`]`**\
14
+
15
+
#### []{#tag_20_55_03}DESCRIPTION {#description .mansect}
16
+
17
+
> The *grep* utility shall search the input files, selecting lines
18
+
> matching one or more patterns; the types of patterns are controlled by
19
+
> the options specified. The patterns are specified by the **-e**
20
+
> option, **-f** option, or the *pattern_list* operand. The
21
+
> *pattern_list*\'s value shall consist of one or more patterns
22
+
> separated by \<newline\> characters; the *pattern_file*\'s contents
23
+
> shall consist of one or more patterns terminated by a \<newline\>
24
+
> character. By default, an input line shall be selected if any pattern,
25
+
> treated as an entire basic regular expression (BRE) as described in
26
+
> XBD [*Basic Regular
27
+
> Expressions*](../basedefs/V1_chap09.html#tag_09_03), matches any part
28
+
> of the line excluding the terminating \<newline\>; a null BRE shall
29
+
> match every line. By default, each selected input line shall be
30
+
> written to the standard output.
31
+
>
32
+
> Regular expression matching shall be based on text lines. Since a
33
+
> \<newline\> separates or terminates patterns (see the **-e** and
34
+
> **-f** options below), regular expressions cannot contain a
35
+
> \<newline\>. Similarly, since patterns are matched against individual
36
+
> lines (excluding the terminating \<newline\> characters) of the input,
37
+
> there is no way for a pattern to match a \<newline\> found in the
38
+
> input.
39
+
40
+
#### []{#tag_20_55_04}OPTIONS {#options .mansect}
41
+
42
+
> The *grep* utility shall conform to XBD [*Utility Syntax
43
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02) .
44
+
>
45
+
> The following options shall be supported:
46
+
>
47
+
> **-E**
48
+
> : Match using extended regular expressions. Treat each pattern
49
+
> specified as an ERE, as described in XBD [*Extended Regular
50
+
> Expressions*](../basedefs/V1_chap09.html#tag_09_04). If any entire
51
+
> ERE pattern matches some part of an input line excluding the
52
+
> terminating \<newline\>, the line shall be matched. A null ERE
53
+
> shall match every line.
54
+
>
55
+
> **-F**
56
+
> : Match using fixed strings. Treat each pattern specified as a
57
+
> string instead of a regular expression. If an input line contains
58
+
> any of the patterns as a contiguous sequence of bytes, the line
59
+
> shall be matched. A null string shall match every line.
60
+
>
61
+
> **-c**
62
+
> : Write only a count of selected lines to standard output.
63
+
>
64
+
> **-e ** *pattern_list*
65
+
> : Specify one or more patterns to be used during the search for
66
+
> input. The application shall ensure that patterns in
67
+
> *pattern_list* are separated by a \<newline\>. A null pattern can
68
+
> be specified by two adjacent \<newline\> characters in
69
+
> *pattern_list*. Unless the **-E** or **-F** option is also
70
+
> specified, each pattern shall be treated as a BRE, as described in
71
+
> XBD [*Basic Regular
72
+
> Expressions*](../basedefs/V1_chap09.html#tag_09_03). Multiple
73
+
> **-e** and **-f** options shall be accepted by the *grep* utility.
74
+
> All of the specified patterns shall be used when matching lines,
75
+
> but the order of evaluation is unspecified.
76
+
>
77
+
> **-f ** *pattern_file*
78
+
> : Read one or more patterns from the file named by the pathname
79
+
> *pattern_file*. Patterns in *pattern_file* shall be terminated by
80
+
> a \<newline\>. A null pattern can be specified by an empty line in
81
+
> *pattern_file*. Unless the **-E** or **-F** option is also
82
+
> specified, each pattern shall be treated as a BRE, as described in
83
+
> XBD [*Basic Regular
84
+
> Expressions*](../basedefs/V1_chap09.html#tag_09_03).
85
+
>
86
+
> **-i**
87
+
> : Perform pattern matching in searches without regard to case; see
88
+
> XBD [*Regular Expression General
89
+
> Requirements*](../basedefs/V1_chap09.html#tag_09_02).
90
+
>
91
+
> **-l**
92
+
> : (The letter ell.) Write only the names of files containing
93
+
> selected lines to standard output. Pathnames shall be written once
94
+
> per file searched. If the standard input is searched, a pathname
95
+
> of `"(standard input)"` shall be written, in the POSIX locale. In
96
+
> other locales, `"standard input"` may be replaced by something
97
+
> more appropriate in those locales.
98
+
>
99
+
> **-n**
100
+
> : Precede each output line by its relative line number in the file,
101
+
> each file starting at line 1. The line number counter shall be
102
+
> reset for each file processed.
103
+
>
104
+
> **-q**
105
+
> : Quiet. Nothing shall be written to the standard output, regardless
106
+
> of matching lines. Exit with zero status if an input line is
107
+
> selected.
108
+
>
109
+
> **-s**
110
+
> : Suppress the error messages ordinarily written for nonexistent or
111
+
> unreadable files. Other error messages shall not be suppressed.
112
+
>
113
+
> **-v**
114
+
> : Select lines not matching any of the specified patterns. If the
115
+
> **-v** option is not specified, selected lines shall be those that
116
+
> match any of the specified patterns.
117
+
>
118
+
> **-x**
119
+
> : Consider only input lines that use all characters in the line
120
+
> excluding the terminating \<newline\> to match an entire fixed
121
+
> string or regular expression to be matching lines.
122
+
123
+
#### []{#tag_20_55_05}OPERANDS {#operands .mansect}
124
+
125
+
> The following operands shall be supported:
126
+
>
127
+
> *pattern_list*
128
+
> : Specify one or more patterns to be used during the search for
129
+
> input. This operand shall be treated as if it were specified as
130
+
> **-e** *pattern_list*.
131
+
>
132
+
> *file*
133
+
> : A pathname of a file to be searched for the patterns. If no *file*
134
+
> operands are specified, the standard input shall be used.
135
+
136
+
#### []{#tag_20_55_06}STDIN {#stdin .mansect}
137
+
138
+
> The standard input shall be used if no *file* operands are specified,
139
+
> and shall be used if a *file* operand is `'-'` and the implementation
140
+
> treats the `'-'` as meaning standard input. Otherwise, the standard
141
+
> input shall not be used. See the INPUT FILES section.
142
+
143
+
#### []{#tag_20_55_07}INPUT FILES {#input-files .mansect}
144
+
145
+
> The input files shall be text files.
146
+
147
+
#### []{#tag_20_55_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
148
+
149
+
> The following environment variables shall affect the execution of
150
+
> *grep*:
151
+
>
152
+
> *LANG*
153
+
> : Provide a default value for the internationalization variables
154
+
> that are unset or null. (See XBD [*Internationalization
155
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
156
+
> precedence of internationalization variables used to determine the
157
+
> values of locale categories.)
158
+
>
159
+
> *LC_ALL*
160
+
> : If set to a non-empty string value, override the values of all the
161
+
> other internationalization variables.
162
+
>
163
+
> *LC_COLLATE*
164
+
> : Determine the locale for the behavior of ranges, equivalence
165
+
> classes, and multi-character collating elements within regular
166
+
> expressions.
167
+
>
168
+
> *LC_CTYPE*
169
+
> : Determine the locale for the interpretation of sequences of bytes
170
+
> of text data as characters (for example, single-byte as opposed to
171
+
> multi-byte characters in arguments and input files) and the
172
+
> behavior of character classes within regular expressions.
173
+
>
174
+
> *LC_MESSAGES*
175
+
> : Determine the locale that should be used to affect the format and
176
+
> contents of diagnostic messages written to standard error.
177
+
>
178
+
> *NLSPATH*
179
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
180
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
181
+
> location of message catalogs for the processing of *LC_MESSAGES.*
182
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
183
+
184
+
#### []{#tag_20_55_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
185
+
186
+
> Default.
187
+
188
+
#### []{#tag_20_55_10}STDOUT {#stdout .mansect}
189
+
190
+
> If the **-l** option is in effect, the following shall be written for
191
+
> each file containing at least one selected input line:
192
+
>
193
+
>
194
+
> "%s\n", <file>
195
+
>
196
+
> Otherwise, if more than one *file* argument appears, and **-q** is not
197
+
> specified, the *grep* utility shall prefix each output line by:
198
+
>
199
+
>
200
+
> "%s:", <file>
201
+
>
202
+
> The remainder of each output line shall depend on the other options
203
+
> specified:
204
+
>
205
+
> - If the **-c** option is in effect, the remainder of each output line
206
+
> shall contain:
207
+
>
208
+
>
209
+
> "%d\n", <count>
210
+
>
211
+
> - Otherwise, if **-c** is not in effect and the **-n** option is in
212
+
> effect, the following shall be written to standard output:
213
+
>
214
+
>
215
+
> "%d:", <line number>
216
+
>
217
+
> - Finally, the following shall be written to standard output:
218
+
>
219
+
>
220
+
> "%s", <selected-line contents>
221
+
222
+
#### []{#tag_20_55_11}STDERR {#stderr .mansect}
223
+
224
+
> The standard error shall be used only for diagnostic messages.
225
+
226
+
#### []{#tag_20_55_12}OUTPUT FILES {#output-files .mansect}
227
+
228
+
> None.
229
+
230
+
#### []{#tag_20_55_13}EXTENDED DESCRIPTION {#extended-description .mansect}
231
+
232
+
> None.
233
+
234
+
#### []{#tag_20_55_14}EXIT STATUS {#exit-status .mansect}
235
+
236
+
> The following exit values shall be returned:
237
+
>
238
+
> 0
239
+
> : One or more lines were selected.
240
+
>
241
+
> 1
242
+
> : No lines were selected.
243
+
>
244
+
> \>1
245
+
> : An error occurred.
246
+
247
+
#### []{#tag_20_55_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
248
+
249
+
> If the **-q** option is specified, the exit status shall be zero if an
250
+
> input line is selected, even if an error was detected. Otherwise,
251
+
> default actions shall be performed.
252
+
253
+
------------------------------------------------------------------------
254
+
255
+
::: box
256
+
*The following sections are informative.*
257
+
:::
258
+
259
+
#### []{#tag_20_55_16}APPLICATION USAGE {#application-usage .mansect}
260
+
261
+
> Care should be taken when using characters in *pattern_list* that may
262
+
> also be meaningful to the command interpreter. It is safest to enclose
263
+
> the entire *pattern_list* argument in single-quotes:
264
+
>
265
+
>
266
+
> '...'
267
+
>
268
+
> The **-e** *pattern_list* option has the same effect as the
269
+
> *pattern_list* operand, but is useful when *pattern_list* begins with
270
+
> the \<hyphen-minus\> delimiter. It is also useful when it is more
271
+
> convenient to provide multiple patterns as separate arguments.
272
+
>
273
+
> Multiple **-e** and **-f** options are accepted and *grep* uses all of
274
+
> the patterns it is given while matching input text lines. (Note that
275
+
> the order of evaluation is not specified. If an implementation finds a
276
+
> null string as a pattern, it is allowed to use that pattern first,
277
+
> matching every line, and effectively ignore any other patterns.)
278
+
>
279
+
> The **-q** option provides a means of easily determining whether or
280
+
> not a pattern (or string) exists in a group of files. When searching
281
+
> several files, it provides a performance improvement (because it can
282
+
> quit as soon as it finds the first match) and requires less care by
283
+
> the user in choosing the set of files to supply as arguments (because
284
+
> it exits zero if it finds a match even if *grep* detected an access or
285
+
> read error on earlier *file* operands).
286
+
>
287
+
> When using *grep* to process pathnames, it is recommended that LC_ALL,
288
+
> or at least LC_CTYPE and LC_COLLATE, are set to POSIX or C in the
289
+
> environment, since pathnames can contain byte sequences that do not
290
+
> form valid characters in some locales, in which case the utility\'s
291
+
> behavior would be undefined. In the POSIX locale each byte is a valid
292
+
> single-byte character, and therefore this problem is avoided.
293
+
294
+
#### []{#tag_20_55_17}EXAMPLES {#examples .mansect}
295
+
296
+
> 1. To find all uses of the word `"Posix"` (in any case) in file
297
+
> **text.mm** and write with line numbers:
298
+
>
299
+
>
300
+
> grep -i -n posix text.mm
301
+
>
302
+
> 2. To find all empty lines in the standard input:
303
+
>
304
+
>
305
+
> grep ^$
306
+
>
307
+
> or:
308
+
>
309
+
>
310
+
> grep -v .
311
+
>
312
+
> 3. Both of the following commands print all lines containing strings
313
+
> `"abc"` or `"def"` or both:
314
+
>
315
+
>
316
+
> grep -E 'abc|def'
317
+
>
318
+
>
319
+
> grep -F 'abc
320
+
> def'
321
+
>
322
+
> 4. Both of the following commands print all lines matching exactly
323
+
> `"abc"` or `"def"` :
324
+
>
325
+
>
326
+
> grep -E '^abc$|^def$'
327
+
>
328
+
>
329
+
> grep -F -x 'abc
330
+
> def'
331
+
332
+
#### []{#tag_20_55_18}RATIONALE {#rationale .mansect}
333
+
334
+
> This *grep* has been enhanced in an upwards-compatible way to provide
335
+
> the exact functionality of the historical *egrep* and *fgrep* commands
336
+
> as well. It was the clear intention of the standard developers to
337
+
> consolidate the three *grep*s into a single command.
338
+
>
339
+
> The old *egrep* and *fgrep* commands are likely to be supported for
340
+
> many years to come as implementation extensions, allowing historical
341
+
> applications to operate unmodified.
342
+
>
343
+
> Historical implementations usually silently ignored all but one of
344
+
> multiply-specified **-e** and **-f** options, but were not consistent
345
+
> as to which specification was actually used.
346
+
>
347
+
> The **-b** option was omitted from the OPTIONS section because block
348
+
> numbers are implementation-defined.
349
+
>
350
+
> The System V restriction on using **-** to mean standard input was
351
+
> omitted.
352
+
>
353
+
> A definition of action taken when given a null BRE or ERE is
354
+
> specified. This is an error condition in some historical
355
+
> implementations.
356
+
>
357
+
> The **-l** option previously indicated that its use was undefined when
358
+
> no files were explicitly named. This behavior was historical and
359
+
> placed an unnecessary restriction on future implementations. It has
360
+
> been removed.
361
+
>
362
+
> The historical BSD *grep* **-s** option practice is easily duplicated
363
+
> by redirecting standard output to **/dev/null**. The **-s** option
364
+
> required here is from System V.
365
+
>
366
+
> The **-x** option, historically available only with *fgrep*, is
367
+
> available here for all of the non-obsolescent versions.
368
+
369
+
#### []{#tag_20_55_19}FUTURE DIRECTIONS {#future-directions .mansect}
370
+
371
+
> None.
372
+
373
+
#### []{#tag_20_55_20}SEE ALSO {#see-also .mansect}
374
+
375
+
> [*sed*](../utilities/sed.html#)
376
+
>
377
+
> XBD [*Environment Variables*](../basedefs/V1_chap08.html#tag_08),
378
+
> [*Regular Expressions*](../basedefs/V1_chap09.html#tag_09), [*Utility
379
+
> Syntax Guidelines*](../basedefs/V1_chap12.html#tag_12_02)
380
+
381
+
#### []{#tag_20_55_21}CHANGE HISTORY {#change-history .mansect}
382
+
383
+
> First released in Issue 2.
384
+
385
+
#### []{#tag_20_55_22}Issue 6 {#issue-6 .mansect}
386
+
387
+
> The Open Group Corrigendum U029/5 is applied, correcting the SYNOPSIS.
388
+
>
389
+
> The normative text is reworded to avoid use of the term \"must\" for
390
+
> application requirements.
391
+
>
392
+
> IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/28 is applied,
393
+
> correcting the examples using the *grep* **-F** option which did not
394
+
> match the normative description of the **-F** option.
395
+
396
+
#### []{#tag_20_55_23}Issue 7 {#issue-7 .mansect}
397
+
398
+
> Austin Group Interpretation 1003.1-2001 #092 is applied.
399
+
>
400
+
> SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.
401
+
>
402
+
> SD5-XCU-ERN-98 is applied, updating the STDOUT section.
403
+
>
404
+
> POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0105 \[584\] and
405
+
> XCU/TC2-2008/0106 \[663\] are applied.
406
+
+211
docs/posix2018/head.md
+211
docs/posix2018/head.md
···
1
+
#### []{#tag_20_57_01}NAME {#name .mansect}
2
+
3
+
> head - copy the first part of files
4
+
5
+
#### []{#tag_20_57_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `head`` `**`[`**`-n`` `*`number`***`] [`***`file`*`...`**`]`**
8
+
9
+
#### []{#tag_20_57_03}DESCRIPTION {#description .mansect}
10
+
11
+
> The *head* utility shall copy its input files to the standard output,
12
+
> ending the output for each file at a designated point.
13
+
>
14
+
> Copying shall end at the point in each input file indicated by the
15
+
> **-n** *number* option. The option-argument *number* shall be counted
16
+
> in units of lines.
17
+
18
+
#### []{#tag_20_57_04}OPTIONS {#options .mansect}
19
+
20
+
> The *head* utility shall conform to XBD [*Utility Syntax
21
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02) .
22
+
>
23
+
> The following option shall be supported:
24
+
>
25
+
> **-n ** *number*
26
+
> : The first *number* lines of each input file shall be copied to
27
+
> standard output. The application shall ensure that the *number*
28
+
> option-argument is a positive decimal integer.
29
+
>
30
+
> When a file contains less than *number* lines, it shall be copied to
31
+
> standard output in its entirety. This shall not be an error.
32
+
>
33
+
> If no options are specified, *head* shall act as if **-n 10** had been
34
+
> specified.
35
+
36
+
#### []{#tag_20_57_05}OPERANDS {#operands .mansect}
37
+
38
+
> The following operand shall be supported:
39
+
>
40
+
> *file*
41
+
> : A pathname of an input file. If no *file* operands are specified,
42
+
> the standard input shall be used.
43
+
44
+
#### []{#tag_20_57_06}STDIN {#stdin .mansect}
45
+
46
+
> The standard input shall be used if no *file* operands are specified,
47
+
> and shall be used if a *file* operand is `'-'` and the implementation
48
+
> treats the `'-'` as meaning standard input. Otherwise, the standard
49
+
> input shall not be used. See the INPUT FILES section.
50
+
51
+
#### []{#tag_20_57_07}INPUT FILES {#input-files .mansect}
52
+
53
+
> Input files shall be text files, but the line length is not restricted
54
+
> to {LINE_MAX} bytes.
55
+
56
+
#### []{#tag_20_57_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
57
+
58
+
> The following environment variables shall affect the execution of
59
+
> *head*:
60
+
>
61
+
> *LANG*
62
+
> : Provide a default value for the internationalization variables
63
+
> that are unset or null. (See XBD [*Internationalization
64
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
65
+
> precedence of internationalization variables used to determine the
66
+
> values of locale categories.)
67
+
>
68
+
> *LC_ALL*
69
+
> : If set to a non-empty string value, override the values of all the
70
+
> other internationalization variables.
71
+
>
72
+
> *LC_CTYPE*
73
+
> : Determine the locale for the interpretation of sequences of bytes
74
+
> of text data as characters (for example, single-byte as opposed to
75
+
> multi-byte characters in arguments and input files).
76
+
>
77
+
> *LC_MESSAGES*
78
+
> : Determine the locale that should be used to affect the format and
79
+
> contents of diagnostic messages written to standard error.
80
+
>
81
+
> *NLSPATH*
82
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
83
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
84
+
> location of message catalogs for the processing of *LC_MESSAGES.*
85
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
86
+
87
+
#### []{#tag_20_57_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
88
+
89
+
> Default.
90
+
91
+
#### []{#tag_20_57_10}STDOUT {#stdout .mansect}
92
+
93
+
> The standard output shall contain designated portions of the input
94
+
> files.
95
+
>
96
+
> If multiple *file* operands are specified, *head* shall precede the
97
+
> output for each with the header:
98
+
>
99
+
>
100
+
> "\n==> %s <==\n", <pathname>
101
+
>
102
+
> except that the first header written shall not include the initial
103
+
> \<newline\>.
104
+
105
+
#### []{#tag_20_57_11}STDERR {#stderr .mansect}
106
+
107
+
> The standard error shall be used only for diagnostic messages.
108
+
109
+
#### []{#tag_20_57_12}OUTPUT FILES {#output-files .mansect}
110
+
111
+
> None.
112
+
113
+
#### []{#tag_20_57_13}EXTENDED DESCRIPTION {#extended-description .mansect}
114
+
115
+
> None.
116
+
117
+
#### []{#tag_20_57_14}EXIT STATUS {#exit-status .mansect}
118
+
119
+
> The following exit values shall be returned:
120
+
>
121
+
> 0
122
+
> : Successful completion.
123
+
>
124
+
> \>0
125
+
> : An error occurred.
126
+
127
+
#### []{#tag_20_57_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
128
+
129
+
> Default.
130
+
131
+
------------------------------------------------------------------------
132
+
133
+
::: box
134
+
*The following sections are informative.*
135
+
:::
136
+
137
+
#### []{#tag_20_57_16}APPLICATION USAGE {#application-usage .mansect}
138
+
139
+
> When using *head* to process pathnames, it is recommended that LC_ALL,
140
+
> or at least LC_CTYPE and LC_COLLATE, are set to POSIX or C in the
141
+
> environment, since pathnames can contain byte sequences that do not
142
+
> form valid characters in some locales, in which case the utility\'s
143
+
> behavior would be undefined. In the POSIX locale each byte is a valid
144
+
> single-byte character, and therefore this problem is avoided.
145
+
146
+
#### []{#tag_20_57_17}EXAMPLES {#examples .mansect}
147
+
148
+
> To write the first ten lines of all files (except those with a leading
149
+
> period) in the directory:
150
+
>
151
+
>
152
+
> head -- *
153
+
154
+
#### []{#tag_20_57_18}RATIONALE {#rationale .mansect}
155
+
156
+
> Although it is possible to simulate *head* with
157
+
> [*sed*](../utilities/sed.html) 10q for a single file, the standard
158
+
> developers decided that the popularity of *head* on historical BSD
159
+
> systems warranted its inclusion alongside
160
+
> [*tail*](../utilities/tail.html).
161
+
>
162
+
> POSIX.1-2017 version of *head* follows the Utility Syntax Guidelines.
163
+
> The **-n** option was added to this new interface so that *head* and
164
+
> [*tail*](../utilities/tail.html) would be more logically related.
165
+
> Earlier versions of this standard allowed a **-number** option. This
166
+
> form is no longer specified by POSIX.1-2017 but may be present in some
167
+
> implementations.
168
+
>
169
+
> There is no **-c** option (as there is in
170
+
> [*tail*](../utilities/tail.html)) because it is not historical
171
+
> practice and because other utilities in this volume of POSIX.1-2017
172
+
> provide similar functionality.
173
+
174
+
#### []{#tag_20_57_19}FUTURE DIRECTIONS {#future-directions .mansect}
175
+
176
+
> None.
177
+
178
+
#### []{#tag_20_57_20}SEE ALSO {#see-also .mansect}
179
+
180
+
> [*sed*](../utilities/sed.html#), [*tail*](../utilities/tail.html#)
181
+
>
182
+
> XBD [*Environment Variables*](../basedefs/V1_chap08.html#tag_08),
183
+
> [*Utility Syntax Guidelines*](../basedefs/V1_chap12.html#tag_12_02)
184
+
185
+
#### []{#tag_20_57_21}CHANGE HISTORY {#change-history .mansect}
186
+
187
+
> First released in Issue 4.
188
+
189
+
#### []{#tag_20_57_22}Issue 6 {#issue-6 .mansect}
190
+
191
+
> The obsolescent **-number** form is removed.
192
+
>
193
+
> The normative text is reworded to avoid use of the term \"must\" for
194
+
> application requirements.
195
+
>
196
+
> The DESCRIPTION is updated to clarify that when a file contains less
197
+
> than the number of lines requested, the entire file is copied to
198
+
> standard output.
199
+
200
+
#### []{#tag_20_57_23}Issue 7 {#issue-7 .mansect}
201
+
202
+
> Austin Group Interpretations 1003.1-2001 #027 and #092 are applied.
203
+
>
204
+
> SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.
205
+
>
206
+
> The APPLICATION USAGE section is removed and the EXAMPLES section is
207
+
> corrected.
208
+
>
209
+
> POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0107 \[663\] is
210
+
> applied.
211
+
+398
docs/posix2018/join.md
+398
docs/posix2018/join.md
···
1
+
#### []{#tag_20_63_01}NAME {#name .mansect}
2
+
3
+
> join - relational database operator
4
+
5
+
#### []{#tag_20_63_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `join`` `**`[`**`-a`` `*`file_number`*`|-v`` `*`file_number`***`] [`**`-e`` `*`string`***`] [`**`-o`` `*`list`***`] [`**`-t`` `*`char`***`]`\**
8
+
> ` `` `` `**`[`**`-1`` `*`field`***`] [`**`-2`` `*`field`***`]`**` `*`file1 file2`*
9
+
10
+
#### []{#tag_20_63_03}DESCRIPTION {#description .mansect}
11
+
12
+
> The *join* utility shall perform an equality join on the files *file1*
13
+
> and *file2*. The joined files shall be written to the standard output.
14
+
>
15
+
> The join field is a field in each file on which the files are
16
+
> compared. The *join* utility shall write one line in the output for
17
+
> each pair of lines in *file1* and *file2* that have join fields that
18
+
> collate equally. The output line by default shall consist of the join
19
+
> field, then the remaining fields from *file1*, then the remaining
20
+
> fields from *file2*. This format can be changed by using the **-o**
21
+
> option (see below). The **-a** option can be used to add unmatched
22
+
> lines to the output. The **-v** option can be used to output only
23
+
> unmatched lines.
24
+
>
25
+
> The files *file1* and *file2* shall be ordered in the collating
26
+
> sequence of [*sort*](../utilities/sort.html) **-b** on the fields on
27
+
> which they shall be joined, by default the first in each line. All
28
+
> selected output shall be written in the same collating sequence.
29
+
>
30
+
> The default input field separators shall be \<blank\> characters. In
31
+
> this case, multiple separators shall count as one field separator, and
32
+
> leading separators shall be ignored. The default output field
33
+
> separator shall be a \<space\>.
34
+
>
35
+
> The field separator and collating sequence can be changed by using the
36
+
> **-t** option (see below).
37
+
>
38
+
> If the same key appears more than once in either file, all
39
+
> combinations of the set of remaining fields in *file1* and the set of
40
+
> remaining fields in *file2* are output in the order of the lines
41
+
> encountered.
42
+
>
43
+
> If the input files are not in the appropriate collating sequence, the
44
+
> results are unspecified.
45
+
46
+
#### []{#tag_20_63_04}OPTIONS {#options .mansect}
47
+
48
+
> The *join* utility shall conform to XBD [*Utility Syntax
49
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02) .
50
+
>
51
+
> The following options shall be supported:
52
+
>
53
+
> **-a ** *file_number*
54
+
> : Produce a line for each unpairable line in file *file_number*,
55
+
> where *file_number* is 1 or 2, in addition to the default output.
56
+
> If both **-a**1 and **-a**2 are specified, all unpairable lines
57
+
> shall be output.
58
+
>
59
+
> **-e ** *string*
60
+
> : Replace empty output fields in the list selected by **-o** with
61
+
> the string *string*.
62
+
>
63
+
> **-o ** *list*
64
+
>
65
+
> : Construct the output line to comprise the fields specified in
66
+
> *list*, each element of which shall have one of the following two
67
+
> forms:
68
+
>
69
+
> 1. *file_number.field*, where *file_number* is a file number and
70
+
> *field* is a decimal integer field number
71
+
>
72
+
> 2. 0 (zero), representing the join field
73
+
>
74
+
> The elements of *list* shall be either \<comma\>-separated or
75
+
> \<blank\>-separated, as specified in Guideline 8 of XBD [*Utility
76
+
> Syntax Guidelines*](../basedefs/V1_chap12.html#tag_12_02). The
77
+
> fields specified by *list* shall be written for all selected
78
+
> output lines. Fields selected by *list* that do not appear in the
79
+
> input shall be treated as empty output fields. (See the **-e**
80
+
> option.) Only specifically requested fields shall be written. The
81
+
> application shall ensure that *list* is a single command line
82
+
> argument.
83
+
>
84
+
> **-t ** *char*
85
+
> : Use character *char* as a separator, for both input and output.
86
+
> Every appearance of *char* in a line shall be significant. When
87
+
> this option is specified, the collating sequence shall be the same
88
+
> as [*sort*](../utilities/sort.html) without the **-b** option.
89
+
>
90
+
> **-v ** *file_number*
91
+
> : Instead of the default output, produce a line only for each
92
+
> unpairable line in *file_number*, where *file_number* is 1 or 2.
93
+
> If both **-v**1 and **-v**2 are specified, all unpairable lines
94
+
> shall be output.
95
+
>
96
+
> **-1 ** *field*
97
+
> : Join on the *field*th field of file 1. Fields are decimal integers
98
+
> starting with 1.
99
+
>
100
+
> **-2 ** *field*
101
+
> : Join on the *field*th field of file 2. Fields are decimal integers
102
+
> starting with 1.
103
+
104
+
#### []{#tag_20_63_05}OPERANDS {#operands .mansect}
105
+
106
+
> The following operands shall be supported:
107
+
>
108
+
> *file1*, *file2*
109
+
> : A pathname of a file to be joined. If either of the *file1* or
110
+
> *file2* operands is `'-'`, the standard input shall be used in its
111
+
> place.
112
+
113
+
#### []{#tag_20_63_06}STDIN {#stdin .mansect}
114
+
115
+
> The standard input shall be used only if the *file1* or *file2*
116
+
> operand is `'-'`. See the INPUT FILES section.
117
+
118
+
#### []{#tag_20_63_07}INPUT FILES {#input-files .mansect}
119
+
120
+
> The input files shall be text files.
121
+
122
+
#### []{#tag_20_63_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
123
+
124
+
> The following environment variables shall affect the execution of
125
+
> *join*:
126
+
>
127
+
> *LANG*
128
+
> : Provide a default value for the internationalization variables
129
+
> that are unset or null. (See XBD [*Internationalization
130
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
131
+
> precedence of internationalization variables used to determine the
132
+
> values of locale categories.)
133
+
>
134
+
> *LC_ALL*
135
+
> : If set to a non-empty string value, override the values of all the
136
+
> other internationalization variables.
137
+
>
138
+
> *LC_COLLATE*
139
+
> : Determine the locale of the collating sequence *join* expects to
140
+
> have been used when the input files were sorted.
141
+
>
142
+
> *LC_CTYPE*
143
+
> : Determine the locale for the interpretation of sequences of bytes
144
+
> of text data as characters (for example, single-byte as opposed to
145
+
> multi-byte characters in arguments and input files).
146
+
>
147
+
> *LC_MESSAGES*
148
+
> : Determine the locale that should be used to affect the format and
149
+
> contents of diagnostic messages written to standard error.
150
+
>
151
+
> *NLSPATH*
152
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
153
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
154
+
> location of message catalogs for the processing of *LC_MESSAGES.*
155
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
156
+
157
+
#### []{#tag_20_63_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
158
+
159
+
> Default.
160
+
161
+
#### []{#tag_20_63_10}STDOUT {#stdout .mansect}
162
+
163
+
> The *join* utility output shall be a concatenation of selected
164
+
> character fields. When the **-o** option is not specified, the output
165
+
> shall be:
166
+
>
167
+
>
168
+
> "%s%s%s\n", <join field>, <other file1 fields>,
169
+
> <other file2 fields>
170
+
>
171
+
> If the join field is not the first field in a file, the
172
+
> \<*other file fields*\> for that file shall be:
173
+
>
174
+
>
175
+
> <fields preceding join field>, <fields following join field>
176
+
>
177
+
> When the **-o** option is specified, the output format shall be:
178
+
>
179
+
>
180
+
> "%s\n", <concatenation of fields>
181
+
>
182
+
> where the concatenation of fields is described by the **-o** option,
183
+
> above.
184
+
>
185
+
> For either format, each field (except the last) shall be written with
186
+
> its trailing separator character. If the separator is the default (
187
+
> \<blank\> characters), a single \<space\> shall be written after each
188
+
> field (except the last).
189
+
190
+
#### []{#tag_20_63_11}STDERR {#stderr .mansect}
191
+
192
+
> The standard error shall be used only for diagnostic messages.
193
+
194
+
#### []{#tag_20_63_12}OUTPUT FILES {#output-files .mansect}
195
+
196
+
> None.
197
+
198
+
#### []{#tag_20_63_13}EXTENDED DESCRIPTION {#extended-description .mansect}
199
+
200
+
> None.
201
+
202
+
#### []{#tag_20_63_14}EXIT STATUS {#exit-status .mansect}
203
+
204
+
> The following exit values shall be returned:
205
+
>
206
+
> 0
207
+
> : All input files were output successfully.
208
+
>
209
+
> \>0
210
+
> : An error occurred.
211
+
212
+
#### []{#tag_20_63_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
213
+
214
+
> Default.
215
+
216
+
------------------------------------------------------------------------
217
+
218
+
::: box
219
+
*The following sections are informative.*
220
+
:::
221
+
222
+
#### []{#tag_20_63_16}APPLICATION USAGE {#application-usage .mansect}
223
+
224
+
> Pathnames consisting of numeric digits or of the form *string.string*
225
+
> should not be specified directly following the **-o** list.
226
+
>
227
+
> If the collating sequence of the current locale does not have a total
228
+
> ordering of all characters (see XBD
229
+
> [*LC_COLLATE*](../basedefs/V1_chap07.html#tag_07_03_02)), *join*
230
+
> treats fields that collate equally but are not identical as being the
231
+
> same. If this behavior is not desired, it can be avoided by forcing
232
+
> the use of the POSIX locale (although this means re-sorting the input
233
+
> files into the POSIX locale collating sequence.)
234
+
>
235
+
> When using *join* to process pathnames, it is recommended that LC_ALL,
236
+
> or at least LC_CTYPE and LC_COLLATE, are set to POSIX or C in the
237
+
> environment, since pathnames can contain byte sequences that do not
238
+
> form valid characters in some locales, in which case the utility\'s
239
+
> behavior would be undefined. In the POSIX locale each byte is a valid
240
+
> single-byte character, and therefore this problem is avoided.
241
+
242
+
#### []{#tag_20_63_17}EXAMPLES {#examples .mansect}
243
+
244
+
> The **-o** 0 field essentially selects the union of the join fields.
245
+
> For example, given file **phone**:
246
+
>
247
+
>
248
+
> !Name Phone Number
249
+
> Don +1 123-456-7890
250
+
> Hal +1 234-567-8901
251
+
> Yasushi +2 345-678-9012
252
+
>
253
+
> and file **fax**:
254
+
>
255
+
>
256
+
> !Name Fax Number
257
+
> Don +1 123-456-7899
258
+
> Keith +1 456-789-0122
259
+
> Yasushi +2 345-678-9011
260
+
>
261
+
> (where the large expanses of white space are meant to each represent a
262
+
> single \<tab\>), the command:
263
+
>
264
+
>
265
+
> join -t "<tab>" -a 1 -a 2 -e '(unknown)' -o 0,1.2,2.2 phone fax
266
+
>
267
+
> (where `<tab>` is a literal \<tab\> character) would produce:
268
+
>
269
+
>
270
+
> !Name Phone Number Fax Number
271
+
> Don +1 123-456-7890 +1 123-456-7899
272
+
> Hal +1 234-567-8901 (unknown)
273
+
> Keith (unknown) +1 456-789-0122
274
+
> Yasushi +2 345-678-9012 +2 345-678-9011
275
+
>
276
+
> Multiple instances of the same key will produce combinatorial results.
277
+
> The following:
278
+
>
279
+
>
280
+
> fa:
281
+
> a x
282
+
> a y
283
+
> a z
284
+
> fb:
285
+
> a p
286
+
>
287
+
> will produce:
288
+
>
289
+
>
290
+
> a x p
291
+
> a y p
292
+
> a z p
293
+
>
294
+
> And the following:
295
+
>
296
+
>
297
+
> fa:
298
+
> a b c
299
+
> a d e
300
+
> fb:
301
+
> a w x
302
+
> a y z
303
+
> a o p
304
+
>
305
+
> will produce:
306
+
>
307
+
>
308
+
> a b c w x
309
+
> a b c y z
310
+
> a b c o p
311
+
> a d e w x
312
+
> a d e y z
313
+
> a d e o p
314
+
315
+
#### []{#tag_20_63_18}RATIONALE {#rationale .mansect}
316
+
317
+
> The **-e** option is only effective when used with **-o** because,
318
+
> unless specific fields are identified using **-o**, *join* is not
319
+
> aware of what fields might be empty. The exception to this is the join
320
+
> field, but identifying an empty join field with the **-e** string is
321
+
> not historical practice and some scripts might break if this were
322
+
> changed.
323
+
>
324
+
> The 0 field in the **-o** list was adopted from the Tenth Edition
325
+
> version of *join* to satisfy international objections that the *join*
326
+
> in the base documents for Base Definitions volume of POSIX.1-2017,
327
+
> [Chapter 7, Locale](../basedefs/V1_chap07.html) did not support the
328
+
> \"full join\" or \"outer join\" described in relational database
329
+
> literature. Although it has been possible to include a join field in
330
+
> the output (by default, or by field number using **-o**), the join
331
+
> field could not be included for an unpaired line selected by **-a**.
332
+
> The **-o** 0 field essentially selects the union of the join fields.
333
+
>
334
+
> This sort of outer join was not possible with the *join* commands in
335
+
> the base documents for Base Definitions volume of POSIX.1-2017,
336
+
> [Chapter 7, Locale](../basedefs/V1_chap07.html). The **-o** 0 field
337
+
> was chosen because it is an upwards-compatible change for
338
+
> applications. An alternative was considered: have the join field
339
+
> represent the union of the fields in the files (where they are
340
+
> identical for matched lines, and one or both are null for unmatched
341
+
> lines). This was not adopted because it would break some historical
342
+
> applications.
343
+
>
344
+
> The ability to specify *file2* as **-** is not historical practice; it
345
+
> was added for completeness.
346
+
>
347
+
> The **-v** option is not historical practice, but was considered
348
+
> necessary because it permitted the writing of *only* those lines that
349
+
> do not match on the join field, as opposed to the **-a** option, which
350
+
> prints both lines that do and do not match. This additional facility
351
+
> is parallel with the **-v** option of
352
+
> [*grep*](../utilities/grep.html).
353
+
>
354
+
> Some historical implementations have been encountered where a blank
355
+
> line in one of the input files was considered to be the end of the
356
+
> file; the description in this volume of POSIX.1-2017 does not cite
357
+
> this as an allowable case.
358
+
>
359
+
> Earlier versions of this standard allowed **-j**, **-j1**, **-j2**
360
+
> options, and a form of the **-o** option that allowed the *list*
361
+
> option-argument to be multiple arguments. These forms are no longer
362
+
> specified by POSIX.1-2017 but may be present in some implementations.
363
+
364
+
#### []{#tag_20_63_19}FUTURE DIRECTIONS {#future-directions .mansect}
365
+
366
+
> None.
367
+
368
+
#### []{#tag_20_63_20}SEE ALSO {#see-also .mansect}
369
+
370
+
> [*awk*](../utilities/awk.html#), [*comm*](../utilities/comm.html#),
371
+
> [*sort*](../utilities/sort.html#), [*uniq*](../utilities/uniq.html#)
372
+
>
373
+
> XBD [*LC_COLLATE*](../basedefs/V1_chap07.html#tag_07_03_02),
374
+
> [*Environment Variables*](../basedefs/V1_chap08.html#tag_08),
375
+
> [*Utility Syntax Guidelines*](../basedefs/V1_chap12.html#tag_12_02)
376
+
377
+
#### []{#tag_20_63_21}CHANGE HISTORY {#change-history .mansect}
378
+
379
+
> First released in Issue 2.
380
+
381
+
#### []{#tag_20_63_22}Issue 6 {#issue-6 .mansect}
382
+
383
+
> The obsolescent **-j** options and the multi-argument **-o** option
384
+
> are removed in this version.
385
+
>
386
+
> The normative text is reworded to avoid use of the term \"must\" for
387
+
> application requirements.
388
+
389
+
#### []{#tag_20_63_23}Issue 7 {#issue-7 .mansect}
390
+
391
+
> Austin Group Interpretation 1003.1-2001 #027 is applied.
392
+
>
393
+
> SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.
394
+
>
395
+
> POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0109 \[963\],
396
+
> XCU/TC2-2008/0110 \[663\], XCU/TC2-2008/0111 \[971\], and
397
+
> XCU/TC2-2008/0112 \[885\] are applied.
398
+
+350
docs/posix2018/ln.md
+350
docs/posix2018/ln.md
···
1
+
#### []{#tag_20_67_01}NAME {#name .mansect}
2
+
3
+
> ln - link files
4
+
5
+
#### []{#tag_20_67_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `ln`` `**`[`**`-fs`**`] [`**`-L|-P`**`]`**` `*`source_file target_file`*\
8
+
> \
9
+
> `ln`` `**`[`**`-fs`**`] [`**`-L|-P`**`]`**` `*`source_file`*`...`` `*`target_dir`*\
10
+
11
+
#### []{#tag_20_67_03}DESCRIPTION {#description .mansect}
12
+
13
+
> In the first synopsis form, the *ln* utility shall create a new
14
+
> directory entry (link) at the destination path specified by the
15
+
> *target_file* operand. If the **-s** option is specified, a symbolic
16
+
> link shall be created for the file specified by the *source_file*
17
+
> operand. This first synopsis form shall be assumed when the final
18
+
> operand does not name an existing directory; if more than two operands
19
+
> are specified and the final is not an existing directory, an error
20
+
> shall result.
21
+
>
22
+
> In the second synopsis form, the *ln* utility shall create a new
23
+
> directory entry (link), or if the **-s** option is specified a
24
+
> symbolic link, for each file specified by a *source_file* operand, at
25
+
> a destination path in the existing directory named by *target_dir*.
26
+
>
27
+
> If the last operand specifies an existing file of a type not specified
28
+
> by the System Interfaces volume of POSIX.1-2017, the behavior is
29
+
> implementation-defined.
30
+
>
31
+
> The corresponding destination path for each *source_file* shall be the
32
+
> concatenation of the target directory pathname, a \<slash\> character
33
+
> if the target directory pathname did not end in a \<slash\>, and the
34
+
> last pathname component of the *source_file*. The second synopsis form
35
+
> shall be assumed when the final operand names an existing directory.
36
+
>
37
+
> For each *source_file*:
38
+
>
39
+
> 1. If the destination path exists and was created by a previous step,
40
+
> it is unspecified whether *ln* shall write a diagnostic message to
41
+
> standard error, do nothing more with the current *source_file*,
42
+
> and go on to any remaining *source_file*s; or will continue
43
+
> processing the current *source_file*. If the destination path
44
+
> exists:
45
+
>
46
+
> a. If the **-f** option is not specified, *ln* shall write a
47
+
> diagnostic message to standard error, do nothing more with the
48
+
> current *source_file*, and go on to any remaining
49
+
> *source_file*s.
50
+
>
51
+
> b. If the destination path names the same directory entry as the
52
+
> current *source_file* *ln* shall write a diagnostic message to
53
+
> standard error, do nothing more with the current
54
+
> *source_file*, and go on to any remaining *source_file*s*.*
55
+
>
56
+
> c. Actions shall be performed equivalent to the
57
+
> [*unlink*()](../functions/unlink.html) function defined in the
58
+
> System Interfaces volume of POSIX.1-2017, called using the
59
+
> destination path as the *path* argument. If this fails for any
60
+
> reason, *ln* shall write a diagnostic message to standard
61
+
> error, do nothing more with the current *source_file*, and go
62
+
> on to any remaining *source_file*s.
63
+
>
64
+
> 2. If the **-s** option is specified, actions shall be performed
65
+
> equivalent to the [*symlink*()](../functions/symlink.html)
66
+
> function with *source_file* as the *path1* argument and the
67
+
> destination path as the *path2* argument. The *ln* utility shall
68
+
> do nothing more with *source_file* and shall go on to any
69
+
> remaining files.
70
+
>
71
+
> 3. If *source_file* is a symbolic link:
72
+
>
73
+
> a. If the **-P** option is in effect, actions shall be performed
74
+
> equivalent to the [*linkat*()](../functions/linkat.html)
75
+
> function with *source_file* as the *path1* argument, the
76
+
> destination path as the *path2* argument, AT_FDCWD as the
77
+
> *fd1* and *fd2* arguments, and zero as the *flag* argument.
78
+
>
79
+
> b. If the **-L** option is in effect, actions shall be performed
80
+
> equivalent to the [*linkat*()](../functions/linkat.html)
81
+
> function with *source_file* as the *path1* argument, the
82
+
> destination path as the *path2* argument, AT_FDCWD as the
83
+
> *fd1* and *fd2* arguments, and AT_SYMLINK_FOLLOW as the *flag*
84
+
> argument.
85
+
>
86
+
> The *ln* utility shall do nothing more with *source_file* and
87
+
> shall go on to any remaining files.
88
+
>
89
+
> 4. Actions shall be performed equivalent to the
90
+
> [*link*()](../functions/link.html) function defined in the System
91
+
> Interfaces volume of POSIX.1-2017 using *source_file* as the
92
+
> *path1* argument, and the destination path as the *path2*
93
+
> argument.
94
+
95
+
#### []{#tag_20_67_04}OPTIONS {#options .mansect}
96
+
97
+
> The *ln* utility shall conform to XBD [*Utility Syntax
98
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02) .
99
+
>
100
+
> The following options shall be supported:
101
+
>
102
+
> **-f**
103
+
> : Force existing destination pathnames to be removed to allow the
104
+
> link.
105
+
>
106
+
> **-L**
107
+
> : For each *source_file* operand that names a file of type symbolic
108
+
> link, create a (hard) link to the file referenced by the symbolic
109
+
> link.
110
+
>
111
+
> **-P**
112
+
> : For each *source_file* operand that names a file of type symbolic
113
+
> link, create a (hard) link to the symbolic link itself.
114
+
>
115
+
> **-s**
116
+
> : Create symbolic links instead of hard links. If the **-s** option
117
+
> is specified, the **-L** and **-P** options shall be silently
118
+
> ignored.
119
+
>
120
+
> Specifying more than one of the mutually-exclusive options **-L** and
121
+
> **-P** shall not be considered an error. The last option specified
122
+
> shall determine the behavior of the utility (unless the **-s** option
123
+
> causes it to be ignored).
124
+
>
125
+
> If the **-s** option is not specified and neither a **-L** nor a
126
+
> **-P** option is specified, it is implementation-defined which of the
127
+
> **-L** and **-P** options will be used as the default.
128
+
129
+
#### []{#tag_20_67_05}OPERANDS {#operands .mansect}
130
+
131
+
> The following operands shall be supported:
132
+
>
133
+
> *source_file*
134
+
> : A pathname of a file to be linked. If the **-s** option is
135
+
> specified, no restrictions on the type of file or on its existence
136
+
> shall be made. If the **-s** option is not specified, whether a
137
+
> directory can be linked is implementation-defined.
138
+
>
139
+
> *target_file*
140
+
> : The pathname of the new directory entry to be created.
141
+
>
142
+
> *target_dir*
143
+
> : A pathname of an existing directory in which the new directory
144
+
> entries are created.
145
+
146
+
#### []{#tag_20_67_06}STDIN {#stdin .mansect}
147
+
148
+
> Not used.
149
+
150
+
#### []{#tag_20_67_07}INPUT FILES {#input-files .mansect}
151
+
152
+
> None.
153
+
154
+
#### []{#tag_20_67_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
155
+
156
+
> The following environment variables shall affect the execution of
157
+
> *ln*:
158
+
>
159
+
> *LANG*
160
+
> : Provide a default value for the internationalization variables
161
+
> that are unset or null. (See XBD [*Internationalization
162
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
163
+
> precedence of internationalization variables used to determine the
164
+
> values of locale categories.)
165
+
>
166
+
> *LC_ALL*
167
+
> : If set to a non-empty string value, override the values of all the
168
+
> other internationalization variables.
169
+
>
170
+
> *LC_CTYPE*
171
+
> : Determine the locale for the interpretation of sequences of bytes
172
+
> of text data as characters (for example, single-byte as opposed to
173
+
> multi-byte characters in arguments).
174
+
>
175
+
> *LC_MESSAGES*
176
+
> : Determine the locale that should be used to affect the format and
177
+
> contents of diagnostic messages written to standard error.
178
+
>
179
+
> *NLSPATH*
180
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
181
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
182
+
> location of message catalogs for the processing of *LC_MESSAGES.*
183
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
184
+
185
+
#### []{#tag_20_67_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
186
+
187
+
> Default.
188
+
189
+
#### []{#tag_20_67_10}STDOUT {#stdout .mansect}
190
+
191
+
> Not used.
192
+
193
+
#### []{#tag_20_67_11}STDERR {#stderr .mansect}
194
+
195
+
> The standard error shall be used only for diagnostic messages.
196
+
197
+
#### []{#tag_20_67_12}OUTPUT FILES {#output-files .mansect}
198
+
199
+
> None.
200
+
201
+
#### []{#tag_20_67_13}EXTENDED DESCRIPTION {#extended-description .mansect}
202
+
203
+
> None.
204
+
205
+
#### []{#tag_20_67_14}EXIT STATUS {#exit-status .mansect}
206
+
207
+
> The following exit values shall be returned:
208
+
>
209
+
> 0
210
+
> : All the specified files were linked successfully.
211
+
>
212
+
> \>0
213
+
> : An error occurred.
214
+
215
+
#### []{#tag_20_67_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
216
+
217
+
> Default.
218
+
219
+
------------------------------------------------------------------------
220
+
221
+
::: box
222
+
*The following sections are informative.*
223
+
:::
224
+
225
+
#### []{#tag_20_67_16}APPLICATION USAGE {#application-usage .mansect}
226
+
227
+
> None.
228
+
229
+
#### []{#tag_20_67_17}EXAMPLES {#examples .mansect}
230
+
231
+
> None.
232
+
233
+
#### []{#tag_20_67_18}RATIONALE {#rationale .mansect}
234
+
235
+
> The CONSEQUENCES OF ERRORS section does not require *ln* **-f** *a b*
236
+
> to remove *b* if a subsequent link operation would fail.
237
+
>
238
+
> Some historic versions of *ln* (including the one specified by the
239
+
> SVID) unlink the destination file, if it exists, by default. If the
240
+
> mode does not permit writing, these versions prompt for confirmation
241
+
> before attempting the unlink. In these versions the **-f** option
242
+
> causes *ln* not to attempt to prompt for confirmation.
243
+
>
244
+
> This allows *ln* to succeed in creating links when the target file
245
+
> already exists, even if the file itself is not writable (although the
246
+
> directory must be). Early proposals specified this functionality.
247
+
>
248
+
> This volume of POSIX.1-2017 does not allow the *ln* utility to unlink
249
+
> existing destination paths by default for the following reasons:
250
+
>
251
+
> - The *ln* utility has historically been used to provide locking for
252
+
> shell applications, a usage that is incompatible with *ln* unlinking
253
+
> the destination path by default. There was no corresponding
254
+
> technical advantage to adding this functionality.
255
+
>
256
+
> - This functionality gave *ln* the ability to destroy the link
257
+
> structure of files, which changes the historical behavior of *ln*.
258
+
>
259
+
> - This functionality is easily replicated with a combination of
260
+
> [*rm*](../utilities/rm.html) and *ln*.
261
+
>
262
+
> - It is not historical practice in many systems; BSD and BSD-derived
263
+
> systems do not support this behavior. Unfortunately, whichever
264
+
> behavior is selected can cause scripts written expecting the other
265
+
> behavior to fail.
266
+
>
267
+
> - It is preferable that *ln* perform in the same manner as the
268
+
> [*link*()](../functions/link.html) function, which does not permit
269
+
> the target to exist already.
270
+
>
271
+
> This volume of POSIX.1-2017 retains the **-f** option to provide
272
+
> support for shell scripts depending on the SVID semantics. It seems
273
+
> likely that shell scripts would not be written to handle prompting by
274
+
> *ln* and would therefore have specified the **-f** option.
275
+
>
276
+
> The **-f** option is an undocumented feature of many historical
277
+
> versions of the *ln* utility, allowing linking to directories. These
278
+
> versions require modification.
279
+
>
280
+
> Early proposals of this volume of POSIX.1-2017 also required a **-i**
281
+
> option, which behaved like the **-i** options in
282
+
> [*cp*](../utilities/cp.html) and [*mv*](../utilities/mv.html),
283
+
> prompting for confirmation before unlinking existing files. This was
284
+
> not historical practice for the *ln* utility and has been omitted.
285
+
>
286
+
> The **-L** and **-P** options allow for implementing both common
287
+
> behaviors of the *ln* utility. Earlier versions of this standard did
288
+
> not specify these options and required the behavior now described for
289
+
> the **-L** option. Many systems by default or as an alternative
290
+
> provided a non-conforming *ln* utility with the behavior now described
291
+
> for the **-P** option. Since applications could not rely on *ln*
292
+
> following links in practice, the **-L** and **-P** options were added
293
+
> to specify the desired behavior for the application.
294
+
>
295
+
> The **-L** and **-P** options are ignored when **-s** is specified in
296
+
> order to allow an alias to be created to alter the default behavior
297
+
> when creating hard links (for example,
298
+
> [*alias*](../utilities/alias.html) *ln*=\' *ln* **-L**\'). They serve
299
+
> no purpose when **-s** is specified, since *source_file* is then just
300
+
> a string to be used as the contents of the created symbolic link and
301
+
> need not exist as a file.
302
+
>
303
+
> The specification ensures that *ln* **a** **a** with or without the
304
+
> **-f** option will not unlink the file **a**. Earlier versions of this
305
+
> standard were unclear in this case.
306
+
307
+
#### []{#tag_20_67_19}FUTURE DIRECTIONS {#future-directions .mansect}
308
+
309
+
> None.
310
+
311
+
#### []{#tag_20_67_20}SEE ALSO {#see-also .mansect}
312
+
313
+
> [*chmod*](../utilities/chmod.html#tag_20_17),
314
+
> [*find*](../utilities/find.html#), [*pax*](../utilities/pax.html#),
315
+
> [*rm*](../utilities/rm.html#)
316
+
>
317
+
> XBD [*Environment Variables*](../basedefs/V1_chap08.html#tag_08),
318
+
> [*Utility Syntax Guidelines*](../basedefs/V1_chap12.html#tag_12_02)
319
+
>
320
+
> XSH [*link*](../functions/link.html#tag_16_293),
321
+
> [*unlink*](../functions/unlink.html#tag_16_635)
322
+
323
+
#### []{#tag_20_67_21}CHANGE HISTORY {#change-history .mansect}
324
+
325
+
> First released in Issue 2.
326
+
327
+
#### []{#tag_20_67_22}Issue 6 {#issue-6 .mansect}
328
+
329
+
> The *ln* utility is updated to include symbolic link processing as
330
+
> defined in the IEEE P1003.2b draft standard.
331
+
332
+
#### []{#tag_20_67_23}Issue 7 {#issue-7 .mansect}
333
+
334
+
> Austin Group Interpretations 1003.1-2001 #164, #168, and #169 are
335
+
> applied.
336
+
>
337
+
> SD5-XCU-ERN-27 is applied, adding a new paragraph to the RATIONALE.
338
+
>
339
+
> SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.
340
+
>
341
+
> The **-L** and **-P** options are added to make it
342
+
> implementation-defined whether the *ln* utility follows symbolic
343
+
> links.
344
+
>
345
+
> POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0096 \[136\] is
346
+
> applied.
347
+
>
348
+
> POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0113 \[930\] is
349
+
> applied.
350
+
+868
docs/posix2018/ls.md
+868
docs/posix2018/ls.md
···
1
+
#### []{#tag_20_73_01}NAME {#name .mansect}
2
+
3
+
> ls - list directory contents
4
+
5
+
#### []{#tag_20_73_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> ^`[`[`XSI`](javascript:open_code('XSI'))`]`^` ls`` `**`[`**`-ikqrs`**`] [`**`-`{border="0"}`g`{border="0"}`ln`{border="0"}`o`{border="0"}**`] [`**`-A|-a`**`] [`**`-C|-m|-x|-1`**`]`**` ``\`\
8
+
> ` `` `**`[`**`-F|-p`**`] [`**`-H|-L`**`] [`**`-R|-d`**`] [`**`-S|-f|-t`**`] [`**`-c|-u`**`] [`***`file`*`...`**`]`**
9
+
10
+
#### []{#tag_20_73_03}DESCRIPTION {#description .mansect}
11
+
12
+
> For each operand that names a file of a type other than directory or
13
+
> symbolic link to a directory, *ls* shall write the name of the file as
14
+
> well as any requested, associated information. For each operand that
15
+
> names a file of type directory, *ls* shall write the names of files
16
+
> contained within the directory as well as any requested, associated
17
+
> information. Filenames beginning with a \<period\> ( `'.'` ) and any
18
+
> associated information shall not be written out unless explicitly
19
+
> referenced, the **-A** or **-a** option is supplied, or an
20
+
> implementation-defined condition causes them to be written. If one or
21
+
> more of the **-d**, **-F**, or **-l** options are specified, and
22
+
> neither the **-H** nor the **-L** option is specified, for each
23
+
> operand that names a file of type symbolic link to a directory, *ls*
24
+
> shall write the name of the file as well as any requested, associated
25
+
> information. If none of the **-d**, **-F**, or **-l** options are
26
+
> specified, or the **-H** or **-L** options are specified, for each
27
+
> operand that names a file of type symbolic link to a directory, *ls*
28
+
> shall write the names of files contained within the directory as well
29
+
> as any requested, associated information. In each case where the names
30
+
> of files contained within a directory are written, if the directory
31
+
> contains any symbolic links then *ls* shall evaluate the file
32
+
> information and file type to be those of the symbolic link itself,
33
+
> unless the **-L** option is specified.
34
+
>
35
+
> If no operands are specified, *ls* shall behave as if a single operand
36
+
> of dot ( `'.'` ) had been specified. If more than one operand is
37
+
> specified, *ls* shall write non-directory operands first; it shall
38
+
> sort directory and non-directory operands separately according to the
39
+
> collating sequence in the current locale.
40
+
>
41
+
> Whenever *ls* sorts filenames or pathnames according to the collating
42
+
> sequence in the current locale, if this collating sequence does not
43
+
> have a total ordering of all characters (see XBD
44
+
> [*LC_COLLATE*](../basedefs/V1_chap07.html#tag_07_03_02)), then any
45
+
> filenames or pathnames that collate equally should be further compared
46
+
> byte-by-byte using the collating sequence for the POSIX locale.
47
+
>
48
+
> The *ls* utility shall detect infinite loops; that is, entering a
49
+
> previously visited directory that is an ancestor of the last file
50
+
> encountered. When it detects an infinite loop, *ls* shall write a
51
+
> diagnostic message to standard error and shall either recover its
52
+
> position in the hierarchy or terminate.
53
+
54
+
#### []{#tag_20_73_04}OPTIONS {#options .mansect}
55
+
56
+
> The *ls* utility shall conform to XBD [*Utility Syntax
57
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02) .
58
+
>
59
+
> The following options shall be supported:
60
+
>
61
+
> **-A**
62
+
> : Write out all directory entries, including those whose names begin
63
+
> with a \<period\> ( `'.'` ) but excluding the entries dot and
64
+
> dot-dot (if they exist).
65
+
>
66
+
> **-C**
67
+
> : Write multi-text-column output with entries sorted down the
68
+
> columns, according to the collating sequence. The number of text
69
+
> columns and the column separator characters are unspecified, but
70
+
> should be adapted to the nature of the output device. This option
71
+
> disables long format output.
72
+
>
73
+
> **-F**
74
+
> : Do not follow symbolic links named as operands unless the **-H**
75
+
> or **-L** options are specified. Write a \<slash\> ( `'/'` )
76
+
> immediately after each pathname that is a directory, an
77
+
> \<asterisk\> ( `'*'` ) after each that is executable, a
78
+
> \<vertical-line\> ( `'|'` ) after each that is a FIFO, and an
79
+
> at-sign ( `'@'` ) after each that is a symbolic link. For other
80
+
> file types, other symbols may be written.
81
+
>
82
+
> **-H**
83
+
> : Evaluate the file information and file type for symbolic links
84
+
> specified on the command line to be those of the file referenced
85
+
> by the link, and not the link itself; however, *ls* shall write
86
+
> the name of the link itself and not the file referenced by the
87
+
> link.
88
+
>
89
+
> **-L**
90
+
> : Evaluate the file information and file type for all symbolic links
91
+
> (whether named on the command line or encountered in a file
92
+
> hierarchy) to be those of the file referenced by the link, and not
93
+
> the link itself; however, *ls* shall write the name of the link
94
+
> itself and not the file referenced by the link. When **-L** is
95
+
> used with **-l**, write the contents of symbolic links in the long
96
+
> format (see the STDOUT section).
97
+
>
98
+
> **-R**
99
+
> : Recursively list subdirectories encountered. When a symbolic link
100
+
> to a directory is encountered, the directory shall not be
101
+
> recursively listed unless the **-L** option is specified. The use
102
+
> of **-R** with **-d** or **-f** produces unspecified results.
103
+
>
104
+
> **-S**
105
+
> : Sort with the primary key being file size (in decreasing order)
106
+
> and the secondary key being filename in the collating sequence (in
107
+
> increasing order).
108
+
>
109
+
> **-a**
110
+
> : Write out all directory entries, including those whose names begin
111
+
> with a \<period\> ( `'.'` ).
112
+
>
113
+
> **-c**
114
+
> : Use time of last modification of the file status information (see
115
+
> XBD [*\<sys/stat.h\>*](../basedefs/sys_stat.h.html)) instead of
116
+
> last modification of the file itself for sorting ( **-t**) or
117
+
> writing (**-l**).
118
+
>
119
+
> **-d**
120
+
> : Do not follow symbolic links named as operands unless the **-H**
121
+
> or **-L** options are specified. Do not treat directories
122
+
> differently than other types of files. The use of **-d** with
123
+
> **-R** or **-f** produces unspecified results.
124
+
>
125
+
> **-f**
126
+
> : List the entries in directory operands in the order they appear in
127
+
> the directory. The behavior for non-directory operands is
128
+
> unspecified. This option shall turn on **-a**. When **-f** is
129
+
> specified, any occurrences of the **-r**, **-S**, and **-t**
130
+
> options shall be ignored and any occurrences of the **-A**,
131
+
> ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
132
+
> Start\]](../images/opt-start.gif){border="0"} **-g**, ![\[Option
133
+
> End\]](../images/opt-end.gif){border="0"} **-l**, **-n**,
134
+
> ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
135
+
> Start\]](../images/opt-start.gif){border="0"} **-o**, ![\[Option
136
+
> End\]](../images/opt-end.gif){border="0"} and **-s** options may
137
+
> be ignored. The use of **-f** with **-R** or **-d** produces
138
+
> unspecified results.
139
+
>
140
+
> **-g**
141
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
142
+
> Start\]](../images/opt-start.gif){border="0"} Turn on the **-l**
143
+
> (ell) option, but disable writing the file\'s owner name or
144
+
> number. Disable the **-C**, **-m**, and **-x** options. ![\[Option
145
+
> End\]](../images/opt-end.gif){border="0"}
146
+
>
147
+
> **-i**
148
+
> : For each file, write the file\'s file serial number (see
149
+
> [*stat*()](../functions/stat.html) in the System Interfaces volume
150
+
> of POSIX.1-2017).
151
+
>
152
+
> **-k**
153
+
> : Set the block size for the **-s** option and the per-directory
154
+
> block count written for the **-l**, **-n**, **-s**,
155
+
> ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
156
+
> Start\]](../images/opt-start.gif){border="0"} **-g**, and **-o**
157
+
> ![\[Option End\]](../images/opt-end.gif){border="0"} options (see
158
+
> the STDOUT section) to 1024 bytes.
159
+
>
160
+
> **-l**
161
+
> : (The letter ell.) Do not follow symbolic links named as operands
162
+
> unless the **-H** or **-L** options are specified. Write out in
163
+
> long format (see the STDOUT section). Disable the **-C**, **-m**,
164
+
> and **-x** options.
165
+
>
166
+
> **-m**
167
+
> : Stream output format; list pathnames across the page, separated by
168
+
> a \<comma\> character followed by a \<space\> character. Use a
169
+
> \<newline\> character as the list terminator and after the
170
+
> separator sequence when there is not room on a line for the next
171
+
> list entry. This option disables long format output.
172
+
>
173
+
> **-n**
174
+
> : Turn on the **-l** (ell) option, but when writing the file\'s
175
+
> owner or group, write the file\'s numeric UID or GID rather than
176
+
> the user or group name, respectively. Disable the **-C**, **-m**,
177
+
> and **-x** options.
178
+
>
179
+
> **-o**
180
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
181
+
> Start\]](../images/opt-start.gif){border="0"} Turn on the **-l**
182
+
> (ell) option, but disable writing the file\'s group name or
183
+
> number. Disable the **-C**, **-m**, and **-x** options. ![\[Option
184
+
> End\]](../images/opt-end.gif){border="0"}
185
+
>
186
+
> **-p**
187
+
> : Write a \<slash\> ( `'/'` ) after each filename if that file is a
188
+
> directory.
189
+
>
190
+
> **-q**
191
+
> : Force each instance of non-printable filename characters and
192
+
> \<tab\> characters to be written as the \<question-mark\> ( `'?'`
193
+
> ) character. Implementations may provide this option by default if
194
+
> the output is to a terminal device.
195
+
>
196
+
> **-r**
197
+
> : Reverse the order of the sort to get reverse collating sequence
198
+
> oldest first, or smallest file size first depending on the other
199
+
> options given.
200
+
>
201
+
> **-s**
202
+
> : Indicate the total number of file system blocks consumed by each
203
+
> file displayed. If the **-k** option is also specified, the block
204
+
> size shall be 1024 bytes; otherwise, the block size is
205
+
> implementation-defined.
206
+
>
207
+
> **-t**
208
+
> : Sort with the primary key being time modified (most recently
209
+
> modified first) and the secondary key being filename in the
210
+
> collating sequence. For a symbolic link, the time used as the sort
211
+
> key is that of the symbolic link itself, unless *ls* is evaluating
212
+
> its file information to be that of the file referenced by the link
213
+
> (see the **-H** and **-L** options).
214
+
>
215
+
> **-u**
216
+
> : Use time of last access (see XBD
217
+
> [*\<sys/stat.h\>*](../basedefs/sys_stat.h.html)) instead of last
218
+
> modification of the file for sorting (**-t**) or writing (**-l**).
219
+
>
220
+
> **-x**
221
+
> : The same as **-C**, except that the multi-text-column output is
222
+
> produced with entries sorted across, rather than down, the
223
+
> columns. This option disables long format output.
224
+
>
225
+
> **-1**
226
+
> : (The numeric digit one.) Force output to be one entry per line.
227
+
> This option does not disable long format output. (Long format
228
+
> output is enabled by ^\[[XSI](javascript:open_code('XSI'))\]^
229
+
> ![\[Option Start\]](../images/opt-start.gif){border="0"} **-g**,
230
+
> ![\[Option End\]](../images/opt-end.gif){border="0"} **-l** (ell),
231
+
> **-n**, and ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
232
+
> Start\]](../images/opt-start.gif){border="0"} **-o**; ![\[Option
233
+
> End\]](../images/opt-end.gif){border="0"} and disabled by **-C**,
234
+
> **-m**, and **-x**.)
235
+
>
236
+
> If an option that enables long format output (
237
+
> ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
238
+
> Start\]](../images/opt-start.gif){border="0"} **-g**, ![\[Option
239
+
> End\]](../images/opt-end.gif){border="0"} **-l** (ell), **-n**, and
240
+
> ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
241
+
> Start\]](../images/opt-start.gif){border="0"} **-o**, ![\[Option
242
+
> End\]](../images/opt-end.gif){border="0"} is given with an option that
243
+
> disables long format output (**-C**, **-m**, and **-x**), this shall
244
+
> not be considered an error. The last of these options specified shall
245
+
> determine whether long format output is written.
246
+
>
247
+
> If **-R**, **-d**, or **-f** are specified, the results of specifying
248
+
> these mutually-exclusive options are specified by the descriptions of
249
+
> these options above. If more than one of any of the other options
250
+
> shown in the SYNOPSIS section in mutually-exclusive sets are given,
251
+
> this shall not be considered an error; the last option specified in
252
+
> each set shall determine the output.
253
+
>
254
+
> Note that if **-t** is specified, **-c** and **-u** are not only
255
+
> mutually-exclusive with each other, they are also mutually-exclusive
256
+
> with **-S** when determining sort order. But even if **-S** is
257
+
> specified after all occurrences of **-c**, **-t**, and **-u**, the
258
+
> last use of **-c** or **-u** determines the timestamp printed when
259
+
> producing long format output.
260
+
261
+
#### []{#tag_20_73_05}OPERANDS {#operands .mansect}
262
+
263
+
> The following operand shall be supported:
264
+
>
265
+
> *file*
266
+
> : A pathname of a file to be written. If the file specified is not
267
+
> found, a diagnostic message shall be output on standard error.
268
+
269
+
#### []{#tag_20_73_06}STDIN {#stdin .mansect}
270
+
271
+
> Not used.
272
+
273
+
#### []{#tag_20_73_07}INPUT FILES {#input-files .mansect}
274
+
275
+
> None.\
276
+
277
+
#### []{#tag_20_73_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
278
+
279
+
> The following environment variables shall affect the execution of
280
+
> *ls*:
281
+
>
282
+
> *COLUMNS*
283
+
> : Determine the user\'s preferred column position width for writing
284
+
> multiple text-column output. If this variable contains a string
285
+
> representing a decimal integer, the *ls* utility shall calculate
286
+
> how many pathname text columns to write (see **-C**) based on the
287
+
> width provided. If *COLUMNS* is not set or invalid, an
288
+
> implementation-defined number of column positions shall be
289
+
> assumed, based on the implementation\'s knowledge of the output
290
+
> device. The column width chosen to write the names of files in any
291
+
> given directory shall be constant. Filenames shall not be
292
+
> truncated to fit into the multiple text-column output.
293
+
>
294
+
> *LANG*
295
+
> : Provide a default value for the internationalization variables
296
+
> that are unset or null. (See XBD [*Internationalization
297
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
298
+
> precedence of internationalization variables used to determine the
299
+
> values of locale categories.)
300
+
>
301
+
> *LC_ALL*
302
+
> : If set to a non-empty string value, override the values of all the
303
+
> other internationalization variables.
304
+
>
305
+
> *LC_COLLATE*
306
+
> : Determine the locale for character collation information in
307
+
> determining the pathname collation sequence.
308
+
>
309
+
> *LC_CTYPE*
310
+
> : Determine the locale for the interpretation of sequences of bytes
311
+
> of text data as characters (for example, single-byte as opposed to
312
+
> multi-byte characters in arguments) and which characters are
313
+
> defined as printable (character class **print**).
314
+
>
315
+
> *LC_MESSAGES*
316
+
> : Determine the locale that should be used to affect the format and
317
+
> contents of diagnostic messages written to standard error.
318
+
>
319
+
> *LC_TIME*
320
+
> : Determine the format and contents for date and time strings
321
+
> written by *ls*.
322
+
>
323
+
> *NLSPATH*
324
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
325
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
326
+
> location of message catalogs for the processing of *LC_MESSAGES.*
327
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
328
+
>
329
+
> *TZ*
330
+
> : Determine the timezone for date and time strings written by *ls*.
331
+
> If *TZ* is unset or null, an unspecified default timezone shall be
332
+
> used.
333
+
334
+
#### []{#tag_20_73_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
335
+
336
+
> Default.
337
+
338
+
#### []{#tag_20_73_10}STDOUT {#stdout .mansect}
339
+
340
+
> The default format shall be to list one entry per line to standard
341
+
> output; the exceptions are to terminals or when one of the **-C**,
342
+
> **-m**, or **-x** options is specified. If the output is to a
343
+
> terminal, the format is implementation-defined.
344
+
>
345
+
> When **-m** is specified, the format used for the last element of the
346
+
> list shall be:
347
+
>
348
+
>
349
+
> "%s\n", <filename>
350
+
>
351
+
> The format used for each other element of the list shall be:
352
+
>
353
+
>
354
+
> "%s,%s", <filename>, <separator>
355
+
>
356
+
> where, if there is not room for the next element of the list to fit
357
+
> within the current line length, \<*separator*\> is a string containing
358
+
> an optional \<space\> character and a mandatory \<newline\> character;
359
+
> otherwise it is a single \<space\> character.
360
+
>
361
+
> If the **-i** option is specified, the file\'s file serial number (see
362
+
> XBD [*\<sys/stat.h\>*](../basedefs/sys_stat.h.html)) shall be written
363
+
> in the following format before any other output for the corresponding
364
+
> entry:
365
+
>
366
+
>
367
+
> %u ", <file serial number>
368
+
>
369
+
> If the **-l** option is specified, the following information shall be
370
+
> written for files other than character special and block special
371
+
> files:
372
+
>
373
+
>
374
+
> "%s %u %s %s %u %s %s\n", <file mode>, <number of links>,
375
+
> <owner name>, <group name>, <size>, <date and time>,
376
+
> <pathname>
377
+
>
378
+
> If the **-l** option is specified, the following information shall be
379
+
> written for character special and block special files:
380
+
>
381
+
>
382
+
> "%s %u %s %s %s %s %s\n", <file mode>, <number of links>,
383
+
> <owner name>, <group name>, <device info>, <date and time>,
384
+
> <pathname>
385
+
>
386
+
> In both cases if the file is a symbolic link and the **-L** option is
387
+
> also specified, this information shall be for the file resolved from
388
+
> the symbolic link, except that the \<*pathname*\> field shall contain
389
+
> the pathname of the symbolic link itself. If the file is a symbolic
390
+
> link and the **-L** option is not specified, this information shall be
391
+
> about the link itself and the \<*pathname*\> field shall be of the
392
+
> form:
393
+
>
394
+
>
395
+
> "%s -> %s", <pathname of link>, <contents of link>
396
+
>
397
+
> The **-n**, ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
398
+
> Start\]](../images/opt-start.gif){border="0"} **-g**, and **-o**
399
+
> ![\[Option End\]](../images/opt-end.gif){border="0"} options use the
400
+
> same format as **-l**, but with omitted items and their associated
401
+
> \<blank\> characters. See the OPTIONS section.
402
+
>
403
+
> In both the preceding **-l** forms, if \<*owner name*\> or \<*group
404
+
> name*\> cannot be determined, or if **-n** is given, they shall be
405
+
> replaced with their associated numeric values using the format `%u`.
406
+
>
407
+
> The \<*size*\> field shall contain the value that would be returned
408
+
> for the file in the *st_size* field of **struct stat** (see XBD
409
+
> [*\<sys/stat.h\>*](../basedefs/sys_stat.h.html)). Note that for some
410
+
> file types this value is unspecified.
411
+
>
412
+
> The \<*device info*\> field shall contain implementation-defined
413
+
> information associated with the device in question.
414
+
>
415
+
> The \<*date and time*\> field shall contain the appropriate date and
416
+
> timestamp of when the file was last modified. In the POSIX locale, the
417
+
> field shall be the equivalent of the output of the following
418
+
> [*date*](../utilities/date.html) command:
419
+
>
420
+
>
421
+
> date "+%b %e %H:%M"
422
+
>
423
+
> if the file has been modified in the last six months, or:
424
+
>
425
+
>
426
+
> date "+%b %e %Y"
427
+
>
428
+
> (where two \<space\> characters are used between `%e` and `%Y` ) if
429
+
> the file has not been modified in the last six months or if the
430
+
> modification date is in the future, except that, in both cases, the
431
+
> final \<newline\> produced by [*date*](../utilities/date.html) shall
432
+
> not be included and the output shall be as if the
433
+
> [*date*](../utilities/date.html) command were executed at the time of
434
+
> the last modification date of the file rather than the current time.
435
+
> When the *LC_TIME* locale category is not set to the POSIX locale, a
436
+
> different format and order of presentation of this field may be used.
437
+
>
438
+
> If the pathname was specified as a *file* operand, it shall be written
439
+
> as specified.
440
+
>
441
+
> The file mode written under the **-l**, **-n**,
442
+
> ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
443
+
> Start\]](../images/opt-start.gif){border="0"} **-g**, and **-o**
444
+
> ![\[Option End\]](../images/opt-end.gif){border="0"} options shall
445
+
> consist of the following format:
446
+
>
447
+
>
448
+
> "%c%s%s%s%s", <entry type>, <owner permissions>,
449
+
> <group permissions>, <other permissions>,
450
+
> <optional alternate access method flag>
451
+
>
452
+
> The \<*optional alternate access method flag*\> shall be the empty
453
+
> string if there is no alternate or additional access control method
454
+
> associated with the file; otherwise, it shall be a string containing a
455
+
> single printable character that is not a \<blank\>.
456
+
>
457
+
> The \<*entry type*\> character shall describe the type of file, as
458
+
> follows:
459
+
>
460
+
> `d`
461
+
> : Directory.
462
+
>
463
+
> `b`
464
+
> : Block special file.
465
+
>
466
+
> `c`
467
+
> : Character special file.
468
+
>
469
+
> `l` (ell)
470
+
> : Symbolic link.
471
+
>
472
+
> `p`
473
+
> : FIFO.
474
+
>
475
+
> `-`
476
+
> : Regular file.
477
+
>
478
+
> Implementations may add other characters to this list to represent
479
+
> other implementation-defined file types.
480
+
>
481
+
> The next three fields shall be three characters each:
482
+
>
483
+
> \<*owner permissions*\>
484
+
> : Permissions for the file owner class (see XBD [*File Access
485
+
> Permissions*](../basedefs/V1_chap04.html#tag_04_05) ).
486
+
>
487
+
> \<*group permissions*\>
488
+
> : Permissions for the file group class.
489
+
>
490
+
> \<*other permissions*\>
491
+
> : Permissions for the file other class.
492
+
>
493
+
> Each field shall have three character positions:
494
+
>
495
+
> 1. If `'r'`, the file is readable; if `'-'`, the file is not
496
+
> readable.
497
+
>
498
+
> 2. If `'w'`, the file is writable; if `'-'`, the file is not
499
+
> writable.
500
+
>
501
+
> 3. The first of the following that applies:
502
+
>
503
+
> `S`
504
+
> : If in \<*owner permissions*\>, the file is not executable and
505
+
> set-user-ID mode is set. If in \<*group permissions*\>, the
506
+
> file is not executable and set-group-ID mode is set.
507
+
>
508
+
> `s`
509
+
> : If in \<*owner permissions*\>, the file is executable and
510
+
> set-user-ID mode is set. If in \<*group permissions*\>, the
511
+
> file is executable and set-group-ID mode is set.
512
+
>
513
+
> `T`
514
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
515
+
> Start\]](../images/opt-start.gif){border="0"} If in
516
+
> \<*other permissions*\> and the file is a directory, search
517
+
> permission is not granted to others, and the restricted
518
+
> deletion flag is set. ![\[Option
519
+
> End\]](../images/opt-end.gif){border="0"}
520
+
>
521
+
> `t`
522
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
523
+
> Start\]](../images/opt-start.gif){border="0"} If in
524
+
> \<*other permissions*\> and the file is a directory, search
525
+
> permission is granted to others, and the restricted deletion
526
+
> flag is set. ![\[Option
527
+
> End\]](../images/opt-end.gif){border="0"}
528
+
>
529
+
> `x`
530
+
> : The file is executable or the directory is searchable.
531
+
>
532
+
> `-`
533
+
> : None of the attributes of `'S'`, `'s'`, `'T'`, `'t'`, or `'x'`
534
+
> applies.
535
+
>
536
+
> Implementations may add other characters to this list for the
537
+
> third character position. Such additions shall, however, be
538
+
> written in lowercase if the file is executable or searchable, and
539
+
> in uppercase if it is not.
540
+
>
541
+
> If any of the **-l**, **-n**, **-s**,
542
+
> ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
543
+
> Start\]](../images/opt-start.gif){border="0"} **-g**, or **-o**
544
+
> ![\[Option End\]](../images/opt-end.gif){border="0"} options is
545
+
> specified, each list of files within the directory shall be preceded
546
+
> by a status line indicating the number of file system blocks occupied
547
+
> by files in the directory in 512-byte units if the **-k** option is
548
+
> not specified, or 1024-byte units if the **-k** option is specified,
549
+
> rounded up to the next integral number of units, if necessary. In the
550
+
> POSIX locale, the format shall be:
551
+
>
552
+
>
553
+
> "total %u\n", <number of units in the directory>
554
+
>
555
+
> If more than one directory, or a combination of non-directory files
556
+
> and directories are written, either as a result of specifying multiple
557
+
> operands, or the **-R** option, each list of files within a directory
558
+
> shall be preceded by:
559
+
>
560
+
>
561
+
> "\n%s:\n", <directory name>
562
+
>
563
+
> If this string is the first thing to be written, the first \<newline\>
564
+
> shall not be written. This output shall precede the number of units in
565
+
> the directory.
566
+
>
567
+
> If the **-s** option is given, each file shall be written with the
568
+
> number of blocks used by the file. Along with **-C**, **-1**, **-m**,
569
+
> or **-x**, the number and a \<space\> shall precede the filename; with
570
+
> **-l**, **-n**, ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
571
+
> Start\]](../images/opt-start.gif){border="0"} **-g**, or **-o**,
572
+
> ![\[Option End\]](../images/opt-end.gif){border="0"} they shall
573
+
> precede each line describing a file.
574
+
575
+
#### []{#tag_20_73_11}STDERR {#stderr .mansect}
576
+
577
+
> The standard error shall be used only for diagnostic messages.
578
+
579
+
#### []{#tag_20_73_12}OUTPUT FILES {#output-files .mansect}
580
+
581
+
> None.
582
+
583
+
#### []{#tag_20_73_13}EXTENDED DESCRIPTION {#extended-description .mansect}
584
+
585
+
> None.
586
+
587
+
#### []{#tag_20_73_14}EXIT STATUS {#exit-status .mansect}
588
+
589
+
> The following exit values shall be returned:
590
+
>
591
+
> 0
592
+
> : Successful completion.
593
+
>
594
+
> \>0
595
+
> : An error occurred.
596
+
597
+
#### []{#tag_20_73_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
598
+
599
+
> Default.
600
+
601
+
------------------------------------------------------------------------
602
+
603
+
::: box
604
+
*The following sections are informative.*
605
+
:::
606
+
607
+
#### []{#tag_20_73_16}APPLICATION USAGE {#application-usage .mansect}
608
+
609
+
> Many implementations use the \<equals-sign\> ( `'='` ) to denote
610
+
> sockets bound to the file system for the **-F** option. Similarly,
611
+
> many historical implementations use the `'s'` character to denote
612
+
> sockets as the entry type characters for the **-l** option.
613
+
>
614
+
> It is difficult for an application to use every part of the file modes
615
+
> field of *ls* **-l** in a portable manner. Certain file types and
616
+
> executable bits are not guaranteed to be exactly as shown, as
617
+
> implementations may have extensions. Applications can use this field
618
+
> to pass directly to a user printout or prompt, but actions based on
619
+
> its contents should generally be deferred, instead, to the
620
+
> [*test*](../utilities/test.html) utility.
621
+
>
622
+
> The output of *ls* (with the **-l** and related options) contains
623
+
> information that logically could be used by utilities such as
624
+
> [*chmod*](../utilities/chmod.html) and
625
+
> [*touch*](../utilities/touch.html) to restore files to a known state.
626
+
> However, this information is presented in a format that cannot be used
627
+
> directly by those utilities or be easily translated into a format that
628
+
> can be used. A character has been added to the end of the permissions
629
+
> string so that applications at least have an indication that they may
630
+
> be working in an area they do not understand instead of assuming that
631
+
> they can translate the permissions string into something that can be
632
+
> used. Future versions or related documents may define one or more
633
+
> specific characters to be used based on different standard additional
634
+
> or alternative access control mechanisms.
635
+
>
636
+
> As with many of the utilities that deal with filenames, the output of
637
+
> *ls* for multiple files or in one of the long listing formats must be
638
+
> used carefully on systems where filenames can contain embedded white
639
+
> space. Systems and system administrators should institute policies and
640
+
> user training to limit the use of such filenames.
641
+
>
642
+
> The number of disk blocks occupied by the file that it reports varies
643
+
> depending on underlying file system type, block size units reported,
644
+
> and the method of calculating the number of blocks. On some file
645
+
> system types, the number is the actual number of blocks occupied by
646
+
> the file (counting indirect blocks and ignoring holes in the file); on
647
+
> others it is calculated based on the file size (usually making an
648
+
> allowance for indirect blocks, but ignoring holes).
649
+
650
+
#### []{#tag_20_73_17}EXAMPLES {#examples .mansect}
651
+
652
+
> An example of a small directory tree being fully listed with *ls*
653
+
> **-laRF a** in the POSIX locale:
654
+
>
655
+
>
656
+
> total 11
657
+
> drwxr-xr-x 3 fox prog 64 Jul 4 12:07 ./
658
+
> drwxrwxrwx 4 fox prog 3264 Jul 4 12:09 ../
659
+
> drwxr-xr-x 2 fox prog 48 Jul 4 12:07 b/
660
+
> -rwxr--r-- 1 fox prog 572 Jul 4 12:07 foo*
661
+
>
662
+
>
663
+
> a/b:
664
+
> total 4
665
+
> drwxr-xr-x 2 fox prog 48 Jul 4 12:07 ./
666
+
> drwxr-xr-x 3 fox prog 64 Jul 4 12:07 ../
667
+
> -rw-r--r-- 1 fox prog 700 Jul 4 12:07 bar
668
+
669
+
#### []{#tag_20_73_18}RATIONALE {#rationale .mansect}
670
+
671
+
> Some historical implementations of the *ls* utility show all entries
672
+
> in a directory except dot and dot-dot when a superuser invokes *ls*
673
+
> without specifying the **-a** option. When \"normal\" users invoke
674
+
> *ls* without specifying **-a**, they should not see information about
675
+
> any files with names beginning with a \<period\> unless they were
676
+
> named as *file* operands.
677
+
>
678
+
> Implementations are expected to traverse arbitrary depths when
679
+
> processing the **-R** option. The only limitation on depth should be
680
+
> based on running out of physical storage for keeping track of
681
+
> untraversed directories.
682
+
>
683
+
> The **-1** (one) option was historically found in BSD and BSD-derived
684
+
> implementations only. It is required in this volume of POSIX.1-2017 so
685
+
> that conforming applications might ensure that output is one entry per
686
+
> line, even if the output is to a terminal.
687
+
>
688
+
> The **-S** option was added in Issue 7, but had been provided by
689
+
> several implementations for many years. The description given in the
690
+
> standard documents historic practice, but does not match much of the
691
+
> documentation that described its behavior. Historical documentation
692
+
> typically described it as something like:
693
+
>
694
+
> **-S**
695
+
> : Sort by size (largest size first) instead of by name. Special
696
+
> character devices (listed last) are sorted by name.
697
+
>
698
+
> even though the file type was never considered when sorting the
699
+
> output. Character special files do typically sort close to the end of
700
+
> the list because their file size on most implementations is zero. But
701
+
> they are sorted alphabetically with any other files that happen to
702
+
> have the same file size (zero), not sorted separately and added to the
703
+
> end.
704
+
>
705
+
> This volume of POSIX.1-2017 is frequently silent about what happens
706
+
> when mutually-exclusive options are specified. Except for **-R**,
707
+
> **-d**, and **-f**, the *ls* utility is required to accept multiple
708
+
> options from each mutually-exclusive option set without treating them
709
+
> as errors and to use the behavior specified by the last option given
710
+
> in each mutually-exclusive set. Since *ls* is one of the most aliased
711
+
> commands, it is important that the implementation perform intuitively.
712
+
> For example, if the alias were:
713
+
>
714
+
>
715
+
> alias ls="ls -C"
716
+
>
717
+
> and the user typed *ls* **-1** (one), single-text-column output should
718
+
> result, not an error.
719
+
>
720
+
> The **-g**, **-l** (ell), **-n**, and **-o** options are not
721
+
> mutually-exclusive options. They all enable long format output. They
722
+
> work together to determine whether the file\'s owner is written (no if
723
+
> **-g** is present), file\'s group is written (no if **-o** is
724
+
> present), and if the file\'s group or owner is written whether it is
725
+
> written as the name (default) or a string representation of the UID or
726
+
> GID number (if **-n** is present). The **-C**, **-m**, **-x**, and
727
+
> **-1** (one) are mutually-exclusive options and the first three of
728
+
> these disable long format output. The **-1** (one) option does not
729
+
> directly change whether or not long format output is enabled, but by
730
+
> overriding **-C**, **-m**, and **-x**, it can re-enable long format
731
+
> output that had been disabled by one of these options.
732
+
>
733
+
> Earlier versions of this standard did not describe the BSD **-A**
734
+
> option (like **-a**, but dot and dot-dot are not written out). It has
735
+
> been added due to widespread implementation.
736
+
>
737
+
> Implementations may make **-q** the default for terminals to prevent
738
+
> trojan horse attacks on terminals with special escape sequences. This
739
+
> is not required because:
740
+
>
741
+
> - Some control characters may be useful on some terminals; for
742
+
> example, a system might write them as `"\001"` or `"^A"`.
743
+
>
744
+
> - Special behavior for terminals is not relevant to applications
745
+
> portability.
746
+
>
747
+
> An early proposal specified that the
748
+
> \<*optional alternate access method flag*\> had to be `'+'` if there
749
+
> was an alternate access method used on the file or \<space\> if there
750
+
> was not. This was changed to be \<space\> if there is not and a single
751
+
> printable character if there is. This was done for three reasons:
752
+
>
753
+
> 1. There are historical implementations using characters other than
754
+
> `'+'`.
755
+
>
756
+
> 2. There are implementations that vary this character used in that
757
+
> position to distinguish between various alternate access methods
758
+
> in use.
759
+
>
760
+
> 3. The standard developers did not want to preclude future
761
+
> specifications that might need a way to specify more than one
762
+
> alternate access method.
763
+
>
764
+
> Nonetheless, implementations providing a single alternate access
765
+
> method are encouraged to use `'+'`.
766
+
>
767
+
> Earlier versions of this standard did not have the **-k** option,
768
+
> which meant that the **-s** option could not be used portably as its
769
+
> block size was implementation-defined, and the units used to specify
770
+
> the number of blocks occupied by files in a directory in an *ls*
771
+
> **-l** listing were fixed as 512-byte units. The **-k** option has
772
+
> been added to provide a way for the **-s** option to be used portably,
773
+
> and for consistency it also changes the aforementioned units from
774
+
> 512-byte to 1024-byte.
775
+
>
776
+
> The \<*date and time*\> field in the **-l** format is specified only
777
+
> for the POSIX locale. As noted, the format can be different in other
778
+
> locales. No mechanism for defining this is present in this volume of
779
+
> POSIX.1-2017, as the appropriate vehicle is a messaging system; that
780
+
> is, the format should be specified as a \"message\".
781
+
782
+
#### []{#tag_20_73_19}FUTURE DIRECTIONS {#future-directions .mansect}
783
+
784
+
> Allowing **-f** to ignore the **-A**, **-g**, **-l**, **-n**, **-o**,
785
+
> and **-s** options may be removed in a future version.
786
+
>
787
+
> A future version of this standard may require that if the collating
788
+
> sequence for the current locale does not have a total ordering of all
789
+
> characters, any filenames or pathnames that collate equally are
790
+
> further compared byte-by-byte using the collating sequence for the
791
+
> POSIX locale.
792
+
793
+
#### []{#tag_20_73_20}SEE ALSO {#see-also .mansect}
794
+
795
+
> [*chmod*](../utilities/chmod.html#tag_20_17),
796
+
> [*find*](../utilities/find.html#)
797
+
>
798
+
> XBD [*LC_COLLATE*](../basedefs/V1_chap07.html#tag_07_03_02), [*File
799
+
> Access Permissions*](../basedefs/V1_chap04.html#tag_04_05),
800
+
> [*Environment Variables*](../basedefs/V1_chap08.html#tag_08),
801
+
> [*Utility Syntax Guidelines*](../basedefs/V1_chap12.html#tag_12_02),
802
+
> [*\<sys/stat.h\>*](../basedefs/sys_stat.h.html)
803
+
>
804
+
> XSH [*fstatat*](../functions/fstatat.html#)
805
+
806
+
#### []{#tag_20_73_21}CHANGE HISTORY {#change-history .mansect}
807
+
808
+
> First released in Issue 2.
809
+
810
+
#### []{#tag_20_73_22}Issue 5 {#issue-5 .mansect}
811
+
812
+
> A second FUTURE DIRECTION is added.
813
+
814
+
#### []{#tag_20_73_23}Issue 6 {#issue-6 .mansect}
815
+
816
+
> The following new requirements on POSIX implementations derive from
817
+
> alignment with the Single UNIX Specification:
818
+
>
819
+
> - In the **-F** option, other symbols are allowed for other file
820
+
> types.
821
+
>
822
+
> Treatment of symbolic links is added, as defined in the IEEE P1003.2b
823
+
> draft standard.
824
+
>
825
+
> The Open Group Base Resolution bwg2001-010 is applied, adding the `T`
826
+
> and `t` fields as part of the XSI option.
827
+
828
+
#### []{#tag_20_73_24}Issue 7 {#issue-7 .mansect}
829
+
830
+
> Austin Group Interpretation 1003.1-2001 #101 is applied, clarifying
831
+
> the optional alternate access method flag in the STDOUT section.
832
+
>
833
+
> Austin Group Interpretation 1003.1-2001 #128 is applied, clarifying
834
+
> the DESCRIPTION and the definition of the **-R** option.
835
+
>
836
+
> Austin Group Interpretation 1003.1-2001 #129 is applied, clarifying
837
+
> the behavior of *ls* when no operands are specified.
838
+
>
839
+
> Austin Group Interpretation 1003.1-2001 #198 is applied, clarifying
840
+
> the requirements for the **-H** option.
841
+
>
842
+
> SD5-XCU-ERN-50 is applied, adding the **-A** option.
843
+
>
844
+
> SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.
845
+
>
846
+
> The **-S** option is added from The Open Group Technical Standard,
847
+
> 2006, Extended API Set Part 1.
848
+
>
849
+
> The **-f**, **-m**, **-n**, **-p**, **-s**, and **-x** options are
850
+
> moved from the XSI option to the Base.
851
+
>
852
+
> The description of the **-f**, **-s**, and **-t** options are revised
853
+
> and the **-k** option is added.
854
+
>
855
+
> POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0098 \[424\],
856
+
> XCU/TC1-2008/0099 \[424\], XCU/TC1-2008/0100 \[424\],
857
+
> XCU/TC1-2008/0101 \[424\], XCU/TC1-2008/0102 \[424\],
858
+
> XCU/TC1-2008/0103 \[424\], XCU/TC1-2008/0104 \[424\],
859
+
> XCU/TC1-2008/0105 \[423,424\], XCU/TC1-2008/0106 \[424\],
860
+
> XCU/TC1-2008/0107 \[424\], XCU/TC1-2008/0108 \[424\],
861
+
> XCU/TC1-2008/0109 \[424\], XCU/TC1-2008/0110 \[424\],
862
+
> XCU/TC1-2008/0111 \[423\], XCU/TC1-2008/0112 \[117\],
863
+
> XCU/TC1-2008/0113 \[117\], XCU/TC1-2008/0114 \[117\],
864
+
> XCU/TC1-2008/0115 \[424\], and XCU/TC1-2008/0116 \[424\] are applied.
865
+
>
866
+
> POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0115 \[963\] and
867
+
> XCU/TC2-2008/0116 \[963\] are applied.
868
+
+239
docs/posix2018/mkdir.md
+239
docs/posix2018/mkdir.md
···
1
+
#### []{#tag_20_79_01}NAME {#name .mansect}
2
+
3
+
> mkdir - make directories
4
+
5
+
#### []{#tag_20_79_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `mkdir`` `**`[`**`-p`**`] [`**`-m`` `*`mode`***`]`**` `*`dir`*`...`
8
+
9
+
#### []{#tag_20_79_03}DESCRIPTION {#description .mansect}
10
+
11
+
> The *mkdir* utility shall create the directories specified by the
12
+
> operands, in the order specified.
13
+
>
14
+
> For each *dir* operand, the *mkdir* utility shall perform actions
15
+
> equivalent to the [*mkdir*()](../functions/mkdir.html) function
16
+
> defined in the System Interfaces volume of POSIX.1-2017, called with
17
+
> the following arguments:
18
+
>
19
+
> 1. The *dir* operand is used as the *path* argument.
20
+
>
21
+
> 2. The value of the bitwise-inclusive OR of S_IRWXU, S_IRWXG, and
22
+
> S_IRWXO is used as the *mode* argument. (If the **-m** option is
23
+
> specified, the value of the [*mkdir*()](../functions/mkdir.html)
24
+
> *mode* argument is unspecified, but the directory shall at no time
25
+
> have permissions less restrictive than the **-m** *mode*
26
+
> option-argument.)
27
+
28
+
#### []{#tag_20_79_04}OPTIONS {#options .mansect}
29
+
30
+
> The *mkdir* utility shall conform to XBD [*Utility Syntax
31
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02).
32
+
>
33
+
> The following options shall be supported:
34
+
>
35
+
> **-m ** *mode*
36
+
> : Set the file permission bits of the newly-created directory to the
37
+
> specified *mode* value. The *mode* option-argument shall be the
38
+
> same as the *mode* operand defined for the
39
+
> [*chmod*](../utilities/chmod.html) utility. In the *symbolic_mode*
40
+
> strings, the *op* characters `'+'` and `'-'` shall be interpreted
41
+
> relative to an assumed initial mode of *a*= *rwx*; `'+'` shall add
42
+
> permissions to the default mode, `'-'` shall delete permissions
43
+
> from the default mode.
44
+
>
45
+
> **-p**
46
+
>
47
+
> : Create any missing intermediate pathname components.
48
+
>
49
+
> For each *dir* operand that does not name an existing directory,
50
+
> before performing the actions described in the DESCRIPTION above,
51
+
> the *mkdir* utility shall create any pathname components of the
52
+
> path prefix of *dir* that do not name an existing directory by
53
+
> performing actions equivalent to first calling the
54
+
> [*mkdir*()](../functions/mkdir.html) function with the following
55
+
> arguments:
56
+
>
57
+
> 1. A pathname naming the missing pathname component, ending with
58
+
> a trailing \<slash\> character, as the *path* argument
59
+
>
60
+
> 2. The value zero as the *mode* argument
61
+
>
62
+
> and then calling the [*chmod*()](../functions/chmod.html) function
63
+
> with the following arguments:
64
+
>
65
+
> 1. The same *path* argument as in the
66
+
> [*mkdir*()](../functions/mkdir.html) call
67
+
>
68
+
> 2. The value `(S_IWUSR|S_IXUSR|~`*`filemask`*`)&0777` as the
69
+
> *mode* argument, where *filemask* is the file mode creation
70
+
> mask of the process (see XSH
71
+
> [*umask*](../functions/umask.html#tag_16_631))
72
+
>
73
+
> Each *dir* operand that names an existing directory shall be
74
+
> ignored without error.
75
+
76
+
#### []{#tag_20_79_05}OPERANDS {#operands .mansect}
77
+
78
+
> The following operand shall be supported:
79
+
>
80
+
> *dir*
81
+
> : A pathname of a directory to be created.
82
+
83
+
#### []{#tag_20_79_06}STDIN {#stdin .mansect}
84
+
85
+
> Not used.
86
+
87
+
#### []{#tag_20_79_07}INPUT FILES {#input-files .mansect}
88
+
89
+
> None.
90
+
91
+
#### []{#tag_20_79_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
92
+
93
+
> The following environment variables shall affect the execution of
94
+
> *mkdir*:
95
+
>
96
+
> *LANG*
97
+
> : Provide a default value for the internationalization variables
98
+
> that are unset or null. (See XBD [*Internationalization
99
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
100
+
> precedence of internationalization variables used to determine the
101
+
> values of locale categories.)
102
+
>
103
+
> *LC_ALL*
104
+
> : If set to a non-empty string value, override the values of all the
105
+
> other internationalization variables.
106
+
>
107
+
> *LC_CTYPE*
108
+
> : Determine the locale for the interpretation of sequences of bytes
109
+
> of text data as characters (for example, single-byte as opposed to
110
+
> multi-byte characters in arguments).
111
+
>
112
+
> *LC_MESSAGES*
113
+
> : Determine the locale that should be used to affect the format and
114
+
> contents of diagnostic messages written to standard error.
115
+
>
116
+
> *NLSPATH*
117
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
118
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
119
+
> location of message catalogs for the processing of *LC_MESSAGES.*
120
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
121
+
122
+
#### []{#tag_20_79_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
123
+
124
+
> Default.
125
+
126
+
#### []{#tag_20_79_10}STDOUT {#stdout .mansect}
127
+
128
+
> Not used.
129
+
130
+
#### []{#tag_20_79_11}STDERR {#stderr .mansect}
131
+
132
+
> The standard error shall be used only for diagnostic messages.
133
+
134
+
#### []{#tag_20_79_12}OUTPUT FILES {#output-files .mansect}
135
+
136
+
> None.
137
+
138
+
#### []{#tag_20_79_13}EXTENDED DESCRIPTION {#extended-description .mansect}
139
+
140
+
> None.
141
+
142
+
#### []{#tag_20_79_14}EXIT STATUS {#exit-status .mansect}
143
+
144
+
> The following exit values shall be returned:
145
+
>
146
+
> 0
147
+
> : All the specified directories were created successfully, or the
148
+
> **-p** option was specified and all the specified directories
149
+
> either already existed or were created successfully.
150
+
>
151
+
> \>0
152
+
> : An error occurred.
153
+
154
+
#### []{#tag_20_79_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
155
+
156
+
> Default.
157
+
158
+
------------------------------------------------------------------------
159
+
160
+
::: box
161
+
*The following sections are informative.*
162
+
:::
163
+
164
+
#### []{#tag_20_79_16}APPLICATION USAGE {#application-usage .mansect}
165
+
166
+
> The default file mode for directories is *a*= *rwx* (777 on most
167
+
> systems) with selected permissions removed in accordance with the file
168
+
> mode creation mask. For intermediate pathname components created by
169
+
> *mkdir*, the mode is the default modified by *u*+ *wx* so that the
170
+
> subdirectories can always be created regardless of the file mode
171
+
> creation mask; if different ultimate permissions are desired for the
172
+
> intermediate directories, they can be changed afterwards with
173
+
> [*chmod*](../utilities/chmod.html).
174
+
>
175
+
> Note that some of the requested directories may have been created even
176
+
> if an error occurs.
177
+
178
+
#### []{#tag_20_79_17}EXAMPLES {#examples .mansect}
179
+
180
+
> None.
181
+
182
+
#### []{#tag_20_79_18}RATIONALE {#rationale .mansect}
183
+
184
+
> The System V **-m** option was included to control the file mode.
185
+
>
186
+
> The System V **-p** option was included to create any needed
187
+
> intermediate directories and to complement the functionality provided
188
+
> by [*rmdir*](../utilities/rmdir.html) for removing directories in the
189
+
> path prefix as they become empty. Because no error is produced if any
190
+
> path component already exists, the **-p** option is also useful to
191
+
> ensure that a particular directory exists.
192
+
>
193
+
> The functionality of *mkdir* is described substantially through a
194
+
> reference to the [*mkdir*()](../functions/mkdir.html) function in the
195
+
> System Interfaces volume of POSIX.1-2017. For example, by default, the
196
+
> mode of the directory is affected by the file mode creation mask in
197
+
> accordance with the specified behavior of the
198
+
> [*mkdir*()](../functions/mkdir.html) function. In this way, there is
199
+
> less duplication of effort required for describing details of the
200
+
> directory creation.
201
+
202
+
#### []{#tag_20_79_19}FUTURE DIRECTIONS {#future-directions .mansect}
203
+
204
+
> None.
205
+
206
+
#### []{#tag_20_79_20}SEE ALSO {#see-also .mansect}
207
+
208
+
> [*chmod*](../utilities/chmod.html#tag_20_17),
209
+
> [*rm*](../utilities/rm.html#),
210
+
> [*rmdir*](../utilities/rmdir.html#tag_20_113),
211
+
> [*umask*](../utilities/umask.html#tag_20_138)
212
+
>
213
+
> XBD [*Environment Variables*](../basedefs/V1_chap08.html#tag_08),
214
+
> [*Utility Syntax Guidelines*](../basedefs/V1_chap12.html#tag_12_02)
215
+
>
216
+
> XSH [*mkdir*](../functions/mkdir.html#tag_16_325),
217
+
> [*umask*](../functions/umask.html#tag_16_631)
218
+
219
+
#### []{#tag_20_79_21}CHANGE HISTORY {#change-history .mansect}
220
+
221
+
> First released in Issue 2.
222
+
223
+
#### []{#tag_20_79_22}Issue 5 {#issue-5 .mansect}
224
+
225
+
> The FUTURE DIRECTIONS section is added.
226
+
227
+
#### []{#tag_20_79_23}Issue 7 {#issue-7 .mansect}
228
+
229
+
> SD5-XCU-ERN-56 is applied, aligning the **-m** option with the
230
+
> IEEE P1003.2b draft standard to clarify an ambiguity.
231
+
>
232
+
> SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.
233
+
>
234
+
> POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0122 \[161\] is
235
+
> applied.
236
+
>
237
+
> POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0145 \[843\] is
238
+
> applied.
239
+
+931
docs/posix2018/more.md
+931
docs/posix2018/more.md
···
1
+
#### []{#tag_20_81_01}NAME {#name .mansect}
2
+
3
+
> more - display files on a page-by-page basis
4
+
5
+
#### []{#tag_20_81_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> ::: box
8
+
> ^`[`[`UP`](javascript:open_code('UP'))`]`^` `![`[Option Start]`](../images/opt-start.gif){border="0"}` more`` `**`[`**`-ceisu`**`] [`**`-n`` `*`number`***`] [`**`-p`` `*`command`***`] [`**`-t`` `*`tagstring`***`] [`***`file`*`...`**`]`**![`[Option End]`](../images/opt-end.gif){border="0"}
9
+
> :::
10
+
11
+
#### []{#tag_20_81_03}DESCRIPTION {#description .mansect}
12
+
13
+
> The *more* utility shall read files and either write them to the
14
+
> terminal on a page-by-page basis or filter them to standard output. If
15
+
> standard output is not a terminal device, all input files shall be
16
+
> copied to standard output in their entirety, without modification,
17
+
> except as specified for the **-s** option. If standard output is a
18
+
> terminal device, the files shall be written a number of lines (one
19
+
> screenful) at a time under the control of user commands. See the
20
+
> EXTENDED DESCRIPTION section.
21
+
>
22
+
> Certain block-mode terminals do not have all the capabilities
23
+
> necessary to support the complete *more* definition; they are
24
+
> incapable of accepting commands that are not terminated with a
25
+
> \<newline\>. Implementations that support such terminals shall provide
26
+
> an operating mode to *more* in which all commands can be terminated
27
+
> with a \<newline\> on those terminals. This mode:
28
+
>
29
+
> - Shall be documented in the system documentation
30
+
>
31
+
> - Shall, at invocation, inform the user of the terminal deficiency
32
+
> that requires the \<newline\> usage and provide instructions on how
33
+
> this warning can be suppressed in future invocations
34
+
>
35
+
> - Shall not be required for implementations supporting only fully
36
+
> capable terminals
37
+
>
38
+
> - Shall not affect commands already requiring \<newline\> characters
39
+
>
40
+
> - Shall not affect users on the capable terminals from using *more* as
41
+
> described in this volume of POSIX.1-2017
42
+
43
+
#### []{#tag_20_81_04}OPTIONS {#options .mansect}
44
+
45
+
> The *more* utility shall conform to XBD [*Utility Syntax
46
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02) , except that `'+'`
47
+
> may be recognized as an option delimiter as well as `'-'`.
48
+
>
49
+
> The following options shall be supported:
50
+
>
51
+
> **-c**
52
+
> : If a screen is to be written that has no lines in common with the
53
+
> current screen, or *more* is writing its first screen, *more*
54
+
> shall not scroll the screen, but instead shall redraw each line of
55
+
> the screen in turn, from the top of the screen to the bottom. In
56
+
> addition, if *more* is writing its first screen, the screen shall
57
+
> be cleared. This option may be silently ignored on devices with
58
+
> insufficient terminal capabilities.
59
+
>
60
+
> **-e**
61
+
> : Exit immediately after writing the last line of the last file in
62
+
> the argument list; see the EXTENDED DESCRIPTION section.
63
+
>
64
+
> **-i**
65
+
> : Perform pattern matching in searches without regard to case; see
66
+
> XBD [*Regular Expression General
67
+
> Requirements*](../basedefs/V1_chap09.html#tag_09_02).
68
+
>
69
+
> **-n ** *number*
70
+
> : Specify the number of lines per screenful. The *number* argument
71
+
> is a positive decimal integer. The **-n** option shall override
72
+
> any values obtained from any other source.
73
+
>
74
+
> **-p ** *command*
75
+
> : Each time a screen from a new file is displayed or redisplayed
76
+
> (including as a result of *more* commands; for example, **:p**),
77
+
> execute the *more* command(s) in the command arguments in the
78
+
> order specified, as if entered by the user after the first screen
79
+
> has been displayed. No intermediate results shall be displayed
80
+
> (that is, if the command is a movement to a screen different from
81
+
> the normal first screen, only the screen resulting from the
82
+
> command shall be displayed.) If any of the commands fail for any
83
+
> reason, an informational message to this effect shall be written,
84
+
> and no further commands specified using the **-p** option shall be
85
+
> executed for this file.
86
+
>
87
+
> **-s**
88
+
> : Behave as if consecutive empty lines were a single empty line.
89
+
>
90
+
> **-t ** *tagstring*
91
+
>
92
+
> : Write the screenful of the file containing the tag named by the
93
+
> *tagstring* argument. See the [*ctags*](../utilities/ctags.html#)
94
+
> utility. The tags feature represented by **-t** *tagstring* and
95
+
> the **:t** command is optional. It shall be provided on any system
96
+
> that also provides a conforming implementation of
97
+
> [*ctags*](../utilities/ctags.html); otherwise, the use of **-t**
98
+
> produces undefined results.
99
+
>
100
+
> The filename resulting from the **-t** option shall be logically
101
+
> added as a prefix to the list of command line files, as if
102
+
> specified by the user. If the tag named by the *tagstring*
103
+
> argument is not found, it shall be an error, and *more* shall take
104
+
> no further action.
105
+
>
106
+
> If the tag specifies a line number, the first line of the display
107
+
> shall contain the beginning of that line. If the tag specifies a
108
+
> pattern, the first line of the display shall contain the beginning
109
+
> of the matching text from the first line of the file that contains
110
+
> that pattern. If the line does not exist in the file or matching
111
+
> text is not found, an informational message to this effect shall
112
+
> be displayed, and *more* shall display the default screen as if
113
+
> **-t** had not been specified.
114
+
>
115
+
> If both the **-t** *tagstring* and **-p** *command* options are
116
+
> given, the **-t** *tagstring* shall be processed first; that is,
117
+
> the file and starting line for the display shall be as specified
118
+
> by **-t**, and then the **-p** *more* command shall be executed.
119
+
> If the line (matching text) specified by the **-t** command does
120
+
> not exist (is not found), no **-p** *more* command shall be
121
+
> executed for this file at any time.
122
+
>
123
+
> **-u**
124
+
> : Treat a \<backspace\> as a printable control character, displayed
125
+
> as an implementation-defined character sequence (see the EXTENDED
126
+
> DESCRIPTION section), suppressing backspacing and the special
127
+
> handling that produces underlined or standout mode text on some
128
+
> terminal types. Also, do not ignore a \<carriage-return\> at the
129
+
> end of a line.
130
+
131
+
#### []{#tag_20_81_05}OPERANDS {#operands .mansect}
132
+
133
+
> The following operand shall be supported:
134
+
>
135
+
> *file*
136
+
> : A pathname of an input file. If no *file* operands are specified,
137
+
> the standard input shall be used. If a *file* is `'-'`, the
138
+
> standard input shall be read at that point in the sequence.
139
+
140
+
#### []{#tag_20_81_06}STDIN {#stdin .mansect}
141
+
142
+
> The standard input shall be used only if no *file* operands are
143
+
> specified, or if a *file* operand is `'-'` .
144
+
145
+
#### []{#tag_20_81_07}INPUT FILES {#input-files .mansect}
146
+
147
+
> The input files being examined shall be text files. If standard output
148
+
> is a terminal, standard error shall be used to read commands from the
149
+
> user. If standard output is a terminal, standard error is not
150
+
> readable, and command input is needed, *more* may attempt to obtain
151
+
> user commands from the controlling terminal (for example,
152
+
> **/dev/tty**); otherwise, *more* shall terminate with an error
153
+
> indicating that it was unable to read user commands. If standard
154
+
> output is not a terminal, no error shall result if standard error
155
+
> cannot be opened for reading.
156
+
157
+
#### []{#tag_20_81_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
158
+
159
+
> The following environment variables shall affect the execution of
160
+
> *more*:
161
+
>
162
+
> *COLUMNS*
163
+
> : Override the system-selected horizontal display line size. See XBD
164
+
> [*Environment Variables*](../basedefs/V1_chap08.html#tag_08) for
165
+
> valid values and results when it is unset or null.
166
+
>
167
+
> *EDITOR*
168
+
> : Used by the **v** command to select an editor. See the EXTENDED
169
+
> DESCRIPTION section.
170
+
>
171
+
> *LANG*
172
+
> : Provide a default value for the internationalization variables
173
+
> that are unset or null. (See XBD [*Internationalization
174
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
175
+
> precedence of internationalization variables used to determine the
176
+
> values of locale categories.)
177
+
>
178
+
> *LC_ALL*
179
+
> : If set to a non-empty string value, override the values of all the
180
+
> other internationalization variables.
181
+
>
182
+
> *LC_COLLATE*
183
+
> : Determine the locale for the behavior of ranges, equivalence
184
+
> classes, and multi-character collating elements within regular
185
+
> expressions.
186
+
>
187
+
> *LC_CTYPE*
188
+
> : Determine the locale for the interpretation of sequences of bytes
189
+
> of text data as characters (for example, single-byte as opposed to
190
+
> multi-byte characters in arguments and input files) and the
191
+
> behavior of character classes within regular expressions.
192
+
>
193
+
> *LC_MESSAGES*
194
+
> : Determine the locale that should be used to affect the format and
195
+
> contents of diagnostic messages written to standard error and
196
+
> informative messages written to standard output.
197
+
>
198
+
> *NLSPATH*
199
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
200
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
201
+
> location of message catalogs for the processing of *LC_MESSAGES.*
202
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
203
+
>
204
+
> *LINES*
205
+
> : Override the system-selected vertical screen size, used as the
206
+
> number of lines in a screenful. See XBD [*Environment
207
+
> Variables*](../basedefs/V1_chap08.html#tag_08) for valid values
208
+
> and results when it is unset or null. The **-n** option shall take
209
+
> precedence over the *LINES* variable for determining the number of
210
+
> lines in a screenful.
211
+
>
212
+
> *MORE*
213
+
>
214
+
> : Determine a string containing options described in the OPTIONS
215
+
> section preceded with \<hyphen-minus\> characters and
216
+
> \<blank\>-separated as on the command line. Any command line
217
+
> options shall be processed after those in the *MORE* variable, as
218
+
> if the command line were:
219
+
>
220
+
>
221
+
> more $MORE options operands
222
+
>
223
+
> The *MORE* variable shall take precedence over the *TERM* and
224
+
> *LINES* variables for determining the number of lines in a
225
+
> screenful.
226
+
>
227
+
> *TERM*
228
+
> : Determine the name of the terminal type. If this variable is unset
229
+
> or null, an unspecified default terminal type is used.
230
+
231
+
#### []{#tag_20_81_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
232
+
233
+
> Default.
234
+
235
+
#### []{#tag_20_81_10}STDOUT {#stdout .mansect}
236
+
237
+
> The standard output shall be used to write the contents of the input
238
+
> files.
239
+
240
+
#### []{#tag_20_81_11}STDERR {#stderr .mansect}
241
+
242
+
> The standard error shall be used for diagnostic messages and user
243
+
> commands (see the INPUT FILES section), and, if standard output is a
244
+
> terminal device, to write a prompting string. The prompting string
245
+
> shall appear on the screen line below the last line of the file
246
+
> displayed in the current screenful. The prompt shall contain the name
247
+
> of the file currently being examined and shall contain an end-of-file
248
+
> indication and the name of the next file, if any, when prompting at
249
+
> the end-of-file. If an error or informational message is displayed, it
250
+
> is unspecified whether it is contained in the prompt. If it is not
251
+
> contained in the prompt, it shall be displayed and then the user shall
252
+
> be prompted for a continuation character, at which point another
253
+
> message or the user prompt may be displayed. The prompt is otherwise
254
+
> unspecified. It is unspecified whether informational messages are
255
+
> written for other user commands.
256
+
257
+
#### []{#tag_20_81_12}OUTPUT FILES {#output-files .mansect}
258
+
259
+
> None.
260
+
261
+
#### []{#tag_20_81_13}EXTENDED DESCRIPTION {#extended-description .mansect}
262
+
263
+
> The following section describes the behavior of *more* when the
264
+
> standard output is a terminal device. If the standard output is not a
265
+
> terminal device, no options other than **-s** shall have any effect,
266
+
> and all input files shall be copied to standard output otherwise
267
+
> unmodified, at which time *more* shall exit without further action.
268
+
>
269
+
> The number of lines available per screen shall be determined by the
270
+
> **-n** option, if present, or by examining values in the environment
271
+
> (see the ENVIRONMENT VARIABLES section). If neither method yields a
272
+
> number, an unspecified number of lines shall be used.
273
+
>
274
+
> The maximum number of lines written shall be one less than this
275
+
> number, because the screen line after the last line written shall be
276
+
> used to write a user prompt and user input. If the number of lines in
277
+
> the screen is less than two, the results are undefined. It is
278
+
> unspecified whether user input is permitted to be longer than the
279
+
> remainder of the single line where the prompt has been written.
280
+
>
281
+
> The number of columns available per line shall be determined by
282
+
> examining values in the environment (see the ENVIRONMENT VARIABLES
283
+
> section), with a default value as described in XBD [*Environment
284
+
> Variables*](../basedefs/V1_chap08.html#tag_08).
285
+
>
286
+
> Lines that are longer than the display shall be folded; the length at
287
+
> which folding occurs is unspecified, but should be appropriate for the
288
+
> output device. Folding may occur between glyphs of single characters
289
+
> that take up multiple display columns.
290
+
>
291
+
> When standard output is a terminal and **-u** is not specified, *more*
292
+
> shall treat \<backspace\> and \<carriage-return\> characters
293
+
> specially:
294
+
>
295
+
> - A character, followed first by a sequence of *n* \<backspace\>
296
+
> characters (where *n* is the same as the number of column positions
297
+
> that the character occupies), then by *n* \<underscore\> characters
298
+
> ( `'_'` ), shall cause that character to be written as underlined
299
+
> text, if the terminal type supports that. The *n* \<underscore\>
300
+
> characters, followed first by *n* \<backspace\> characters, then any
301
+
> character with *n* column positions, shall also cause that character
302
+
> to be written as underlined text, if the terminal type supports
303
+
> that.
304
+
>
305
+
> - A sequence of *n* \<backspace\> characters (where *n* is the same as
306
+
> the number of column positions that the previous character occupies)
307
+
> that appears between two identical printable characters shall cause
308
+
> the first of those two characters to be written as emboldened text
309
+
> (that is, visually brighter, standout mode, or inverse-video mode),
310
+
> if the terminal type supports that, and the second to be discarded.
311
+
> Immediately subsequent occurrences of \<backspace\>/ character pairs
312
+
> for that same character shall also be discarded. (For example, the
313
+
> sequence `"a\ba\ba\ba"` is interpreted as a single emboldened
314
+
> `'a'`.)
315
+
>
316
+
> - The *more* utility shall logically discard all other \<backspace\>
317
+
> characters from the line as well as the character which precedes
318
+
> them, if any.
319
+
>
320
+
> - A \<carriage-return\> at the end of a line shall be ignored, rather
321
+
> than being written as a non-printable character, as described in the
322
+
> next paragraph.
323
+
>
324
+
> It is implementation-defined how other non-printable characters are
325
+
> written. Implementations should use the same format that they use for
326
+
> the [*ex*](../utilities/ex.html) **print** command; see the OPTIONS
327
+
> section within the [*ed*](../utilities/ed.html) utility. It is
328
+
> unspecified whether a multi-column character shall be separated if it
329
+
> crosses a display line boundary; it shall not be discarded. The
330
+
> behavior is unspecified if the number of columns on the display is
331
+
> less than the number of columns any single character in the line being
332
+
> displayed would occupy.
333
+
>
334
+
> When each new file is displayed (or redisplayed), *more* shall write
335
+
> the first screen of the file. Once the initial screen has been
336
+
> written, *more* shall prompt for a user command. If the execution of
337
+
> the user command results in a screen that has lines in common with the
338
+
> current screen, and the device has sufficient terminal capabilities,
339
+
> *more* shall scroll the screen; otherwise, it is unspecified whether
340
+
> the screen is scrolled or redrawn.
341
+
>
342
+
> For all files but the last (including standard input if no file was
343
+
> specified, and for the last file as well, if the **-e** option was not
344
+
> specified), when *more* has written the last line in the file, *more*
345
+
> shall prompt for a user command. This prompt shall contain the name of
346
+
> the next file as well as an indication that *more* has reached
347
+
> end-of-file. If the user command is **f**, \<control\>-F, \<space\>,
348
+
> **j**, \<newline\>, **d**, \<control\>-D, or **s**, *more* shall
349
+
> display the next file. Otherwise, if displaying the last file, *more*
350
+
> shall exit. Otherwise, *more* shall execute the user command
351
+
> specified.
352
+
>
353
+
> Several of the commands described in this section display a previous
354
+
> screen from the input stream. In the case that text is being taken
355
+
> from a non-rewindable stream, such as a pipe, it is
356
+
> implementation-defined how much backwards motion is supported. If a
357
+
> command cannot be executed because of a limitation on backwards
358
+
> motion, an error message to this effect shall be displayed, the
359
+
> current screen shall not change, and the user shall be prompted for
360
+
> another command.
361
+
>
362
+
> If a command cannot be performed because there are insufficient lines
363
+
> to display, *more* shall alert the terminal. If a command cannot be
364
+
> performed because there are insufficient lines to display or a **/**
365
+
> command fails: if the input is the standard input, the last screen in
366
+
> the file may be displayed; otherwise, the current file and screen
367
+
> shall not change, and the user shall be prompted for another command.
368
+
>
369
+
> The interactive commands in the following sections shall be supported.
370
+
> Some commands can be preceded by a decimal integer, called *count* in
371
+
> the following descriptions. If not specified with the command, *count*
372
+
> shall default to 1. In the following descriptions, *pattern* is a
373
+
> basic regular expression, as described in XBD [*Basic Regular
374
+
> Expressions*](../basedefs/V1_chap09.html#tag_09_03). The term
375
+
> \"examine\" is historical usage meaning \"open the file for
376
+
> viewing\'\'; for example, *more* **foo** would be expressed as
377
+
> examining file **foo**.
378
+
>
379
+
> In the following descriptions, unless otherwise specified, *line* is a
380
+
> line in the *more* display, not a line from the file being examined.
381
+
>
382
+
> In the following descriptions, the *current position* refers to two
383
+
> things:
384
+
>
385
+
> 1. The position of the current line on the screen
386
+
>
387
+
> 2. The line number (in the file) of the current line on the screen
388
+
>
389
+
> Usually, the line on the screen corresponding to the current position
390
+
> is the third line on the screen. If this is not possible (there are
391
+
> fewer than three lines to display or this is the first page of the
392
+
> file, or it is the last page of the file), then the current position
393
+
> is either the first or last line on the screen as described later.
394
+
>
395
+
> ##### []{#tag_20_81_13_01}Help
396
+
>
397
+
> *Synopsis*:
398
+
>
399
+
> :
400
+
> h
401
+
>
402
+
> Write a summary of these commands and other implementation-defined
403
+
> commands. The behavior shall be as if the *more* utility were executed
404
+
> with the **-e** option on a file that contained the summary
405
+
> information. The user shall be prompted as described earlier in this
406
+
> section when end-of-file is reached. If the user command is one of
407
+
> those specified to continue to the next file, *more* shall return to
408
+
> the file and screen state from which the **h** command was executed.
409
+
>
410
+
> ##### []{#tag_20_81_13_02}Scroll Forward One Screenful
411
+
>
412
+
> *Synopsis*:
413
+
>
414
+
> :
415
+
> [count]f
416
+
> [count]<control>-F
417
+
>
418
+
> Scroll forward *count* lines, with a default of one screenful. If
419
+
> *count* is more than the screen size, only the final screenful shall
420
+
> be written.
421
+
>
422
+
> ##### []{#tag_20_81_13_03}Scroll Backward One Screenful
423
+
>
424
+
> *Synopsis*:
425
+
>
426
+
> :
427
+
> [count]b
428
+
> [count]<control>-B
429
+
>
430
+
> Scroll backward *count* lines, with a default of one screenful (see
431
+
> the **-n** option). If *count* is more than the screen size, only the
432
+
> final screenful shall be written.
433
+
>
434
+
> ##### []{#tag_20_81_13_04}Scroll Forward One Line
435
+
>
436
+
> *Synopsis*:
437
+
>
438
+
> :
439
+
> [count]<space>
440
+
> [count]j
441
+
> [count]<newline>
442
+
>
443
+
> Scroll forward *count* lines. The default *count* for the \<space\>
444
+
> shall be one screenful; for **j** and \<newline\>, one line. The
445
+
> entire *count* lines shall be written, even if *count* is more than
446
+
> the screen size.
447
+
>
448
+
> ##### []{#tag_20_81_13_05}Scroll Backward One Line
449
+
>
450
+
> *Synopsis*:
451
+
>
452
+
> :
453
+
> [count]k
454
+
>
455
+
> Scroll backward *count* lines. The entire *count* lines shall be
456
+
> written, even if *count* is more than the screen size.
457
+
>
458
+
> ##### []{#tag_20_81_13_06}Scroll Forward One Half Screenful
459
+
>
460
+
> *Synopsis*:
461
+
>
462
+
> :
463
+
> [count]d
464
+
> [count]<control>-D
465
+
>
466
+
> Scroll forward *count* lines, with a default of one half of the screen
467
+
> size. If *count* is specified, it shall become the new default for
468
+
> subsequent **d**, \<control\>-D, and **u** commands.
469
+
>
470
+
> ##### []{#tag_20_81_13_07}Skip Forward One Line
471
+
>
472
+
> *Synopsis*:
473
+
>
474
+
> :
475
+
> [count]s
476
+
>
477
+
> Display the screenful beginning with the line *count* lines after the
478
+
> last line on the current screen. If *count* would cause the current
479
+
> position to be such that less than one screenful would be written, the
480
+
> last screenful in the file shall be written.
481
+
>
482
+
> ##### []{#tag_20_81_13_08}Scroll Backward One Half Screenful
483
+
>
484
+
> *Synopsis*:
485
+
>
486
+
> :
487
+
> [count]u
488
+
> [count]<control>-U
489
+
>
490
+
> Scroll backward *count* lines, with a default of one half of the
491
+
> screen size. If *count* is specified, it shall become the new default
492
+
> for subsequent **d**, \<control\>-D, **u**, and \<control\>-U
493
+
> commands. The entire *count* lines shall be written, even if *count*
494
+
> is more than the screen size.
495
+
>
496
+
> ##### []{#tag_20_81_13_09}Go to Beginning of File
497
+
>
498
+
> *Synopsis*:
499
+
>
500
+
> :
501
+
> [count]g
502
+
>
503
+
> Display the screenful beginning with line *count*.
504
+
>
505
+
> ##### []{#tag_20_81_13_10}Go to End-of-File
506
+
>
507
+
> *Synopsis*:
508
+
>
509
+
> :
510
+
> [count]G
511
+
>
512
+
> If *count* is specified, display the screenful beginning with the line
513
+
> *count*. Otherwise, display the last screenful of the file.
514
+
>
515
+
> ##### []{#tag_20_81_13_11}Refresh the Screen
516
+
>
517
+
> *Synopsis*:
518
+
>
519
+
> :
520
+
> r
521
+
> <control>-L
522
+
>
523
+
> Refresh the screen.
524
+
>
525
+
> ##### []{#tag_20_81_13_12}Discard and Refresh
526
+
>
527
+
> *Synopsis*:
528
+
>
529
+
> :
530
+
> R
531
+
>
532
+
> Refresh the screen, discarding any buffered input. If the current file
533
+
> is non-seekable, buffered input shall not be discarded and the **R**
534
+
> command shall be equivalent to the **r** command.
535
+
>
536
+
> ##### []{#tag_20_81_13_13}Mark Position
537
+
>
538
+
> *Synopsis*:
539
+
>
540
+
> :
541
+
> mletter
542
+
>
543
+
> Mark the current position with the letter named by *letter*, where
544
+
> *letter* represents the name of one of the lowercase letters of the
545
+
> portable character set. When a new file is examined, all marks may be
546
+
> lost.
547
+
>
548
+
> ##### []{#tag_20_81_13_14}Return to Mark
549
+
>
550
+
> *Synopsis*:
551
+
>
552
+
> :
553
+
> 'letter
554
+
>
555
+
> Return to the position that was previously marked with the letter
556
+
> named by *letter*, making that line the current position.
557
+
>
558
+
> ##### []{#tag_20_81_13_15}Return to Previous Position
559
+
>
560
+
> *Synopsis*:
561
+
>
562
+
> :
563
+
> ''
564
+
>
565
+
> Return to the position from which the last large movement command was
566
+
> executed (where a \"large movement\" is defined as any movement of
567
+
> more than a screenful of lines). If no such movements have been made,
568
+
> return to the beginning of the file.
569
+
>
570
+
> ##### []{#tag_20_81_13_16}Search Forward for Pattern
571
+
>
572
+
> *Synopsis*:
573
+
>
574
+
> :
575
+
> [count]/[!]pattern<newline>
576
+
>
577
+
> Display the screenful beginning with the *count*th line containing the
578
+
> pattern. The search shall start after the first line currently
579
+
> displayed. The null regular expression ( `'/'` followed by a
580
+
> \<newline\>) shall repeat the search using the previous regular
581
+
> expression, with a default *count*. If the character `'!'` is
582
+
> included, the matching lines shall be those that do not contain the
583
+
> *pattern*. If no match is found for the *pattern*, a message to that
584
+
> effect shall be displayed.
585
+
>
586
+
> ##### []{#tag_20_81_13_17}Search Backward for Pattern
587
+
>
588
+
> *Synopsis*:
589
+
>
590
+
> :
591
+
> [count]?[!]pattern<newline>
592
+
>
593
+
> Display the screenful beginning with the *count*th previous line
594
+
> containing the pattern. The search shall start on the last line before
595
+
> the first line currently displayed. The null regular expression (
596
+
> `'?'` followed by a \<newline\>) shall repeat the search using the
597
+
> previous regular expression, with a default *count*. If the character
598
+
> `'!'` is included, matching lines shall be those that do not contain
599
+
> the *pattern*. If no match is found for the *pattern*, a message to
600
+
> that effect shall be displayed.
601
+
>
602
+
> ##### []{#tag_20_81_13_18}Repeat Search
603
+
>
604
+
> *Synopsis*:
605
+
>
606
+
> :
607
+
> [count]n
608
+
>
609
+
> Repeat the previous search for *count*th line containing the last
610
+
> *pattern* (or not containing the last *pattern*, if the previous
611
+
> search was `"/!"` or `"?!"` ).
612
+
>
613
+
> ##### []{#tag_20_81_13_19}Repeat Search in Reverse
614
+
>
615
+
> *Synopsis*:
616
+
>
617
+
> :
618
+
> [count]N
619
+
>
620
+
> Repeat the search in the opposite direction of the previous search for
621
+
> the *count*th line containing the last *pattern* (or not containing
622
+
> the last *pattern*, if the previous search was `"/!"` or `"?!"` ).
623
+
>
624
+
> ##### []{#tag_20_81_13_20}Examine New File
625
+
>
626
+
> *Synopsis*:
627
+
>
628
+
> :
629
+
> :e [filename]<newline>
630
+
>
631
+
> Examine a new file. If the *filename* argument is not specified, the
632
+
> current file (see the **:n** and **:p** commands below) shall be
633
+
> re-examined. The *filename* shall be subjected to the process of shell
634
+
> word expansions (see [*wordexp*](../functions/wordexp.html#)); if more
635
+
> than a single pathname results, the effects are unspecified. If
636
+
> *filename* is a \<number-sign\> ( `'#'` ), the previously examined
637
+
> file shall be re-examined. If *filename* is not accessible for any
638
+
> reason (including that it is a non-seekable file), an error message to
639
+
> this effect shall be displayed and the current file and screen shall
640
+
> not change.
641
+
>
642
+
> ##### []{#tag_20_81_13_21}Examine Next File
643
+
>
644
+
> *Synopsis*:
645
+
>
646
+
> :
647
+
> [count]:n
648
+
>
649
+
> Examine the next file. If a number *count* is specified, the *count*th
650
+
> next file shall be examined. If *filename* refers to a non-seekable
651
+
> file, the results are unspecified.
652
+
>
653
+
> ##### []{#tag_20_81_13_22}Examine Previous File
654
+
>
655
+
> *Synopsis*:
656
+
>
657
+
> :
658
+
> [count]:p
659
+
>
660
+
> Examine the previous file. If a number *count* is specified, the
661
+
> *count*th previous file shall be examined. If *filename* refers to a
662
+
> non-seekable file, the results are unspecified.
663
+
>
664
+
> ##### []{#tag_20_81_13_23}Go to Tag
665
+
>
666
+
> *Synopsis*:
667
+
>
668
+
> :
669
+
> :t tagstring<newline>
670
+
>
671
+
> If the file containing the tag named by the *tagstring* argument is
672
+
> not the current file, examine the file, as if the **:e** command was
673
+
> executed with that file as the argument. Otherwise, or in addition,
674
+
> display the screenful beginning with the tag, as described for the
675
+
> **-t** option (see the OPTIONS section). If the
676
+
> [*ctags*](../utilities/ctags.html) utility is not supported by the
677
+
> system, the use of **:t** produces undefined results.
678
+
>
679
+
> ##### []{#tag_20_81_13_24}Invoke Editor
680
+
>
681
+
> *Synopsis*:
682
+
>
683
+
> :
684
+
> v
685
+
>
686
+
> Invoke an editor to edit the current file being examined. If standard
687
+
> input is being examined, the results are unspecified. The name of the
688
+
> editor shall be taken from the environment variable *EDITOR,* or shall
689
+
> default to [*vi*](../utilities/vi.html). If the last pathname
690
+
> component in *EDITOR* is either [*vi*](../utilities/vi.html) or
691
+
> [*ex*](../utilities/ex.html), the editor shall be invoked with a
692
+
> **-c** *linenumber* command line argument, where *linenumber* is the
693
+
> line number of the file line containing the display line currently
694
+
> displayed as the first line of the screen. It is
695
+
> implementation-defined whether line-setting options are passed to
696
+
> editors other than [*vi*](../utilities/vi.html) and
697
+
> [*ex*](../utilities/ex.html).
698
+
>
699
+
> When the editor exits, *more* shall resume with the same file and
700
+
> screen as when the editor was invoked.
701
+
>
702
+
> ##### []{#tag_20_81_13_25}Display Position
703
+
>
704
+
> *Synopsis*:
705
+
>
706
+
> :
707
+
> =
708
+
> <control>-G
709
+
>
710
+
> Write a message for which the information references the first byte of
711
+
> the line after the last line of the file on the screen. This message
712
+
> shall include the name of the file currently being examined, its
713
+
> number relative to the total number of files there are to examine, the
714
+
> line number in the file, the byte number and the total bytes in the
715
+
> file, and what percentage of the file precedes the current position.
716
+
> If *more* is reading from standard input, or the file is shorter than
717
+
> a single screen, the line number, the byte number, the total bytes,
718
+
> and the percentage need not be written.
719
+
>
720
+
> ##### []{#tag_20_81_13_26}Quit
721
+
>
722
+
> *Synopsis*:
723
+
>
724
+
> :
725
+
> q
726
+
> :q
727
+
> ZZ
728
+
>
729
+
> Exit *more*.
730
+
731
+
#### []{#tag_20_81_14}EXIT STATUS {#exit-status .mansect}
732
+
733
+
> The following exit values shall be returned:
734
+
>
735
+
> 0
736
+
> : Successful completion.
737
+
>
738
+
> \>0
739
+
> : An error occurred.
740
+
741
+
#### []{#tag_20_81_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
742
+
743
+
> If an error is encountered accessing a file when using the **:n**
744
+
> command, *more* shall attempt to examine the next file in the argument
745
+
> list, but the final exit status shall be affected. If an error is
746
+
> encountered accessing a file via the **:p** command, *more* shall
747
+
> attempt to examine the previous file in the argument list, but the
748
+
> final exit status shall be affected. If an error is encountered
749
+
> accessing a file via the **:e** command, *more* shall remain in the
750
+
> current file and the final exit status shall not be affected.
751
+
752
+
------------------------------------------------------------------------
753
+
754
+
::: box
755
+
*The following sections are informative.*
756
+
:::
757
+
758
+
#### []{#tag_20_81_16}APPLICATION USAGE {#application-usage .mansect}
759
+
760
+
> When the standard output is not a terminal, only the **-s**
761
+
> filter-modification option is effective. This is based on historical
762
+
> practice. For example, a typical implementation of
763
+
> [*man*](../utilities/man.html) pipes its output through *more* **-s**
764
+
> to squeeze excess white space for terminal users. When
765
+
> [*man*](../utilities/man.html) is piped to
766
+
> [*lp*](../utilities/lp.html), however, it is undesirable for this
767
+
> squeezing to happen.
768
+
769
+
#### []{#tag_20_81_17}EXAMPLES {#examples .mansect}
770
+
771
+
> The **-p** allows arbitrary commands to be executed at the start of
772
+
> each file. Examples are:
773
+
>
774
+
> *more * **-p G ** *file1 file2*
775
+
> : Examine each file starting with its last screenful.
776
+
>
777
+
> *more * **-p ** 100 *file1 file2*
778
+
> : Examine each file starting with line 100 in the current position
779
+
> (usually the third line, so line 98 would be the first line
780
+
> written).
781
+
>
782
+
> *more * **-p ** /100 *file1 file2*
783
+
> : Examine each file starting with the first line containing the
784
+
> string `"100"` in the current position
785
+
786
+
#### []{#tag_20_81_18}RATIONALE {#rationale .mansect}
787
+
788
+
> The *more* utility, available in BSD and BSD-derived systems, was
789
+
> chosen as the prototype for the POSIX file display program since it is
790
+
> more widely available than either the public-domain program *less* or
791
+
> than *pg*, a pager provided in System V. The 4.4 BSD *more* is the
792
+
> model for the features selected; it is almost fully upwards-compatible
793
+
> from the 4.3 BSD version in wide use and has become more amenable for
794
+
> [*vi*](../utilities/vi.html) users. Several features originally
795
+
> derived from various file editors, found in both *less* and *pg*, have
796
+
> been added to this volume of POSIX.1-2017 as they have proved
797
+
> extremely popular with users.
798
+
>
799
+
> There are inconsistencies between *more* and
800
+
> [*vi*](../utilities/vi.html) that result from historical practice. For
801
+
> example, the single-character commands **h**, **f**, **b**, and
802
+
> \<space\> are screen movers in *more*, but cursor movers in
803
+
> [*vi*](../utilities/vi.html). These inconsistencies were maintained
804
+
> because the cursor movements are not applicable to *more* and the
805
+
> powerful functionality achieved without the use of the control key
806
+
> justifies the differences.
807
+
>
808
+
> The tags interface has been included in a program that is not a text
809
+
> editor because it promotes another degree of consistent operation with
810
+
> [*vi*](../utilities/vi.html). It is conceivable that the paging
811
+
> environment of *more* would be superior for browsing source code files
812
+
> in some circumstances.
813
+
>
814
+
> The operating mode referred to for block-mode terminals effectively
815
+
> adds a \<newline\> to each Synopsis line that currently has none. So,
816
+
> for example, **d** \<newline\> would page one screenful. The mode
817
+
> could be triggered by a command line option, environment variable, or
818
+
> some other method. The details are not imposed by this volume of
819
+
> POSIX.1-2017 because there are so few systems known to support such
820
+
> terminals. Nevertheless, it was considered that all systems should be
821
+
> able to support *more* given the exception cited for this small
822
+
> community of terminals because, in comparison to
823
+
> [*vi*](../utilities/vi.html), the cursor movements are few and the
824
+
> command set relatively amenable to the optional \<newline\>
825
+
> characters.
826
+
>
827
+
> Some versions of *more* provide a shell escaping mechanism similar to
828
+
> the [*ex*](../utilities/ex.html) **!** command. The standard
829
+
> developers did not consider that this was necessary in a paginator,
830
+
> particularly given the wide acceptance of multiple window terminals
831
+
> and job control features. (They chose to retain such features in the
832
+
> editors and [*mailx*](../utilities/mailx.html) because the shell
833
+
> interaction also gives an opportunity to modify the editing buffer,
834
+
> which is not applicable to *more*.)
835
+
>
836
+
> The **-p** (position) option replaces the **+** command because of the
837
+
> Utility Syntax Guidelines. The **+** *command* option is no longer
838
+
> specified by POSIX.1-2017 but may be present in some implementations.
839
+
> In early proposals, it took a *pattern* argument, but historical
840
+
> *less* provided the *more* general facility of a command. It would
841
+
> have been desirable to use the same **-c** as
842
+
> [*ex*](../utilities/ex.html) and [*vi*](../utilities/vi.html), but the
843
+
> letter was already in use.
844
+
>
845
+
> The text stating \"from a non-rewindable stream \... implementations
846
+
> may limit the amount of backwards motion supported\" would allow an
847
+
> implementation that permitted no backwards motion beyond text already
848
+
> on the screen. It was not possible to require a minimum amount of
849
+
> backwards motion that would be effective for all conceivable device
850
+
> types. The implementation should allow the user to back up as far as
851
+
> possible, within device and reasonable memory allocation constraints.
852
+
>
853
+
> Historically, non-printable characters were displayed using the ARPA
854
+
> standard mappings, which are as follows:
855
+
>
856
+
> 1. Printable characters are left alone.
857
+
>
858
+
> 2. Control characters less than \\177 are represented as followed by
859
+
> the character offset from the `'@'` character in the ASCII map;
860
+
> for example, \\007 is represented as `'G'`.
861
+
>
862
+
> 3. \\177 is represented as followed by `'?'`.
863
+
>
864
+
> The display of characters having their eighth bit set was less
865
+
> standard. Existing implementations use hex (0x00), octal (\\000), and
866
+
> a meta-bit display. (The latter displayed characters with their eighth
867
+
> bit set as the two characters `"M-"`, followed by the seven-bit
868
+
> display as described previously.) The latter probably has the best
869
+
> claim to historical practice because it was used with the **-v**
870
+
> option of 4 BSD and 4 BSD-derived versions of the
871
+
> [*cat*](../utilities/cat.html) utility since 1980.
872
+
>
873
+
> No specific display format is required by POSIX.1-2017.
874
+
> Implementations are encouraged to conform to historic practice in the
875
+
> absence of any strong reason to diverge.
876
+
877
+
#### []{#tag_20_81_19}FUTURE DIRECTIONS {#future-directions .mansect}
878
+
879
+
> None.
880
+
881
+
#### []{#tag_20_81_20}SEE ALSO {#see-also .mansect}
882
+
883
+
> [*Shell Command Language*](../utilities/V3_chap02.html#tag_18),
884
+
> [*ctags*](../utilities/ctags.html#), [*ed*](../utilities/ed.html#),
885
+
> [*ex*](../utilities/ex.html#), [*vi*](../utilities/vi.html#)
886
+
>
887
+
> XBD [*Environment Variables*](../basedefs/V1_chap08.html#tag_08),
888
+
> [*Regular Expression General
889
+
> Requirements*](../basedefs/V1_chap09.html#tag_09_02), [*Basic Regular
890
+
> Expressions*](../basedefs/V1_chap09.html#tag_09_03), [*Utility Syntax
891
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02)
892
+
893
+
#### []{#tag_20_81_21}CHANGE HISTORY {#change-history .mansect}
894
+
895
+
> First released in Issue 4.
896
+
897
+
#### []{#tag_20_81_22}Issue 5 {#issue-5 .mansect}
898
+
899
+
> The FUTURE DIRECTIONS section is added.
900
+
901
+
#### []{#tag_20_81_23}Issue 6 {#issue-6 .mansect}
902
+
903
+
> This utility is marked as part of the User Portability Utilities
904
+
> option.
905
+
>
906
+
> The obsolescent SYNOPSIS is removed.
907
+
>
908
+
> The utility has been extensively reworked for alignment with the
909
+
> IEEE P1003.2b draft standard:
910
+
>
911
+
> - Changes have been made as a result of IEEE PASC Interpretations
912
+
> 1003.2 #37 and #109.
913
+
>
914
+
> - The *more* utility should be able to handle underlined and
915
+
> emboldened displays of characters that are wider than a single
916
+
> column position.
917
+
918
+
#### []{#tag_20_81_24}Issue 7 {#issue-7 .mansect}
919
+
920
+
> Austin Group Interpretation 1003.1-2001 #027 is applied, clarifying
921
+
> that `'+'` may be recognized as an option delimiter in the OPTIONS
922
+
> section.
923
+
>
924
+
> SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.
925
+
>
926
+
> POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0123 \[265\] is
927
+
> applied.
928
+
>
929
+
> POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0146 \[584\] is
930
+
> applied.
931
+
+421
docs/posix2018/mv.md
+421
docs/posix2018/mv.md
···
1
+
#### []{#tag_20_82_01}NAME {#name .mansect}
2
+
3
+
> mv - move files
4
+
5
+
#### []{#tag_20_82_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `mv`` `**`[`**`-if`**`]`**` `*`source_file target_file`*\
8
+
> \
9
+
> `mv`` `**`[`**`-if`**`]`**` `*`source_file`*`...`` `*`target_dir`*\
10
+
11
+
#### []{#tag_20_82_03}DESCRIPTION {#description .mansect}
12
+
13
+
> In the first synopsis form, the *mv* utility shall move the file named
14
+
> by the *source_file* operand to the destination specified by the
15
+
> *target_file*. This first synopsis form is assumed when the final
16
+
> operand does not name an existing directory and is not a symbolic link
17
+
> referring to an existing directory. In this case, if *source_file*
18
+
> names a non-directory file and *target_file* ends with a trailing
19
+
> \<slash\> character, *mv* shall treat this as an error and no
20
+
> *source_file* operands will be processed.
21
+
>
22
+
> In the second synopsis form, *mv* shall move each file named by a
23
+
> *source_file* operand to a destination file in the existing directory
24
+
> named by the *target_dir* operand, or referenced if *target_dir* is a
25
+
> symbolic link referring to an existing directory. The destination path
26
+
> for each *source_file* shall be the concatenation of the target
27
+
> directory, a single \<slash\> character if the target did not end in a
28
+
> \<slash\>, and the last pathname component of the *source_file*. This
29
+
> second form is assumed when the final operand names an existing
30
+
> directory.
31
+
>
32
+
> If any operand specifies an existing file of a type not specified by
33
+
> the System Interfaces volume of POSIX.1-2017, the behavior is
34
+
> implementation-defined.
35
+
>
36
+
> For each *source_file* the following steps shall be taken:
37
+
>
38
+
> 1. If the destination path exists, the **-f** option is not
39
+
> specified, and either of the following conditions is true:
40
+
>
41
+
> a. The permissions of the destination path do not permit writing
42
+
> and the standard input is a terminal.
43
+
>
44
+
> b. The **-i** option is specified.
45
+
>
46
+
> the *mv* utility shall write a prompt to standard error and read a
47
+
> line from standard input. If the response is not affirmative, *mv*
48
+
> shall do nothing more with the current *source_file* and go on to
49
+
> any remaining *source_file*s.
50
+
>
51
+
> 2. If the *source_file* operand and destination path resolve to
52
+
> either the same existing directory entry or different directory
53
+
> entries for the same existing file, then the destination path
54
+
> shall not be removed, and one of the following shall occur:
55
+
>
56
+
> a. No change is made to *source_file*, no error occurs, and no
57
+
> diagnostic is issued.
58
+
>
59
+
> b. No change is made to *source_file*, a diagnostic is issued to
60
+
> standard error identifying the two names, and the exit status
61
+
> is affected.
62
+
>
63
+
> c. If the *source_file* operand and destination path name
64
+
> distinct directory entries, then the *source_file* operand is
65
+
> removed, no error occurs, and no diagnostic is issued.
66
+
>
67
+
> The *mv* utility shall do nothing more with the current
68
+
> *source_file*, and go on to any remaining *source_file*s.
69
+
>
70
+
> 3. The *mv* utility shall perform actions equivalent to the
71
+
> [*rename*()](../functions/rename.html) function defined in the
72
+
> System Interfaces volume of POSIX.1-2017, called with the
73
+
> following arguments:
74
+
>
75
+
> a. The *source_file* operand is used as the *old* argument.
76
+
>
77
+
> b. The destination path is used as the *new* argument.
78
+
>
79
+
> If this succeeds, *mv* shall do nothing more with the current
80
+
> *source_file* and go on to any remaining *source_file*s. If this
81
+
> fails for any reasons other than those described for the *errno*
82
+
> \[EXDEV\] in the System Interfaces volume of POSIX.1-2017, *mv*
83
+
> shall write a diagnostic message to standard error, do nothing
84
+
> more with the current *source_file*, and go on to any remaining
85
+
> *source_file*s.
86
+
>
87
+
> 4. If the destination path exists, and it is a file of type directory
88
+
> and *source_file* is not a file of type directory, or it is a file
89
+
> not of type directory and *source_file* is a file of type
90
+
> directory, *mv* shall write a diagnostic message to standard
91
+
> error, do nothing more with the current *source_file*, and go on
92
+
> to any remaining *source_file*s. If the destination path exists
93
+
> and was created by a previous step, it is unspecified whether this
94
+
> will treated as an error or the destination path will be
95
+
> overwritten.
96
+
>
97
+
> 5. If the destination path exists, *mv* shall attempt to remove it.
98
+
> If this fails for any reason, *mv* shall write a diagnostic
99
+
> message to standard error, do nothing more with the current
100
+
> *source_file*, and go on to any remaining *source_file*s.
101
+
>
102
+
> 6. The file hierarchy rooted in *source_file* shall be duplicated as
103
+
> a file hierarchy rooted in the destination path. If *source_file*
104
+
> or any of the files below it in the hierarchy are symbolic links,
105
+
> the links themselves shall be duplicated, including their
106
+
> contents, rather than any files to which they refer. The following
107
+
> characteristics of each file in the file hierarchy shall be
108
+
> duplicated:
109
+
>
110
+
> - The time of last data modification and time of last access
111
+
>
112
+
> - The user ID and group ID
113
+
>
114
+
> - The file mode
115
+
>
116
+
> If the user ID, group ID, or file mode of a regular file cannot be
117
+
> duplicated, the file mode bits S_ISUID and S_ISGID shall not be
118
+
> duplicated.
119
+
>
120
+
> When files are duplicated to another file system, the
121
+
> implementation may require that the process invoking *mv* has read
122
+
> access to each file being duplicated.
123
+
>
124
+
> If files being duplicated to another file system have hard links
125
+
> to other files, it is unspecified whether the files copied to the
126
+
> new file system have the hard links preserved or separate copies
127
+
> are created for the linked files.
128
+
>
129
+
> If the duplication of the file hierarchy fails for any reason,
130
+
> *mv* shall write a diagnostic message to standard error, do
131
+
> nothing more with the current *source_file*, and go on to any
132
+
> remaining *source_file*s.
133
+
>
134
+
> If the duplication of the file characteristics fails for any
135
+
> reason, *mv* shall write a diagnostic message to standard error,
136
+
> but this failure shall not cause *mv* to modify its exit status.
137
+
>
138
+
> 7. The file hierarchy rooted in *source_file* shall be removed. If
139
+
> this fails for any reason, *mv* shall write a diagnostic message
140
+
> to the standard error, do nothing more with the current
141
+
> *source_file*, and go on to any remaining *source_file*s.
142
+
143
+
#### []{#tag_20_82_04}OPTIONS {#options .mansect}
144
+
145
+
> The *mv* utility shall conform to XBD [*Utility Syntax
146
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02) .
147
+
>
148
+
> The following options shall be supported:
149
+
>
150
+
> **-f**
151
+
> : Do not prompt for confirmation if the destination path exists. Any
152
+
> previous occurrence of the **-i** option is ignored.
153
+
>
154
+
> **-i**
155
+
> : Prompt for confirmation if the destination path exists. Any
156
+
> previous occurrence of the **-f** option is ignored.
157
+
>
158
+
> Specifying more than one of the **-f** or **-i** options shall not be
159
+
> considered an error. The last option specified shall determine the
160
+
> behavior of *mv*.
161
+
162
+
#### []{#tag_20_82_05}OPERANDS {#operands .mansect}
163
+
164
+
> The following operands shall be supported:
165
+
>
166
+
> *source_file*
167
+
> : A pathname of a file or directory to be moved.
168
+
>
169
+
> *target_file*
170
+
> : A new pathname for the file or directory being moved.
171
+
>
172
+
> *target_dir*
173
+
> : A pathname of an existing directory into which to move the input
174
+
> files.
175
+
176
+
#### []{#tag_20_82_06}STDIN {#stdin .mansect}
177
+
178
+
> The standard input shall be used to read an input line in response to
179
+
> each prompt specified in the STDERR section. Otherwise, the standard
180
+
> input shall not be used.
181
+
182
+
#### []{#tag_20_82_07}INPUT FILES {#input-files .mansect}
183
+
184
+
> The input files specified by each *source_file* operand can be of any
185
+
> file type.
186
+
187
+
#### []{#tag_20_82_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
188
+
189
+
> The following environment variables shall affect the execution of
190
+
> *mv*:
191
+
>
192
+
> *LANG*
193
+
> : Provide a default value for the internationalization variables
194
+
> that are unset or null. (See XBD [*Internationalization
195
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
196
+
> precedence of internationalization variables used to determine the
197
+
> values of locale categories.)
198
+
>
199
+
> *LC_ALL*
200
+
> : If set to a non-empty string value, override the values of all the
201
+
> other internationalization variables.
202
+
>
203
+
> *LC_COLLATE*
204
+
> : Determine the locale for the behavior of ranges, equivalence
205
+
> classes, and multi-character collating elements used in the
206
+
> extended regular expression defined for the **yesexpr** locale
207
+
> keyword in the *LC_MESSAGES* category.
208
+
>
209
+
> *LC_CTYPE*
210
+
> : Determine the locale for the interpretation of sequences of bytes
211
+
> of text data as characters (for example, single-byte as opposed to
212
+
> multi-byte characters in arguments and input files), the behavior
213
+
> of character classes used in the extended regular expression
214
+
> defined for the **yesexpr** locale keyword in the *LC_MESSAGES*
215
+
> category.
216
+
>
217
+
> *LC_MESSAGES*
218
+
> : Determine the locale used to process affirmative responses, and
219
+
> the locale used to affect the format and contents of diagnostic
220
+
> messages and prompts written to standard error.
221
+
>
222
+
> *NLSPATH*
223
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
224
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
225
+
> location of message catalogs for the processing of *LC_MESSAGES.*
226
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
227
+
228
+
#### []{#tag_20_82_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
229
+
230
+
> Default.
231
+
232
+
#### []{#tag_20_82_10}STDOUT {#stdout .mansect}
233
+
234
+
> Not used.
235
+
236
+
#### []{#tag_20_82_11}STDERR {#stderr .mansect}
237
+
238
+
> Prompts shall be written to the standard error under the conditions
239
+
> specified in the DESCRIPTION section. The prompts shall contain the
240
+
> destination pathname, but their format is otherwise unspecified.
241
+
> Otherwise, the standard error shall be used only for diagnostic
242
+
> messages.
243
+
244
+
#### []{#tag_20_82_12}OUTPUT FILES {#output-files .mansect}
245
+
246
+
> The output files may be of any file type.
247
+
248
+
#### []{#tag_20_82_13}EXTENDED DESCRIPTION {#extended-description .mansect}
249
+
250
+
> None.
251
+
252
+
#### []{#tag_20_82_14}EXIT STATUS {#exit-status .mansect}
253
+
254
+
> The following exit values shall be returned:
255
+
>
256
+
> 0
257
+
> : All input files were moved successfully.
258
+
>
259
+
> \>0
260
+
> : An error occurred.
261
+
262
+
#### []{#tag_20_82_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
263
+
264
+
> If the copying or removal of *source_file* is prematurely terminated
265
+
> by a signal or error, *mv* may leave a partial copy of *source_file*
266
+
> at the source or destination. The *mv* utility shall not modify both
267
+
> *source_file* and the destination path simultaneously; termination at
268
+
> any point shall leave either *source_file* or the destination path
269
+
> complete.
270
+
271
+
------------------------------------------------------------------------
272
+
273
+
::: box
274
+
*The following sections are informative.*
275
+
:::
276
+
277
+
#### []{#tag_20_82_16}APPLICATION USAGE {#application-usage .mansect}
278
+
279
+
> Some implementations mark for update the last file status change
280
+
> timestamp of renamed files and some do not. Applications which make
281
+
> use of the last file status change timestamp may behave differently
282
+
> with respect to renamed files unless they are designed to allow for
283
+
> either behavior.
284
+
>
285
+
> The specification ensures that *mv* **a** **a** will not alter the
286
+
> contents of file **a**, and allows the implementation to issue an
287
+
> error that a file cannot be moved onto itself. Likewise, when **a**
288
+
> and **b** are hard links to the same file, *mv* **a** **b** will not
289
+
> alter **b**, but if a diagnostic is not issued, then it is unspecified
290
+
> whether **a** is left untouched (as it would be by the
291
+
> [*rename*()](../functions/rename.html) function) or unlinked (reducing
292
+
> the link count of **b**).
293
+
294
+
#### []{#tag_20_82_17}EXAMPLES {#examples .mansect}
295
+
296
+
> If the current directory contains only files **a** (of any type
297
+
> defined by the System Interfaces volume of POSIX.1-2017), **b** (also
298
+
> of any type), and a directory **c**:
299
+
>
300
+
>
301
+
> mv a b c
302
+
> mv c d
303
+
>
304
+
> results with the original files **a** and **b** residing in the
305
+
> directory **d** in the current directory.
306
+
307
+
#### []{#tag_20_82_18}RATIONALE {#rationale .mansect}
308
+
309
+
> Early proposals diverged from the SVID and BSD historical practice in
310
+
> that they required that when the destination path exists, the **-f**
311
+
> option is not specified, and input is not a terminal, *mv* fails. This
312
+
> was done for compatibility with [*cp*](../utilities/cp.html). The
313
+
> current text returns to historical practice. It should be noted that
314
+
> this is consistent with the [*rename*()](../functions/rename.html)
315
+
> function defined in the System Interfaces volume of POSIX.1-2017,
316
+
> which does not require write permission on the target.
317
+
>
318
+
> For absolute clarity, paragraph (1), describing the behavior of *mv*
319
+
> when prompting for confirmation, should be interpreted in the
320
+
> following manner:
321
+
>
322
+
>
323
+
> if (exists AND (NOT f_option) AND
324
+
> ((not_writable AND input_is_terminal) OR i_option))
325
+
>
326
+
> The **-i** option exists on BSD systems, giving applications and users
327
+
> a way to avoid accidentally unlinking files when moving others. When
328
+
> the standard input is not a terminal, the 4.3 BSD *mv* deletes all
329
+
> existing destination paths without prompting, even when **-i** is
330
+
> specified; this is inconsistent with the behavior of the 4.3 BSD
331
+
> [*cp*](../utilities/cp.html) utility, which always generates an error
332
+
> when the file is unwritable and the standard input is not a terminal.
333
+
> The standard developers decided that use of **-i** is a request for
334
+
> interaction, so when the destination path exists, the utility takes
335
+
> instructions from whatever responds to standard input.
336
+
>
337
+
> The [*rename*()](../functions/rename.html) function is able to move
338
+
> directories within the same file system. Some historical versions of
339
+
> *mv* have been able to move directories, but not to a different file
340
+
> system. The standard developers considered that this was an annoying
341
+
> inconsistency, so this volume of POSIX.1-2017 requires directories to
342
+
> be able to be moved even across file systems. There is no **-R**
343
+
> option to confirm that moving a directory is actually intended, since
344
+
> such an option was not required for moving directories in historical
345
+
> practice. Requiring the application to specify it sometimes, depending
346
+
> on the destination, seemed just as inconsistent. The semantics of the
347
+
> [*rename*()](../functions/rename.html) function were preserved as much
348
+
> as possible. For example, *mv* is not permitted to \"rename\" files to
349
+
> or from directories, even though they might be empty and removable.
350
+
>
351
+
> Historic implementations of *mv* did not exit with a non-zero exit
352
+
> status if they were unable to duplicate any file characteristics when
353
+
> moving a file across file systems, nor did they write a diagnostic
354
+
> message for the user. The former behavior has been preserved to
355
+
> prevent scripts from breaking; a diagnostic message is now required,
356
+
> however, so that users are alerted that the file characteristics have
357
+
> changed.
358
+
>
359
+
> The exact format of the interactive prompts is unspecified. Only the
360
+
> general nature of the contents of prompts are specified because
361
+
> implementations may desire more descriptive prompts than those used on
362
+
> historical implementations. Therefore, an application not using the
363
+
> **-f** option or using the **-i** option relies on the system to
364
+
> provide the most suitable dialog directly with the user, based on the
365
+
> behavior specified.
366
+
>
367
+
> When *mv* is dealing with a single file system and *source_file* is a
368
+
> symbolic link, the link itself is moved as a consequence of the
369
+
> dependence on the [*rename*()](../functions/rename.html)
370
+
> functionality, per the DESCRIPTION. Across file systems, this has to
371
+
> be made explicit.
372
+
373
+
#### []{#tag_20_82_19}FUTURE DIRECTIONS {#future-directions .mansect}
374
+
375
+
> None.
376
+
377
+
#### []{#tag_20_82_20}SEE ALSO {#see-also .mansect}
378
+
379
+
> [*cp*](../utilities/cp.html#), [*ln*](../utilities/ln.html#)
380
+
>
381
+
> XBD [*Environment Variables*](../basedefs/V1_chap08.html#tag_08),
382
+
> [*Utility Syntax Guidelines*](../basedefs/V1_chap12.html#tag_12_02)
383
+
>
384
+
> XSH [*rename*](../functions/rename.html#)
385
+
386
+
#### []{#tag_20_82_21}CHANGE HISTORY {#change-history .mansect}
387
+
388
+
> First released in Issue 2.
389
+
390
+
#### []{#tag_20_82_22}Issue 6 {#issue-6 .mansect}
391
+
392
+
> The *mv* utility is changed to describe processing of symbolic links
393
+
> as specified in the IEEE P1003.2b draft standard.
394
+
>
395
+
> The APPLICATION USAGE section is added.
396
+
397
+
#### []{#tag_20_82_23}Issue 7 {#issue-7 .mansect}
398
+
399
+
> Austin Group Interpretation 1003.1-2001 #016 is applied.
400
+
>
401
+
> Austin Group Interpretation 1003.1-2001 #126 is applied, changing the
402
+
> description of the *LC_MESSAGES* environment variable.
403
+
>
404
+
> Austin Group Interpretations 1003.1-2001 #164, #168, and #169 are
405
+
> applied.
406
+
>
407
+
> SD5-XCU-ERN-13 is applied, making an editorial correction to the
408
+
> SYNOPSIS.
409
+
>
410
+
> SD5-XCU-ERN-51 is applied to the DESCRIPTION, defining the behavior
411
+
> for when files are being duplicated to another file system while
412
+
> having hard links.
413
+
>
414
+
> Changes are made related to support for finegrained timestamps.
415
+
>
416
+
> POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0124 \[48\] is
417
+
> applied.
418
+
>
419
+
> POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0147 \[534\] is
420
+
> applied.
421
+
+285
docs/posix2018/nl.md
+285
docs/posix2018/nl.md
···
1
+
#### []{#tag_20_85_01}NAME {#name .mansect}
2
+
3
+
> nl - line numbering filter
4
+
5
+
#### []{#tag_20_85_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> ::: box
8
+
> ^`[`[`XSI`](javascript:open_code('XSI'))`]`^` `![`[Option Start]`](../images/opt-start.gif){border="0"}` nl`` `**`[`**`-p`**`] [`**`-b`` `*`type`***`] [`**`-d`` `*`delim`***`] [`**`-f`` `*`type`***`] [`**`-h`` `*`type`***`] [`**`-i`` `*`incr`***`] [`**`-l`` `*`num`***`]`\**
9
+
> ` `` `` `**`[`**`-n`` `*`format`***`] [`**`-s`` `*`sep`***`] [`**`-v`` `*`startnum`***`] [`**`-w`` `*`width`***`] [`***`file`***`]`**![`[Option End]`](../images/opt-end.gif){border="0"}
10
+
> :::
11
+
12
+
#### []{#tag_20_85_03}DESCRIPTION {#description .mansect}
13
+
14
+
> The *nl* utility shall read lines from the named *file* or the
15
+
> standard input if no *file* is named and shall reproduce the lines to
16
+
> standard output. Lines shall be numbered on the left. Additional
17
+
> functionality may be provided in accordance with the command options
18
+
> in effect.
19
+
>
20
+
> The *nl* utility views the text it reads in terms of logical pages.
21
+
> Line numbering shall be reset at the start of each logical page. A
22
+
> logical page consists of a header, a body, and a footer section. Empty
23
+
> sections are valid. Different line numbering options are independently
24
+
> available for header, body, and footer (for example, no numbering of
25
+
> header and footer lines while numbering blank lines only in the body).
26
+
>
27
+
> The starts of logical page sections shall be signaled by input lines
28
+
> containing nothing but the following delimiter characters:
29
+
>
30
+
> **Line** **Start of**
31
+
> ----------- --------------
32
+
> \\:\\:\\: Header
33
+
> \\:\\: Body
34
+
> \\: Footer
35
+
>
36
+
> Unless otherwise specified, *nl* shall assume the text being read is
37
+
> in a single logical page body.
38
+
39
+
#### []{#tag_20_85_04}OPTIONS {#options .mansect}
40
+
41
+
> The *nl* utility shall conform to XBD [*Utility Syntax
42
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02). Only one file can
43
+
> be named.
44
+
>
45
+
> The following options shall be supported:
46
+
>
47
+
> **-b ** *type*
48
+
>
49
+
> : Specify which logical page body lines shall be numbered.
50
+
> Recognized *types* and their meaning are:
51
+
>
52
+
> **a**
53
+
> : Number all lines.
54
+
>
55
+
> **t**
56
+
> : Number only non-empty lines.
57
+
>
58
+
> **n**
59
+
> : No line numbering.
60
+
>
61
+
> **p***string*
62
+
> : Number only lines that contain the basic regular expression
63
+
> specified in *string*.
64
+
>
65
+
> The default *type* for logical page body shall be **t** (text
66
+
> lines numbered).
67
+
>
68
+
> **-d ** *delim*
69
+
> : Specify the delimiter characters that indicate the start of a
70
+
> logical page section. These can be changed from the default
71
+
> characters `"\:"` to two user-specified characters. If only one
72
+
> character is entered, the second character shall remain the
73
+
> default character `':'`.
74
+
>
75
+
> **-f ** *type*
76
+
> : Specify the same as **b** *type* except for footer. The default
77
+
> for logical page footer shall be **n** (no lines numbered).
78
+
>
79
+
> **-h ** *type*
80
+
> : Specify the same as **b** *type* except for header. The default
81
+
> *type* for logical page header shall be **n** (no lines numbered).
82
+
>
83
+
> **-i ** *incr*
84
+
> : Specify the increment value used to number logical page lines. The
85
+
> default shall be 1.
86
+
>
87
+
> **-l ** *num*
88
+
> : Specify the number of blank lines to be considered as one. For
89
+
> example, **-l 2** results in only the second adjacent blank line
90
+
> being numbered (if the appropriate **-h a**, **-b a**, or **-f a**
91
+
> option is set). The default shall be 1.
92
+
>
93
+
> **-n ** *format*
94
+
> : Specify the line numbering format. Recognized values are: **ln**,
95
+
> left justified, leading zeros suppressed; **rn**, right justified,
96
+
> leading zeros suppressed; **rz**, right justified, leading zeros
97
+
> kept. The default *format* shall be **rn** (right justified).
98
+
>
99
+
> **-p**
100
+
> : Specify that numbering should not be restarted at logical page
101
+
> delimiters.
102
+
>
103
+
> **-s ** *sep*
104
+
> : Specify the characters used in separating the line number and the
105
+
> corresponding text line. The default *sep* shall be a \<tab\>.
106
+
>
107
+
> **-v ** *startnum*
108
+
> : Specify the initial value used to number logical page lines. The
109
+
> default shall be 1.
110
+
>
111
+
> **-w ** *width*
112
+
> : Specify the number of characters to be used for the line number.
113
+
> The default *width* shall be 6.
114
+
115
+
#### []{#tag_20_85_05}OPERANDS {#operands .mansect}
116
+
117
+
> The following operand shall be supported:
118
+
>
119
+
> *file*
120
+
> : A pathname of a text file to be line-numbered.
121
+
122
+
#### []{#tag_20_85_06}STDIN {#stdin .mansect}
123
+
124
+
> The standard input shall be used if no *file* operand is specified,
125
+
> and shall be used if the *file* operand is `'-'` and the
126
+
> implementation treats the `'-'` as meaning standard input. Otherwise,
127
+
> the standard input shall not be used. See the INPUT FILES section.
128
+
129
+
#### []{#tag_20_85_07}INPUT FILES {#input-files .mansect}
130
+
131
+
> The input file shall be a text file.
132
+
133
+
#### []{#tag_20_85_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
134
+
135
+
> The following environment variables shall affect the execution of
136
+
> *nl*:
137
+
>
138
+
> *LANG*
139
+
> : Provide a default value for the internationalization variables
140
+
> that are unset or null. (See XBD [*Internationalization
141
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
142
+
> precedence of internationalization variables used to determine the
143
+
> values of locale categories.)
144
+
>
145
+
> *LC_ALL*
146
+
> : If set to a non-empty string value, override the values of all the
147
+
> other internationalization variables.
148
+
>
149
+
> *LC_COLLATE*
150
+
> : Determine the locale for the behavior of ranges, equivalence
151
+
> classes, and multi-character collating elements within regular
152
+
> expressions.
153
+
>
154
+
> *LC_CTYPE*
155
+
> : Determine the locale for the interpretation of sequences of bytes
156
+
> of text data as characters (for example, single-byte as opposed to
157
+
> multi-byte characters in arguments and input files), the behavior
158
+
> of character classes within regular expressions, and for deciding
159
+
> which characters are in character class **graph** (for the
160
+
> **-b t**, **-f t**, and **-h t** options).
161
+
>
162
+
> *LC_MESSAGES*
163
+
> : Determine the locale that should be used to affect the format and
164
+
> contents of diagnostic messages written to standard error.
165
+
>
166
+
> *NLSPATH*
167
+
> : Determine the location of message catalogs for the processing of
168
+
> *LC_MESSAGES.*
169
+
170
+
#### []{#tag_20_85_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
171
+
172
+
> Default.
173
+
174
+
#### []{#tag_20_85_10}STDOUT {#stdout .mansect}
175
+
176
+
> The standard output shall be a text file in the following format:
177
+
>
178
+
>
179
+
> "%s%s%s", <line number>, <separator>, <input line>
180
+
>
181
+
> where \<*line number*\> is one of the following numeric formats:
182
+
>
183
+
> `%6d`
184
+
> : When the **rn** format is used (the default; see **-n**).
185
+
>
186
+
> `%06d`
187
+
> : When the **rz** format is used.
188
+
>
189
+
> `%-6d`
190
+
> : When the **ln** format is used.
191
+
>
192
+
> \<empty\>
193
+
> : When line numbers are suppressed for a portion of the page; the
194
+
> \<*separator*\> is also suppressed.
195
+
>
196
+
> In the preceding list, the number 6 is the default width; the **-w**
197
+
> option can change this value.
198
+
199
+
#### []{#tag_20_85_11}STDERR {#stderr .mansect}
200
+
201
+
> The standard error shall be used only for diagnostic messages.
202
+
203
+
#### []{#tag_20_85_12}OUTPUT FILES {#output-files .mansect}
204
+
205
+
> None.
206
+
207
+
#### []{#tag_20_85_13}EXTENDED DESCRIPTION {#extended-description .mansect}
208
+
209
+
> None.
210
+
211
+
#### []{#tag_20_85_14}EXIT STATUS {#exit-status .mansect}
212
+
213
+
> The following exit values shall be returned:
214
+
>
215
+
> 0
216
+
> : Successful completion.
217
+
>
218
+
> \>0
219
+
> : An error occurred.
220
+
221
+
#### []{#tag_20_85_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
222
+
223
+
> Default.
224
+
225
+
------------------------------------------------------------------------
226
+
227
+
::: box
228
+
*The following sections are informative.*
229
+
:::
230
+
231
+
#### []{#tag_20_85_16}APPLICATION USAGE {#application-usage .mansect}
232
+
233
+
> In using the **-d** *delim* option, care should be taken to escape
234
+
> characters that have special meaning to the command interpreter.
235
+
236
+
#### []{#tag_20_85_17}EXAMPLES {#examples .mansect}
237
+
238
+
> The command:
239
+
>
240
+
>
241
+
> nl -v 10 -i 10 -d \!+ file1
242
+
>
243
+
> numbers *file1* starting at line number 10 with an increment of 10.
244
+
> The logical page delimiter is `"!+"`. Note that the `'!'` has to be
245
+
> escaped when using *csh* as a command interpreter because of its
246
+
> history substitution syntax. For *ksh* and
247
+
> [*sh*](../utilities/sh.html) the escape is not necessary, but does not
248
+
> do any harm.
249
+
250
+
#### []{#tag_20_85_18}RATIONALE {#rationale .mansect}
251
+
252
+
> None.
253
+
254
+
#### []{#tag_20_85_19}FUTURE DIRECTIONS {#future-directions .mansect}
255
+
256
+
> None.
257
+
258
+
#### []{#tag_20_85_20}SEE ALSO {#see-also .mansect}
259
+
260
+
> [*pr*](../utilities/pr.html#)
261
+
>
262
+
> XBD [*Environment Variables*](../basedefs/V1_chap08.html#tag_08),
263
+
> [*Utility Syntax Guidelines*](../basedefs/V1_chap12.html#tag_12_02)
264
+
265
+
#### []{#tag_20_85_21}CHANGE HISTORY {#change-history .mansect}
266
+
267
+
> First released in Issue 2.
268
+
269
+
#### []{#tag_20_85_22}Issue 5 {#issue-5 .mansect}
270
+
271
+
> The option \[ **-f** *type*\] is added to the SYNOPSIS. The option
272
+
> descriptions are presented in alphabetic order. The description of
273
+
> **-bt** is changed to \"Number only non-empty lines\".
274
+
275
+
#### []{#tag_20_85_23}Issue 6 {#issue-6 .mansect}
276
+
277
+
> The obsolescent behavior allowing the options to be intermingled with
278
+
> the optional *file* operand is removed.
279
+
280
+
#### []{#tag_20_85_24}Issue 7 {#issue-7 .mansect}
281
+
282
+
> Austin Group Interpretation 1003.1-2001 #092 is applied.
283
+
>
284
+
> SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.
285
+
+641
docs/posix2018/od.md
+641
docs/posix2018/od.md
···
1
+
#### []{#tag_20_88_01}NAME {#name .mansect}
2
+
3
+
> od - dump files in various formats
4
+
5
+
#### []{#tag_20_88_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `od`` `**`[`**`-v`**`] [`**`-A`` `*`address_base`***`] [`**`-j`` `*`skip`***`] [`**`-N`` `*`count`***`] [`**`-t`` `*`type_string`***`]`**`...`\
8
+
> ` `` `**`[`***`file`*`...`**`]`**\
9
+
> \
10
+
>
11
+
> ::: box
12
+
> ^`[`[`XSI`](javascript:open_code('XSI'))`]`^` `![`[Option Start]`](../images/opt-start.gif){border="0"}` od`` `**`[`**`-bcdosx`**`] [`***`file`***`] [[`**`+`**`]`***`offset`***`[`**`.`**`][`**`b`**`]]`**![`[Option End]`](../images/opt-end.gif){border="0"}
13
+
> :::
14
+
>
15
+
> \
16
+
17
+
#### []{#tag_20_88_03}DESCRIPTION {#description .mansect}
18
+
19
+
> The *od* utility shall write the contents of its input files to
20
+
> standard output in a user-specified format.
21
+
22
+
#### []{#tag_20_88_04}OPTIONS {#options .mansect}
23
+
24
+
> The *od* utility shall conform to XBD [*Utility Syntax
25
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02), except that the
26
+
> order of presentation of the **-t** options
27
+
> ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
28
+
> Start\]](../images/opt-start.gif){border="0"} and the **-bcdosx**
29
+
> options ![\[Option End\]](../images/opt-end.gif){border="0"} is
30
+
> significant.
31
+
>
32
+
> The following options shall be supported:
33
+
>
34
+
> **-A ** *address_base*
35
+
> : Specify the input offset base. See the EXTENDED DESCRIPTION
36
+
> section. The application shall ensure that the *address_base*
37
+
> option-argument is a character. The characters `'d'`, `'o'`, and
38
+
> `'x'` specify that the offset base shall be written in decimal,
39
+
> octal, or hexadecimal, respectively. The character `'n'` specifies
40
+
> that the offset shall not be written.
41
+
>
42
+
> **-b**
43
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
44
+
> Start\]](../images/opt-start.gif){border="0"} Interpret bytes in
45
+
> octal. This shall be equivalent to **-t o1**. ![\[Option
46
+
> End\]](../images/opt-end.gif){border="0"}
47
+
>
48
+
> **-c**
49
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
50
+
> Start\]](../images/opt-start.gif){border="0"} Interpret bytes as
51
+
> characters specified by the current setting of the *LC_CTYPE*
52
+
> category. Certain non-graphic characters appear as C escapes:
53
+
> `"NUL=\0"`, `"BS=\b"`, `"FF=\f"`, `"NL=\n"`, `"CR=\r"`, `"HT=\t"`;
54
+
> others appear as 3-digit octal numbers. ![\[Option
55
+
> End\]](../images/opt-end.gif){border="0"}
56
+
>
57
+
> **-d**
58
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
59
+
> Start\]](../images/opt-start.gif){border="0"} Interpret *word*s
60
+
> (two-byte units) in unsigned decimal. This shall be equivalent to
61
+
> **-t u2**. ![\[Option End\]](../images/opt-end.gif){border="0"}
62
+
>
63
+
> **-j ** *skip*
64
+
>
65
+
> : Jump over *skip* bytes from the beginning of the input. The *od*
66
+
> utility shall read or seek past the first *skip* bytes in the
67
+
> concatenated input files. If the combined input is not at least
68
+
> *skip* bytes long, the *od* utility shall write a diagnostic
69
+
> message to standard error and exit with a non-zero exit status.
70
+
>
71
+
> By default, the *skip* option-argument shall be interpreted as a
72
+
> decimal number. With a leading 0x or 0X, the offset shall be
73
+
> interpreted as a hexadecimal number; otherwise, with a leading
74
+
> `'0'`, the offset shall be interpreted as an octal number.
75
+
> Appending the character `'b'`, `'k'`, or `'m'` to offset shall
76
+
> cause it to be interpreted as a multiple of 512, 1024, or 1048576
77
+
> bytes, respectively. If the *skip* number is hexadecimal, any
78
+
> appended `'b'` shall be considered to be the final hexadecimal
79
+
> digit.
80
+
>
81
+
> **-N ** *count*
82
+
> : Format no more than *count* bytes of input. By default, *count*
83
+
> shall be interpreted as a decimal number. With a leading 0x or 0X,
84
+
> *count* shall be interpreted as a hexadecimal number; otherwise,
85
+
> with a leading `'0'`, it shall be interpreted as an octal number.
86
+
> If *count* bytes of input (after successfully skipping, if **-j**
87
+
> *skip* is specified) are not available, it shall not be considered
88
+
> an error; the *od* utility shall format the input that is
89
+
> available.
90
+
>
91
+
> **-o**
92
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
93
+
> Start\]](../images/opt-start.gif){border="0"} Interpret *word*s
94
+
> (two-byte units) in octal. This shall be equivalent to **-t o2**.
95
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
96
+
>
97
+
> **-s**
98
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
99
+
> Start\]](../images/opt-start.gif){border="0"} Interpret *word*s
100
+
> (two-byte units) in signed decimal. This shall be equivalent to
101
+
> **-t d2**. ![\[Option End\]](../images/opt-end.gif){border="0"}
102
+
>
103
+
> **-t ** *type_string*
104
+
> : Specify one or more output types. See the EXTENDED DESCRIPTION
105
+
> section. The application shall ensure that the *type_string*
106
+
> option-argument is a string specifying the types to be used when
107
+
> writing the input data. The string shall consist of the type
108
+
> specification characters `a`, `c`, `d`, `f`, `o`, `u`, and `x`,
109
+
> specifying named character, character, signed decimal, floating
110
+
> point, octal, unsigned decimal, and hexadecimal, respectively. The
111
+
> type specification characters `d`, `f`, `o`, `u`, and `x` can be
112
+
> followed by an optional unsigned decimal integer that specifies
113
+
> the number of bytes to be transformed by each instance of the
114
+
> output type. The type specification character `f` can be followed
115
+
> by an optional `F`, `D`, or `L` indicating that the conversion
116
+
> should be applied to an item of type **float**, **double**, or
117
+
> **long double**, respectively. The type specification characters
118
+
> `d`, `o`, `u`, and `x` can be followed by an optional `C`, `S`,
119
+
> `I`, or `L` indicating that the conversion should be applied to an
120
+
> item of type **char**, **short**, **int**, or **long**,
121
+
> respectively. Multiple types can be concatenated within the same
122
+
> *type_string* and multiple **-t** options can be specified. Output
123
+
> lines shall be written for each type specified in the order in
124
+
> which the type specification characters are specified.
125
+
>
126
+
> **-v**
127
+
> : Write all input data. Without the **-v** option, any number of
128
+
> groups of output lines, which would be identical to the
129
+
> immediately preceding group of output lines (except for the byte
130
+
> offsets), shall be replaced with a line containing only an
131
+
> \<asterisk\> ( `'*'` ).
132
+
>
133
+
> **-x**
134
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
135
+
> Start\]](../images/opt-start.gif){border="0"} Interpret *word*s
136
+
> (two-byte units) in hexadecimal. This shall be equivalent to
137
+
> **-t x2**. ![\[Option End\]](../images/opt-end.gif){border="0"}
138
+
>
139
+
> ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
140
+
> Start\]](../images/opt-start.gif){border="0"} Multiple types can be
141
+
> specified by using multiple **-bcdostx** options. Output lines are
142
+
> written for each type specified in the order in which the types are
143
+
> specified. ![\[Option End\]](../images/opt-end.gif){border="0"}
144
+
145
+
#### []{#tag_20_88_05}OPERANDS {#operands .mansect}
146
+
147
+
> The following operands shall be supported:
148
+
>
149
+
> *file*
150
+
>
151
+
> : A pathname of a file to be read. If no *file* operands are
152
+
> specified, the standard input shall be used.
153
+
>
154
+
> If there are no more than two operands, none of the **-A**,
155
+
> **-j**, **-N**, **-t**, or **-v** options is specified, and either
156
+
> of the following is true: the first character of the last operand
157
+
> is a \<plus-sign\> ( `'+'` ), or there are two operands and the
158
+
> first character of the last operand is numeric;
159
+
> ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
160
+
> Start\]](../images/opt-start.gif){border="0"} the last operand
161
+
> shall be interpreted as an offset operand on XSI-conformant
162
+
> systems. ![\[Option End\]](../images/opt-end.gif){border="0"}
163
+
> Under these conditions, the results are unspecified on systems
164
+
> that are not XSI-conformant systems.
165
+
>
166
+
> **\[+\]***offset***\[.\]\[b\]**
167
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
168
+
> Start\]](../images/opt-start.gif){border="0"} The *offset* operand
169
+
> specifies the offset in the file where dumping is to commence.
170
+
> This operand is normally interpreted as octal bytes. If `'.'` is
171
+
> appended, the offset shall be interpreted in decimal. If `'b'` is
172
+
> appended, the offset shall be interpreted in units of 512 bytes.
173
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
174
+
175
+
#### []{#tag_20_88_06}STDIN {#stdin .mansect}
176
+
177
+
> The standard input shall be used if no *file* operands are specified,
178
+
> and shall be used if a *file* operand is `'-'` and the implementation
179
+
> treats the `'-'` as meaning standard input. Otherwise, the standard
180
+
> input shall not be used. See the INPUT FILES section.
181
+
182
+
#### []{#tag_20_88_07}INPUT FILES {#input-files .mansect}
183
+
184
+
> The input files can be any file type.
185
+
186
+
#### []{#tag_20_88_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
187
+
188
+
> The following environment variables shall affect the execution of
189
+
> *od*:
190
+
>
191
+
> *LANG*
192
+
> : Provide a default value for the internationalization variables
193
+
> that are unset or null. (See XBD [*Internationalization
194
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
195
+
> precedence of internationalization variables used to determine the
196
+
> values of locale categories.)
197
+
>
198
+
> *LC_ALL*
199
+
> : If set to a non-empty string value, override the values of all the
200
+
> other internationalization variables.
201
+
>
202
+
> *LC_CTYPE*
203
+
> : Determine the locale for the interpretation of sequences of bytes
204
+
> of text data as characters (for example, single-byte as opposed to
205
+
> multi-byte characters in arguments and input files).
206
+
>
207
+
> *LC_MESSAGES*
208
+
> : Determine the locale that should be used to affect the format and
209
+
> contents of diagnostic messages written to standard error.
210
+
>
211
+
> *LC_NUMERIC*
212
+
> : Determine the locale for selecting the radix character used when
213
+
> writing floating-point formatted output.
214
+
>
215
+
> *NLSPATH*
216
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
217
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
218
+
> location of message catalogs for the processing of *LC_MESSAGES.*
219
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
220
+
221
+
#### []{#tag_20_88_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
222
+
223
+
> Default.
224
+
225
+
#### []{#tag_20_88_10}STDOUT {#stdout .mansect}
226
+
227
+
> See the EXTENDED DESCRIPTION section.
228
+
229
+
#### []{#tag_20_88_11}STDERR {#stderr .mansect}
230
+
231
+
> The standard error shall be used only for diagnostic messages.
232
+
233
+
#### []{#tag_20_88_12}OUTPUT FILES {#output-files .mansect}
234
+
235
+
> None.
236
+
237
+
#### []{#tag_20_88_13}EXTENDED DESCRIPTION {#extended-description .mansect}
238
+
239
+
> The *od* utility shall copy sequentially each input file to standard
240
+
> output, transforming the input data according to the output types
241
+
> specified by the **-t** option
242
+
> ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
243
+
> Start\]](../images/opt-start.gif){border="0"} or the **-bcdosx**
244
+
> options. ![\[Option End\]](../images/opt-end.gif){border="0"} If no
245
+
> output type is specified, the default output shall be as if **-t oS**
246
+
> had been specified.
247
+
>
248
+
> The number of bytes transformed by the output type specifier `c` may
249
+
> be variable depending on the *LC_CTYPE* category.
250
+
>
251
+
> The default number of bytes transformed by output type specifiers `d`,
252
+
> `f`, `o`, `u`, and `x` corresponds to the various C-language types as
253
+
> follows. If the [*c99*](../utilities/c99.html) compiler is present on
254
+
> the system, these specifiers shall correspond to the sizes used by
255
+
> default in that compiler. Otherwise, these sizes may vary among
256
+
> systems that conform to POSIX.1-2017.
257
+
>
258
+
> - For the type specifier characters `d`, `o`, `u`, and `x`, the
259
+
> default number of bytes shall correspond to the size of the
260
+
> underlying implementation\'s basic integer type. For these specifier
261
+
> characters, the implementation shall support values of the optional
262
+
> number of bytes to be converted corresponding to the number of bytes
263
+
> in the C-language types **char**, **short**, **int**, and **long**.
264
+
> These numbers can also be specified by an application as the
265
+
> characters `'C'`, `'S'`, `'I'`, and `'L'`, respectively. The
266
+
> implementation shall also support the values 1, 2, 4, and 8, even if
267
+
> it provides no C-Language types of those sizes. The implementation
268
+
> shall support the decimal value corresponding to the C-language type
269
+
> **long long**. The byte order used when interpreting numeric values
270
+
> is implementation-defined, but shall correspond to the order in
271
+
> which a constant of the corresponding type is stored in memory on
272
+
> the system.
273
+
>
274
+
> - For the type specifier character `f`, the default number of bytes
275
+
> shall correspond to the number of bytes in the underlying
276
+
> implementation\'s basic double precision floating-point data type.
277
+
> The implementation shall support values of the optional number of
278
+
> bytes to be converted corresponding to the number of bytes in the
279
+
> C-language types **float,** **double**, and **long double**. These
280
+
> numbers can also be specified by an application as the characters
281
+
> `'F'`, `'D'`, and `'L'`, respectively.
282
+
>
283
+
> The type specifier character `a` specifies that bytes shall be
284
+
> interpreted as named characters from the International Reference
285
+
> Version (IRV) of the ISO/IEC 646:1991 standard. Only the least
286
+
> significant seven bits of each byte shall be used for this type
287
+
> specification. Bytes with the values listed in the following table
288
+
> shall be written using the corresponding names for those characters.\
289
+
>
290
+
> **Table: Named Characters in *od***
291
+
>
292
+
> **Value** **Name** **Value** **Name** **Value** **Name** **Value** **Name**
293
+
> ----------- ---------- ----------- ---------- ----------- ---------------------------- ----------- ----------
294
+
> \\000 **nul** \\001 **soh** \\002 **stx** \\003 **etx**
295
+
> \\004 **eot** \\005 **enq** \\006 **ack** \\007 **bel**
296
+
> \\010 **bs** \\011 **ht** \\012 **lf or nl^[\*]{.small}^** \\013 **vt**
297
+
> \\014 **ff** \\015 **cr** \\016 **so** \\017 **si**
298
+
> \\020 **dle** \\021 **dc1** \\022 **dc2** \\023 **dc3**
299
+
> \\024 **dc4** \\025 **nak** \\026 **syn** \\027 **etb**
300
+
> \\030 **can** \\031 **em** \\032 **sub** \\033 **esc**
301
+
> \\034 **fs** \\035 **gs** \\036 **rs** \\037 **us**
302
+
> \\040 **sp** \\177 **del** ** ** ** **
303
+
>
304
+
> **Note:**
305
+
> : The `"\012"` value may be written either as **lf** or **nl**.
306
+
>
307
+
> The type specifier character `c` specifies that bytes shall be
308
+
> interpreted as characters specified by the current setting of the
309
+
> *LC_CTYPE* locale category. Characters listed in the table in XBD
310
+
> [*File Format Notation*](../basedefs/V1_chap05.html#tag_05) ( `'\\'`,
311
+
> `'\a'`, `'\b'`, `'\f'`, `'\n'`, `'\r'`, `'\t'`, `'\v'` ) shall be
312
+
> written as the corresponding escape sequences, except that
313
+
> \<backslash\> shall be written as a single \<backslash\> and a NUL
314
+
> shall be written as `'\0'`. Other non-printable characters shall be
315
+
> written as one three-digit octal number for each byte in the
316
+
> character. Printable multi-byte characters shall be written in the
317
+
> area corresponding to the first byte of the character; the
318
+
> two-character sequence `"**"` shall be written in the area
319
+
> corresponding to each remaining byte in the character, as an
320
+
> indication that the character is continued. When either the **-j**
321
+
> *skip* or **-N** *count* option is specified along with the `c` type
322
+
> specifier, and this results in an attempt to start or finish in the
323
+
> middle of a multi-byte character, the result is
324
+
> implementation-defined.
325
+
>
326
+
> The input data shall be manipulated in blocks, where a block is
327
+
> defined as a multiple of the least common multiple of the number of
328
+
> bytes transformed by the specified output types. If the least common
329
+
> multiple is greater than 16, the results are unspecified. Each input
330
+
> block shall be written as transformed by each output type, one per
331
+
> written line, in the order that the output types were specified. If
332
+
> the input block size is larger than the number of bytes transformed by
333
+
> the output type, the output type shall sequentially transform the
334
+
> parts of the input block, and the output from each of the
335
+
> transformations shall be separated by one or more \<blank\>
336
+
> characters.
337
+
>
338
+
> If, as a result of the specification of the **-N** option or
339
+
> end-of-file being reached on the last input file, input data only
340
+
> partially satisfies an output type, the input shall be extended
341
+
> sufficiently with null bytes to write the last byte of the input.
342
+
>
343
+
> Unless **-A n** is specified, the first output line produced for each
344
+
> input block shall be preceded by the input offset, cumulative across
345
+
> input files, of the next byte to be written. The format of the input
346
+
> offset is unspecified; however, it shall not contain any \<blank\>
347
+
> characters, shall start at the first character of the output line, and
348
+
> shall be followed by one or more \<blank\> characters. In addition,
349
+
> the offset of the byte following the last byte written shall be
350
+
> written after all the input data has been processed, but shall not be
351
+
> followed by any \<blank\> characters.
352
+
>
353
+
> If no **-A** option is specified, the input offset base is
354
+
> unspecified.
355
+
356
+
#### []{#tag_20_88_14}EXIT STATUS {#exit-status .mansect}
357
+
358
+
> The following exit values shall be returned:
359
+
>
360
+
> 0
361
+
> : All input files were processed successfully.
362
+
>
363
+
> \>0
364
+
> : An error occurred.
365
+
366
+
#### []{#tag_20_88_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
367
+
368
+
> Default.
369
+
370
+
------------------------------------------------------------------------
371
+
372
+
::: box
373
+
*The following sections are informative.*
374
+
:::
375
+
376
+
#### []{#tag_20_88_16}APPLICATION USAGE {#application-usage .mansect}
377
+
378
+
> XSI-conformant applications are warned not to use filenames starting
379
+
> with `'+'` or a first operand starting with a numeric character so
380
+
> that the old functionality can be maintained by implementations,
381
+
> unless they specify one of the **-A**, **-j**, or **-N** options. To
382
+
> guarantee that one of these filenames is always interpreted as a
383
+
> filename, an application could always specify the address base format
384
+
> with the **-A** option.
385
+
386
+
#### []{#tag_20_88_17}EXAMPLES {#examples .mansect}
387
+
388
+
> If a file containing 128 bytes with decimal values zero to 127, in
389
+
> increasing order, is supplied as standard input to the command:
390
+
>
391
+
>
392
+
> od -A d -t a
393
+
>
394
+
> on an implementation using an input block size of 16 bytes, the
395
+
> standard output, independent of the current locale setting, would be
396
+
> similar to:
397
+
>
398
+
>
399
+
> 0000000 nul soh stx etx eot enq ack bel bs ht nl vt ff cr so si
400
+
> 0000016 dle dc1 dc2 dc3 dc4 nak syn etb can em sub esc fs gs rs us
401
+
> 0000032 sp ! " # $ % & ' ( ) * + , - . /
402
+
> 0000048 0 1 2 3 4 5 6 7 8 9 : ; < = > ?
403
+
> 0000064 @ A B C D E F G H I J K L M N O
404
+
> 0000080 P Q R S T U V W X Y Z [ \ ] ^ _
405
+
> 0000096 ` a b c d e f g h i j k l m n o
406
+
> 0000112 p q r s t u v w x y z { | } del
407
+
> 0000128
408
+
>
409
+
> Note that this volume of POSIX.1-2017 allows **nl** or **lf** to be
410
+
> used as the name for the ISO/IEC 646:1991 standard IRV character with
411
+
> decimal value 10. The IRV names this character **lf** (line feed), but
412
+
> traditional implementations have referred to this character as newline
413
+
> (**nl**) and the POSIX locale character set symbolic name for the
414
+
> corresponding character is a \<newline\>.
415
+
>
416
+
> The command:
417
+
>
418
+
>
419
+
> od -A o -t o2x2x -N 18
420
+
>
421
+
> on a system with 32-bit words and an implementation using an input
422
+
> block size of 16 bytes could write 18 bytes in approximately the
423
+
> following format:
424
+
>
425
+
>
426
+
> 0000000 032056 031440 041123 042040 052516 044530 020043 031464
427
+
> 342e 3320 4253 4420 554e 4958 2023 3334
428
+
> 342e3320 42534420 554e4958 20233334
429
+
> 0000020 032472
430
+
> 353a
431
+
> 353a0000
432
+
> 0000022
433
+
>
434
+
> The command:
435
+
>
436
+
>
437
+
> od -A d -t f -t o4 -t x4 -N 24 -j 0x15
438
+
>
439
+
> on a system with 64-bit doubles (for example, IEEE Std 754-1985 double
440
+
> precision floating-point format) would skip 21 bytes of input data and
441
+
> then write 24 bytes in approximately the following format:
442
+
>
443
+
>
444
+
> 0000000 1.00000000000000e+00 1.57350000000000e+01
445
+
> 07774000000 00000000000 10013674121 35341217270
446
+
> 3ff00000 00000000 402f3851 eb851eb8
447
+
> 0000016 1.40668230000000e+02
448
+
> 10030312542 04370303230
449
+
> 40619562 23e18698
450
+
> 0000024
451
+
452
+
#### []{#tag_20_88_18}RATIONALE {#rationale .mansect}
453
+
454
+
> The *od* utility went through several names in early proposals,
455
+
> including *hd*, *xd*, and most recently *hexdump*. There were several
456
+
> objections to all of these based on the following reasons:
457
+
>
458
+
> - The *hd* and *xd* names conflicted with historical utilities that
459
+
> behaved differently.
460
+
>
461
+
> - The *hexdump* description was much more complex than needed for a
462
+
> simple dump utility.
463
+
>
464
+
> - The *od* utility has been available on all historical
465
+
> implementations and there was no need to create a new name for a
466
+
> utility so similar to the historical *od* utility.
467
+
>
468
+
> The original reasons for not standardizing historical *od* were also
469
+
> fairly widespread. Those reasons are given below along with rationale
470
+
> explaining why the standard developers believe that this version does
471
+
> not suffer from the indicated problem:
472
+
>
473
+
> - The BSD and System V versions of *od* have diverged, and the
474
+
> intersection of features provided by both does not meet the needs of
475
+
> the user community. In fact, the System V version only provides a
476
+
> mechanism for dumping octal bytes and **short**s, signed and
477
+
> unsigned decimal **short**s, hexadecimal **short**s, and ASCII
478
+
> characters. BSD added the ability to dump **float**s, **double**s,
479
+
> named ASCII characters, and octal, signed decimal, unsigned decimal,
480
+
> and hexadecimal **long**s. The version presented here provides more
481
+
> normalized forms for dumping bytes, **short**s, **int**s, and
482
+
> **long**s in octal, signed decimal, unsigned decimal, and
483
+
> hexadecimal; **float**, **double**, and **long double**; and named
484
+
> ASCII as well as current locale characters.
485
+
>
486
+
> - It would not be possible to come up with a compatible superset of
487
+
> the BSD and System V flags that met the requirements of the standard
488
+
> developers. The historical default *od* output is the specified
489
+
> default output of this utility. None of the option letters chosen
490
+
> for this version of *od* conflict with any of the options to
491
+
> historical versions of *od*.
492
+
>
493
+
> - On systems with different sizes for **short**, **int**, and
494
+
> **long**, there was no way to ask for dumps of **int**s, even in the
495
+
> BSD version. Because of the way options are named, the name space
496
+
> could not be extended to solve these problems. This is why the
497
+
> **-t** option was added (with type specifiers more closely matched
498
+
> to the [*printf*()](../functions/printf.html) formats used in the
499
+
> rest of this volume of POSIX.1-2017) and the optional field sizes
500
+
> were added to the `d`, `f`, `o`, `u`, and `x` type specifiers. It is
501
+
> also one of the reasons why the historical practice was not mandated
502
+
> as a required obsolescent form of *od*. (Although the old versions
503
+
> of *od* are not listed as an obsolescent form, implementations are
504
+
> urged to continue to recognize the older forms for several more
505
+
> years.) The `a`, `c`, `f`, `o`, and `x` types match the meaning of
506
+
> the corresponding format characters in the historical
507
+
> implementations of *od* except for the default sizes of the fields
508
+
> converted. The `d` format is signed in this volume of POSIX.1-2017
509
+
> to match the [*printf*()](../functions/printf.html) notation.
510
+
> (Historical versions of *od* used `d` as a synonym for `u` in this
511
+
> version. The System V implementation uses `s` for signed decimal;
512
+
> BSD uses `i` for signed decimal and `s` for null-terminated
513
+
> strings.) Other than `d` and `u`, all of the type specifiers match
514
+
> format characters in the historical BSD version of **od**.
515
+
>
516
+
> The sizes of the C-language types **char**, **short**, **int**,
517
+
> **long**, **float**, **double**, and **long double** are used even
518
+
> though it is recognized that there may be zero or more than one
519
+
> compiler for the C language on an implementation and that they may
520
+
> use different sizes for some of these types. (For example, one
521
+
> compiler might use 2 bytes **short**s, 2 bytes **int**s, and 4 bytes
522
+
> **long**s, while another compiler (or an option to the same
523
+
> compiler) uses 2 bytes **short**s, 4 bytes **int**s, and 4 bytes
524
+
> **long**s.) Nonetheless, there has to be a basic size known by the
525
+
> implementation for these types, corresponding to the values reported
526
+
> by invocations of the [*getconf*](../utilities/getconf.html) utility
527
+
> when called with *system_var* operands {UCHAR_MAX}, {USHORT_MAX},
528
+
> {UINT_MAX}, and {ULONG_MAX} for the types **char**, **short**,
529
+
> **int**, and **long**, respectively. There are similar constants
530
+
> required by the ISO C standard, but not required by the System
531
+
> Interfaces volume of POSIX.1-2017 or this volume of POSIX.1-2017.
532
+
> They are {FLT_MANT_DIG}, {DBL_MANT_DIG}, and {LDBL_MANT_DIG} for the
533
+
> types **float**, **double**, and **long double**, respectively. If
534
+
> the optional [*c99*](../utilities/c99.html) utility is provided by
535
+
> the implementation and used as specified by this volume of
536
+
> POSIX.1-2017, these are the sizes that would be provided. If an
537
+
> option is used that specifies different sizes for these types, there
538
+
> is no guarantee that the *od* utility is able to interpret binary
539
+
> data output by such a program correctly.
540
+
>
541
+
> This volume of POSIX.1-2017 requires that the numeric values of
542
+
> these lengths be recognized by the *od* utility and that symbolic
543
+
> forms also be recognized. Thus, a conforming application can always
544
+
> look at an array of **unsigned long** data elements using *od*
545
+
> **-t** *uL*.
546
+
>
547
+
> - The method of specifying the format for the address field based on
548
+
> specifying a starting offset in a file unnecessarily tied the two
549
+
> together. The **-A** option now specifies the address base and the
550
+
> **-S** option specifies a starting offset.
551
+
>
552
+
> - It would be difficult to break the dependence on US ASCII to achieve
553
+
> an internationalized utility. It does not seem to be any harder for
554
+
> *od* to dump characters in the current locale than it is for the
555
+
> [*ed*](../utilities/ed.html) or [*sed*](../utilities/sed.html) **l**
556
+
> commands. The `c` type specifier does this without difficulty and is
557
+
> completely compatible with the historical implementations of the
558
+
> **c** format character when the current locale uses a superset of
559
+
> the ISO/IEC 646:1991 standard as a codeset. The `a` type specifier
560
+
> (from the BSD **a** format character) was left as a portable means
561
+
> to dump ASCII (or more correctly ISO/IEC 646:1991 standard (IRV)) so
562
+
> that headers produced by [*pax*](../utilities/pax.html) could be
563
+
> deciphered even on systems that do not use the ISO/IEC 646:1991
564
+
> standard as a subset of their base codeset.
565
+
>
566
+
> The use of `"**"` as an indication of continuation of a multi-byte
567
+
> character in `c` specifier output was chosen based on seeing an
568
+
> implementation that uses this method. The continuation bytes have to
569
+
> be marked in a way that is not ambiguous with another single-byte or
570
+
> multi-byte character.
571
+
>
572
+
> An early proposal used **-S** and **-n**, respectively, for the **-j**
573
+
> and **-N** options eventually selected. These were changed to avoid
574
+
> conflicts with historical implementations.
575
+
>
576
+
> The original standard specified **-t o2** as the default when no
577
+
> output type was given. This was changed to **-t oS** (the length of a
578
+
> **short**) to accommodate a supercomputer implementation that
579
+
> historically used 64 bits as its default (and that defined shorts as
580
+
> 64 bits). This change should not affect conforming applications. The
581
+
> requirement to support lengths of 1, 2, and 4 was added at the same
582
+
> time to address an historical implementation that had no two-byte data
583
+
> types in its C compiler.
584
+
>
585
+
> The use of a basic integer data type is intended to allow the
586
+
> implementation to choose a word size commonly used by applications on
587
+
> that architecture.
588
+
>
589
+
> Earlier versions of this standard allowed for implementations with
590
+
> bytes other than eight bits, but this has been modified in this
591
+
> version.
592
+
593
+
#### []{#tag_20_88_19}FUTURE DIRECTIONS {#future-directions .mansect}
594
+
595
+
> All option and operand interfaces marked XSI may be removed in a
596
+
> future version.
597
+
598
+
#### []{#tag_20_88_20}SEE ALSO {#see-also .mansect}
599
+
600
+
> [*c99*](../utilities/c99.html#), [*sed*](../utilities/sed.html#)
601
+
>
602
+
> XBD [*File Format Notation*](../basedefs/V1_chap05.html#tag_05),
603
+
> [*Environment Variables*](../basedefs/V1_chap08.html#tag_08),
604
+
> [*Utility Syntax Guidelines*](../basedefs/V1_chap12.html#tag_12_02)
605
+
606
+
#### []{#tag_20_88_21}CHANGE HISTORY {#change-history .mansect}
607
+
608
+
> First released in Issue 2.
609
+
610
+
#### []{#tag_20_88_22}Issue 5 {#issue-5 .mansect}
611
+
612
+
> In the description of the **-c** option, the phrase \"This is
613
+
> equivalent to **-t c**.\" is deleted.
614
+
>
615
+
> The FUTURE DIRECTIONS section is modified.
616
+
617
+
#### []{#tag_20_88_23}Issue 6 {#issue-6 .mansect}
618
+
619
+
> The *od* utility is changed to remove the assumption that **short**
620
+
> was a two-byte entity, as per the revisions in the IEEE P1003.2b draft
621
+
> standard.
622
+
>
623
+
> The normative text is reworded to avoid use of the term \"must\" for
624
+
> application requirements.
625
+
>
626
+
> IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/33 is applied,
627
+
> correcting the examples which used an undefined **-n** option, which
628
+
> should have been **-N**.
629
+
>
630
+
> IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/19 is applied,
631
+
> removing text describing behavior on systems with bytes consisting of
632
+
> more than eight bits.
633
+
634
+
#### []{#tag_20_88_24}Issue 7 {#issue-7 .mansect}
635
+
636
+
> Austin Group Interpretation 1003.1-2001 #092 is applied.
637
+
>
638
+
> SD5-XCU-ERN-37 is applied, updating the OPERANDS section.
639
+
>
640
+
> SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.
641
+
+284
docs/posix2018/paste.md
+284
docs/posix2018/paste.md
···
1
+
#### []{#tag_20_89_01}NAME {#name .mansect}
2
+
3
+
> paste - merge corresponding or subsequent lines of files
4
+
5
+
#### []{#tag_20_89_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `paste`` `**`[`**`-s`**`] [`**`-d`` `*`list`***`]`**` `*`file`*`...`
8
+
9
+
#### []{#tag_20_89_03}DESCRIPTION {#description .mansect}
10
+
11
+
> The *paste* utility shall concatenate the corresponding lines of the
12
+
> given input files, and write the resulting lines to standard output.
13
+
>
14
+
> The default operation of *paste* shall concatenate the corresponding
15
+
> lines of the input files. The \<newline\> of every line except the
16
+
> line from the last input file shall be replaced with a \<tab\>.
17
+
>
18
+
> If an end-of-file condition is detected on one or more input files,
19
+
> but not all input files, *paste* shall behave as though empty lines
20
+
> were read from the files on which end-of-file was detected, unless the
21
+
> **-s** option is specified.
22
+
23
+
#### []{#tag_20_89_04}OPTIONS {#options .mansect}
24
+
25
+
> The *paste* utility shall conform to XBD [*Utility Syntax
26
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02).
27
+
>
28
+
> The following options shall be supported:
29
+
>
30
+
> **-d ** *list*
31
+
>
32
+
> : Unless a \<backslash\> character appears in *list*, each character
33
+
> in *list* is an element specifying a delimiter character. If a
34
+
> \<backslash\> character appears in *list*, the \<backslash\>
35
+
> character and one or more characters following it are an element
36
+
> specifying a delimiter character as described below. These
37
+
> elements specify one or more delimiters to use, instead of the
38
+
> default \<tab\>, to replace the \<newline\> of the input lines.
39
+
> The elements in *list* shall be used circularly; that is, when the
40
+
> list is exhausted the first element from the list is reused. When
41
+
> the **-s** option is specified:
42
+
>
43
+
> - The last \<newline\> in a file shall not be modified.
44
+
>
45
+
> - The delimiter shall be reset to the first element of *list*
46
+
> after each *file* operand is processed.
47
+
>
48
+
> When the **-s** option is not specified:
49
+
>
50
+
> - The \<newline\> characters in the file specified by the last
51
+
> *file* operand shall not be modified.
52
+
>
53
+
> - The delimiter shall be reset to the first element of list each
54
+
> time a line is processed from each file.
55
+
>
56
+
> If a \<backslash\> character appears in *list*, it and the
57
+
> character following it shall be used to represent the following
58
+
> delimiter characters:
59
+
>
60
+
> `\n`
61
+
> : \<newline\>.
62
+
>
63
+
> `\t`
64
+
> : \<tab\>.
65
+
>
66
+
> `\\`
67
+
> : \<backslash\> character.
68
+
>
69
+
> `\0`
70
+
> : Empty string (not a null character). If `'\0'` is immediately
71
+
> followed by the character `'x'`, the character `'X'`, or any
72
+
> character defined by the *LC_CTYPE* **digit** keyword (see XBD
73
+
> [*Locale*](../basedefs/V1_chap07.html#tag_07)), the results
74
+
> are unspecified.
75
+
>
76
+
> If any other characters follow the \<backslash\>, the results are
77
+
> unspecified.
78
+
>
79
+
> **-s**
80
+
> : Concatenate all of the lines from each input file into one line of
81
+
> output per file, in command line order. The \<newline\> of every
82
+
> line except the last line in each input file shall be replaced
83
+
> with a \<tab\>, unless otherwise specified by the **-d** option.
84
+
> If an input file is empty, the output line corresponding to that
85
+
> file shall consist of only a \<newline\> character.
86
+
87
+
#### []{#tag_20_89_05}OPERANDS {#operands .mansect}
88
+
89
+
> The following operand shall be supported:
90
+
>
91
+
> *file*
92
+
> : A pathname of an input file. If `'-'` is specified for one or more
93
+
> of the *file*s, the standard input shall be used; the standard
94
+
> input shall be read one line at a time, circularly, for each
95
+
> instance of `'-'`. Implementations shall support pasting of at
96
+
> least 12 *file* operands.
97
+
98
+
#### []{#tag_20_89_06}STDIN {#stdin .mansect}
99
+
100
+
> The standard input shall be used only if one or more *file* operands
101
+
> is `'-'`. See the INPUT FILES section.
102
+
103
+
#### []{#tag_20_89_07}INPUT FILES {#input-files .mansect}
104
+
105
+
> The input files shall be text files, except that line lengths shall be
106
+
> unlimited.
107
+
108
+
#### []{#tag_20_89_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
109
+
110
+
> The following environment variables shall affect the execution of
111
+
> *paste*:
112
+
>
113
+
> *LANG*
114
+
> : Provide a default value for the internationalization variables
115
+
> that are unset or null. (See XBD [*Internationalization
116
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) the precedence
117
+
> of internationalization variables used to determine the values of
118
+
> locale categories.)
119
+
>
120
+
> *LC_ALL*
121
+
> : If set to a non-empty string value, override the values of all the
122
+
> other internationalization variables.
123
+
>
124
+
> *LC_CTYPE*
125
+
> : Determine the locale for the interpretation of sequences of bytes
126
+
> of text data as characters (for example, single-byte as opposed to
127
+
> multi-byte characters in arguments and input files).
128
+
>
129
+
> *LC_MESSAGES*
130
+
> : Determine the locale that should be used to affect the format and
131
+
> contents of diagnostic messages written to standard error.
132
+
>
133
+
> *NLSPATH*
134
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
135
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
136
+
> location of message catalogs for the processing of *LC_MESSAGES.*
137
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
138
+
139
+
#### []{#tag_20_89_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
140
+
141
+
> Default.
142
+
143
+
#### []{#tag_20_89_10}STDOUT {#stdout .mansect}
144
+
145
+
> Concatenated lines of input files shall be separated by the \<tab\>
146
+
> (or other characters under the control of the **-d** option) and
147
+
> terminated by a \<newline\>.
148
+
149
+
#### []{#tag_20_89_11}STDERR {#stderr .mansect}
150
+
151
+
> The standard error shall be used only for diagnostic messages.
152
+
153
+
#### []{#tag_20_89_12}OUTPUT FILES {#output-files .mansect}
154
+
155
+
> None.
156
+
157
+
#### []{#tag_20_89_13}EXTENDED DESCRIPTION {#extended-description .mansect}
158
+
159
+
> None.
160
+
161
+
#### []{#tag_20_89_14}EXIT STATUS {#exit-status .mansect}
162
+
163
+
> The following exit values shall be returned:
164
+
>
165
+
> 0
166
+
> : Successful completion.
167
+
>
168
+
> \>0
169
+
> : An error occurred.
170
+
171
+
#### []{#tag_20_89_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
172
+
173
+
> If one or more input files cannot be opened when the **-s** option is
174
+
> not specified, a diagnostic message shall be written to standard
175
+
> error, but no output is written to standard output. If the **-s**
176
+
> option is specified, the *paste* utility shall provide the default
177
+
> behavior described in [*Utility Description
178
+
> Defaults*](../utilities/V3_chap01.html#tag_17_04) .
179
+
180
+
------------------------------------------------------------------------
181
+
182
+
::: box
183
+
*The following sections are informative.*
184
+
:::
185
+
186
+
#### []{#tag_20_89_16}APPLICATION USAGE {#application-usage .mansect}
187
+
188
+
> When the escape sequences of the *list* option-argument are used in a
189
+
> shell script, they must be quoted; otherwise, the shell treats the
190
+
> \<backslash\> as a special character.
191
+
>
192
+
> Conforming applications should only use the specific
193
+
> \<backslash\>-escaped delimiters presented in this volume of
194
+
> POSIX.1-2017. Historical implementations treat `'\x'`, where `'x'` is
195
+
> not in this list, as `'x'`, but future implementations are free to
196
+
> expand this list to recognize other common escapes similar to those
197
+
> accepted by [*printf*](../utilities/printf.html) and other standard
198
+
> utilities.
199
+
>
200
+
> Most of the standard utilities work on text files. The
201
+
> [*cut*](../utilities/cut.html) utility can be used to turn files with
202
+
> arbitrary line lengths into a set of text files containing the same
203
+
> data. The *paste* utility can be used to create (or recreate) files
204
+
> with arbitrary line lengths. For example, if *file* contains long
205
+
> lines:
206
+
>
207
+
>
208
+
> cut -b 1-500 -n file > file1
209
+
> cut -b 501- -n file > file2
210
+
>
211
+
> creates **file1** (a text file) with lines no longer than 500 bytes
212
+
> (plus the \<newline\>) and **file2** that contains the remainder of
213
+
> the data from *file*. Note that **file2** is not a text file if there
214
+
> are lines in *file* that are longer than 500 + {LINE_MAX} bytes. The
215
+
> original file can be recreated from **file1** and **file2** using the
216
+
> command:
217
+
>
218
+
>
219
+
> paste -d "\0" file1 file2 > file
220
+
>
221
+
> The commands:
222
+
>
223
+
>
224
+
> paste -d "\0" ...
225
+
> paste -d "" ...
226
+
>
227
+
> are not necessarily equivalent; the latter is not specified by this
228
+
> volume of POSIX.1-2017 and may result in an error. The construct
229
+
> `'\0'` is used to mean \"no separator\" because historical versions of
230
+
> *paste* did not follow the syntax guidelines, and the command:
231
+
>
232
+
>
233
+
> paste -d"" ...
234
+
>
235
+
> could not be handled properly by
236
+
> [*getopt*()](../functions/getopt.html).
237
+
238
+
#### []{#tag_20_89_17}EXAMPLES {#examples .mansect}
239
+
240
+
> 1. Write out a directory in four columns:
241
+
>
242
+
>
243
+
> ls | paste - - - -
244
+
>
245
+
> 2. Combine pairs of lines from a file into single lines:
246
+
>
247
+
>
248
+
> paste -s -d "\t\n" file
249
+
250
+
#### []{#tag_20_89_18}RATIONALE {#rationale .mansect}
251
+
252
+
> None.
253
+
254
+
#### []{#tag_20_89_19}FUTURE DIRECTIONS {#future-directions .mansect}
255
+
256
+
> None.
257
+
258
+
#### []{#tag_20_89_20}SEE ALSO {#see-also .mansect}
259
+
260
+
> [*Utility Description
261
+
> Defaults*](../utilities/V3_chap01.html#tag_17_04),
262
+
> [*cut*](../utilities/cut.html#), [*grep*](../utilities/grep.html#),
263
+
> [*pr*](../utilities/pr.html#)
264
+
>
265
+
> XBD [*Locale*](../basedefs/V1_chap07.html#tag_07), [*Environment
266
+
> Variables*](../basedefs/V1_chap08.html#tag_08), [*Utility Syntax
267
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02)
268
+
269
+
#### []{#tag_20_89_21}CHANGE HISTORY {#change-history .mansect}
270
+
271
+
> First released in Issue 2.
272
+
273
+
#### []{#tag_20_89_22}Issue 6 {#issue-6 .mansect}
274
+
275
+
> The normative text is reworded to avoid use of the term \"must\" for
276
+
> application requirements.
277
+
278
+
#### []{#tag_20_89_23}Issue 7 {#issue-7 .mansect}
279
+
280
+
> SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.
281
+
>
282
+
> POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0149 \[973\] is
283
+
> applied.
284
+
+546
docs/posix2018/patch.md
+546
docs/posix2018/patch.md
···
1
+
#### []{#tag_20_90_01}NAME {#name .mansect}
2
+
3
+
> patch - apply changes to files
4
+
5
+
#### []{#tag_20_90_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `patch`` `**`[`**`-blNR`**`] [`**`-c|-e|-n|-u`**`] [`**`-d`` `*`dir`***`] [`**`-D`` `*`define`***`] [`**`-i`` `*`patchfile`***`]`\**
8
+
> ` `` `` `**`[`**`-o`` `*`outfile`***`] [`**`-p`` `*`num`***`] [`**`-r`` `*`rejectfile`***`] [`***`file`***`]`**
9
+
10
+
#### []{#tag_20_90_03}DESCRIPTION {#description .mansect}
11
+
12
+
> The *patch* utility shall read a source (patch) file containing any of
13
+
> four forms of difference (diff) listings produced by the
14
+
> [*diff*](../utilities/diff.html) utility (normal, copied context,
15
+
> unified context, or in the style of [*ed*](../utilities/ed.html)) and
16
+
> apply those differences to a file. By default, *patch* shall read from
17
+
> the standard input.
18
+
>
19
+
> The *patch* utility shall attempt to determine the type of the
20
+
> [*diff*](../utilities/diff.html) listing, unless overruled by a
21
+
> **-c**, **-e**, **-n**, or **-u** option.
22
+
>
23
+
> If the patch file contains more than one patch, *patch* shall attempt
24
+
> to apply each of them as if they came from separate patch files. (In
25
+
> this case, the application shall ensure that the name of the patch
26
+
> file is determinable for each [*diff*](../utilities/diff.html)
27
+
> listing.)
28
+
29
+
#### []{#tag_20_90_04}OPTIONS {#options .mansect}
30
+
31
+
> The *patch* utility shall conform to XBD [*Utility Syntax
32
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02).
33
+
>
34
+
> The following options shall be supported:
35
+
>
36
+
> **-b**
37
+
> : Save a copy of the original contents of each modified file, before
38
+
> the differences are applied, in a file of the same name with the
39
+
> suffix **.orig** appended to it. If the file already exists, it
40
+
> shall be overwritten; if multiple patches are applied to the same
41
+
> file, the **.orig** file shall be written only for the first
42
+
> patch. When the **-o** *outfile* option is also specified, *file*
43
+
> **.orig** shall not be created but, if *outfile* already exists,
44
+
> *outfile* **.orig** shall be created.
45
+
>
46
+
> **-c**
47
+
> : Interpret the patch file as a copied context difference (the
48
+
> output of the utility [*diff*](../utilities/diff.html) when the
49
+
> **-c** or **-C** options are specified).
50
+
>
51
+
> **-d ** *dir*
52
+
> : Change the current directory to *dir* before processing as
53
+
> described in the EXTENDED DESCRIPTION section.
54
+
>
55
+
> **-D ** *define*
56
+
>
57
+
> : Mark changes with one of the following C preprocessor constructs:
58
+
>
59
+
>
60
+
> #ifdef define
61
+
> ...
62
+
> #endif
63
+
>
64
+
>
65
+
> #ifndef define
66
+
> ...
67
+
> #endif
68
+
>
69
+
> optionally combined with the C preprocessor construct **#else**.
70
+
> If the patched file is processed with the C preprocessor, where
71
+
> the macro *define* is defined, the output shall contain the
72
+
> changes from the patch file; otherwise, the output shall not
73
+
> contain the patches specified in the patch file.
74
+
>
75
+
> **-e**
76
+
> : Interpret the patch file as an [*ed*](../utilities/ed.html)
77
+
> script, rather than a [*diff*](../utilities/diff.html) script.
78
+
>
79
+
> **-i ** *patchfile*
80
+
> : Read the patch information from the file named by the pathname
81
+
> *patchfile*, rather than the standard input.
82
+
>
83
+
> **-l**
84
+
> : (The letter ell.) Cause any sequence of \<blank\> characters in
85
+
> the difference script to match any sequence of \<blank\>
86
+
> characters in the input file. Other characters shall be matched
87
+
> exactly.
88
+
>
89
+
> **-n**
90
+
> : Interpret the script as a normal difference.
91
+
>
92
+
> **-N**
93
+
> : Ignore patches where the differences have already been applied to
94
+
> the file; by default, already-applied patches shall be rejected.
95
+
>
96
+
> **-o ** *outfile*
97
+
> : Instead of modifying the files (specified by the *file* operand or
98
+
> the difference listings) directly, write a copy of the file
99
+
> referenced by each patch, with the appropriate differences
100
+
> applied, to *outfile*. Multiple patches for a single file shall be
101
+
> applied to the intermediate versions of the file created by any
102
+
> previous patches, and shall result in multiple, concatenated
103
+
> versions of the file being written to *outfile*.
104
+
>
105
+
> **-p ** *num*
106
+
> : For all pathnames in the patch file that indicate the names of
107
+
> files to be patched, delete *num* pathname components from the
108
+
> beginning of each pathname. If the pathname in the patch file is
109
+
> absolute, any leading \<slash\> characters shall be considered the
110
+
> first component (that is, **-p 1** shall remove the leading
111
+
> \<slash\> characters). Specifying **-p 0** shall cause the full
112
+
> pathname to be used. If **-p** is not specified, only the basename
113
+
> (the final pathname component) shall be used.
114
+
>
115
+
> **-R**
116
+
> : Reverse the sense of the patch script; that is, assume that the
117
+
> difference script was created from the new version to the old
118
+
> version. The **-R** option cannot be used with
119
+
> [*ed*](../utilities/ed.html) scripts. The *patch* utility shall
120
+
> attempt to reverse each portion of the script before applying it.
121
+
> Rejected differences shall be saved in swapped format. If this
122
+
> option is not specified, and until a portion of the patch file is
123
+
> successfully applied, *patch* attempts to apply each portion in
124
+
> its reversed sense as well as in its normal sense. If the attempt
125
+
> is successful, the user shall be prompted to determine whether the
126
+
> **-R** option should be set.
127
+
>
128
+
> **-r ** *rejectfile*
129
+
> : Override the default reject filename. In the default case, the
130
+
> reject file shall have the same name as the output file, with the
131
+
> suffix **.rej** appended to it; see [Patch
132
+
> Application](#tag_20_90_13_03).
133
+
>
134
+
> **-u**
135
+
> : Interpret the patch file as a unified context difference (the
136
+
> output of the [*diff*](../utilities/diff.html) utility when the
137
+
> **-u** or **-U** options are specified).
138
+
139
+
#### []{#tag_20_90_05}OPERANDS {#operands .mansect}
140
+
141
+
> The following operand shall be supported:
142
+
>
143
+
> *file*
144
+
> : A pathname of a file to patch.
145
+
146
+
#### []{#tag_20_90_06}STDIN {#stdin .mansect}
147
+
148
+
> See the INPUT FILES section.
149
+
150
+
#### []{#tag_20_90_07}INPUT FILES {#input-files .mansect}
151
+
152
+
> Input files shall be text files.
153
+
154
+
#### []{#tag_20_90_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
155
+
156
+
> The following environment variables shall affect the execution of
157
+
> *patch*:
158
+
>
159
+
> *LANG*
160
+
> : Provide a default value for the internationalization variables
161
+
> that are unset or null. (See XBD [*Internationalization
162
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) the precedence
163
+
> of internationalization variables used to determine the values of
164
+
> locale categories.)
165
+
>
166
+
> *LC_ALL*
167
+
> : If set to a non-empty string value, override the values of all the
168
+
> other internationalization variables.
169
+
>
170
+
> *LC_COLLATE*
171
+
> : Determine the locale for the behavior of ranges, equivalence
172
+
> classes, and multi-character collating elements used in the
173
+
> extended regular expression defined for the **yesexpr** locale
174
+
> keyword in the *LC_MESSAGES* category.
175
+
>
176
+
> *LC_CTYPE*
177
+
> : Determine the locale for the interpretation of sequences of bytes
178
+
> of text data as characters (for example, single-byte as opposed to
179
+
> multi-byte characters in arguments and input files), and the
180
+
> behavior of character classes used in the extended regular
181
+
> expression defined for the **yesexpr** locale keyword in the
182
+
> *LC_MESSAGES* category.
183
+
>
184
+
> *LC_MESSAGES*
185
+
> : Determine the locale used to process affirmative responses, and
186
+
> the locale used to affect the format and contents of diagnostic
187
+
> messages and prompts written to standard error.
188
+
>
189
+
> *NLSPATH*
190
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
191
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
192
+
> location of message catalogs for the processing of *LC_MESSAGES.*
193
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
194
+
>
195
+
> *LC_TIME*
196
+
> : Determine the locale for recognizing the format of file timestamps
197
+
> written by the [*diff*](../utilities/diff.html) utility in a
198
+
> context-difference input file.
199
+
200
+
#### []{#tag_20_90_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
201
+
202
+
> Default.
203
+
204
+
#### []{#tag_20_90_10}STDOUT {#stdout .mansect}
205
+
206
+
> Not used.
207
+
208
+
#### []{#tag_20_90_11}STDERR {#stderr .mansect}
209
+
210
+
> The standard error shall be used for diagnostic and informational
211
+
> messages.
212
+
213
+
#### []{#tag_20_90_12}OUTPUT FILES {#output-files .mansect}
214
+
215
+
> The output of the *patch* utility, the save files (**.orig**
216
+
> suffixes), and the reject files (**.rej** suffixes) shall be text
217
+
> files.
218
+
219
+
#### []{#tag_20_90_13}EXTENDED DESCRIPTION {#extended-description .mansect}
220
+
221
+
> A patch file may contain patching instructions for more than one file;
222
+
> filenames shall be determined as specified in [Filename
223
+
> Determination](#tag_20_90_13_02). When the **-b** option is specified,
224
+
> for each patched file, the original shall be saved in a file of the
225
+
> same name with the suffix **.orig** appended to it.
226
+
>
227
+
> For each patched file, a reject file may also be created as noted in
228
+
> [Patch Application](#tag_20_90_13_03). In the absence of a **-r**
229
+
> option, the name of this file shall be formed by appending the suffix
230
+
> **.rej** to the original filename.
231
+
>
232
+
> ##### []{#tag_20_90_13_01}Patch File Format
233
+
>
234
+
> The patch file shall contain zero or more lines of header information
235
+
> followed by one or more patches. Each patch shall contain zero or more
236
+
> lines of filename identification in the format produced by the **-c**,
237
+
> **-C**, **-u**, or **-U** options of the
238
+
> [*diff*](../utilities/diff.html) utility, and one or more sets of
239
+
> [*diff*](../utilities/diff.html) output, which are customarily called
240
+
> *hunks*.
241
+
>
242
+
> The *patch* utility shall recognize the following expression in the
243
+
> header information:
244
+
>
245
+
> **Index: ** *pathname*
246
+
> : The file to be patched is named *pathname*.
247
+
>
248
+
> If all lines (including headers) within a patch begin with the same
249
+
> leading sequence of \<blank\> characters, the *patch* utility shall
250
+
> remove this sequence before proceeding. Within each patch, if the type
251
+
> of difference is common context, the *patch* utility shall recognize
252
+
> the following expressions:
253
+
>
254
+
> \*\*\* *filename timestamp*
255
+
> : The patches arose from *filename*.
256
+
>
257
+
> \-\-- *filename timestamp*
258
+
> : The patches should be applied to *filename*.
259
+
>
260
+
> If the type of difference is unified context, the *patch* utility
261
+
> shall recognize the following expressions:
262
+
>
263
+
> \-\-- *filename timestamp*
264
+
> : The patches arose from *filename*.
265
+
>
266
+
> +++ *filename timestamp*
267
+
> : The patches should be applied to *filename*.
268
+
>
269
+
> Each hunk within a patch shall be the [*diff*](../utilities/diff.html)
270
+
> output to change a line range within the original file. The line
271
+
> numbers for successive hunks within a patch shall occur in ascending
272
+
> order.
273
+
>
274
+
> ##### []{#tag_20_90_13_02}Filename Determination
275
+
>
276
+
> If no *file* operand is specified, *patch* shall perform the following
277
+
> steps to determine the filename to use:
278
+
>
279
+
> 1. If the type of [*diff*](../utilities/diff.html) is context, the
280
+
> *patch* utility shall delete pathname components (as specified by
281
+
> the **-p** option) from the filename on the line beginning with
282
+
> `"***"` (if copied context) or `"---"` (if unified context), then
283
+
> test for the existence of this file relative to the current
284
+
> directory (or the directory specified with the **-d** option). If
285
+
> the file exists, the *patch* utility shall use this filename.
286
+
>
287
+
> 2. If the type of [*diff*](../utilities/diff.html) is context, the
288
+
> *patch* utility shall delete the pathname components (as specified
289
+
> by the **-p** option) from the filename on the line beginning with
290
+
> `"---"` (if copied context) or `"+++"` (if unified context), then
291
+
> test for the existence of this file relative to the current
292
+
> directory (or the directory specified with the **-d** option). If
293
+
> the file exists, the *patch* utility shall use this filename.
294
+
>
295
+
> 3. If the header information contains a line beginning with the
296
+
> string **Index:**, the *patch* utility shall delete pathname
297
+
> components (as specified by the **-p** option) from this line,
298
+
> then test for the existence of this file relative to the current
299
+
> directory (or the directory specified with the **-d** option). If
300
+
> the file exists, the *patch* utility shall use this filename.
301
+
>
302
+
> 4. ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
303
+
> Start\]](../images/opt-start.gif){border="0"} If an **SCCS**
304
+
> directory exists in the current directory, *patch* shall attempt
305
+
> to perform a [*get*](../utilities/get.html) **-e** **SCCS/s.**
306
+
> *filename* command to retrieve an editable version of the file. If
307
+
> the file exists, the *patch* utility shall use this filename.
308
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
309
+
>
310
+
> 5. The *patch* utility shall write a prompt to standard output and
311
+
> request a filename interactively from the controlling terminal
312
+
> (for example, **/dev/tty**).
313
+
>
314
+
> ##### []{#tag_20_90_13_03}Patch Application
315
+
>
316
+
> If the **-c**, **-e**, **-n**, or **-u** option is present, the
317
+
> *patch* utility shall interpret information within each hunk as a
318
+
> copied context difference, an [*ed*](../utilities/ed.html) difference,
319
+
> a normal difference, or a unified context difference, respectively. In
320
+
> the absence of any of these options, the *patch* utility shall
321
+
> determine the type of difference based on the format of information
322
+
> within the hunk.
323
+
>
324
+
> For each hunk, the *patch* utility shall begin to search for the place
325
+
> to apply the patch at the line number at the beginning of the hunk,
326
+
> plus or minus any offset used in applying the previous hunk. If lines
327
+
> matching the hunk context are not found, *patch* shall scan both
328
+
> forwards and backwards at least 1000 bytes for a set of lines that
329
+
> match the hunk context.
330
+
>
331
+
> If no such place is found and it is a context difference, then another
332
+
> scan shall take place, ignoring the first and last line of context. If
333
+
> that fails, the first two and last two lines of context shall be
334
+
> ignored and another scan shall be made. Implementations may search
335
+
> more extensively for installation locations.
336
+
>
337
+
> If no location can be found, the *patch* utility shall append the hunk
338
+
> to the reject file. A rejected hunk that is a copied context
339
+
> difference, an [*ed*](../utilities/ed.html) difference, or a normal
340
+
> difference shall be written in copied-context-difference format
341
+
> regardless of the format of the patch file. It is
342
+
> implementation-defined whether a rejected hunk that is a unified
343
+
> context difference is written in copied-context-difference format or
344
+
> in unified-context-difference format. If the input was a normal or
345
+
> [*ed*](../utilities/ed.html)-style difference, the reject file may
346
+
> contain differences with zero lines of context. The line numbers on
347
+
> the hunks in the reject file may be different from the line numbers in
348
+
> the patch file since they shall reflect the approximate locations for
349
+
> the failed hunks in the new file rather than the old one.
350
+
>
351
+
> If the type of patch is an [*ed*](../utilities/ed.html) diff, the
352
+
> implementation may accomplish the patching by invoking the
353
+
> [*ed*](../utilities/ed.html) utility.
354
+
355
+
#### []{#tag_20_90_14}EXIT STATUS {#exit-status .mansect}
356
+
357
+
> The following exit values shall be returned:
358
+
>
359
+
> 0
360
+
> : Successful completion.
361
+
>
362
+
> 1
363
+
> : One or more lines were written to a reject file.
364
+
>
365
+
> \>1
366
+
> : An error occurred.
367
+
368
+
#### []{#tag_20_90_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
369
+
370
+
> Patches that cannot be correctly placed in the file shall be written
371
+
> to a reject file.
372
+
373
+
------------------------------------------------------------------------
374
+
375
+
::: box
376
+
*The following sections are informative.*
377
+
:::
378
+
379
+
#### []{#tag_20_90_16}APPLICATION USAGE {#application-usage .mansect}
380
+
381
+
> The **-R** option does not work with [*ed*](../utilities/ed.html)
382
+
> scripts because there is too little information to reconstruct the
383
+
> reverse operation.
384
+
>
385
+
> The **-p** option makes it possible to customize a patch file to local
386
+
> user directory structures without manually editing the patch file. For
387
+
> example, if the filename in the patch file was:
388
+
>
389
+
>
390
+
> /curds/whey/src/blurfl/blurfl.c
391
+
>
392
+
> Setting **-p 0** gives the entire pathname unmodified; **-p 1** gives:
393
+
>
394
+
>
395
+
> curds/whey/src/blurfl/blurfl.c
396
+
>
397
+
> without the leading \<slash\>, **-p 4** gives:
398
+
>
399
+
>
400
+
> blurfl/blurfl.c
401
+
>
402
+
> and not specifying **-p** at all gives:
403
+
>
404
+
>
405
+
> blurfl.c .
406
+
407
+
#### []{#tag_20_90_17}EXAMPLES {#examples .mansect}
408
+
409
+
> None.
410
+
411
+
#### []{#tag_20_90_18}RATIONALE {#rationale .mansect}
412
+
413
+
> Some of the functionality in historical *patch* implementations was
414
+
> not specified. The following documents those features present in
415
+
> historical implementations that have not been specified.
416
+
>
417
+
> A deleted piece of functionality was the `'+'` pseudo-option allowing
418
+
> an additional set of options and a patch file operand to be given.
419
+
> This was seen as being insufficiently useful to standardize.
420
+
>
421
+
> In historical implementations, if the string `"Prereq:"` appeared in
422
+
> the header, the *patch* utility would search for the corresponding
423
+
> version information (the string specified in the header, delimited by
424
+
> \<blank\> characters or the beginning or end of a line or the file)
425
+
> anywhere in the original file. This was deleted as too simplistic and
426
+
> insufficiently trustworthy a mechanism to standardize. For example,
427
+
> if:
428
+
>
429
+
>
430
+
> Prereq: 1.2
431
+
>
432
+
> were in the header, the presence of a delimited 1.2 anywhere in the
433
+
> file would satisfy the prerequisite.
434
+
>
435
+
> The following options were dropped from historical implementations of
436
+
> *patch* as insufficiently useful to standardize:
437
+
>
438
+
> **-b**
439
+
> : The **-b** option historically provided a method for changing the
440
+
> name extension of the backup file from the default **.orig**. This
441
+
> option has been modified and retained in this volume of
442
+
> POSIX.1-2017.
443
+
>
444
+
> **-F**
445
+
> : The **-F** option specified the number of lines of a context diff
446
+
> to ignore when searching for a place to install a patch.
447
+
>
448
+
> **-f**
449
+
> : The **-f** option historically caused *patch* not to request
450
+
> additional information from the user.
451
+
>
452
+
> **-r**
453
+
> : The **-r** option historically provided a method of overriding the
454
+
> extension of the reject file from the default **.rej**.
455
+
>
456
+
> **-s**
457
+
> : The **-s** option historically caused *patch* to work silently
458
+
> unless an error occurred.
459
+
>
460
+
> **-x**
461
+
> : The **-x** option historically set internal debugging flags.
462
+
>
463
+
> In some file system implementations, the saving of a **.orig** file
464
+
> may produce unwanted results. In the case of 12, 13, or 14-character
465
+
> filenames (on file systems supporting 14-character maximum filenames),
466
+
> the **.orig** file overwrites the new file. The reject file may also
467
+
> exceed this filename limit. It was suggested, due to some historical
468
+
> practice, that a \<tilde\> ( `'˜'` ) suffix be used instead of
469
+
> **.orig** and some other character instead of the **.rej** suffix.
470
+
> This was rejected because it is not obvious to the user which file is
471
+
> which. The suffixes **.orig** and **.rej** are clearer and more
472
+
> understandable.
473
+
>
474
+
> The **-b** option has the opposite sense in some historical
475
+
> implementations-do not save the **.orig** file. The default case here
476
+
> is not to save the files, making *patch* behave more consistently with
477
+
> the other standard utilities.
478
+
>
479
+
> The **-w** option in early proposals was changed to **-l** to match
480
+
> historical practice.
481
+
>
482
+
> The **-N** option was included because without it, a non-interactive
483
+
> application cannot reject previously applied patches. For example, if
484
+
> a user is piping the output of [*diff*](../utilities/diff.html) into
485
+
> the *patch* utility, and the user only wants to patch a file to a
486
+
> newer version non-interactively, the **-N** option is required.
487
+
>
488
+
> Changes to the **-l** option description were proposed to allow
489
+
> matching across \<newline\> characters in addition to just \<blank\>
490
+
> characters. Since this is not historical practice, and since some
491
+
> ambiguities could result, it is suggested that future developments in
492
+
> this area utilize another option letter, such as **-L**.
493
+
>
494
+
> The **-u** option of GNU *patch* has been added, along with support
495
+
> for unified context formats.
496
+
497
+
#### []{#tag_20_90_19}FUTURE DIRECTIONS {#future-directions .mansect}
498
+
499
+
> None.
500
+
501
+
#### []{#tag_20_90_20}SEE ALSO {#see-also .mansect}
502
+
503
+
> [*diff*](../utilities/diff.html#), [*ed*](../utilities/ed.html#)
504
+
>
505
+
> XBD [*Environment Variables*](../basedefs/V1_chap08.html#tag_08),
506
+
> [*Utility Syntax Guidelines*](../basedefs/V1_chap12.html#tag_12_02)
507
+
508
+
#### []{#tag_20_90_21}CHANGE HISTORY {#change-history .mansect}
509
+
510
+
> First released in Issue 4.
511
+
512
+
#### []{#tag_20_90_22}Issue 5 {#issue-5 .mansect}
513
+
514
+
> The FUTURE DIRECTIONS section is added.
515
+
516
+
#### []{#tag_20_90_23}Issue 6 {#issue-6 .mansect}
517
+
518
+
> This utility is marked as part of the User Portability Utilities
519
+
> option.
520
+
>
521
+
> The description of the **-D** option and the steps in [Filename
522
+
> Determination](#tag_20_90_13_02) are changed to match historical
523
+
> practice as defined in the IEEE P1003.2b draft standard.
524
+
>
525
+
> The normative text is reworded to avoid use of the term \"must\" for
526
+
> application requirements.
527
+
>
528
+
> IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/34 is applied,
529
+
> clarifying the way that the *patch* utility performs **ifdef**
530
+
> selection for the **-D** option.
531
+
532
+
#### []{#tag_20_90_24}Issue 7 {#issue-7 .mansect}
533
+
534
+
> The *patch* utility is moved from the User Portability Utilities
535
+
> option to the Base. User Portability Utilities is now an option for
536
+
> interactive utilities.
537
+
>
538
+
> SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.
539
+
>
540
+
> SD5-XCU-ERN-103 and SD5-XCU-ERN-120 are applied, adding the **-u**
541
+
> option.
542
+
>
543
+
> Austin Group Interpretation 1003.1-2001 #126 is applied, changing the
544
+
> description of the *LC_MESSAGES* and *LC_CTYPE* environment variables
545
+
> and adding the *LC_COLLATE* environment variable.
546
+
+429
docs/posix2018/printf.md
+429
docs/posix2018/printf.md
···
1
+
#### []{#tag_20_94_01}NAME {#name .mansect}
2
+
3
+
> printf - write formatted output
4
+
5
+
#### []{#tag_20_94_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `printf`` `*`format`*` `**`[`***`argument`*`...`**`]`**
8
+
9
+
#### []{#tag_20_94_03}DESCRIPTION {#description .mansect}
10
+
11
+
> The *printf* utility shall write formatted operands to the standard
12
+
> output. The *argument* operands shall be formatted under control of
13
+
> the *format* operand.
14
+
15
+
#### []{#tag_20_94_04}OPTIONS {#options .mansect}
16
+
17
+
> None.
18
+
19
+
#### []{#tag_20_94_05}OPERANDS {#operands .mansect}
20
+
21
+
> The following operands shall be supported:
22
+
>
23
+
> *format*
24
+
> : A string describing the format to use to write the remaining
25
+
> operands. See the EXTENDED DESCRIPTION section.
26
+
>
27
+
> *argument*
28
+
> : The strings to be written to standard output, under the control of
29
+
> *format*. See the EXTENDED DESCRIPTION section.
30
+
31
+
#### []{#tag_20_94_06}STDIN {#stdin .mansect}
32
+
33
+
> Not used.
34
+
35
+
#### []{#tag_20_94_07}INPUT FILES {#input-files .mansect}
36
+
37
+
> None.
38
+
39
+
#### []{#tag_20_94_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
40
+
41
+
> The following environment variables shall affect the execution of
42
+
> *printf*:
43
+
>
44
+
> *LANG*
45
+
> : Provide a default value for the internationalization variables
46
+
> that are unset or null. (See XBD [*Internationalization
47
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) the precedence
48
+
> of internationalization variables used to determine the values of
49
+
> locale categories.)
50
+
>
51
+
> *LC_ALL*
52
+
> : If set to a non-empty string value, override the values of all the
53
+
> other internationalization variables.
54
+
>
55
+
> *LC_CTYPE*
56
+
> : Determine the locale for the interpretation of sequences of bytes
57
+
> of text data as characters (for example, single-byte as opposed to
58
+
> multi-byte characters in arguments).
59
+
>
60
+
> *LC_MESSAGES*
61
+
> : Determine the locale that should be used to affect the format and
62
+
> contents of diagnostic messages written to standard error.
63
+
>
64
+
> *LC_NUMERIC*
65
+
> : Determine the locale for numeric formatting. It shall affect the
66
+
> format of numbers written using the `e`, `E`, `f`, `g`, and `G`
67
+
> conversion specifier characters (if supported).
68
+
>
69
+
> *NLSPATH*
70
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
71
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
72
+
> location of message catalogs for the processing of *LC_MESSAGES.*
73
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
74
+
75
+
#### []{#tag_20_94_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
76
+
77
+
> Default.
78
+
79
+
#### []{#tag_20_94_10}STDOUT {#stdout .mansect}
80
+
81
+
> See the EXTENDED DESCRIPTION section.
82
+
83
+
#### []{#tag_20_94_11}STDERR {#stderr .mansect}
84
+
85
+
> The standard error shall be used only for diagnostic messages.
86
+
87
+
#### []{#tag_20_94_12}OUTPUT FILES {#output-files .mansect}
88
+
89
+
> None.
90
+
91
+
#### []{#tag_20_94_13}EXTENDED DESCRIPTION {#extended-description .mansect}
92
+
93
+
> The *format* operand shall be used as the *format* string described in
94
+
> XBD [*File Format Notation*](../basedefs/V1_chap05.html#tag_05) with
95
+
> the following exceptions:
96
+
>
97
+
> 1. A \<space\> in the format string, in any context other than a flag
98
+
> of a conversion specification, shall be treated as an ordinary
99
+
> character that is copied to the output.
100
+
>
101
+
> 2. A `'`{border="0"}`'` character in the
102
+
> format string shall be treated as a
103
+
> `'`{border="0"}`'` character, not as a
104
+
> \<space\>.
105
+
>
106
+
> 3. In addition to the escape sequences shown in XBD [*File Format
107
+
> Notation*](../basedefs/V1_chap05.html#tag_05) ( `'\\'`, `'\a'`,
108
+
> `'\b'`, `'\f'`, `'\n'`, `'\r'`, `'\t'`, `'\v'` ), `"\ddd"`, where
109
+
> *ddd* is a one, two, or three-digit octal number, shall be written
110
+
> as a byte with the numeric value specified by the octal number.
111
+
>
112
+
> 4. The implementation shall not precede or follow output from the `d`
113
+
> or `u` conversion specifiers with \<blank\> characters not
114
+
> specified by the *format* operand.
115
+
>
116
+
> 5. The implementation shall not precede output from the `o`
117
+
> conversion specifier with zeros not specified by the *format*
118
+
> operand.
119
+
>
120
+
> 6. The `a`, `A`, `e`, `E`, `f`, `F`, `g`, and `G` conversion
121
+
> specifiers need not be supported.
122
+
>
123
+
> 7. An additional conversion specifier character, `b`, shall be
124
+
> supported as follows. The argument shall be taken to be a string
125
+
> that can contain \<backslash\>-escape sequences. The following
126
+
> \<backslash\>-escape sequences shall be supported:
127
+
>
128
+
> - The escape sequences listed in XBD [*File Format
129
+
> Notation*](../basedefs/V1_chap05.html#tag_05) ( `'\\'`, `'\a'`,
130
+
> `'\b'`, `'\f'`, `'\n'`, `'\r'`, `'\t'`, `'\v'` ), which shall be
131
+
> converted to the characters they represent
132
+
>
133
+
> - `"\0ddd"`, where *ddd* is a zero, one, two, or three-digit octal
134
+
> number that shall be converted to a byte with the numeric value
135
+
> specified by the octal number
136
+
>
137
+
> - `'\c'`, which shall not be written and shall cause *printf* to
138
+
> ignore any remaining characters in the string operand containing
139
+
> it, any remaining string operands, and any additional characters
140
+
> in the *format* operand
141
+
>
142
+
> The interpretation of a \<backslash\> followed by any other
143
+
> sequence of characters is unspecified.
144
+
>
145
+
> Bytes from the converted string shall be written until the end of
146
+
> the string or the number of bytes indicated by the precision
147
+
> specification is reached. If the precision is omitted, it shall be
148
+
> taken to be infinite, so all bytes up to the end of the converted
149
+
> string shall be written.
150
+
>
151
+
> 8. For each conversion specification that consumes an argument, the
152
+
> next *argument* operand shall be evaluated and converted to the
153
+
> appropriate type for the conversion as specified below.
154
+
>
155
+
> 9. The *format* operand shall be reused as often as necessary to
156
+
> satisfy the *argument* operands. Any extra `b`, `c`, or `s`
157
+
> conversion specifiers shall be evaluated as if a null string
158
+
> argument were supplied; other extra conversion specifications
159
+
> shall be evaluated as if a zero argument were supplied. If the
160
+
> *format* operand contains no conversion specifications and
161
+
> *argument* operands are present, the results are unspecified.
162
+
>
163
+
> 10. If a character sequence in the *format* operand begins with a
164
+
> `'%'` character, but does not form a valid conversion
165
+
> specification, the behavior is unspecified.
166
+
>
167
+
> 11. The argument to the `c` conversion specifier can be a string
168
+
> containing zero or more bytes. If it contains one or more bytes,
169
+
> the first byte shall be written and any additional bytes shall be
170
+
> ignored. If the argument is an empty string, it is unspecified
171
+
> whether nothing is written or a null byte is written.
172
+
>
173
+
> The *argument* operands shall be treated as strings if the
174
+
> corresponding conversion specifier is `b`, `c`, or `s`, and shall be
175
+
> evaluated as if by the [*strtod*()](../functions/strtod.html) function
176
+
> if the corresponding conversion specifier is `a`, `A`, `e`, `E`, `f`,
177
+
> `F`, `g`, or `G`. Otherwise, they shall be evaluated as unsuffixed C
178
+
> integer constants, as described by the ISO C standard, with the
179
+
> following extensions:
180
+
>
181
+
> - A leading \<plus-sign\> or \<hyphen-minus\> shall be allowed.
182
+
>
183
+
> - If the leading character is a single-quote or double-quote, the
184
+
> value shall be the numeric value in the underlying codeset of the
185
+
> character following the single-quote or double-quote.
186
+
>
187
+
> - Suffixed integer constants may be allowed.
188
+
>
189
+
> If an *argument* operand cannot be completely converted into an
190
+
> internal value appropriate to the corresponding conversion
191
+
> specification, a diagnostic message shall be written to standard error
192
+
> and the utility shall not exit with a zero exit status, but shall
193
+
> continue processing any remaining operands and shall write the value
194
+
> accumulated at the time the error was detected to standard output.
195
+
>
196
+
> It shall not be considered an error if an *argument* operand is not
197
+
> completely used for a `b`, `c`, or `s` conversion.
198
+
199
+
#### []{#tag_20_94_14}EXIT STATUS {#exit-status .mansect}
200
+
201
+
> The following exit values shall be returned:
202
+
>
203
+
> 0
204
+
> : Successful completion.
205
+
>
206
+
> \>0
207
+
> : An error occurred.
208
+
209
+
#### []{#tag_20_94_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
210
+
211
+
> Default.
212
+
213
+
------------------------------------------------------------------------
214
+
215
+
::: box
216
+
*The following sections are informative.*
217
+
:::
218
+
219
+
#### []{#tag_20_94_16}APPLICATION USAGE {#application-usage .mansect}
220
+
221
+
> The floating-point formatting conversion specifications of
222
+
> [*printf*()](../functions/printf.html) are not required because all
223
+
> arithmetic in the shell is integer arithmetic. The
224
+
> [*awk*](../utilities/awk.html) utility performs floating-point
225
+
> calculations and provides its own **printf** function. The
226
+
> [*bc*](../utilities/bc.html) utility can perform arbitrary-precision
227
+
> floating-point arithmetic, but does not provide extensive formatting
228
+
> capabilities. (This *printf* utility cannot really be used to format
229
+
> [*bc*](../utilities/bc.html) output; it does not support arbitrary
230
+
> precision.) Implementations are encouraged to support the
231
+
> floating-point conversions as an extension.
232
+
>
233
+
> Note that this *printf* utility, like the
234
+
> [*printf*()](../functions/printf.html) function defined in the System
235
+
> Interfaces volume of POSIX.1-2017 on which it is based, makes no
236
+
> special provision for dealing with multi-byte characters when using
237
+
> the `%c` conversion specification or when a precision is specified in
238
+
> a `%b` or `%s` conversion specification. Applications should be
239
+
> extremely cautious using either of these features when there are
240
+
> multi-byte characters in the character set.
241
+
>
242
+
> No provision is made in this volume of POSIX.1-2017 which allows field
243
+
> widths and precisions to be specified as `'*'` since the `'*'` can be
244
+
> replaced directly in the *format* operand using shell variable
245
+
> substitution. Implementations can also provide this feature as an
246
+
> extension if they so choose.
247
+
>
248
+
> Hexadecimal character constants as defined in the ISO C standard are
249
+
> not recognized in the *format* operand because there is no consistent
250
+
> way to detect the end of the constant. Octal character constants are
251
+
> limited to, at most, three octal digits, but hexadecimal character
252
+
> constants are only terminated by a non-hex-digit character. In the
253
+
> ISO C standard, the `"##"` concatenation operator can be used to
254
+
> terminate a constant and follow it with a hexadecimal character to be
255
+
> written. In the shell, concatenation occurs before the *printf*
256
+
> utility has a chance to parse the end of the hexadecimal constant.
257
+
>
258
+
> The `%b` conversion specification is not part of the ISO C standard;
259
+
> it has been added here as a portable way to process
260
+
> \<backslash\>-escapes expanded in string operands as provided by the
261
+
> [*echo*](../utilities/echo.html) utility. See also the APPLICATION
262
+
> USAGE section of [*echo*](../utilities/echo.html#) for ways to use
263
+
> *printf* as a replacement for all of the traditional versions of the
264
+
> [*echo*](../utilities/echo.html) utility.
265
+
>
266
+
> If an argument cannot be parsed correctly for the corresponding
267
+
> conversion specification, the *printf* utility is required to report
268
+
> an error. Thus, overflow and extraneous characters at the end of an
269
+
> argument being used for a numeric conversion shall be reported as
270
+
> errors.
271
+
272
+
#### []{#tag_20_94_17}EXAMPLES {#examples .mansect}
273
+
274
+
> To alert the user and then print and read a series of prompts:
275
+
>
276
+
>
277
+
> printf "\aPlease fill in the following: \nName: "
278
+
> read name
279
+
> printf "Phone number: "
280
+
> read phone
281
+
>
282
+
> To read out a list of right and wrong answers from a file, calculate
283
+
> the percentage correctly, and print them out. The numbers are
284
+
> right-justified and separated by a single \<tab\>. The percentage is
285
+
> written to one decimal place of accuracy:
286
+
>
287
+
>
288
+
> while read right wrong ; do
289
+
> percent=$(echo "scale=1;($right*100)/($right+$wrong)" | bc)
290
+
> printf "%2d right\t%2d wrong\t(%s%%)\n" \
291
+
> $right $wrong $percent
292
+
> done < database_file
293
+
>
294
+
> The command:
295
+
>
296
+
>
297
+
> printf "%5d%4d\n" 1 21 321 4321 54321
298
+
>
299
+
> produces:
300
+
>
301
+
>
302
+
>
303
+
> 1 21
304
+
> 3214321
305
+
> 54321 0
306
+
>
307
+
> Note that the *format* operand is used three times to print all of the
308
+
> given strings and that a `'0'` was supplied by *printf* to satisfy the
309
+
> last `%4d` conversion specification.
310
+
>
311
+
> The *printf* utility is required to notify the user when conversion
312
+
> errors are detected while producing numeric output; thus, the
313
+
> following results would be expected on an implementation with 32-bit
314
+
> twos-complement integers when `%d` is specified as the *format*
315
+
> operand:\
316
+
>
317
+
> ** ** **Standard** ** **
318
+
> -------------- -------------- ---------------------------------------------
319
+
> **Argument** **Output** **Diagnostic Output**
320
+
> 5a 5 printf: \"5a\" not completely converted
321
+
> 9999999999 2147483647 printf: \"9999999999\" arithmetic overflow
322
+
> -9999999999 -2147483648 printf: \"-9999999999\" arithmetic overflow
323
+
> ABC 0 printf: \"ABC\" expected numeric value
324
+
>
325
+
> The diagnostic message format is not specified, but these examples
326
+
> convey the type of information that should be reported. Note that the
327
+
> value shown on standard output is what would be expected as the return
328
+
> value from the [*strtol*()](../functions/strtol.html) function as
329
+
> defined in the System Interfaces volume of POSIX.1-2017. A similar
330
+
> correspondence exists between `%u` and
331
+
> [*strtoul*()](../functions/strtoul.html) and `%e`, `%f`, and `%g` (if
332
+
> the implementation supports floating-point conversions) and
333
+
> [*strtod*()](../functions/strtod.html).
334
+
>
335
+
> In a locale using the ISO/IEC 646:1991 standard as the underlying
336
+
> codeset, the command:
337
+
>
338
+
>
339
+
> printf "%d\n" 3 +3 -3 \'3 \"+3 "'-3"
340
+
>
341
+
> produces:
342
+
>
343
+
> 3
344
+
> : Numeric value of constant 3
345
+
>
346
+
> 3
347
+
> : Numeric value of constant 3
348
+
>
349
+
> -3
350
+
> : Numeric value of constant -3
351
+
>
352
+
> 51
353
+
> : Numeric value of the character `'3'` in the ISO/IEC 646:1991
354
+
> standard codeset
355
+
>
356
+
> 43
357
+
> : Numeric value of the character `'+'` in the ISO/IEC 646:1991
358
+
> standard codeset
359
+
>
360
+
> 45
361
+
> : Numeric value of the character `'-'` in the ISO/IEC 646:1991
362
+
> standard codeset
363
+
>
364
+
> Note that in a locale with multi-byte characters, the value of a
365
+
> character is intended to be the value of the equivalent of the
366
+
> **wchar_t** representation of the character as described in the System
367
+
> Interfaces volume of POSIX.1-2017.
368
+
369
+
#### []{#tag_20_94_18}RATIONALE {#rationale .mansect}
370
+
371
+
> The *printf* utility was added to provide functionality that has
372
+
> historically been provided by [*echo*](../utilities/echo.html).
373
+
> However, due to irreconcilable differences in the various versions of
374
+
> [*echo*](../utilities/echo.html) extant, the version has few special
375
+
> features, leaving those to this new *printf* utility, which is based
376
+
> on one in the Ninth Edition system.
377
+
>
378
+
> The EXTENDED DESCRIPTION section almost exactly matches the
379
+
> [*printf*()](../functions/printf.html) function in the ISO C standard,
380
+
> although it is described in terms of the file format notation in XBD
381
+
> [*File Format Notation*](../basedefs/V1_chap05.html#tag_05).
382
+
>
383
+
> Earlier versions of this standard specified that arguments for all
384
+
> conversions other than `b`, `c`, and `s` were evaluated in the same
385
+
> way (as C constants, but with stated exceptions). For implementations
386
+
> supporting the floating-point conversions it was not clear whether
387
+
> integer conversions need only accept integer constants and
388
+
> floating-point conversions need only accept floating-point constants,
389
+
> or whether both types of conversions should accept both types of
390
+
> constants. Also by not distinguishing between them, the requirement
391
+
> relating to a leading single-quote or double-quote applied to
392
+
> floating-point conversions even though this provided no useful
393
+
> functionality to applications that was not already available through
394
+
> the integer conversions. The current standard clarifies the situation
395
+
> by specifying that the arguments for floating-point conversions are
396
+
> evaluated as if by [*strtod*()](../functions/strtod.html), and the
397
+
> arguments for integer conversions are evaluated as C integer
398
+
> constants, with the special treatment of leading single-quote and
399
+
> double-quote applying only to integer conversions.
400
+
401
+
#### []{#tag_20_94_19}FUTURE DIRECTIONS {#future-directions .mansect}
402
+
403
+
> None.
404
+
405
+
#### []{#tag_20_94_20}SEE ALSO {#see-also .mansect}
406
+
407
+
> [*awk*](../utilities/awk.html#), [*bc*](../utilities/bc.html#),
408
+
> [*echo*](../utilities/echo.html#)
409
+
>
410
+
> XBD [*File Format Notation*](../basedefs/V1_chap05.html#tag_05),
411
+
> [*Environment Variables*](../basedefs/V1_chap08.html#tag_08)
412
+
>
413
+
> XSH [*fprintf*](../functions/fprintf.html#),
414
+
> [*strtod*](../functions/strtod.html#)
415
+
416
+
#### []{#tag_20_94_21}CHANGE HISTORY {#change-history .mansect}
417
+
418
+
> First released in Issue 4.
419
+
420
+
#### []{#tag_20_94_22}Issue 7 {#issue-7 .mansect}
421
+
422
+
> Austin Group Interpretations 1003.1-2001 #175 and #177 are applied.
423
+
>
424
+
> SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.
425
+
>
426
+
> POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0156 \[727\],
427
+
> XCU/TC2-2008/0157 \[727,932\], XCU/TC2-2008/0158 \[584\], and
428
+
> XCU/TC2-2008/0159 \[727\] are applied.
429
+
+202
docs/posix2018/pwd.md
+202
docs/posix2018/pwd.md
···
1
+
#### []{#tag_20_97_01}NAME {#name .mansect}
2
+
3
+
> pwd - return working directory name
4
+
5
+
#### []{#tag_20_97_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `pwd`` `**`[`**`-L|-P`**`]`**
8
+
9
+
#### []{#tag_20_97_03}DESCRIPTION {#description .mansect}
10
+
11
+
> The *pwd* utility shall write to standard output an absolute pathname
12
+
> of the current working directory, which does not contain the filenames
13
+
> dot or dot-dot.
14
+
15
+
#### []{#tag_20_97_04}OPTIONS {#options .mansect}
16
+
17
+
> The *pwd* utility shall conform to XBD [*Utility Syntax
18
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02) .
19
+
>
20
+
> The following options shall be supported by the implementation:
21
+
>
22
+
> **-L**
23
+
> : If the *PWD* environment variable contains an absolute pathname of
24
+
> the current directory and the pathname does not contain any
25
+
> components that are dot or dot-dot, *pwd* shall write this
26
+
> pathname to standard output, except that if the *PWD* environment
27
+
> variable is longer than {PATH_MAX} bytes including the terminating
28
+
> null, it is unspecified whether *pwd* writes this pathname to
29
+
> standard output or behaves as if the **-P** option had been
30
+
> specified. Otherwise, the **-L** option shall behave as the **-P**
31
+
> option.
32
+
>
33
+
> **-P**
34
+
> : The pathname written to standard output shall not contain any
35
+
> components that refer to files of type symbolic link. If there are
36
+
> multiple pathnames that the *pwd* utility could write to standard
37
+
> output, one beginning with a single \<slash\> character and one or
38
+
> more beginning with two \<slash\> characters, then it shall write
39
+
> the pathname beginning with a single \<slash\> character. The
40
+
> pathname shall not contain any unnecessary \<slash\> characters
41
+
> after the leading one or two \<slash\> characters.
42
+
>
43
+
> If both **-L** and **-P** are specified, the last one shall apply. If
44
+
> neither **-L** nor **-P** is specified, the *pwd* utility shall behave
45
+
> as if **-L** had been specified.
46
+
47
+
#### []{#tag_20_97_05}OPERANDS {#operands .mansect}
48
+
49
+
> None.
50
+
51
+
#### []{#tag_20_97_06}STDIN {#stdin .mansect}
52
+
53
+
> Not used.
54
+
55
+
#### []{#tag_20_97_07}INPUT FILES {#input-files .mansect}
56
+
57
+
> None.
58
+
59
+
#### []{#tag_20_97_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
60
+
61
+
> The following environment variables shall affect the execution of
62
+
> *pwd*:
63
+
>
64
+
> *LANG*
65
+
> : Provide a default value for the internationalization variables
66
+
> that are unset or null. (See XBD [*Internationalization
67
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) the precedence
68
+
> of internationalization variables used to determine the values of
69
+
> locale categories.)
70
+
>
71
+
> *LC_ALL*
72
+
> : If set to a non-empty string value, override the values of all the
73
+
> other internationalization variables.
74
+
>
75
+
> *LC_MESSAGES*
76
+
> : Determine the locale that should be used to affect the format and
77
+
> contents of diagnostic messages written to standard error.
78
+
>
79
+
> *NLSPATH*
80
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
81
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
82
+
> location of message catalogs for the processing of *LC_MESSAGES.*
83
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
84
+
>
85
+
> *PWD*
86
+
> : An absolute pathname of the current working directory. If an
87
+
> application sets or unsets the value of *PWD,* the behavior of
88
+
> *pwd* is unspecified.
89
+
90
+
#### []{#tag_20_97_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
91
+
92
+
> Default.
93
+
94
+
#### []{#tag_20_97_10}STDOUT {#stdout .mansect}
95
+
96
+
> The *pwd* utility output is an absolute pathname of the current
97
+
> working directory:
98
+
>
99
+
>
100
+
> "%s\n", <directory pathname>
101
+
102
+
#### []{#tag_20_97_11}STDERR {#stderr .mansect}
103
+
104
+
> The standard error shall be used only for diagnostic messages.
105
+
106
+
#### []{#tag_20_97_12}OUTPUT FILES {#output-files .mansect}
107
+
108
+
> None.
109
+
110
+
#### []{#tag_20_97_13}EXTENDED DESCRIPTION {#extended-description .mansect}
111
+
112
+
> None.
113
+
114
+
#### []{#tag_20_97_14}EXIT STATUS {#exit-status .mansect}
115
+
116
+
> The following exit values shall be returned:
117
+
>
118
+
> 0
119
+
> : Successful completion.
120
+
>
121
+
> \>0
122
+
> : An error occurred.
123
+
124
+
#### []{#tag_20_97_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
125
+
126
+
> If an error is detected, output shall not be written to standard
127
+
> output, a diagnostic message shall be written to standard error, and
128
+
> the exit status is not zero.
129
+
130
+
------------------------------------------------------------------------
131
+
132
+
::: box
133
+
*The following sections are informative.*
134
+
:::
135
+
136
+
#### []{#tag_20_97_16}APPLICATION USAGE {#application-usage .mansect}
137
+
138
+
> If the pathname obtained from *pwd* is longer than {PATH_MAX} bytes,
139
+
> it could produce an error if passed to [*cd*](../utilities/cd.html).
140
+
> Therefore, in order to return to that directory it may be necessary to
141
+
> break the pathname into sections shorter than {PATH_MAX} and call
142
+
> [*cd*](../utilities/cd.html) on each section in turn (the first
143
+
> section being an absolute pathname and subsequent sections being
144
+
> relative pathnames).
145
+
146
+
#### []{#tag_20_97_17}EXAMPLES {#examples .mansect}
147
+
148
+
> None.
149
+
150
+
#### []{#tag_20_97_18}RATIONALE {#rationale .mansect}
151
+
152
+
> Some implementations have historically provided *pwd* as a shell
153
+
> special built-in command.
154
+
>
155
+
> In most utilities, if an error occurs, partial output may be written
156
+
> to standard output. This does not happen in historical implementations
157
+
> of *pwd*. Because *pwd* is frequently used in historical shell scripts
158
+
> without checking the exit status, it is important that the historical
159
+
> behavior is required here; therefore, the CONSEQUENCES OF ERRORS
160
+
> section specifically disallows any partial output being written to
161
+
> standard output.
162
+
>
163
+
> An earlier version of this standard stated that the *PWD* environment
164
+
> variable was affected when the **-P** option was in effect. This was
165
+
> incorrect; conforming implementations do not do this.
166
+
167
+
#### []{#tag_20_97_19}FUTURE DIRECTIONS {#future-directions .mansect}
168
+
169
+
> None.
170
+
171
+
#### []{#tag_20_97_20}SEE ALSO {#see-also .mansect}
172
+
173
+
> [*cd*](../utilities/cd.html#)
174
+
>
175
+
> XBD [*Environment Variables*](../basedefs/V1_chap08.html#tag_08),
176
+
> [*Utility Syntax Guidelines*](../basedefs/V1_chap12.html#tag_12_02)
177
+
>
178
+
> XSH [*getcwd*](../functions/getcwd.html#)
179
+
180
+
#### []{#tag_20_97_21}CHANGE HISTORY {#change-history .mansect}
181
+
182
+
> First released in Issue 2.
183
+
184
+
#### []{#tag_20_97_22}Issue 6 {#issue-6 .mansect}
185
+
186
+
> The **-P** and **-L** options are added to describe actions relating
187
+
> to symbolic links as specified in the IEEE P1003.2b draft standard.
188
+
189
+
#### []{#tag_20_97_23}Issue 7 {#issue-7 .mansect}
190
+
191
+
> Austin Group Interpretation 1003.1-2001 #097 is applied.
192
+
>
193
+
> SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.
194
+
>
195
+
> Changes to the *pwd* utility and *PWD* environment variable have been
196
+
> made to match the changes to the
197
+
> [*getcwd*()](../functions/getcwd.html) function made for Austin Group
198
+
> Interpretation 1003.1-2001 #140.
199
+
>
200
+
> POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0161 \[471\] is
201
+
> applied.
202
+
+353
docs/posix2018/rm.md
+353
docs/posix2018/rm.md
···
1
+
#### []{#tag_20_111_01}NAME {#name .mansect}
2
+
3
+
> rm - remove directory entries
4
+
5
+
#### []{#tag_20_111_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `rm`` `**`[`**`-iRr`**`]`**` `*`file`*`...`\
8
+
> \
9
+
> `rm -f`` `**`[`**`-iRr`**`]`**` `**`[`***`file`*`...`**`]`**\
10
+
11
+
#### []{#tag_20_111_03}DESCRIPTION {#description .mansect}
12
+
13
+
> The *rm* utility shall remove the directory entry specified by each
14
+
> *file* argument.
15
+
>
16
+
> If either of the files dot or dot-dot are specified as the basename
17
+
> portion of an operand (that is, the final pathname component) or if an
18
+
> operand resolves to the root directory, *rm* shall write a diagnostic
19
+
> message to standard error and do nothing more with such operands.
20
+
>
21
+
> For each *file* the following steps shall be taken:
22
+
>
23
+
> 1. If the *file* does not exist:
24
+
>
25
+
> a. If the **-f** option is not specified, *rm* shall write a
26
+
> diagnostic message to standard error.
27
+
>
28
+
> b. Go on to any remaining *files*.
29
+
>
30
+
> 2. If *file* is of type directory, the following steps shall be
31
+
> taken:
32
+
>
33
+
> a. If neither the **-R** option nor the **-r** option is
34
+
> specified, *rm* shall write a diagnostic message to standard
35
+
> error, do nothing more with *file*, and go on to any remaining
36
+
> files.
37
+
>
38
+
> b. If *file* is an empty directory, *rm* may skip to step 2d. If
39
+
> the **-f** option is not specified, and either the permissions
40
+
> of *file* do not permit writing and the standard input is a
41
+
> terminal or the **-i** option is specified, *rm* shall write a
42
+
> prompt to standard error and read a line from the standard
43
+
> input. If the response is not affirmative, *rm* shall do
44
+
> nothing more with the current file and go on to any remaining
45
+
> files.
46
+
>
47
+
> c. For each entry contained in *file*, other than dot or dot-dot,
48
+
> the four steps listed here (1 to 4) shall be taken with the
49
+
> entry as if it were a *file* operand. The *rm* utility shall
50
+
> not traverse directories by following symbolic links into
51
+
> other parts of the hierarchy, but shall remove the links
52
+
> themselves.
53
+
>
54
+
> d. If the **-i** option is specified, *rm* shall write a prompt
55
+
> to standard error and read a line from the standard input. If
56
+
> the response is not affirmative, *rm* shall do nothing more
57
+
> with the current file, and go on to any remaining files.
58
+
>
59
+
> 3. If *file* is not of type directory, the **-f** option is not
60
+
> specified, and either the permissions of *file* do not permit
61
+
> writing and the standard input is a terminal or the **-i** option
62
+
> is specified, *rm* shall write a prompt to the standard error and
63
+
> read a line from the standard input. If the response is not
64
+
> affirmative, *rm* shall do nothing more with the current file and
65
+
> go on to any remaining files.
66
+
>
67
+
> 4. If the current file is a directory, *rm* shall perform actions
68
+
> equivalent to the [*rmdir*()](../functions/rmdir.html) function
69
+
> defined in the System Interfaces volume of POSIX.1-2017 called
70
+
> with a pathname of the current file used as the *path* argument.
71
+
> If the current file is not a directory, *rm* shall perform actions
72
+
> equivalent to the [*unlink*()](../functions/unlink.html) function
73
+
> defined in the System Interfaces volume of POSIX.1-2017 called
74
+
> with a pathname of the current file used as the *path* argument.
75
+
>
76
+
> If this fails for any reason, *rm* shall write a diagnostic
77
+
> message to standard error, do nothing more with the current file,
78
+
> and go on to any remaining files.
79
+
>
80
+
> The *rm* utility shall be able to descend to arbitrary depths in a
81
+
> file hierarchy, and shall not fail due to path length limitations
82
+
> (unless an operand specified by the user exceeds system limitations).
83
+
84
+
#### []{#tag_20_111_04}OPTIONS {#options .mansect}
85
+
86
+
> The *rm* utility shall conform to XBD [*Utility Syntax
87
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02) .
88
+
>
89
+
> The following options shall be supported:
90
+
>
91
+
> **-f**
92
+
> : Do not prompt for confirmation. Do not write diagnostic messages
93
+
> or modify the exit status in the case of no file operands, or in
94
+
> the case of operands that do not exist. Any previous occurrences
95
+
> of the **-i** option shall be ignored.
96
+
>
97
+
> **-i**
98
+
> : Prompt for confirmation as described previously. Any previous
99
+
> occurrences of the **-f** option shall be ignored.
100
+
>
101
+
> **-R**
102
+
> : Remove file hierarchies. See the DESCRIPTION.
103
+
>
104
+
> **-r**
105
+
> : Equivalent to **-R**.
106
+
107
+
#### []{#tag_20_111_05}OPERANDS {#operands .mansect}
108
+
109
+
> The following operand shall be supported:
110
+
>
111
+
> *file*
112
+
> : A pathname of a directory entry to be removed.
113
+
114
+
#### []{#tag_20_111_06}STDIN {#stdin .mansect}
115
+
116
+
> The standard input shall be used to read an input line in response to
117
+
> each prompt specified in the STDOUT section. Otherwise, the standard
118
+
> input shall not be used.
119
+
120
+
#### []{#tag_20_111_07}INPUT FILES {#input-files .mansect}
121
+
122
+
> None.
123
+
124
+
#### []{#tag_20_111_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
125
+
126
+
> The following environment variables shall affect the execution of
127
+
> *rm*:
128
+
>
129
+
> *LANG*
130
+
> : Provide a default value for the internationalization variables
131
+
> that are unset or null. (See XBD [*Internationalization
132
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
133
+
> precedence of internationalization variables used to determine the
134
+
> values of locale categories.)
135
+
>
136
+
> *LC_ALL*
137
+
> : If set to a non-empty string value, override the values of all the
138
+
> other internationalization variables.
139
+
>
140
+
> *LC_COLLATE*
141
+
> : Determine the locale for the behavior of ranges, equivalence
142
+
> classes, and multi-character collating elements used in the
143
+
> extended regular expression defined for the **yesexpr** locale
144
+
> keyword in the *LC_MESSAGES* category.
145
+
>
146
+
> *LC_CTYPE*
147
+
> : Determine the locale for the interpretation of sequences of bytes
148
+
> of text data as characters (for example, single-byte as opposed to
149
+
> multi-byte characters in arguments) and the behavior of character
150
+
> classes within regular expressions used in the extended regular
151
+
> expression defined for the **yesexpr** locale keyword in the
152
+
> *LC_MESSAGES* category.
153
+
>
154
+
> *LC_MESSAGES*
155
+
> : Determine the locale used to process affirmative responses, and
156
+
> the locale used to affect the format and contents of diagnostic
157
+
> messages and prompts written to standard error.
158
+
>
159
+
> *NLSPATH*
160
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
161
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
162
+
> location of message catalogs for the processing of *LC_MESSAGES.*
163
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
164
+
165
+
#### []{#tag_20_111_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
166
+
167
+
> Default.
168
+
169
+
#### []{#tag_20_111_10}STDOUT {#stdout .mansect}
170
+
171
+
> Not used.
172
+
173
+
#### []{#tag_20_111_11}STDERR {#stderr .mansect}
174
+
175
+
> Prompts shall be written to standard error under the conditions
176
+
> specified in the DESCRIPTION and OPTIONS sections. The prompts shall
177
+
> contain the *file* pathname, but their format is otherwise
178
+
> unspecified. The standard error also shall be used for diagnostic
179
+
> messages.
180
+
181
+
#### []{#tag_20_111_12}OUTPUT FILES {#output-files .mansect}
182
+
183
+
> None.
184
+
185
+
#### []{#tag_20_111_13}EXTENDED DESCRIPTION {#extended-description .mansect}
186
+
187
+
> None.
188
+
189
+
#### []{#tag_20_111_14}EXIT STATUS {#exit-status .mansect}
190
+
191
+
> The following exit values shall be returned:
192
+
>
193
+
> 0
194
+
> : Each directory entry was successfully removed, unless its removal
195
+
> was canceled by a non-affirmative response to a prompt for
196
+
> confirmation.
197
+
>
198
+
> \>0
199
+
> : An error occurred.
200
+
201
+
#### []{#tag_20_111_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
202
+
203
+
> Default.
204
+
205
+
------------------------------------------------------------------------
206
+
207
+
::: box
208
+
*The following sections are informative.*
209
+
:::
210
+
211
+
#### []{#tag_20_111_16}APPLICATION USAGE {#application-usage .mansect}
212
+
213
+
> The *rm* utility is forbidden to remove the names dot and dot-dot in
214
+
> order to avoid the consequences of inadvertently doing something like:
215
+
>
216
+
>
217
+
> rm -r .*
218
+
>
219
+
> Some implementations do not permit the removal of the last link to an
220
+
> executable binary file that is being executed; see the \[EBUSY\] error
221
+
> in the [*unlink*()](../functions/unlink.html) function defined in the
222
+
> System Interfaces volume of POSIX.1-2017. Thus, the *rm* utility can
223
+
> fail to remove such files.
224
+
>
225
+
> The **-i** option causes *rm* to prompt and read the standard input
226
+
> even if the standard input is not a terminal, but in the absence of
227
+
> **-i** the mode prompting is not done when the standard input is not a
228
+
> terminal.
229
+
230
+
#### []{#tag_20_111_17}EXAMPLES {#examples .mansect}
231
+
232
+
> 1. The following command:
233
+
>
234
+
>
235
+
> rm a.out core
236
+
>
237
+
> removes the directory entries: **a.out** and **core**.
238
+
>
239
+
> 2. The following command:
240
+
>
241
+
>
242
+
> rm -Rf junk
243
+
>
244
+
> removes the directory **junk** and all its contents, without
245
+
> prompting.
246
+
247
+
#### []{#tag_20_111_18}RATIONALE {#rationale .mansect}
248
+
249
+
> For absolute clarity, paragraphs (2b) and (3) in the DESCRIPTION of
250
+
> *rm* describing the behavior when prompting for confirmation, should
251
+
> be interpreted in the following manner:
252
+
>
253
+
>
254
+
> if ((NOT f_option) AND
255
+
> ((not_writable AND input_is_terminal) OR i_option))
256
+
>
257
+
> The exact format of the interactive prompts is unspecified. Only the
258
+
> general nature of the contents of prompts are specified because
259
+
> implementations may desire more descriptive prompts than those used on
260
+
> historical implementations. Therefore, an application not using the
261
+
> **-f** option, or using the **-i** option, relies on the system to
262
+
> provide the most suitable dialog directly with the user, based on the
263
+
> behavior specified.
264
+
>
265
+
> The **-r** option is historical practice on all known systems. The
266
+
> synonym **-R** option is provided for consistency with the other
267
+
> utilities in this volume of POSIX.1-2017 that provide options
268
+
> requesting recursive descent through the file hierarchy.
269
+
>
270
+
> The behavior of the **-f** option in historical versions of *rm* is
271
+
> inconsistent. In general, along with \"forcing\" the unlink without
272
+
> prompting for permission, it always causes diagnostic messages to be
273
+
> suppressed and the exit status to be unmodified for nonexistent
274
+
> operands and files that cannot be unlinked. In some versions, however,
275
+
> the **-f** option suppresses usage messages and system errors as well.
276
+
> Suppressing such messages is not a service to either shell scripts or
277
+
> users.
278
+
>
279
+
> It is less clear that error messages regarding files that cannot be
280
+
> unlinked (removed) should be suppressed. Although this is historical
281
+
> practice, this volume of POSIX.1-2017 does not permit the **-f**
282
+
> option to suppress such messages.
283
+
>
284
+
> When given the **-r** and **-i** options, historical versions of *rm*
285
+
> prompt the user twice for each directory, once before removing its
286
+
> contents and once before actually attempting to delete the directory
287
+
> entry that names it. This allows the user to \"prune\" the file
288
+
> hierarchy walk. Historical versions of *rm* were inconsistent in that
289
+
> some did not do the former prompt for directories named on the command
290
+
> line and others had obscure prompting behavior when the **-i** option
291
+
> was specified and the permissions of the file did not permit writing.
292
+
> The POSIX Shell and Utilities *rm* differs little from historic
293
+
> practice, but does require that prompts be consistent. Historical
294
+
> versions of *rm* were also inconsistent in that prompts were done to
295
+
> both standard output and standard error. This volume of POSIX.1-2017
296
+
> requires that prompts be done to standard error, for consistency with
297
+
> [*cp*](../utilities/cp.html) and [*mv*](../utilities/mv.html), and to
298
+
> allow historical extensions to *rm* that provide an option to list
299
+
> deleted files on standard output.
300
+
>
301
+
> The *rm* utility is required to descend to arbitrary depths so that
302
+
> any file hierarchy may be deleted. This means, for example, that the
303
+
> *rm* utility cannot run out of file descriptors during its descent
304
+
> (that is, if the number of file descriptors is limited, *rm* cannot be
305
+
> implemented in the historical fashion where one file descriptor is
306
+
> used per directory level). Also, *rm* is not permitted to fail because
307
+
> of path length restrictions, unless an operand specified by the user
308
+
> is longer than {PATH_MAX}.
309
+
>
310
+
> The *rm* utility removes symbolic links themselves, not the files they
311
+
> refer to, as a consequence of the dependence on the
312
+
> [*unlink*()](../functions/unlink.html) functionality, per the
313
+
> DESCRIPTION. When removing hierarchies with **-r** or **-R**, the
314
+
> prohibition on following symbolic links has to be made explicit.
315
+
316
+
#### []{#tag_20_111_19}FUTURE DIRECTIONS {#future-directions .mansect}
317
+
318
+
> None.
319
+
320
+
#### []{#tag_20_111_20}SEE ALSO {#see-also .mansect}
321
+
322
+
> [*rmdir*](../utilities/rmdir.html#tag_20_113)
323
+
>
324
+
> XBD [*Environment Variables*](../basedefs/V1_chap08.html#tag_08),
325
+
> [*Utility Syntax Guidelines*](../basedefs/V1_chap12.html#tag_12_02)
326
+
>
327
+
> XSH [*remove*](../functions/remove.html#),
328
+
> [*rmdir*](../functions/rmdir.html#tag_16_491),
329
+
> [*unlink*](../functions/unlink.html#tag_16_635)
330
+
331
+
#### []{#tag_20_111_21}CHANGE HISTORY {#change-history .mansect}
332
+
333
+
> First released in Issue 2.
334
+
335
+
#### []{#tag_20_111_22}Issue 5 {#issue-5 .mansect}
336
+
337
+
> The FUTURE DIRECTIONS section is added.
338
+
339
+
#### []{#tag_20_111_23}Issue 6 {#issue-6 .mansect}
340
+
341
+
> Text is added to clarify actions relating to symbolic links as
342
+
> specified in the IEEE P1003.2b draft standard.
343
+
344
+
#### []{#tag_20_111_24}Issue 7 {#issue-7 .mansect}
345
+
346
+
> Austin Group Interpretations 1003.1-2001 #019 and #091 are applied.
347
+
>
348
+
> Austin Group Interpretation 1003.1-2001 #126 is applied, changing the
349
+
> description of the *LC_MESSAGES* environment variable.
350
+
>
351
+
> POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0163 \[542\],
352
+
> XCU/TC2-2008/0164 \[819\], and XCU/TC2-2008/0165 \[542\] are applied.
353
+
+183
docs/posix2018/rmdir.md
+183
docs/posix2018/rmdir.md
···
1
+
#### []{#tag_20_113_01}NAME {#name .mansect}
2
+
3
+
> rmdir - remove directories
4
+
5
+
#### []{#tag_20_113_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `rmdir`` `**`[`**`-p`**`]`**` `*`dir`*`...`
8
+
9
+
#### []{#tag_20_113_03}DESCRIPTION {#description .mansect}
10
+
11
+
> The *rmdir* utility shall remove the directory entry specified by each
12
+
> *dir* operand.
13
+
>
14
+
> For each *dir* operand, the *rmdir* utility shall perform actions
15
+
> equivalent to the [*rmdir*()](../functions/rmdir.html) function called
16
+
> with the *dir* operand as its only argument.
17
+
>
18
+
> Directories shall be processed in the order specified. If a directory
19
+
> and a subdirectory of that directory are specified in a single
20
+
> invocation of the *rmdir* utility, the application shall specify the
21
+
> subdirectory before the parent directory so that the parent directory
22
+
> will be empty when the *rmdir* utility tries to remove it.
23
+
24
+
#### []{#tag_20_113_04}OPTIONS {#options .mansect}
25
+
26
+
> The *rmdir* utility shall conform to XBD [*Utility Syntax
27
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02).
28
+
>
29
+
> The following option shall be supported:
30
+
>
31
+
> **-p**
32
+
> : Remove all directories in a pathname. For each *dir* operand:
33
+
> 1. The directory entry it names shall be removed.
34
+
>
35
+
> 2. If the *dir* operand includes more than one pathname
36
+
> component, effects equivalent to the following command shall
37
+
> occur:
38
+
>
39
+
>
40
+
> rmdir -p $(dirname dir)
41
+
42
+
#### []{#tag_20_113_05}OPERANDS {#operands .mansect}
43
+
44
+
> The following operand shall be supported:
45
+
>
46
+
> *dir*
47
+
> : A pathname of an empty directory to be removed.
48
+
49
+
#### []{#tag_20_113_06}STDIN {#stdin .mansect}
50
+
51
+
> Not used.
52
+
53
+
#### []{#tag_20_113_07}INPUT FILES {#input-files .mansect}
54
+
55
+
> None.
56
+
57
+
#### []{#tag_20_113_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
58
+
59
+
> The following environment variables shall affect the execution of
60
+
> *rmdir*:
61
+
>
62
+
> *LANG*
63
+
> : Provide a default value for the internationalization variables
64
+
> that are unset or null. (See XBD [*Internationalization
65
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
66
+
> precedence of internationalization variables used to determine the
67
+
> values of locale categories.)
68
+
>
69
+
> *LC_ALL*
70
+
> : If set to a non-empty string value, override the values of all the
71
+
> other internationalization variables.
72
+
>
73
+
> *LC_CTYPE*
74
+
> : Determine the locale for the interpretation of sequences of bytes
75
+
> of text data as characters (for example, single-byte as opposed to
76
+
> multi-byte characters in arguments).
77
+
>
78
+
> *LC_MESSAGES*
79
+
> : Determine the locale that should be used to affect the format and
80
+
> contents of diagnostic messages written to standard error.
81
+
>
82
+
> *NLSPATH*
83
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
84
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
85
+
> location of message catalogs for the processing of *LC_MESSAGES.*
86
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
87
+
88
+
#### []{#tag_20_113_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
89
+
90
+
> Default.
91
+
92
+
#### []{#tag_20_113_10}STDOUT {#stdout .mansect}
93
+
94
+
> Not used.
95
+
96
+
#### []{#tag_20_113_11}STDERR {#stderr .mansect}
97
+
98
+
> The standard error shall be used only for diagnostic messages.
99
+
100
+
#### []{#tag_20_113_12}OUTPUT FILES {#output-files .mansect}
101
+
102
+
> None.
103
+
104
+
#### []{#tag_20_113_13}EXTENDED DESCRIPTION {#extended-description .mansect}
105
+
106
+
> None.
107
+
108
+
#### []{#tag_20_113_14}EXIT STATUS {#exit-status .mansect}
109
+
110
+
> The following exit values shall be returned:
111
+
>
112
+
> 0
113
+
> : Each directory entry specified by a *dir* operand was removed
114
+
> successfully.
115
+
>
116
+
> \>0
117
+
> : An error occurred.
118
+
119
+
#### []{#tag_20_113_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
120
+
121
+
> Default.
122
+
123
+
------------------------------------------------------------------------
124
+
125
+
::: box
126
+
*The following sections are informative.*
127
+
:::
128
+
129
+
#### []{#tag_20_113_16}APPLICATION USAGE {#application-usage .mansect}
130
+
131
+
> The definition of an empty directory is one that contains, at most,
132
+
> directory entries for dot and dot-dot.
133
+
134
+
#### []{#tag_20_113_17}EXAMPLES {#examples .mansect}
135
+
136
+
> If a directory **a** in the current directory is empty except it
137
+
> contains a directory **b** and **a/b** is empty except it contains a
138
+
> directory **c**:
139
+
>
140
+
>
141
+
> rmdir -p a/b/c
142
+
>
143
+
> removes all three directories.
144
+
145
+
#### []{#tag_20_113_18}RATIONALE {#rationale .mansect}
146
+
147
+
> On historical System V systems, the **-p** option also caused a
148
+
> message to be written to the standard output. The message indicated
149
+
> whether the whole path was removed or whether part of the path
150
+
> remained for some reason. The STDERR section requires this diagnostic
151
+
> when the entire path specified by a *dir* operand is not removed, but
152
+
> does not allow the status message reporting success to be written as a
153
+
> diagnostic.
154
+
>
155
+
> The *rmdir* utility on System V also included a **-s** option that
156
+
> suppressed the informational message output by the **-p** option. This
157
+
> option has been omitted because the informational message is not
158
+
> specified by this volume of POSIX.1-2017.
159
+
160
+
#### []{#tag_20_113_19}FUTURE DIRECTIONS {#future-directions .mansect}
161
+
162
+
> None.
163
+
164
+
#### []{#tag_20_113_20}SEE ALSO {#see-also .mansect}
165
+
166
+
> [*rm*](../utilities/rm.html#)
167
+
>
168
+
> XBD [*Environment Variables*](../basedefs/V1_chap08.html#tag_08),
169
+
> [*Utility Syntax Guidelines*](../basedefs/V1_chap12.html#tag_12_02)
170
+
>
171
+
> XSH [*remove*](../functions/remove.html#),
172
+
> [*rmdir*](../functions/rmdir.html#tag_16_491),
173
+
> [*unlink*](../functions/unlink.html#tag_16_635)
174
+
175
+
#### []{#tag_20_113_21}CHANGE HISTORY {#change-history .mansect}
176
+
177
+
> First released in Issue 2.
178
+
179
+
#### []{#tag_20_113_22}Issue 6 {#issue-6 .mansect}
180
+
181
+
> The normative text is reworded to avoid use of the term \"must\" for
182
+
> application requirements.
183
+
+175
docs/posix2018/sleep.md
+175
docs/posix2018/sleep.md
···
1
+
#### []{#tag_20_118_01}NAME {#name .mansect}
2
+
3
+
> sleep - suspend execution for an interval
4
+
5
+
#### []{#tag_20_118_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `sleep`` `*`time`*
8
+
9
+
#### []{#tag_20_118_03}DESCRIPTION {#description .mansect}
10
+
11
+
> The *sleep* utility shall suspend execution for at least the integral
12
+
> number of seconds specified by the *time* operand.
13
+
14
+
#### []{#tag_20_118_04}OPTIONS {#options .mansect}
15
+
16
+
> None.
17
+
18
+
#### []{#tag_20_118_05}OPERANDS {#operands .mansect}
19
+
20
+
> The following operand shall be supported:
21
+
>
22
+
> *time*
23
+
> : A non-negative decimal integer specifying the number of seconds
24
+
> for which to suspend execution.
25
+
26
+
#### []{#tag_20_118_06}STDIN {#stdin .mansect}
27
+
28
+
> Not used.
29
+
30
+
#### []{#tag_20_118_07}INPUT FILES {#input-files .mansect}
31
+
32
+
> None.
33
+
34
+
#### []{#tag_20_118_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
35
+
36
+
> The following environment variables shall affect the execution of
37
+
> *sleep*:
38
+
>
39
+
> *LANG*
40
+
> : Provide a default value for the internationalization variables
41
+
> that are unset or null. (See XBD [*Internationalization
42
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
43
+
> precedence of internationalization variables used to determine the
44
+
> values of locale categories.)
45
+
>
46
+
> *LC_ALL*
47
+
> : If set to a non-empty string value, override the values of all the
48
+
> other internationalization variables.
49
+
>
50
+
> *LC_CTYPE*
51
+
> : Determine the locale for the interpretation of sequences of bytes
52
+
> of text data as characters (for example, single-byte as opposed to
53
+
> multi-byte characters in arguments).
54
+
>
55
+
> *LC_MESSAGES*
56
+
> : Determine the locale that should be used to affect the format and
57
+
> contents of diagnostic messages written to standard error.
58
+
>
59
+
> *NLSPATH*
60
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
61
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
62
+
> location of message catalogs for the processing of *LC_MESSAGES.*
63
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
64
+
65
+
#### []{#tag_20_118_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
66
+
67
+
> If the *sleep* utility receives a SIGALRM signal, one of the following
68
+
> actions shall be taken:
69
+
>
70
+
> 1. Terminate normally with a zero exit status.
71
+
>
72
+
> 2. Effectively ignore the signal.
73
+
>
74
+
> 3. Provide the default behavior for signals described in the
75
+
> ASYNCHRONOUS EVENTS section of [*Utility Description
76
+
> Defaults*](../utilities/V3_chap01.html#tag_17_04). This could
77
+
> include terminating with a non-zero exit status.
78
+
>
79
+
> The *sleep* utility shall take the standard action for all other
80
+
> signals.
81
+
82
+
#### []{#tag_20_118_10}STDOUT {#stdout .mansect}
83
+
84
+
> Not used.
85
+
86
+
#### []{#tag_20_118_11}STDERR {#stderr .mansect}
87
+
88
+
> The standard error shall be used only for diagnostic messages.
89
+
90
+
#### []{#tag_20_118_12}OUTPUT FILES {#output-files .mansect}
91
+
92
+
> None.
93
+
94
+
#### []{#tag_20_118_13}EXTENDED DESCRIPTION {#extended-description .mansect}
95
+
96
+
> None.
97
+
98
+
#### []{#tag_20_118_14}EXIT STATUS {#exit-status .mansect}
99
+
100
+
> The following exit values shall be returned:
101
+
>
102
+
> 0
103
+
> : The execution was successfully suspended for at least *time*
104
+
> seconds, or a SIGALRM signal was received. See the ASYNCHRONOUS
105
+
> EVENTS section.
106
+
>
107
+
> \>0
108
+
> : An error occurred.
109
+
110
+
#### []{#tag_20_118_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
111
+
112
+
> Default.
113
+
114
+
------------------------------------------------------------------------
115
+
116
+
::: box
117
+
*The following sections are informative.*
118
+
:::
119
+
120
+
#### []{#tag_20_118_16}APPLICATION USAGE {#application-usage .mansect}
121
+
122
+
> None.
123
+
124
+
#### []{#tag_20_118_17}EXAMPLES {#examples .mansect}
125
+
126
+
> The *sleep* utility can be used to execute a command after a certain
127
+
> amount of time, as in:
128
+
>
129
+
>
130
+
> (sleep 105; command) &
131
+
>
132
+
> or to execute a command every so often, as in:
133
+
>
134
+
>
135
+
> while true
136
+
> do
137
+
> command
138
+
> sleep 37
139
+
> done
140
+
141
+
#### []{#tag_20_118_18}RATIONALE {#rationale .mansect}
142
+
143
+
> The exit status is allowed to be zero when *sleep* is interrupted by
144
+
> the SIGALRM signal because most implementations of this utility rely
145
+
> on the arrival of that signal to notify them that the requested
146
+
> finishing time has been successfully attained. Such implementations
147
+
> thus do not distinguish this situation from the successful completion
148
+
> case. Other implementations are allowed to catch the signal and go
149
+
> back to sleep until the requested time expires or to provide the
150
+
> normal signal termination procedures.
151
+
>
152
+
> As with all other utilities that take integral operands and do not
153
+
> specify subranges of allowed values, *sleep* is required by this
154
+
> volume of POSIX.1-2017 to deal with *time* requests of up to
155
+
> 2147483647 seconds. This may mean that some implementations have to
156
+
> make multiple calls to the delay mechanism of the underlying operating
157
+
> system if its argument range is less than this.
158
+
159
+
#### []{#tag_20_118_19}FUTURE DIRECTIONS {#future-directions .mansect}
160
+
161
+
> None.
162
+
163
+
#### []{#tag_20_118_20}SEE ALSO {#see-also .mansect}
164
+
165
+
> [*wait*](../utilities/wait.html#tag_20_153)
166
+
>
167
+
> XBD [*Environment Variables*](../basedefs/V1_chap08.html#tag_08)
168
+
>
169
+
> XSH [*alarm*](../functions/alarm.html#),
170
+
> [*sleep*](../functions/sleep.html#tag_16_560)
171
+
172
+
#### []{#tag_20_118_21}CHANGE HISTORY {#change-history .mansect}
173
+
174
+
> First released in Issue 2.
175
+
+266
docs/posix2018/split.md
+266
docs/posix2018/split.md
···
1
+
#### []{#tag_20_120_01}NAME {#name .mansect}
2
+
3
+
> split - split a file into pieces
4
+
5
+
#### []{#tag_20_120_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `split`` `**`[`**`-l`` `*`line_count`***`] [`**`-a`` `*`suffix_length`***`] [`***`file`*` `**`[`***`name`***`]]`**\
8
+
> \
9
+
> `split -b`` `*`n`***`[`**`k|m`**`] [`**`-a`` `*`suffix_length`***`] [`***`file`*` `**`[`***`name`***`]]`**\
10
+
11
+
#### []{#tag_20_120_03}DESCRIPTION {#description .mansect}
12
+
13
+
> The *split* utility shall read an input file and write zero or more
14
+
> output files. The default size of each output file shall be 1000
15
+
> lines. The size of the output files can be modified by specification
16
+
> of the **-b** or **-l** options. Each output file shall be created
17
+
> with a unique suffix. The suffix shall consist of exactly
18
+
> *suffix_length* lowercase letters from the POSIX locale. The letters
19
+
> of the suffix shall be used as if they were a base-26 digit system,
20
+
> with the first suffix to be created consisting of all `'a'`
21
+
> characters, the second with a `'b'` replacing the last `'a'`, and so
22
+
> on, until a name of all `'z'` characters is created. By default, the
23
+
> names of the output files shall be `'x'`, followed by a two-character
24
+
> suffix from the character set as described above, starting with
25
+
> `"aa"`, `"ab"`, `"ac"`, and so on, and continuing until the suffix
26
+
> `"zz"`, for a maximum of 676 files.
27
+
>
28
+
> If the number of files required exceeds the maximum allowed by the
29
+
> suffix length provided, such that the last allowable file would be
30
+
> larger than the requested size, the *split* utility shall fail after
31
+
> creating the last file with a valid suffix; *split* shall not delete
32
+
> the files it created with valid suffixes. If the file limit is not
33
+
> exceeded, the last file created shall contain the remainder of the
34
+
> input file, and may be smaller than the requested size. If the input
35
+
> is an empty file, no output file shall be created and this shall not
36
+
> be considered to be an error.
37
+
38
+
#### []{#tag_20_120_04}OPTIONS {#options .mansect}
39
+
40
+
> The *split* utility shall conform to XBD [*Utility Syntax
41
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02).
42
+
>
43
+
> The following options shall be supported:
44
+
>
45
+
> **-a ** *suffix_length*
46
+
> : Use *suffix_length* letters to form the suffix portion of the
47
+
> filenames of the split file. If **-a** is not specified, the
48
+
> default suffix length shall be two. If the sum of the *name*
49
+
> operand and the *suffix_length* option-argument would create a
50
+
> filename exceeding {NAME_MAX} bytes, an error shall result;
51
+
> *split* shall exit with a diagnostic message and no files shall be
52
+
> created.
53
+
>
54
+
> **-b ** *n*
55
+
> : Split a file into pieces *n* bytes in size.
56
+
>
57
+
> **-b ** *n***k**
58
+
> : Split a file into pieces *n*\*1024 bytes in size.
59
+
>
60
+
> **-b ** *n***m**
61
+
> : Split a file into pieces *n*\*1048576 bytes in size.
62
+
>
63
+
> **-l ** *line_count*
64
+
> : Specify the number of lines in each resulting file piece. The
65
+
> *line_count* argument is an unsigned decimal integer. The default
66
+
> is 1000. If the input does not end with a \<newline\>, the partial
67
+
> line shall be included in the last output file.
68
+
69
+
#### []{#tag_20_120_05}OPERANDS {#operands .mansect}
70
+
71
+
> The following operands shall be supported:
72
+
>
73
+
> *file*
74
+
> : The pathname of the ordinary file to be split. If no input file is
75
+
> given or *file* is `'-'`, the standard input shall be used.
76
+
>
77
+
> *name*
78
+
> : The prefix to be used for each of the files resulting from the
79
+
> split operation. If no *name* argument is given, `'x'` shall be
80
+
> used as the prefix of the output files. The combined length of the
81
+
> basename of *prefix* and *suffix_length* cannot exceed {NAME_MAX}
82
+
> bytes. See the OPTIONS section.
83
+
84
+
#### []{#tag_20_120_06}STDIN {#stdin .mansect}
85
+
86
+
> See the INPUT FILES section.
87
+
88
+
#### []{#tag_20_120_07}INPUT FILES {#input-files .mansect}
89
+
90
+
> Any file can be used as input.
91
+
92
+
#### []{#tag_20_120_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
93
+
94
+
> The following environment variables shall affect the execution of
95
+
> *split*:
96
+
>
97
+
> *LANG*
98
+
> : Provide a default value for the internationalization variables
99
+
> that are unset or null. (See XBD [*Internationalization
100
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
101
+
> precedence of internationalization variables used to determine the
102
+
> values of locale categories.)
103
+
>
104
+
> *LC_ALL*
105
+
> : If set to a non-empty string value, override the values of all the
106
+
> other internationalization variables.
107
+
>
108
+
> *LC_CTYPE*
109
+
> : Determine the locale for the interpretation of sequences of bytes
110
+
> of text data as characters (for example, single-byte as opposed to
111
+
> multi-byte characters in arguments and input files).
112
+
>
113
+
> *LC_MESSAGES*
114
+
> : Determine the locale that should be used to affect the format and
115
+
> contents of diagnostic messages written to standard error.
116
+
>
117
+
> *NLSPATH*
118
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
119
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
120
+
> location of message catalogs for the processing of *LC_MESSAGES.*
121
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
122
+
123
+
#### []{#tag_20_120_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
124
+
125
+
> Default.
126
+
127
+
#### []{#tag_20_120_10}STDOUT {#stdout .mansect}
128
+
129
+
> Not used.
130
+
131
+
#### []{#tag_20_120_11}STDERR {#stderr .mansect}
132
+
133
+
> The standard error shall be used only for diagnostic messages.
134
+
135
+
#### []{#tag_20_120_12}OUTPUT FILES {#output-files .mansect}
136
+
137
+
> The output files contain portions of the original input file;
138
+
> otherwise, unchanged.
139
+
140
+
#### []{#tag_20_120_13}EXTENDED DESCRIPTION {#extended-description .mansect}
141
+
142
+
> None.
143
+
144
+
#### []{#tag_20_120_14}EXIT STATUS {#exit-status .mansect}
145
+
146
+
> The following exit values shall be returned:
147
+
>
148
+
> 0
149
+
> : Successful completion.
150
+
>
151
+
> \>0
152
+
> : An error occurred.
153
+
154
+
#### []{#tag_20_120_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
155
+
156
+
> Default.
157
+
158
+
------------------------------------------------------------------------
159
+
160
+
::: box
161
+
*The following sections are informative.*
162
+
:::
163
+
164
+
#### []{#tag_20_120_16}APPLICATION USAGE {#application-usage .mansect}
165
+
166
+
> None.
167
+
168
+
#### []{#tag_20_120_17}EXAMPLES {#examples .mansect}
169
+
170
+
> In the following examples **foo** is a text file that contains 5000
171
+
> lines.
172
+
>
173
+
> 1. Create five files, **xaa**, **xab**, **xac**, **xad**, and
174
+
> **xae**:
175
+
>
176
+
>
177
+
> split foo
178
+
>
179
+
> 2. Create five files, but the suffixed portion of the created files
180
+
> consists of three letters, **xaaa**, **xaab**, **xaac**, **xaad**,
181
+
> and **xaae**:
182
+
>
183
+
>
184
+
> split -a 3 foo
185
+
>
186
+
> 3. Create three files with four-letter suffixes and a supplied
187
+
> prefix, **bar_aaaa**, **bar_aaab**, and **bar_aaac**:
188
+
>
189
+
>
190
+
> split -a 4 -l 2000 foo bar_
191
+
>
192
+
> 4. Create as many files as are necessary to contain at most 20\*1024
193
+
> bytes, each with the default prefix of **x** and a five-letter
194
+
> suffix:
195
+
>
196
+
>
197
+
> split -a 5 -b 20k foo
198
+
199
+
#### []{#tag_20_120_18}RATIONALE {#rationale .mansect}
200
+
201
+
> The **-b** option was added to provide a mechanism for splitting files
202
+
> other than by lines. While most uses of the **-b** option are for
203
+
> transmitting files over networks, some believed it would have
204
+
> additional uses.
205
+
>
206
+
> The **-a** option was added to overcome the limitation of being able
207
+
> to create only 676 files.
208
+
>
209
+
> Consideration was given to deleting this utility, using the rationale
210
+
> that the functionality provided by this utility is available via the
211
+
> [*csplit*](../utilities/csplit.html) utility (see
212
+
> [*csplit*](../utilities/csplit.html#)). Upon reconsideration of the
213
+
> purpose of the User Portability Utilities option, it was decided to
214
+
> retain both this utility and the [*csplit*](../utilities/csplit.html)
215
+
> utility because users use both utilities and have historical
216
+
> expectations of their behavior. Furthermore, the splitting on byte
217
+
> boundaries in *split* cannot be duplicated with the historical
218
+
> [*csplit*](../utilities/csplit.html).
219
+
>
220
+
> The text \" *split* shall not delete the files it created with valid
221
+
> suffixes\" would normally be assumed, but since the related utility,
222
+
> [*csplit*](../utilities/csplit.html), does delete files under some
223
+
> circumstances, the historical behavior of *split* is made explicit to
224
+
> avoid misinterpretation.
225
+
>
226
+
> Earlier versions of this standard allowed a **-** *line_count* option.
227
+
> This form is no longer specified by POSIX.1-2017 but may be present in
228
+
> some implementations.
229
+
230
+
#### []{#tag_20_120_19}FUTURE DIRECTIONS {#future-directions .mansect}
231
+
232
+
> None.
233
+
234
+
#### []{#tag_20_120_20}SEE ALSO {#see-also .mansect}
235
+
236
+
> [*csplit*](../utilities/csplit.html#)
237
+
>
238
+
> XBD [*Environment Variables*](../basedefs/V1_chap08.html#tag_08),
239
+
> [*Utility Syntax Guidelines*](../basedefs/V1_chap12.html#tag_12_02)
240
+
241
+
#### []{#tag_20_120_21}CHANGE HISTORY {#change-history .mansect}
242
+
243
+
> First released in Issue 2.
244
+
245
+
#### []{#tag_20_120_22}Issue 6 {#issue-6 .mansect}
246
+
247
+
> This utility is marked as part of the User Portability Utilities
248
+
> option.
249
+
>
250
+
> The APPLICATION USAGE section is added.
251
+
>
252
+
> The obsolescent SYNOPSIS is removed.
253
+
254
+
#### []{#tag_20_120_23}Issue 7 {#issue-7 .mansect}
255
+
256
+
> Austin Group Interpretation 1003.1-2001 #027 is applied.
257
+
>
258
+
> The *split* utility is moved from the User Portability Utilities
259
+
> option to the Base. User Portability Utilities is now an option for
260
+
> interactive utilities.
261
+
>
262
+
> SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.
263
+
>
264
+
> POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0188 \[731\] is
265
+
> applied.
266
+
+298
docs/posix2018/tail.md
+298
docs/posix2018/tail.md
···
1
+
#### []{#tag_20_125_01}NAME {#name .mansect}
2
+
3
+
> tail - copy the last part of a file
4
+
5
+
#### []{#tag_20_125_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `tail`` `**`[`**`-f`**`] [`**`-c`` `*`number`*`|-n`` `*`number`***`] [`***`file`***`]`**
8
+
9
+
#### []{#tag_20_125_03}DESCRIPTION {#description .mansect}
10
+
11
+
> The *tail* utility shall copy its input file to the standard output
12
+
> beginning at a designated place.
13
+
>
14
+
> Copying shall begin at the point in the file indicated by the **-c**
15
+
> *number* or **-n** *number* options. The option-argument *number*
16
+
> shall be counted in units of lines or bytes, according to the options
17
+
> **-n** and **-c**. Both line and byte counts start from 1.
18
+
>
19
+
> Tails relative to the end of the file may be saved in an internal
20
+
> buffer, and thus may be limited in length. Such a buffer, if any,
21
+
> shall be no smaller than {LINE_MAX}\*10 bytes.
22
+
23
+
#### []{#tag_20_125_04}OPTIONS {#options .mansect}
24
+
25
+
> The *tail* utility shall conform to XBD [*Utility Syntax
26
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02) , except that `'+'`
27
+
> may be recognized as an option delimiter as well as `'-'`.
28
+
>
29
+
> The following options shall be supported:
30
+
>
31
+
> **-c ** *number*
32
+
>
33
+
> : The application shall ensure that the *number* option-argument is
34
+
> a decimal integer, optionally including a sign. The sign shall
35
+
> affect the location in the file, measured in bytes, to begin the
36
+
> copying:
37
+
>
38
+
> **Sign** **Copying Starts**
39
+
> ---------- ----------------------------------------
40
+
> \+ Relative to the beginning of the file.
41
+
> \- Relative to the end of the file.
42
+
> *none* Relative to the end of the file.
43
+
>
44
+
> The application shall ensure that if the sign of the *number*
45
+
> option-argument is `'+'`, the *number* option-argument is a
46
+
> non-zero decimal integer.
47
+
>
48
+
> The origin for counting shall be 1; that is, **-c** +1 represents
49
+
> the first byte of the file, **-c** -1 the last.
50
+
>
51
+
> **-f**
52
+
> : If the input file is a regular file or if the *file* operand
53
+
> specifies a FIFO, do not terminate after the last line of the
54
+
> input file has been copied, but read and copy further bytes from
55
+
> the input file when they become available. If no *file* operand is
56
+
> specified and standard input is a pipe or FIFO, the **-f** option
57
+
> shall be ignored. If the input file is not a FIFO, pipe, or
58
+
> regular file, it is unspecified whether or not the **-f** option
59
+
> shall be ignored.
60
+
>
61
+
> **-n ** *number*
62
+
> : This option shall be equivalent to **-c** *number*, except the
63
+
> starting location in the file shall be measured in lines instead
64
+
> of bytes. The origin for counting shall be 1; that is, **-n** +1
65
+
> represents the first line of the file, **-n** -1 the last.
66
+
>
67
+
> If neither **-c** nor **-n** is specified, **-n** 10 shall be assumed.
68
+
69
+
#### []{#tag_20_125_05}OPERANDS {#operands .mansect}
70
+
71
+
> The following operand shall be supported:
72
+
>
73
+
> *file*
74
+
> : A pathname of an input file. If no *file* operand is specified,
75
+
> the standard input shall be used.
76
+
77
+
#### []{#tag_20_125_06}STDIN {#stdin .mansect}
78
+
79
+
> The standard input shall be used if no *file* operand is specified,
80
+
> and shall be used if the *file* operand is `'-'` and the
81
+
> implementation treats the `'-'` as meaning standard input. Otherwise,
82
+
> the standard input shall not be used. See the INPUT FILES section.
83
+
84
+
#### []{#tag_20_125_07}INPUT FILES {#input-files .mansect}
85
+
86
+
> If the **-c** option is specified, the input file can contain
87
+
> arbitrary data; otherwise, the input file shall be a text file.
88
+
89
+
#### []{#tag_20_125_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
90
+
91
+
> The following environment variables shall affect the execution of
92
+
> *tail*:
93
+
>
94
+
> *LANG*
95
+
> : Provide a default value for the internationalization variables
96
+
> that are unset or null. (See XBD [*Internationalization
97
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
98
+
> precedence of internationalization variables used to determine the
99
+
> values of locale categories.)
100
+
>
101
+
> *LC_ALL*
102
+
> : If set to a non-empty string value, override the values of all the
103
+
> other internationalization variables.
104
+
>
105
+
> *LC_CTYPE*
106
+
> : Determine the locale for the interpretation of sequences of bytes
107
+
> of text data as characters (for example, single-byte as opposed to
108
+
> multi-byte characters in arguments and input files).
109
+
>
110
+
> *LC_MESSAGES*
111
+
> : Determine the locale that should be used to affect the format and
112
+
> contents of diagnostic messages written to standard error.
113
+
>
114
+
> *NLSPATH*
115
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
116
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
117
+
> location of message catalogs for the processing of *LC_MESSAGES.*
118
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
119
+
120
+
#### []{#tag_20_125_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
121
+
122
+
> Default.
123
+
124
+
#### []{#tag_20_125_10}STDOUT {#stdout .mansect}
125
+
126
+
> The designated portion of the input file shall be written to standard
127
+
> output.
128
+
129
+
#### []{#tag_20_125_11}STDERR {#stderr .mansect}
130
+
131
+
> The standard error shall be used only for diagnostic messages.
132
+
133
+
#### []{#tag_20_125_12}OUTPUT FILES {#output-files .mansect}
134
+
135
+
> None.
136
+
137
+
#### []{#tag_20_125_13}EXTENDED DESCRIPTION {#extended-description .mansect}
138
+
139
+
> None.
140
+
141
+
#### []{#tag_20_125_14}EXIT STATUS {#exit-status .mansect}
142
+
143
+
> The following exit values shall be returned:
144
+
>
145
+
> 0
146
+
> : Successful completion.
147
+
>
148
+
> \>0
149
+
> : An error occurred.
150
+
151
+
#### []{#tag_20_125_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
152
+
153
+
> Default.
154
+
155
+
------------------------------------------------------------------------
156
+
157
+
::: box
158
+
*The following sections are informative.*
159
+
:::
160
+
161
+
#### []{#tag_20_125_16}APPLICATION USAGE {#application-usage .mansect}
162
+
163
+
> The **-c** option should be used with caution when the input is a text
164
+
> file containing multi-byte characters; it may produce output that does
165
+
> not start on a character boundary.
166
+
>
167
+
> Although the input file to *tail* can be any type, the results might
168
+
> not be what would be expected on some character special device files
169
+
> or on file types not described by the System Interfaces volume of
170
+
> POSIX.1-2017. Since this volume of POSIX.1-2017 does not specify the
171
+
> block size used when doing input, *tail* need not read all of the data
172
+
> from devices that only perform block transfers.
173
+
>
174
+
> When using *tail* to process pathnames, and the **-c** option is not
175
+
> specified, it is recommended that LC_ALL, or at least LC_CTYPE and
176
+
> LC_COLLATE, are set to POSIX or C in the environment, since pathnames
177
+
> can contain byte sequences that do not form valid characters in some
178
+
> locales, in which case the utility\'s behavior would be undefined. In
179
+
> the POSIX locale each byte is a valid single-byte character, and
180
+
> therefore this problem is avoided.
181
+
182
+
#### []{#tag_20_125_17}EXAMPLES {#examples .mansect}
183
+
184
+
> The **-f** option can be used to monitor the growth of a file that is
185
+
> being written by some other process. For example, the command:
186
+
>
187
+
>
188
+
> tail -f fred
189
+
>
190
+
> prints the last ten lines of the file **fred**, followed by any lines
191
+
> that are appended to **fred** between the time *tail* is initiated and
192
+
> killed. As another example, the command:
193
+
>
194
+
>
195
+
> tail -f -c 15 fred
196
+
>
197
+
> prints the last 15 bytes of the file **fred**, followed by any bytes
198
+
> that are appended to **fred** between the time *tail* is initiated and
199
+
> killed.
200
+
201
+
#### []{#tag_20_125_18}RATIONALE {#rationale .mansect}
202
+
203
+
> This version of *tail* was created to allow conformance to the Utility
204
+
> Syntax Guidelines. The historical **-b** option was omitted because of
205
+
> the general non-portability of block-sized units of text. The **-c**
206
+
> option historically meant \"characters\", but this volume of
207
+
> POSIX.1-2017 indicates that it means \"bytes\". This was selected to
208
+
> allow reasonable implementations when multi-byte characters are
209
+
> possible; it was not named **-b** to avoid confusion with the
210
+
> historical **-b**.
211
+
>
212
+
> The origin of counting both lines and bytes is 1, matching all
213
+
> widespread historical implementations. Hence *tail* **-n** +0 is not
214
+
> conforming usage because it attempts to output line zero; but note
215
+
> that *tail* **-n** 0 does conform, and outputs nothing.
216
+
>
217
+
> Earlier versions of this standard allowed the following forms in the
218
+
> SYNOPSIS:
219
+
>
220
+
>
221
+
> tail -[number][b|c|l][f] [file]tail +[number][b|c|l][f] [file]
222
+
>
223
+
> These forms are no longer specified by POSIX.1-2017, but may be
224
+
> present in some implementations.
225
+
>
226
+
> The restriction on the internal buffer is a compromise between the
227
+
> historical System V implementation of 4096 bytes and the BSD 32768
228
+
> bytes.
229
+
>
230
+
> The **-f** option has been implemented as a loop that sleeps for 1
231
+
> second and copies any bytes that are available. This is sufficient,
232
+
> but if more efficient methods of determining when new data are
233
+
> available are developed, implementations are encouraged to use them.
234
+
>
235
+
> Historical documentation indicates that *tail* ignores the **-f**
236
+
> option if the input file is a pipe (pipe and FIFO on systems that
237
+
> support FIFOs). On BSD-based systems, this has been true; on System
238
+
> V-based systems, this was true when input was taken from standard
239
+
> input, but it did not ignore the **-f** flag if a FIFO was named as
240
+
> the *file* operand. Since the **-f** option is not useful on pipes and
241
+
> all historical implementations ignore **-f** if no *file* operand is
242
+
> specified and standard input is a pipe, this volume of POSIX.1-2017
243
+
> requires this behavior. However, since the **-f** option is useful on
244
+
> a FIFO, this volume of POSIX.1-2017 also requires that if a FIFO is
245
+
> named, the **-f** option shall not be ignored. Earlier versions of
246
+
> this standard did not state any requirement for the case where no
247
+
> *file* operand is specified and standard input is a FIFO. The standard
248
+
> has been updated to reflect current practice which is to treat this
249
+
> case the same as a pipe on standard input. Although historical
250
+
> behavior does not ignore the **-f** option for other file types, this
251
+
> is unspecified so that implementations are allowed to ignore the
252
+
> **-f** option if it is known that the file cannot be extended.
253
+
254
+
#### []{#tag_20_125_19}FUTURE DIRECTIONS {#future-directions .mansect}
255
+
256
+
> None.
257
+
258
+
#### []{#tag_20_125_20}SEE ALSO {#see-also .mansect}
259
+
260
+
> [*head*](../utilities/head.html#)
261
+
>
262
+
> XBD [*Environment Variables*](../basedefs/V1_chap08.html#tag_08),
263
+
> [*Utility Syntax Guidelines*](../basedefs/V1_chap12.html#tag_12_02)
264
+
265
+
#### []{#tag_20_125_21}CHANGE HISTORY {#change-history .mansect}
266
+
267
+
> First released in Issue 2.
268
+
269
+
#### []{#tag_20_125_22}Issue 6 {#issue-6 .mansect}
270
+
271
+
> The obsolescent SYNOPSIS lines and associated text are removed.
272
+
>
273
+
> The normative text is reworded to avoid use of the term \"must\" for
274
+
> application requirements.
275
+
276
+
#### []{#tag_20_125_23}Issue 7 {#issue-7 .mansect}
277
+
278
+
> Austin Group Interpretation 1003.1-2001 #027 is applied, clarifying
279
+
> that `'+'` may be recognized as an option delimiter in the OPTIONS
280
+
> section.
281
+
>
282
+
> Austin Group Interpretation 1003.1-2001 #092 is applied.
283
+
>
284
+
> Austin Group Interpretation 1003.1-2001 #100 is applied, adding the
285
+
> requirement on applications that if the sign of the option-argument
286
+
> *number* is `'+'`, the *number* option-argument is a non-zero decimal
287
+
> integer.
288
+
>
289
+
> SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.
290
+
>
291
+
> SD5-XCU-ERN-114 is applied, updating the OPTIONS section (the **-f**
292
+
> option).
293
+
>
294
+
> SD5-XCU-ERN-149 is applied.
295
+
>
296
+
> POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0190 \[663\] is
297
+
> applied.
298
+
+297
docs/posix2018/time.md
+297
docs/posix2018/time.md
···
1
+
#### []{#tag_20_129_01}NAME {#name .mansect}
2
+
3
+
> time - time a simple command
4
+
5
+
#### []{#tag_20_129_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `time`` `**`[`**`-p`**`]`**` `*`utility`*` `**`[`***`argument`*`...`**`]`**
8
+
9
+
#### []{#tag_20_129_03}DESCRIPTION {#description .mansect}
10
+
11
+
> The *time* utility shall invoke the utility named by the *utility*
12
+
> operand with arguments supplied as the *argument* operands and write a
13
+
> message to standard error that lists timing statistics for the
14
+
> utility. The message shall include the following information:
15
+
>
16
+
> - The elapsed (real) time between invocation of *utility* and its
17
+
> termination.
18
+
>
19
+
> - The User CPU time, equivalent to the sum of the *tms_utime* and
20
+
> *tms_cutime* fields returned by the
21
+
> [*times*()](../functions/times.html) function defined in the System
22
+
> Interfaces volume of POSIX.1-2017 for the process in which *utility*
23
+
> is executed.
24
+
>
25
+
> - The System CPU time, equivalent to the sum of the *tms_stime* and
26
+
> *tms_cstime* fields returned by the
27
+
> [*times*()](../functions/times.html) function for the process in
28
+
> which *utility* is executed.
29
+
>
30
+
> The precision of the timing shall be no less than the granularity
31
+
> defined for the size of the clock tick unit on the system, but the
32
+
> results shall be reported in terms of standard time units (for
33
+
> example, 0.02 seconds, 00:00:00.02, 1m33.75s, 365.21 seconds), not
34
+
> numbers of clock ticks.
35
+
>
36
+
> When *time* is used as part of a pipeline, the times reported are
37
+
> unspecified, except when it is the sole command within a grouping
38
+
> command (see [*Grouping
39
+
> Commands*](../utilities/V3_chap02.html#tag_18_09_04_01)) in that
40
+
> pipeline. For example, the commands on the left are unspecified; those
41
+
> on the right report on utilities **a** and **c**, respectively:
42
+
>
43
+
>
44
+
> time a | b | c { time a; } | b | c
45
+
> a | b | time c a | b | (time c)
46
+
47
+
#### []{#tag_20_129_04}OPTIONS {#options .mansect}
48
+
49
+
> The *time* utility shall conform to XBD [*Utility Syntax
50
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02) .
51
+
>
52
+
> The following option shall be supported:
53
+
>
54
+
> **-p**
55
+
> : Write the timing output to standard error in the format shown in
56
+
> the STDERR section.
57
+
58
+
#### []{#tag_20_129_05}OPERANDS {#operands .mansect}
59
+
60
+
> The following operands shall be supported:
61
+
>
62
+
> *utility*
63
+
> : The name of a utility that is to be invoked. If the *utility*
64
+
> operand names any of the special built-in utilities in [*Special
65
+
> Built-In Utilities*](../utilities/V3_chap02.html#tag_18_14), the
66
+
> results are undefined.
67
+
>
68
+
> *argument*
69
+
> : Any string to be supplied as an argument when invoking the utility
70
+
> named by the *utility* operand.
71
+
72
+
#### []{#tag_20_129_06}STDIN {#stdin .mansect}
73
+
74
+
> Not used.
75
+
76
+
#### []{#tag_20_129_07}INPUT FILES {#input-files .mansect}
77
+
78
+
> None.
79
+
80
+
#### []{#tag_20_129_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
81
+
82
+
> The following environment variables shall affect the execution of
83
+
> *time*:
84
+
>
85
+
> *LANG*
86
+
> : Provide a default value for the internationalization variables
87
+
> that are unset or null. (See XBD [*Internationalization
88
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
89
+
> precedence of internationalization variables used to determine the
90
+
> values of locale categories.)
91
+
>
92
+
> *LC_ALL*
93
+
> : If set to a non-empty string value, override the values of all the
94
+
> other internationalization variables.
95
+
>
96
+
> *LC_CTYPE*
97
+
> : Determine the locale for the interpretation of sequences of bytes
98
+
> of text data as characters (for example, single-byte as opposed to
99
+
> multi-byte characters in arguments).
100
+
>
101
+
> *LC_MESSAGES*
102
+
> : Determine the locale that should be used to affect the format and
103
+
> contents of diagnostic and informative messages written to
104
+
> standard error.
105
+
>
106
+
> *LC_NUMERIC*
107
+
> : Determine the locale for numeric formatting.
108
+
>
109
+
> *NLSPATH*
110
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
111
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
112
+
> location of message catalogs for the processing of *LC_MESSAGES.*
113
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
114
+
>
115
+
> *PATH*
116
+
> : Determine the search path that shall be used to locate the utility
117
+
> to be invoked; see XBD [*Environment
118
+
> Variables*](../basedefs/V1_chap08.html#tag_08).
119
+
120
+
#### []{#tag_20_129_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
121
+
122
+
> Default.
123
+
124
+
#### []{#tag_20_129_10}STDOUT {#stdout .mansect}
125
+
126
+
> Not used.
127
+
128
+
#### []{#tag_20_129_11}STDERR {#stderr .mansect}
129
+
130
+
> If the *utility* utility is invoked, the standard error shall be used
131
+
> to write the timing statistics and may be used to write a diagnostic
132
+
> message if the utility terminates abnormally; otherwise, the standard
133
+
> error shall be used to write diagnostic messages and may also be used
134
+
> to write the timing statistics.
135
+
>
136
+
> If **-p** is specified, the following format shall be used for the
137
+
> timing statistics in the POSIX locale:
138
+
>
139
+
>
140
+
> "real %f\nuser %f\nsys %f\n", <real seconds>, <user seconds>,
141
+
> <system seconds>
142
+
>
143
+
> where each floating-point number shall be expressed in seconds. The
144
+
> precision used may be less than the default six digits of `%f`, but
145
+
> shall be sufficiently precise to accommodate the size of the clock
146
+
> tick on the system (for example, if there were 60 clock ticks per
147
+
> second, at least two digits shall follow the radix character). The
148
+
> number of digits following the radix character shall be no less than
149
+
> one, even if this always results in a trailing zero. The
150
+
> implementation may append white space and additional information
151
+
> following the format shown here. The implementation may also prepend a
152
+
> single empty line before the format shown here.
153
+
154
+
#### []{#tag_20_129_12}OUTPUT FILES {#output-files .mansect}
155
+
156
+
> None.
157
+
158
+
#### []{#tag_20_129_13}EXTENDED DESCRIPTION {#extended-description .mansect}
159
+
160
+
> None.
161
+
162
+
#### []{#tag_20_129_14}EXIT STATUS {#exit-status .mansect}
163
+
164
+
> If the *utility* utility is invoked, the exit status of *time* shall
165
+
> be the exit status of *utility*; otherwise, the *time* utility shall
166
+
> exit with one of the following values:
167
+
>
168
+
> 1-125
169
+
> : An error occurred in the *time* utility.
170
+
>
171
+
> 126
172
+
> : The utility specified by *utility* was found but could not be
173
+
> invoked.
174
+
>
175
+
> 127
176
+
> : The utility specified by *utility* could not be found.
177
+
178
+
#### []{#tag_20_129_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
179
+
180
+
> Default.
181
+
182
+
------------------------------------------------------------------------
183
+
184
+
::: box
185
+
*The following sections are informative.*
186
+
:::
187
+
188
+
#### []{#tag_20_129_16}APPLICATION USAGE {#application-usage .mansect}
189
+
190
+
> The [*command*](../utilities/command.html),
191
+
> [*env*](../utilities/env.html), [*nice*](../utilities/nice.html),
192
+
> [*nohup*](../utilities/nohup.html), *time*, and
193
+
> [*xargs*](../utilities/xargs.html) utilities have been specified to
194
+
> use exit code 127 if an error occurs so that applications can
195
+
> distinguish \"failure to find a utility\" from \"invoked utility
196
+
> exited with an error indication\". The value 127 was chosen because it
197
+
> is not commonly used for other meanings; most utilities use small
198
+
> values for \"normal error conditions\" and the values above 128 can be
199
+
> confused with termination due to receipt of a signal. The value 126
200
+
> was chosen in a similar manner to indicate that the utility could be
201
+
> found, but not invoked. Some scripts produce meaningful error messages
202
+
> differentiating the 126 and 127 cases. The distinction between exit
203
+
> codes 126 and 127 is based on KornShell practice that uses 127 when
204
+
> all attempts to *exec* the utility fail with \[ENOENT\], and uses 126
205
+
> when any attempt to *exec* the utility fails for any other reason.
206
+
207
+
#### []{#tag_20_129_17}EXAMPLES {#examples .mansect}
208
+
209
+
> It is frequently desirable to apply *time* to pipelines or lists of
210
+
> commands. This can be done by placing pipelines and command lists in a
211
+
> single file; this file can then be invoked as a utility, and the
212
+
> *time* applies to everything in the file.
213
+
>
214
+
> Alternatively, the following command can be used to apply *time* to a
215
+
> complex command:
216
+
>
217
+
>
218
+
> time sh -c 'complex-command-line'
219
+
220
+
#### []{#tag_20_129_18}RATIONALE {#rationale .mansect}
221
+
222
+
> When the *time* utility was originally proposed to be included in the
223
+
> ISO POSIX-2:1993 standard, questions were raised about its suitability
224
+
> for inclusion on the grounds that it was not useful for conforming
225
+
> applications, specifically:
226
+
>
227
+
> - The underlying CPU definitions from the System Interfaces volume of
228
+
> POSIX.1-2017 are vague, so the numeric output could not be compared
229
+
> accurately between systems or even between invocations.
230
+
>
231
+
> - The creation of portable benchmark programs was outside the scope
232
+
> this volume of POSIX.1-2017.
233
+
>
234
+
> However, *time* does fit in the scope of user portability. Human
235
+
> judgement can be applied to the analysis of the output, and it could
236
+
> be very useful in hands-on debugging of applications or in providing
237
+
> subjective measures of system performance. Hence it has been included
238
+
> in this volume of POSIX.1-2017.
239
+
>
240
+
> The default output format has been left unspecified because historical
241
+
> implementations differ greatly in their style of depicting this
242
+
> numeric output. The **-p** option was invented to provide scripts with
243
+
> a common means of obtaining this information.
244
+
>
245
+
> In the KornShell, *time* is a shell reserved word that can be used to
246
+
> time an entire pipeline, rather than just a simple command. The POSIX
247
+
> definition has been worded to allow this implementation. Consideration
248
+
> was given to invalidating this approach because of the historical
249
+
> model from the C shell and System V shell. However, since the System V
250
+
> *time* utility historically has not produced accurate results in
251
+
> pipeline timing (because the constituent processes are not all owned
252
+
> by the same parent process, as allowed by POSIX), it did not seem
253
+
> worthwhile to break historical KornShell usage.
254
+
>
255
+
> The term *utility* is used, rather than *command*, to highlight the
256
+
> fact that shell compound commands, pipelines, special built-ins, and
257
+
> so on, cannot be used directly. However, *utility* includes user
258
+
> application programs and shell scripts, not just the standard
259
+
> utilities.
260
+
261
+
#### []{#tag_20_129_19}FUTURE DIRECTIONS {#future-directions .mansect}
262
+
263
+
> None.
264
+
265
+
#### []{#tag_20_129_20}SEE ALSO {#see-also .mansect}
266
+
267
+
> [*Shell Command Language*](../utilities/V3_chap02.html#tag_18),
268
+
> [*sh*](../utilities/sh.html#)
269
+
>
270
+
> XBD [*Environment Variables*](../basedefs/V1_chap08.html#tag_08),
271
+
> [*Utility Syntax Guidelines*](../basedefs/V1_chap12.html#tag_12_02)
272
+
>
273
+
> XSH [*times*](../functions/times.html#tag_16_617)
274
+
275
+
#### []{#tag_20_129_21}CHANGE HISTORY {#change-history .mansect}
276
+
277
+
> First released in Issue 2.
278
+
279
+
#### []{#tag_20_129_22}Issue 6 {#issue-6 .mansect}
280
+
281
+
> This utility is marked as part of the User Portability Utilities
282
+
> option.
283
+
284
+
#### []{#tag_20_129_23}Issue 7 {#issue-7 .mansect}
285
+
286
+
> The *time* utility is moved from the User Portability Utilities option
287
+
> to the Base. User Portability Utilities is now an option for
288
+
> interactive utilities.
289
+
>
290
+
> SD5-XCU-ERN-115 is applied, updating the example in the DESCRIPTION.
291
+
>
292
+
> POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0144 \[266\] is
293
+
> applied.
294
+
>
295
+
> POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0194 \[723\] is
296
+
> applied.
297
+
+461
docs/posix2018/touch.md
+461
docs/posix2018/touch.md
···
1
+
#### []{#tag_20_130_01}NAME {#name .mansect}
2
+
3
+
> touch - change file access and modification times
4
+
5
+
#### []{#tag_20_130_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `touch`` `**`[`**`-acm`**`] [`**`-r`` `*`ref_file`*`|-t`` `*`time`*`|-d`` `*`date_time`***`]`**` `*`file`*`...`
8
+
9
+
#### []{#tag_20_130_03}DESCRIPTION {#description .mansect}
10
+
11
+
> The *touch* utility shall change the last data modification
12
+
> timestamps, the last data access timestamps, or both.
13
+
>
14
+
> The time used can be specified by the **-t** *time* option-argument,
15
+
> the corresponding *time* fields of the file referenced by the **-r**
16
+
> *ref_file* option-argument, or the **-d** *date_time* option-argument,
17
+
> as specified in the following sections. If none of these are
18
+
> specified, *touch* shall use the current time.
19
+
>
20
+
> For each *file* operand, *touch* shall perform actions equivalent to
21
+
> the following functions defined in the System Interfaces volume of
22
+
> POSIX.1-2017:
23
+
>
24
+
> 1. If *file* does not exist:
25
+
>
26
+
> a. The [*creat*()](../functions/creat.html) function is called
27
+
> with the following arguments:
28
+
>
29
+
> - The *file* operand is used as the *path* argument.
30
+
>
31
+
> - The value of the bitwise-inclusive OR of S_IRUSR, S_IWUSR,
32
+
> S_IRGRP, S_IWGRP, S_IROTH, and S_IWOTH is used as the *mode*
33
+
> argument.
34
+
>
35
+
> b. The [*futimens*()](../functions/futimens.html) function is
36
+
> called with the following arguments:
37
+
>
38
+
> - The file descriptor opened in step 1a.
39
+
>
40
+
> - The access time and the modification time, set as described
41
+
> in the OPTIONS section, are used as the first and second
42
+
> elements of the *times* array argument, respectively.
43
+
>
44
+
> 2. If *file* exists, the [*utimensat*()](../functions/utimensat.html)
45
+
> function is called with the following arguments:
46
+
>
47
+
> a. The AT_FDCWD special value is used as the *fd* argument.
48
+
>
49
+
> b. The *file* operand is used as the *path* argument.
50
+
>
51
+
> c. The access time and the modification time, set as described in
52
+
> the OPTIONS section, are used as the first and second elements
53
+
> of the *times* array argument, respectively.
54
+
>
55
+
> d. The *flag* argument is set to zero.
56
+
57
+
#### []{#tag_20_130_04}OPTIONS {#options .mansect}
58
+
59
+
> The *touch* utility shall conform to XBD [*Utility Syntax
60
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02).
61
+
>
62
+
> The following options shall be supported:
63
+
>
64
+
> **-a**
65
+
> : Change the access time of *file*. Do not change the modification
66
+
> time unless **-m** is also specified.
67
+
>
68
+
> **-c**
69
+
> : Do not create a specified *file* if it does not exist. Do not
70
+
> write any diagnostic messages concerning this condition.
71
+
>
72
+
> **-d ** *date_time*
73
+
>
74
+
> : Use the specified *date_time* instead of the current time. The
75
+
> option-argument shall be a string of the form:
76
+
>
77
+
>
78
+
> YYYY-MM-DDThh:mm:SS[.frac][tz]
79
+
>
80
+
> or:
81
+
>
82
+
>
83
+
> YYYY-MM-DDThh:mm:SS[,frac][tz]
84
+
>
85
+
> where:
86
+
>
87
+
> - *YYYY* are at least four decimal digits giving the year.
88
+
>
89
+
> - *MM*, *DD*, *hh*, *mm*, and *SS* are as with **-t** *time*.
90
+
>
91
+
> - `T` is the time designator, and can be replaced by a single
92
+
> \<space\>.
93
+
>
94
+
> - `[.`*frac*`]` and `[,`*frac*`]` are either empty, or a
95
+
> \<period\> ( `'.'` ) or a \<comma\> ( `','` ) respectively,
96
+
> followed by one or more decimal digits, specifying a fractional
97
+
> second.
98
+
>
99
+
> - `[`*tz*`]` is either empty, signifying local time, or the letter
100
+
> `'Z'`, signifying UTC. If `[`*tz*`]` is empty, the resulting
101
+
> time shall be affected by the value of the *TZ* environment
102
+
> variable.
103
+
>
104
+
> If the resulting time precedes the Epoch, the behavior is
105
+
> implementation-defined. If the time cannot be represented as the
106
+
> file\'s timestamp, *touch* shall exit immediately with an error
107
+
> status.
108
+
>
109
+
> **-m**
110
+
> : Change the modification time of *file*. Do not change the access
111
+
> time unless **-a** is also specified.
112
+
>
113
+
> **-r ** *ref_file*
114
+
> : Use the corresponding time of the file named by the pathname
115
+
> *ref_file* instead of the current time.
116
+
>
117
+
> **-t ** *time*
118
+
>
119
+
> : Use the specified *time* instead of the current time. The
120
+
> option-argument shall be a decimal number of the form:
121
+
>
122
+
>
123
+
> [[CC]YY]MMDDhhmm[.SS]
124
+
>
125
+
> where each two digits represents the following:
126
+
>
127
+
> *MM*
128
+
> : The month of the year \[01,12\].
129
+
>
130
+
> *DD*
131
+
> : The day of the month \[01,31\].
132
+
>
133
+
> *hh*
134
+
> : The hour of the day \[00,23\].
135
+
>
136
+
> *mm*
137
+
> : The minute of the hour \[00,59\].
138
+
>
139
+
> *CC*
140
+
> : The first two digits of the year (the century).
141
+
>
142
+
> *YY*
143
+
> : The second two digits of the year.
144
+
>
145
+
> *SS*
146
+
> : The second of the minute \[00,60\].
147
+
>
148
+
> Both *CC* and *YY* shall be optional. If neither is given, the
149
+
> current year shall be assumed. If *YY* is specified, but *CC* is
150
+
> not, *CC* shall be derived as follows:
151
+
>
152
+
> **If *YY* is:** ***CC* becomes:**
153
+
> ----------------- -------------------
154
+
> \[69,99\] 19
155
+
> \[00,68\] 20
156
+
>
157
+
> **Note:**
158
+
> : It is expected that in a future version of this standard the
159
+
> default century inferred from a 2-digit year will change.
160
+
> (This would apply to all commands accepting a 2-digit year as
161
+
> input.)
162
+
>
163
+
> The resulting time shall be affected by the value of the *TZ*
164
+
> environment variable. If the resulting time value precedes the
165
+
> Epoch, the behavior is implementation-defined. If the time is out
166
+
> of range for the file\'s timestamp, *touch* shall exit immediately
167
+
> with an error status. The range of valid times past the Epoch is
168
+
> implementation-defined, but it shall extend to at least the time 0
169
+
> hours, 0 minutes, 0 seconds, January 1, 2038, Coordinated
170
+
> Universal Time. Some implementations may not be able to represent
171
+
> dates beyond January 18, 2038, because they use **signed int** as
172
+
> a time holder.
173
+
>
174
+
> The range for *SS* is \[00,60\] rather than \[00,59\] because of
175
+
> leap seconds. If *SS* is 60, and the resulting time, as affected
176
+
> by the *TZ* environment variable, does not refer to a leap second,
177
+
> the resulting time shall be one second after a time where *SS*
178
+
> is 59. If *SS* is not given a value, it is assumed to be zero.
179
+
>
180
+
> If neither the **-a** nor **-m** options were specified, *touch* shall
181
+
> behave as if both the **-a** and **-m** options were specified.
182
+
183
+
#### []{#tag_20_130_05}OPERANDS {#operands .mansect}
184
+
185
+
> The following operands shall be supported:
186
+
>
187
+
> *file*
188
+
> : A pathname of a file whose times shall be modified.
189
+
190
+
#### []{#tag_20_130_06}STDIN {#stdin .mansect}
191
+
192
+
> Not used.
193
+
194
+
#### []{#tag_20_130_07}INPUT FILES {#input-files .mansect}
195
+
196
+
> None.
197
+
198
+
#### []{#tag_20_130_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
199
+
200
+
> The following environment variables shall affect the execution of
201
+
> *touch*:
202
+
>
203
+
> *LANG*
204
+
> : Provide a default value for the internationalization variables
205
+
> that are unset or null. (See XBD [*Internationalization
206
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
207
+
> precedence of internationalization variables used to determine the
208
+
> values of locale categories.)
209
+
>
210
+
> *LC_ALL*
211
+
> : If set to a non-empty string value, override the values of all the
212
+
> other internationalization variables.
213
+
>
214
+
> *LC_CTYPE*
215
+
> : Determine the locale for the interpretation of sequences of bytes
216
+
> of text data as characters (for example, single-byte as opposed to
217
+
> multi-byte characters in arguments).
218
+
>
219
+
> *LC_MESSAGES*
220
+
> : Determine the locale that should be used to affect the format and
221
+
> contents of diagnostic messages written to standard error.
222
+
>
223
+
> *NLSPATH*
224
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
225
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
226
+
> location of message catalogs for the processing of *LC_MESSAGES.*
227
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
228
+
>
229
+
> *TZ*
230
+
> : Determine the timezone to be used for interpreting the *time*
231
+
> option-argument. If *TZ* is unset or null, an unspecified default
232
+
> timezone shall be used.
233
+
234
+
#### []{#tag_20_130_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
235
+
236
+
> Default.
237
+
238
+
#### []{#tag_20_130_10}STDOUT {#stdout .mansect}
239
+
240
+
> Not used.
241
+
242
+
#### []{#tag_20_130_11}STDERR {#stderr .mansect}
243
+
244
+
> The standard error shall be used only for diagnostic messages.
245
+
246
+
#### []{#tag_20_130_12}OUTPUT FILES {#output-files .mansect}
247
+
248
+
> None.
249
+
250
+
#### []{#tag_20_130_13}EXTENDED DESCRIPTION {#extended-description .mansect}
251
+
252
+
> None.
253
+
254
+
#### []{#tag_20_130_14}EXIT STATUS {#exit-status .mansect}
255
+
256
+
> The following exit values shall be returned:
257
+
>
258
+
> 0
259
+
> : The utility executed successfully and all requested changes were
260
+
> made.
261
+
>
262
+
> \>0
263
+
> : An error occurred.
264
+
265
+
#### []{#tag_20_130_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
266
+
267
+
> Default.
268
+
269
+
------------------------------------------------------------------------
270
+
271
+
::: box
272
+
*The following sections are informative.*
273
+
:::
274
+
275
+
#### []{#tag_20_130_16}APPLICATION USAGE {#application-usage .mansect}
276
+
277
+
> The interpretation of time is taken to be *seconds since the Epoch*
278
+
> (see XBD [*Seconds Since the
279
+
> Epoch*](../basedefs/V1_chap04.html#tag_04_16)). It should be noted
280
+
> that implementations conforming to the System Interfaces volume of
281
+
> POSIX.1-2017 do not take leap seconds into account when computing
282
+
> seconds since the Epoch. When *SS*=60 is used, the resulting time
283
+
> always refers to 1 plus *seconds since the Epoch* for a time when
284
+
> *SS*=59.
285
+
>
286
+
> Although the **-t** *time* option-argument specifies values in 1969,
287
+
> the access time and modification time fields are defined in terms of
288
+
> seconds since the Epoch (00:00:00 on 1 January 1970 UTC). Therefore,
289
+
> depending on the value of *TZ* when *touch* is run, there is never
290
+
> more than a few valid hours in 1969 and there need not be any valid
291
+
> times in 1969.
292
+
>
293
+
> If the *T* time designator is replaced by a \<space\> for the **-d**
294
+
> *date_time* option-argument, the \<space\> must be quoted to prevent
295
+
> the shell from splitting the argument.
296
+
297
+
#### []{#tag_20_130_17}EXAMPLES {#examples .mansect}
298
+
299
+
> Create or update a file called **dwc**; the resulting file has both
300
+
> the last data modification and last data access timestamps set to
301
+
> November 12, 2007 at 10:15:30 local time:
302
+
>
303
+
>
304
+
> touch -d 2007-11-12T10:15:30 dwc
305
+
>
306
+
> Create or update a file called **nick**; the resulting file has both
307
+
> the last data modification and last data access timestamps set to
308
+
> November 12, 2007 at 10:15:30 UTC:
309
+
>
310
+
>
311
+
> touch -d 2007-11-12T10:15:30Z nick
312
+
>
313
+
> Create or update a file called **gwc**; the resulting file has both
314
+
> the last data modification and last data access timestamps set to
315
+
> November 12, 2007 at 10:15:30 local time with a fractional second
316
+
> timestamp of .002 seconds:
317
+
>
318
+
>
319
+
> touch -d 2007-11-12T10:15:30,002 gwc
320
+
>
321
+
> Create or update a file called **ajosey**; the resulting file has both
322
+
> the last data modification and last data access timestamps set to
323
+
> November 12, 2007 at 10:15:30 UTC with a fractional second timestamp
324
+
> of .002 seconds:
325
+
>
326
+
>
327
+
> touch -d "2007-11-12 10:15:30.002Z" ajosey
328
+
>
329
+
> Create or update a file called **cathy**; the resulting file has both
330
+
> the last data modification and last data access timestamps set to
331
+
> November 12, 2007 at 10:15:00 local time:
332
+
>
333
+
>
334
+
> touch -t 200711121015 cathy
335
+
>
336
+
> Create or update a file called **drepper**; the resulting file has
337
+
> both the last data modification and last data access timestamps set to
338
+
> November 12, 2007 at 10:15:30 local time:
339
+
>
340
+
>
341
+
> touch -t 200711121015.30 drepper
342
+
>
343
+
> Create or update a file called **ebb9**; the resulting file has both
344
+
> the last data modification and last data access timestamps set to
345
+
> November 12, 2007 at 10:15:30 local time:
346
+
>
347
+
>
348
+
> touch -t 0711121015.30 ebb9
349
+
>
350
+
> Create or update a file called **eggert**; the resulting file has the
351
+
> last data access timestamp set to the corresponding time of the file
352
+
> named **mark** instead of the current time. If the file exists, the
353
+
> last data modification time is not changed:
354
+
>
355
+
>
356
+
> touch -a -r mark eggert
357
+
358
+
#### []{#tag_20_130_18}RATIONALE {#rationale .mansect}
359
+
360
+
> The functionality of *touch* is described almost entirely through
361
+
> references to functions in the System Interfaces volume of
362
+
> POSIX.1-2017. In this way, there is no duplication of effort required
363
+
> for describing such side-effects as the relationship of user IDs to
364
+
> the user database, permissions, and so on.
365
+
>
366
+
> There are some significant differences between the *touch* utility in
367
+
> this volume of POSIX.1-2017 and those in System V and BSD systems.
368
+
> They are upwards-compatible for historical applications from both
369
+
> implementations:
370
+
>
371
+
> 1. In System V, an ambiguity exists when a pathname that is a decimal
372
+
> number leads the operands; it is treated as a time value. In BSD,
373
+
> no *time* value is allowed; files may only be *touch*ed to the
374
+
> current time. The **-t** *time* construct solves these problems
375
+
> for future conforming applications (note that the **-t** option is
376
+
> not historical practice).
377
+
>
378
+
> 2. The inclusion of the century digits, *CC*, is also new. Note that
379
+
> a ten-digit *time* value is treated as if *YY*, and not *CC*, were
380
+
> specified. The caveat about the range of dates following the Epoch
381
+
> was included as recognition that some implementations are not able
382
+
> to represent dates beyond 18 January 2038 because they use
383
+
> **signed int** as a time holder.
384
+
>
385
+
> The **-r** option was added because several comments requested this
386
+
> capability. This option was named **-f** in an early proposal, but was
387
+
> changed because the **-f** option is used in the BSD version of
388
+
> *touch* with a different meaning.
389
+
>
390
+
> At least one historical implementation of *touch* incremented the exit
391
+
> code if **-c** was specified and the file did not exist. This volume
392
+
> of POSIX.1-2017 requires exit status zero if no errors occur.
393
+
>
394
+
> In previous version of the standard, if at least two operands are
395
+
> specified, and the first operand is an eight or ten-digit decimal
396
+
> integer, the first operand was assumed to be a *date_time* operand.
397
+
> This usage was removed in this version of the standard since it had
398
+
> been marked obsolescent previously.
399
+
>
400
+
> The **-d** *date_time* format is an ISO 8601:2000 standard complete
401
+
> representation of date and time extended format with an optional
402
+
> decimal point or \<comma\> followed by a string of digits following
403
+
> the seconds portion to specify fractions of a second. It is not
404
+
> necessary to recognize `"[+/-]hh:mm"` and `"[+/-]hh"` to specify
405
+
> timezones other than local time and UTC. The *T* time designator in
406
+
> the ISO 8601:2000 standard extended format may be replaced by
407
+
> \<space\>.
408
+
409
+
#### []{#tag_20_130_19}FUTURE DIRECTIONS {#future-directions .mansect}
410
+
411
+
> None.
412
+
413
+
#### []{#tag_20_130_20}SEE ALSO {#see-also .mansect}
414
+
415
+
> [*date*](../utilities/date.html#)
416
+
>
417
+
> XBD [*Seconds Since the Epoch*](../basedefs/V1_chap04.html#tag_04_16),
418
+
> [*Environment Variables*](../basedefs/V1_chap08.html#tag_08),
419
+
> [*Utility Syntax Guidelines*](../basedefs/V1_chap12.html#tag_12_02),
420
+
> [*\<sys/stat.h\>*](../basedefs/sys_stat.h.html)
421
+
>
422
+
> XSH [*creat*](../functions/creat.html#),
423
+
> [*futimens*](../functions/futimens.html#),
424
+
> [*time*](../functions/time.html#tag_16_613),
425
+
> [*utime*](../functions/utime.html#)
426
+
427
+
#### []{#tag_20_130_21}CHANGE HISTORY {#change-history .mansect}
428
+
429
+
> First released in Issue 2.
430
+
431
+
#### []{#tag_20_130_22}Issue 6 {#issue-6 .mansect}
432
+
433
+
> The obsolescent *date_time* operand is removed.
434
+
>
435
+
> The Open Group Corrigendum U027/1 is applied. This extends the range
436
+
> of valid time past the Epoch to at least the time 0 hours, 0 minutes,
437
+
> 0 seconds, January 1, 2038, Coordinated Universal Time. This is a new
438
+
> requirement on POSIX implementations.
439
+
>
440
+
> The range for seconds is changed from \[00,61\] to \[00,60\] to align
441
+
> with the ISO/IEC 9899:1999 standard, and to allow for positive leap
442
+
> seconds.
443
+
444
+
#### []{#tag_20_130_23}Issue 7 {#issue-7 .mansect}
445
+
446
+
> Austin Group Interpretation 1003.1-2001 #118 is applied.
447
+
>
448
+
> Austin Group Interpretation 1003.1-2001 #193 is applied, adding
449
+
> support for subsecond timestamps.
450
+
>
451
+
> SD5-XCU-ERN-45 is applied, adding a new paragraph to the RATIONALE.
452
+
>
453
+
> SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.
454
+
>
455
+
> SD5-XCU-ERN-110 is applied, updating the OPTIONS section.
456
+
>
457
+
> Changes are made related to support for finegrained timestamps.
458
+
>
459
+
> POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0195 \[474\] is
460
+
> applied.
461
+
+513
docs/posix2018/tr.md
+513
docs/posix2018/tr.md
···
1
+
#### []{#tag_20_132_01}NAME {#name .mansect}
2
+
3
+
> tr - translate characters
4
+
5
+
#### []{#tag_20_132_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `tr`` `**`[`**`-c|-C`**`] [`**`-s`**`]`**` `*`string1 string2`*\
8
+
> \
9
+
> `tr -s`` `**`[`**`-c|-C`**`]`**` `*`string1`*\
10
+
> \
11
+
> `tr -d`` `**`[`**`-c|-C`**`]`**` `*`string1`*\
12
+
> \
13
+
> `tr -ds`` `**`[`**`-c|-C`**`]`**` `*`string1 string2`*\
14
+
15
+
#### []{#tag_20_132_03}DESCRIPTION {#description .mansect}
16
+
17
+
> The *tr* utility shall copy the standard input to the standard output
18
+
> with substitution or deletion of selected characters. The options
19
+
> specified and the *string1* and *string2* operands shall control
20
+
> translations that occur while copying characters and single-character
21
+
> collating elements.
22
+
23
+
#### []{#tag_20_132_04}OPTIONS {#options .mansect}
24
+
25
+
> The *tr* utility shall conform to XBD [*Utility Syntax
26
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02) .
27
+
>
28
+
> The following options shall be supported:
29
+
>
30
+
> **-c**
31
+
> : Complement the set of values specified by *string1*. See the
32
+
> EXTENDED DESCRIPTION section.
33
+
>
34
+
> **-C**
35
+
> : Complement the set of characters specified by *string1*. See the
36
+
> EXTENDED DESCRIPTION section.
37
+
>
38
+
> **-d**
39
+
> : Delete all occurrences of input characters that are specified by
40
+
> *string1*.
41
+
>
42
+
> **-s**
43
+
> : Replace instances of repeated characters with a single character,
44
+
> as described in the EXTENDED DESCRIPTION section.
45
+
46
+
#### []{#tag_20_132_05}OPERANDS {#operands .mansect}
47
+
48
+
> The following operands shall be supported:
49
+
>
50
+
> *string1*, *string2*
51
+
> : Translation control strings. Each string shall represent a set of
52
+
> characters to be converted into an array of characters used for
53
+
> the translation. For a detailed description of how the strings are
54
+
> interpreted, see the EXTENDED DESCRIPTION section.
55
+
56
+
#### []{#tag_20_132_06}STDIN {#stdin .mansect}
57
+
58
+
> The standard input can be any type of file.
59
+
60
+
#### []{#tag_20_132_07}INPUT FILES {#input-files .mansect}
61
+
62
+
> None.
63
+
64
+
#### []{#tag_20_132_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
65
+
66
+
> The following environment variables shall affect the execution of
67
+
> *tr*:
68
+
>
69
+
> *LANG*
70
+
> : Provide a default value for the internationalization variables
71
+
> that are unset or null. (See XBD [*Internationalization
72
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
73
+
> precedence of internationalization variables used to determine the
74
+
> values of locale categories.)
75
+
>
76
+
> *LC_ALL*
77
+
> : If set to a non-empty string value, override the values of all the
78
+
> other internationalization variables.
79
+
>
80
+
> *LC_COLLATE*
81
+
> : Determine the locale for the behavior of range expressions and
82
+
> equivalence classes.
83
+
>
84
+
> *LC_CTYPE*
85
+
> : Determine the locale for the interpretation of sequences of bytes
86
+
> of text data as characters (for example, single-byte as opposed to
87
+
> multi-byte characters in arguments) and the behavior of character
88
+
> classes.
89
+
>
90
+
> *LC_MESSAGES*
91
+
> : Determine the locale that should be used to affect the format and
92
+
> contents of diagnostic messages written to standard error.
93
+
>
94
+
> *NLSPATH*
95
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
96
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
97
+
> location of message catalogs for the processing of *LC_MESSAGES.*
98
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
99
+
100
+
#### []{#tag_20_132_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
101
+
102
+
> Default.
103
+
104
+
#### []{#tag_20_132_10}STDOUT {#stdout .mansect}
105
+
106
+
> The *tr* output shall be identical to the input, with the exception of
107
+
> the specified transformations.
108
+
109
+
#### []{#tag_20_132_11}STDERR {#stderr .mansect}
110
+
111
+
> The standard error shall be used only for diagnostic messages.
112
+
113
+
#### []{#tag_20_132_12}OUTPUT FILES {#output-files .mansect}
114
+
115
+
> None.
116
+
117
+
#### []{#tag_20_132_13}EXTENDED DESCRIPTION {#extended-description .mansect}
118
+
119
+
> The operands *string1* and *string2* (if specified) define two arrays
120
+
> of characters. The constructs in the following list can be used to
121
+
> specify characters or single-character collating elements. If any of
122
+
> the constructs result in multi-character collating elements, *tr*
123
+
> shall exclude, without a diagnostic, those multi-character elements
124
+
> from the resulting array.
125
+
>
126
+
> *character*
127
+
> : Any character not described by one of the conventions below shall
128
+
> represent itself.
129
+
>
130
+
> \\*octal*
131
+
> : Octal sequences can be used to represent characters with specific
132
+
> coded values. An octal sequence shall consist of a \<backslash\>
133
+
> followed by the longest sequence of one, two, or three-octal-digit
134
+
> characters (01234567). The sequence shall cause the value whose
135
+
> encoding is represented by the one, two, or three-digit octal
136
+
> integer to be placed into the array. Multi-byte characters require
137
+
> multiple, concatenated escape sequences of this type, including
138
+
> the leading \<backslash\> for each byte.
139
+
>
140
+
> \\*character*
141
+
> : The \<backslash\>-escape sequences in XBD [*Escape Sequences and
142
+
> Associated Actions*](../basedefs/V1_chap05.html#tagtcjh_2) (
143
+
> `'\\'`, `'\a'`, `'\b'`, `'\f'`, `'\n'`, `'\r'`, `'\t'`, `'\v'` )
144
+
> shall be supported. The results of using any other character,
145
+
> other than an octal digit, following the \<backslash\> are
146
+
> unspecified. Also, if there is no character following the
147
+
> \<backslash\>, the results are unspecified.
148
+
>
149
+
> *c*-*c*
150
+
>
151
+
> : In the POSIX locale, this construct shall represent the range of
152
+
> collating elements between the range endpoints (as long as neither
153
+
> endpoint is an octal sequence of the form \\*octal*), inclusive,
154
+
> as defined by the collation sequence. The characters or collating
155
+
> elements in the range shall be placed in the array in ascending
156
+
> collation sequence. If the second endpoint precedes the starting
157
+
> endpoint in the collation sequence, it is unspecified whether the
158
+
> range of collating elements is empty, or this construct is treated
159
+
> as invalid. In locales other than the POSIX locale, this construct
160
+
> has unspecified behavior.
161
+
>
162
+
> If either or both of the range endpoints are octal sequences of
163
+
> the form \\*octal*, this shall represent the range of specific
164
+
> coded values between the two range endpoints, inclusive.
165
+
>
166
+
> \[:*class*:\]
167
+
>
168
+
> : Represents all characters belonging to the defined character
169
+
> class, as defined by the current setting of the *LC_CTYPE* locale
170
+
> category. The following character class names shall be accepted
171
+
> when specified in *string1*:
172
+
>
173
+
> ----------- ----------- ----------- ----------- ----------- ------------
174
+
> **alnum** **blank** **digit** **lower** **punct** **upper**
175
+
> **alpha** **cntrl** **graph** **print** **space** **xdigit**
176
+
> ----------- ----------- ----------- ----------- ----------- ------------
177
+
>
178
+
> ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
179
+
> Start\]](../images/opt-start.gif){border="0"} In addition,
180
+
> character class expressions of the form \[: *name*:\] shall be
181
+
> recognized in those locales where the *name* keyword has been
182
+
> given a **charclass** definition in the *LC_CTYPE* category.
183
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
184
+
>
185
+
> When both the **-d** and **-s** options are specified, any of the
186
+
> character class names shall be accepted in *string2*. Otherwise,
187
+
> only character class names **lower** or **upper** are valid in
188
+
> *string2* and then only if the corresponding character class
189
+
> (**upper** and **lower**, respectively) is specified in the same
190
+
> relative position in *string1*. Such a specification shall be
191
+
> interpreted as a request for case conversion. When \[: *lower*:\]
192
+
> appears in *string1* and \[: *upper*:\] appears in *string2*, the
193
+
> arrays shall contain the characters from the **toupper** mapping
194
+
> in the *LC_CTYPE* category of the current locale. When \[:
195
+
> *upper*:\] appears in *string1* and \[: *lower*:\] appears in
196
+
> *string2*, the arrays shall contain the characters from the
197
+
> **tolower** mapping in the *LC_CTYPE* category of the current
198
+
> locale. The first character from each mapping pair shall be in the
199
+
> array for *string1* and the second character from each mapping
200
+
> pair shall be in the array for *string2* in the same relative
201
+
> position.
202
+
>
203
+
> Except for case conversion, the characters specified by a
204
+
> character class expression shall be placed in the array in an
205
+
> unspecified order.
206
+
>
207
+
> If the name specified for *class* does not define a valid
208
+
> character class in the current locale, the behavior is undefined.
209
+
>
210
+
> \[=*equiv*=\]
211
+
> : Represents all characters or collating elements belonging to the
212
+
> same equivalence class as *equiv*, as defined by the current
213
+
> setting of the *LC_COLLATE* locale category. An equivalence class
214
+
> expression shall be allowed only in *string1*, or in *string2*
215
+
> when it is being used by the combined **-d** and **-s** options.
216
+
> The characters belonging to the equivalence class shall be placed
217
+
> in the array in an unspecified order.
218
+
>
219
+
> \[*x*\**n*\]
220
+
> : Represents *n* repeated occurrences of the character *x*. Because
221
+
> this expression is used to map multiple characters to one, it is
222
+
> only valid when it occurs in *string2*. If *n* is omitted or is
223
+
> zero, it shall be interpreted as large enough to extend the
224
+
> *string2*-based sequence to the length of the *string1*-based
225
+
> sequence. If *n* has a leading zero, it shall be interpreted as an
226
+
> octal value. Otherwise, it shall be interpreted as a decimal
227
+
> value.
228
+
>
229
+
> When the **-d** option is not specified:
230
+
>
231
+
> - If *string2* is present, each input character found in the array
232
+
> specified by *string1* shall be replaced by the character in the
233
+
> same relative position in the array specified by *string2*. If the
234
+
> array specified by *string2* is shorter that the one specified by
235
+
> *string1*, or if a character occurs more than once in *string1*, the
236
+
> results are unspecified.
237
+
>
238
+
> - If the **-C** option is specified, the complements of the characters
239
+
> specified by *string1* (the set of all characters in the current
240
+
> character set, as defined by the current setting of *LC_CTYPE,*
241
+
> except for those actually specified in the *string1* operand) shall
242
+
> be placed in the array in ascending collation sequence, as defined
243
+
> by the current setting of *LC_COLLATE.*
244
+
>
245
+
> - If the **-c** option is specified, the complement of the values
246
+
> specified by *string1* shall be placed in the array in ascending
247
+
> order by binary value.
248
+
>
249
+
> - Because the order in which characters specified by character class
250
+
> expressions or equivalence class expressions is undefined, such
251
+
> expressions should only be used if the intent is to map several
252
+
> characters into one. An exception is case conversion, as described
253
+
> previously.
254
+
>
255
+
> When the **-d** option is specified:
256
+
>
257
+
> - Input characters found in the array specified by *string1* shall be
258
+
> deleted.
259
+
>
260
+
> - When the **-C** option is specified with **-d**, all characters
261
+
> except those specified by *string1* shall be deleted. The contents
262
+
> of *string2* are ignored, unless the **-s** option is also
263
+
> specified.
264
+
>
265
+
> - When the **-c** option is specified with **-d**, all values except
266
+
> those specified by *string1* shall be deleted. The contents of
267
+
> *string2* shall be ignored, unless the **-s** option is also
268
+
> specified.
269
+
>
270
+
> - The same string cannot be used for both the **-d** and the **-s**
271
+
> option; when both options are specified, both *string1* (used for
272
+
> deletion) and *string2* (used for squeezing) shall be required.
273
+
>
274
+
> When the **-s** option is specified, after any deletions or
275
+
> translations have taken place, repeated sequences of the same
276
+
> character shall be replaced by one occurrence of the same character,
277
+
> if the character is found in the array specified by the last operand.
278
+
> If the last operand contains a character class, such as the following
279
+
> example:
280
+
>
281
+
>
282
+
> tr -s '[:space:]'
283
+
>
284
+
> the last operand\'s array shall contain all of the characters in that
285
+
> character class. However, in a case conversion, as described
286
+
> previously, such as:
287
+
>
288
+
>
289
+
> tr -s '[:upper:]' '[:lower:]'
290
+
>
291
+
> the last operand\'s array shall contain only those characters defined
292
+
> as the second characters in each of the **toupper** or **tolower**
293
+
> character pairs, as appropriate.
294
+
>
295
+
> An empty string used for *string1* or *string2* produces undefined
296
+
> results.
297
+
298
+
#### []{#tag_20_132_14}EXIT STATUS {#exit-status .mansect}
299
+
300
+
> The following exit values shall be returned:
301
+
>
302
+
> 0
303
+
> : All input was processed successfully.
304
+
>
305
+
> \>0
306
+
> : An error occurred.
307
+
308
+
#### []{#tag_20_132_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
309
+
310
+
> Default.
311
+
312
+
------------------------------------------------------------------------
313
+
314
+
::: box
315
+
*The following sections are informative.*
316
+
:::
317
+
318
+
#### []{#tag_20_132_16}APPLICATION USAGE {#application-usage .mansect}
319
+
320
+
> If necessary, *string1* and *string2* can be quoted to avoid pattern
321
+
> matching by the shell.
322
+
>
323
+
> If an ordinary digit (representing itself) is to follow an octal
324
+
> sequence, the octal sequence must use the full three digits to avoid
325
+
> ambiguity.
326
+
>
327
+
> When *string2* is shorter than *string1*, a difference results between
328
+
> historical System V and BSD systems. A BSD system pads *string2* with
329
+
> the last character found in *string2*. Thus, it is possible to do the
330
+
> following:
331
+
>
332
+
>
333
+
> tr 0123456789 d
334
+
>
335
+
> which would translate all digits to the letter `'d'`. Since this area
336
+
> is specifically unspecified in this volume of POSIX.1-2017, both the
337
+
> BSD and System V behaviors are allowed, but a conforming application
338
+
> cannot rely on the BSD behavior. It would have to code the example in
339
+
> the following way:
340
+
>
341
+
>
342
+
> tr 0123456789 '[d*]'
343
+
>
344
+
> It should be noted that, despite similarities in appearance, the
345
+
> string operands used by *tr* are not regular expressions.
346
+
>
347
+
> Unlike some historical implementations, this definition of the *tr*
348
+
> utility correctly processes NUL characters in its input stream. NUL
349
+
> characters can be stripped by using:
350
+
>
351
+
>
352
+
> tr -d '\000'
353
+
354
+
#### []{#tag_20_132_17}EXAMPLES {#examples .mansect}
355
+
356
+
> 1. The following example creates a list of all words in **file1** one
357
+
> per line in **file2**, where a word is taken to be a maximal
358
+
> string of letters.
359
+
>
360
+
>
361
+
> tr -cs "[:alpha:]" "[\n*]" <file1 >file2
362
+
>
363
+
> 2. The next example translates all lowercase characters in **file1**
364
+
> to uppercase and writes the results to standard output.
365
+
>
366
+
>
367
+
> tr "[:lower:]" "[:upper:]" <file1
368
+
>
369
+
> 3. This example uses an equivalence class to identify accented
370
+
> variants of the base character `'e'` in **file1**, which are
371
+
> stripped of diacritical marks and written to **file2**.
372
+
>
373
+
>
374
+
> tr "[=e=]" "[e*]" <file1 >file2
375
+
376
+
#### []{#tag_20_132_18}RATIONALE {#rationale .mansect}
377
+
378
+
> In some early proposals, an explicit option **-n** was added to
379
+
> disable the historical behavior of stripping NUL characters from the
380
+
> input. It was considered that automatically stripping NUL characters
381
+
> from the input was not correct functionality. However, the removal of
382
+
> **-n** in a later proposal does not remove the requirement that *tr*
383
+
> correctly process NUL characters in its input stream. NUL characters
384
+
> can be stripped by using *tr* **-d** \'\\000\'.
385
+
>
386
+
> Historical implementations of *tr* differ widely in syntax and
387
+
> behavior. For example, the BSD version has not needed the bracket
388
+
> characters for the repetition sequence. The *tr* utility syntax is
389
+
> based more closely on the System V and XPG3 model while attempting to
390
+
> accommodate historical BSD implementations. In the case of the short
391
+
> *string2* padding, the decision was to unspecify the behavior and
392
+
> preserve System V and XPG3 scripts, which might find difficulty with
393
+
> the BSD method. The assumption was made that BSD users of *tr* have to
394
+
> make accommodations to meet the syntax defined here. Since it is
395
+
> possible to use the repetition sequence to duplicate the desired
396
+
> behavior, whereas there is no simple way to achieve the System V
397
+
> method, this was the correct, if not desirable, approach.
398
+
>
399
+
> The use of octal values to specify control characters, while having
400
+
> historical precedents, is not portable. The introduction of escape
401
+
> sequences for control characters should provide the necessary
402
+
> portability. It is recognized that this may cause some historical
403
+
> scripts to break.
404
+
>
405
+
> An early proposal included support for multi-character collating
406
+
> elements. It was pointed out that, while *tr* does employ some
407
+
> syntactical elements from REs, the aim of *tr* is quite different;
408
+
> ranges, for example, do not have a similar meaning (\`\`any of the
409
+
> chars in the range matches\", *versus* \"translate each character in
410
+
> the range to the output counterpart\"). As a result, the previously
411
+
> included support for multi-character collating elements has been
412
+
> removed. What remains are ranges in current collation order (to
413
+
> support, for example, accented characters), character classes, and
414
+
> equivalence classes.
415
+
>
416
+
> In XPG3 the \[: *class*:\] and \[= *equiv*=\] conventions are shown
417
+
> with double brackets, as in RE syntax. However, *tr* does not
418
+
> implement RE principles; it just borrows part of the syntax.
419
+
> Consequently, \[: *class*:\] and \[= *equiv*=\] should be regarded as
420
+
> syntactical elements on a par with \[ *x*\* *n*\], which is not an RE
421
+
> bracket expression.
422
+
>
423
+
> The standard developers will consider changes to *tr* that allow it to
424
+
> translate characters between different character encodings, or they
425
+
> will consider providing a new utility to accomplish this.
426
+
>
427
+
> On historical System V systems, a range expression requires enclosing
428
+
> square-brackets, such as:
429
+
>
430
+
>
431
+
> tr '[a-z]' '[A-Z]'
432
+
>
433
+
> However, BSD-based systems did not require the brackets, and this
434
+
> convention is used here to avoid breaking large numbers of BSD
435
+
> scripts:
436
+
>
437
+
>
438
+
> tr a-z A-Z
439
+
>
440
+
> The preceding System V script will continue to work because the
441
+
> brackets, treated as regular characters, are translated to themselves.
442
+
> However, any System V script that relied on `"a-z"` representing the
443
+
> three characters `'a'`, `'-'`, and `'z'` have to be rewritten as
444
+
> `"az-"`.
445
+
>
446
+
> The ISO POSIX-2:1993 standard had a **-c** option that behaved
447
+
> similarly to the **-C** option, but did not supply functionality
448
+
> equivalent to the **-c** option specified in POSIX.1-2017.
449
+
>
450
+
> The earlier version also said that octal sequences referred to
451
+
> collating elements and could be placed adjacent to each other to
452
+
> specify multi-byte characters. However, it was noted that this caused
453
+
> ambiguities because *tr* would not be able to tell whether adjacent
454
+
> octal sequences were intending to specify multi-byte characters or
455
+
> multiple single byte characters. POSIX.1-2017 specifies that octal
456
+
> sequences always refer to single byte binary values when used to
457
+
> specify an endpoint of a range of collating elements.
458
+
>
459
+
> Earlier versions of this standard allowed for implementations with
460
+
> bytes other than eight bits, but this has been modified in this
461
+
> version.
462
+
463
+
#### []{#tag_20_132_19}FUTURE DIRECTIONS {#future-directions .mansect}
464
+
465
+
> None.
466
+
467
+
#### []{#tag_20_132_20}SEE ALSO {#see-also .mansect}
468
+
469
+
> [*sed*](../utilities/sed.html#)
470
+
>
471
+
> XBD [*Escape Sequences and Associated
472
+
> Actions*](../basedefs/V1_chap05.html#tagtcjh_2), [*Environment
473
+
> Variables*](../basedefs/V1_chap08.html#tag_08), [*Utility Syntax
474
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02)
475
+
476
+
#### []{#tag_20_132_21}CHANGE HISTORY {#change-history .mansect}
477
+
478
+
> First released in Issue 2.
479
+
480
+
#### []{#tag_20_132_22}Issue 6 {#issue-6 .mansect}
481
+
482
+
> The **-C** operand is added, and the description of the **-c** operand
483
+
> is changed to align with the IEEE P1003.2b draft standard.
484
+
>
485
+
> The normative text is reworded to avoid use of the term \"must\" for
486
+
> application requirements.
487
+
>
488
+
> IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/31 is applied,
489
+
> removing text describing behavior on systems with bytes consisting of
490
+
> more than eight bits.
491
+
>
492
+
> IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/32 is applied,
493
+
> updating an example in the EXAMPLES section to avoid using unspecified
494
+
> behavior.
495
+
>
496
+
> IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/33 is applied, making
497
+
> a correction to the RATIONALE.
498
+
499
+
#### []{#tag_20_132_23}Issue 7 {#issue-7 .mansect}
500
+
501
+
> SD5-XCU-ERN-30 is applied.
502
+
>
503
+
> SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.\
504
+
>
505
+
> Austin Group Interpretation 1003.1-2001 #132 is applied, adding
506
+
> rationale to the \\ *character* construct.
507
+
>
508
+
> POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0145 \[325\] is
509
+
> applied.
510
+
>
511
+
> POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0196 \[663\] is
512
+
> applied.
513
+
+110
docs/posix2018/true.md
+110
docs/posix2018/true.md
···
1
+
#### []{#tag_20_133_01}NAME {#name .mansect}
2
+
3
+
> true - return true value
4
+
5
+
#### []{#tag_20_133_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `true`
8
+
9
+
#### []{#tag_20_133_03}DESCRIPTION {#description .mansect}
10
+
11
+
> The *true* utility shall return with exit code zero.
12
+
13
+
#### []{#tag_20_133_04}OPTIONS {#options .mansect}
14
+
15
+
> None.
16
+
17
+
#### []{#tag_20_133_05}OPERANDS {#operands .mansect}
18
+
19
+
> None.
20
+
21
+
#### []{#tag_20_133_06}STDIN {#stdin .mansect}
22
+
23
+
> Not used.
24
+
25
+
#### []{#tag_20_133_07}INPUT FILES {#input-files .mansect}
26
+
27
+
> None.
28
+
29
+
#### []{#tag_20_133_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
30
+
31
+
> None.
32
+
33
+
#### []{#tag_20_133_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
34
+
35
+
> Default.
36
+
37
+
#### []{#tag_20_133_10}STDOUT {#stdout .mansect}
38
+
39
+
> Not used.
40
+
41
+
#### []{#tag_20_133_11}STDERR {#stderr .mansect}
42
+
43
+
> Not used.
44
+
45
+
#### []{#tag_20_133_12}OUTPUT FILES {#output-files .mansect}
46
+
47
+
> None.
48
+
49
+
#### []{#tag_20_133_13}EXTENDED DESCRIPTION {#extended-description .mansect}
50
+
51
+
> None.
52
+
53
+
#### []{#tag_20_133_14}EXIT STATUS {#exit-status .mansect}
54
+
55
+
> Zero.
56
+
57
+
#### []{#tag_20_133_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
58
+
59
+
> None.
60
+
61
+
------------------------------------------------------------------------
62
+
63
+
::: box
64
+
*The following sections are informative.*
65
+
:::
66
+
67
+
#### []{#tag_20_133_16}APPLICATION USAGE {#application-usage .mansect}
68
+
69
+
> This utility is typically used in shell scripts, as shown in the
70
+
> EXAMPLES section. The special built-in utility **:** is sometimes more
71
+
> efficient than *true*.
72
+
73
+
#### []{#tag_20_133_17}EXAMPLES {#examples .mansect}
74
+
75
+
> This command is executed forever:
76
+
>
77
+
>
78
+
> while true
79
+
> do
80
+
> command
81
+
> done
82
+
83
+
#### []{#tag_20_133_18}RATIONALE {#rationale .mansect}
84
+
85
+
> The *true* utility has been retained in this volume of POSIX.1-2017,
86
+
> even though the shell special built-in **:** provides similar
87
+
> functionality, because *true* is widely used in historical scripts and
88
+
> is less cryptic to novice script readers.
89
+
90
+
#### []{#tag_20_133_19}FUTURE DIRECTIONS {#future-directions .mansect}
91
+
92
+
> None.
93
+
94
+
#### []{#tag_20_133_20}SEE ALSO {#see-also .mansect}
95
+
96
+
> [*Shell Commands*](../utilities/V3_chap02.html#tag_18_09),
97
+
> [*false*](../utilities/false.html#)
98
+
99
+
#### []{#tag_20_133_21}CHANGE HISTORY {#change-history .mansect}
100
+
101
+
> First released in Issue 2.
102
+
103
+
#### []{#tag_20_133_22}Issue 6 {#issue-6 .mansect}
104
+
105
+
> IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/39 is applied,
106
+
> replacing the terms \`\`None\'\' and \`\`Default\'\' from the STDERR
107
+
> and EXIT STATUS sections, respectively, with terms as defined in
108
+
> [*Utility Description
109
+
> Defaults*](../utilities/V3_chap01.html#tag_17_04).
110
+
+221
docs/posix2018/unexpand.md
+221
docs/posix2018/unexpand.md
···
1
+
#### []{#tag_20_142_01}NAME {#name .mansect}
2
+
3
+
> unexpand - convert spaces to tabs
4
+
5
+
#### []{#tag_20_142_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `unexpand`` `**`[`**`-a|-t`` `*`tablist`***`] [`***`file`*`...`**`]`**
8
+
9
+
#### []{#tag_20_142_03}DESCRIPTION {#description .mansect}
10
+
11
+
> The *unexpand* utility shall copy files or standard input to standard
12
+
> output, converting \<blank\> characters at the beginning of each line
13
+
> into the maximum number of \<tab\> characters followed by the minimum
14
+
> number of \<space\> characters needed to fill the same column
15
+
> positions originally filled by the translated \<blank\> characters. By
16
+
> default, tabstops shall be set at every eighth column position. Each
17
+
> \<backspace\> shall be copied to the output, and shall cause the
18
+
> column position count for tab calculations to be decremented; the
19
+
> count shall never be decremented to a value less than one.
20
+
21
+
#### []{#tag_20_142_04}OPTIONS {#options .mansect}
22
+
23
+
> The *unexpand* utility shall conform to XBD [*Utility Syntax
24
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02).
25
+
>
26
+
> The following options shall be supported:
27
+
>
28
+
> **-a**
29
+
> : In addition to translating \<blank\> characters at the beginning
30
+
> of each line, translate all sequences of two or more \<blank\>
31
+
> characters immediately preceding a tab stop to the maximum number
32
+
> of \<tab\> characters followed by the minimum number of \<space\>
33
+
> characters needed to fill the same column positions originally
34
+
> filled by the translated \<blank\> characters.
35
+
>
36
+
> **-t ** *tablist*
37
+
>
38
+
> : Specify the tab stops. The application shall ensure that the
39
+
> *tablist* option-argument is a single argument consisting of a
40
+
> single positive decimal integer or multiple positive decimal
41
+
> integers, separated by \<blank\> or \<comma\> characters, in
42
+
> ascending order. If a single number is given, tabs shall be set
43
+
> *tablist* column positions apart instead of the default 8. If
44
+
> multiple numbers are given, the tabs shall be set at those
45
+
> specific column positions.
46
+
>
47
+
> The application shall ensure that each tab-stop position *N* is an
48
+
> integer value greater than zero, and the list shall be in strictly
49
+
> ascending order. This is taken to mean that, from the start of a
50
+
> line of output, tabbing to position *N* shall cause the next
51
+
> character output to be in the (*N*+1)th column position on that
52
+
> line. When the **-t** option is not specified, the default shall
53
+
> be the equivalent of specifying **-t 8** (except for the
54
+
> interaction with **-a**, described below).
55
+
>
56
+
> No \<space\>-to- \<tab\> conversions shall occur for characters at
57
+
> positions beyond the last of those specified in a multiple
58
+
> tab-stop list.
59
+
>
60
+
> When **-t** is specified, the presence or absence of the **-a**
61
+
> option shall be ignored; conversion shall not be limited to the
62
+
> processing of leading \<blank\> characters.
63
+
64
+
#### []{#tag_20_142_05}OPERANDS {#operands .mansect}
65
+
66
+
> The following operand shall be supported:
67
+
>
68
+
> *file*
69
+
> : A pathname of a text file to be used as input.
70
+
71
+
#### []{#tag_20_142_06}STDIN {#stdin .mansect}
72
+
73
+
> See the INPUT FILES section.
74
+
75
+
#### []{#tag_20_142_07}INPUT FILES {#input-files .mansect}
76
+
77
+
> The input files shall be text files.
78
+
79
+
#### []{#tag_20_142_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
80
+
81
+
> The following environment variables shall affect the execution of
82
+
> *unexpand*:
83
+
>
84
+
> *LANG*
85
+
> : Provide a default value for the internationalization variables
86
+
> that are unset or null. (See XBD [*Internationalization
87
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
88
+
> precedence of internationalization variables used to determine the
89
+
> values of locale categories.)
90
+
>
91
+
> *LC_ALL*
92
+
> : If set to a non-empty string value, override the values of all the
93
+
> other internationalization variables.
94
+
>
95
+
> *LC_CTYPE*
96
+
> : Determine the locale for the interpretation of sequences of bytes
97
+
> of text data as characters (for example, single-byte as opposed to
98
+
> multi-byte characters in arguments and input files), the
99
+
> processing of \<tab\> and \<space\> characters, and for the
100
+
> determination of the width in column positions each character
101
+
> would occupy on an output device.
102
+
>
103
+
> *LC_MESSAGES*
104
+
> : Determine the locale that should be used to affect the format and
105
+
> contents of diagnostic messages written to standard error.
106
+
>
107
+
> *NLSPATH*
108
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
109
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
110
+
> location of message catalogs for the processing of *LC_MESSAGES.*
111
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
112
+
113
+
#### []{#tag_20_142_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
114
+
115
+
> Default.
116
+
117
+
#### []{#tag_20_142_10}STDOUT {#stdout .mansect}
118
+
119
+
> The standard output shall be equivalent to the input files with the
120
+
> specified \<space\>-to- \<tab\> conversions.
121
+
122
+
#### []{#tag_20_142_11}STDERR {#stderr .mansect}
123
+
124
+
> The standard error shall be used only for diagnostic messages.
125
+
126
+
#### []{#tag_20_142_12}OUTPUT FILES {#output-files .mansect}
127
+
128
+
> None.
129
+
130
+
#### []{#tag_20_142_13}EXTENDED DESCRIPTION {#extended-description .mansect}
131
+
132
+
> None.
133
+
134
+
#### []{#tag_20_142_14}EXIT STATUS {#exit-status .mansect}
135
+
136
+
> The following exit values shall be returned:
137
+
>
138
+
> 0
139
+
> : Successful completion.
140
+
>
141
+
> \>0
142
+
> : An error occurred.
143
+
144
+
#### []{#tag_20_142_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
145
+
146
+
> Default.
147
+
148
+
------------------------------------------------------------------------
149
+
150
+
::: box
151
+
*The following sections are informative.*
152
+
:::
153
+
154
+
#### []{#tag_20_142_16}APPLICATION USAGE {#application-usage .mansect}
155
+
156
+
> One non-intuitive aspect of *unexpand* is its restriction to leading
157
+
> \<space\> characters when neither **-a** nor **-t** is specified.
158
+
> Users who always want to convert all \<space\> characters in a file
159
+
> can easily alias *unexpand* to use the **-a** or **-t 8** option.
160
+
161
+
#### []{#tag_20_142_17}EXAMPLES {#examples .mansect}
162
+
163
+
> None.
164
+
165
+
#### []{#tag_20_142_18}RATIONALE {#rationale .mansect}
166
+
167
+
> On several occasions, consideration was given to adding a **-t**
168
+
> option to the *unexpand* utility to complement the **-t** in
169
+
> [*expand*](../utilities/expand.html) (see
170
+
> [*expand*](../utilities/expand.html#)). The historical intent of
171
+
> *unexpand* was to translate multiple \<blank\> characters into tab
172
+
> stops, where tab stops were a multiple of eight column positions on
173
+
> most UNIX systems. An early proposal omitted **-t** because it seemed
174
+
> outside the scope of the User Portability Utilities option; it was not
175
+
> described in any of the base documents for Base Definitions volume of
176
+
> POSIX.1-2017, [Chapter 7, Locale](../basedefs/V1_chap07.html).
177
+
> However, hard-coding tab stops every eight columns was not suitable
178
+
> for the international community and broke historical precedents for
179
+
> some vendors in the FORTRAN community, so **-t** was restored in
180
+
> conjunction with the list of valid extension categories considered by
181
+
> the standard developers. Thus, *unexpand* is now the logical converse
182
+
> of [*expand*](../utilities/expand.html).
183
+
184
+
#### []{#tag_20_142_19}FUTURE DIRECTIONS {#future-directions .mansect}
185
+
186
+
> None.
187
+
188
+
#### []{#tag_20_142_20}SEE ALSO {#see-also .mansect}
189
+
190
+
> [*expand*](../utilities/expand.html#),
191
+
> [*tabs*](../utilities/tabs.html#)
192
+
>
193
+
> XBD [*Environment Variables*](../basedefs/V1_chap08.html#tag_08),
194
+
> [*Utility Syntax Guidelines*](../basedefs/V1_chap12.html#tag_12_02)
195
+
196
+
#### []{#tag_20_142_21}CHANGE HISTORY {#change-history .mansect}
197
+
198
+
> First released in Issue 4.
199
+
200
+
#### []{#tag_20_142_22}Issue 6 {#issue-6 .mansect}
201
+
202
+
> This utility is marked as part of the User Portability Utilities
203
+
> option.
204
+
>
205
+
> The definition of the *LC_CTYPE* environment variable is changed to
206
+
> align with the IEEE P1003.2b draft standard.
207
+
>
208
+
> The normative text is reworded to avoid use of the term \"must\" for
209
+
> application requirements.
210
+
211
+
#### []{#tag_20_142_23}Issue 7 {#issue-7 .mansect}
212
+
213
+
> The *unexpand* utility is moved from the User Portability Utilities
214
+
> option to the Base. User Portability Utilities is now an option for
215
+
> interactive utilities.
216
+
>
217
+
> SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.
218
+
>
219
+
> POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0198 \[885\] is
220
+
> applied.
221
+
+325
docs/posix2018/uniq.md
+325
docs/posix2018/uniq.md
···
1
+
#### []{#tag_20_144_01}NAME {#name .mansect}
2
+
3
+
> uniq - report or filter out repeated lines in a file
4
+
5
+
#### []{#tag_20_144_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `uniq`` `**`[`**`-c|-d|-u`**`] [`**`-f`` `*`fields`***`] [`**`-s`` `*`char`***`] [`***`input_file`*` `**`[`***`output_file`***`]]`**
8
+
9
+
#### []{#tag_20_144_03}DESCRIPTION {#description .mansect}
10
+
11
+
> The *uniq* utility shall read an input file comparing adjacent lines,
12
+
> and write one copy of each input line on the output. The second and
13
+
> succeeding copies of repeated adjacent input lines shall not be
14
+
> written. The trailing \<newline\> of each line in the input shall be
15
+
> ignored when doing comparisons.
16
+
>
17
+
> Repeated lines in the input shall not be detected if they are not
18
+
> adjacent.
19
+
20
+
#### []{#tag_20_144_04}OPTIONS {#options .mansect}
21
+
22
+
> The *uniq* utility shall conform to XBD [*Utility Syntax
23
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02) , except that `'+'`
24
+
> may be recognized as an option delimiter as well as `'-'`.
25
+
>
26
+
> The following options shall be supported:
27
+
>
28
+
> **-c**
29
+
> : Precede each output line with a count of the number of times the
30
+
> line occurred in the input.
31
+
>
32
+
> **-d**
33
+
> : Suppress the writing of lines that are not repeated in the input.
34
+
>
35
+
> **-f ** *fields*
36
+
>
37
+
> : Ignore the first *fields* fields on each input line when doing
38
+
> comparisons, where *fields* is a positive decimal integer. A field
39
+
> is the maximal string matched by the basic regular expression:
40
+
>
41
+
>
42
+
> [[:blank:]]*[^[:blank:]]*
43
+
>
44
+
> If the *fields* option-argument specifies more fields than appear
45
+
> on an input line, a null string shall be used for comparison.
46
+
>
47
+
> **-s ** *chars*
48
+
> : Ignore the first *chars* characters when doing comparisons, where
49
+
> *chars* shall be a positive decimal integer. If specified in
50
+
> conjunction with the **-f** option, the first *chars* characters
51
+
> after the first *fields* fields shall be ignored. If the *chars*
52
+
> option-argument specifies more characters than remain on an input
53
+
> line, a null string shall be used for comparison.
54
+
>
55
+
> **-u**
56
+
> : Suppress the writing of lines that are repeated in the input.
57
+
58
+
#### []{#tag_20_144_05}OPERANDS {#operands .mansect}
59
+
60
+
> The following operands shall be supported:
61
+
>
62
+
> *input_file*
63
+
> : A pathname of the input file. If the *input_file* operand is not
64
+
> specified, or if the *input_file* is `'-'`, the standard input
65
+
> shall be used.
66
+
>
67
+
> *output_file*
68
+
> : A pathname of the output file. If the *output_file* operand is not
69
+
> specified, the standard output shall be used. The results are
70
+
> unspecified if the file named by *output_file* is the file named
71
+
> by *input_file*.
72
+
73
+
#### []{#tag_20_144_06}STDIN {#stdin .mansect}
74
+
75
+
> The standard input shall be used only if no *input_file* operand is
76
+
> specified or if *input_file* is `'-'`. See the INPUT FILES section.
77
+
78
+
#### []{#tag_20_144_07}INPUT FILES {#input-files .mansect}
79
+
80
+
> The input file shall be a text file.
81
+
82
+
#### []{#tag_20_144_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
83
+
84
+
> The following environment variables shall affect the execution of
85
+
> *uniq*:
86
+
>
87
+
> *LANG*
88
+
> : Provide a default value for the internationalization variables
89
+
> that are unset or null. (See XBD [*Internationalization
90
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
91
+
> precedence of internationalization variables used to determine the
92
+
> values of locale categories.)
93
+
>
94
+
> *LC_ALL*
95
+
> : If set to a non-empty string value, override the values of all the
96
+
> other internationalization variables.
97
+
>
98
+
> *LC_CTYPE*
99
+
> : Determine the locale for the interpretation of sequences of bytes
100
+
> of text data as characters (for example, single-byte as opposed to
101
+
> multi-byte characters in arguments and input files) and which
102
+
> characters constitute a \<blank\> in the current locale.
103
+
>
104
+
> *LC_MESSAGES*
105
+
> : Determine the locale that should be used to affect the format and
106
+
> contents of diagnostic messages written to standard error.
107
+
>
108
+
> *NLSPATH*
109
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
110
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
111
+
> location of message catalogs for the processing of *LC_MESSAGES.*
112
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
113
+
114
+
#### []{#tag_20_144_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
115
+
116
+
> Default.
117
+
118
+
#### []{#tag_20_144_10}STDOUT {#stdout .mansect}
119
+
120
+
> The standard output shall be used if no *output_file* operand is
121
+
> specified, and shall be used if the *output_file* operand is `'-'` and
122
+
> the implementation treats the `'-'` as meaning standard output.
123
+
> Otherwise, the standard output shall not be used. See the OUTPUT FILES
124
+
> section.
125
+
126
+
#### []{#tag_20_144_11}STDERR {#stderr .mansect}
127
+
128
+
> The standard error shall be used only for diagnostic messages.
129
+
130
+
#### []{#tag_20_144_12}OUTPUT FILES {#output-files .mansect}
131
+
132
+
> If the **-c** option is specified, the output file shall be empty or
133
+
> each line shall be of the form:
134
+
>
135
+
>
136
+
> "%d %s", <number of duplicates>, <line>
137
+
>
138
+
> otherwise, the output file shall be empty or each line shall be of the
139
+
> form:
140
+
>
141
+
>
142
+
> "%s", <line>
143
+
144
+
#### []{#tag_20_144_13}EXTENDED DESCRIPTION {#extended-description .mansect}
145
+
146
+
> None.
147
+
148
+
#### []{#tag_20_144_14}EXIT STATUS {#exit-status .mansect}
149
+
150
+
> The following exit values shall be returned:
151
+
>
152
+
> 0
153
+
> : The utility executed successfully.
154
+
>
155
+
> \>0
156
+
> : An error occurred.
157
+
158
+
#### []{#tag_20_144_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
159
+
160
+
> Default.
161
+
162
+
------------------------------------------------------------------------
163
+
164
+
::: box
165
+
*The following sections are informative.*
166
+
:::
167
+
168
+
#### []{#tag_20_144_16}APPLICATION USAGE {#application-usage .mansect}
169
+
170
+
> If the collating sequence of the current locale has a total ordering
171
+
> of all characters, the [*sort*](../utilities/sort.html) utility can be
172
+
> used to cause repeated lines to be adjacent in the input file. If the
173
+
> collating sequence does not have a total ordering of all characters,
174
+
> the [*sort*](../utilities/sort.html) utility should still do this but
175
+
> it might not. To ensure that all duplicate lines are eliminated, and
176
+
> have the output sorted according the collating sequence of the current
177
+
> locale, applications should use:
178
+
>
179
+
>
180
+
> LC_ALL=C sort -u | sort
181
+
>
182
+
> instead of:
183
+
>
184
+
>
185
+
> sort | uniq
186
+
>
187
+
> To remove duplicate lines based on whether they collate equally
188
+
> instead of whether they are identical, applications should use:
189
+
>
190
+
>
191
+
> sort -u
192
+
>
193
+
> instead of:
194
+
>
195
+
>
196
+
> sort | uniq
197
+
>
198
+
> When using *uniq* to process pathnames, it is recommended that LC_ALL,
199
+
> or at least LC_CTYPE and LC_COLLATE, are set to POSIX or C in the
200
+
> environment, since pathnames can contain byte sequences that do not
201
+
> form valid characters in some locales, in which case the utility\'s
202
+
> behavior would be undefined. In the POSIX locale each byte is a valid
203
+
> single-byte character, and therefore this problem is avoided.
204
+
205
+
#### []{#tag_20_144_17}EXAMPLES {#examples .mansect}
206
+
207
+
> The following input file data (but flushed left) was used for a test
208
+
> series on *uniq*:
209
+
>
210
+
>
211
+
> #01 foo0 bar0 foo1 bar1
212
+
> #02 bar0 foo1 bar1 foo1
213
+
> #03 foo0 bar0 foo1 bar1
214
+
> #04
215
+
> #05 foo0 bar0 foo1 bar1
216
+
> #06 foo0 bar0 foo1 bar1
217
+
> #07 bar0 foo1 bar1 foo0
218
+
>
219
+
> What follows is a series of test invocations of the *uniq* utility
220
+
> that use a mixture of *uniq* options against the input file data.
221
+
> These tests verify the meaning of *adjacent*. The *uniq* utility views
222
+
> the input data as a sequence of strings delimited by `'\n'`.
223
+
> Accordingly, for the *fields*th member of the sequence, *uniq*
224
+
> interprets unique or repeated adjacent lines strictly relative to the
225
+
> *fields*+1th member.
226
+
>
227
+
> 1. This first example tests the line counting option, comparing each
228
+
> line of the input file data starting from the second field:
229
+
>
230
+
>
231
+
> uniq -c -f 1 uniq_0I.t
232
+
> 1 #01 foo0 bar0 foo1 bar1
233
+
> 1 #02 bar0 foo1 bar1 foo1
234
+
> 1 #03 foo0 bar0 foo1 bar1
235
+
> 1 #04
236
+
> 2 #05 foo0 bar0 foo1 bar1
237
+
> 1 #07 bar0 foo1 bar1 foo0
238
+
>
239
+
> The number `'2'`, prefixing the fifth line of output, signifies
240
+
> that the *uniq* utility detected a pair of repeated lines. Given
241
+
> the input data, this can only be true when *uniq* is run using the
242
+
> **-f 1** option (which shall cause *uniq* to ignore the first
243
+
> field on each input line).
244
+
>
245
+
> 2. The second example tests the option to suppress unique lines,
246
+
> comparing each line of the input file data starting from the
247
+
> second field:
248
+
>
249
+
>
250
+
> uniq -d -f 1 uniq_0I.t
251
+
> #05 foo0 bar0 foo1 bar1
252
+
>
253
+
> 3. This test suppresses repeated lines, comparing each line of the
254
+
> input file data starting from the second field:
255
+
>
256
+
>
257
+
> uniq -u -f 1 uniq_0I.t
258
+
> #01 foo0 bar0 foo1 bar1
259
+
> #02 bar0 foo1 bar1 foo1
260
+
> #03 foo0 bar0 foo1 bar1
261
+
> #04
262
+
> #07 bar0 foo1 bar1 foo0
263
+
>
264
+
> 4. This suppresses unique lines, comparing each line of the input
265
+
> file data starting from the third character:
266
+
>
267
+
>
268
+
> uniq -d -s 2 uniq_0I.t
269
+
>
270
+
> In the last example, the *uniq* utility found no input matching
271
+
> the above criteria.
272
+
273
+
#### []{#tag_20_144_18}RATIONALE {#rationale .mansect}
274
+
275
+
> Some historical implementations have limited lines to be 1080 bytes in
276
+
> length, which does not meet the implied {LINE_MAX} limit.
277
+
>
278
+
> Earlier versions of this standard allowed the **-** *number* and **+**
279
+
> *number* options. These options are no longer specified by
280
+
> POSIX.1-2017 but may be present in some implementations.
281
+
282
+
#### []{#tag_20_144_19}FUTURE DIRECTIONS {#future-directions .mansect}
283
+
284
+
> None.
285
+
286
+
#### []{#tag_20_144_20}SEE ALSO {#see-also .mansect}
287
+
288
+
> [*comm*](../utilities/comm.html#), [*sort*](../utilities/sort.html#)
289
+
>
290
+
> XBD [*Environment Variables*](../basedefs/V1_chap08.html#tag_08),
291
+
> [*Utility Syntax Guidelines*](../basedefs/V1_chap12.html#tag_12_02)
292
+
293
+
#### []{#tag_20_144_21}CHANGE HISTORY {#change-history .mansect}
294
+
295
+
> First released in Issue 2.
296
+
297
+
#### []{#tag_20_144_22}Issue 6 {#issue-6 .mansect}
298
+
299
+
> The obsolescent SYNOPSIS and associated text are removed.
300
+
>
301
+
> The normative text is reworded to avoid use of the term \"must\" for
302
+
> application requirements.
303
+
>
304
+
> IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/40 is applied, adding
305
+
> *LC_COLLATE* to the ENVIRONMENT VARIABLES section, and changing \"the
306
+
> application shall ensure that\" in the OUTPUT FILES section.
307
+
308
+
#### []{#tag_20_144_23}Issue 7 {#issue-7 .mansect}
309
+
310
+
> Austin Group Interpretation 1003.1-2001 #027 is applied, clarifying
311
+
> that `'+'` may be recognized as an option delimiter in the OPTIONS
312
+
> section.
313
+
>
314
+
> Austin Group Interpretation 1003.1-2001 #092 is applied.
315
+
>
316
+
> Austin Group Interpretation 1003.1-2001 #133 is applied, clarifying
317
+
> the behavior of the trailing \<newline\>.
318
+
>
319
+
> SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.
320
+
>
321
+
> SD5-XCU-ERN-141 is applied, updating the EXAMPLES section.
322
+
>
323
+
> POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0199 \[963\] and
324
+
> XCU/TC2-2008/0200 \[663\] are applied.
325
+
+235
docs/posix2018/wc.md
+235
docs/posix2018/wc.md
···
1
+
#### []{#tag_20_154_01}NAME {#name .mansect}
2
+
3
+
> wc - word, line, and byte or character count
4
+
5
+
#### []{#tag_20_154_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> `wc`` `**`[`**`-c|-m`**`] [`**`-lw`**`] [`***`file`*`...`**`]`**
8
+
9
+
#### []{#tag_20_154_03}DESCRIPTION {#description .mansect}
10
+
11
+
> The *wc* utility shall read one or more input files and, by default,
12
+
> write the number of \<newline\> characters, words, and bytes contained
13
+
> in each input file to the standard output.
14
+
>
15
+
> The utility also shall write a total count for all named files, if
16
+
> more than one input file is specified.
17
+
>
18
+
> The *wc* utility shall consider a *word* to be a non-zero-length
19
+
> string of characters delimited by white space.
20
+
21
+
#### []{#tag_20_154_04}OPTIONS {#options .mansect}
22
+
23
+
> The *wc* utility shall conform to XBD [*Utility Syntax
24
+
> Guidelines*](../basedefs/V1_chap12.html#tag_12_02) .
25
+
>
26
+
> The following options shall be supported:
27
+
>
28
+
> **-c**
29
+
> : Write to the standard output the number of bytes in each input
30
+
> file.
31
+
>
32
+
> **-l**
33
+
> : Write to the standard output the number of \<newline\> characters
34
+
> in each input file.
35
+
>
36
+
> **-m**
37
+
> : Write to the standard output the number of characters in each
38
+
> input file.
39
+
>
40
+
> **-w**
41
+
> : Write to the standard output the number of words in each input
42
+
> file.
43
+
>
44
+
> When any option is specified, *wc* shall report only the information
45
+
> requested by the specified options.
46
+
47
+
#### []{#tag_20_154_05}OPERANDS {#operands .mansect}
48
+
49
+
> The following operand shall be supported:
50
+
>
51
+
> *file*
52
+
> : A pathname of an input file. If no *file* operands are specified,
53
+
> the standard input shall be used.
54
+
55
+
#### []{#tag_20_154_06}STDIN {#stdin .mansect}
56
+
57
+
> The standard input shall be used if no *file* operands are specified,
58
+
> and shall be used if a *file* operand is `'-'` and the implementation
59
+
> treats the `'-'` as meaning standard input. Otherwise, the standard
60
+
> input shall not be used. See the INPUT FILES section.
61
+
62
+
#### []{#tag_20_154_07}INPUT FILES {#input-files .mansect}
63
+
64
+
> The input files may be of any type.
65
+
66
+
#### []{#tag_20_154_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
67
+
68
+
> The following environment variables shall affect the execution of
69
+
> *wc*:
70
+
>
71
+
> *LANG*
72
+
> : Provide a default value for the internationalization variables
73
+
> that are unset or null. (See XBD [*Internationalization
74
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
75
+
> precedence of internationalization variables used to determine the
76
+
> values of locale categories.)
77
+
>
78
+
> *LC_ALL*
79
+
> : If set to a non-empty string value, override the values of all the
80
+
> other internationalization variables.
81
+
>
82
+
> *LC_CTYPE*
83
+
> : Determine the locale for the interpretation of sequences of bytes
84
+
> of text data as characters (for example, single-byte as opposed to
85
+
> multi-byte characters in arguments and input files) and which
86
+
> characters are defined as white-space characters.
87
+
>
88
+
> *LC_MESSAGES*
89
+
> : Determine the locale that should be used to affect the format and
90
+
> contents of diagnostic messages written to standard error and
91
+
> informative messages written to standard output.
92
+
>
93
+
> *NLSPATH*
94
+
> : ^\[[XSI](javascript:open_code('XSI'))\]^ ![\[Option
95
+
> Start\]](../images/opt-start.gif){border="0"} Determine the
96
+
> location of message catalogs for the processing of *LC_MESSAGES.*
97
+
> ![\[Option End\]](../images/opt-end.gif){border="0"}
98
+
99
+
#### []{#tag_20_154_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
100
+
101
+
> Default.
102
+
103
+
#### []{#tag_20_154_10}STDOUT {#stdout .mansect}
104
+
105
+
> By default, the standard output shall contain an entry for each input
106
+
> file of the form:
107
+
>
108
+
>
109
+
> "%d %d %d %s\n", <newlines>, <words>, <bytes>, <file>
110
+
>
111
+
> If the **-m** option is specified, the number of characters shall
112
+
> replace the \<*bytes*\> field in this format.
113
+
>
114
+
> If any options are specified and the **-l** option is not specified,
115
+
> the number of \<newline\> characters shall not be written.
116
+
>
117
+
> If any options are specified and the **-w** option is not specified,
118
+
> the number of words shall not be written.
119
+
>
120
+
> If any options are specified and neither **-c** nor **-m** is
121
+
> specified, the number of bytes or characters shall not be written.
122
+
>
123
+
> If no input *file* operands are specified, no name shall be written
124
+
> and no \<blank\> characters preceding the pathname shall be written.
125
+
>
126
+
> If more than one input *file* operand is specified, an additional line
127
+
> shall be written, of the same format as the other lines, except that
128
+
> the word **total** (in the POSIX locale) shall be written instead of a
129
+
> pathname and the total of each column shall be written as appropriate.
130
+
> Such an additional line, if any, is written at the end of the output.
131
+
132
+
#### []{#tag_20_154_11}STDERR {#stderr .mansect}
133
+
134
+
> The standard error shall be used only for diagnostic messages.
135
+
136
+
#### []{#tag_20_154_12}OUTPUT FILES {#output-files .mansect}
137
+
138
+
> None.
139
+
140
+
#### []{#tag_20_154_13}EXTENDED DESCRIPTION {#extended-description .mansect}
141
+
142
+
> None.
143
+
144
+
#### []{#tag_20_154_14}EXIT STATUS {#exit-status .mansect}
145
+
146
+
> The following exit values shall be returned:
147
+
>
148
+
> 0
149
+
> : Successful completion.
150
+
>
151
+
> \>0
152
+
> : An error occurred.
153
+
154
+
#### []{#tag_20_154_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
155
+
156
+
> Default.
157
+
158
+
------------------------------------------------------------------------
159
+
160
+
::: box
161
+
*The following sections are informative.*
162
+
:::
163
+
164
+
#### []{#tag_20_154_16}APPLICATION USAGE {#application-usage .mansect}
165
+
166
+
> The **-m** option is not a switch, but an option at the same level as
167
+
> **-c**. Thus, to produce the full default output with character counts
168
+
> instead of bytes, the command required is:
169
+
>
170
+
>
171
+
> wc -mlw
172
+
173
+
#### []{#tag_20_154_17}EXAMPLES {#examples .mansect}
174
+
175
+
> None.
176
+
177
+
#### []{#tag_20_154_18}RATIONALE {#rationale .mansect}
178
+
179
+
> The output file format pseudo- [*printf*()](../functions/printf.html)
180
+
> string differs from the System V version of *wc*:
181
+
>
182
+
>
183
+
> "%7d%7d%7d %s\n"
184
+
>
185
+
> which produces possibly ambiguous and unparsable results for very
186
+
> large files, as it assumes no number shall exceed six digits.
187
+
>
188
+
> Some historical implementations use only \<space\>, \<tab\>, and
189
+
> \<newline\> as word separators. The equivalent of the ISO C standard
190
+
> [*isspace*()](../functions/isspace.html) function is more appropriate.
191
+
>
192
+
> The **-c** option stands for \"character\" count, even though it
193
+
> counts bytes. This stems from the sometimes erroneous historical view
194
+
> that bytes and characters are the same size. Due to international
195
+
> requirements, the **-m** option (reminiscent of \"multi-byte\") was
196
+
> added to obtain actual character counts.
197
+
>
198
+
> Early proposals only specified the results when input files were text
199
+
> files. The current specification more closely matches historical
200
+
> practice. (Bytes, words, and \<newline\> characters are counted
201
+
> separately and the results are written when an end-of-file is
202
+
> detected.)
203
+
>
204
+
> Historical implementations of the *wc* utility only accepted one
205
+
> argument to specify the options **-c**, **-l**, and **-w**. Some of
206
+
> them also had multiple occurrences of an option cause the
207
+
> corresponding count to be written multiple times and had the order of
208
+
> specification of the options affect the order of the fields on output,
209
+
> but did not document either of these. Because common usage either
210
+
> specifies no options or only one option, and because none of this was
211
+
> documented, the changes required by this volume of POSIX.1-2017 should
212
+
> not break many historical applications (and do not break any
213
+
> historical conforming applications).
214
+
215
+
#### []{#tag_20_154_19}FUTURE DIRECTIONS {#future-directions .mansect}
216
+
217
+
> None.
218
+
219
+
#### []{#tag_20_154_20}SEE ALSO {#see-also .mansect}
220
+
221
+
> [*cksum*](../utilities/cksum.html#)
222
+
>
223
+
> XBD [*Environment Variables*](../basedefs/V1_chap08.html#tag_08),
224
+
> [*Utility Syntax Guidelines*](../basedefs/V1_chap12.html#tag_12_02)
225
+
226
+
#### []{#tag_20_154_21}CHANGE HISTORY {#change-history .mansect}
227
+
228
+
> First released in Issue 2.
229
+
230
+
#### []{#tag_20_154_22}Issue 7 {#issue-7 .mansect}
231
+
232
+
> Austin Group Interpretation 1003.1-2001 #092 is applied.
233
+
>
234
+
> SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.
235
+
+140
docs/posix2018/zcat.md
+140
docs/posix2018/zcat.md
···
1
+
#### []{#tag_20_160_01}NAME {#name .mansect}
2
+
3
+
> zcat - expand and concatenate data
4
+
5
+
#### []{#tag_20_160_02}SYNOPSIS {#synopsis .mansect}
6
+
7
+
> ::: box
8
+
> ^`[`[`XSI`](javascript:open_code('XSI'))`]`^` `![`[Option Start]`](../images/opt-start.gif){border="0"}` zcat`` `**`[`***`file`*`...`**`]`**![`[Option End]`](../images/opt-end.gif){border="0"}
9
+
> :::
10
+
11
+
#### []{#tag_20_160_03}DESCRIPTION {#description .mansect}
12
+
13
+
> The *zcat* utility shall write to standard output the uncompressed
14
+
> form of files that have been compressed using the
15
+
> [*compress*](../utilities/compress.html) utility. It is the equivalent
16
+
> of [*uncompress*](../utilities/uncompress.html) **-c**. Input files
17
+
> are not affected.
18
+
19
+
#### []{#tag_20_160_04}OPTIONS {#options .mansect}
20
+
21
+
> None.
22
+
23
+
#### []{#tag_20_160_05}OPERANDS {#operands .mansect}
24
+
25
+
> The following operand shall be supported:
26
+
>
27
+
> *file*
28
+
> : The pathname of a file previously processed by the
29
+
> [*compress*](../utilities/compress.html) utility. If *file*
30
+
> already has the **.Z** suffix specified, it is used as submitted.
31
+
> Otherwise, the **.Z** suffix is appended to the filename prior to
32
+
> processing.
33
+
34
+
#### []{#tag_20_160_06}STDIN {#stdin .mansect}
35
+
36
+
> The standard input shall be used only if no *file* operands are
37
+
> specified, or if a *file* operand is `'-'` .
38
+
39
+
#### []{#tag_20_160_07}INPUT FILES {#input-files .mansect}
40
+
41
+
> Input files shall be compressed files that are in the format produced
42
+
> by the [*compress*](../utilities/compress.html) utility.
43
+
44
+
#### []{#tag_20_160_08}ENVIRONMENT VARIABLES {#environment-variables .mansect}
45
+
46
+
> The following environment variables shall affect the execution of
47
+
> *zcat*:
48
+
>
49
+
> *LANG*
50
+
> : Provide a default value for the internationalization variables
51
+
> that are unset or null. (See XBD [*Internationalization
52
+
> Variables*](../basedefs/V1_chap08.html#tag_08_02) for the
53
+
> precedence of internationalization variables used to determine the
54
+
> values of locale categories.)
55
+
>
56
+
> *LC_ALL*
57
+
> : If set to a non-empty string value, override the values of all the
58
+
> other internationalization variables.
59
+
>
60
+
> *LC_CTYPE*
61
+
> : Determine the locale for the interpretation of sequences of bytes
62
+
> of text data as characters (for example, single-byte as opposed to
63
+
> multi-byte characters in arguments).
64
+
>
65
+
> *LC_MESSAGES*
66
+
> : Determine the locale that should be used to affect the format and
67
+
> contents of diagnostic messages written to standard error.
68
+
>
69
+
> *NLSPATH*
70
+
> : Determine the location of message catalogs for the processing of
71
+
> *LC_MESSAGES.*
72
+
73
+
#### []{#tag_20_160_09}ASYNCHRONOUS EVENTS {#asynchronous-events .mansect}
74
+
75
+
> Default.
76
+
77
+
#### []{#tag_20_160_10}STDOUT {#stdout .mansect}
78
+
79
+
> The compressed files given as input shall be written on standard
80
+
> output in their uncompressed form.
81
+
82
+
#### []{#tag_20_160_11}STDERR {#stderr .mansect}
83
+
84
+
> The standard error shall be used only for diagnostic messages.
85
+
86
+
#### []{#tag_20_160_12}OUTPUT FILES {#output-files .mansect}
87
+
88
+
> None.
89
+
90
+
#### []{#tag_20_160_13}EXTENDED DESCRIPTION {#extended-description .mansect}
91
+
92
+
> None.
93
+
94
+
#### []{#tag_20_160_14}EXIT STATUS {#exit-status .mansect}
95
+
96
+
> The following exit values shall be returned:
97
+
>
98
+
> 0
99
+
> : Successful completion.
100
+
>
101
+
> \>0
102
+
> : An error occurred.
103
+
104
+
#### []{#tag_20_160_15}CONSEQUENCES OF ERRORS {#consequences-of-errors .mansect}
105
+
106
+
> Default.
107
+
108
+
------------------------------------------------------------------------
109
+
110
+
::: box
111
+
*The following sections are informative.*
112
+
:::
113
+
114
+
#### []{#tag_20_160_16}APPLICATION USAGE {#application-usage .mansect}
115
+
116
+
> None.
117
+
118
+
#### []{#tag_20_160_17}EXAMPLES {#examples .mansect}
119
+
120
+
> None.
121
+
122
+
#### []{#tag_20_160_18}RATIONALE {#rationale .mansect}
123
+
124
+
> None.
125
+
126
+
#### []{#tag_20_160_19}FUTURE DIRECTIONS {#future-directions .mansect}
127
+
128
+
> None.
129
+
130
+
#### []{#tag_20_160_20}SEE ALSO {#see-also .mansect}
131
+
132
+
> [*compress*](../utilities/compress.html#),
133
+
> [*uncompress*](../utilities/uncompress.html#)
134
+
>
135
+
> XBD [*Environment Variables*](../basedefs/V1_chap08.html#tag_08)
136
+
137
+
#### []{#tag_20_160_21}CHANGE HISTORY {#change-history .mansect}
138
+
139
+
> First released in Issue 4.
140
+