Un outil pour savoir si une commande est posix - retour accueil
git clone git://bebou.netlib.re/isposix
Log | Files | Refs | README |
commit ab66e31bd709609690c1a4208d82e3a342899d9f Auteurice: Arthur Pons <arthur.pons@unistra.fr> Date: Sun, 24 Nov 2024 19:41:26 +0100 Premier commit Je sais pas si à terme je veux les pages de toutes les commandes en html ni qu'elles sont dans ce dépôt git Si jamais un jour je repars de zéro pour ne pas avoir dix mille fichiers html gitté Peut-être un format "md" construit "manuellement" ? Remarque bof parce que cela voudrait dire que isposix ne fonctionne strictement qu'avec ce format plutôt que celui plus "générique" d'opengroup qui, j'imagine, change peu Diffstat:
| A | .gitignore | | | 1 | + |
| A | README | | | 2 | ++ |
| A | bdd/admin.html | | | 365 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/alias.html | | | 282 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/all.html | | | 329 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/ar.html | | | 504 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/asa.html | | | 228 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/at.html | | | 575 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/awk.html | | | 2483 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/basename.html | | | 262 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/batch.html | | | 262 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/bc.html | | | 974 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/bg.html | | | 242 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/c17.html | | | 1041 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/cal.html | | | 203 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/cat.html | | | 271 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/cd.html | | | 418 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/cflow.html | | | 265 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/chgrp.html | | | 246 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/chmod.html | | | 556 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/chown.html | | | 277 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/cksum.html | | | 344 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/cmp.html | | | 266 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/comm.html | | | 275 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/command.html | | | 457 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/compress.html | | | 627 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/cp.html | | | 515 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/crontab.html | | | 321 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/csplit.html | | | 280 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/ctags.html | | | 354 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/cut.html | | | 319 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/cxref.html | | | 233 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/date.html | | | 364 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/dd.html | | | 480 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/delta.html | | | 317 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/df.html | | | 300 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/diff.html | | | 546 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/dirname.html | | | 228 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/du.html | | | 267 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/echo.html | | | 285 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/ed.html | | | 1503 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/env.html | | | 277 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/ex.html | | | 3808 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/expand.html | | | 221 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/expr.html | | | 453 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/false.html | | | 143 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/fc.html | | | 378 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/fg.html | | | 208 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/file.html | | | 689 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/find.html | | | 700 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/fold.html | | | 248 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/fuser.html | | | 277 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/gencat.html | | | 343 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/get.html | | | 801 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/getconf.html | | | 365 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/getopts.html | | | 351 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/gettext.html | | | 439 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/grep.html | | | 371 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/hash.html | | | 228 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/head.html | | | 242 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/iconv.html | | | 264 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/id.html | | | 276 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/ipcrm.html | | | 201 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/ipcs.html | | | 448 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/jobs.html | | | 326 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/join.html | | | 351 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/kill.html | | | 373 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/lex.html | | | 860 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/link.html | | | 182 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/ln.html | | | 343 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/locale.html | | | 388 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/localedef.html | | | 316 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/logger.html | | | 266 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/logname.html | | | 173 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/lp.html | | | 355 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/ls.html | | | 700 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/m4.html | | | 635 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/mailx.html | | | 1654 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/make.html | | | 1806 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/man.html | | | 266 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/mesg.html | | | 207 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/mkdir.html | | | 258 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/mkfifo.html | | | 215 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/more.html | | | 830 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/msgfmt.html | | | 447 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/mv.html | | | 385 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/newgrp.html | | | 280 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/ngettext.html | | | 439 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/nice.html | | | 265 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/nl.html | | | 315 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/nm.html | | | 363 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/nohup.html | | | 248 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/od.html | | | 760 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/paste.html | | | 288 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/patch.html | | | 447 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/pathchk.html | | | 360 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/pax.html | | | 2739 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/pr.html | | | 402 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/printf.html | | | 675 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/prs.html | | | 1216 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/ps.html | | | 718 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/pwd.html | | | 220 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/read.html | | | 323 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/readlink.html | | | 186 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/realpath.html | | | 239 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/renice.html | | | 269 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/rm.html | | | 374 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/rmdel.html | | | 214 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/rmdir.html | | | 213 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/sact.html | | | 211 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/sccs.html | | | 347 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/sed.html | | | 662 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/sh.html | | | 1012 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/sleep.html | | | 206 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/sort.html | | | 503 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/split.html | | | 270 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/strings.html | | | 244 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/strip.html | | | 200 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/stty.html | | | 938 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/tabs.html | | | 284 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/tail.html | | | 320 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/talk.html | | | 277 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/tee.html | | | 218 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/test.html | | | 584 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/time.html | | | 329 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/timeout.html | | | 319 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/touch.html | | | 451 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/tput.html | | | 247 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/tr.html | | | 442 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/true.html | | | 175 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/tsort.html | | | 226 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/tty.html | | | 195 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/type.html | | | 194 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/ulimit.html | | | 317 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/umask.html | | | 286 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/unalias.html | | | 206 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/uname.html | | | 215 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/uncompress.html | | | 627 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/unexpand.html | | | 227 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/unget.html | | | 218 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/uniq.html | | | 306 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/unlink.html | | | 175 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/uucp.html | | | 284 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/uudecode.html | | | 239 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/uuencode.html | | | 944 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/uustat.html | | | 214 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/uux.html | | | 285 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/val.html | | | 333 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/vi.html | | | 3314 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/wait.html | | | 304 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/wc.html | | | 239 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/what.html | | | 229 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/who.html | | | 317 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/write.html | | | 248 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/xargs.html | | | 479 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/xgettext.html | | | 315 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/yacc.html | | | 962 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | bdd/zcat.html | | | 627 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | isposix | | | 61 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
159 files changed, 73512 insertions(+), 0 deletions(-)
diff --git a/.gitignore b/.gitignore @@ -0,0 +1 @@ +.*.sw? diff --git a/README b/README @@ -0,0 +1,2 @@ +Script pour vérifier si une commande et/ou une option de cette commande sont +posix ou pas diff --git a/bdd/admin.html b/bdd/admin.html @@ -0,0 +1,365 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>admin</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/V3_chap03.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/alias.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="admin" id="admin"></a> <a name="tag_20_01" id="tag_20_01"></a><!-- admin --> +<h4 class="mansect"><a name="tag_20_01_01" id="tag_20_01_01"></a>NAME</h4> +<blockquote>admin — create and administer SCCS files (<b>DEVELOPMENT</b>)</blockquote> +<h4 class="mansect"><a name="tag_20_01_02" id="tag_20_01_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> admin -i</tt><b>[</b><i>name</i><b>] [</b><tt>-n</tt><b>] [</b><tt>-a</tt> <i>login</i><b>] +[</b><tt>-d</tt> <i>flag</i><b>] [</b><tt>-e</tt> <i>login</i><b>] [</b><tt>-f</tt> <i>flag</i><b>]<br></b> +<tt> </tt> <b>[</b><tt>-m</tt> <i>mrlist</i><b>] [</b><tt>-r</tt> <i>rel</i><b>] +[</b><tt>-t</tt><b>[</b><i>name</i><b>] [</b><tt>-y</tt><b>[</b><i>comment</i><b>]]</b> <i>newfile</i> <tt><br> +<br> +admin -n</tt> <b>[</b><tt>-a</tt> <i>login</i><b>] [</b><tt>-d</tt> <i>flag</i><b>] [</b><tt>-e</tt> <i>login</i><b>] +[</b><tt>-f</tt> <i>flag</i><b>] [</b><tt>-m</tt> <i>mrlist</i><b>]<br></b> <tt> </tt> +<b>[</b><tt>-t</tt><b>[</b><i>name</i><b>]] [</b><tt>-y</tt><b>[</b><i>comment</i><b>]]</b> <i>newfile</i><tt>...<br> +<br> +admin</tt> <b>[</b><tt>-a</tt> <i>login</i><b>] [</b><tt>-d</tt> <i>flag</i><b>] [</b><tt>-m</tt> <i>mrlist</i><b>] +[</b><tt>-r</tt> <i>rel</i><b>] [</b><tt>-t</tt><b>[</b><i>name</i><b>]]</b> <i>file</i><tt>...<br> +<br> +admin -h</tt> <i>file</i><tt>...<br> +<br> +admin -z</tt> <i>file</i><tt>... <img src="../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div> +<tt><br></tt></blockquote> +<h4 class="mansect"><a name="tag_20_01_03" id="tag_20_01_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>admin</i> utility shall create new SCCS files or change parameters of existing ones. If a named file does not exist, it +shall be created, and its parameters shall be initialized according to the specified options. Parameters not initialized by an +option shall be assigned a default value. If a named file does exist, parameters corresponding to specified options shall be +changed, and other parameters shall be left as is.</p> +<p>All SCCS filenames supplied by the application shall be of the form s.<i>filename</i>. New SCCS files shall be given read-only +permission mode. Write permission in the parent directory is required to create a file. All writing done by <i>admin</i> shall be +to a temporary <i>x-file</i>, named x.<i>filename</i> (see <a href="../utilities/get.html#"><i>get</i></a> ) created with read-only +mode if <i>admin</i> is creating a new SCCS file, or created with the same mode as that of the SCCS file if the file already +exists. After successful execution of <i>admin</i>, the SCCS file shall be removed (if it exists), and the <i>x-file</i> shall be +renamed with the name of the SCCS file. This ensures that changes are made to the SCCS file only if no errors occur.</p> +<p>The <i>admin</i> utility shall also use a transient lock file (named z.<i>filename</i>), which is used to prevent simultaneous +updates to the SCCS file; see <a href="../utilities/get.html#"><i>get</i></a> .</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_01_04" id="tag_20_01_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>admin</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> , except that the <b>-i</b>, <b>-t</b>, and <b>-y</b> options have optional option-arguments. These optional +option-arguments shall not be presented as separate arguments. The following options are supported:</p> +<dl compact> +<dd></dd> +<dt><b>-n</b></dt> +<dd>Create a new SCCS file. When <b>-n</b> is used without <b>-i</b>, the SCCS file shall be created with control information but +without any file data.</dd> +<dt><b>-i[</b><i>name</i><b>]</b></dt> +<dd>Specify the <i>name</i> of a file from which the text for a new SCCS file shall be taken. The text constitutes the first delta +of the file (see the <b>-r</b> option for the delta numbering scheme). If the <b>-i</b> option is used, but the <i>name</i> +option-argument is omitted, the text shall be obtained by reading the standard input. If this option is omitted, the SCCS file +shall be created with control information but without any file data. The <b>-i</b> option implies the <b>-n</b> option.</dd> +<dt><b>-r </b><i>SID</i></dt> +<dd>Specify the SID of the initial delta to be inserted. This SID shall be a trunk SID; that is, the branch and sequence numbers +shall be zero or missing. The level number is optional, and defaults to 1.</dd> +<dt><b>-t[</b><i>name</i><b>]</b></dt> +<dd>Specify the <i>name</i> of a file from which descriptive text for the SCCS file shall be taken. In the case of existing SCCS +files (neither <b>-i</b> nor <b>-n</b> is specified): +<ul> +<li> +<p>A <b>-t</b> option without a <i>name</i> option-argument shall cause the removal of descriptive text (if any) currently in the +SCCS file.</p> +</li> +<li> +<p>A <b>-t</b> option with a <i>name</i> option-argument shall cause the text (if any) in the named file to replace the descriptive +text (if any) currently in the SCCS file.</p> +</li> +</ul> +</dd> +<dt><b>-f </b><i>flag</i></dt> +<dd>Specify a <i>flag</i>, and, possibly, a value for the <i>flag</i>, to be placed in the SCCS file. Several <b>-f</b> options may +be supplied on a single <i>admin</i> command line. Implementations shall recognize the following flags and associated values: +<dl compact> +<dd></dd> +<dt><b>b</b></dt> +<dd>Allow use of the <b>-b</b> option on a <a href="../utilities/get.html"><i>get</i></a> command to create branch deltas.</dd> +<dt><b>c</b><i>ceil</i></dt> +<dd>Specify the highest release (that is, ceiling), a number less than or equal to 9999, which may be retrieved by a <a href= +"../utilities/get.html"><i>get</i></a> command for editing. The default value for an unspecified <b>c</b> flag shall be 9999.</dd> +<dt><b>f</b><i>floor</i></dt> +<dd>Specify the lowest release (that is, floor), a number greater than 0 but less than 9999, which may be retrieved by a <a href= +"../utilities/get.html"><i>get</i></a> command for editing. The default value for an unspecified <b>f</b> flag shall be 1.</dd> +<dt><b>d</b><i>SID</i></dt> +<dd>Specify the default delta number (SID) to be used by a <a href="../utilities/get.html"><i>get</i></a> command.</dd> +<dt><b>i</b><i>str</i></dt> +<dd>Treat the "No ID keywords" message issued by <a href="../utilities/get.html"><i>get</i></a> or <a href= +"../utilities/delta.html"><i>delta</i></a> as a fatal error. In the absence of this flag, the message is only a warning. The +message is issued if no SCCS identification keywords (see <a href="../utilities/get.html#"><i>get</i></a> ) are found in the text +retrieved or stored in the SCCS file. If a value is supplied, the application shall ensure that the keywords exactly match the +given string; however, the string shall contain a keyword, and no embedded <newline> characters.</dd> +<dt><b>j</b></dt> +<dd>Allow concurrent <a href="../utilities/get.html"><i>get</i></a> commands for editing on the same SID of an SCCS file. This +allows multiple concurrent updates to the same version of the SCCS file.</dd> +<dt><b>l</b><i>list</i></dt> +<dd>Specify a <i>list</i> of releases to which deltas can no longer be made (that is, <a href= +"../utilities/get.html"><i>get</i></a> <b>-e</b> against one of these locked releases fails). Conforming applications shall use the +following syntax to specify a <i>list</i>. Implementations may accept additional forms as an extension: +<pre> +<tt><list> ::= a | <range-list> +<range-list> ::= <range> | <range-list>, <range> +<range> ::= <SID> +</tt></pre> +<p>The character <i>a</i> in the <i>list</i> shall be equivalent to specifying all releases for the named SCCS file. The +non-terminal <<i>SID</i>> in range shall be the delta number of an existing delta associated with the SCCS file.</p> +</dd> +<dt><b>n</b></dt> +<dd>Cause <a href="../utilities/delta.html"><i>delta</i></a> to create a null delta in each of those releases (if any) being +skipped when a delta is made in a new release (for example, in making delta 5.1 after delta 2.7, releases 3 and 4 are skipped). +These null deltas shall serve as anchor points so that branch deltas may later be created from them. The absence of this flag shall +cause skipped releases to be nonexistent in the SCCS file, preventing branch deltas from being created from them in the future. +During the initial creation of an SCCS file, the <b>n</b> flag may be ignored; that is, if the <b>-r</b> option is used to set the +release number of the initial SID to a value greater than 1, null deltas need not be created for the "skipped" releases.</dd> +<dt><b>q</b><i>text</i></dt> +<dd>Substitute user-definable <i>text</i> for all occurrences of the %<b>Q</b>% keyword in the SCCS file text retrieved by <a href= +"../utilities/get.html"><i>get</i></a>.</dd> +<dt><b>m</b><i>mod</i></dt> +<dd>Specify the module name of the SCCS file substituted for all occurrences of the %<b>M</b>% keyword in the SCCS file text +retrieved by <a href="../utilities/get.html"><i>get</i></a>. If the <b>m</b> flag is not specified, the value assigned shall be the +name of the SCCS file with the leading <tt>'.'</tt> removed.</dd> +<dt><b>t</b><i>type</i></dt> +<dd>Specify the <i>type</i> of module in the SCCS file substituted for all occurrences of the %<b>Y</b>% keyword in the SCCS file +text retrieved by <a href="../utilities/get.html"><i>get</i></a>.</dd> +<dt><b>v</b><i>pgm</i></dt> +<dd>Cause <a href="../utilities/delta.html"><i>delta</i></a> to prompt for modification request (MR) numbers as the reason for +creating a delta. The optional value specifies the name of an MR number validation program. (If this flag is set when creating an +SCCS file, the application shall ensure that the <b>m</b> option is also used even if its value is null.)</dd> +</dl> +</dd> +<dt><b>-d </b><i>flag</i></dt> +<dd>Remove (delete) the specified <i>flag</i> from an SCCS file. Several <b>-d</b> options may be supplied on a single <i>admin</i> +command. See the <b>-f</b> option for allowable <i>flag</i> names. (The <b>l</b><i>list</i> flag gives a <i>list</i> of releases to +be unlocked. See the <b>-f</b> option for further description of the <b>l</b> flag and the syntax of a <i>list</i>.)</dd> +<dt><b>-a </b><i>login</i></dt> +<dd>Specify a <i>login</i> name, or numerical group ID, to be added to the list of users who may make deltas (changes) to the SCCS +file. A group ID shall be equivalent to specifying all <i>login</i> names common to that group ID. Several <b>-a</b> options may be +used on a single <i>admin</i> command line. As many <i>login</i>s, or numerical group IDs, as desired may be on the list +simultaneously. If the list of users is empty, then anyone may add deltas. If <i>login</i> or group ID is preceded by a +<tt>'!'</tt>, the users so specified shall be denied permission to make deltas.</dd> +<dt><b>-e </b><i>login</i></dt> +<dd>Specify a <i>login</i> name, or numerical group ID, to be erased from the list of users allowed to make deltas (changes) to the +SCCS file. Specifying a group ID is equivalent to specifying all <i>login</i> names common to that group ID. Several <b>-e</b> +options may be used on a single <i>admin</i> command line.</dd> +<dt><b>-y[</b><i>comment</i><b>]</b></dt> +<dd>Insert the <i>comment</i> text into the SCCS file as a comment for the initial delta in a manner identical to that of <a href= +"../utilities/delta.html"><i>delta</i></a>. In the POSIX locale, omission of the <b>-y</b> option shall result in a default comment +line being inserted in the form: +<pre> +<tt>"date and time created %s %s by %s", <</tt><i>date</i><tt>>, <</tt><i>time</i><tt>>, <</tt><i>login</i><tt>> +</tt></pre> +<p>where <<i>date</i>> is expressed in the format of the <a href="../utilities/date.html"><i>date</i></a> utility's +<tt>%y</tt>/<tt>%m</tt>/<tt>%d</tt> conversion specification, <<i>time</i>> in the format of the <a href= +"../utilities/date.html"><i>date</i></a> utility's <tt>%T</tt> conversion specification format, and <<i>login</i>> is the +login name of the user creating the file.</p> +</dd> +<dt><b>-m </b><i>mrlist</i></dt> +<dd>Insert the list of modification request (MR) numbers into the SCCS file as the reason for creating the initial delta in a +manner identical to <a href="../utilities/delta.html"><i>delta</i></a>. The application shall ensure that the <b>v</b> flag is set +and the MR numbers are validated if the <b>v</b> flag has a value (the name of an MR number validation program). A diagnostic +message shall be written if the <b>v</b> flag is not set or MR validation fails.</dd> +<dt><b>-h</b></dt> +<dd>Check the structure of the SCCS file and compare the newly computed checksum with the checksum that is stored in the SCCS file. +If the newly computed checksum does not match the checksum in the SCCS file, a diagnostic message shall be written.</dd> +<dt><b>-z</b></dt> +<dd>Recompute the SCCS file checksum and store it in the first line of the SCCS file (see the <b>-h</b> option above). Note that +use of this option on a truly corrupted file may prevent future detection of the corruption.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_01_05" id="tag_20_01_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of an existing SCCS file or a directory. If <i>file</i> is a directory, the <i>admin</i> utility shall behave as +though each file in the directory were specified as a named file, except that non-SCCS files (last component of the pathname does +not begin with <b>s.</b>) and unreadable files shall be silently ignored.</dd> +<dt><i>newfile</i></dt> +<dd>A pathname of an SCCS file to be created.</dd> +</dl> +<p>If exactly one <i>file</i> or <i>newfile</i> operand appears, and it is <tt>'-'</tt>, the standard input shall be read; each +line of the standard input shall be taken to be the name of an SCCS file to be processed. Non-SCCS files and unreadable files shall +be silently ignored.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_01_06" id="tag_20_01_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be a text file used only if <b>-i</b> is specified without an option-argument or if a <i>file</i> or +<i>newfile</i> operand is specified as <tt>'-'</tt>. If the first character of any standard input line is <SOH> in the POSIX +locale, the results are unspecified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_01_07" id="tag_20_01_07"></a>INPUT FILES</h4> +<blockquote> +<p>The existing SCCS files shall be text files of an unspecified format.</p> +<p>The application shall ensure that the file named by the <b>-i</b> option's <i>name</i> option-argument shall be a text file; if +the first character of any line in this file is <SOH> in the POSIX locale, the results are unspecified. If this file contains +more than 99999 lines, the number of lines recorded in the header for this file shall be 99999 for this delta.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_01_08" id="tag_20_01_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>admin</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error and the +contents of the default <b>-y</b> comment.</dd> +<dt><i>NLSPATH</i></dt> +<dd>Determine the location of messages objects and message catalogs.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_01_09" id="tag_20_01_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_01_10" id="tag_20_01_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_01_11" id="tag_20_01_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_01_12" id="tag_20_01_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>Any SCCS files created shall be text files of an unspecified format. During processing of a <i>file</i>, a locking +<i>z-file</i>, as described in <a href="../utilities/get.html#"><i>get</i></a> , may be created and deleted.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_01_13" id="tag_20_01_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_01_14" id="tag_20_01_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_01_15" id="tag_20_01_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_01_16" id="tag_20_01_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>It is recommended that directories containing SCCS files be writable by the owner only, and that SCCS files themselves be +read-only. The mode of the directories should allow only the owner to modify SCCS files contained in the directories. The mode of +the SCCS files prevents any modification at all except by SCCS commands.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_01_17" id="tag_20_01_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_01_18" id="tag_20_01_18"></a>RATIONALE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_01_19" id="tag_20_01_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +<p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a +<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require +implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_01_20" id="tag_20_01_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/delta.html#"><i>delta</i></a> , <a href="../utilities/get.html#"><i>get</i></a> , <a href= +"../utilities/prs.html#"><i>prs</i></a> , <a href="../utilities/what.html#"><i>what</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_01_21" id="tag_20_01_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_01_22" id="tag_20_01_22"></a>Issue 6</h4> +<blockquote> +<p>The normative text is reworded to avoid use of the term "must" for application requirements, and to emphasize the term +"shall" for implementation requirements.</p> +<p>The grammar is updated.</p> +<p>The Open Group Base Resolution bwg2001-007 is applied, adding new text to the INPUT FILES section warning that the maximum lines +recorded in the file is 99999.</p> +<p>The Open Group Base Resolution bwg2001-009 is applied, amending the description of the <b>-h</b> option.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_01_23" id="tag_20_01_23"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to behave as follows:</p> +<ol type="a"> +<li> +<p>Report an error if a utility is directed to display a pathname that contains any bytes that have the encoded value of a +<newline> character when <newline> is a terminator or separator in the output format being used.</p> +</li> +<li> +<p>Disallow the creation of filenames containing any bytes that have the encoded value of a <newline> character.</p> +</li> +</ol> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/V3_chap03.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/alias.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/alias.html b/bdd/alias.html @@ -0,0 +1,282 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>alias</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/admin.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/ar.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="alias" id="alias"></a> <a name="tag_20_02" id="tag_20_02"></a><!-- alias --> +<h4 class="mansect"><a name="tag_20_02_01" id="tag_20_02_01"></a>NAME</h4> +<blockquote>alias — define or display aliases</blockquote> +<h4 class="mansect"><a name="tag_20_02_02" id="tag_20_02_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>alias</tt> <b>[</b><i>alias-name</i><b>[</b><tt>=</tt><i>string</i><b>]</b><tt>...</tt><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_02_03" id="tag_20_02_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>alias</i> utility shall create or redefine alias definitions or write the values of existing alias definitions to +standard output. An alias definition provides a string value that shall replace a command name when it is encountered. For +information on valid string values, and the processing involved, see <a href="../utilities/V3_chap02.html#tag_19_03_01"><i>2.3.1 +Alias Substitution</i></a> .</p> +<p>An alias definition shall affect the current shell execution environment and the execution environments of the subshells of the +current shell. When used as specified by this volume of POSIX.1-2024, the alias definition shall not affect the parent process of +the current shell nor any utility environment invoked by the shell; see <a href="../utilities/V3_chap02.html#tag_19_13"><i>2.13 +Shell Execution Environment</i></a> .</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_02_04" id="tag_20_02_04"></a>OPTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_02_05" id="tag_20_02_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>alias-name</i></dt> +<dd>Write the alias definition to standard output.</dd> +<dt><i>alias-name</i>=<i>string</i></dt> +<dd><br> +Assign the value of <i>string</i> to the alias <i>alias-name</i>.</dd> +</dl> +<p>If no operands are given, all alias definitions shall be written to standard output.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_02_06" id="tag_20_02_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_02_07" id="tag_20_02_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_02_08" id="tag_20_02_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>alias</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_02_09" id="tag_20_02_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_02_10" id="tag_20_02_10"></a>STDOUT</h4> +<blockquote> +<p>The format for displaying aliases (when no operands or only <i>name</i> operands are specified) shall be:</p> +<pre> +<tt>"%s=%s\n", </tt><i>name</i><tt>, </tt><i>value</i><tt> +</tt></pre> +<p>The <i>value</i> string shall be written with appropriate quoting so that it is suitable for reinput to the shell. See the +description of shell quoting in <a href="../utilities/V3_chap02.html#tag_19_02"><i>2.2 Quoting</i></a> .</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_02_11" id="tag_20_02_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_02_12" id="tag_20_02_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_02_13" id="tag_20_02_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_02_14" id="tag_20_02_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>One of the <i>name</i> operands specified did not have an alias definition, or an error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_02_15" id="tag_20_02_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_02_16" id="tag_20_02_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>This utility is required to be intrinsic. See <a href="../utilities/V3_chap01.html#tag_18_07"><i>1.7 Intrinsic Utilities</i></a> +for details.</p> +<p>Care should be taken to avoid alias values that end with a character that could be treated as part of an operator token, as it +is unspecified whether the character that follows the alias name in the input can be used as part of the same token (see <a href= +"../utilities/V3_chap02.html#tag_19_03_01"><i>2.3.1 Alias Substitution</i></a> ). For example, with:</p> +<pre> +<tt>$ alias foo='echo 0' +$ foo>&2 +</tt></pre> +the shell can either pass the argument <tt>'0'</tt> to <a href="../utilities/echo.html"><i>echo</i></a> and redirect fd 1 to fd 2, +or pass no arguments to <a href="../utilities/echo.html"><i>echo</i></a> and redirect fd 0 to fd 2. Changing it to: +<pre> +<tt>$ alias foo='echo "0"' +</tt></pre> +avoids this problem. The alternative of adding a <space> after the <tt>'0'</tt> would also avoid the problem, but in addition +it would alter the way the alias works, as described in <a href="../utilities/V3_chap02.html#tag_19_03_01"><i>2.3.1 Alias +Substitution</i></a> . +<p>Likewise, given:</p> +<pre> +<tt>$ alias foo='some_command &' +$ foo& +</tt></pre> +the shell may combine the two <tt>'&'</tt> characters into an <tt>&&</tt> (and) operator. Since the alias cannot pass +arguments to <i>some_command</i> and thus can be expected to be invoked without arguments, adding a <space> after the +<tt>'&'</tt> would be an acceptable way to prevent this. Alternatively, the alias could be specified as a grouping command: +<pre> +<tt>$ alias foo='{ some_command & }' +</tt></pre> +<p>Problems can occur for tokens other than operators as well, if the alias is used in unusual ways. For example, with:</p> +<pre> +<tt>$ alias foo='echo $' +$ foo((123)) +</tt></pre> +some shells combine the <tt>'$'</tt> and the <tt>"((123))"</tt> to form an arithmetic expansion, but others do not (resulting in a +syntax error).</blockquote> +<h4 class="mansect"><a name="tag_20_02_17" id="tag_20_02_17"></a>EXAMPLES</h4> +<blockquote> +<ol> +<li> +<p>Create a short alias for a commonly used <a href="../utilities/ls.html"><i>ls</i></a> command:</p> +<pre> +<tt>alias lf="ls -CF" +</tt></pre></li> +<li> +<p>Create a simple "redo" command to repeat previous entries in the command history file:</p> +<pre> +<tt>alias r='fc -s' +</tt></pre></li> +<li> +<p>Use 1K units for <a href="../utilities/du.html"><i>du</i></a>:</p> +<pre> +<tt>alias du=du\ -k +</tt></pre></li> +<li> +<p>Set up <a href="../utilities/nohup.html"><i>nohup</i></a> so that it can deal with an argument that is itself an alias name:</p> +<pre> +<tt>alias nohup="nohup " +</tt></pre></li> +<li> +<p>Add the <b>-F</b> option to interactive uses of <a href="../utilities/ls.html"><i>ls</i></a>, even when executed as +<tt>xargs ls</tt> or <tt>xargs -0 ls</tt>:</p> +<pre> +<tt>alias ls='ls -F' +alias xargs='xargs ' +alias -- -0='-0 ' +find . [...] -print | xargs ls # breaks on filenames with \n + # (two aliases expanded) +find . [...] -print0 | xargs -0 ls # minimizes \n issues (three + # aliases expanded) +</tt></pre></li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_02_18" id="tag_20_02_18"></a>RATIONALE</h4> +<blockquote> +<p>The <i>alias</i> description is based on historical KornShell implementations. Known differences exist between that and the C +shell. The KornShell version was adopted to be consistent with all the other KornShell features in this volume of POSIX.1-2024, +such as command line editing.</p> +<p>Since <i>alias</i> affects the current shell execution environment, it is generally provided as a shell regular built-in.</p> +<p>Historical versions of the KornShell have allowed aliases to be exported to scripts that are invoked by the same shell. This is +triggered by the <i>alias</i> <b>-x</b> flag; it is allowed by this volume of POSIX.1-2024 only when an explicit extension such as +<b>-x</b> is used. The standard developers considered that aliases were of use primarily to interactive users and that they should +normally not affect shell scripts called by those users; functions are available to such scripts.</p> +<p>Historical versions of the KornShell had not written aliases in a quoted manner suitable for reentry to the shell, but this +volume of POSIX.1-2024 has made this a requirement for all similar output. Therefore, consistency was chosen over this detail of +historical practice.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_02_19" id="tag_20_02_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_02_20" id="tag_20_02_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19_09_05"><i>2.9.5 Function Definition Command</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_02_21" id="tag_20_02_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_02_22" id="tag_20_02_22"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +<p>The APPLICATION USAGE section is added.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_02_23" id="tag_20_02_23"></a>Issue 7</h4> +<blockquote> +<p>The <i>alias</i> utility is moved from the User Portability Utilities option to the Base. User Portability Utilities is now an +option for interactive utilities.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>The first example is changed to remove the creation of an alias for a standard utility that alters its behavior to be +non-conforming.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_02_24" id="tag_20_02_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 854 is applied, adding a note to the APPLICATION USAGE section that this utility is required to be +intrinsic.</p> +<p>Austin Group Defect 953 is applied, clarifying that the details of how alias replacement is performed are in the +cross-referenced section ( <a href="../utilities/V3_chap02.html#tag_19_03_01"><i>2.3.1 Alias Substitution</i></a> ) and updating +the APPLICATION USAGE section.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1630 is applied, adding a new item in EXAMPLES.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/admin.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/ar.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/all.html b/bdd/all.html @@ -0,0 +1,329 @@ +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy, see www.w3.org"> +<link type="text/css" rel="stylesheet" href="../utilities/style.css"> +<title>Utilities</title> +</head> +<body bgcolor="white"> +<basefont size="3"> + +<h2>Utilities</h2> + + +<ul> +<li><a href="../utilities/admin.html" target="main">admin</a> +</li> +<li><a href="../utilities/alias.html" target="main">alias</a> +</li> +<li><a href="../utilities/ar.html" target="main">ar</a> +</li> +<li><a href="../utilities/asa.html" target="main">asa</a> +</li> +<li><a href="../utilities/at.html" target="main">at</a> +</li> +<li><a href="../utilities/awk.html" target="main">awk</a> +</li> +<li><a href="../utilities/basename.html" target="main">basename</a> +</li> +<li><a href="../utilities/batch.html" target="main">batch</a> +</li> +<li><a href="../utilities/bc.html" target="main">bc</a> +</li> +<li><a href="../utilities/bg.html" target="main">bg</a> +</li> +<li><a href="../utilities/c17.html" target="main">c17</a> +</li> +<li><a href="../utilities/cal.html" target="main">cal</a> +</li> +<li><a href="../utilities/cat.html" target="main">cat</a> +</li> +<li><a href="../utilities/cd.html" target="main">cd</a> +</li> +<li><a href="../utilities/cflow.html" target="main">cflow</a> +</li> +<li><a href="../utilities/chgrp.html" target="main">chgrp</a> +</li> +<li><a href="../utilities/chmod.html" target="main">chmod</a> +</li> +<li><a href="../utilities/chown.html" target="main">chown</a> +</li> +<li><a href="../utilities/cksum.html" target="main">cksum</a> +</li> +<li><a href="../utilities/cmp.html" target="main">cmp</a> +</li> +<li><a href="../utilities/comm.html" target="main">comm</a> +</li> +<li><a href="../utilities/command.html" target="main">command</a> +</li> +<li><a href="../utilities/compress.html" target="main">compress</a> +</li> +<li><a href="../utilities/cp.html" target="main">cp</a> +</li> +<li><a href="../utilities/crontab.html" target="main">crontab</a> +</li> +<li><a href="../utilities/csplit.html" target="main">csplit</a> +</li> +<li><a href="../utilities/ctags.html" target="main">ctags</a> +</li> +<li><a href="../utilities/cut.html" target="main">cut</a> +</li> +<li><a href="../utilities/cxref.html" target="main">cxref</a> +</li> +<li><a href="../utilities/date.html" target="main">date</a> +</li> +<li><a href="../utilities/dd.html" target="main">dd</a> +</li> +<li><a href="../utilities/delta.html" target="main">delta</a> +</li> +<li><a href="../utilities/df.html" target="main">df</a> +</li> +<li><a href="../utilities/diff.html" target="main">diff</a> +</li> +<li><a href="../utilities/dirname.html" target="main">dirname</a> +</li> +<li><a href="../utilities/du.html" target="main">du</a> +</li> +<li><a href="../utilities/echo.html" target="main">echo</a> +</li> +<li><a href="../utilities/ed.html" target="main">ed</a> +</li> +<li><a href="../utilities/env.html" target="main">env</a> +</li> +<li><a href="../utilities/ex.html" target="main">ex</a> +</li> +<li><a href="../utilities/expand.html" target="main">expand</a> +</li> +<li><a href="../utilities/expr.html" target="main">expr</a> +</li> +<li><a href="../utilities/false.html" target="main">false</a> +</li> +<li><a href="../utilities/fc.html" target="main">fc</a> +</li> +<li><a href="../utilities/fg.html" target="main">fg</a> +</li> +<li><a href="../utilities/file.html" target="main">file</a> +</li> +<li><a href="../utilities/find.html" target="main">find</a> +</li> +<li><a href="../utilities/fold.html" target="main">fold</a> +</li> +<li><a href="../utilities/fuser.html" target="main">fuser</a> +</li> +<li><a href="../utilities/gencat.html" target="main">gencat</a> +</li> +<li><a href="../utilities/get.html" target="main">get</a> +</li> +<li><a href="../utilities/getconf.html" target="main">getconf</a> +</li> +<li><a href="../utilities/getopts.html" target="main">getopts</a> +</li> +<li><a href="../utilities/gettext.html" target="main">gettext</a> +</li> +<li><a href="../utilities/grep.html" target="main">grep</a> +</li> +<li><a href="../utilities/hash.html" target="main">hash</a> +</li> +<li><a href="../utilities/head.html" target="main">head</a> +</li> +<li><a href="../utilities/iconv.html" target="main">iconv</a> +</li> +<li><a href="../utilities/id.html" target="main">id</a> +</li> +<li><a href="../utilities/ipcrm.html" target="main">ipcrm</a> +</li> +<li><a href="../utilities/ipcs.html" target="main">ipcs</a> +</li> +<li><a href="../utilities/jobs.html" target="main">jobs</a> +</li> +<li><a href="../utilities/join.html" target="main">join</a> +</li> +<li><a href="../utilities/kill.html" target="main">kill</a> +</li> +<li><a href="../utilities/lex.html" target="main">lex</a> +</li> +<li><a href="../utilities/link.html" target="main">link</a> +</li> +<li><a href="../utilities/ln.html" target="main">ln</a> +</li> +<li><a href="../utilities/locale.html" target="main">locale</a> +</li> +<li><a href="../utilities/localedef.html" target="main">localedef</a> +</li> +<li><a href="../utilities/logger.html" target="main">logger</a> +</li> +<li><a href="../utilities/logname.html" target="main">logname</a> +</li> +<li><a href="../utilities/lp.html" target="main">lp</a> +</li> +<li><a href="../utilities/ls.html" target="main">ls</a> +</li> +<li><a href="../utilities/m4.html" target="main">m4</a> +</li> +<li><a href="../utilities/mailx.html" target="main">mailx</a> +</li> +<li><a href="../utilities/make.html" target="main">make</a> +</li> +<li><a href="../utilities/man.html" target="main">man</a> +</li> +<li><a href="../utilities/mesg.html" target="main">mesg</a> +</li> +<li><a href="../utilities/mkdir.html" target="main">mkdir</a> +</li> +<li><a href="../utilities/mkfifo.html" target="main">mkfifo</a> +</li> +<li><a href="../utilities/more.html" target="main">more</a> +</li> +<li><a href="../utilities/msgfmt.html" target="main">msgfmt</a> +</li> +<li><a href="../utilities/mv.html" target="main">mv</a> +</li> +<li><a href="../utilities/newgrp.html" target="main">newgrp</a> +</li> +<li><a href="../utilities/ngettext.html" target="main">ngettext</a> +</li> +<li><a href="../utilities/nice.html" target="main">nice</a> +</li> +<li><a href="../utilities/nl.html" target="main">nl</a> +</li> +<li><a href="../utilities/nm.html" target="main">nm</a> +</li> +<li><a href="../utilities/nohup.html" target="main">nohup</a> +</li> +<li><a href="../utilities/od.html" target="main">od</a> +</li> +<li><a href="../utilities/paste.html" target="main">paste</a> +</li> +<li><a href="../utilities/patch.html" target="main">patch</a> +</li> +<li><a href="../utilities/pathchk.html" target="main">pathchk</a> +</li> +<li><a href="../utilities/pax.html" target="main">pax</a> +</li> +<li><a href="../utilities/pr.html" target="main">pr</a> +</li> +<li><a href="../utilities/printf.html" target="main">printf</a> +</li> +<li><a href="../utilities/prs.html" target="main">prs</a> +</li> +<li><a href="../utilities/ps.html" target="main">ps</a> +</li> +<li><a href="../utilities/pwd.html" target="main">pwd</a> +</li> +<li><a href="../utilities/read.html" target="main">read</a> +</li> +<li><a href="../utilities/readlink.html" target="main">readlink</a> +</li> +<li><a href="../utilities/realpath.html" target="main">realpath</a> +</li> +<li><a href="../utilities/renice.html" target="main">renice</a> +</li> +<li><a href="../utilities/rm.html" target="main">rm</a> +</li> +<li><a href="../utilities/rmdel.html" target="main">rmdel</a> +</li> +<li><a href="../utilities/rmdir.html" target="main">rmdir</a> +</li> +<li><a href="../utilities/sact.html" target="main">sact</a> +</li> +<li><a href="../utilities/sccs.html" target="main">sccs</a> +</li> +<li><a href="../utilities/sed.html" target="main">sed</a> +</li> +<li><a href="../utilities/sh.html" target="main">sh</a> +</li> +<li><a href="../utilities/sleep.html" target="main">sleep</a> +</li> +<li><a href="../utilities/sort.html" target="main">sort</a> +</li> +<li><a href="../utilities/split.html" target="main">split</a> +</li> +<li><a href="../utilities/strings.html" target="main">strings</a> +</li> +<li><a href="../utilities/strip.html" target="main">strip</a> +</li> +<li><a href="../utilities/stty.html" target="main">stty</a> +</li> +<li><a href="../utilities/tabs.html" target="main">tabs</a> +</li> +<li><a href="../utilities/tail.html" target="main">tail</a> +</li> +<li><a href="../utilities/talk.html" target="main">talk</a> +</li> +<li><a href="../utilities/tee.html" target="main">tee</a> +</li> +<li><a href="../utilities/test.html" target="main">test</a> +</li> +<li><a href="../utilities/time.html" target="main">time</a> +</li> +<li><a href="../utilities/timeout.html" target="main">timeout</a> +</li> +<li><a href="../utilities/touch.html" target="main">touch</a> +</li> +<li><a href="../utilities/tput.html" target="main">tput</a> +</li> +<li><a href="../utilities/tr.html" target="main">tr</a> +</li> +<li><a href="../utilities/true.html" target="main">true</a> +</li> +<li><a href="../utilities/tsort.html" target="main">tsort</a> +</li> +<li><a href="../utilities/tty.html" target="main">tty</a> +</li> +<li><a href="../utilities/type.html" target="main">type</a> +</li> +<li><a href="../utilities/ulimit.html" target="main">ulimit</a> +</li> +<li><a href="../utilities/umask.html" target="main">umask</a> +</li> +<li><a href="../utilities/unalias.html" target="main">unalias</a> +</li> +<li><a href="../utilities/uname.html" target="main">uname</a> +</li> +<li><a href="../utilities/uncompress.html" target="main">uncompress</a> +</li> +<li><a href="../utilities/unexpand.html" target="main">unexpand</a> +</li> +<li><a href="../utilities/unget.html" target="main">unget</a> +</li> +<li><a href="../utilities/uniq.html" target="main">uniq</a> +</li> +<li><a href="../utilities/unlink.html" target="main">unlink</a> +</li> +<li><a href="../utilities/uucp.html" target="main">uucp</a> +</li> +<li><a href="../utilities/uudecode.html" target="main">uudecode</a> +</li> +<li><a href="../utilities/uuencode.html" target="main">uuencode</a> +</li> +<li><a href="../utilities/uustat.html" target="main">uustat</a> +</li> +<li><a href="../utilities/uux.html" target="main">uux</a> +</li> +<li><a href="../utilities/val.html" target="main">val</a> +</li> +<li><a href="../utilities/vi.html" target="main">vi</a> +</li> +<li><a href="../utilities/wait.html" target="main">wait</a> +</li> +<li><a href="../utilities/wc.html" target="main">wc</a> +</li> +<li><a href="../utilities/what.html" target="main">what</a> +</li> +<li><a href="../utilities/who.html" target="main">who</a> +</li> +<li><a href="../utilities/write.html" target="main">write</a> +</li> +<li><a href="../utilities/xargs.html" target="main">xargs</a> +</li> +<li><a href="../utilities/xgettext.html" target="main">xgettext</a> +</li> +<li><a href="../utilities/yacc.html" target="main">yacc</a> +</li> +<li><a href="../utilities/zcat.html" target="main">zcat</a> +</li> +</ul> + +</body> +</html> + diff --git a/bdd/ar.html b/bdd/ar.html @@ -0,0 +1,504 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>ar</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/alias.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/asa.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="ar" id="ar"></a> <a name="tag_20_03" id="tag_20_03"></a><!-- ar --> +<h4 class="mansect"><a name="tag_20_03_01" id="tag_20_03_01"></a>NAME</h4> +<blockquote>ar — create and maintain library archives</blockquote> +<h4 class="mansect"><a name="tag_20_03_02" id="tag_20_03_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('SD')">SD</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> ar -d</tt> <b>[</b><tt>-v</tt><b>]</b> <i>archive file</i><tt>... <img src="../images/opt-end.gif" +alt="[Option End]" border="0"></tt></code></div> +<tt><br> +<br></tt> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> ar -m</tt> <b>[</b><tt>-v</tt><b>]</b> <i>archive file</i><tt>...<br> +ar -m -a</tt> <b>[</b><tt>-v</tt><b>]</b> <i>posname archive file</i><tt>...<br> +ar -m -b</tt> <b>[</b><tt>-v</tt><b>]</b> <i>posname archive file</i><tt>...<br> +ar -m -i</tt> <b>[</b><tt>-v</tt><b>]</b> <i>posname archive file</i><tt>... <img src="../images/opt-end.gif" alt="[Option End]" +border="0"></tt></code></div> +<tt><br> +<br> +<sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> ar -p</tt> <b>[</b><tt>-v</tt><b>] <img src="../images/opt-start.gif" +border="0">[</b><tt>-s</tt><b>]<img src="../images/opt-end.gif" border="0"></b> <i>archive</i> +<b>[</b><i>file</i><tt>...</tt><b>]</b> <tt><br> +<br></tt> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> ar -q</tt> <b>[</b><tt>-cv</tt><b>]</b> <i>archive file</i><tt>... <img src="../images/opt-end.gif" +alt="[Option End]" border="0"></tt></code></div> +<tt><br> +<br> +ar -r</tt> <b>[</b><tt>-cuv</tt><b>]</b> <i>archive file</i><tt>...<br> +<br></tt> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> ar -r -a</tt> <b>[</b><tt>-cuv</tt><b>]</b> <i>posname archive file</i><tt>...<br> +ar -r -b</tt> <b>[</b><tt>-cuv</tt><b>]</b> <i>posname archive file</i><tt>...<br> +ar -r -i</tt> <b>[</b><tt>-cuv</tt><b>]</b> <i>posname archive file</i><tt>... <img src="../images/opt-end.gif" alt="[Option End]" +border="0"></tt></code></div> +<tt><br> +<br> +<sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> ar -t</tt> <b>[</b><tt>-v</tt><b>] <img src="../images/opt-start.gif" +border="0">[</b><tt>-s</tt><b>]<img src="../images/opt-end.gif" border="0"></b> <i>archive</i> +<b>[</b><i>file</i><tt>...</tt><b>]</b> <tt><br> +<br> +<sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> ar -x</tt> <b>[</b><tt>-v</tt><b>] <img src="../images/opt-start.gif" +border="0">[</b><tt>-sCT</tt><b>]<img src="../images/opt-end.gif" border="0"></b> <i>archive</i> +<b>[</b><i>file</i><tt>...</tt><b>]</b> <tt><br></tt></blockquote> +<h4 class="mansect"><a name="tag_20_03_03" id="tag_20_03_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>ar</i> utility is part of the Software Development Utilities option.</p> +<p>The <i>ar</i> utility can be used to create and maintain groups of files combined into an archive. Once an archive has been +created, new files can be added, and existing files in an archive can be extracted, deleted, or replaced. When an archive consists +entirely of valid object files, the implementation shall format the archive so that it is usable as a library for link editing (see +<a href="../utilities/c17.html"><i>c17</i></a>). When some of the archived files are not valid object files, the suitability of the +archive for library use is undefined. <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" +alt="[Option Start]" border="0"> If an archive consists entirely of printable files, the entire archive shall be +printable.</p> +<p>When <i>ar</i> creates an archive, it creates administrative information indicating whether a symbol table is present in the +archive. When there is at least one object file that <i>ar</i> recognizes as such in the archive, an archive symbol table shall be +created in the archive and maintained by <i>ar</i>; it is used by the link editor to search the archive. Whenever the <i>ar</i> +utility is used to create or update the contents of such an archive, the symbol table shall be rebuilt. The <b>-s</b> option shall +force the symbol table to be rebuilt. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p> +<p>All <i>file</i> operands can be pathnames. However, files within archives shall be named by a filename, which is the last +component of the pathname used when the file was entered into the archive. The comparison of <i>file</i> operands to the names of +files in archives shall be performed by comparing the last component of the operand to the name of the file in the archive.</p> +<p>It is unspecified whether multiple files in the archive may be identically named. In the case of such files, however, each +<i>file</i> <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" +border="0"> and <i>posname</i> <img src="../images/opt-end.gif" alt="[Option End]" border="0"> operand shall match only the +first file in the archive having a name that is the same as the last component of the operand.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_03_04" id="tag_20_03_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>ar</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> , except for Guideline 9.</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-a</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Position new files in the archive after the file named by the <i>posname</i> operand. <img src="../images/opt-end.gif" alt= +"[Option End]" border="0"></dd> +<dt><b>-b</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Position new files in the archive before the file named by the <i>posname</i> operand. <img src="../images/opt-end.gif" alt= +"[Option End]" border="0"></dd> +<dt><b>-c</b></dt> +<dd>Suppress the diagnostic message that is written to standard error by default when the archive <i>archive</i> is created.</dd> +<dt><b>-C</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Prevent extracted files from replacing like-named files in the file system. This option is useful when <b>-T</b> is also used, to +prevent truncated filenames from replacing files with the same prefix. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><b>-d</b></dt> +<dd>Delete one or more <i>file</i>s from <i>archive</i>.</dd> +<dt><b>-i</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Position new files in the archive before the file in the archive named by the <i>posname</i> operand (equivalent to <b>-b</b>). +<img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-m</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Move the named files in the archive. The <b>-a</b>, <b>-b</b>, or <b>-i</b> options with the <i>posname</i> operand indicate the +position; otherwise, move the names files in the archive to the end of the archive. <img src="../images/opt-end.gif" alt= +"[Option End]" border="0"></dd> +<dt><b>-p</b></dt> +<dd>Write the contents of the <i>file</i>s in the archive named by <i>file</i> operands from <i>archive</i> to the standard output. +If no <i>file</i> operands are specified, the contents of all files in the archive shall be written in the order of the +archive.</dd> +<dt><b>-q</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Append the named files to the end of the archive. In this case <i>ar</i> does not check whether the added files are already in the +archive. This is useful to bypass the searching otherwise done when creating a large archive piece by piece. <img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-r</b></dt> +<dd>Replace or add <i>file</i>s to <i>archive</i>. If the archive named by <i>archive</i> does not exist, a new archive shall be +created and a diagnostic message shall be written to standard error (unless the <b>-c</b> option is specified). If no <i>file</i>s +are specified and the <i>archive</i> exists, the results are undefined. Files that replace existing files in the archive shall not +change the order of the archive. Files that do not replace existing files in the archive shall be appended to the archive +<sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> + unless a <b>-a</b>, <b>-b</b>, or <b>-i</b> option specifies another position. <img src="../images/opt-end.gif" alt= +"[Option End]" border="0"></dd> +<dt><b>-s</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Force the regeneration of the archive symbol table even if <i>ar</i> is not invoked with an option that modifies the archive +contents. This option is useful to restore the archive symbol table after it has been stripped; see <a href= +"../utilities/strip.html"><i>strip</i></a>. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-t</b></dt> +<dd>Write a table of contents of <i>archive</i> to the standard output. Only the files specified by the <i>file</i> operands shall +be included in the written list. If no <i>file</i> operands are specified, all files in <i>archive</i> shall be included in the +order of the archive.</dd> +<dt><b>-T</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Allow filename truncation of extracted files whose archive names are longer than the file system can support. By default, +extracting a file with a name that is too long shall be an error; a diagnostic message shall be written and the file shall not be +extracted. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-u</b></dt> +<dd>Update older files in the archive. When used with the <b>-r</b> option, files in the archive shall be replaced only if the +corresponding <i>file</i> has a modification time that is at least as new as the modification time of the file in the archive.</dd> +<dt><b>-v</b></dt> +<dd>Give verbose output. When used with the option characters <b>-d</b>, <b>-r</b>, or <b>-x</b>, write a detailed file-by-file +description of the archive creation and maintenance activity, as described in the STDOUT section. +<p>When used with <b>-p</b>, write the name of the file in the archive to the standard output before writing the file in the +archive itself to the standard output, as described in the STDOUT section.</p> +<p>When used with <b>-t</b>, include a long listing of information about the files in the archive, as described in the STDOUT +section.</p> +</dd> +<dt><b>-x</b></dt> +<dd>Extract the files in the archive named by the <i>file</i> operands from <i>archive</i>. The contents of the archive shall not +be changed. If no <i>file</i> operands are given, all files in the archive shall be extracted. The modification time of each file +extracted shall be set to the time the file is extracted from the archive.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_03_05" id="tag_20_03_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>archive</i></dt> +<dd>A pathname of the archive.</dd> +<dt><i>file</i></dt> +<dd>A pathname. Only the last component shall be used when comparing against the names of files in the archive. If two or more +<i>file</i> operands have the same last pathname component (basename), the results are unspecified. The implementation's archive +format shall not truncate valid filenames of files added to or replaced in the archive.</dd> +<dt><i>posname</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +The name of a file in the archive, used for relative positioning; see options <b>-m</b> and <b>-r</b>. <img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_03_06" id="tag_20_03_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_03_07" id="tag_20_03_07"></a>INPUT FILES</h4> +<blockquote> +<p>The archive named by <i>archive</i> shall be a file in the format created by <i>ar</i> <b>-r</b>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_03_08" id="tag_20_03_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>ar</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>LC_TIME</i></dt> +<dd>Determine the format and content for date and time strings written by <i>ar</i> <b>-tv</b>.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>TMPDIR</i></dt> +<dd>Determine the pathname that overrides the default directory for temporary files, if any.</dd> +<dt><i>TZ</i></dt> +<dd>Determine the timezone used to calculate date and time strings written by <i>ar</i> <b>-tv</b>. If <i>TZ</i> is unset or null, +an unspecified default timezone shall be used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_03_09" id="tag_20_03_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_03_10" id="tag_20_03_10"></a>STDOUT</h4> +<blockquote> +<p>If the <b>-d</b> option is used with the <b>-v</b> option, the standard output format shall be:</p> +<pre> +<tt>"d - %s\n", <</tt><i>file</i><tt>> +</tt></pre> +<p>where <i>file</i> is the operand specified on the command line.</p> +<p>If the <b>-p</b> option is used with the <b>-v</b> option, <i>ar</i> shall precede the contents of each file with:</p> +<pre> +<tt>"\n<%s>\n\n", <</tt><i>file</i><tt>> +</tt></pre> +<p>where <i>file</i> is the operand specified on the command line, if <i>file</i> operands were specified, and the name of the file +in the archive if they were not.</p> +<p>If the <b>-r</b> option is used with the <b>-v</b> option:</p> +<ul> +<li> +<p>If <i>file</i> is already in the archive, the standard output format shall be:</p> +<pre> +<tt>"r - %s\n", <</tt><i>file</i><tt>> +</tt></pre> +<p>where <<i>file</i>> is the operand specified on the command line.</p> +</li> +<li> +<p>If <i>file</i> is not already in the archive, the standard output format shall be:</p> +<pre> +<tt>"a - %s\n", <</tt><i>file</i><tt>> +</tt></pre> +<p>where <<i>file</i>> is the operand specified on the command line.</p> +</li> +</ul> +<p>If the <b>-t</b> option is used, <i>ar</i> shall write the names of the files in the archive to the standard output in the +format:</p> +<pre> +<tt>"%s\n", <</tt><i>file</i><tt>> +</tt></pre> +<p>where <i>file</i> is the operand specified on the command line, if <i>file</i> operands were specified, or the name of the file +in the archive if they were not.</p> +<p>If the <b>-t</b> option is used with the <b>-v</b> option, the standard output format shall be:</p> +<pre> +<tt>"%s %u/%u %u %s %d %d:%d %d %s\n", <</tt><i>member mode</i><tt>>, <</tt><i>user ID</i><tt>>, + <</tt><i>group ID</i><tt>>, <</tt><i>number of bytes in member</i><tt>>, + <</tt><i>abbreviated month</i><tt>>, <</tt><i>day-of-month</i><tt>>, <</tt><i>hour</i><tt>>, + <</tt><i>minute</i><tt>>, <</tt><i>year</i><tt>>, <</tt><i>file</i><tt>> +</tt></pre> +<p>where:</p> +<dl compact> +<dd></dd> +<dt><<i>file</i>></dt> +<dd>Shall be the operand specified on the command line, if <i>file</i> operands were specified, or the name of the file in the +archive if they were not.</dd> +<dt><<i>member mode</i>></dt> +<dd><br> +Shall be formatted the same as the <<i>file mode</i>> string defined in the STDOUT section of <a href= +"../utilities/ls.html"><i>ls</i></a>, except that the first character, the <<i>entry type</i>>, is not used; the string +represents the file mode of the file in the archive at the time it was added to or replaced in the archive.</dd> +</dl> +<br> +<p>The following represent the last-modification time of a file when it was most recently added to or replaced in the archive:</p> +<dl compact> +<dd></dd> +<dt><<i>abbreviated month</i>></dt> +<dd><br> +Equivalent to the format of the <tt>%b</tt> conversion specification format in <a href= +"../utilities/date.html"><i>date</i></a>.</dd> +<dt><<i>day-of-month</i>></dt> +<dd><br> +Equivalent to the format of the <tt>%e</tt> conversion specification format in <a href= +"../utilities/date.html"><i>date</i></a>.</dd> +<dt><<i>hour</i>></dt> +<dd>Equivalent to the format of the <tt>%H</tt> conversion specification format in <a href= +"../utilities/date.html"><i>date</i></a>.</dd> +<dt><<i>minute</i>></dt> +<dd>Equivalent to the format of the <tt>%M</tt> conversion specification format in <a href= +"../utilities/date.html"><i>date</i></a>.</dd> +<dt><<i>year</i>></dt> +<dd>Equivalent to the format of the <tt>%Y</tt> conversion specification format in <a href= +"../utilities/date.html"><i>date</i></a>.</dd> +</dl> +<p>When <i>LC_TIME</i> does not specify the POSIX locale, a different format and order of presentation of these fields relative to +each other may be used in a format appropriate in the specified locale.</p> +<p>If the <b>-x</b> option is used with the <b>-v</b> option, the standard output format shall be:</p> +<pre> +<tt>"x - %s\n", <</tt><i>file</i><tt>> +</tt></pre> +<p>where <i>file</i> is the operand specified on the command line, if <i>file</i> operands were specified, or the name of the file +in the archive if they were not.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_03_11" id="tag_20_03_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages. The diagnostic message about creating a new archive when +<b>-c</b> is not specified shall not modify the exit status.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_03_12" id="tag_20_03_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>Archives are files with unspecified formats.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_03_13" id="tag_20_03_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_03_14" id="tag_20_03_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_03_15" id="tag_20_03_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_03_16" id="tag_20_03_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_03_17" id="tag_20_03_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_03_18" id="tag_20_03_18"></a>RATIONALE</h4> +<blockquote> +<p>The archive format is not described. It is recognized that there are several known <i>ar</i> formats, which are not compatible. +The <i>ar</i> utility is included, however, to allow creation of archives that are intended for use only on one machine. The +archive is specified as a file, and it can be moved as a file. This does allow an archive to be moved from one machine to another +machine that uses the same implementation of <i>ar</i>.</p> +<p>Utilities such as <a href="../utilities/pax.html"><i>pax</i></a> (and its forebears <i>tar</i> and <i>cpio</i>) also provide +portable "archives". This is a not a duplication; the <i>ar</i> utility is included to provide an interface primarily for +<a href="../utilities/make.html"><i>make</i></a> and the compilers, based on a historical model.</p> +<p>In historical implementations, the <b>-q</b> option (available on XSI-conforming systems) is known to execute quickly because +<i>ar</i> does not check on whether the added members are already in the archive. This is useful to bypass the searching otherwise +done when creating a large archive piece-by-piece. These remarks may but need not remain true for a brand new implementation of +this utility; hence, these remarks have been moved into the RATIONALE.</p> +<p>BSD implementations historically required applications to provide the <b>-s</b> option whenever the archive was supposed to +contain a symbol table. As in this volume of POSIX.1-2024, System V historically creates or updates an archive symbol table +whenever an object file is removed from, added to, or updated in the archive.</p> +<p>The OPERANDS section requires what might seem to be true without specifying it: the archive cannot truncate the filenames below +{NAME_MAX}. Some historical implementations do so, however, causing unexpected results for the application. Therefore, this volume +of POSIX.1-2024 makes the requirement explicit to avoid misunderstandings.</p> +<p>According to the System V documentation, the options <b>-dmpqrtx</b> are not required to begin with a <hyphen-minus> +(<tt>'-'</tt>). This volume of POSIX.1-2024 requires that a conforming application use the leading <hyphen-minus>.</p> +<p>The archive format used by the 4.4 BSD implementation is documented in this RATIONALE as an example:</p> +<blockquote>A file created by <i>ar</i> begins with the "magic" string <tt>"!<arch>\n"</tt>. The rest of the archive is +made up of objects, each of which is composed of a header for a file, a possible filename, and the file contents. The header is +portable between machine architectures, and, if the file contents are printable, the archive is itself printable. +<p>The header is made up of six ASCII fields, followed by a two-character trailer. The fields are the object name (16 characters), +the file last modification time (12 characters), the user and group IDs (each 6 characters), the file mode (8 characters), and the +file size (10 characters). All numeric fields are in decimal, except for the file mode, which is in octal.</p> +<p>The modification time is the file <i>st_mtime</i> field. The user and group IDs are the file <i>st_uid</i> and <i>st_gid</i> +fields. The file mode is the file <i>st_mode</i> field. The file size is the file <i>st_size</i> field. The two-byte trailer is the +string <tt>"`<newline>"</tt>.</p> +<p>Only the name field has any provision for overflow. If any filename is more than 16 characters in length or contains an embedded +space, the string <tt>"#1/"</tt> followed by the ASCII length of the name is written in the name field. The file size (stored in +the archive header) is incremented by the length of the name. The name is then written immediately following the archive +header.</p> +<p>Any unused characters in any of these fields are written as <space> characters. If any fields are their particular maximum +number of characters in length, there is no separation between the fields.</p> +<p>Objects in the archive are always an even number of bytes long; files that are an odd number of bytes long are padded with a +<newline>, although the size in the header does not reflect this.</p> +</blockquote> +<p>The <i>ar</i> utility description requires that (when all its members are valid object files) <i>ar</i> produce an object code +library, which the linkage editor can use to extract object modules. If the linkage editor needs a symbol table to permit random +access to the archive, <i>ar</i> must provide it; however, <i>ar</i> does not require a symbol table.</p> +<p>The BSD <b>-o</b> option was omitted. It is a rare conforming application that uses <i>ar</i> to extract object code from a +library with concern for its modification time, since this can only be of importance to <a href= +"../utilities/make.html"><i>make</i></a>. Hence, since this functionality is not deemed important for applications portability, the +modification time of the extracted files is set to the current time.</p> +<p>There is at least one known implementation (for a small computer) that can accommodate only object files for that system, +disallowing mixed object and other files. The ability to handle any type of file is not only historical practice for most +implementations, but is also a reasonable expectation.</p> +<p>Consideration was given to changing the output format of <i>ar</i> <b>-tv</b> to the same format as the output of <a href= +"../utilities/ls.html"><i>ls</i></a> <b>-l</b>. This would have made parsing the output of <i>ar</i> the same as that of <a href= +"../utilities/ls.html"><i>ls</i></a>. This was rejected in part because the current <i>ar</i> format is commonly used and changes +would break historical usage. Second, <i>ar</i> gives the user ID and group ID in numeric format separated by a <slash>. +Changing this to be the user name and group name would not be correct if the archive were moved to a machine that contained a +different user database. Since <i>ar</i> cannot know whether the archive was generated on the same machine, it cannot tell what to +report.</p> +<p>The text on the <b>-ur</b> option combination is historical practice—since one filename can easily represent two different files +(for example, <b>/a/foo</b> and <b>/b/foo</b>), it is reasonable to replace the file in the archive even when the modification time +in the archive is identical to that in the file system.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_03_19" id="tag_20_03_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +<p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a +<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require +implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_03_20" id="tag_20_03_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/c17.html#"><i>c17</i></a> , <a href="../utilities/date.html#"><i>date</i></a> , <a href= +"../utilities/pax.html#"><i>pax</i></a> , <a href="../utilities/strip.html#"><i>strip</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a> , <a href= +"../basedefs/unistd.h.html"><i><unistd.h></i></a> , description of {POSIX_NO_TRUNC}</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_03_21" id="tag_20_03_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_03_22" id="tag_20_03_22"></a>Issue 5</h4> +<blockquote> +<p>The FUTURE DIRECTIONS section is added.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_03_23" id="tag_20_03_23"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the Software Development Utilities option.</p> +<p>The STDOUT description is changed for the <b>-v</b> option to align with the IEEE P1003.2b draft standard.</p> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +<p>The <i>TZ</i> entry is added to the ENVIRONMENT VARIABLES section.</p> +<p>IEEE PASC Interpretation 1003.2 #198 is applied, changing the description to consistently use "file" to refer to a file in the +file system hierarchy, "archive" to refer to the archive being operated upon by the <i>ar</i> utility, and "file in the +archive" to refer to a copy of a file that is contained in the archive.</p> +<p>IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/10 is applied, making corrections to the SYNOPSIS. The change +was needed since the <b>-a</b>, <b>-b</b>, and <b>-i</b> options are mutually-exclusive, and <i>posname</i> is required if any of +these options is specified.</p> +<p>IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/11 is applied, correcting the description of the two-byte +trailer in RATIONALE which had missed out a backquote. The correct trailer is a backquote followed by a <newline>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_03_24" id="tag_20_03_24"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-6 is applied, clarifying that Guideline 9 of the Utility Syntax Guidelines does not apply.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>The description of the <b>-t</b> option is changed to say "Only the files specified ...".</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0057 [584] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_03_25" id="tag_20_03_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to behave as follows:</p> +<ol type="a"> +<li> +<p>Report an error if a utility is directed to display a pathname that contains any bytes that have the encoded value of a +<newline> character when <newline> is a terminator or separator in the output format being used.</p> +</li> +<li> +<p>Disallow the creation of filenames containing any bytes that have the encoded value of a <newline> character.</p> +</li> +</ol> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1330 is applied, removing obsolescent interfaces.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/alias.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/asa.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/asa.html b/bdd/asa.html @@ -0,0 +1,228 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>asa</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/ar.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/at.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="asa" id="asa"></a> <a name="tag_20_04" id="tag_20_04"></a><!-- asa --> +<h4 class="mansect"><a name="tag_20_04_01" id="tag_20_04_01"></a>NAME</h4> +<blockquote>asa — interpret carriage-control characters</blockquote> +<h4 class="mansect"><a name="tag_20_04_02" id="tag_20_04_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('FR')">FR</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> asa</tt> <b>[</b><i>file</i><tt>...</tt><b>]</b> <tt><img src="../images/opt-end.gif" alt= +"[Option End]" border="0"></tt></code></div> +</blockquote> +<h4 class="mansect"><a name="tag_20_04_03" id="tag_20_04_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>asa</i> utility shall write its input files to standard output, mapping carriage-control characters from the text files +to line-printer control sequences in an implementation-defined manner.</p> +<p>The first character of every line shall be removed from the input, and the following actions are performed.</p> +<p>If the character removed is:</p> +<dl compact> +<dd></dd> +<dt><space></dt> +<dd>The rest of the line is output without change.</dd> +<dt>0</dt> +<dd>A <newline> is output, then the rest of the input line.</dd> +<dt>1</dt> +<dd>One or more implementation-defined characters that causes an advance to the next page shall be output, followed by the rest of +the input line.</dd> +<dt><tt>+</tt></dt> +<dd>The <newline> of the previous line shall be replaced with one or more implementation-defined characters that causes +printing to return to column position 1, followed by the rest of the input line. If the <tt>'+'</tt> is the first character in the +input, it shall be equivalent to <space>.</dd> +</dl> +<p>The action of the <i>asa</i> utility is unspecified upon encountering any character other than those listed above as the first +character in a line.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_04_04" id="tag_20_04_04"></a>OPTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_04_05" id="tag_20_04_05"></a>OPERANDS</h4> +<blockquote> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of a text file used for input. If no <i>file</i> operands are specified, the standard input shall be used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_04_06" id="tag_20_04_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be used if no <i>file</i> operands are specified, and shall be used if a <i>file</i> operand is +<tt>'-'</tt> and the implementation treats the <tt>'-'</tt> as meaning standard input. Otherwise, the standard input shall not be +used. See the INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_04_07" id="tag_20_04_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files shall be text files.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_04_08" id="tag_20_04_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>asa</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_04_09" id="tag_20_04_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_04_10" id="tag_20_04_10"></a>STDOUT</h4> +<blockquote> +<p>The standard output shall be the text from the input file modified as described in the DESCRIPTION section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_04_11" id="tag_20_04_11"></a>STDERR</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_04_12" id="tag_20_04_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_04_13" id="tag_20_04_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_04_14" id="tag_20_04_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>All input files were output successfully.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_04_15" id="tag_20_04_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_04_16" id="tag_20_04_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_04_17" id="tag_20_04_17"></a>EXAMPLES</h4> +<blockquote> +<ol> +<li> +<p>The following command:</p> +<pre> +<tt>asa </tt><i>file</i><tt> +</tt></pre> +<p>permits the viewing of <i>file</i> (created by a program using FORTRAN-style carriage-control characters) on a terminal.</p> +</li> +<li> +<p>The following command:</p> +<pre> +<tt>a.out | asa | lp +</tt></pre> +<p>formats the FORTRAN output of <b>a.out</b> and directs it to the printer.</p> +</li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_04_18" id="tag_20_04_18"></a>RATIONALE</h4> +<blockquote> +<p>The <i>asa</i> utility is needed to map "standard" FORTRAN 77 output into a form acceptable to contemporary printers. Usually, +<i>asa</i> is used to pipe data to the <a href="../utilities/lp.html"><i>lp</i></a> utility; see <a href= +"../utilities/lp.html"><i>lp</i></a>.</p> +<p>This utility is generally used only by FORTRAN programs. The standard developers decided to retain <i>asa</i> to avoid breaking +the historical large base of FORTRAN applications that put carriage-control characters in their output files. There is no +requirement that a system have a FORTRAN compiler in order to run applications that need <i>asa</i>.</p> +<p>Historical implementations have used an ASCII <form-feed> in response to a 1 and an ASCII <carriage-return> in +response to a <tt>'+'</tt>. It is suggested that implementations treat characters other than 0, 1, and <tt>'+'</tt> as +<space> in the absence of any compelling reason to do otherwise. However, the action is listed here as "unspecified", +permitting an implementation to provide extensions to access fast multiple-line slewing and channel seeking in a non-portable +manner.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_04_19" id="tag_20_04_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_04_20" id="tag_20_04_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/lp.html#"><i>lp</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_04_21" id="tag_20_04_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_04_22" id="tag_20_04_22"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the FORTRAN Runtime Utilities option.</p> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_04_23" id="tag_20_04_23"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #092 is applied.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_04_24" id="tag_20_04_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/ar.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/at.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/at.html b/bdd/at.html @@ -0,0 +1,575 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>at</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/asa.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/awk.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="at" id="at"></a> <a name="tag_20_05" id="tag_20_05"></a><!-- at --> +<h4 class="mansect"><a name="tag_20_05_01" id="tag_20_05_01"></a>NAME</h4> +<blockquote>at — execute commands at a later time</blockquote> +<h4 class="mansect"><a name="tag_20_05_02" id="tag_20_05_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>at</tt> <b>[</b><tt>-m</tt><b>] [</b><tt>-f</tt> <i>file</i><b>] [</b><tt>-q</tt> <i>queuename</i><b>]</b> <tt>-t</tt> +<i>time_arg</i> <tt><br> +<br> +at</tt> <b>[</b><tt>-m</tt><b>] [</b><tt>-f</tt> <i>file</i><b>] [</b><tt>-q</tt> <i>queuename</i><b>]</b> +<i>timespec</i><tt>...<br> +<br> +at -r</tt> <i>at_job_id</i><tt>...<br> +<br> +at -l -q</tt> <i>queuename</i> <tt><br> +<br> +at -l</tt> <b>[</b><i>at_job_id</i><tt>...</tt><b>]</b> <tt><br></tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_05_03" id="tag_20_05_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>at</i> utility shall read commands from standard input and group them together as an <i>at-job</i>, to be executed at a +later time.</p> +<p>The at-job shall be executed in a separate invocation of the shell, running in a separate process group with no controlling +terminal, except that the environment variables, current working directory, file creation mask, and other implementation-defined +execution-time attributes in effect when the <i>at</i> utility is executed shall be retained and used when the at-job is +executed.</p> +<p>When the at-job is submitted, the <i>at_job_id</i> and scheduled time shall be written to standard error. The <i>at_job_id</i> +is an identifier that shall be a string consisting solely of alphanumeric characters and the <period> character. The +<i>at_job_id</i> shall be assigned by the system when the job is scheduled such that it uniquely identifies a particular job.</p> +<p>User notification and the processing of the job's standard output and standard error are described under the <b>-m</b> +option.</p> +<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Users shall be permitted to use <i>at</i> if their name appears in the file <b>at.allow</b> which is located in an +implementation-defined directory. If that file does not exist, the file <b>at.deny</b>, which is located in an +implementation-defined directory, shall be checked to determine whether the user shall be denied access to <i>at</i>. If neither +file exists, only a process with appropriate privileges shall be allowed to submit a job. If only <b>at.deny</b> exists and is +empty, global usage shall be permitted. The <b>at.allow</b> and <b>at.deny</b> files shall consist of one user name per line. +<img src="../images/opt-end.gif" alt="[Option End]" border="0"></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_05_04" id="tag_20_05_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>at</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-f </b><i>file</i></dt> +<dd>Specify the pathname of a file to be used as the source of the at-job, instead of standard input.</dd> +<dt><b>-l</b></dt> +<dd>(The letter ell.) Report all jobs scheduled for the invoking user if no <i>at_job_id</i> operands are specified. If +<i>at_job_id</i>s are specified, report only information for these jobs. The output shall be written to standard output.</dd> +<dt><b>-m</b></dt> +<dd>Send mail to the invoking user after the at-job has run, announcing its completion. Standard output and standard error produced +by the at-job shall be mailed to the user as well, unless redirected elsewhere. Mail shall be sent even if the job produces no +output. +<p>If <b>-m</b> is not used, the job's standard output and standard error shall be provided to the user by means of mail, unless +they are redirected elsewhere; if there is no such output to provide, the implementation need not notify the user of the job's +completion.</p> +</dd> +<dt><b>-q </b><i>queuename</i></dt> +<dd><br> +Specify in which queue to schedule a job for submission. When used with the <b>-l</b> option, limit the search to that particular +queue. By default, at-jobs shall be scheduled in queue <i>a</i>. In contrast, queue <i>b</i> shall be reserved for batch jobs; see +<a href="../utilities/batch.html"><i>batch</i></a>. The meanings of all other <i>queuename</i>s are implementation-defined. If +<b>-q</b> <i>b</i> is specified along with either of the <b>-t</b> <i>time_arg</i> or <i>timespec</i> arguments, the results are +unspecified.</dd> +<dt><b>-r</b></dt> +<dd>Remove the jobs with the specified <i>at_job_id</i> operands that were previously scheduled by the <i>at</i> utility.</dd> +<dt><b>-t </b><i>time_arg</i></dt> +<dd>Submit the job to be run at the time specified by the <i>time</i> option-argument, which the application shall ensure has the +format as specified by the <a href="../utilities/touch.html"><i>touch</i></a> <b>-t</b> <i>time</i> utility.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_05_05" id="tag_20_05_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>at_job_id</i></dt> +<dd>The name reported by a previous invocation of the <i>at</i> utility at the time the job was scheduled.</dd> +<dt><i>timespec</i></dt> +<dd>Submit the job to be run at the date and time specified. All of the <i>timespec</i> operands are interpreted as if they were +separated by <space> characters and concatenated, and shall be parsed as described in the grammar at the end of this section. +The date and time shall be interpreted as being in the timezone of the user (as determined by the <i>TZ</i> variable), unless a +timezone name appears as part of <i>time</i>, below. +<p>In the POSIX locale, the following describes the three parts of the time specification string. All of the values from the +<i>LC_TIME</i> categories in the POSIX locale shall be recognized in a case-insensitive manner.</p> +<dl compact> +<dd></dd> +<dt><i>time</i></dt> +<dd>The time can be specified as one, two, or four digits. One-digit and two-digit numbers shall be taken to be hours; four-digit +numbers to be hours and minutes. The time can alternatively be specified as two numbers separated by a <colon>, meaning +<i>hour</i>:<i>minute</i>. If the <i>LC_TIME</i> category of the locale supports 12-hour time format (see XBD <a href= +"../basedefs/V1_chap07.html#tag_07_03_05"><i>7.3.5 LC_TIME</i></a> ), an AM/PM indication in the form of one of the values from the +<b>am_pm</b> keywords in the <i>LC_TIME</i> locale category can follow the time; otherwise, a 24-hour clock time shall be +understood. A timezone name can also follow to further qualify the time. The acceptable timezone names are implementation-defined, +except that they shall be case-insensitive and the string <b>utc</b> is supported to indicate the time is in Coordinated Universal +Time. In the POSIX locale, the <i>time</i> field can also be one of the following tokens: +<dl compact> +<dd></dd> +<dt><b>midnight</b></dt> +<dd>Indicates the time 12:00 am (00:00).</dd> +<dt><b>noon</b></dt> +<dd>Indicates the time 12:00 pm.</dd> +<dt><b>now</b></dt> +<dd>Indicates the current day and time. Invoking <i>at</i> <<b>now</b>> shall submit an at-job for potentially immediate +execution (that is, subject only to unspecified scheduling delays).</dd> +</dl> +</dd> +<dt><i>date</i></dt> +<dd>An optional <i>date</i> can be specified as either a month name (one of the values from the <b>mon</b> or <b>abmon</b> keywords +in the <i>LC_TIME</i> locale category) followed by a day number (and possibly year number preceded by a comma), or a day of the +week (one of the values from the <b>day</b> or <b>abday</b> keywords in the <i>LC_TIME</i> locale category). In the POSIX locale, +two special days shall be recognized: +<dl compact> +<dd></dd> +<dt><b>today</b></dt> +<dd>Indicates the current day.</dd> +<dt><b>tomorrow</b></dt> +<dd>Indicates the day following the current day.</dd> +</dl> +<p>If no <i>date</i> is given, <b>today</b> shall be assumed if the given time is greater than the current time, and +<b>tomorrow</b> shall be assumed if it is less. If the given month is less than the current month (and no year is given), next year +shall be assumed.</p> +</dd> +<dt><i>increment</i></dt> +<dd>The optional <i>increment</i> shall be a number preceded by a <plus-sign> (<tt>'+'</tt>) and suffixed by one of the +following: <b>minutes</b>, <b>hours</b>, <b>days</b>, <b>weeks</b>, <b>months</b>, or <b>years</b>. (The singular forms shall also +be accepted.) The keyword <b>next</b> shall be equivalent to an increment number of +1. For example, the following are equivalent +commands: +<pre> +<tt>at 2pm + 1 week +at 2pm next week +</tt></pre></dd> +</dl> +</dd> +</dl> +<p>The following grammar describes the precise format of <i>timespec</i> in the POSIX locale. The general conventions for this +style of grammar are described in <a href="../utilities/V3_chap01.html#tag_18_03"><i>1.3 Grammar Conventions</i></a> . This formal +syntax shall take precedence over the preceding text syntax description. The longest possible token or delimiter shall be +recognized at a given point. When used in a <i>timespec</i>, white space shall also delimit tokens.</p> +<pre> +<tt>%token hr24clock_hr_min +%token hr24clock_hour +/* + An hr24clock_hr_min is a one, two, or four-digit number. A one-digit + or two-digit number constitutes an hr24clock_hour. An hr24clock_hour + may be any of the single digits [0,9], or may be double digits, ranging + from [00,23]. If an hr24clock_hr_min is a four-digit number, the + first two digits shall be a valid hr24clock_hour, while the last two + represent the number of minutes, from [00,59]. +*/ +<br> +%token wallclock_hr_min +%token wallclock_hour +/* + A wallclock_hr_min is a one, two-digit, or four-digit number. + A one-digit or two-digit number constitutes a wallclock_hour. + A wallclock_hour may be any of the single digits [1,9], or may + be double digits, ranging from [01,12]. If a wallclock_hr_min + is a four-digit number, the first two digits shall be a valid + wallclock_hour, while the last two represent the number of + minutes, from [00,59]. +*/ +<br> +%token minute +/* + A minute is a one or two-digit number whose value can be [0,9] + or [00,59]. +*/ +<br> +%token day_number +/* + A day_number is a number in the range appropriate for the particular + month and year specified by month_name and year_number, respectively. + If no year_number is given, the current year is assumed if the given + date and time are later this year. If no year_number is given and + the date and time have already occurred this year and the month is + not the current month, next year is the assumed year. +*/ +<br> +%token year_number +/* + A year_number is a four-digit number representing the year A.D., in + which the at_job is to be run. +*/ +<br> +%token inc_number +/* + The inc_number is the number of times the succeeding increment + period is to be added to the specified date and time. +*/ +<br> +%token timezone_name +/* + The name of an optional timezone suffix to the time field, in an + implementation-defined format. +*/ +<br> +%token month_name +/* + One of the values from the mon or abmon keywords in the LC_TIME + locale category. +*/ +<br> +%token day_of_week +/* + One of the values from the day or abday keywords in the LC_TIME + locale category. +*/ +<br> +%token am_pm +/* + One of the values from the am_pm keyword in the LC_TIME locale + category. +*/ +<br> +%start timespec +%% +timespec : time + | time date + | time increment + | time date increment + | nowspec + ; +<br> +nowspec : "now" + | "now" increment + ; +<br> +time : hr24clock_hr_min + | hr24clock_hr_min timezone_name + | hr24clock_hour ":" minute + | hr24clock_hour ":" minute timezone_name + | wallclock_hr_min am_pm + | wallclock_hr_min am_pm timezone_name + | wallclock_hour ":" minute am_pm + | wallclock_hour ":" minute am_pm timezone_name + | "noon" + | "midnight" + ; +<br> +date : month_name day_number + | month_name day_number "," year_number + | day_of_week + | "today" + | "tomorrow" + ; +<br> +increment : "+" inc_number inc_period + | "next" inc_period + ; +<br> +inc_period : "minute" | "minutes" + | "hour" | "hours" + | "day" | "days" + | "week" | "weeks" + | "month" | "months" + | "year" | "years" + ; +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_05_06" id="tag_20_05_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be a text file consisting of commands acceptable to the shell command language described in <a href= +"../utilities/V3_chap02.html#tag_19"><i>2. Shell Command Language</i></a> . The standard input shall only be used if no <b>-f</b> +<i>file</i> option is specified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_05_07" id="tag_20_05_07"></a>INPUT FILES</h4> +<blockquote> +<p>See the STDIN section.</p> +<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +The text files <b>at.allow</b> and <b>at.deny</b>, which are located in an implementation-defined directory, shall contain zero or +more user names, one per line, of users who are, respectively, authorized or denied access to the <i>at</i> and <a href= +"../utilities/batch.html"><i>batch</i></a> utilities. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_05_08" id="tag_20_05_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>at</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error and +informative messages written to standard output.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>LC_TIME</i></dt> +<dd>Determine the format and contents for date and time strings written and accepted by <i>at</i>.</dd> +<dt><i>SHELL</i></dt> +<dd>Determine a name of a command interpreter to be used to invoke the at-job. If the variable is unset or null, <a href= +"../utilities/sh.html"><i>sh</i></a> shall be used. If it is set to a value other than a name for <a href= +"../utilities/sh.html"><i>sh</i></a>, the implementation shall do one of the following: use that shell; use <a href= +"../utilities/sh.html"><i>sh</i></a>; use the login shell from the user database; or any of the preceding accompanied by a warning +diagnostic about which was chosen.</dd> +<dt><i>TZ</i></dt> +<dd>Determine the timezone. The job shall be submitted for execution at the time specified by <i>timespec</i> or <b>-t</b> +<i>time</i> relative to the timezone specified by the <i>TZ</i> variable. If <i>timespec</i> specifies a timezone, it shall +override <i>TZ .</i> If <i>timespec</i> does not specify a timezone and <i>TZ</i> is unset or null, an unspecified default timezone +shall be used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_05_09" id="tag_20_05_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_05_10" id="tag_20_05_10"></a>STDOUT</h4> +<blockquote> +<p>When standard input is a terminal, prompts of unspecified format for each line of the user input described in the STDIN section +may be written to standard output.</p> +<p>In the POSIX locale, the following shall be written to the standard output for each job when jobs are listed in response to the +<b>-l</b> option:</p> +<pre> +<tt>"%s\t%s\n", </tt><i>at_job_id</i><tt>, <</tt><i>date</i><tt>> +</tt></pre> +<p>where <i>date</i> shall be equivalent in format to the output of:</p> +<pre> +<tt>date +"%a %b %e %T %Y" +</tt></pre> +<p>The date and time written shall be adjusted so that they appear in the timezone of the user (as determined by the <i>TZ</i> +variable).</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_05_11" id="tag_20_05_11"></a>STDERR</h4> +<blockquote> +<p>In the POSIX locale, the following shall be written to standard error when a job has been successfully submitted:</p> +<pre> +<tt>"job %s at %s\n", </tt><i>at_job_id</i><tt>, <</tt><i>date</i><tt>> +</tt></pre> +<p>where <i>date</i> has the same format as that described in the STDOUT section. Neither this, nor warning messages concerning the +selection of the command interpreter, shall be considered a diagnostic that changes the exit status.</p> +<p>Diagnostic messages, if any, shall be written to standard error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_05_12" id="tag_20_05_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_05_13" id="tag_20_05_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_05_14" id="tag_20_05_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Neither the <b>-l</b> option nor the <b>-r</b> option was specified and a job was successfully submitted; or, the <b>-l</b> +option was specified with no <i>at_job_id</i> operands and there were no jobs to be listed; or, the <b>-l</b> option was specified +and all job listings were successfully output; or, the <b>-r</b> option was specified and all of the specified jobs were +successfully removed.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_05_15" id="tag_20_05_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>If neither the <b>-l</b> option nor the <b>-r</b> option was specified, the job shall not be scheduled. Otherwise, the default +actions specified in <a href="../utilities/V3_chap01.html#tag_18_04"><i>1.4 Utility Description Defaults</i></a> apply.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_05_16" id="tag_20_05_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The format of the <i>at</i> command line shown here is guaranteed only for the POSIX locale. Other cultures may be supported +with substantially different interfaces, although implementations are encouraged to provide comparable levels of functionality.</p> +<p>Since the commands run in a separate shell invocation, running in a separate process group with no controlling terminal, open +file descriptors, traps, and priority inherited from the invoking environment are lost.</p> +<p>Some implementations do not allow substitution of different shells using <i>SHELL .</i> System V systems, for example, have used +the login shell value for the user in <b>/etc/passwd</b>. To select reliably another command interpreter, the user must include it +as part of the script, such as:</p> +<pre> +<b>$</b><tt> at 1800 +myshell myscript +EOT +</tt><b>job ... at ... +$</b><tt> +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_05_17" id="tag_20_05_17"></a>EXAMPLES</h4> +<blockquote> +<ol> +<li> +<p>This sequence can be used at a terminal:</p> +<pre> +<tt>at -m 0730 tomorrow +sort < file >outfile +EOT +</tt></pre></li> +<li> +<p>This sequence, which demonstrates redirecting standard error to a pipe, is useful in a command procedure (the sequence of output +redirection specifications is significant):</p> +<pre> +<tt>at now + 1 hour <<! +diff file1 file2 2>&1 >outfile | mailx -s "outfile update" mygroup +! +</tt></pre> +<p>Note that this always sends mail when there has been an attempt to update <b>outfile</b> and the body of the message will be +empty unless an error occurred.</p> +</li> +<li> +<p>The following shows how to capture both standard error and standard output:</p> +<pre> +<tt>at now + 1 hour <<EOF +{ + run-batch-processing | + mailx -s "batch processing output" mygroup +} 2>&1 | mailx -E -s "errors during batch processing" mygroup +EOF +</tt></pre></li> +<li> +<p>To have a job reschedule itself, <i>at</i> can be invoked from within the at-job. For example, this daily processing script +named <b>my.daily</b> runs every day (although <a href="../utilities/crontab.html"><i>crontab</i></a> is a more appropriate vehicle +for such work):</p> +<pre> +<tt># my.daily runs every day +</tt><i>daily processing</i><tt> +at now tomorrow < my.daily +</tt></pre></li> +<li> +<p>The spacing of the three portions of the POSIX locale <i>timespec</i> is quite flexible as long as there are no ambiguities. +Examples of various times and operand presentation include:</p> +<pre> +<tt>at 0815am Jan 24 +at 8 :15amjan24 +at now "+ 1day" +at 5 pm FRIday +at '17 + utc+ + 30minutes' +</tt></pre></li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_05_18" id="tag_20_05_18"></a>RATIONALE</h4> +<blockquote> +<p>The <i>at</i> utility reads from standard input the commands to be executed at a later time. It may be useful to redirect +standard output and standard error within the specified commands.</p> +<p>The <b>-t</b> <i>time</i> option was added as a new capability to support an internationalized way of specifying a time for +execution of the submitted job.</p> +<p>Early proposals added a "jobname" concept as a way of giving submitted jobs names that are meaningful to the user submitting +them. The historical, system-specified <i>at_job_id</i> gives no indication of what the job is. Upon further reflection, it was +decided that the benefit of this was not worth the change in historical interface.</p> +<p>The <b>-q</b> option historically has been an undocumented option, used mainly by the <a href= +"../utilities/batch.html"><i>batch</i></a> utility.</p> +<p>The System V <b>-m</b> option was added to provide a method for informing users that an at-job had completed. Otherwise, users +are only informed when output to standard error or standard output are not redirected.</p> +<p>The behavior of <i>at</i> <<b>now</b>> was changed in an early proposal from being unspecified to submitting a job for +potentially immediate execution. Historical BSD <i>at</i> implementations support this. Historical System V implementations give an +error in that case, but a change to the System V versions should have no backwards-compatibility ramifications.</p> +<p>On BSD-based systems, a <b>-u</b> <i>user</i> option has allowed those with appropriate privileges to access the work of other +users. Since this is primarily a system administration feature and is not universally implemented, it has been omitted. Similarly, +a specification for the output format for a user with appropriate privileges viewing the queues of other users has been +omitted.</p> +<p>The <b>-f</b> <i>file</i> option from System V is used instead of the BSD method of using the last operand as the pathname. The +BSD method is ambiguous—does:</p> +<pre> +<tt>at 1200 friday +</tt></pre> +<p>mean the same thing if there is a file named <b>friday</b> in the current directory?</p> +<p>The <i>at_job_id</i> is composed of a limited character set in historical practice, and it is mandated here to invalidate +systems that might try using characters that require shell quoting or that could not be easily parsed by shell scripts.</p> +<p>The <i>at</i> utility varies between System V and BSD systems in the way timezones are used. On System V systems, the <i>TZ</i> +variable affects the at-job submission times and the times displayed for the user. On BSD systems, <i>TZ</i> is not taken into +account. The BSD behavior is easily achieved with the current specification. If the user wishes to have the timezone default to +that of the system, they merely need to issue the <i>at</i> command immediately following an unsetting or null assignment to <i>TZ +.</i> For example:</p> +<pre> +<tt>TZ= at noon ... +</tt></pre> +<p>gives the desired BSD result.</p> +<p>While the <a href="../utilities/yacc.html"><i>yacc</i></a>-like grammar specified in the OPERANDS section is lexically +unambiguous with respect to the digit strings, a lexical analyzer would probably be written to look for and return digit strings in +those cases. The parser could then check whether the digit string returned is a valid <i>day_number</i>, <i>year_number</i>, and so +on, based on the context.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_05_19" id="tag_20_05_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_05_20" id="tag_20_05_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/batch.html#"><i>batch</i></a> , <a href="../utilities/crontab.html#"><i>crontab</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_05_21" id="tag_20_05_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_05_22" id="tag_20_05_22"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p> +<ul> +<li> +<p>If <b>-m</b> is not used, the job's standard output and standard error are provided to the user by mail.</p> +</li> +</ul> +<p>The effects of using the <b>-q</b> and <b>-t</b> options as defined in the IEEE P1003.2b draft standard are specified.</p> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_05_23" id="tag_20_05_23"></a>Issue 7</h4> +<blockquote> +<p>The <i>at</i> utility is moved from the User Portability Utilities option to the Base. User Portability Utilities is now an +option for interactive utilities.</p> +<p>SD5-XCU-ERN-95 is applied, removing the references to fixed locations for the files referenced by the <i>at</i> utility.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_05_24" id="tag_20_05_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1307 is applied, changing the <i>timespec</i> operand in relation to locales that do not support the 12-hour +clock format.</p> +<p>Austin Group Defect 1330 is applied, removing obsolescent interfaces.</p> +<p>Austin Group Defect 1368 is applied, changing the EXAMPLES section.</p> +<p>Austin Group Defect 1377 is applied, correcting a typographic error in the description of the <b>-q</b> option.</p> +<p>Austin Group Defect 1495 is applied, changing the EXIT STATUS and CONSEQUENCES OF ERRORS sections.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/asa.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/awk.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/awk.html b/bdd/awk.html @@ -0,0 +1,2483 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>awk</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/at.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/basename.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="awk" id="awk"></a> <a name="tag_20_06" id="tag_20_06"></a><!-- awk --> +<h4 class="mansect"><a name="tag_20_06_01" id="tag_20_06_01"></a>NAME</h4> +<blockquote>awk — pattern scanning and processing language</blockquote> +<h4 class="mansect"><a name="tag_20_06_02" id="tag_20_06_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>awk</tt> <b>[</b><tt>-F</tt> <i>sepstring</i><b>] [</b><tt>-v</tt> <i>assignment</i><b>]</b><tt>...</tt> <i>program</i> +<b>[</b><i>argument</i><tt>...</tt><b>]</b> <tt><br> +<br> +awk</tt> <b>[</b><tt>-F</tt> <i>sepstring</i><b>]</b> <tt>-f</tt> <i>progfile</i> <b>[</b><tt>-f</tt> +<i>progfile</i><b>]</b><tt>...</tt> <b>[</b><tt>-v</tt> <i>assignment</i><b>]</b><tt>...<br> + </tt> <b>[</b><i>argument</i><tt>...</tt><b>]</b> <tt><br></tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_06_03" id="tag_20_06_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>awk</i> utility shall execute programs written in the <i>awk</i> programming language, which is specialized for textual +data manipulation. An <i>awk</i> program is a sequence of patterns and corresponding actions. When input is read that matches a +pattern, the action associated with that pattern is carried out.</p> +<p>Input shall be interpreted as a sequence of records. By default, a record is a line, less its terminating <newline>, but +this can be changed by using the <b>RS</b> built-in variable. Each record of input shall be matched in turn against each pattern in +the program. For each pattern matched, the associated action shall be executed.</p> +<p>The <i>awk</i> utility shall interpret each input record as a sequence of fields where, by default, a field is a string of +non-<blank> non-<newline> characters. This default <blank> and <newline> field delimiter can be changed by +using the <b>FS</b> built-in variable or the <b>-F</b> <i>sepstring</i> option. The <i>awk</i> utility shall denote the first field +in a record $1, the second $2, and so on. The symbol $0 shall refer to the entire record; setting any other field causes the +re-evaluation of $0. Assigning to $0 shall reset the values of all other fields and the <b>NF</b> built-in variable.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_06_04" id="tag_20_06_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>awk</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-F </b><i>sepstring</i></dt> +<dd>Define the input field separator. This option shall be equivalent to: +<pre> +<tt>-v FS=</tt><i>sepstring +</i></pre> +<p>except that if <b>-F</b> <i>sepstring</i> and <b>-v</b> <i><tt>FS=</tt>sepstring</i> are both used, it is unspecified whether +the <b>FS</b> assignment resulting from <b>-F</b> <i>sepstring</i> is processed in command line order or is processed after the +last <b>-v</b> <i><tt>FS=</tt>sepstring</i>. See the description of the <b>FS</b> built-in variable, and how it is used, in the +EXTENDED DESCRIPTION section.</p> +</dd> +<dt><b>-f </b><i>progfile</i></dt> +<dd>Specify the pathname of the file <i>progfile</i> containing an <i>awk</i> program. A pathname of <tt>'-'</tt> shall denote the +standard input. If multiple instances of this option are specified, the concatenation of the files specified as <i>progfile</i> in +the order specified shall be the <i>awk</i> program. The <i>awk</i> program can alternatively be specified in the command line as a +single argument.</dd> +<dt><b>-v </b><i>assignment</i></dt> +<dd> +The application shall ensure that the <i>assignment</i> argument is in the same form as an <i>assignment</i> operand. The specified +variable assignment shall occur prior to executing the <i>awk</i> program, including the actions associated with <b>BEGIN</b> +patterns (if any). Multiple occurrences of this option can be specified.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_06_05" id="tag_20_06_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>program</i></dt> +<dd>If no <b>-f</b> option is specified, the first operand to <i>awk</i> shall be the text of the <i>awk</i> program. The +application shall supply the <i>program</i> operand as a single argument to <i>awk</i>. If the text does not end in a +<newline>, <i>awk</i> shall interpret the text as if it did.</dd> +<dt><i>argument</i></dt> +<dd>Either of the following two types of <i>argument</i> can be intermixed: +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of a file that contains the input to be read, which is matched against the set of patterns in the program. If no +<i>file</i> operands or their equivalents, achieved by modifying the <i>awk</i> variables <b>ARGV</b> and <b>ARGC</b>, are +specified, or if a <i>file</i> operand is <tt>'-'</tt>, the standard input shall be used.</dd> +<dt><i>assignment</i></dt> +<dd>An operand that begins with an <underscore> or alphabetic character from the portable character set (see the table in XBD +<a href="../basedefs/V1_chap06.html#tag_06_01"><i>6.1 Portable Character Set</i></a> ), followed by a sequence of underscores, +digits, and alphabetics from the portable character set, followed by the <tt>'='</tt> character, shall specify a variable +assignment rather than a pathname. The characters before the <tt>'='</tt> represent the name of an <i>awk</i> variable; if that +name is an <i>awk</i> reserved word (see <a href="#tag_20_06_13_16">Grammar</a> ) the behavior is undefined. The characters +following the <equals-sign> shall be interpreted as if they appeared in the <i>awk</i> program preceded and followed by a +double-quote (<tt>'"'</tt> ) character, as a <b>STRING</b> token (see <a href="#tag_20_06_13_16">Grammar</a> ), except that if the +last character is an unescaped <backslash>, it shall be interpreted as a literal <backslash> rather than as the first +character of the sequence <tt>"\""</tt>. The variable shall be assigned the value of that <b>STRING</b> token and, if appropriate, +shall be considered a <i>numeric string</i> (see <a href="#tag_20_06_13_02">Expressions in awk</a> ), the variable shall also be +assigned its numeric value. Each such variable assignment shall occur just prior to the processing of the following <i>file</i>, if +any. Thus, an assignment before the first <i>file</i> argument shall be executed after the <b>BEGIN</b> actions (if any), while an +assignment after the last <i>file</i> argument shall occur before the <b>END</b> actions (if any). If there are no <i>file</i> +arguments or their equivalents, achieved by modifying the <i>awk</i> variables <b>ARGV</b> and <b>ARGC</b>, assignments shall be +executed before processing the standard input.</dd> +</dl> +</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_06_06" id="tag_20_06_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be used only if no <i>file</i> operands or their equivalents, achieved by modifying the <i>awk</i> +variables <b>ARGV</b> and <b>ARGC</b>, are specified; or if a <i>file</i> operand, or its equivalent, is <tt>'-'</tt>; or if a +<i>progfile</i> option-argument is <tt>'-'</tt>; see the INPUT FILES section. If the <i>awk</i> program contains no actions and no +patterns, but is otherwise a valid <i>awk</i> program, standard input and any <i>file</i> operands shall not be read and <i>awk</i> +shall exit with a return status of zero.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_06_07" id="tag_20_06_07"></a>INPUT FILES</h4> +<blockquote> +<p>Input files to the <i>awk</i> program from any of the following sources shall be text files:</p> +<ul> +<li> +<p>Any <i>file</i> operands or their equivalents, achieved by modifying the <i>awk</i> variables <b>ARGV</b> and <b>ARGC</b></p> +</li> +<li> +<p>Standard input in the absence of any <i>file</i> operands, or their equivalents</p> +</li> +<li> +<p>Arguments to the <b>getline</b> function</p> +</li> +</ul> +<p>Whether the variable <b>RS</b> is set to a value other than a <newline> or not, for these files, implementations shall +support records terminated with the specified separator up to {LINE_MAX} bytes and may support longer records.</p> +<p>If <b>-f</b> <i>progfile</i> is specified, the application shall ensure that the files named by each of the <i>progfile</i> +option-arguments are text files and their concatenation, in the same order as they appear in the arguments, is an <i>awk</i> +program.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_06_08" id="tag_20_06_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>awk</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_COLLATE</i></dt> +<dd> +Determine the locale for the behavior of ranges, equivalence classes, and multi-character collating elements within regular +expressions and in comparisons of string values.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files), the behavior of character classes within regular expressions, the +identification of characters as letters, and the mapping of uppercase and lowercase characters for the <b>toupper</b> and +<b>tolower</b> functions.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>LC_NUMERIC</i></dt> +<dd> +Determine the radix character used when interpreting numeric input, performing conversions between numeric and string values, and +formatting numeric output. Regardless of locale, the <period> character (the decimal-point character of the POSIX locale) is +the decimal-point character recognized in processing <i>awk</i> programs (including assignments in command line arguments).</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>PATH</i></dt> +<dd>Determine the search path when looking for commands executed by <i>system</i>(<i>expr</i>), or input and output pipes; see XBD +<a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> .</dd> +</dl> +<p>In addition, all environment variables shall be visible via the <i>awk</i> variable <b>ENVIRON</b>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_06_09" id="tag_20_06_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_06_10" id="tag_20_06_10"></a>STDOUT</h4> +<blockquote> +<p>The nature of the output files depends on the <i>awk</i> program.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_06_11" id="tag_20_06_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_06_12" id="tag_20_06_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>The nature of the output files depends on the <i>awk</i> program.<br></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_06_13" id="tag_20_06_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<h5><a name="tag_20_06_13_01" id="tag_20_06_13_01"></a>Overall Program Structure</h5> +<p>An <i>awk</i> program is composed of pairs of the form:</p> +<pre> +<i>pattern</i><tt> { </tt><i>action</i><tt> } +</tt></pre> +<p>Either the pattern or the action (including the enclosing brace characters) can be omitted.</p> +<p>A missing pattern shall match any record of input, and a missing action shall be equivalent to:</p> +<pre> +<tt>{ print } +</tt></pre> +<p>Execution of the <i>awk</i> program shall start by first executing the actions associated with all <b>BEGIN</b> patterns in the +order they occur in the program. Then each <i>file</i> operand (or standard input if no files were specified) shall be processed in +turn by reading data from the file until a record separator is seen (<newline> by default). Before the first reference to a +field in the record is evaluated, the record shall be split into fields, according to the rules in <a href= +"#tag_20_06_13_04">Regular Expressions</a> , using the value of <b>FS</b> that was current at the time the record was read. Each +pattern in the program then shall be evaluated in the order of occurrence, and the action associated with each pattern that matches +the current record executed. The action for a matching pattern shall be executed before evaluating subsequent patterns. Finally, +the actions associated with all <b>END</b> patterns shall be executed in the order they occur in the program.</p> +<h5><a name="tag_20_06_13_02" id="tag_20_06_13_02"></a>Expressions in awk</h5> +<p>Expressions describe computations used in <i>patterns</i> and <i>actions</i>. In the following table, valid expression +operations are given in groups from highest precedence first to lowest precedence last, with equal-precedence operators grouped +between horizontal lines. In expression evaluation, where the grammar is formally ambiguous, higher precedence operators shall be +evaluated before lower precedence operators. In this table <i>expr</i>, <i>expr1</i>, <i>expr2</i>, and <i>expr3</i> represent any +expression, while lvalue represents any entity that can be assigned to (that is, on the left side of an assignment operator). The +precise syntax of expressions is given in <a href="#tag_20_06_13_16">Grammar</a> .</p> +<p class="caption"><a name="tagtcjh_14" id="tagtcjh_14"></a> Table: Expressions in Decreasing Precedence in awk</p> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Syntax</b></p> +</th> +<th align="center"> +<p class="tent"><b>Name</b></p> +</th> +<th align="center"> +<p class="tent"><b>Type of Result</b></p> +</th> +<th align="center"> +<p class="tent"><b>Associativity</b></p> +</th> +</tr> + +<tr valign="top"> +<td align="left"> +<p class="tent">(<i>expr</i>)</p> +</td> +<td align="left"> +<p class="tent">Grouping</p> +</td> +<td align="left"> +<p class="tent">Type of <i>expr</i></p> +</td> +<td align="left"> +<p class="tent">N/A</p> +</td> +</tr> + +<tr valign="top"> +<td align="left"> +<p class="tent">$<i>expr</i></p> +</td> +<td align="left"> +<p class="tent">Field reference</p> +</td> +<td align="left"> +<p class="tent">Uninitialized or String</p> +</td> +<td align="left"> +<p class="tent">N/A</p> +</td> +</tr> + +<tr valign="top"> +<td align="left"> +<p class="tent">lvalue ++</p> +<p class="tent">lvalue --</p> +</td> +<td align="left"> +<p class="tent">Post-increment</p> +<p class="tent">Post-decrement</p> +</td> +<td align="left"> +<p class="tent">Numeric</p> +<p class="tent">Numeric</p> +</td> +<td align="left"> +<p class="tent">N/A</p> +<p class="tent">N/A</p> +</td> +</tr> + +<tr valign="top"> +<td align="left"> +<p class="tent">++ lvalue</p> +<p class="tent">-- lvalue</p> +</td> +<td align="left"> +<p class="tent">Pre-increment</p> +<p class="tent">Pre-decrement</p> +</td> +<td align="left"> +<p class="tent">Numeric</p> +<p class="tent">Numeric</p> +</td> +<td align="left"> +<p class="tent">N/A</p> +<p class="tent">N/A</p> +</td> +</tr> + + +<tr valign="top"> +<td align="left"> +<p class="tent"><i>expr</i> ^ <i>expr</i></p> +</td> +<td align="left"> +<p class="tent">Exponentiation</p> +</td> +<td align="left"> +<p class="tent">Numeric</p> +</td> +<td align="left"> +<p class="tent">Right</p> +</td> +</tr> + +<tr valign="top"> +<td align="left"> +<p class="tent">! <i>expr</i></p> +<p class="tent">+ <i>expr</i></p> +<p class="tent">- <i>expr</i></p> +</td> +<td align="left"> +<p class="tent">Logical not</p> +<p class="tent">Unary plus</p> +<p class="tent">Unary minus</p> +</td> +<td align="left"> +<p class="tent">Numeric</p> +<p class="tent">Numeric</p> +<p class="tent">Numeric</p> +</td> +<td align="left"> +<p class="tent">N/A</p> +<p class="tent">N/A</p> +<p class="tent">N/A</p> +</td> +</tr> + +<tr valign="top"> +<td align="left"> +<p class="tent"><i>expr</i> * <i>expr</i></p> +<p class="tent"><i>expr</i> / <i>expr</i></p> +<p class="tent"><i>expr</i> % <i>expr</i></p> +</td> +<td align="left"> +<p class="tent">Multiplication</p> +<p class="tent">Division</p> +<p class="tent">Modulus</p> +</td> +<td align="left"> +<p class="tent">Numeric</p> +<p class="tent">Numeric</p> +<p class="tent">Numeric</p> +</td> +<td align="left"> +<p class="tent">Left</p> +<p class="tent">Left</p> +<p class="tent">Left</p> +</td> +</tr> + +<tr valign="top"> +<td align="left"> +<p class="tent"><i>expr</i> + <i>expr</i></p> +<p class="tent"><i>expr</i> - <i>expr</i></p> +</td> +<td align="left"> +<p class="tent">Addition</p> +<p class="tent">Subtraction</p> +</td> +<td align="left"> +<p class="tent">Numeric</p> +<p class="tent">Numeric</p> +</td> +<td align="left"> +<p class="tent">Left</p> +<p class="tent">Left</p> +</td> +</tr> + + +<tr valign="top"> +<td align="left"> +<p class="tent"><i>expr</i> <i>expr</i></p> +</td> +<td align="left"> +<p class="tent">String concatenation</p> +</td> +<td align="left"> +<p class="tent">String</p> +</td> +<td align="left"> +<p class="tent">Left</p> +</td> +</tr> + +<tr valign="top"> +<td align="left"> +<p class="tent"><i>expr</i> < <i>expr</i></p> +<p class="tent"><i>expr</i> <= <i>expr</i></p> +<p class="tent"><i>expr</i> != <i>expr</i></p> +<p class="tent"><i>expr</i> == <i>expr</i></p> +<p class="tent"><i>expr</i> > <i>expr</i></p> +<p class="tent"><i>expr</i> >= <i>expr</i></p> +</td> +<td align="left"> +<p class="tent">Less than</p> +<p class="tent">Less than or equal to</p> +<p class="tent">Not equal to</p> +<p class="tent">Equal to</p> +<p class="tent">Greater than</p> +<p class="tent">Greater than or equal to</p> +</td> +<td align="left"> +<p class="tent">Numeric</p> +<p class="tent">Numeric</p> +<p class="tent">Numeric</p> +<p class="tent">Numeric</p> +<p class="tent">Numeric</p> +<p class="tent">Numeric</p> +</td> +<td align="left"> +<p class="tent">None</p> +<p class="tent">None</p> +<p class="tent">None</p> +<p class="tent">None</p> +<p class="tent">None</p> +<p class="tent">None</p> +</td> +</tr> + + +<tr valign="top"> +<td align="left"> +<p class="tent"><i>expr</i> ˜ <i>expr</i></p> +<p class="tent"><i>expr</i> !˜ <i>expr</i></p> +</td> +<td align="left"> +<p class="tent">ERE match</p> +<p class="tent">ERE non-match</p> +</td> +<td align="left"> +<p class="tent">Numeric</p> +<p class="tent">Numeric</p> +</td> +<td align="left"> +<p class="tent">None</p> +<p class="tent">None</p> +</td> +</tr> + +<tr valign="top"> +<td align="left"> +<p class="tent"><i>expr</i> in array</p> +<p class="tent">(<i>index</i>) in <i>array</i></p> +</td> +<td align="left"> +<p class="tent">Array membership</p> +<p class="tent">Multi-dimension array membership</p> +</td> +<td align="left"> +<p class="tent">Numeric</p> +<p class="tent">Numeric</p> +</td> +<td align="left"> +<p class="tent">Left</p> +<p class="tent">Left</p> +</td> +</tr> + +<tr valign="top"> +<td align="left"> +<p class="tent"><i>expr</i> && <i>expr</i></p> +</td> +<td align="left"> +<p class="tent">Logical AND</p> +</td> +<td align="left"> +<p class="tent">Numeric</p> +</td> +<td align="left"> +<p class="tent">Left</p> +</td> +</tr> + +<tr valign="top"> +<td align="left"> +<p class="tent"><i>expr</i> || <i>expr</i></p> +</td> +<td align="left"> +<p class="tent">Logical OR</p> +</td> +<td align="left"> +<p class="tent">Numeric</p> +</td> +<td align="left"> +<p class="tent">Left</p> +</td> +</tr> + +<tr valign="top"> +<td align="left"> +<p class="tent"><i>expr1</i> ? <i>expr2</i> : <i>expr3</i></p> +</td> +<td align="left"> +<p class="tent">Conditional expression</p> +</td> +<td align="left"> +<p class="tent">Type of selected<br><i>expr2</i> or <i>expr3</i></p> +</td> +<td align="left"> +<p class="tent">Right</p> +</td> +</tr> + +<tr valign="top"> +<td align="left"> +<p class="tent">lvalue ^= <i>expr</i></p> +<p class="tent">lvalue %= <i>expr</i></p> +<p class="tent">lvalue *= <i>expr</i></p> +<p class="tent">lvalue /= <i>expr</i></p> +<p class="tent">lvalue += <i>expr</i></p> +<p class="tent">lvalue -= <i>expr</i></p> +<p class="tent">lvalue = <i>expr</i></p> +</td> +<td align="left"> +<p class="tent">Exponentiation assignment</p> +<p class="tent">Modulus assignment</p> +<p class="tent">Multiplication assignment</p> +<p class="tent">Division assignment</p> +<p class="tent">Addition assignment</p> +<p class="tent">Subtraction assignment</p> +<p class="tent">Assignment</p> +</td> +<td align="left"> +<p class="tent">Numeric</p> +<p class="tent">Numeric</p> +<p class="tent">Numeric</p> +<p class="tent">Numeric</p> +<p class="tent">Numeric</p> +<p class="tent">Numeric</p> +<p class="tent">Type of <i>expr</i></p> +</td> +<td align="left"> +<p class="tent">Right</p> +<p class="tent">Right</p> +<p class="tent">Right</p> +<p class="tent">Right</p> +<p class="tent">Right</p> +<p class="tent">Right</p> +<p class="tent">Right</p> +</td> +</tr> + +</table> +</center> +<p class="tent">Each expression shall have either a string value, a numeric value, or both. Except as stated for specific contexts, +the value of an expression shall be implicitly converted to the type needed for the context in which it is used. A string value +shall be converted to a numeric value either by the equivalent of the following calls to functions defined by the ISO C +standard:</p> +<pre> +<tt>setlocale(LC_NUMERIC, ""); +</tt><i>numeric_value</i><tt> = atof(</tt><i>string_value</i><tt>); +</tt></pre> +<p class="tent">or by converting the initial portion of the string to type <b>double</b> representation as follows:</p> +<blockquote>The input string is decomposed into two parts: an initial, possibly empty, sequence of white-space characters (as +specified by <a href="../functions/isspace.html"><i>isspace</i>()</a>) and a subject sequence interpreted as a floating-point +constant. +<p class="tent">The expected form of the subject sequence is an optional <tt>'+'</tt> or <tt>'-'</tt> sign, then a non-empty +sequence of digits optionally containing a radix character, then an optional exponent part. An exponent part consists of +<tt>'e'</tt> or <tt>'E'</tt>, followed by an optional sign, followed by one or more decimal digits.</p> +<p class="tent">The sequence starting with the first digit or the radix character (whichever occurs first) is interpreted as a +floating constant of the C language, except that the radix character shall be used in place of a <period>, and if neither an +exponent part nor a radix character appears, a radix character is assumed to follow the last digit in the string. If the subject +sequence begins with a <hyphen-minus>, the value resulting from the conversion is negated.</p> +</blockquote> +<p class="tent">A numeric value that is exactly equal to the value of an integer (see <a href= +"../utilities/V3_chap01.html#tag_18_01_02"><i>1.1.2 Concepts Derived from the ISO C Standard</i></a> ) shall be converted to a +string by the equivalent of a call to the <b>sprintf</b> function (see <a href="#tag_20_06_13_13">String Functions</a> ) with the +string <tt>"%d"</tt> as the <i>fmt</i> argument and the numeric value being converted as the first and only <i>expr</i> argument. +Any other numeric value shall be converted to a string by the equivalent of a call to the <b>sprintf</b> function with the value of +the variable <b>CONVFMT</b> as the <i>fmt</i> argument and the numeric value being converted as the first and only <i>expr</i> +argument. The result of the conversion is unspecified if the value of <b>CONVFMT</b> is not a floating-point format specification. +This volume of POSIX.1-2024 specifies no explicit conversions between numbers and strings. An application can force an expression +to be treated as a number by adding zero to it, or can force it to be treated as a string by concatenating the null string +(<tt>""</tt>) to it.</p> +<p class="tent">A string value shall be considered a <i>numeric string</i> if it comes from one of the following:</p> +<ol> +<li class="tent">Field variables</li> +<li class="tent">Input from the <i>getline</i>() function</li> +<li class="tent"><b>FILENAME</b></li> +<li class="tent"><b>ARGV</b> array elements</li> +<li class="tent"><b>ENVIRON</b> array elements</li> +<li class="tent">Array elements created by the <i>split</i>() function</li> +<li class="tent">A command line variable assignment</li> +<li class="tent">Variable assignment from another numeric string variable</li> +</ol> +<p class="tent">and an implementation-dependent condition corresponding to either case (a) or (b) below is met.</p> +<ol type="a"> +<li class="tent">After the equivalent of the following calls to functions defined by the ISO C standard, +<i>string_value_end</i> would differ from <i>string_value</i>, and any characters before the terminating null character in +<i>string_value_end</i> would be <blank> characters: +<pre> +<tt>char *string_value_end; +setlocale(LC_NUMERIC, ""); +numeric_value = strtod (string_value, &string_value_end); +</tt></pre></li> +<li class="tent">After all the following conversions have been applied, the resulting string would lexically be recognized as a +<b>NUMBER</b> token as described by the lexical conventions in <a href="#tag_20_06_13_16">Grammar</a> : +<ul> +<li class="tent">All leading and trailing <blank> characters are discarded.</li> +<li class="tent">If the first non-<blank> is <tt>'+'</tt> or <tt>'-'</tt>, it is discarded.</li> +<li class="tent">Each occurrence of the radix character from the current locale is changed to a <period>.</li> +</ul> +</li> +</ol> +In case (a) the numeric value of the <i>numeric string</i> shall be the value that would be returned by the <a href= +"../functions/strtod.html"><i>strtod</i>()</a> call. In case (b) if the first non-<blank> is <tt>'-'</tt>, the numeric value +of the <i>numeric string</i> shall be the negation of the numeric value of the recognized <b>NUMBER</b> token; otherwise, the +numeric value of the <i>numeric string</i> shall be the numeric value of the recognized <b>NUMBER</b> token. Whether or not a +string is a <i>numeric string</i> shall be relevant only in contexts where that term is used in this section. +<p class="tent">When an expression is used in a Boolean context, if it has a numeric value, a value of zero shall be treated as +false and any other value shall be treated as true. Otherwise, a string value of the null string shall be treated as false and any +other value shall be treated as true. A Boolean context shall be one of the following:</p> +<ul> +<li class="tent">The first subexpression of a conditional expression</li> +<li class="tent">An expression operated on by logical NOT, logical AND, or logical OR</li> +<li class="tent">The second expression of a <b>for</b> statement</li> +<li class="tent">The expression of an <b>if</b> statement</li> +<li class="tent">The expression of the <b>while</b> clause in either a <b>while</b> or <b>do</b>...<b>while</b> statement</li> +<li class="tent">An expression used as a pattern (as in Overall Program Structure)</li> +</ul> +<p class="tent">All arithmetic shall follow the semantics of floating-point arithmetic as specified by the ISO C standard (see +<a href="../utilities/V3_chap01.html#tag_18_01_02"><i>1.1.2 Concepts Derived from the ISO C Standard</i></a> ).</p> +<p class="tent">The value of the expression:</p> +<pre> +<i>expr1</i><tt> ^ </tt><i>expr2</i><tt> +</tt></pre> +<p class="tent">shall be equivalent to the value returned by the ISO C standard function call:</p> +<pre> +<tt>pow(</tt><i>expr1</i><tt>, </tt><i>expr2</i><tt>) +</tt></pre> +<p class="tent">The expression:</p> +<pre> +<tt>lvalue ^= </tt><i>expr</i><tt> +</tt></pre> +<p class="tent">shall be equivalent to the ISO C standard expression:</p> +<pre> +<tt>lvalue = pow(lvalue, </tt><i>expr</i><tt>) +</tt></pre> +<p class="tent">except that lvalue shall be evaluated only once. The value of the expression:</p> +<pre> +<i>expr1</i><tt> % </tt><i>expr2</i><tt> +</tt></pre> +<p class="tent">shall be equivalent to the value returned by the ISO C standard function call:</p> +<pre> +<tt>fmod(</tt><i>expr1</i><tt>, </tt><i>expr2</i><tt>) +</tt></pre> +<p class="tent">The expression:</p> +<pre> +<tt>lvalue %= </tt><i>expr</i><tt> +</tt></pre> +<p class="tent">shall be equivalent to the ISO C standard expression:</p> +<pre> +<tt>lvalue = fmod(lvalue, </tt><i>expr</i><tt>) +</tt></pre> +<p class="tent">except that lvalue shall be evaluated only once.</p> +<p class="tent">Variables and fields shall be set by the assignment statement:</p> +<pre> +<tt>lvalue = </tt><i>expression</i><tt> +</tt></pre> +<p class="tent">and the type of <i>expression</i> shall determine the resulting variable type. The assignment includes the +arithmetic assignments (<tt>"+="</tt>, <tt>"-="</tt>, <tt>"*="</tt>, <tt>"/="</tt>, <tt>"%="</tt>, <tt>"^="</tt>, <tt>"++"</tt>, +<tt>"--"</tt>) all of which shall produce a numeric result. The left-hand side of an assignment and the target of increment and +decrement operators can be one of a variable, an array with index, or a field selector.</p> +<p class="tent">The <i>awk</i> language supplies arrays that are used for storing numbers or strings. Arrays need not be declared. +They shall initially be empty, and their sizes shall change dynamically. The subscripts, or element identifiers, are strings, +providing a type of associative array capability. An array name followed by a subscript within square brackets can be used as an +lvalue and thus as an expression, as described in the grammar; see <a href="#tag_20_06_13_16">Grammar</a> . Unsubscripted array +names can be used in only the following contexts:</p> +<ul> +<li class="tent">A parameter in a function definition or function call</li> +<li class="tent">The <b>NAME</b> token following any use of the keyword <b>in</b> as specified in the grammar (see <a href= +"#tag_20_06_13_16">Grammar</a> ); if the name used in this context is not an array name, the behavior is undefined</li> +<li class="tent">The <b>NAME</b> token following the keyword <b>Delete</b> without a subscript as specified in the grammar (see +<a href="#tag_20_06_13_16">Grammar</a> ); if the name used in this context is not an array name, the behavior is undefined.</li> +</ul> +<p class="tent">A valid array <i>index</i> shall consist of one or more <comma>-separated expressions, similar to the way in +which multi-dimensional arrays are indexed in some programming languages. Because <i>awk</i> arrays are really one-dimensional, +such a <comma>-separated list shall be converted to a single string by concatenating the string values of the separate +expressions, each separated from the other by the value of the <b>SUBSEP</b> variable. Thus, the following two index operations +shall be equivalent:</p> +<pre> +<i>var</i><b>[</b><i>expr1</i><tt>, </tt><i>expr2</i><tt>, ... </tt><i>exprn</i><b>] +<br class="tent"> +</b><i>var</i><b>[</b><i>expr1</i><tt> SUBSEP </tt><i>expr2</i><tt> SUBSEP ... SUBSEP </tt><i>exprn</i><b>]</b><tt> +</tt></pre> +<p class="tent">The application shall ensure that a multi-dimensioned <i>index</i> used with the <b>in</b> operator is +parenthesized. The <b>in</b> operator, which tests for the existence of a particular array element, shall not cause that element to +exist. Any other reference to a nonexistent array element shall automatically create it.</p> +<p class="tent">Comparisons (with the <tt>'<'</tt>, <tt>"<="</tt>, <tt>"!="</tt>, <tt>"=="</tt>, <tt>'>'</tt>, and +<tt>">="</tt> operators) shall be made numerically:</p> +<ul> +<li class="tent">if both operands are numeric,</li> +<li class="tent">if one is numeric and the other has a string value that is a numeric string,</li> +<li class="tent">if both have string values that are numeric strings, or</li> +<li class="tent">if one is numeric and the other has the uninitialized value.</li> +</ul> +<p class="tent">Otherwise, operands shall be converted to strings as required and a string comparison shall be made as follows:</p> +<ul> +<li class="tent">For the <tt>"!="</tt> and <tt>"=="</tt> operators, the strings shall be compared to check if they are identical +(not to check if they collate equally).</li> +<li class="tent">For the other operators, the strings shall be compared using the locale-specific collation sequence.</li> +</ul> +<p class="tent">The value of the comparison expression shall be 1 if the relation is true, or 0 if the relation is false.</p> +<h5><a name="tag_20_06_13_03" id="tag_20_06_13_03"></a>Variables and Special Variables</h5> +<p class="tent">Variables can be used in an <i>awk</i> program by referencing them. With the exception of function parameters (see +<a href="#tag_20_06_13_15">User-Defined Functions</a> ), they are not explicitly declared. Function parameter names shall be local +to the function; all other variable names shall be global. The same name shall not be used as both a function parameter name and as +the name of a function or a special <i>awk</i> variable. The same name shall not be used both as a variable name with global scope +and as the name of a function. The same name shall not be used within the same scope both as a scalar variable and as an array. +Uninitialized variables, including scalar variables, array elements, and field variables, shall have an uninitialized value. An +uninitialized value shall have both a numeric value of zero and a string value of the empty string. Evaluation of variables with an +uninitialized value, to either string or numeric, shall be determined by the context in which they are used.</p> +<p class="tent">Field variables shall be designated by a <tt>'$'</tt> followed by a number or numerical expression. The effect of +the field number <i>expression</i> evaluating to anything other than a non-negative integer is unspecified; uninitialized variables +or string values need not be converted to numeric values in this context. New field variables can be created by assigning a value +to them. References to nonexistent fields (that is, fields after $<b>NF</b>), shall evaluate to the uninitialized value. Such +references shall not create new fields. However, assigning to a nonexistent field (for example, $(<b>NF</b>+2)=5) shall increase +the value of <b>NF</b>; create any intervening fields with the uninitialized value; and cause the value of $0 to be recomputed, +with the fields being separated by the value of <b>OFS</b>. Each field variable shall have a string value or an uninitialized value +when created. Field variables shall have the uninitialized value when created from $0 using <b>FS</b> and the variable does not +contain any characters. If appropriate, the field variable shall be considered a numeric string (see <a href= +"#tag_20_06_13_02">Expressions in awk</a> ).</p> +<p class="tent">Implementations shall support the following other special variables that are set by <i>awk</i>:</p> +<dl compact> +<dd></dd> +<dt><b>ARGC</b></dt> +<dd>A number determining when the iteration described for <b>ARGV</b> stops. When an <i>awk</i> program starts, <b>ARGC</b> shall +be initialized to the number of elements in the <b>ARGV</b> array. <b>ARGC</b> can be updated by the <i>awk</i> program and by +assignment operands. If <b>ARGC</b> is set to a value less than 1, the behavior is unspecified. It is unspecified whether +alterations to <b>ARGC</b> can be made using the <b>-v</b> option.</dd> +<dt><b>ARGV</b></dt> +<dd>An array containing, initially, the command name (see <a href="../utilities/V3_chap02.html#tag_19_09_01"><i>2.9.1 Simple +Commands</i></a> ) used to invoke <i>awk</i> in <tt>ARGV[0]</tt> and the command line arguments, if any, excluding options and the +<i>program</i> operand, in <tt>ARGV[1]</tt> through <tt>ARGV[ARGC-1]</tt>. The elements in <b>ARGV</b> can be assigned new values +or deleted, and new elements can be added. Note that alterations to <b>ARGV</b> cannot be made using either the <i>assignment</i> +operand or the <b>-v</b> option, because an operand with a <tt>'['</tt> before <tt>'='</tt> is treated as a <i>file</i> operand, +not an <i>assignment</i> operand, and applications are required to ensure that the <b>-v</b> option-argument has the same form as +an <i>assignment</i> operand. (See the OPTIONS and OPERANDS sections.) +<p class="tent">After processing the <b>BEGIN</b> actions, if any, <i>awk</i> begins interating over the elements of <b>ARGV</b>, +processing them as if they were <i>argument</i> operands. It shall behave as if the implementation maintains an internal counter +that is initialized to 1 and increments by 1 at the end of each iteration. For each iteration, the following shall occur:</p> +<ul> +<li class="tent">If the internal counter is greater than or equal to the current value of <b>ARGC</b> and no <i>file</i> operands +have been processed, <i>awk</i> shall set <b>FILENAME</b> to <tt>'-'</tt> and process standard input as if it was given as a file +operand. The internal counter shall not be incremented at the end of this iteration.</li> +<li class="tent">Otherwise, if the internal counter is greater than or equal to the current value of <b>ARGC</b>, the iterations +shall stop and processing of the <b>END</b> actions, if any, shall begin. Any <b>ARGV</b> elements with index values greater than +or equal to <b>ARGC</b> shall not be processed as <i>argument</i> operands.</li> +<li class="tent">Otherwise, if the element <tt>ARGV[</tt> <i>internal counter value</i><tt>]</tt> does not exist, it is unspecified +whether that element is created. No other action shall be taken.</li> +<li class="tent">Otherwise, if <tt>ARGV[</tt> <i>internal counter value</i><tt>]</tt> is a null string, no action shall be +taken.</li> +<li class="tent">Otherwise, if <tt>ARGV[</tt> <i>internal counter value</i><tt>]</tt> matches the format of an <i>assignment</i> +operand (see OPERANDS), <i>awk</i> shall process the assignment.</li> +<li class="tent">Otherwise, <tt>ARGV[</tt> <i>internal counter value</i><tt>]</tt> shall be treated as a <i>file</i> operand, +<b>FILENAME</b> shall be set to that value, and the named file, or standard input if the value is <tt>'-'</tt>, shall be processed +as an input file.</li> +</ul> +<p class="tent">Since only non-null elements are processed, setting an element of <b>ARGV</b> to the null string or deleting it +means that it shall not be treated as an <i>argument</i> operand.</p> +</dd> +<dt><b>CONVFMT</b></dt> +<dd>The <b>printf</b> format for converting numbers to strings (except for output statements, where <b>OFMT</b> is used); +<tt>"%.6g"</tt> by default.</dd> +<dt><b>ENVIRON</b></dt> +<dd>An array representing the value of the environment, as described in the <i>exec</i> functions defined in the System Interfaces +volume of POSIX.1-2024. The indices of the array shall be strings consisting of the names of the environment variables, and the +value of each array element shall be a string consisting of the value of that variable. If appropriate, the environment variable +shall be considered a <i>numeric string</i> (see <a href="#tag_20_06_13_02">Expressions in awk</a> ); the array element shall also +have its numeric value. +<p class="tent">In all cases where the behavior of <i>awk</i> is affected by environment variables (including the environment of +any commands that <i>awk</i> executes via the <b>system</b> function or via pipeline redirections with the <b>print</b> statement, +the <b>printf</b> statement, or the <b>getline</b> function), the environment used shall be the environment at the time <i>awk</i> +began executing; it is implementation-defined whether any modification of <b>ENVIRON</b> affects this environment.</p> +</dd> +<dt><b>FILENAME</b></dt> +<dd>The pathname used to open the current input file, or <tt>'-'</tt> if the file is standard input. Inside a <b>BEGIN</b> action +<b>FILENAME</b> shall be unset. Inside an <b>END</b> action the value shall be the name of the last input file processed. If an +application changes the value of <b>FILENAME</b>, the results are unspecified.</dd> +<dt><b>FNR</b></dt> +<dd>The ordinal number of the current record in the current file. Inside a <b>BEGIN</b> action the value shall be zero. Inside an +<b>END</b> action the value shall be the number of the last record processed in the last file processed.</dd> +<dt><b>FS</b></dt> +<dd>Input field separator regular expression; a <space> by default.</dd> +<dt><b>NF</b></dt> +<dd>The number of fields in the current record. Inside a <b>BEGIN</b> action, the use of <b>NF</b> is undefined unless a +<b>getline</b> function without a <i>var</i> argument is executed previously. Inside an <b>END</b> action, <b>NF</b> shall retain +the value it had for the last record read, unless a subsequent, redirected, <b>getline</b> function without a <i>var</i> argument +is performed prior to entering the <b>END</b> action.</dd> +<dt><b>NR</b></dt> +<dd>The ordinal number of the current record from the start of input. Inside a <b>BEGIN</b> action the value shall be zero. Inside +an <b>END</b> action the value shall be the number of the last record processed. Records skipped by the <b>nextfile</b> statement +shall not be included.</dd> +<dt><b>OFMT</b></dt> +<dd>The <b>printf</b> format for converting numbers to strings in output statements (see <a href="#tag_20_06_13_10">Output +Statements</a> ); <tt>"%.6g"</tt> by default. The result of the conversion is unspecified if the value of <b>OFMT</b> is not a +floating-point format specification.</dd> +<dt><b>OFS</b></dt> +<dd>The <b>print</b> statement output field separator; <space> by default.</dd> +<dt><b>ORS</b></dt> +<dd>The <b>print</b> statement output record separator; a <newline> by default.</dd> +<dt><b>RLENGTH</b></dt> +<dd>The length of the string matched by the <b>match</b> function.</dd> +<dt><b>RS</b></dt> +<dd>The first character of the string value of <b>RS</b> shall be the input record separator; a <newline> by default. If +<b>RS</b> contains more than one character, the results are unspecified. If <b>RS</b> is null, then records are separated by +sequences consisting of a <newline> plus one or more blank lines, leading or trailing blank lines shall not result in empty +records at the beginning or end of the input, and a <newline> shall always be a field separator, no matter what the value of +<b>FS</b> is.</dd> +<dt><b>RSTART</b></dt> +<dd>The starting position of the string matched by the <b>match</b> function, numbering from 1. This shall always be equivalent to +the return value of the <b>match</b> function.</dd> +<dt><b>SUBSEP</b></dt> +<dd>The subscript separator string for multi-dimensional arrays; the default value is implementation-defined.</dd> +</dl> +<h5><a name="tag_20_06_13_04" id="tag_20_06_13_04"></a>Regular Expressions</h5> +<p class="tent">The <i>awk</i> utility shall make use of the extended regular expression notation (see XBD <a href= +"../basedefs/V1_chap09.html#tag_09_04"><i>9.4 Extended Regular Expressions</i></a> ) except that it shall allow the use of +C-language conventions for escaping special characters within the EREs, as specified in the table in XBD <a href= +"../basedefs/V1_chap05.html#tag_05"><i>5. File Format Notation</i></a> for <tt>'\\'</tt>, <tt>'\a'</tt>, <tt>'\b'</tt>, +<tt>'\f'</tt>, <tt>'\n'</tt>, <tt>'\r'</tt>, <tt>'\t'</tt>, <tt>'\v'</tt> and in the following table for other sequences; these +escape sequences shall be recognized both inside and outside bracket expressions. Note that records need not be separated by +<newline> characters and string constants can contain <newline> characters, so even the <tt>"\n"</tt> sequence is valid +in <i>awk</i> EREs. Using a <slash> character within the lexical token <b>ERE</b> (except as one of the two delimiters) +requires the escaping shown in the following table.<br></p> +<p class="caption"><a name="tagtcjh_15" id="tagtcjh_15"></a> Table: Escape Sequences in awk</p> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Escape Sequence</b></p> +</th> +<th align="center"> +<p class="tent"><b>Description</b></p> +</th> +<th align="center"> +<p class="tent"><b>Meaning</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">\"</p> +</td> +<td align="left"> +<p class="tent"><backslash> <quotation-mark></p> +</td> +<td align="left"> +<p class="tent">In the lexical token <b>STRING</b>, <quotation-mark> character. Otherwise undefined.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">\/</p> +</td> +<td align="left"> +<p class="tent"><backslash> <slash></p> +</td> +<td align="left"> +<p class="tent">In the lexical token <b>ERE</b>, <slash> character. Otherwise undefined.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">\ddd</p> +</td> +<td align="left"> +<p class="tent">A <backslash> character followed by the longest sequence of one, two, or three octal-digit characters +(01234567). If all of the digits are 0 (that is, representation of the NUL character), the behavior is undefined. If the digits +produce a value greater than octal 377, the behavior is undefined.</p> +</td> +<td align="left"> +<p class="tent">The character whose encoding is represented by the one, two, or three-digit octal integer. Multi-byte characters +require multiple, concatenated escape sequences of this type, including the leading <backslash> for each byte.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">\., \[, \(,\*, \+, \?, \{, \|, \^, \$</p> +</td> +<td align="left"> +<p class="tent">A <backslash> character followed by a character that has a special meaning in EREs (see XBD <a href= +"../basedefs/V1_chap09.html#tag_09_04"><i>9.4 Extended Regular Expressions</i></a> ), other than <backslash>.</p> +</td> +<td align="left"> +<p class="tent">In the lexical token <b>ERE</b> when not inside a bracket expression, the sequence shall represent itself. +Otherwise undefined.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">\\</p> +</td> +<td align="left"> +<p class="tent">Two <backslash> characters.</p> +</td> +<td align="left"> +<p class="tent">In the lexical token <b>ERE</b>, the sequence shall represent itself. In the lexical token <b>STRING</b>, it shall +represent a single <backslash>.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">\c</p> +</td> +<td align="left"> +<p class="tent">A <backslash> character followed by any character not described in this table or in the table in XBD <a href= +"../basedefs/V1_chap05.html#tag_05"><i>5. File Format Notation</i></a> (<tt>'\\'</tt>, <tt>'\a'</tt>, <tt>'\b'</tt>, <tt>'\f'</tt>, +<tt>'\n'</tt>, <tt>'\r'</tt>, <tt>'\t'</tt>, <tt>'\v'</tt>).</p> +</td> +<td align="left"> +<p class="tent">Undefined</p> +</td> +</tr> +</table> +</center> +<p class="tent">A regular expression can be matched against a specific field or string by using one of the two regular expression +matching operators, <tt>'~'</tt> and <tt>"!~"</tt>. These operators shall interpret their right-hand operand as a regular +expression and their left-hand operand as a string. If the regular expression matches the string, the <tt>'~'</tt> expression shall +evaluate to a value of 1, and the <tt>"!~"</tt> expression shall evaluate to a value of 0. (The regular expression matching +operation is as defined by the term matched in XBD <a href="../basedefs/V1_chap09.html#tag_09_01"><i>9.1 Regular Expression +Definitions</i></a> , where a match occurs on any part of the string unless the regular expression is limited with the +<circumflex> or <dollar-sign> special characters.) If the regular expression does not match the string, the +<tt>'~'</tt> expression shall evaluate to a value of 0, and the <tt>"!~"</tt> expression shall evaluate to a value of 1. If the +right-hand operand is any expression other than the lexical token <b>ERE</b>, the string value of the expression shall be +interpreted as an extended regular expression, including the escape conventions described above. Note that these escape conventions +shall also be applied in determining the value of a string literal (the lexical token <b>STRING</b>), and thus shall be applied a +second time when a string literal is used in this context.</p> +<p class="tent">When an <b>ERE</b> token appears as an expression in any context other than as the right-hand of the <tt>'~'</tt> +or <tt>"!~"</tt> operator or as one of the built-in function arguments described below, the value of the resulting expression shall +be the equivalent of:</p> +<pre> +<tt>$0 ~ /</tt><i>ere</i><tt>/ +</tt></pre> +<p class="tent">The <i>ere</i> argument to the <b>gsub</b>, <b>match</b>, <b>sub</b> functions, and the <i>fs</i> argument to the +<b>split</b> function (see <a href="#tag_20_06_13_13">String Functions</a> ) shall be interpreted as extended regular expressions. +These can be either <b>ERE</b> tokens or arbitrary expressions, and shall be interpreted in the same manner as the right-hand side +of the <tt>'~'</tt> or <tt>"!~"</tt> operator.</p> +<p class="tent">An extended regular expression can be used to separate fields by assigning a string containing the expression to +the built-in variable <b>FS</b>, either directly or as a consequence of using the <b>-F</b> <i>sepstring</i> option. The default +value of the <b>FS</b> variable shall be a single <space>. The following describes <b>FS</b> behavior:</p> +<ol> +<li class="tent">If <b>FS</b> is a null string, the behavior is unspecified.</li> +<li class="tent">If <b>FS</b> is a single character: +<ol type="a"> +<li class="tent">If <b>FS</b> is <space>, skip leading and trailing <blank> and <newline> characters; fields +shall be delimited by sets of one or more <blank> or <newline> characters.</li> +<li class="tent">Otherwise, if <b>FS</b> is any other character <i>c</i>, fields shall be delimited by each single occurrence of +<i>c</i>.</li> +</ol> +</li> +<li class="tent">Otherwise, the string value of <b>FS</b> shall be considered to be an extended regular expression. Each occurrence +of a sequence of one or more characters matching the extended regular expression shall delimit fields.</li> +</ol> +<p class="tent">When ERE matching is performed against input records; that is, the match is against $0 and the current value of $0 +resulted from processing an input record, record separator characters (the first character of the value of the variable <b>RS</b>, +<newline> by default) cannot be embedded in the expression, and no expression shall match the record separator character. If +the record separator is not <newline>, <newline> characters embedded in the expression can be matched. When ERE +matching is not performed against input records, it shall be based on text strings; any character (including <newline> and +the record separator) can be embedded in the pattern, and an appropriate pattern shall match any character. However, in all +<i>awk</i> ERE matching, the use of one or more NUL characters in the pattern, input record, or text string produces undefined +results.</p> +<h5><a name="tag_20_06_13_05" id="tag_20_06_13_05"></a>Patterns</h5> +<p class="tent">A <i>pattern</i> is any valid <i>expression</i>, a range specified by two expressions separated by a comma, or one +of the two special patterns <b>BEGIN</b> or <b>END</b>.</p> +<h5><a name="tag_20_06_13_06" id="tag_20_06_13_06"></a>Special Patterns</h5> +<p class="tent">The <i>awk</i> utility shall recognize two special patterns, <b>BEGIN</b> and <b>END</b>. Each <b>BEGIN</b> pattern +shall be matched once and its associated action executed before the first record of input is read—except possibly by use of the +<b>getline</b> function (see <a href="#tag_20_06_13_14">Input/Output and General Functions</a> ) in a prior <b>BEGIN</b> action—and +before command line assignment is done. Each <b>END</b> pattern shall be matched once and its associated action executed after the +last record of input has been read, or if there is no further input file to process following a <b>nextfile</b> statement. These +two patterns shall have associated actions.</p> +<p class="tent"><b>BEGIN</b> and <b>END</b> shall not combine with other patterns. Multiple <b>BEGIN</b> and <b>END</b> patterns +shall be allowed. The actions associated with the <b>BEGIN</b> patterns shall be executed in the order specified in the program, as +are the <b>END</b> actions. An <b>END</b> pattern can precede a <b>BEGIN</b> pattern in a program.</p> +<p class="tent">If an <i>awk</i> program consists of only actions with the pattern <b>BEGIN</b>, and the <b>BEGIN</b> action +contains no <b>getline</b> function, <i>awk</i> shall exit without reading its input when the last statement in the last +<b>BEGIN</b> action is executed. If an <i>awk</i> program consists of only actions with the pattern <b>END</b> or only actions with +the patterns <b>BEGIN</b> and <b>END</b>, the input shall be read before the statements in the <b>END</b> actions are executed.</p> +<h5><a name="tag_20_06_13_07" id="tag_20_06_13_07"></a>Expression Patterns</h5> +<p class="tent">An expression pattern shall be evaluated as if it were an expression in a Boolean context. If the result is true, +the pattern shall be considered to match, and the associated action (if any) shall be executed. If the result is false, the action +shall not be executed.</p> +<h5><a name="tag_20_06_13_08" id="tag_20_06_13_08"></a>Pattern Ranges</h5> +<p class="tent">A pattern range consists of two expressions separated by a comma; in this case, the action shall be performed for +all records between a match of the first expression and the following match of the second expression, inclusive. At this point, the +pattern range can be repeated starting at input records subsequent to the end of the matched range.</p> +<h5><a name="tag_20_06_13_09" id="tag_20_06_13_09"></a>Actions</h5> +<p class="tent">An action is a sequence of statements as shown in the grammar in <a href="#tag_20_06_13_16">Grammar</a> . Any +single statement can be replaced by a statement list enclosed in curly braces. The application shall ensure that statements in a +statement list are separated by <newline> or <semicolon> characters. Statements in a statement list shall be executed +sequentially in the order that they appear.</p> +<p class="tent">The <i>expression</i> acting as the conditional in an <b>if</b> statement shall be evaluated and if it is non-zero +or non-null, the following statement shall be executed; otherwise, if <b>else</b> is present, the statement following the +<b>else</b> shall be executed.</p> +<p class="tent">The <b>if</b>, <b>while</b>, <b>do</b>...<b>while</b>, <b>for</b>, <b>break</b>, and <b>continue</b> statements are +based on the ISO C standard (see <a href="../utilities/V3_chap01.html#tag_18_01_02"><i>1.1.2 Concepts Derived from the ISO C +Standard</i></a> ), except that the Boolean expressions shall be treated as described in <a href="#tag_20_06_13_02">Expressions in +awk</a> , and except in the case of:</p> +<pre> +<tt>for (</tt><i>variable</i><tt> in </tt><i>array</i><tt>) +</tt></pre> +<p class="tent">which shall iterate, assigning each <i>index</i> of <i>array</i> to <i>variable</i> in an unspecified order. The +results of adding new elements to <i>array</i> within such a <b>for</b> loop are undefined. If a <b>break</b> or <b>continue</b> +statement occurs outside of a loop, the behavior is undefined.</p> +<p class="tent">The <b>delete</b> statement shall remove either a specified individual array element or, if no element is +specified, all array elements. Thus, the following code:</p> +<pre> +<tt>for (index in array) + delete array[index] +</tt></pre> +<p class="tent">is equivalent to:</p> +<pre> +<tt>delete array +</tt></pre> +<p class="tent">Both delete all elements of the array.</p> +<p class="tent">The <b>next</b> statement shall cause all further processing of the current input record to be abandoned. The +behavior is undefined if a <b>next</b> statement appears or is invoked in a <b>BEGIN</b> or <b>END</b> action.</p> +<p class="tent">The <b>nextfile</b> statement shall cause all further processing of the current input file to be abandoned. The +behavior is undefined if a <b>nextfile</b> statement appears or is invoked in a <b>BEGIN</b> or <b>END</b> action, or in a +user-defined function.</p> +<p class="tent">The <b>exit</b> statement shall invoke all <b>END</b> actions in the order in which they occur in the program +source and then terminate the program without reading further input. An <b>exit</b> statement inside an <b>END</b> action shall +terminate the program without further execution of <b>END</b> actions. If an expression is specified in an <b>exit</b> statement, +its numeric value shall be the exit status of <i>awk</i>, unless subsequent errors are encountered or a subsequent <b>exit</b> +statement with an expression is executed.</p> +<h5><a name="tag_20_06_13_10" id="tag_20_06_13_10"></a>Output Statements</h5> +<p class="tent">Both <b>print</b> and <b>printf</b> statements shall write to standard output by default. The output shall be +written to the location specified by <i>output_redirection</i> if one is supplied, as follows:</p> +<pre> +<tt>> </tt><i>expression</i><tt> +>> </tt><i>expression</i><tt> +| </tt><i>expression</i><tt> +</tt></pre> +<p class="tent">In all cases, the <i>expression</i> shall be evaluated to produce a string that is used as a pathname into which to +write (for <tt>'>'</tt> or <tt>">>"</tt>) or as a command to be executed (for <tt>'|'</tt>). Using the first two forms, if +the file of that name is not currently open, it shall be opened, creating it if necessary and using the first form, truncating the +file. The output then shall be appended to the file. As long as the file remains open, subsequent calls in which <i>expression</i> +evaluates to the same string value shall simply append output to the file. The file remains open until the <b>close</b> function +(see <a href="#tag_20_06_13_14">Input/Output and General Functions</a> ) is called with an expression that evaluates to the same +string value.</p> +<p class="tent">The third form shall write output onto a stream piped to the input of a command. The stream shall be created if no +stream is currently open with the value of <i>expression</i> as its command name. The stream created shall be equivalent to one +created by a call to the <a href="../functions/popen.html"><i>popen</i>()</a> function defined in the System Interfaces volume of +POSIX.1-2024 with the value of <i>expression</i> as the <i>command</i> argument and a value of <i>w</i> as the <i>mode</i> +argument. As long as the stream remains open, subsequent calls in which <i>expression</i> evaluates to the same string value shall +write output to the existing stream. The stream shall remain open until the <b>close</b> function (see <a href= +"#tag_20_06_13_14">Input/Output and General Functions</a> ) is called with an expression that evaluates to the same string value. +At that time, the stream shall be closed as if by a call to the <a href="../functions/pclose.html"><i>pclose</i>()</a> function +defined in the System Interfaces volume of POSIX.1-2024.</p> +<p class="tent">As described in detail by the grammar in <a href="#tag_20_06_13_16">Grammar</a> , these output statements shall +take a <comma>-separated list of <i>expression</i>s referred to in the grammar by the non-terminal symbols <b>expr_list</b>, +<b>print_expr_list</b>, or <b>print_expr_list_opt</b>. This list is referred to here as the <i>expression list</i>, and each member +is referred to as an <i>expression argument</i>.</p> +<p class="tent">The <b>print</b> statement shall write the value of each expression argument onto the indicated output stream +separated by the current output field separator (see variable <b>OFS</b> above), and terminated by the output record separator (see +variable <b>ORS</b> above). All expression arguments shall be taken as strings, being converted if necessary; this conversion shall +be as described in <a href="#tag_20_06_13_02">Expressions in awk</a> , with the exception that the <b>printf</b> format in +<b>OFMT</b> shall be used instead of the value in <b>CONVFMT</b>. An empty expression list shall stand for the whole input record +($0).</p> +<p class="tent">The <b>printf</b> statement shall produce output based on a notation similar to the File Format Notation used to +describe file formats in this volume of POSIX.1-2024 (see XBD <a href="../basedefs/V1_chap05.html#tag_05"><i>5. File Format +Notation</i></a> ). Output shall be produced as specified with the first <i>expression</i> argument as the string <i>format</i> and +subsequent <i>expression</i> arguments as the strings <i>arg1</i> to <i>argn</i>, inclusive, with the following exceptions:</p> +<ol> +<li class="tent">The <i>format</i> shall be an actual character string rather than a graphical representation. Therefore, it cannot +contain empty character positions. The <space> in the <i>format</i> string, in any context other than a <i>flag</i> of a +conversion specification, shall be treated as an ordinary character that is copied to the output.</li> +<li class="tent">If the character set contains a <tt>'Δ'</tt> character and that character appears in the <i>format</i> string, it +shall be treated as an ordinary character that is copied to the output.</li> +<li class="tent">The <i>escape sequences</i> beginning with a <backslash> character shall be treated as sequences of ordinary +characters that are copied to the output. Note that these same sequences shall be interpreted lexically by <i>awk</i> when they +appear in literal strings, but they shall not be treated specially by the <b>printf</b> statement.</li> +<li class="tent">A <i>field width</i> or <i>precision</i> can be specified as the <tt>'*'</tt> character instead of a digit string. +In this case the next argument from the expression list shall be fetched and its numeric value taken as the field width or +precision.</li> +<li class="tent">The implementation shall not precede or follow output from the <tt>d</tt> or <tt>u</tt> conversion specifier +characters with <blank> characters not specified by the <i>format</i> string.</li> +<li class="tent">The implementation shall not precede output from the <tt>o</tt> conversion specifier character with leading zeros +not specified by the <i>format</i> string.</li> +<li class="tent">For the <tt>c</tt> conversion specifier character: if the argument has a numeric value, the character whose +encoding is that value shall be output. If the value is zero or is not the encoding of any character in the character set, the +behavior is undefined. If the argument does not have a numeric value, the first character of the string value shall be output; if +the string does not contain any characters, the behavior is undefined.</li> +<li class="tent">For each conversion specification that consumes an argument, the next expression argument shall be evaluated. With +the exception of the <tt>c</tt> conversion specifier character, the value shall be converted (according to the rules specified in +<a href="#tag_20_06_13_02">Expressions in awk</a> ) to the appropriate type for the conversion specification.</li> +<li class="tent">If there are insufficient expression arguments to satisfy all the conversion specifications in the <i>format</i> +string, the behavior is undefined.</li> +<li class="tent">If any character sequence in the <i>format</i> string begins with a <tt>'%'</tt> character, but does not form a +valid conversion specification, the behavior is unspecified.</li> +</ol> +<p class="tent">Both <b>print</b> and <b>printf</b> can output at least {LINE_MAX} bytes.</p> +<h5><a name="tag_20_06_13_11" id="tag_20_06_13_11"></a>Functions</h5> +<p class="tent">The <i>awk</i> language has a variety of built-in functions: arithmetic, string, input/output, and general.</p> +<p class="tent">Function parameters, if present, can be either scalars or arrays; the behavior is undefined if an array name is +passed as a parameter that the function uses as a scalar, or if a scalar expression is passed as a parameter that the function uses +as an array. Function parameters shall be passed by value if scalar and by reference if array name.</p> +<h5><a name="tag_20_06_13_12" id="tag_20_06_13_12"></a>Arithmetic Functions</h5> +<p class="tent">The arithmetic functions, except for <b>int</b>, shall be based on the ISO C standard (see <a href= +"../utilities/V3_chap01.html#tag_18_01_02"><i>1.1.2 Concepts Derived from the ISO C Standard</i></a> ). The behavior is undefined +in cases where the ISO C standard specifies that an error be returned or that the behavior is undefined. Although the grammar +(see <a href="#tag_20_06_13_16">Grammar</a> ) permits built-in functions to appear with no arguments or parentheses, unless the +argument or parentheses are indicated as optional in the following list (by displaying them within the <tt>"[]"</tt> brackets), +such use is undefined.</p> +<dl compact> +<dd></dd> +<dt><b>atan2</b>(<i>y</i>,<i>x</i>)</dt> +<dd>Return arctangent of <i>y</i>/<i>x</i> in radians in the range [-ℼ,ℼ].</dd> +<dt><b>cos</b>(<i>x</i>)</dt> +<dd>Return cosine of <i>x</i>, where <i>x</i> is in radians.</dd> +<dt><b>sin</b>(<i>x</i>)</dt> +<dd>Return sine of <i>x</i>, where <i>x</i> is in radians.</dd> +<dt><b>exp</b>(<i>x</i>)</dt> +<dd>Return the exponential function of <i>x</i>.</dd> +<dt><b>log</b>(<i>x</i>)</dt> +<dd>Return the natural logarithm of <i>x</i>.</dd> +<dt><b>sqrt</b>(<i>x</i>)</dt> +<dd>Return the square root of <i>x</i>.</dd> +<dt><b>int</b>(<i>x</i>)</dt> +<dd>Return the argument truncated to an integer. Truncation shall be toward 0 when <i>x</i>>0.</dd> +<dt><b>rand</b>()</dt> +<dd>Return a floating point pseudo-random number <i>n</i>, such that 0<=<i>n</i><1.</dd> +<dt><b>srand</b>(<b>[</b><i>expr</i><b>]</b>)</dt> +<dd>Set the seed value for <b>rand</b> to <i>expr</i> or use the seconds since the Epoch if <i>expr</i> is omitted. The previous +seed value shall be returned. The behavior is unspecified if <i>expr</i> is not an integer expression or if the value of +<i>expr</i> is not within the range 0 through 2<sup><small>31</small></sup>-1 (2147483647), inclusive. The initial seed value is +unspecified if <b>rand</b> is called without calling <b>srand</b> first. The <b>srand</b> function uses the argument as a seed for +a new sequence of pseudo-random numbers to be returned by subsequent calls to <b>rand</b>. If <b>srand</b> is then called with the +same seed value, the sequence of pseudo-random numbers shall be repeated.</dd> +</dl> +<h5><a name="tag_20_06_13_13" id="tag_20_06_13_13"></a>String Functions</h5> +<p class="tent">The string functions in the following list shall be supported. Although the grammar (see <a href= +"#tag_20_06_13_16">Grammar</a> ) permits built-in functions to appear with no arguments or parentheses, unless the argument or +parentheses are indicated as optional in the following list (by displaying them within the <tt>"[]"</tt> brackets), such use is +undefined.</p> +<dl compact> +<dd></dd> +<dt><b>gsub</b>(<i>ere</i>, <i>repl</i><b>[</b>, <i>in</i><b>]</b>)</dt> +<dd> +Behave like <b>sub</b> (see below), except that it shall replace all occurrences of the regular expression (like the <a href= +"../utilities/ed.html"><i>ed</i></a> utility global substitute) in $0 or in the <i>in</i> argument, when specified.</dd> +<dt><b>index</b>(<i>s</i>, <i>t</i>)</dt> +<dd>Return the position, in characters, numbering from 1, in string <i>s</i> where string <i>t</i> first occurs, or zero if it does +not occur at all.</dd> +<dt><b>length[</b>(<b>[</b><i>arg</i><b>]</b>)<b>]</b></dt> +<dd> +If <i>arg</i> is an array, return the number of elements in the array; otherwise, return the length, in characters, of <i>arg</i> +taken as a string, or of the whole record, $0, if there is no argument.</dd> +<dt><b>match</b>(<i>s</i>, <i>ere</i>)</dt> +<dd>Return the position, in characters, numbering from 1, in string <i>s</i> where the extended regular expression <i>ere</i> +occurs, or zero if it does not occur at all. RSTART shall be set to the starting position (which is the same as the returned +value), zero if no match is found; RLENGTH shall be set to the length of the matched string, -1 if no match is found.</dd> +<dt><b>split</b>(<i>s</i>, <i>a</i><b>[</b>, <i>fs </i><b>]</b>)</dt> +<dd> +Split the string <i>s</i> into array elements <i>a</i>[1], <i>a</i>[2], ..., <i>a</i>[<i>n</i>], and return <i>n</i>. All elements +of the array shall be deleted before the split is performed. The separation shall be done with the ERE <i>fs</i> or with the field +separator <b>FS</b> if <i>fs</i> is not given. Each array element shall have a string value when created and, if appropriate, the +array element shall be considered a numeric string (see <a href="#tag_20_06_13_02">Expressions in awk</a> ). The effect of a null +string as the value of <i>fs</i> is unspecified.</dd> +<dt><b>sprintf</b>(<i>fmt</i>, <i>expr</i>, <i>expr</i>, ...)</dt> +<dd> +Format the expressions according to the <b>printf</b> format given by <i>fmt</i> and return the resulting string.</dd> +<dt><b>sub(</b><i>ere</i>, <i>repl</i><b>[</b>, <i>in </i><b>]</b>)</dt> +<dd> +Substitute the string <i>repl</i> in place of the first instance of the extended regular expression <i>ERE</i> in string <i>in</i> +and return the number of substitutions. An <ampersand> (<tt>'&'</tt>) appearing in the string <i>repl</i> shall be +replaced by the string from <i>in</i> that matches the ERE. An <ampersand> preceded with a <backslash> shall be +interpreted as the literal <ampersand> character. An occurrence of two consecutive <backslash> characters shall be +interpreted as just a single literal <backslash> character. Any other occurrence of a <backslash> (for example, +preceding any other character) shall be treated as a literal <backslash> character. Note that if <i>repl</i> is a string +literal (the lexical token <b>STRING</b>; see <a href="#tag_20_06_13_16">Grammar</a> ), the handling of the <ampersand> +character occurs after any lexical processing, including any lexical <backslash>-escape sequence processing. If <i>in</i> is +specified and it is not an lvalue (see <a href="#tag_20_06_13_02">Expressions in awk</a> ), the behavior is undefined. If <i>in</i> +is omitted, <i>awk</i> shall use the current record ($0) in its place.</dd> +<dt><b>substr</b>(<i>s</i>, <i>m</i><b>[</b>, <i>n </i><b>]</b>)</dt> +<dd> +Return the at most <i>n</i>-character substring of <i>s</i> that begins at position <i>m</i>, numbering from 1. If <i>n</i> is +omitted, or if <i>n</i> specifies more characters than are left in the string, the length of the substring shall be limited by the +length of the string <i>s</i>.</dd> +<dt><b>tolower</b>(<i>s</i>)</dt> +<dd>Return a string based on the string <i>s</i>. Each character in <i>s</i> that is an uppercase letter specified to have a +<b>tolower</b> mapping by the <i>LC_CTYPE</i> category of the current locale shall be replaced in the returned string by the +lowercase letter specified by the mapping. Other characters in <i>s</i> shall be unchanged in the returned string.</dd> +<dt><b>toupper</b>(<i>s</i>)</dt> +<dd>Return a string based on the string <i>s</i>. Each character in <i>s</i> that is a lowercase letter specified to have a +<b>toupper</b> mapping by the <i>LC_CTYPE</i> category of the current locale is replaced in the returned string by the uppercase +letter specified by the mapping. Other characters in <i>s</i> are unchanged in the returned string.</dd> +</dl> +<p class="tent">All of the preceding functions that take <i>ERE</i> as a parameter expect a pattern or a string valued expression +that is a regular expression as defined in <a href="#tag_20_06_13_04">Regular Expressions</a> .</p> +<h5><a name="tag_20_06_13_14" id="tag_20_06_13_14"></a>Input/Output and General Functions</h5> +<p class="tent">The input/output and general functions are:</p> +<dl compact> +<dd></dd> +<dt><b>close</b>(<i>expression</i>)</dt> +<dd> +Close the file or pipe opened by a <b>print</b> or <b>printf</b> statement or a call to <b>getline</b> with the same string-valued +<i>expression</i>. The limit on the number of open <i>expression</i> arguments is implementation-defined. If the close was +successful, the function shall return zero; otherwise, it shall return non-zero.</dd> +<dt><b>fflush</b>(<b>[</b><i>expression</i><b>]</b>)</dt> +<dd> +Write any unwritten data to the file or piped stream opened by a <b>print</b> or <b>printf</b> statement with the same +string-valued <i>expression</i>. If no argument, or if <i>expression</i> evaluates to the null string, then write all such data for +all such open files and piped streams, and standard output. +<p class="tent">If <b>fflush</b> is successful, it shall return 0; otherwise, it shall return non-zero.</p> +</dd> +<dt><i>expression | </i><b>getline [</b><i>var</i><b>]</b></dt> +<dd> +Read a record of input from a stream piped from the output of a command. The stream shall be created if no stream is currently open +with the value of <i>expression</i> as its command name. The stream created shall be equivalent to one created by a call to the +<a href="../functions/popen.html"><i>popen</i>()</a> function with the value of <i>expression</i> as the <i>command</i> argument +and a value of <i>r</i> as the <i>mode</i> argument. As long as the stream remains open, subsequent calls in which +<i>expression</i> evaluates to the same string value shall read subsequent records from the stream. The stream shall remain open +until the <b>close</b> function is called with an expression that evaluates to the same string value. At that time, the stream +shall be closed as if by a call to the <a href="../functions/pclose.html"><i>pclose</i>()</a> function. If <i>var</i> is omitted, +$0 and <b>NF</b> shall be set; otherwise, <i>var</i> shall be set and, if appropriate, it shall be considered a numeric string (see +<a href="#tag_20_06_13_02">Expressions in awk</a> ). +<p class="tent">The <b>getline</b> operator can form ambiguous constructs when there are unparenthesized operators (including +concatenate) to the left of the <tt>'|'</tt> (to the beginning of the expression containing <b>getline</b>). In the context of the +<tt>'$'</tt> operator, <tt>'|'</tt> shall behave as if it had a lower precedence than <tt>'$'</tt>. The result of evaluating other +operators is unspecified, and conforming applications shall parenthesize properly all such usages.</p> +</dd> +<dt><b>getline</b></dt> +<dd>Set $0 to the next input record from the current input file. This form of <b>getline</b> shall set the <b>NF</b>, <b>NR</b>, +and <b>FNR</b> variables.</dd> +<dt><b>getline </b><i>var</i></dt> +<dd>Set variable <i>var</i> to the next input record from the current input file and, if appropriate, <i>var</i> shall be +considered a numeric string (see <a href="#tag_20_06_13_02">Expressions in awk</a> ). This form of <b>getline</b> shall set the +<b>FNR</b> and <b>NR</b> variables.</dd> +<dt><b>getline [</b><i>var</i><b>] </b>< <i>expression</i></dt> +<dd> +Read the next record of input from a named file. The <i>expression</i> shall be evaluated to produce a string that is used as a +pathname. If the file of that name is not currently open, it shall be opened. As long as the stream remains open, subsequent calls +in which <i>expression</i> evaluates to the same string value shall read subsequent records from the file. The file shall remain +open until the <b>close</b> function is called with an expression that evaluates to the same string value. If <i>var</i> is +omitted, $0 and <b>NF</b> shall be set; otherwise, <i>var</i> shall be set and, if appropriate, it shall be considered a numeric +string (see <a href="#tag_20_06_13_02">Expressions in awk</a> ). +<p class="tent">The <b>getline</b> operator can form ambiguous constructs when there are unparenthesized binary operators +(including concatenate) to the right of the <tt>'<'</tt> (up to the end of the expression containing the <b>getline</b>). The +result of evaluating such a construct is unspecified, and conforming applications shall parenthesize properly all such usages.</p> +</dd> +<dt><b>system</b>(<i>expression</i>)</dt> +<dd> +Execute the command given by <i>expression</i> in a manner equivalent to the <a href="../functions/system.html"><i>system</i>()</a> +function defined in the System Interfaces volume of POSIX.1-2024 and return the exit status of the command.</dd> +</dl> +<p class="tent">All forms of <b>getline</b> shall return 1 for successful input, zero for end-of-file, and -1 for an error.</p> +<p class="tent">Where strings are used as the name of a file or pipeline, the application shall ensure that the strings are +textually identical. The terminology "same string value" implies that "equivalent strings", even those that differ only by +<space> characters, represent different files.</p> +<h5><a name="tag_20_06_13_15" id="tag_20_06_13_15"></a>User-Defined Functions</h5> +<p class="tent">The <i>awk</i> language also provides user-defined functions. Such functions can be defined as:</p> +<pre> +<tt>function </tt><i>name</i><tt>(</tt><b>[</b><i>parameter</i><tt>, ...</tt><b>]</b><tt>) { </tt><i>statements</i><tt> } +</tt></pre> +<p class="tent">A function can be referred to anywhere in an <i>awk</i> program; in particular, its use can precede its definition. +The scope of a function is global.</p> +<p class="tent">The number of parameters in the function definition need not match the number of parameters in the function call. +Excess formal parameters can be used as local variables. If fewer arguments are supplied in a function call than are in the +function definition, the extra parameters that are used in the function body as scalars shall evaluate to the uninitialized value +until they are otherwise initialized, and the extra parameters that are used in the function body as arrays shall be treated as +uninitialized arrays where each element evaluates to the uninitialized value until otherwise initialized.</p> +<p class="tent">When invoking a function, no white space can be placed between the function name and the opening parenthesis. +Function calls can be nested and recursive calls can be made upon functions. Upon return from any nested or recursive function +call, the values of all of the calling function's parameters shall be unchanged, except for array parameters passed by reference. +The <b>return</b> statement can be used to return a value. If a <b>return</b> statement appears outside of a function definition, +the behavior is undefined.</p> +<p class="tent">In the function definition, <newline> characters shall be optional before the opening brace and after the +closing brace. Function definitions can appear anywhere in the program where a <i>pattern-action</i> pair is allowed.</p> +<h5><a name="tag_20_06_13_16" id="tag_20_06_13_16"></a>Grammar</h5> +<p class="tent">The grammar in this section and the lexical conventions in the following section shall together describe the syntax +for <i>awk</i> programs. The general conventions for this style of grammar are described in <a href= +"../utilities/V3_chap01.html#tag_18_03"><i>1.3 Grammar Conventions</i></a> . A valid program can be represented as the non-terminal +symbol <i>program</i> in the grammar. This formal syntax shall take precedence over the preceding text syntax description.</p> +<pre> +<tt>%token NAME NUMBER STRING ERE +%token FUNC_NAME /* Name followed by '(' without white space. */ +<br class="tent"> +/* Keywords */ +%token Begin End +/* 'BEGIN' 'END' */ +<br class="tent"> +%token Break Continue Delete Do Else +/* 'break' 'continue' 'delete' 'do' 'else' */ +<br class="tent"> +%token Exit For Function If In Next +/* 'exit' 'for' 'function' 'if' 'in' 'next' */ +<br class="tent"> +%token Nextfile Print Printf Return While +/* 'nextfile' 'print' 'printf' 'return' 'while' */ +<br class="tent"> +/* Reserved function names */ +%token BUILTIN_FUNC_NAME + /* One token for the following: + * atan2 cos sin exp log sqrt int rand srand + * gsub index length match split sprintf sub + * substr tolower toupper close fflush system + */ +%token GETLINE + /* Syntactically different from other built-ins. */ +<br class="tent"> +/* Two-character tokens. */ +%token ADD_ASSIGN SUB_ASSIGN MUL_ASSIGN DIV_ASSIGN MOD_ASSIGN POW_ASSIGN +/* '+=' '-=' '*=' '/=' '%=' '^=' */ +<br class="tent"> +%token OR AND NO_MATCH EQ LE GE NE INCR DECR APPEND +/* '||' '&&' '!~' '==' '<=' '>=' '!=' '++' '--' '>>' */ +<br class="tent"> +/* One-character tokens. */ +%token '{' '}' '(' ')' '[' ']' ',' ';' NEWLINE +%token '+' '-' '*' '%' '^' '!' '>' '<' '|' '?' ':' '~' '$' '=' +<br class="tent"> +%start program +%% +<br class="tent"> +program : item_list + | item_list item + ; +<br class="tent"> +item_list : /* empty */ + | item_list item terminator + ; +<br class="tent"> +item : action + | pattern action + | normal_pattern + | Function NAME '(' param_list_opt ')' + newline_opt action + | Function FUNC_NAME '(' param_list_opt ')' + newline_opt action + ; +<br class="tent"> +param_list_opt : /* empty */ + | param_list + ; +<br class="tent"> +param_list : NAME + | param_list ',' NAME + ; +<br class="tent"> +pattern : normal_pattern + | special_pattern + ; +<br class="tent"> +normal_pattern : expr + | expr ',' newline_opt expr + ; +<br class="tent"> +special_pattern : Begin + | End + ; +<br class="tent"> +action : '{' newline_opt '}' + | '{' newline_opt terminated_statement_list '}' + | '{' newline_opt unterminated_statement_list '}' + ; +<br class="tent"> +terminator : terminator NEWLINE + | ';' + | NEWLINE + ; +<br class="tent"> +terminated_statement_list : terminated_statement + | terminated_statement_list terminated_statement + ; +<br class="tent"> +unterminated_statement_list : unterminated_statement + | terminated_statement_list unterminated_statement + ; +<br class="tent"> +terminated_statement : action newline_opt + | If '(' expr ')' newline_opt terminated_statement + | If '(' expr ')' newline_opt terminated_statement + Else newline_opt terminated_statement + | While '(' expr ')' newline_opt terminated_statement + | For '(' simple_statement_opt ';' + expr_opt ';' simple_statement_opt ')' newline_opt + terminated_statement + | For '(' NAME In NAME ')' newline_opt + terminated_statement + | ';' newline_opt + | terminatable_statement NEWLINE newline_opt + | terminatable_statement ';' newline_opt + ; +<br class="tent"> +unterminated_statement : terminatable_statement + | If '(' expr ')' newline_opt unterminated_statement + | If '(' expr ')' newline_opt terminated_statement + Else newline_opt unterminated_statement + | While '(' expr ')' newline_opt unterminated_statement + | For '(' simple_statement_opt ';' + expr_opt ';' simple_statement_opt ')' newline_opt + unterminated_statement + | For '(' NAME In NAME ')' newline_opt + unterminated_statement + ; +<br class="tent"> +terminatable_statement : simple_statement + | Break + | Continue + | Next + | Nextfile + | Exit expr_opt + | Return expr_opt + | Do newline_opt terminated_statement While '(' expr ')' + ; +<br class="tent"> +simple_statement_opt : /* empty */ + | simple_statement + ; +<br class="tent"> +simple_statement : Delete NAME '[' expr_list ']' + | Delete NAME + | expr + | print_statement + ; +<br class="tent"> +print_statement : simple_print_statement + | simple_print_statement output_redirection + ; +<br class="tent"> +simple_print_statement : Print print_expr_list_opt + | Print '(' multiple_expr_list ')' + | Printf print_expr_list + | Printf '(' multiple_expr_list ')' + ; +<br class="tent"> +output_redirection : '>' expr + | APPEND expr + | '|' expr + ; +<br class="tent"> +expr_list_opt : /* empty */ + | expr_list + ; +<br class="tent"> +expr_list : expr + | multiple_expr_list + ; +<br class="tent"> +multiple_expr_list : expr ',' newline_opt expr + | multiple_expr_list ',' newline_opt expr + ; +<br class="tent"> +expr_opt : /* empty */ + | expr + ; +<br class="tent"> +expr : unary_expr + | non_unary_expr + ; +<br class="tent"> +unary_expr : '+' expr + | '-' expr + | unary_expr '^' expr + | unary_expr '*' expr + | unary_expr '/' expr + | unary_expr '%' expr + | unary_expr '+' expr + | unary_expr '-' expr + | unary_expr non_unary_expr + | unary_expr '<' expr + | unary_expr LE expr + | unary_expr NE expr + | unary_expr EQ expr + | unary_expr '>' expr + | unary_expr GE expr + | unary_expr '~' expr + | unary_expr NO_MATCH expr + | unary_expr In NAME + | unary_expr AND newline_opt expr + | unary_expr OR newline_opt expr + | unary_expr '?' expr ':' expr + | unary_input_function + ; +<br class="tent"> +non_unary_expr : '(' expr ')' + | '!' expr + | non_unary_expr '^' expr + | non_unary_expr '*' expr + | non_unary_expr '/' expr + | non_unary_expr '%' expr + | non_unary_expr '+' expr + | non_unary_expr '-' expr + | non_unary_expr non_unary_expr + | non_unary_expr '<' expr + | non_unary_expr LE expr + | non_unary_expr NE expr + | non_unary_expr EQ expr + | non_unary_expr '>' expr + | non_unary_expr GE expr + | non_unary_expr '~' expr + | non_unary_expr NO_MATCH expr + | non_unary_expr In NAME + | '(' multiple_expr_list ')' In NAME + | non_unary_expr AND newline_opt expr + | non_unary_expr OR newline_opt expr + | non_unary_expr '?' expr ':' expr + | NUMBER + | STRING + | lvalue + | ERE + | lvalue INCR + | lvalue DECR + | INCR lvalue + | DECR lvalue + | lvalue POW_ASSIGN expr + | lvalue MOD_ASSIGN expr + | lvalue MUL_ASSIGN expr + | lvalue DIV_ASSIGN expr + | lvalue ADD_ASSIGN expr + | lvalue SUB_ASSIGN expr + | lvalue '=' expr + | FUNC_NAME '(' expr_list_opt ')' + /* no white space allowed before '(' */ + | BUILTIN_FUNC_NAME '(' expr_list_opt ')' + | BUILTIN_FUNC_NAME + | non_unary_input_function + ; +<br class="tent"> +print_expr_list_opt : /* empty */ + | print_expr_list + ; +<br class="tent"> +print_expr_list : print_expr + | print_expr_list ',' newline_opt print_expr + ; +<br class="tent"> +print_expr : unary_print_expr + | non_unary_print_expr + ; +<br class="tent"> +unary_print_expr : '+' print_expr + | '-' print_expr + | unary_print_expr '^' print_expr + | unary_print_expr '*' print_expr + | unary_print_expr '/' print_expr + | unary_print_expr '%' print_expr + | unary_print_expr '+' print_expr + | unary_print_expr '-' print_expr + | unary_print_expr non_unary_print_expr + | unary_print_expr '~' print_expr + | unary_print_expr NO_MATCH print_expr + | unary_print_expr In NAME + | unary_print_expr AND newline_opt print_expr + | unary_print_expr OR newline_opt print_expr + | unary_print_expr '?' print_expr ':' print_expr + ; +<br class="tent"> +non_unary_print_expr : '(' expr ')' + | '!' print_expr + | non_unary_print_expr '^' print_expr + | non_unary_print_expr '*' print_expr + | non_unary_print_expr '/' print_expr + | non_unary_print_expr '%' print_expr + | non_unary_print_expr '+' print_expr + | non_unary_print_expr '-' print_expr + | non_unary_print_expr non_unary_print_expr + | non_unary_print_expr '~' print_expr + | non_unary_print_expr NO_MATCH print_expr + | non_unary_print_expr In NAME + | '(' multiple_expr_list ')' In NAME + | non_unary_print_expr AND newline_opt print_expr + | non_unary_print_expr OR newline_opt print_expr + | non_unary_print_expr '?' print_expr ':' print_expr + | NUMBER + | STRING + | lvalue + | ERE + | lvalue INCR + | lvalue DECR + | INCR lvalue + | DECR lvalue + | lvalue POW_ASSIGN print_expr + | lvalue MOD_ASSIGN print_expr + | lvalue MUL_ASSIGN print_expr + | lvalue DIV_ASSIGN print_expr + | lvalue ADD_ASSIGN print_expr + | lvalue SUB_ASSIGN print_expr + | lvalue '=' print_expr + | FUNC_NAME '(' expr_list_opt ')' + /* no white space allowed before '(' */ + | BUILTIN_FUNC_NAME '(' expr_list_opt ')' + | BUILTIN_FUNC_NAME + ; +<br class="tent"> +lvalue : NAME + | NAME '[' expr_list ']' + | '$' expr + ; +<br class="tent"> +non_unary_input_function : simple_get + | simple_get '<' expr + | non_unary_expr '|' simple_get + ; +<br class="tent"> +unary_input_function : unary_expr '|' simple_get + ; +<br class="tent"> +simple_get : GETLINE + | GETLINE lvalue + ; +<br class="tent"> +newline_opt : /* empty */ + | newline_opt NEWLINE + ; +</tt></pre> +<p class="tent">This grammar has several ambiguities that shall be resolved as follows:</p> +<ul> +<li class="tent">Operator precedence and associativity shall be as described in <a href="#tagtcjh_14">Expressions in Decreasing +Precedence in awk</a> .</li> +<li class="tent">In case of ambiguity, an <b>else</b> shall be associated with the most immediately preceding <b>if</b> that would +satisfy the grammar.</li> +<li class="tent">In some contexts, a <slash> (<tt>'/'</tt>) that is used to surround an ERE could also be the division +operator. This shall be resolved in such a way that wherever the division operator could appear, a <slash> is assumed to be +the division operator. (There is no unary division operator.)</li> +</ul> +<p class="tent">Each expression in an <i>awk</i> program shall conform to the precedence and associativity rules, even when this is +not needed to resolve an ambiguity. For example, because <tt>'$'</tt> has higher precedence than <tt>'++'</tt>, the string +<tt>"$x++--"</tt> is not a valid <i>awk</i> expression, even though it is unambiguously parsed by the grammar as +<tt>"$(x++)--"</tt>.</p> +<p class="tent">One convention that might not be obvious from the formal grammar is where <newline> characters are +acceptable. There are several obvious placements such as terminating a statement, and a <backslash> can be used to escape +<newline> characters between any lexical tokens. In addition, <newline> characters without <backslash> characters +can follow a comma, an open brace, logical AND operator (<tt>"&&"</tt>), logical OR operator (<tt>"||"</tt>), the <b>do</b> +keyword, the <b>else</b> keyword, and the closing parenthesis of an <b>if</b>, <b>for</b>, or <b>while</b> statement. For +example:</p> +<pre> +<tt>{ print $1, + $2 } +</tt></pre> +<h5><a name="tag_20_06_13_17" id="tag_20_06_13_17"></a>Lexical Conventions</h5> +<p class="tent">The lexical conventions for <i>awk</i> programs, with respect to the preceding grammar, shall be as follows:</p> +<ol> +<li class="tent">Except as noted, <i>awk</i> shall recognize the longest possible token or delimiter beginning at a given +point.</li> +<li class="tent">A comment shall consist of any characters beginning with the <number-sign> character and terminated by, but +excluding the next occurrence of, a <newline>. Comments shall have no effect, except to delimit lexical tokens.</li> +<li class="tent">The <newline> shall be recognized as the token <b>NEWLINE</b>.</li> +<li class="tent">A <backslash> character immediately followed by a <newline> shall have no effect.</li> +<li class="tent">The token <b>STRING</b> shall represent a string constant. A string constant shall begin with the character +<tt>'"'</tt>. Within a string constant, a <backslash> character shall be considered to begin an escape sequence as specified +in the table in XBD <a href="../basedefs/V1_chap05.html#tag_05"><i>5. File Format Notation</i></a> (<tt>'\\'</tt>, <tt>'\a'</tt>, +<tt>'\b'</tt>, <tt>'\f'</tt>, <tt>'\n'</tt>, <tt>'\r'</tt>, <tt>'\t'</tt>, <tt>'\v'</tt>). In addition, the escape sequences in +<a href="#tagtcjh_15">Escape Sequences in awk</a> shall be recognized. A <newline> shall not occur within a string constant. +A string constant shall be terminated by the first unescaped occurrence of the character <tt>'"'</tt> after the one that begins the +string constant. The value of the string shall be the sequence of all unescaped characters and values of escape sequences between, +but not including, the two delimiting <tt>'"'</tt> characters.</li> +<li class="tent">The token <b>ERE</b> represents an extended regular expression constant. An ERE constant shall begin with the +<slash> character. Within an ERE constant, a <backslash> character shall be considered to begin an escape sequence as +specified in the table in XBD <a href="../basedefs/V1_chap05.html#tag_05"><i>5. File Format Notation</i></a> . In addition, the +escape sequences in <a href="#tagtcjh_15">Escape Sequences in awk</a> shall be recognized. The application shall ensure that a +<newline> does not occur within an ERE constant. An ERE constant shall be terminated by the first unescaped occurrence of the +<slash> character after the one that begins the ERE constant. The extended regular expression represented by the ERE constant +shall be the sequence of all unescaped characters and values of escape sequences between, but not including, the two delimiting +<slash> characters.</li> +<li class="tent">A <blank> shall have no effect, except to delimit lexical tokens or within <b>STRING</b> or <b>ERE</b> +tokens.</li> +<li class="tent">The token <b>NUMBER</b> shall represent a numeric constant. Its form and numeric value shall either be equivalent +to the <b>decimal-floating-constant</b> token as specified by the ISO C standard, or it shall be a sequence of decimal digits +and shall be evaluated as an integer constant in decimal. In addition, implementations may accept numeric constants with the form +and numeric value equivalent to the <b>hexadecimal-constant</b> and <b>hexadecimal-floating-constant</b> tokens as specified by the +ISO C standard. Note that these forms do not use the radix character from the current locale; they always use a +<period>. +<p class="tent">If the value is too large or too small to be representable (see <a href= +"../utilities/V3_chap01.html#tag_18_01_02"><i>1.1.2 Concepts Derived from the ISO C Standard</i></a> ), the behavior is +undefined.</p> +</li> +<li class="tent">A sequence of underscores, digits, and alphabetics from the portable character set (see XBD <a href= +"../basedefs/V1_chap06.html#tag_06_01"><i>6.1 Portable Character Set</i></a> ), beginning with an <underscore> or alphabetic +character, shall be considered a word.</li> +<li class="tent">The following words are keywords that shall be recognized as individual tokens; the name of the token is the same +as the keyword: +<table cellpadding="3"> +<tr valign="top"> +<td align="left"> +<p class="tent"><b><br> +BEGIN<br> +break<br> +continue<br></b></p> +</td> +<td align="left"> +<p class="tent"><b><br> +delete<br> +do<br> +else<br></b></p> +</td> +<td align="left"> +<p class="tent"><b><br> +END<br> +exit<br> +for<br></b></p> +</td> +<td align="left"> +<p class="tent"><b><br> +function<br> +getline<br> +if<br></b></p> +</td> +<td align="left"> +<p class="tent"><b><br> +in<br> +next<br> +nextfile<br></b></p> +</td> +<td align="left"> +<p class="tent"><b><br> +print<br> +printf<br> +return<br></b></p> +</td> +<td align="left"> +<p class="tent"><b><br> +while<br></b></p> +</td> +</tr> +</table> +</li> +<li class="tent">The following words are names of built-in functions and shall be recognized as the token <b>BUILTIN_FUNC_NAME</b>: +<table cellpadding="3"> +<tr valign="top"> +<td align="left"> +<p class="tent"><b><br> +atan2<br> +close<br> +cos<br> +exp<br></b></p> +</td> +<td align="left"> +<p class="tent"><b><br> +fflush<br> +gsub<br> +index<br></b></p> +</td> +<td align="left"> +<p class="tent"><b><br> +int<br> +length<br> +log<br></b></p> +</td> +<td align="left"> +<p class="tent"><b><br> +match<br> +rand<br> +sin<br></b></p> +</td> +<td align="left"> +<p class="tent"><b><br> +split<br> +sprintf<br> +sqrt<br></b></p> +</td> +<td align="left"> +<p class="tent"><b><br> +srand<br> +sub<br> +substr<br></b></p> +</td> +<td align="left"> +<p class="tent"><b><br> +system<br> +tolower<br> +toupper<br></b></p> +</td> +</tr> +</table> +<p class="tent">The above-listed keywords and names of built-in functions are considered reserved words.</p> +</li> +<li class="tent">The token <b>NAME</b> shall consist of a word that is not a keyword or a name of a built-in function and is not +followed immediately (without any delimiters) by the <tt>'('</tt> character.</li> +<li class="tent">The token <b>FUNC_NAME</b> shall consist of a word that is not a keyword or a name of a built-in function, +followed immediately (without any delimiters) by the <tt>'('</tt> character. The <tt>'('</tt> character shall not be included as +part of the token.</li> +<li class="tent">The following two-character sequences shall be recognized as the named tokens: +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Token Name</b></p> +</th> +<th align="center"> +<p class="tent"><b>Sequence</b></p> +</th> +<th align="center"> +<p class="tent"><b>Token Name</b></p> +</th> +<th align="center"> +<p class="tent"><b>Sequence</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>ADD_ASSIGN</b></p> +</td> +<td align="center"> +<p class="tent">+=</p> +</td> +<td align="left"> +<p class="tent"><b>NO_MATCH</b></p> +</td> +<td align="center"> +<p class="tent">!~</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>SUB_ASSIGN</b></p> +</td> +<td align="center"> +<p class="tent">-=</p> +</td> +<td align="left"> +<p class="tent"><b>EQ</b></p> +</td> +<td align="center"> +<p class="tent">==</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>MUL_ASSIGN</b></p> +</td> +<td align="center"> +<p class="tent">*=</p> +</td> +<td align="left"> +<p class="tent"><b>LE</b></p> +</td> +<td align="center"> +<p class="tent"><=</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>DIV_ASSIGN</b></p> +</td> +<td align="center"> +<p class="tent">/=</p> +</td> +<td align="left"> +<p class="tent"><b>GE</b></p> +</td> +<td align="center"> +<p class="tent">>=</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>MOD_ASSIGN</b></p> +</td> +<td align="center"> +<p class="tent">%=</p> +</td> +<td align="left"> +<p class="tent"><b>NE</b></p> +</td> +<td align="center"> +<p class="tent">!=</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>POW_ASSIGN</b></p> +</td> +<td align="center"> +<p class="tent">^=</p> +</td> +<td align="left"> +<p class="tent"><b>INCR</b></p> +</td> +<td align="center"> +<p class="tent">++</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>OR</b></p> +</td> +<td align="center"> +<p class="tent">||</p> +</td> +<td align="left"> +<p class="tent"><b>DECR</b></p> +</td> +<td align="center"> +<p class="tent">--</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>AND</b></p> +</td> +<td align="center"> +<p class="tent">&&</p> +</td> +<td align="left"> +<p class="tent"><b>APPEND</b></p> +</td> +<td align="center"> +<p class="tent">>></p> +</td> +</tr> +</table> +</center> +</li> +<li class="tent">The following single characters shall be recognized as tokens whose names are the character: +<pre> +<tt><newline> { } ( ) [ ] , ; + - * % ^ ! > < | ? : ~ $ = +</tt></pre></li> +</ol> +<p class="tent">There is a lexical ambiguity between the token <b>ERE</b> and the tokens <tt>'/'</tt> and <b>DIV_ASSIGN</b>. When +an input sequence begins with a <slash> character in any syntactic context where the token <tt>'/'</tt> or <b>DIV_ASSIGN</b> +could appear as the next token in a valid program, the longer of those two tokens that can be recognized shall be recognized. In +any other syntactic context where the token <b>ERE</b> could appear as the next token in a valid program, the token <b>ERE</b> +shall be recognized.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_06_14" id="tag_20_06_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>All input files were processed successfully.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +<p class="tent">The exit status can be altered within the program by using an <b>exit</b> expression.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_06_15" id="tag_20_06_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>If any <i>file</i> operand is specified and the named file cannot be accessed, <i>awk</i> shall write a diagnostic message to +standard error and terminate without any further action.</p> +<p class="tent">If the program specified by either the <i>program</i> operand or a <i>progfile</i> operand is not a valid +<i>awk</i> program (as specified in the EXTENDED DESCRIPTION section), the behavior is undefined.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_06_16" id="tag_20_06_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Since <backslash> has a special meaning both in the <i>assignment</i> option-argument to the <b>-v</b> option and in the +<i>assignment</i> operand, applications that need to pass strings to <i>awk</i> without special interpretation of <backslash> +should not use these methods but should instead make use of the <b>ARGV</b> or <b>ENVIRON</b> array.</p> +<p class="tent">The <b>index</b>, <b>length</b>, <b>match</b>, and <b>substr</b> functions should not be confused with similar +functions in the ISO C standard; the <i>awk</i> versions deal with characters, while the ISO C standard deals with +bytes.</p> +<p class="tent">Because the concatenation operation is represented by adjacent expressions rather than an explicit operator, it is +often necessary to use parentheses to enforce the proper evaluation precedence.</p> +<p class="tent">When using <i>awk</i> to process pathnames, it is recommended that LC_ALL, or at least LC_CTYPE and LC_COLLATE, are +set to POSIX or C in the environment, since pathnames can contain byte sequences that do not form valid characters in some locales, +in which case the utility's behavior would be undefined. In the POSIX locale each byte is a valid single-byte character, and +therefore this problem is avoided.</p> +<p class="tent">Since the <tt>"=="</tt> operator checks if strings are identical, not whether they collate equally, applications +needing to check whether strings collate equally can use:</p> +<pre> +<tt>a <= b && a >= b +</tt></pre> +<p class="tent">To specify a <i>file</i> operand naming a file with a name containing an <equals-sign>, users can use +<tt>"./"</tt> as the first two characters of a relative file pathname that starts with an <underscore> or an alphabetic +character to keep the <i>file</i> operand from being interpreted as an <i>assignment</i> operand. Similarly, <tt>"./-"</tt> can be +used to access a file named <tt>'-'</tt> in the current directory rather than use standard input.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_06_17" id="tag_20_06_17"></a>EXAMPLES</h4> +<blockquote> +<p>The <i>awk</i> program specified in the command line is most easily specified within single-quotes (for example, +'<i>program</i>') for applications using <a href="../utilities/sh.html"><i>sh</i></a>, because <i>awk</i> programs commonly contain +characters that are special to the shell, including double-quotes. In the cases where an <i>awk</i> program contains single-quote +characters, it is usually easiest to specify most of the program as strings within single-quotes concatenated by the shell with +quoted single-quote characters. For example:</p> +<pre> +<tt>awk '/'\''/ { print "quote:", $0 }' +</tt></pre> +<p class="tent">prints all lines from the standard input containing a single-quote character, prefixed with <i>quote</i>:.</p> +<p class="tent">The following are examples of simple <i>awk</i> programs:</p> +<ol> +<li class="tent">Write to the standard output all input lines for which field 3 is greater than 5: +<pre> +<tt>$3 > 5 +</tt></pre></li> +<li class="tent">Write every tenth line: +<pre> +<tt>(NR % 10) == 0 +</tt></pre></li> +<li class="tent">Write any line with a substring matching the regular expression: +<pre> +<tt>/(G|D)(2[0-9][[:alpha:]]*)/ +</tt></pre></li> +<li class="tent">Print any line with a substring containing a <tt>'G'</tt> or <tt>'D'</tt>, followed by a sequence of digits and +characters. This example uses character classes <b>digit</b> and <b>alpha</b> to match language-independent digit and alphabetic +characters respectively: +<pre> +<tt>/(G|D)([[:digit:][:alpha:]]*)/ +</tt></pre></li> +<li class="tent">Write any line in which the second field matches the regular expression and the fourth field does not: +<pre> +<tt>$2 ~ /xyz/ && $4 !~ /xyz/ +</tt></pre></li> +<li class="tent">Write any line in which the second field contains a <backslash>: +<pre> +<tt>$2 ~ /\\/ +</tt></pre></li> +<li class="tent">Write any line in which the second field contains a <backslash>. Note that <backslash>-escapes are +interpreted twice; once in lexical processing of the string and once in processing the regular expression: +<pre> +<tt>$2 ~ "\\\\" +</tt></pre></li> +<li class="tent">Write the second to the last and the last field in each line. Separate the fields by a <colon>: +<pre> +<tt>{OFS=":";print $(NF-1), $NF} +</tt></pre></li> +<li class="tent">Write the line number and number of fields in each line. The three strings representing the line number, the +<colon>, and the number of fields are concatenated and that string is written to standard output: +<pre> +<tt>{print NR ":" NF} +</tt></pre></li> +<li class="tent">Write lines longer than 72 characters: +<pre> +<tt>length($0) > 72 +</tt></pre></li> +<li class="tent">Write the first two fields in opposite order separated by <b>OFS</b>: +<pre> +<tt>{ print $2, $1 } +</tt></pre></li> +<li class="tent">Same, with input fields separated by a <comma> or <space> and <tab> characters, or both: +<pre> +<tt>BEGIN { FS = ",[ \t]*|[ \t]+" } + { print $2, $1 } +</tt></pre></li> +<li class="tent">Add up the first column, print sum, and average: +<pre> +<tt> {s += $1 } +END {print "sum is ", s, " average is", s/NR} +</tt></pre></li> +<li class="tent">Write fields in reverse order, one per line (many lines out for each line in): +<pre> +<tt>{ for (i = NF; i > 0; --i) print $i } +</tt></pre></li> +<li class="tent">Write all lines between occurrences of the strings <b>start</b> and <b>stop</b>: +<pre> +<tt>/start/, /stop/ +</tt></pre></li> +<li class="tent">Write all lines whose first field is different from the previous one: +<pre> +<tt>$1 != prev { print; prev = $1 } +</tt></pre></li> +<li class="tent">Simulate <a href="../utilities/echo.html"><i>echo</i></a>: +<pre> +<tt>BEGIN { + for (i = 1; i < ARGC; ++i) + printf("%s%s", ARGV[i], i==ARGC-1?"\n":" ") +} +</tt></pre></li> +<li class="tent">Write the path prefixes contained in the <i>PATH</i> environment variable, one per line: +<pre> +<tt>BEGIN { + n = split (ENVIRON["PATH"], path, ":") + for (i = 1; i <= n; ++i) + print path[i] +} +</tt></pre></li> +<li class="tent">If there is a file named <b>input</b> containing page headers of the form: Page # +<p class="tent">and a file named <b>program</b> that contains:</p> +<pre> +<tt>/Page/ { $2 = n++; } + { print } +</tt></pre> +then the command line: +<pre> +<tt>awk -f program n=5 input +</tt></pre> +<p class="tent">prints the file <b>input</b>, filling in page numbers starting at 5.</p> +</li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_06_18" id="tag_20_06_18"></a>RATIONALE</h4> +<blockquote> +<p>This description is based on the new <i>awk</i>, "nawk", (see the referenced <i>The AWK Programming Language</i>), which +introduced a number of new features to the historical <i>awk</i>:</p> +<ol> +<li class="tent">New keywords: <b>delete</b>, <b>do</b>, <b>function</b>, <b>return</b></li> +<li class="tent">New built-in functions: <b>atan2</b>, <b>close</b>, <b>cos</b>, <b>gsub</b>, <b>match</b>, <b>rand</b>, +<b>sin</b>, <b>srand</b>, <b>sub</b>, <b>system</b></li> +<li class="tent">New predefined variables: <b>FNR</b>, <b>ARGC</b>, <b>ARGV</b>, <b>RSTART</b>, <b>RLENGTH</b>, <b>SUBSEP</b></li> +<li class="tent">New expression operators: <b>?</b>, <b>:</b>, <b>,</b>, <b>^</b></li> +<li class="tent">The <b>FS</b> variable and the third argument to <b>split</b>, now treated as extended regular expressions.</li> +<li class="tent">The operator precedence, changed to more closely match the C language. Two examples of code that operate +differently are: +<pre> +<tt>while ( n /= 10 > 1) ... +if (!"wk" ~ /bwk/) ... +</tt></pre></li> +</ol> +<p class="tent">Several features have been added based on newer implementations of <i>awk</i>:</p> +<ul> +<li class="tent">Multiple instances of <b>-f</b> <i>progfile</i> are permitted.</li> +<li class="tent">The new option <b>-v</b> <i>assignment.</i></li> +<li class="tent">The new predefined variable <b>ENVIRON</b>.</li> +<li class="tent">New built-in functions <b>toupper</b> and <b>tolower</b>.</li> +<li class="tent">More formatting capabilities are added to <b>printf</b> to match the ISO C standard.</li> +</ul> +<p class="tent">Earlier versions of this standard required implementations to support multiple adjacent <semicolon>s, lines +with one or more <semicolon> before a rule (<i>pattern-action</i> pairs), and lines with only <semicolon>(s). These are +not required by this standard and are considered poor programming practice, but can be accepted by an implementation of <i>awk</i> +as an extension.</p> +<p class="tent">The overall <i>awk</i> syntax has always been based on the C language, with a few features from the shell command +language and other sources. Because of this, it is not completely compatible with any other language, which has caused confusion +for some users. It is not the intent of the standard developers to address such issues. A few relatively minor changes toward +making the language more compatible with the ISO C standard were made; most of these changes are based on similar changes in +recent implementations, as described above. There remain several C-language conventions that are not in <i>awk</i>. One of the +notable ones is the <comma> operator, which is commonly used to specify multiple expressions in the C language <b>for</b> +statement. Also, there are various places where <i>awk</i> is more restrictive than the C language regarding the type of expression +that can be used in a given context. These limitations are due to the different features that the <i>awk</i> language does +provide.</p> +<p class="tent">Regular expressions in <i>awk</i> have been extended somewhat from historical implementations to make them a pure +superset of extended regular expressions, as defined by POSIX.1-2024 (see XBD <a href="../basedefs/V1_chap09.html#tag_09_04"><i>9.4 +Extended Regular Expressions</i></a> ). The main extensions are internationalization features and interval expressions. Historical +implementations of <i>awk</i> have long supported <backslash>-escape sequences as an extension to extended regular +expressions, and this extension has been retained despite inconsistency with other utilities. The number of escape sequences +recognized in both extended regular expressions and strings has varied (generally increasing with time) among implementations. The +set specified by POSIX.1-2024 includes most sequences known to be supported by popular implementations and by the ISO C +standard. One sequence that is not supported is hexadecimal value escapes beginning with <tt>'\x'</tt>. This would allow values +expressed in more than 9 bits to be used within <i>awk</i> as in the ISO C standard. However, because this syntax has a +non-deterministic length, it does not permit the subsequent character to be a hexadecimal digit. This limitation can be dealt with +in the C language by the use of lexical string concatenation. In the <i>awk</i> language, concatenation could also be a solution +for strings, but not for extended regular expressions (either lexical ERE tokens or strings used dynamically as regular +expressions). Because of this limitation, the feature has not been added to POSIX.1-2024.</p> +<p class="tent">When a string variable is used in a context where an extended regular expression normally appears (where the +lexical token ERE is used in the grammar) the string does not contain the literal <slash> characters.</p> +<p class="tent">Some versions of <i>awk</i> allow the form:</p> +<pre> +<tt>func name(args, ... ) { statements } +</tt></pre> +<p class="tent">This has been deprecated by the authors of the language, who asked that it not be specified.</p> +<p class="tent">Historical implementations of <i>awk</i> produce an error if a <b>next</b> statement is executed in a <b>BEGIN</b> +action, and cause <i>awk</i> to terminate if a <b>next</b> statement is executed in an <b>END</b> action. This behavior has not +been documented, and it was not believed that it was necessary to standardize it.</p> +<p class="tent">The specification of conversions between string and numeric values is much more detailed than in the documentation +of historical implementations or in the referenced <i>The AWK Programming Language</i>. Although most of the behavior is designed +to be intuitive, the details are necessary to ensure compatible behavior from different implementations. This is especially +important in relational expressions since the types of the operands determine whether a string or numeric comparison is performed. +From the perspective of an application developer, it is usually sufficient to expect intuitive behavior and to force conversions +(by adding zero or concatenating a null string) when the type of an expression does not obviously match what is needed. The intent +has been to specify historical practice in almost all cases. The one exception is that, in historical implementations, variables +and constants maintain both string and numeric values after their original value is converted by any use. This means that +referencing a variable or constant can have unexpected side-effects. For example, with historical implementations the following +program:</p> +<pre> +<tt>{ + a = "+2" + b = 2 + if (NR % 2) + c = a + b + if (a == b) + print "numeric comparison" + else + print "string comparison" +} +</tt></pre> +<p class="tent">would perform a numeric comparison (and output numeric comparison) for each odd-numbered line, but perform a string +comparison (and output string comparison) for each even-numbered line. POSIX.1-2024 ensures that comparisons will be numeric if +necessary. With historical implementations, the following program:</p> +<pre> +<tt>BEGIN { + OFMT = "%e" + print 3.14 + OFMT = "%f" + print 3.14 +} +</tt></pre> +<p class="tent">would output <tt>"3.140000e+00"</tt> twice, because in the second <b>print</b> statement the constant +<tt>"3.14"</tt> would have a string value from the previous conversion. POSIX.1-2024 requires that the output of the second +<b>print</b> statement be <tt>"3.140000"</tt>. The behavior of historical implementations was seen as too unintuitive and +unpredictable.</p> +<p class="tent">It was pointed out that with the rules contained in early drafts, the following script would print nothing:</p> +<pre> +<tt>BEGIN { + y[1.5] = 1 + OFMT = "%e" + print y[1.5] +} +</tt></pre> +<p class="tent">Therefore, a new variable, <b>CONVFMT</b>, was introduced. The <b>OFMT</b> variable is now restricted to affecting +output conversions of numbers to strings and <b>CONVFMT</b> is used for internal conversions, such as comparisons or array +indexing. The default value is the same as that for <b>OFMT</b>, so unless a program changes <b>CONVFMT</b> (which no historical +program would do), it will receive the historical behavior associated with internal string conversions.</p> +<p class="tent">The POSIX <i>awk</i> lexical and syntactic conventions are specified more formally than in other sources. Again the +intent has been to specify historical practice. One convention that may not be obvious from the formal grammar as in other verbal +descriptions is where <newline> characters are acceptable. There are several obvious placements such as terminating a +statement, and a <backslash> can be used to escape <newline> characters between any lexical tokens. In addition, +<newline> characters without <backslash> characters can follow a comma, an open brace, a logical AND operator +(<tt>"&&"</tt>), a logical OR operator (<tt>"||"</tt>), the <b>do</b> keyword, the <b>else</b> keyword, and the closing +parenthesis of an <b>if</b>, <b>for</b>, or <b>while</b> statement. For example:</p> +<pre> +<tt>{ print $1, + $2 } +</tt></pre> +<p class="tent">The requirement that <i>awk</i> add a trailing <newline> to the program argument text is to simplify the +grammar, making it match a text file in form. There is no way for an application or test suite to determine whether a literal +<newline> is added or whether <i>awk</i> simply acts as if it did.</p> +<p class="tent">POSIX.1-2024 requires several changes from historical implementations in order to support internationalization. +Probably the most subtle of these is the use of the decimal-point character, defined by the <i>LC_NUMERIC</i> category of the +locale, in representations of floating-point numbers. This locale-specific character is used in recognizing numeric input, in +converting between strings and numeric values, and in formatting output. However, regardless of locale, the <period> +character (the decimal-point character of the POSIX locale) is the decimal-point character recognized in processing <i>awk</i> +programs (including assignments in command line arguments). This is essentially the same convention as the one used in the +ISO C standard. The difference is that the C language includes the <a href= +"../functions/setlocale.html"><i>setlocale</i>()</a> function, which permits an application to modify its locale. Because of this +capability, a C application begins executing with its locale set to the C locale, and only executes in the environment-specified +locale after an explicit call to <a href="../functions/setlocale.html"><i>setlocale</i>()</a>. However, adding such an elaborate +new feature to the <i>awk</i> language was seen as inappropriate for POSIX.1-2024. It is possible to execute an <i>awk</i> program +explicitly in any desired locale by setting the environment in the shell.</p> +<p class="tent">The undefined behavior resulting from NULs in extended regular expressions allows future extensions for the GNU +<i>gawk</i> program to process binary data.</p> +<p class="tent">The behavior in the case of invalid <i>awk</i> programs (including lexical, syntactic, and semantic errors) is +undefined because it was considered overly limiting on implementations to specify. In most cases such errors can be expected to +produce a diagnostic and a non-zero exit status. However, some implementations may choose to extend the language in ways that make +use of certain invalid constructs. Other invalid constructs might be deemed worthy of a warning, but otherwise cause some +reasonable behavior. Still other constructs may be very difficult to detect in some implementations. Also, different +implementations might detect a given error during an initial parsing of the program (before reading any input files) while others +might detect it when executing the program after reading some input. Implementors should be aware that diagnosing errors as early +as possible and producing useful diagnostics can ease debugging of applications, and thus make an implementation more usable.</p> +<p class="tent">The unspecified behavior from using multi-character <b>RS</b> values is to allow possible future extensions based +on extended regular expressions used for record separators. Historical implementations take the first character of the string and +ignore the others.</p> +<p class="tent">Unspecified behavior when <a href= +"../utilities/split.html"><i>split</i></a>(<i>string</i>,<i>array</i>,<null>) is used is to allow a proposed future extension +that would split up a string into an array of individual characters.</p> +<p class="tent">In the context of the <b>getline</b> function, equally good arguments for different precedences of the <b>|</b> and +<b><</b> operators can be made. Historical practice has been that:</p> +<pre> +<tt>getline < "a" "b" +</tt></pre> +<p class="tent">is parsed as:</p> +<pre> +<tt>( getline < "a" ) "b" +</tt></pre> +<p class="tent">although many would argue that the intent was that the file <b>ab</b> should be read. However:</p> +<pre> +<tt>getline < "x" + 1 +</tt></pre> +<p class="tent">parses as:</p> +<pre> +<tt>getline < ( "x" + 1 ) +</tt></pre> +<p class="tent">Similar problems occur with the <b>|</b> version of <b>getline</b>, particularly in combination with <b>$</b>. For +example:</p> +<pre> +<tt>$"echo hi" | getline +</tt></pre> +<p class="tent">(This situation is particularly problematic when used in a <b>print</b> statement, where the <b>|getline</b> part +might be a redirection of the <b>print</b>.)</p> +<p class="tent">Since in most cases such constructs are not (or at least should not) be used (because they have a natural ambiguity +for which there is no conventional parsing), the meaning of these constructs has been made explicitly unspecified. (The effect is +that a conforming application that runs into the problem must parenthesize to resolve the ambiguity.) There appeared to be few if +any actual uses of such constructs.</p> +<p class="tent">Grammars can be written that would cause an error under these circumstances. Where backwards-compatibility is not a +large consideration, implementors may wish to use such grammars.</p> +<p class="tent">Some historical implementations have allowed some built-in functions to be called without an argument list, the +result being a default argument list chosen in some "reasonable" way. Use of <b>length</b> as a synonym for <b>length($0)</b> is +the only one of these forms that is thought to be widely known or widely used; this particular form is documented in various places +(for example, most historical <i>awk</i> reference pages, although not in the referenced <i>The AWK Programming Language</i>) as +legitimate practice. With this exception, default argument lists have always been undocumented and vaguely defined, and it is not +at all clear how (or if) they should be generalized to user-defined functions. They add no useful functionality and preclude +possible future extensions that might need to name functions without calling them. Not standardizing them seems the simplest +course. The standard developers considered that <b>length</b> merited special treatment, however, since it has been documented in +the past and sees possibly substantial use in historical programs. Accordingly, this usage has been made legitimate, but +Issue 5 removed the obsolescent marking for XSI-conforming implementations and many otherwise conforming applications depend +on this feature.</p> +<p class="tent">In <b>sub</b> and <b>gsub</b>, if <i>repl</i> is a string literal (the lexical token <b>STRING</b>), then two +consecutive <backslash> characters should be used in the string to ensure a single <backslash> will precede the +<ampersand> when the resultant string is passed to the function. (For example, to specify one literal <ampersand> in +the replacement string, use <b>gsub</b>(<b>ERE</b>, <tt>"\\&"</tt>).)</p> +<p class="tent">Historically, the only special character in the <i>repl</i> argument of <b>sub</b> and <b>gsub</b> string functions +was the <ampersand> (<tt>'&'</tt>) character and preceding it with the <backslash> character was used to turn off +its special meaning.</p> +<p class="tent">The description in the ISO POSIX-2:1993 standard introduced behavior such that the <backslash> character +was another special character and it was unspecified whether there were any other special characters. This description introduced +several portability problems, some of which are described below, and so it has been replaced with the more historical description. +Some of the problems include:</p> +<ul> +<li class="tent">Historically, to create the replacement string, a script could use <b>gsub</b>(<b>ERE</b>, <tt>"\\&"</tt>), +but with the ISO POSIX-2:1993 standard wording, it was necessary to use <b>gsub</b>(<b>ERE</b>, <tt>"\\\\&"</tt>). The +<backslash> characters are doubled here because all string literals are subject to lexical analysis, which would reduce each +pair of <backslash> characters to a single <backslash> before being passed to <b>gsub</b>.</li> +<li class="tent">Since it was unspecified what the special characters were, for portable scripts to guarantee that characters are +printed literally, each character had to be preceded with a <backslash>. (For example, a portable script had to use +<b>gsub</b>(<b>ERE</b>, <tt>"\\h\\i"</tt>) to produce a replacement string of <tt>"hi"</tt>.)</li> +</ul> +<p class="tent">The description for comparisons in the ISO POSIX-2:1993 standard did not properly describe historical practice +because of the way numeric strings are compared as numbers. The current rules cause the following code:</p> +<pre> +<tt>if (0 == "000") + print "strange, but true" +else + print "not true" +</tt></pre> +<p class="tent">to do a numeric comparison, causing the <b>if</b> to succeed. It should be intuitively obvious that this is +incorrect behavior, and indeed, no historical implementation of <i>awk</i> actually behaves this way.</p> +<p class="tent">To fix this problem, the definition of <i>numeric string</i> was enhanced to include only those values obtained +from specific circumstances (mostly external sources) where it is not possible to determine unambiguously whether the value is +intended to be a string or a numeric.</p> +<p class="tent">Variables that are assigned to a numeric string shall also be treated as a numeric string. (For example, the notion +of a numeric string can be propagated across assignments.) In comparisons, all variables having the uninitialized value are to be +treated as a numeric operand evaluating to the numeric value zero.</p> +<p class="tent">Uninitialized variables include all types of variables including scalars, array elements, and fields. The +definition of an uninitialized value in <a href="#tag_20_06_13_03">Variables and Special Variables</a> is necessary to describe the +value placed on uninitialized variables and on fields that are valid (for example, <b><</b> <b>$NF</b>) but have no characters +in them and to describe how these variables are to be used in comparisons. A valid field, such as <b>$1</b>, that has no characters +in it can be obtained from an input line of <tt>"\t\t"</tt> when <b>FS=</b><tt>'\t'</tt>. Historically, the comparison +(<b>$1<</b>10) was done numerically after evaluating <b>$1</b> to the value zero.</p> +<p class="tent">The phrase "... also shall have the numeric value of the numeric string" was removed from several sections of the +ISO POSIX-2:1993 standard because is specifies an unnecessary implementation detail. It is not necessary for POSIX.1-2024 to +specify that these objects be assigned two different values. It is only necessary to specify that these objects may evaluate to two +different values depending on context.</p> +<p class="tent">Historical implementations of <i>awk</i> did not parse hexadecimal integer or floating constants like +<tt>"0xa"</tt> and <tt>"0xap0"</tt>. Due to an oversight, the 2001 through 2004 editions of this standard required support for +hexadecimal floating constants. This was due to the reference to <a href="../functions/atof.html"><i>atof</i>()</a>. This version +of the standard allows but does not require implementations to use <a href="../functions/atof.html"><i>atof</i>()</a> and includes +a description of how floating-point numbers are recognized as an alternative to match historic behavior. The intent of this change +is to allow implementations to recognize floating-point constants according to either the ISO/IEC 9899:1990 standard or +ISO/IEC 9899:1999 standard, and to allow (but not require) implementations to recognize hexadecimal integer constants.</p> +<p class="tent">Historical implementations of <i>awk</i> did not support floating-point infinities and NaNs in <i>numeric +strings</i>; e.g., <tt>"-INF"</tt> and <tt>"NaN"</tt>. However, implementations that use the <a href= +"../functions/atof.html"><i>atof</i>()</a> or <a href="../functions/strtod.html"><i>strtod</i>()</a> functions to do the conversion +picked up support for these values if they used a ISO/IEC 9899:1999 standard version of the function instead of a +ISO/IEC 9899:1990 standard version. Due to an oversight, the 2001 through 2004 editions of this standard did not allow support +for infinities and NaNs, but in this revision support is allowed (but not required). This is a silent change to the behavior of +<i>awk</i> programs; for example, in the POSIX locale the expression:</p> +<pre> +<tt>("-INF" + 0 < 0) +</tt></pre> +<p class="tent">formerly had the value 0 because <tt>"-INF"</tt> converted to 0, but now it may have the value 0 or 1.</p> +<p class="tent">Deleting all elements of an array one element at a time, via:</p> +<pre> +<tt>for (index in array) + delete array[index] +</tt></pre> +<p class="tent">is usually not efficient. This standard requires <tt>delete array</tt> to have the same effects, and this was +supported in most implementations as a more efficient operation. It is also possible to use <tt>split("", array)</tt> to achieve +the same effect and efficiency.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_06_19" id="tag_20_06_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a +<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require +implementations to treat this as an error.</p> +<p class="tent">A future version of this standard may require <b>srand</b> to accept any numeric value and calculate the seed by +taking the provided value, converting it to an integer, and calculating the integer value modulo +2<sup><small><i>n</i></small></sup> where <i>n</i> is an implementation-defined value greater than or equal to 32.</p> +<p class="tent">A future version of this standard may require the initial seed for the <b>rand</b> function (the seed value used if +<b>srand</b> is not called) to be an integer between 0 and 2<sup><small><i>n</i></small></sup>-1 inclusive where <i>n</i> is an +implementation-defined value greater than or equal to 32. Additionally, the initial seed value may be required to be a +(pseudo-)random value such that two invocations of <i>awk</i> are unlikely to emit the same sequence of random values (unless the +seed is explicitly set to the same value via <b>srand</b>).</p> +<p class="tent">A future version of this standard may define a new <b>posix_srand</b> function that enables application authors to +set the seed to a (pseudo-)random value generated by the system. Alternatively, the specification of the <b>srand</b> function may +be altered to provide some means to set the default seed value to a (pseudo-)random value.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_06_20" id="tag_20_06_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap01.html#tag_18_03"><i>1.3 Grammar Conventions</i></a> , <a href= +"../utilities/grep.html#"><i>grep</i></a> , <a href="../utilities/lex.html#"><i>lex</i></a> , <a href= +"../utilities/sed.html#"><i>sed</i></a></p> +<p class="tent">XBD <a href="../basedefs/V1_chap05.html#tag_05"><i>5. File Format Notation</i></a> , <a href= +"../basedefs/V1_chap06.html#tag_06_01"><i>6.1 Portable Character Set</i></a> , <a href="../basedefs/V1_chap08.html#tag_08"><i>8. +Environment Variables</i></a> , <a href="../basedefs/V1_chap09.html#tag_09"><i>9. Regular Expressions</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p class="tent">XSH <a href="../functions/atof.html#"><i>atof</i></a> , <a href="../functions/exec.html#tag_17_129"><i>exec</i></a> +, <a href="../functions/isspace.html#"><i>isspace</i></a> , <a href="../functions/popen.html#"><i>popen</i></a> , <a href= +"../functions/setlocale.html#"><i>setlocale</i></a> , <a href="../functions/strtod.html#"><i>strtod</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_06_21" id="tag_20_06_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_06_22" id="tag_20_06_22"></a>Issue 5</h4> +<blockquote> +<p>The FUTURE DIRECTIONS section is added.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_06_23" id="tag_20_06_23"></a>Issue 6</h4> +<blockquote> +<p>The <i>awk</i> utility is aligned with the IEEE P1003.2b draft standard.</p> +<p class="tent">The normative text is reworded to avoid use of the term "must" for application requirements.<br></p> +<p class="tent">IEEE PASC Interpretation 1003.2 #211 is applied, adding the sentence "An occurrence of two consecutive +<backslash> characters shall be interpreted as just a single literal <backslash> character." into the description of +the <b>sub</b> string function.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_06_24" id="tag_20_06_24"></a>Issue 7</h4> +<blockquote> +<p>PASC Interpretation 1003.2-1992 #107 (SD5-XCU-ERN-73) is applied, updating the description of the <b>OFS</b> variable.</p> +<p class="tent">Austin Group Interpretation 1003.1-2001 #189 is applied.</p> +<p class="tent">Austin Group Interpretation 1003.1-2001 #201 is applied, permitting implementations to support infinities and +NaNs.</p> +<p class="tent">SD5-XCU-ERN-79 is applied, restoring the horizontal lines to <a href="#tagtcjh_14">Expressions in Decreasing +Precedence in awk</a> , and SD5-XCU-ERN-80 is applied, changing the order of some table entries.</p> +<p class="tent">SD5-XCU-ERN-87 is applied, updating the descriptive text of the Grammar.</p> +<p class="tent">SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p class="tent">The EXTENDED DESCRIPTION is changed to make the support of hexadecimal integer and floating constants optional.</p> +<p class="tent">POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0057 [224], XCU/TC1-2008/0058 [454], XCU/TC1-2008/0059 [224], +XCU/TC1-2008/0060 [224], XCU/TC1-2008/0061 [254], XCU/TC1-2008/0062 [254], XCU/TC1-2008/0063 [224], and XCU/TC1-2008/0064 [454] are +applied.</p> +<p class="tent">POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0058 [584], XCU/TC2-2008/0059 [963], XCU/TC2-2008/0060 [226], +XCU/TC2-2008/0061 [663], XCU/TC2-2008/0062 [963], XCU/TC2-2008/0063 [226], and XCU/TC2-2008/0064 [963] are applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_06_25" id="tag_20_06_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to disallow the creation of filenames containing any bytes that +have the encoded value of a <newline> character.</p> +<p class="tent">Austin Group Defects 544 and 1136 are applied, requiring implementations to accept the <b>delete</b> statement with +an unsubscripted array name.</p> +<p class="tent">Austin Group Defect 607 is applied, adding the <b>nextfile</b> statement.</p> +<p class="tent">Austin Group Defect 634 is applied, adding the <b>fflush</b> function.</p> +<p class="tent">Austin Group Defects 974 and 1451 are applied, clarifying the <b>ARGC</b>, <b>ARGV</b> and <b>FILENAME</b> +variables, and adding to APPLICATION USAGE.</p> +<p class="tent">Austin Group Defect 983 is applied, changing the descriptions of the <b>rand</b> and <b>srand</b> functions and the +FUTURE DIRECTIONS section.</p> +<p class="tent">Austin Group Defect 1070 is applied, requiring the <tt>"!="</tt> and <tt>"=="</tt> operators to perform string +comparisons by checking if the strings are identical (and not by checking if they collate equally).</p> +<p class="tent">Austin Group Defect 1105 is applied, clarifying the requirements for <backslash> escaping.</p> +<p class="tent">Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p class="tent">Austin Group Defect 1198 is applied, requiring comparisons to be performed numerically when both operands have +string values that are numeric strings.</p> +<p class="tent">Austin Group Defect 1277 is applied, clarifying that using a <slash> character within an ERE requires +escaping only if it is within the lexical token <b>ERE</b>.</p> +<p class="tent">Austin Group Defect 1320 is applied, clarifying the condition under which ERE matching is against input +records.</p> +<p class="tent">Austin Group Defect 1395 is applied, changing the requirements for string to number conversion.</p> +<p class="tent">Austin Group Defect 1468 is applied, clarifying the behavior when <b>FS</b> is an ERE that can match the null +string.</p> +<p class="tent">Austin Group Defect 1566 is applied, specifying the behavior of the <b>length</b> function when passed an array +argument.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/at.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/basename.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/basename.html b/bdd/basename.html @@ -0,0 +1,262 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>basename</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/awk.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/batch.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="basename" id="basename"></a> <a name="tag_20_07" id="tag_20_07"></a><!-- basename --> +<h4 class="mansect"><a name="tag_20_07_01" id="tag_20_07_01"></a>NAME</h4> +<blockquote>basename — return non-directory portion of a pathname</blockquote> +<h4 class="mansect"><a name="tag_20_07_02" id="tag_20_07_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>basename</tt> <i>string</i> <b>[</b><i>suffix</i><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_07_03" id="tag_20_07_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>string</i> operand shall be treated as a pathname, as defined in XBD <a href= +"../basedefs/V1_chap03.html#tag_03_254"><i>3.254 Pathname</i></a> . The string <i>string</i> shall be converted to the filename +corresponding to the last pathname component in <i>string</i> and then the suffix string <i>suffix</i>, if present, shall be +removed. This shall be done by performing actions equivalent to the following steps in order:</p> +<ol> +<li> +<p>If <i>string</i> is a null string, it is unspecified whether the resulting string is <tt>'.'</tt> or a null string. In either +case, skip steps 2 through 6.</p> +</li> +<li> +<p>If <i>string</i> is <tt>"//"</tt>, it is implementation-defined whether steps 3 to 6 are skipped or processed.</p> +</li> +<li> +<p>If <i>string</i> consists entirely of <slash> characters, <i>string</i> shall be set to a single <slash> character. +In this case, skip steps 4 to 6.</p> +</li> +<li> +<p>If there are any trailing <slash> characters in <i>string</i>, they shall be removed.</p> +</li> +<li> +<p>If there are any <slash> characters remaining in <i>string</i>, the prefix of <i>string</i> up to and including the last +<slash> character in <i>string</i> shall be removed.</p> +</li> +<li> +<p>If the <i>suffix</i> operand is present, is not identical to the characters remaining in <i>string</i>, and is identical to a +suffix of the characters remaining in <i>string</i>, the suffix <i>suffix</i> shall be removed from <i>string</i>. Otherwise, +<i>string</i> is not modified by this step. It shall not be considered an error if <i>suffix</i> is not found in <i>string</i>.</p> +</li> +</ol> +<p>The resulting string shall be written to standard output.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_07_04" id="tag_20_07_04"></a>OPTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_07_05" id="tag_20_07_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>string</i></dt> +<dd>A string.</dd> +<dt><i>suffix</i></dt> +<dd>A string.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_07_06" id="tag_20_07_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_07_07" id="tag_20_07_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_07_08" id="tag_20_07_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>basename</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_07_09" id="tag_20_07_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_07_10" id="tag_20_07_10"></a>STDOUT</h4> +<blockquote> +<p>The <i>basename</i> utility shall write a line to the standard output in the following format:</p> +<pre> +<tt>"%s\n", <</tt><i>resulting string</i><tt>> +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_07_11" id="tag_20_07_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_07_12" id="tag_20_07_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_07_13" id="tag_20_07_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_07_14" id="tag_20_07_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_07_15" id="tag_20_07_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_07_16" id="tag_20_07_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The definition of <i>pathname</i> specifies implementation-defined behavior for pathnames starting with two <slash> +characters. Therefore, applications shall not arbitrarily add <slash> characters to the beginning of a pathname unless they +can ensure that there are more or less than two or are prepared to deal with the implementation-defined consequences.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_07_17" id="tag_20_07_17"></a>EXAMPLES</h4> +<blockquote> +<p>If the string <i>string</i> is a valid pathname:</p> +<pre> +<tt>$(basename -- "</tt><i>string</i><tt>") +</tt></pre> +<p>produces a filename that could be used to open the file named by <i>string</i> in the directory returned by:</p> +<pre> +<tt>$(dirname -- "</tt><i>string</i><tt>") +</tt></pre> +<p>If the string <i>string</i> is not a valid pathname, the same algorithm is used, but the result need not be a valid filename. +The <i>basename</i> utility is not expected to make any judgements about the validity of <i>string</i> as a pathname; it just +follows the specified algorithm to produce a result string.</p> +<p>The following shell script compiles <b>/usr/src/cmd/cat.c</b> and moves the output to a file named <b>cat</b> in the current +directory when invoked with the argument <b>/usr/src/cmd/cat</b> or with the argument <b>/usr/src/cmd/cat.c</b>:</p> +<pre> +<tt>c17 -- "$(dirname -- "$1")/$(basename -- "$1" .c).c" && +mv a.out "$(basename -- "$1" .c)" +</tt></pre> +<p>The EXAMPLES section of the <a href="../functions/basename.html"><i>basename</i>()</a> function (see XSH <a href= +"../functions/basename.html#tag_17_42"><i>basename</i></a> ) includes a table showing examples of the results of processing several +sample pathnames by the <a href="../functions/basename.html"><i>basename</i>()</a> and <a href= +"../functions/dirname.html"><i>dirname</i>()</a> functions and by the <i>basename</i> and <a href= +"../utilities/dirname.html"><i>dirname</i></a> utilities.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_07_18" id="tag_20_07_18"></a>RATIONALE</h4> +<blockquote> +<p>The behaviors of <i>basename</i> and <a href="../utilities/dirname.html"><i>dirname</i></a> have been coordinated so that when +<i>string</i> is a valid pathname:</p> +<pre> +<tt>$(basename -- "</tt><i>string</i><tt>") +</tt></pre> +<p>would be a valid filename for the file in the directory:</p> +<pre> +<tt>$(dirname -- "</tt><i>string</i><tt>") +</tt></pre> +<p>This would not work for the early proposal versions of these utilities due to the way it specified handling of trailing +<slash> characters.</p> +<p>Since the definition of <i>pathname</i> specifies implementation-defined behavior for pathnames starting with two <slash> +characters, this volume of POSIX.1-2024 specifies similar implementation-defined behavior for the <i>basename</i> and <a href= +"../utilities/dirname.html"><i>dirname</i></a> utilities.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_07_19" id="tag_20_07_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_07_20" id="tag_20_07_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19_05"><i>2.5 Parameters and Variables</i></a> , <a href= +"../utilities/dirname.html#tag_20_35"><i>dirname</i></a></p> +<p>XBD <a href="../basedefs/V1_chap03.html#tag_03_254"><i>3.254 Pathname</i></a> , <a href= +"../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a></p> +<p>XSH <a href="../functions/basename.html#tag_17_42"><i>basename</i></a> , <a href= +"../functions/dirname.html#tag_17_108"><i>dirname</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_07_21" id="tag_20_07_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_07_22" id="tag_20_07_22"></a>Issue 6</h4> +<blockquote> +<p>IEEE PASC Interpretation 1003.2 #164 is applied.</p> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_07_23" id="tag_20_07_23"></a>Issue 7</h4> +<blockquote> +<p>POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0065 [192,538], XCU/TC1-2008/0066 [192,538], and XCU/TC1-2008/0067 +[192,430,538] are applied.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0065 [612] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_07_24" id="tag_20_07_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to report an error if a utility is directed to display a +pathname that contains any bytes that have the encoded value of a <newline> character when <newline> is a terminator or +separator in the output format being used.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/awk.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/batch.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/batch.html b/bdd/batch.html @@ -0,0 +1,262 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>batch</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/basename.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/bc.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="batch" id="batch"></a> <a name="tag_20_08" id="tag_20_08"></a><!-- batch --> +<h4 class="mansect"><a name="tag_20_08_01" id="tag_20_08_01"></a>NAME</h4> +<blockquote>batch — schedule commands to be executed in a batch queue</blockquote> +<h4 class="mansect"><a name="tag_20_08_02" id="tag_20_08_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><i>batch</i></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_08_03" id="tag_20_08_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>batch</i> utility shall read commands from standard input and schedule them for execution in a batch queue. It shall be +the equivalent of the command:</p> +<pre> +<tt>at -q b -m now +</tt></pre> +<p>where queue <i>b</i> is a special <a href="../utilities/at.html"><i>at</i></a> queue, specifically for batch jobs. Batch jobs +shall be submitted to the batch queue with no time constraints and shall be run by the system using algorithms, based on +unspecified factors, that may vary with each invocation of <i>batch</i>.</p> +<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Users shall be permitted to use <i>batch</i> if their name appears in the file <b>at.allow</b> which is located in an +implementation-defined directory. If that file does not exist, the file <b>at.deny</b>, which is located in an +implementation-defined directory, shall be checked to determine whether the user shall be denied access to <i>batch</i>. If neither +file exists, only a process with appropriate privileges shall be allowed to submit a job. If only <b>at.deny</b> exists and is +empty, global usage shall be permitted. The <b>at.allow</b> and <b>at.deny</b> files shall consist of one user name per line. +<img src="../images/opt-end.gif" alt="[Option End]" border="0"></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_08_04" id="tag_20_08_04"></a>OPTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_08_05" id="tag_20_08_05"></a>OPERANDS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_08_06" id="tag_20_08_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be a text file consisting of commands acceptable to the shell command language described in <a href= +"../utilities/V3_chap02.html#tag_19"><i>2. Shell Command Language</i></a> .</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_08_07" id="tag_20_08_07"></a>INPUT FILES</h4> +<blockquote> +<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +The text files <b>at.allow</b> and <b>at.deny</b>, which are located in an implementation-defined directory, shall contain zero or +more user names, one per line, of users who are, respectively, authorized or denied access to the <a href= +"../utilities/at.html"><i>at</i></a> and <i>batch</i> utilities. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_08_08" id="tag_20_08_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>batch</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error and +informative messages written to standard output.</dd> +<dt><i>LC_TIME</i></dt> +<dd>Determine the format and contents for date and time strings written by <i>batch</i>.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>SHELL</i></dt> +<dd>Determine the name of a command interpreter to be used to invoke the at-job. If the variable is unset or null, <a href= +"../utilities/sh.html"><i>sh</i></a> shall be used. If it is set to a value other than a name for <a href= +"../utilities/sh.html"><i>sh</i></a>, the implementation shall do one of the following: use that shell; use <a href= +"../utilities/sh.html"><i>sh</i></a>; use the login shell from the user database; any of the preceding accompanied by a warning +diagnostic about which was chosen.</dd> +<dt><i>TZ</i></dt> +<dd>Determine the timezone. The job shall be submitted for execution at the time specified by <i>timespec</i> or <b>-t</b> +<i>time</i> relative to the timezone specified by the <i>TZ</i> variable. If <i>timespec</i> specifies a timezone, it overrides +<i>TZ .</i> If <i>timespec</i> does not specify a timezone and <i>TZ</i> is unset or null, an unspecified default timezone shall be +used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_08_09" id="tag_20_08_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_08_10" id="tag_20_08_10"></a>STDOUT</h4> +<blockquote> +<p>When standard input is a terminal, prompts of unspecified format for each line of the user input described in the STDIN section +may be written to standard output.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_08_11" id="tag_20_08_11"></a>STDERR</h4> +<blockquote> +<p>The following shall be written to standard error when a job has been successfully submitted:</p> +<pre> +<tt>"job %s at %s\n", </tt><i>at_job_id</i><tt>, <</tt><i>date</i><tt>> +</tt></pre> +<p>where <i>date</i> shall be equivalent in format to the output of:</p> +<pre> +<tt>date +"%a %b %e %T %Y" +</tt></pre> +<p>The date and time written shall be adjusted so that they appear in the timezone of the user (as determined by the <i>TZ</i> +variable).</p> +<p>Neither this, nor warning messages concerning the selection of the command interpreter, are considered a diagnostic that changes +the exit status.</p> +<p>Diagnostic messages, if any, shall be written to standard error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_08_12" id="tag_20_08_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_08_13" id="tag_20_08_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_08_14" id="tag_20_08_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_08_15" id="tag_20_08_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>The job shall not be scheduled.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_08_16" id="tag_20_08_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>It may be useful to redirect standard output within the specified commands.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_08_17" id="tag_20_08_17"></a>EXAMPLES</h4> +<blockquote> +<ol> +<li> +<p>This sequence can be used at a terminal:</p> +<pre> +<tt>batch +sort < file >outfile +EOT +</tt></pre></li> +<li> +<p>This sequence, which demonstrates redirecting standard error to a pipe, is useful in a command procedure (the sequence of output +redirection specifications is significant):</p> +<pre> +<tt>batch <<! +diff file1 file2 2>&1 >outfile | mailx -s "outfile update" mygroup +! +</tt></pre> +<p>Note that this always sends mail when there has been an attempt to update <b>outfile</b> and the body of the message will be +empty unless an error occurred.</p> +</li> +<li> +<p>The following shows how to capture both standard error and standard output:</p> +<pre> +<tt>batch <<EOF +{ + run-batch-processing | + mailx -s "batch processing output" mygroup +} 2>&1 | mailx -E -s "errors during batch processing" mygroup +EOF +</tt></pre></li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_08_18" id="tag_20_08_18"></a>RATIONALE</h4> +<blockquote> +<p>Early proposals described <i>batch</i> in a manner totally separated from <a href="../utilities/at.html"><i>at</i></a>, even +though the historical model treated it almost as a synonym for <a href="../utilities/at.html"><i>at</i></a> <b>-qb</b>. A number of +features were added to list and control batch work separately from those in <a href="../utilities/at.html"><i>at</i></a>. Upon +further reflection, it was decided that the benefit of this did not merit the change to the historical interface.</p> +<p>The <b>-m</b> option was included on the equivalent <a href="../utilities/at.html"><i>at</i></a> command because it is +historical practice to mail results to the submitter, even if all job-produced output is redirected. As explained in the RATIONALE +for <a href="../utilities/at.html"><i>at</i></a>, the <b>now</b> keyword submits the job for immediate execution (after scheduling +delays), despite some historical systems where <a href="../utilities/at.html"><i>at</i></a> <b>now</b> would have been considered +an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_08_19" id="tag_20_08_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_08_20" id="tag_20_08_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/at.html#"><i>at</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_08_21" id="tag_20_08_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_08_22" id="tag_20_08_22"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +<p>The NAME is changed to align with the IEEE P1003.2b draft standard.</p> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_08_23" id="tag_20_08_23"></a>Issue 7</h4> +<blockquote> +<p>The <i>batch</i> utility is moved from the User Portability Utilities option to the Base. User Portability Utilities is now an +option for interactive utilities.</p> +<p>SD5-XCU-ERN-95 is applied, removing the references to fixed locations for the files referenced by the <i>batch</i> utility.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_08_24" id="tag_20_08_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1368 is applied, changing the EXAMPLES section.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/basename.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/bc.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/bc.html b/bdd/bc.html @@ -0,0 +1,974 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>bc</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/batch.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/bg.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="bc" id="bc"></a> <a name="tag_20_09" id="tag_20_09"></a><!-- bc --> +<h4 class="mansect"><a name="tag_20_09_01" id="tag_20_09_01"></a>NAME</h4> +<blockquote>bc — arbitrary-precision arithmetic language</blockquote> +<h4 class="mansect"><a name="tag_20_09_02" id="tag_20_09_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>bc</tt> <b>[</b><tt>-l</tt><b>] [</b><i>file</i><tt>...</tt><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_09_03" id="tag_20_09_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>bc</i> utility shall implement an arbitrary precision calculator. It shall take input from any files given, then read +from the standard input. If the standard input and standard output to <i>bc</i> are attached to a terminal, the invocation of +<i>bc</i> shall be considered to be <i>interactive</i>, causing behavioral constraints described in the following sections.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_09_04" id="tag_20_09_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>bc</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following option shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-l</b></dt> +<dd>(The letter ell.) Define the math functions and initialize <i>scale</i> to 20, instead of the default zero; see the EXTENDED +DESCRIPTION section.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_09_05" id="tag_20_09_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of a text file containing <i>bc</i> program statements. After all <i>file</i>s have been read, <i>bc</i> shall read +the standard input.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_09_06" id="tag_20_09_06"></a>STDIN</h4> +<blockquote> +<p>See the INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_09_07" id="tag_20_09_07"></a>INPUT FILES</h4> +<blockquote> +<p>Input files shall be text files containing a sequence of comments, statements, and function definitions that shall be executed +as they are read.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_09_08" id="tag_20_09_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>bc</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_09_09" id="tag_20_09_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_09_10" id="tag_20_09_10"></a>STDOUT</h4> +<blockquote> +<p>The output of the <i>bc</i> utility shall be controlled by the program read, and consist of zero or more lines containing the +value of all executed expressions without assignments. The radix and precision of the output shall be controlled by the values of +the <b>obase</b> and <b>scale</b> variables; see the EXTENDED DESCRIPTION section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_09_11" id="tag_20_09_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_09_12" id="tag_20_09_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_09_13" id="tag_20_09_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<h5><a name="tag_20_09_13_01" id="tag_20_09_13_01"></a>Grammar</h5> +<p>The grammar in this section and the lexical conventions in the following section shall together describe the syntax for +<i>bc</i> programs. The general conventions for this style of grammar are described in <a href= +"../utilities/V3_chap01.html#tag_18_03"><i>1.3 Grammar Conventions</i></a> . A valid program can be represented as the non-terminal +symbol <b>program</b> in the grammar. This formal syntax shall take precedence over the text syntax description.</p> +<pre> +<tt>%token EOF NEWLINE STRING LETTER NUMBER +<br> +%token MUL_OP +/* '*', '/', '%' */ +<br> +%token ASSIGN_OP +/* '=', '+=', '-=', '*=', '/=', '%=', '^=' */ +<br> +%token REL_OP +/* '==', '<=', '>=', '!=', '<', '>' */ +<br> +%token INCR_DECR +/* '++', '--' */ +<br> +%token Define Break Quit Length +/* 'define', 'break', 'quit', 'length' */ +<br> +%token Return For If While Sqrt +/* 'return', 'for', 'if', 'while', 'sqrt' */ +<br> +%token Scale Ibase Obase Auto +/* 'scale', 'ibase', 'obase', 'auto' */ +<br> +%start program +<br> +%% +<br> +program : EOF + | input_item program + ; +<br> +input_item : semicolon_list NEWLINE + | function + ; +<br> +semicolon_list : /* empty */ + | statement + | semicolon_list ';' statement + | semicolon_list ';' + ; +<br> +statement_list : /* empty */ + | statement + | statement_list NEWLINE + | statement_list NEWLINE statement + | statement_list ';' + | statement_list ';' statement + ; +<br> +statement : expression + | STRING + | Break + | Quit + | Return + | Return '(' return_expression ')' + | For '(' expression ';' + relational_expression ';' + expression ')' statement + | If '(' relational_expression ')' statement + | While '(' relational_expression ')' statement + | '{' statement_list '}' + ; +<br> +function : Define LETTER '(' opt_define_list ')' + '{' NEWLINE opt_auto_define_list + statement_list '}' + ; +<br> +opt_define_list : /* empty */ + | define_list + ; +<br> +opt_auto_define_list : /* empty */ + | Auto define_list NEWLINE + | Auto define_list ';' + ; +<br> +define_list : LETTER + | LETTER '[' ']' + | define_list ',' LETTER + | define_list ',' LETTER '[' ']' + ; +<br> +opt_argument_list : /* empty */ + | argument_list + ; +<br> +argument_list : expression + | expression ',' argument_list + | LETTER '[' ']' + | LETTER '[' ']' ',' argument_list + ; +<br> +relational_expression : expression + | expression REL_OP expression + ; +<br> +return_expression : /* empty */ + | expression + ; +<br> +expression : named_expression + | NUMBER + | '(' expression ')' + | LETTER '(' opt_argument_list ')' + | '-' expression + | expression '+' expression + | expression '-' expression + | expression MUL_OP expression + | expression '^' expression + | INCR_DECR named_expression + | named_expression INCR_DECR + | named_expression ASSIGN_OP expression + | Length '(' expression ')' + | Sqrt '(' expression ')' + | Scale '(' expression ')' + ; +<br> +named_expression : LETTER + | LETTER '[' expression ']' + | Scale + | Ibase + | Obase + ; +</tt></pre> +<h5><a name="tag_20_09_13_02" id="tag_20_09_13_02"></a>Lexical Conventions in bc</h5> +<p>The lexical conventions for <i>bc</i> programs, with respect to the preceding grammar, shall be as follows:</p> +<ol> +<li> +<p>Except as noted, <i>bc</i> shall recognize the longest possible token or delimiter beginning at a given point.</p> +</li> +<li> +<p>A comment shall consist of any characters beginning with the two adjacent characters <tt>"/*"</tt> and terminated by the next +occurrence of the two adjacent characters <tt>"*/"</tt>. Comments shall have no effect except to delimit lexical tokens.</p> +</li> +<li> +<p>The <newline> shall be recognized as the token <b>NEWLINE</b>.</p> +</li> +<li> +<p>The token <b>STRING</b> shall represent a string constant; it shall consist of any characters beginning with the double-quote +character (<tt>'"'</tt> ) and terminated by another occurrence of the double-quote character. The value of the string is the +sequence of all characters between, but not including, the two double-quote characters. All characters shall be taken literally +from the input, and there is no way to specify a string containing a double-quote character. The length of the value of each string +shall be limited to {BC_STRING_MAX} bytes.</p> +</li> +<li> +<p>A <blank> shall have no effect except as an ordinary character if it appears within a <b>STRING</b> token, or to delimit a +lexical token other than <b>STRING</b>.</p> +</li> +<li> +<p>The combination of a <backslash> character immediately followed by a <newline> shall have no effect other than to +delimit lexical tokens with the following exceptions:</p> +<ul> +<li> +<p>It shall be interpreted as the character sequence <tt>"\<newline>"</tt> in <b>STRING</b> tokens.</p> +</li> +<li> +<p>It shall be ignored as part of a multi-line <b>NUMBER</b> token.</p> +</li> +</ul> +</li> +<li> +<p>The token <b>NUMBER</b> shall represent a numeric constant. It shall be recognized by the following grammar:</p> +<pre> +<tt>NUMBER : integer + | '.' integer + | integer '.' + | integer '.' integer + ; +<br> +integer : digit + | integer digit + ; +<br> +digit : 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 + | 8 | 9 | A | B | C | D | E | F + ; +</tt></pre></li> +<li> +<p>The value of a <b>NUMBER</b> token shall be interpreted as a numeral in the base specified by the value of the internal register +<b>ibase</b> (described below). Each of the <b>digit</b> characters shall have the value from 0 to 15 in the order listed here, and +the <period> character shall represent the radix point. The behavior is undefined if digits greater than or equal to the +value of <b>ibase</b> appear in the token. However, note the exception for single-digit values being assigned to <b>ibase</b> and +<b>obase</b> themselves, in <a href="#tag_20_09_13_03">Operations in bc</a> .</p> +</li> +<li> +<p>The following keywords shall be recognized as tokens:</p> +<table cellpadding="3"> +<tr valign="top"> +<td align="left"> +<p class="tent"><b><br> +auto<br> +break<br> +define<br></b></p> +</td> +<td align="left"> +<p class="tent"><b><br> +ibase<br> +if<br> +for<br></b></p> +</td> +<td align="left"> +<p class="tent"><b><br> +length<br> +obase<br> +quit<br></b></p> +</td> +<td align="left"> +<p class="tent"><b><br> +return<br> +scale<br> +sqrt<br></b></p> +</td> +<td align="left"> +<p class="tent"><b><br> +while<br></b></p> +</td> +</tr> +</table> +</li> +<li class="tent">Any of the following characters occurring anywhere except within a keyword shall be recognized as the token +<b>LETTER</b>: +<pre> +<tt>a b c d e f g h i j k l m n o p q r s t u v w x y z +</tt></pre></li> +<li class="tent">The following single-character and two-character sequences shall be recognized as the token <b>ASSIGN_OP</b>: +<pre> +<tt>= += -= *= /= %= ^= +</tt></pre></li> +<li class="tent">If an <tt>'='</tt> character, as the beginning of a token, is followed by a <tt>'-'</tt> character with no +intervening delimiter, the behavior is undefined.</li> +<li class="tent">The following single-characters shall be recognized as the token <b>MUL_OP</b>: +<pre> +<tt>* / % +</tt></pre></li> +<li class="tent">The following single-character and two-character sequences shall be recognized as the token <b>REL_OP</b>: +<pre> +<tt>== <= >= != < > +</tt></pre></li> +<li class="tent">The following two-character sequences shall be recognized as the token <b>INCR_DECR</b>: +<pre> +<tt>++ -- +</tt></pre></li> +<li class="tent">The following single characters shall be recognized as tokens whose names are the character: +<pre> +<tt><newline> ( ) , + - ; [ ] ^ { } +</tt></pre></li> +<li class="tent">The token <b>EOF</b> is returned when the end of input is reached.</li> +</ol> +<h5><a name="tag_20_09_13_03" id="tag_20_09_13_03"></a>Operations in bc</h5> +<p class="tent">There are three kinds of identifiers: ordinary identifiers, array identifiers, and function identifiers. All three +types consist of single lowercase letters. Array identifiers shall be followed by square brackets (<tt>"[]"</tt>). An array +subscript is required except in an argument or auto list. Arrays are singly dimensioned and can contain up to {BC_DIM_MAX} +elements. Indexing shall begin at zero so an array is indexed from 0 to {BC_DIM_MAX}-1. Subscripts shall be truncated to integers. +The application shall ensure that function identifiers are followed by parentheses, possibly enclosing arguments. The three types +of identifiers do not conflict.</p> +<p class="tent">The following table summarizes the rules for precedence and associativity of all operators. Operators on the same +line shall have the same precedence; rows are in order of decreasing precedence.</p> +<p class="caption">Table: Operators in <i>bc</i></p> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Operator</b></p> +</th> +<th align="center"> +<p class="tent"><b>Associativity</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">++, --</p> +</td> +<td align="left"> +<p class="tent">N/A</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">unary -</p> +</td> +<td align="left"> +<p class="tent">N/A</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">^</p> +</td> +<td align="left"> +<p class="tent">Right to left</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">*, /, %</p> +</td> +<td align="left"> +<p class="tent">Left to right</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">+, binary -</p> +</td> +<td align="left"> +<p class="tent">Left to right</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">=, +=, -=, *=, /=, %=, ^=</p> +</td> +<td align="left"> +<p class="tent">Right to left</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">==, <=, >=, !=, <, ></p> +</td> +<td align="left"> +<p class="tent">None</p> +</td> +</tr> +</table> +</center> +<p class="tent">Each expression or named expression has a <i>scale</i>, which is the number of decimal digits that shall be +maintained as the fractional portion of the expression.</p> +<p class="tent"><i>Named expressions</i> are places where values are stored. Named expressions shall be valid on the left side of +an assignment. The value of a named expression shall be the value stored in the place named. Simple identifiers and array elements +are named expressions; they have an initial value of zero and an initial scale of zero.</p> +<p class="tent">The internal registers <b>scale</b>, <b>ibase</b>, and <b>obase</b> are all named expressions. The scale of an +expression consisting of the name of one of these registers shall be zero; values assigned to any of these registers are truncated +to integers. The <b>scale</b> register shall contain a global value used in computing the scale of expressions (as described +below). The value of the register <b>scale</b> is limited to 0 <= <b>scale</b> <= {BC_SCALE_MAX} and shall have a default +value of zero. The <b>ibase</b> and <b>obase</b> registers are the input and output number radix, respectively. The value of +<b>ibase</b> shall be limited to:</p> +<pre> +<tt>2 <= ibase <= 16 +</tt></pre> +<p class="tent">The value of <b>obase</b> shall be limited to:</p> +<pre> +<tt>2 <= obase <= {BC_BASE_MAX} +</tt></pre> +<p class="tent">When either <b>ibase</b> or <b>obase</b> is assigned a single <b>digit</b> value from the list in <a href= +"#tag_20_09_13_02">Lexical Conventions in bc</a> , the value shall be assumed in hexadecimal. (For example, <b>ibase</b>=A sets to +base ten, regardless of the current <b>ibase</b> value.) Otherwise, the behavior is undefined when digits greater than or equal to +the value of <b>ibase</b> appear in the input. Both <b>ibase</b> and <b>obase</b> shall have initial values of 10.</p> +<p class="tent">Internal computations shall be conducted as if in decimal, regardless of the input and output bases, to the +specified number of decimal digits. When an exact result is not achieved (for example, <b>scale</b>=0; 3.2/1)<b>,</b> the +result shall be truncated.</p> +<p class="tent">For all values of <b>obase</b> specified by this volume of POSIX.1-2024, <i>bc</i> shall output numeric values by +performing each of the following steps in order:</p> +<ol> +<li class="tent">If the value is less than zero, a <hyphen-minus> (<tt>'-'</tt>) character shall be output.</li> +<li class="tent">One of the following is output, depending on the numerical value: +<ul> +<li class="tent">If the absolute value of the numerical value is greater than or equal to one, the integer portion of the value +shall be output as a series of digits appropriate to <b>obase</b> (as described below), most significant digit first. The most +significant non-zero digit shall be output next, followed by each successively less significant digit.</li> +<li class="tent">If the absolute value of the numerical value is less than one but greater than zero and the scale of the numerical +value is greater than zero, it is unspecified whether the character 0 is output.</li> +<li class="tent">If the numerical value is zero, the character 0 shall be output.</li> +</ul> +</li> +<li class="tent">If the scale of the value is greater than zero and the numeric value is not zero, a <period> character shall +be output, followed by a series of digits appropriate to <b>obase</b> (as described below) representing the most significant +portion of the fractional part of the value. If <i>s</i> represents the scale of the value being output, the number of digits +output shall be <i>s</i> if <b>obase</b> is 10, less than or equal to <i>s</i> if <b>obase</b> is greater than 10, or greater than +or equal to <i>s</i> if <b>obase</b> is less than 10. For <b>obase</b> values other than 10, this should be the number of digits +needed to represent a precision of 10<sup><small><i>s</i></small></sup>.</li> +</ol> +<p class="tent">For <b>obase</b> values from 2 to 16, valid digits are the first <b>obase</b> of the single characters:</p> +<pre> +<tt>0 1 2 3 4 5 6 7 8 9 A B C D E F +</tt></pre> +<p class="tent">which represent the values zero to 15, inclusive, respectively.</p> +<p class="tent">For bases greater than 16, each digit shall be written as a separate multi-digit decimal number. Each digit except +the most significant fractional digit shall be preceded by a single <space>. For bases from 17 to 100, <i>bc</i> shall write +two-digit decimal numbers; for bases from 101 to 1000, three-digit decimal strings, and so on. For example, the decimal number 1024 +in base 25 would be written as:</p> +<pre> +<tt>Δ01Δ15Δ24 +</tt></pre> +<p class="tent">and in base 125, as:</p> +<pre> +<tt>Δ008Δ024 +</tt></pre> +<p class="tent">Very large numbers shall be split across lines with 70 characters per line in the POSIX locale; other locales may +split at different character boundaries. Lines that are continued shall end with a <backslash>.</p> +<p class="tent">A function call shall consist of a function name followed by parentheses containing a <comma>-separated list +of expressions, which are the function arguments. A whole array passed as an argument shall be specified by the array name followed +by empty square brackets. All function arguments shall be passed by value. As a result, changes made to the formal parameters shall +have no effect on the actual arguments. If the function terminates by executing a <b>return</b> statement, the value of the +function shall be the value of the expression in the parentheses of the <b>return</b> statement or shall be zero if no expression +is provided or if there is no <b>return</b> statement.</p> +<p class="tent">The result of <b>sqrt</b>(<i>expression</i>) shall be the square root of the expression. The result shall be +truncated in the least significant decimal place. The scale of the result shall be the scale of the expression or the value of +<b>scale</b>, whichever is larger.</p> +<p class="tent">The result of <b>length</b>(<i>expression</i>) shall be the total number of significant decimal digits in the +expression. The scale of the result shall be zero.</p> +<p class="tent">The result of <b>scale</b>(<i>expression</i>) shall be the scale of the expression. The scale of the result shall +be zero.</p> +<p class="tent">A numeric constant shall be an expression. The scale shall be the number of digits that follow the radix point in +the input representing the constant, or zero if no radix point appears.</p> +<p class="tent">The sequence ( <i>expression</i> ) shall be an expression with the same value and scale as +<i>expression</i>. The parentheses can be used to alter the normal precedence.</p> +<p class="tent">The semantics of the unary and binary operators are as follows:</p> +<dl compact> +<dd></dd> +<dt>-<i>expression</i></dt> +<dd><br> +The result shall be the negative of the <i>expression</i>. The scale of the result shall be the scale of <i>expression</i>.</dd> +</dl> +<p class="tent">The unary increment and decrement operators shall not modify the scale of the named expression upon which they +operate. The scale of the result shall be the scale of that named expression.</p> +<dl compact> +<dd></dd> +<dt>++<i>named-expression</i></dt> +<dd><br> +The named expression shall be incremented by one. The result shall be the value of the named expression after incrementing.</dd> +<dt>--<i>named-expression</i></dt> +<dd><br> +The named expression shall be decremented by one. The result shall be the value of the named expression after decrementing.</dd> +<dt><i>named-expression</i>++</dt> +<dd><br> +The named expression shall be incremented by one. The result shall be the value of the named expression before incrementing.</dd> +<dt><i>named-expression</i>--</dt> +<dd><br> +The named expression shall be decremented by one. The result shall be the value of the named expression before decrementing.</dd> +</dl> +<p class="tent">The exponentiation operator, <circumflex> (<tt>'^'</tt>), shall bind right to left.</p> +<dl compact> +<dd></dd> +<dt><i>expression</i>^<i>expression</i></dt> +<dd><br> +The result shall be the first <i>expression</i> raised to the power of the second <i>expression</i>. If the second expression is +not an integer, the behavior is undefined. If <i>a</i> is the scale of the left expression and <i>b</i> is the absolute value of +the right expression, the scale of the result shall be: +<pre> +<tt>if b >= 0 min(a * b, max(scale, a)) if b < 0 scale +</tt></pre></dd> +</dl> +The multiplicative operators (<tt>'*'</tt>, <tt>'/'</tt>, <tt>'%'</tt>) shall bind left to right. +<dl compact> +<dd></dd> +<dt><i>expression</i>*<i>expression</i></dt> +<dd><br> +The result shall be the product of the two expressions. If <i>a</i> and <i>b</i> are the scales of the two expressions, then the +scale of the result shall be: +<pre> +<tt>min(a+b,max(scale,a,b)) +</tt></pre></dd> +<dt><i>expression</i>/<i>expression</i></dt> +<dd><br> +The result shall be the quotient of the two expressions. The scale of the result shall be the value of <b>scale</b>.</dd> +<dt><i>expression</i>%<i>expression</i></dt> +<dd><br> +For expressions <i>a</i> and <i>b</i>, <i>a</i>%<i>b</i> shall be evaluated equivalent to the steps: +<ol> +<li class="tent">Compute <i>a</i>/<i>b</i> to current scale.</li> +<li class="tent">Use the result to compute: +<pre> +<tt>a - (a / b) * b +</tt></pre> +<p class="tent">to scale:</p> +<pre> +<tt>max(scale + scale(b), scale(a)) +</tt></pre></li> +</ol> +The scale of the result shall be: +<pre> +<tt>max(scale + scale(b), scale(a)) +</tt></pre> +<p class="tent">When <b>scale</b> is zero, the <tt>'%'</tt> operator is the mathematical remainder operator.</p> +</dd> +</dl> +<p class="tent">The additive operators (<tt>'+'</tt>, <tt>'-'</tt>) shall bind left to right.</p> +<dl compact> +<dd></dd> +<dt><i>expression</i>+<i>expression</i></dt> +<dd><br> +The result shall be the sum of the two expressions. The scale of the result shall be the maximum of the scales of the +expressions.</dd> +<dt><i>expression</i>-<i>expression</i></dt> +<dd><br> +The result shall be the difference of the two expressions. The scale of the result shall be the maximum of the scales of the +expressions.</dd> +</dl> +<p class="tent">The assignment operators (<tt>'='</tt>, <tt>"+="</tt>, <tt>"-="</tt>, <tt>"*="</tt>, <tt>"/="</tt>, <tt>"%="</tt>, +<tt>"^="</tt>) shall bind right to left.</p> +<dl compact> +<dd></dd> +<dt><i>named-expression</i>=<i>expression</i></dt> +<dd><br> +This expression shall result in assigning the value of the expression on the right to the named expression on the left. The scale +of both the named expression and the result shall be the scale of <i>expression</i>.</dd> +</dl> +<p class="tent">The compound assignment forms:</p> +<pre> +<i>named-expression</i><tt> <</tt><i>operator</i><tt>>= </tt><i>expression</i><tt> +</tt></pre> +<p class="tent">shall be equivalent to:</p> +<pre> +<i>named-expression</i><tt>=</tt><i>named-expression</i><tt> <</tt><i>operator</i><tt>> </tt><i>expression</i><tt> +</tt></pre> +<p class="tent">except that the <i>named-expression</i> shall be evaluated only once.</p> +<p class="tent">Unlike all other operators, the relational operators (<tt>'<'</tt>, <tt>'>'</tt>, <tt>"<="</tt>, +<tt>">="</tt>, <tt>"=="</tt>, <tt>"!="</tt>) shall be only valid as the object of an <b>if</b>, <b>while</b>, or inside a +<b>for</b> statement.</p> +<dl compact> +<dd></dd> +<dt><i>expression1</i><<i>expression2</i></dt> +<dd><br> +The relation shall be true if the value of <i>expression1</i> is strictly less than the value of <i>expression2</i>.</dd> +<dt><i>expression1</i>><i>expression2</i></dt> +<dd><br> +The relation shall be true if the value of <i>expression1</i> is strictly greater than the value of <i>expression2</i>.</dd> +<dt><i>expression1</i><=<i>expression2</i></dt> +<dd><br> +The relation shall be true if the value of <i>expression1</i> is less than or equal to the value of <i>expression2</i>.</dd> +<dt><i>expression1</i>>=<i>expression2</i></dt> +<dd><br> +The relation shall be true if the value of <i>expression1</i> is greater than or equal to the value of <i>expression2</i>.</dd> +<dt><i>expression1</i>==<i>expression2</i></dt> +<dd><br> +The relation shall be true if the values of <i>expression1</i> and <i>expression2</i> are equal.</dd> +<dt><i>expression1</i>!=<i>expression2</i></dt> +<dd><br> +The relation shall be true if the values of <i>expression1</i> and <i>expression2</i> are unequal.</dd> +</dl> +<p class="tent">There are only two storage classes in <i>bc</i>: global and automatic (local). Only identifiers that are local to a +function need be declared with the <b>auto</b> command. The arguments to a function shall be local to the function. All other +identifiers are assumed to be global and available to all functions. All identifiers, global and local, have initial values of +zero. Identifiers declared as auto shall be allocated on entry to the function and released on returning from the function. They +therefore do not retain values between function calls. Auto arrays shall be specified by the array name followed by empty square +brackets. On entry to a function, the old values of the names that appear as parameters and as automatic variables shall be pushed +onto a stack. Until the function returns, reference to these names shall refer only to the new values.</p> +<p class="tent">References to any of these names from other functions that are called from this function also refer to the new +value until one of those functions uses the same name for a local variable.</p> +<p class="tent">When a statement is an expression, unless the main operator is an assignment, execution of the statement shall +write the value of the expression followed by a <newline>.</p> +<p class="tent">When a statement is a string, execution of the statement shall write the value of the string.</p> +<p class="tent">Statements separated by <semicolon> or <newline> characters shall be executed sequentially. In an +interactive invocation of <i>bc</i>, each time a <newline> is read that satisfies the grammatical production:</p> +<pre> +<tt>input_item : semicolon_list NEWLINE +</tt></pre> +<p class="tent">the sequential list of statements making up the <b>semicolon_list</b> shall be executed immediately and any output +produced by that execution shall be written without any delay due to buffering.</p> +<p class="tent">In an <b>if</b> statement (<b>if</b>(<i>relation</i>) <i>statement</i>), the <i>statement</i> shall be executed if +the relation is true.</p> +<p class="tent">The <b>while</b> statement (<b>while</b>(<i>relation</i>) <i>statement</i>) implements a loop in which the +<i>relation</i> is tested; each time the <i>relation</i> is true, the <i>statement</i> shall be executed and the <i>relation</i> +retested. When the <i>relation</i> is false, execution shall resume after <i>statement</i>.</p> +<p class="tent">A <b>for</b> statement(<b>for</b>(<i>expression</i>; <i>relation</i>; <i>expression</i>) <i>statement</i>) shall be +the same as:</p> +<pre> +<i>first-expression</i><tt> +while (</tt><i>relation</i><tt>) { + </tt><i>statement</i><tt> + </tt><i>last-expression</i><tt> +} +</tt></pre> +The application shall ensure that all three expressions are present. +<p class="tent">The <b>break</b> statement shall cause termination of a <b>for</b> or <b>while</b> statement.</p> +<p class="tent">The <b>auto</b> statement (<b>auto</b> <i>identifier</i> <b>[</b>,<i>identifier</i><b>]</b> ...) shall cause the +values of the identifiers to be pushed down. The identifiers can be ordinary identifiers or array identifiers. Array identifiers +shall be specified by following the array name by empty square brackets. The application shall ensure that the <b>auto</b> +statement is the first statement in a function definition.</p> +<p class="tent">A <b>define</b> statement:</p> +<pre> +<tt>define </tt><i>LETTER</i><tt> ( </tt><i>opt_define_list</i><tt> ) { + </tt><i>opt_auto_define_list</i><tt> + </tt><i>statement_list</i><tt> +} +</tt></pre> +<p class="tent">defines a function named <b>LETTER</b>. If a function named <b>LETTER</b> was previously defined, the <b>define</b> +statement shall replace the previous definition. The expression:</p> +<pre> +<tt>LETTER ( </tt><i>opt_argument_list</i><tt> ) +</tt></pre> +<p class="tent">shall invoke the function named <b>LETTER</b>. The behavior is undefined if the number of arguments in the +invocation does not match the number of parameters in the definition. Functions shall be defined before they are invoked. A +function shall be considered to be defined within its own body, so recursive calls are valid. The values of numeric constants +within a function shall be interpreted in the base specified by the value of the <b>ibase</b> register when the function is +invoked.</p> +<p class="tent">The <b>return</b> statements (<b>return</b> and <b>return</b>(<i>expression</i>)) shall cause termination of a +function, popping of its auto variables, and specification of the result of the function. The first form shall be equivalent to +<b>return</b>(0). The value and scale of the result returned by the function shall be the value and scale of the expression +returned.</p> +<p class="tent">The <b>quit</b> statement (<b>quit</b>) shall stop execution of a <i>bc</i> program at the point where the +statement occurs in the input, even if it occurs in a function definition, or in an <b>if</b>, <b>for</b>, or <b>while</b> +statement.</p> +<p class="tent">The following functions shall be defined when the <b>-l</b> option is specified:</p> +<dl compact> +<dd></dd> +<dt><b>s</b>( <i>expression</i> )</dt> +<dd><br> +Sine of argument in radians.</dd> +<dt><b>c</b>( <i>expression</i> )</dt> +<dd><br> +Cosine of argument in radians.</dd> +<dt><b>a</b>( <i>expression</i> )</dt> +<dd><br> +Arctangent of argument.</dd> +<dt><b>l</b>( <i>expression</i> )</dt> +<dd><br> +Natural logarithm of argument.</dd> +<dt><b>e</b>( <i>expression</i> )</dt> +<dd><br> +Exponential function of argument.</dd> +<dt><b>j</b>( <i>expression1</i>, <i>expression2</i> )</dt> +<dd><br> +Bessel function of <i>expression2</i> of the first kind of integer order <i>expression1</i>.</dd> +</dl> +<p class="tent">The scale of the result returned by these functions shall be the value of the <b>scale</b> register at the time the +function is invoked. The value of the <b>scale</b> register after these functions have completed their execution shall be the same +value it had upon invocation. The behavior is undefined if any of these functions is invoked with an argument outside the domain of +the mathematical function.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_09_14" id="tag_20_09_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt>0</dt> +<dd>All input files were processed successfully.</dd> +<dt><i>unspecified</i></dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_09_15" id="tag_20_09_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>If any <i>file</i> operand is specified and the named file cannot be accessed, <i>bc</i> shall write a diagnostic message to +standard error and terminate without any further action.</p> +<p class="tent">In an interactive invocation of <i>bc</i>, the utility should print an error message and recover following any +error in the input. In a non-interactive invocation of <i>bc</i>, invalid input causes undefined behavior.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_09_16" id="tag_20_09_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Automatic variables in <i>bc</i> do not work in exactly the same way as in either C or PL/1.</p> +<p class="tent">For historical reasons, the exit status from <i>bc</i> cannot be relied upon to indicate that an error has +occurred. Returning zero after an error is possible. Therefore, <i>bc</i> should be used primarily by interactive users (who can +react to error messages) or by application programs that can somehow validate the answers returned as not including error +messages.</p> +<p class="tent">The <i>bc</i> utility always uses the <period> (<tt>'.'</tt>) character to represent a radix point, +regardless of any decimal-point character specified as part of the current locale. In languages like C or <a href= +"../utilities/awk.html"><i>awk</i></a>, the <period> character is used in program source, so it can be portable and +unambiguous, while the locale-specific character is used in input and output. Because there is no distinction between source and +input in <i>bc</i>, this arrangement would not be possible. Using the locale-specific character in <i>bc</i>'s input would +introduce ambiguities into the language; consider the following example in a locale with a <comma> as the decimal-point +character:</p> +<pre> +<tt>define f(a,b) { + ... +} +... +<br class="tent"> +f(1,2,3) +</tt></pre> +<p class="tent">Because of such ambiguities, the <period> character is used in input. Having input follow different +conventions from output would be confusing in either pipeline usage or interactive usage, so the <period> is also used in +output.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_09_17" id="tag_20_09_17"></a>EXAMPLES</h4> +<blockquote> +<p>In the shell, the following assigns an approximation of the first ten digits of <tt>'ℼ'</tt> to the variable <i>x</i>:</p> +<pre> +<tt>x=$(printf "%s\n" 'scale = 10; 104348/33215' | bc) +</tt></pre> +<p class="tent">The following <i>bc</i> program prints the same approximation of <tt>'ℼ'</tt>, with a label, to standard +output:</p> +<pre> +<tt>scale = 10 +"pi equals " +104348 / 33215 +</tt></pre> +<p class="tent">The following defines a function to compute an approximate value of the exponential function (note that such a +function is predefined if the <b>-l</b> option is specified):</p> +<pre> +<tt>scale = 20 +define e(x){ + auto a, b, c, i, s + a = 1 + b = 1 + s = 1 + for (i = 1; 1 == 1; i++){ + a = a*x + b = b*i + c = a/b + if (c == 0) { + return(s) + } + s = s+c + } +} +</tt></pre> +<p class="tent">The following prints approximate values of the exponential function of the first ten integers:</p> +<pre> +<tt>for (i = 1; i <= 10; ++i) { + e(i) +} +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_09_18" id="tag_20_09_18"></a>RATIONALE</h4> +<blockquote> +<p>The <i>bc</i> utility is implemented historically as a front-end processor for <i>dc</i>; <i>dc</i> was not selected to be part +of this volume of POSIX.1-2024 because <i>bc</i> was thought to have a more intuitive programmatic interface. Current +implementations that implement <i>bc</i> using <i>dc</i> are expected to be compliant.</p> +<p class="tent">The exit status for error conditions has been left unspecified for several reasons:</p> +<ul> +<li class="tent">The <i>bc</i> utility is used in both interactive and non-interactive situations. Different exit codes may be +appropriate for the two uses.</li> +<li class="tent">It is unclear when a non-zero exit should be given; divide-by-zero, undefined functions, and syntax errors are all +possibilities.</li> +<li class="tent">It is not clear what utility the exit status has.</li> +<li class="tent">In the 4.3 BSD, System V, and Ninth Edition implementations, <i>bc</i> works in conjunction with <i>dc</i>. The +<i>dc</i> utility is the parent, <i>bc</i> is the child. This was done to cleanly terminate <i>bc</i> if <i>dc</i> aborted.</li> +</ul> +<p class="tent">The decision to have <i>bc</i> exit upon encountering an inaccessible input file is based on the belief that +<i>bc</i> <i>file1</i> <i>file2</i> is used most often when at least <i>file1</i> contains data/function +declarations/initializations. Having <i>bc</i> continue with prerequisite files missing is probably not useful. There is no +implication in the CONSEQUENCES OF ERRORS section that <i>bc</i> must check all its files for accessibility before opening any of +them.</p> +<p class="tent">There was considerable debate on the appropriateness of the language accepted by <i>bc</i>. Several reviewers +preferred to see either a pure subset of the C language or some changes to make the language more compatible with C. While the +<i>bc</i> language has some obvious similarities to C, it has never claimed to be compatible with any version of C. An interpreter +for a subset of C might be a very worthwhile utility, and it could potentially make <i>bc</i> obsolete. However, no such utility is +known in historical practice, and it was not within the scope of this volume of POSIX.1-2024 to define such a language and utility. +If and when they are defined, it may be appropriate to include them in a future version of this standard. This left the following +alternatives:</p> +<ol> +<li class="tent">Exclude any calculator language from this volume of POSIX.1-2024. +<p class="tent">The consensus of the standard developers was that a simple programmatic calculator language is very useful for both +applications and interactive users. The only arguments for excluding any calculator were that it would become obsolete if and when +a C-compatible one emerged, or that the absence would encourage the development of such a C-compatible one. These arguments did not +sufficiently address the needs of current application developers.</p> +</li> +<li class="tent">Standardize the historical <i>dc</i>, possibly with minor modifications. +<p class="tent">The consensus of the standard developers was that <i>dc</i> is a fundamentally less usable language and that that +would be far too severe a penalty for avoiding the issue of being similar to but incompatible with C.</p> +</li> +<li class="tent">Standardize the historical <i>bc</i>, possibly with minor modifications. +<p class="tent">This was the approach taken. Most of the proponents of changing the language would not have been satisfied until +most or all of the incompatibilities with C were resolved. Since most of the changes considered most desirable would break +historical applications and require significant modification to historical implementations, almost no modifications were made. The +one significant modification that was made was the replacement of the historical <i>bc</i> assignment operators <tt>"=+"</tt>, and +so on, with the more modern <tt>"+="</tt>, and so on. The older versions are considered to be fundamentally flawed because of the +lexical ambiguity in uses like <i>a</i>=-1.</p> +<p class="tent">In order to permit implementations to deal with backwards-compatibility as they see fit, the behavior of this one +ambiguous construct was made undefined. (At least three implementations have been known to support this change already, so the +degree of change involved should not be great.)</p> +</li> +</ol> +<p class="tent">The <tt>'%'</tt> operator is the mathematical remainder operator when <b>scale</b> is zero. The behavior of this +operator for other values of <b>scale</b> is from historical implementations of <i>bc</i>, and has been maintained for the sake of +historical applications despite its non-intuitive nature.</p> +<p class="tent">Historical implementations permit setting <b>ibase</b> and <b>obase</b> to a broader range of values. This includes +values less than 2, which were not seen as sufficiently useful to standardize. These implementations do not interpret input +properly for values of <b>ibase</b> that are greater than 16. This is because numeric constants are recognized syntactically, +rather than lexically, as described in this volume of POSIX.1-2024. They are built from lexical tokens of single hexadecimal digits +and <period> characters. Since <blank> characters between tokens are not visible at the syntactic level, it is not +possible to recognize the multi-digit "digits" used in the higher bases properly. The ability to recognize input in these bases +was not considered useful enough to require modifying these implementations. Note that the recognition of numeric constants at the +syntactic level is not a problem with conformance to this volume of POSIX.1-2024, as it does not impact the behavior of conforming +applications (and correct <i>bc</i> programs). Historical implementations also accept input with all of the digits +<tt>'0'</tt>-<tt>'9'</tt> and <tt>'A'</tt>-<tt>'F'</tt> regardless of the value of <b>ibase</b>; since digits with value greater +than or equal to <b>ibase</b> are not really appropriate, the behavior when they appear is undefined, except for the common case +of:</p> +<pre> +<tt>ibase=8; + /* Process in octal base. */ +... +ibase=A + /* Restore decimal base. */ +</tt></pre> +<p class="tent">In some historical implementations, if the expression to be written is an uninitialized array element, a leading +<space> and/or up to four leading 0 characters may be output before the character zero. This behavior is considered a bug; it +is unlikely that any currently conforming application relies on:</p> +<pre> +<tt>echo 'b[3]' | bc +</tt></pre> +<p class="tent">returning 00000 rather than 0.</p> +<p class="tent">Exact calculation of the number of fractional digits to output for a given value in a base other than 10 can be +computationally expensive. Historical implementations use a faster approximation, and this is permitted. Note that the requirements +apply only to values of <b>obase</b> that this volume of POSIX.1-2024 requires implementations to support (in particular, not to 1, +0, or negative bases, if an implementation supports them as an extension).</p> +<p class="tent">Historical implementations of <i>bc</i> did not allow array parameters to be passed as the last parameter to a +function. When <i>bc</i> was first standardized in Issue 4, this restriction was allowed. To make <i>bc</i> more widely useful, and +because there are implementations without this restriction, the allowance for the restriction has been removed.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_09_19" id="tag_20_09_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_09_20" id="tag_20_09_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap01.html#tag_18_03"><i>1.3 Grammar Conventions</i></a> , <a href= +"../utilities/awk.html#"><i>awk</i></a></p> +<p class="tent">XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_09_21" id="tag_20_09_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_09_22" id="tag_20_09_22"></a>Issue 5</h4> +<blockquote> +<p>The FUTURE DIRECTIONS section is added.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_09_23" id="tag_20_09_23"></a>Issue 6</h4> +<blockquote> +<p>Updated to align with the IEEE P1003.2b draft standard, which included resolution of several interpretations of the +ISO POSIX-2:1993 standard.</p> +<p class="tent">The normative text is reworded to avoid use of the term "must" for application requirements.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_09_24" id="tag_20_09_24"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p class="tent">POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0066 [584] and XCU/TC2-2008/0067 [679] are applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_09_25" id="tag_20_09_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p class="tent">Austin Group Defect 1230 is applied, changing the EXTENDED DESCRIPTION section to specify that array parameters can +be passed as the last parameter to a function.</p> +<p class="tent">Austin Group Defect 1570 is applied, removing extra spacing in <tt>"=="</tt>.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/batch.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/bg.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/bg.html b/bdd/bg.html @@ -0,0 +1,242 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>bg</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/bc.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/c17.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="bg" id="bg"></a> <a name="tag_20_10" id="tag_20_10"></a><!-- bg --> +<h4 class="mansect"><a name="tag_20_10_01" id="tag_20_10_01"></a>NAME</h4> +<blockquote>bg — run jobs in the background</blockquote> +<h4 class="mansect"><a name="tag_20_10_02" id="tag_20_10_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> bg</tt> <b>[</b><i>job_id</i><tt>...</tt><b>]</b> <tt><img src="../images/opt-end.gif" alt= +"[Option End]" border="0"></tt></code></div> +</blockquote> +<h4 class="mansect"><a name="tag_20_10_03" id="tag_20_10_03"></a>DESCRIPTION</h4> +<blockquote> +<p>If job control is enabled (see the description of <a href="../utilities/V3_chap02.html#set"><i>set</i></a> <b>-m</b>), the shell +is interactive, and the current shell execution environment (see <a href="../utilities/V3_chap02.html#tag_19_13"><i>2.13 Shell +Execution Environment</i></a> ) is not a subshell environment, the <i>bg</i> utility shall resume suspended jobs from the current +shell execution environment by running them as background jobs, as described in <a href= +"../utilities/V3_chap02.html#tag_19_11"><i>2.11 Job Control</i></a> ; it may also do so if the shell is non-interactive or the +current shell execution environment is a subshell environment. If the job specified by <i>job_id</i> is already a running +background job, the <i>bg</i> utility shall have no effect and shall exit successfully.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_10_04" id="tag_20_10_04"></a>OPTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_10_05" id="tag_20_10_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>job_id</i></dt> +<dd>Specify the job to be resumed as a background job. If no <i>job_id</i> operand is given, the most recently suspended job shall +be used. The format of <i>job_id</i> is described in XBD <a href="../basedefs/V1_chap03.html#tag_03_182"><i>3.182 Job ID</i></a> +.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_10_06" id="tag_20_10_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_10_07" id="tag_20_10_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_10_08" id="tag_20_10_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>bg</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_10_09" id="tag_20_10_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_10_10" id="tag_20_10_10"></a>STDOUT</h4> +<blockquote> +<p>The output of <i>bg</i> shall consist of a line in the format:</p> +<pre> +<tt>"[%d] %s\n", <</tt><i>job-number</i><tt>>, <</tt><i>command</i><tt>> +</tt></pre> +<p>where the fields are as follows:</p> +<dl compact> +<dd></dd> +<dt><<i>job-number</i>></dt> +<dd>A number that can be used to identify the job to the <a href="../utilities/wait.html"><i>wait</i></a>, <a href= +"../utilities/fg.html"><i>fg</i></a>, and <a href="../utilities/kill.html"><i>kill</i></a> utilities. Using these utilities, the +job can be identified by prefixing the job number with <tt>'%'</tt>.</dd> +<dt><<i>command</i>></dt> +<dd>The associated command that was given to the shell.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_10_11" id="tag_20_10_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_10_12" id="tag_20_10_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_10_13" id="tag_20_10_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_10_14" id="tag_20_10_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_10_15" id="tag_20_10_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>If job control is disabled, the <i>bg</i> utility shall exit with an error and no job shall be placed in the background.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_10_16" id="tag_20_10_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>This utility is required to be intrinsic. See <a href="../utilities/V3_chap01.html#tag_18_07"><i>1.7 Intrinsic Utilities</i></a> +for details.</p> +<p>A job is generally suspended by typing the SUSP character (<control>-Z on most systems); see XBD <a href= +"../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> . At that point, <i>bg</i> can put the job into the +background. This is most effective when the job is expecting no terminal input and its output has been redirected to non-terminal +files. A background job can be forced to stop when it has terminal output by issuing the command:</p> +<pre> +<tt>stty tostop +</tt></pre> +<p>A background job can be stopped with the command:</p> +<pre> +<tt>kill -s stop </tt><i>job ID</i><tt> +</tt></pre> +<p>The <i>bg</i> utility does not work as expected when it is operating in its own utility execution environment because that +environment has no suspended jobs. In the following examples:</p> +<pre> +<tt>... | xargs bg +(bg) +</tt></pre> +<p>each <i>bg</i> operates in a different environment and does not share its parent shell's understanding of jobs. For this reason, +<i>bg</i> is generally implemented as a shell regular built-in.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_10_17" id="tag_20_10_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_10_18" id="tag_20_10_18"></a>RATIONALE</h4> +<blockquote> +<p>The extensions to the shell specified in this volume of POSIX.1-2024 have mostly been based on features provided by the +KornShell. The job control features provided by <i>bg</i>, <a href="../utilities/fg.html"><i>fg</i></a>, and <a href= +"../utilities/jobs.html"><i>jobs</i></a> are also based on the KornShell. The standard developers examined the characteristics of +the C shell versions of these utilities and found that differences exist. Despite widespread use of the C shell, the KornShell +versions were selected for this volume of POSIX.1-2024 to maintain a degree of uniformity with the rest of the KornShell features +selected (such as the very popular command line editing features).</p> +<p>The <i>bg</i> utility is expected to wrap its output if the output exceeds the number of display columns.</p> +<p>The <i>bg</i> and <a href="../utilities/fg.html"><i>fg</i></a> utilities are not symmetric as regards the list of process IDs +known in the current shell execution environment. Whereas <a href="../utilities/fg.html"><i>fg</i></a> removes a process ID from +this list, <i>bg</i> has no need to add one to this list when it resumes execution of a suspended job in the background, because +this has already been done by the shell when the suspended background job was created (see <a href= +"../utilities/V3_chap02.html#tag_19_11"><i>2.11 Job Control</i></a> ).</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_10_19" id="tag_20_10_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_10_20" id="tag_20_10_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19_09_03_02"><i>2.9.3.1 Asynchronous AND-OR Lists</i></a> , <a href= +"../utilities/fg.html#"><i>fg</i></a> , <a href="../utilities/kill.html#tag_20_64"><i>kill</i></a> , <a href= +"../utilities/jobs.html#"><i>jobs</i></a> , <a href="../utilities/wait.html#tag_20_147"><i>wait</i></a></p> +<p>XBD <a href="../basedefs/V1_chap03.html#tag_03_182"><i>3.182 Job ID</i></a> , <a href="../basedefs/V1_chap08.html#tag_08"><i>8. +Environment Variables</i></a> , <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_10_21" id="tag_20_10_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_10_22" id="tag_20_10_22"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +<p>The JC margin marker on the SYNOPSIS is removed since support for Job Control is mandatory in this version. This is a FIPS +requirement.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_10_23" id="tag_20_10_23"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_10_24" id="tag_20_10_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 854 is applied, adding a note to the APPLICATION USAGE section that this utility is required to be +intrinsic.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1254 is applied, updating the DESCRIPTION to account for the addition of <a href= +"../utilities/V3_chap02.html#tag_19_11"><i>2.11 Job Control</i></a> and adding a paragraph to RATIONALE.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/bc.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/c17.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/c17.html b/bdd/c17.html @@ -0,0 +1,1041 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>c17</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/bg.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/cal.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="c17" id="c17"></a> <a name="tag_20_11" id="tag_20_11"></a><!-- c17 --> +<h4 class="mansect"><a name="tag_20_11_01" id="tag_20_11_01"></a>NAME</h4> +<blockquote>c17 — compile standard C programs</blockquote> +<h4 class="mansect"><a name="tag_20_11_02" id="tag_20_11_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('CD')">CD</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> c17</tt> <b>[</b><i>options</i><tt>...</tt><b>]</b> <i>pathname</i> <b>[[</b><i>pathname</i><b>] +[</b><tt>-I</tt> <i>directory</i><b>]<br></b> <tt> </tt> <b>[</b><tt>-L</tt> +<i>directory</i><b>] [</b><tt>-l</tt> <i>library</i><b>] [</b><tt>-R</tt> <i>directory</i><b>]]</b><tt>... <img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div> +</blockquote> +<h4 class="mansect"><a name="tag_20_11_03" id="tag_20_11_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>c17</i> utility is an interface to the standard C compilation system; it shall accept source code written in the C +language as defined in section 6 of the ISO C standard. The system conceptually consists of a compilation phase, encompassing +Translation Phases 1 through 7 of the ISO C standard, and a linkage phase, for handling Phase 8 of the ISO C standard and +extensions described here. The reference to "library components" in Phase 8 shall be taken to refer to components of libraries +specified using the <b>-l</b> option, libraries specified as <i>file</i><b>.a</b> or <i>file</i><b>.so</b> operands, and the +equivalent of a <b>-l c</b> option passed to the link editor in the manner specified in the EXTENDED DESCRIPTION. In addition, the +compilation phase can be split into a separate preprocessing operation, handling Translation Phases 1 through 4, and a processing +operation, handling Phases 5 though 7. Whether a single utility or multiple utilities for handling phases separately is provided by +an implementation is left unspecified. The input files referenced by <i>pathname</i> operands and <b>-l</b> option-arguments shall +be compiled and linked to produce an executable file or, if the <b>-G</b> option is specified, a shared library file. It is +unspecified whether the linking of an executable file occurs entirely within the operation of <i>c17</i>; when a <i>pathname</i> +operand or <b>-l</b> option-argument names a shared library, an executable object may be produced that is not fully resolved until +the file is executed.</p> +<p>If the <b>-c</b> option is specified and the <b>-o</b> option is not specified, for all <i>pathname</i> operands of the form +<i>file</i><b>.c</b> or <i>file</i><b>.i</b>, the files:</p> +<pre> +<tt>$(basename </tt><i>pathname</i><tt> .c).o +</tt></pre> +<p>or</p> +<pre> +<tt>$(basename </tt><i>pathname</i><tt> .i).o +</tt></pre> +<p>respectively shall be created as the result of successful compilation. If the <b>-c</b> option is not specified, it is +unspecified whether such <b>.o</b> files are created or deleted for the <i>file</i><b>.c</b> and <i>file</i><b>.i</b> operands.</p> +<p>If there are no options that prevent link editing (such as <b>-c</b> or <b>-E</b>), and all input files compile and link without +error, the resulting executable file or shared library file shall be written according to the <b>-o</b> <i>outfile</i> option, if +present. If <b>-o</b> <i>outfile</i> is not specified, a resulting executable file shall be written to the file <b>a.out</b>; if +the file to be written is a shared library file, the behavior is unspecified.</p> +<p>Executable files shall be created as specified in <a href="../utilities/V3_chap01.html#tag_18_01_01_04"><i>1.1.1.4 File Read, +Write, and Creation</i></a> , except that the file permission bits shall be set to: S_IRWXO | S_IRWXG | S_IRWXU</p> +<p>and the bits specified by the <a href="../utilities/umask.html"><i>umask</i></a> of the process shall be cleared.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_11_04" id="tag_20_11_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>c17</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> , except that:</p> +<ul> +<li> +<p>Options can be interspersed with operands.</p> +</li> +<li> +<p>The order of specifying the <b>-L</b>, <b>-l</b>, and <b>-R</b> options, and the order of specifying <b>-l</b> options with +respect to <i>pathname</i> operands is significant.</p> +</li> +<li> +<p>Conforming applications shall specify each option separately; that is, grouping option letters (for example, <b>-cO</b>) need +not be recognized by all implementations.</p> +</li> +</ul> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-B </b><i>mode</i></dt> +<dd>If <i>mode</i> is <b>dynamic</b>, produce a dynamically linked executable file. If the <b>-B</b> option is present with +<b>-c</b>, <b>-E</b>, or <b>-G</b>, the result is unspecified.</dd> +<dt><b>-c</b></dt> +<dd>Suppress the link-edit phase of the compilation, and do not remove any object files that are produced. The application shall +ensure that all operands are of the form <i>file</i><b>.c</b> or <i>file</i><b>.i</b>.</dd> +<dt><b>-D </b><i>name</i><b>[=</b><i>value</i><b>]</b></dt> +<dd><br> +Define <i>name</i> as if by a C-language <b>#define</b> directive. If no =<i>value</i> is given, a value of 1 shall be used. The +<b>-D</b> option has lower precedence than the <b>-U</b> option. That is, if <i>name</i> is used in both a <b>-U</b> and a +<b>-D</b> option, <i>name</i> shall be undefined regardless of the order of the options. Additional implementation-defined +<i>name</i>s may be provided by the compiler. Implementations shall support at least 2048 bytes of <b>-D</b> definitions and 256 +<i>names</i>.</dd> +<dt><b>-E</b></dt> +<dd>Copy C-language source files to standard output, executing all preprocessor directives; no compilation shall be performed. If +any operand is not a text file, the effects are unspecified.</dd> +<dt><b>-G</b></dt> +<dd>Create a shared library or create object files suitable for inclusion in such a shared library. Compilations shall be performed +in a manner suitable for the creation of shared libraries (for example, by producing position-independent code). +<p>If <b>-c</b> is also specified, create object files suitable for inclusion in a shared library.</p> +<p>If <b>-c</b> is not specified, create a shared library. In this case the application shall ensure that the file named by the +<b>-o</b> <i>outfile</i> option-argument includes an element named <b>so</b> or an implementation-defined element denoting a shared +library, where elements in the last component of <i>outfile</i> are separated by <period> characters, for example +<b>libx.so.1</b>; if no <b>-o</b> option is included in the options or the file named by the <b>-o</b> <i>outfile</i> option does +not contain an element named <b>so</b> or an implementation-defined element denoting a shared library, the result is unspecified. +If a <i>pathname</i> operand or <b>-l</b> option-argument names a shared library and that shared library defines an object used by +the library being created, it shall become a dependency of the created shared library.</p> +<p>If the <b>-G</b> option is present with <b>-B</b> or <b>-E</b>, the result is unspecified.</p> +</dd> +<dt><b>-g</b></dt> +<dd>Produce symbolic information in the object or executable files; the nature of this information is unspecified, and may be +modified by implementation-defined interactions with other options.</dd> +<dt><b>-I </b><i>directory</i></dt> +<dd>Change the algorithm for searching for headers whose names are not absolute pathnames to look in the directory named by the +<i>directory</i> pathname before looking in the usual places. Thus, headers whose names are enclosed in double-quotes (<tt>""</tt>) +shall be searched for first in the directory of the file with the <b>#include</b> line, then in directories named in <b>-I</b> +options, and last in the usual places. For headers whose names are enclosed in angle brackets (<tt>"<>"</tt>), the header +shall be searched for only in directories named in <b>-I</b> options and then in the usual places. Directories named in <b>-I</b> +options shall be searched in the order specified. If the <b>-I</b> option is used to specify a directory that is one of the usual +places searched by default, the results are unspecified. Implementations shall support at least ten instances of this option in a +single <i>c17</i> command invocation.</dd> +<dt><b>-L </b><i>directory</i></dt> +<dd>Change the algorithm of searching for the libraries named in the <b>-l</b> objects to look in the directory named by the +<i>directory</i> pathname before looking in the usual places. Directories named in <b>-L</b> options shall be searched in the order +specified. If the <b>-L</b> option is used to specify a directory that is one of the usual places searched by default, the results +are unspecified. Implementations shall support at least ten instances of this option in a single <i>c17</i> command invocation. If +a directory specified by a <b>-L</b> option contains files with names starting with any of the strings <tt>"libc."</tt>, +<tt>"libl."</tt>, <tt>"libpthread."</tt>, <tt>"libm."</tt>, <tt>"librt."</tt>, <tt>"libxnet."</tt>, or <tt>"liby."</tt>, the +results are unspecified.</dd> +<dt><b>-l </b><i>library</i></dt> +<dd>Search the library named <b>lib<i>library</i>.a</b> or <b>lib<i>library</i>.so</b>. When searching for a library, the linker +shall look at each directory specified by <b>-L</b> options that appear on the command line before this <b>-l</b> option, in the +order given, and then the system default libraries. If <b>lib<i>library</i>.a</b> and <b>lib<i>library</i>.so</b> both exist in a +directory, <i>c17</i> shall use <b>lib<i>library</i>.so</b> if either <b>-B dynamic</b> or <b>-G</b> is specified. Once a library +has been found (shared or static) in a directory, later directories in the list shall not be considered. A library shall be +searched when its name is encountered, so the placement of a <b>-l</b> option is significant. Several standard libraries can be +specified in this manner, as described in the EXTENDED DESCRIPTION section. Implementations may recognize implementation-defined +suffixes other than <b>.a</b> and <b>.so</b> as denoting libraries.</dd> +<dt><b>-O </b><i>optlevel</i></dt> +<dd>Specify the level of code optimization. If the <i>optlevel</i> option-argument is the digit <tt>'0'</tt>, all special code +optimizations shall be disabled. If it is the digit <tt>'1'</tt>, the nature of the optimization is unspecified. If the <b>-O</b> +option is omitted, the nature of the system's default optimization is unspecified. It is unspecified whether code generated in the +presence of the <b>-O</b> 0 option is the same as that generated when <b>-O</b> is omitted. Other <i>optlevel</i> values may be +supported.</dd> +<dt><b>-o </b><i>outfile</i></dt> +<dd>Name the output file to be produced. If the <b>-o</b> option is present with <b>-E</b>, or with <b>-c</b> and more than one +input file, the result is unspecified. +<p>When creating a single object file (by using <b>-c</b> with a single input file), use the pathname <i>outfile</i>, instead of +the default <i>file</i><b>.o</b>, for the object file produced.</p> +<p>When creating an executable file, use the pathname <i>outfile</i>, instead of the default <b>a.out</b>, for the executable file +produced.</p> +<p>When creating a shared library, use the pathname <i>outfile</i> as the name of the shared library. If no <b>-o</b> +<i>outfile</i> option is specified when creating a shared library, the result is unspecified.</p> +</dd> +<dt><b>-s</b></dt> +<dd>Produce object or executable files, or both, from which symbolic and other information not required for proper execution using +the <i>exec</i> family defined in the System Interfaces volume of POSIX.1-2024 has been removed (stripped). If both <b>-g</b> and +<b>-s</b> options are present, the action taken is unspecified.</dd> +<dt><b>-R </b><i>directory</i></dt> +<dd>If the object file format supports it, specify a directory to be searched for shared libraries when an executable file or +shared library being created by <i>c17</i> is subsequently executed, or loaded using <a href= +"../functions/dlopen.html"><i>dlopen</i>()</a>. If <i>directory</i> contains any <colon> or <dollar-sign> characters, +the behavior is unspecified. If an implementation provides a means for setting a default load time search location or locations, +the <b>-R</b> option shall take precedence. +<p>The directory named by <i>directory</i> shall not be searched by a process performing dynamic loading if either of the following +are true:</p> +<ul> +<li> +<p>The real and effective user IDs of that process are different and the directory has write permission for a user ID outside the +set of the effective user ID of that process and any implementation-specific user IDs used for directories containing system +libraries.</p> +</li> +<li> +<p>The real and effective group IDs of that process are different and the directory has write permission for group IDs other than +the effective group ID of that process.</p> +</li> +</ul> +<p>Directories named in <b>-R</b> options shall be searched in the order specified, before the default system library locations are +searched.</p> +<p>If a directory specified by a <b>-R</b> option contains files with names starting with any of the strings <tt>"libc."</tt>, +<tt>"libl."</tt>, <tt>"libpthread."</tt>, <tt>"libm."</tt>, <tt>"librt."</tt>, <tt>"libxnet."</tt>, or <tt>"liby."</tt>, the result +is unspecified.</p> +<p>If the <b>-R</b> option is present with <b>-c</b> or <b>-E</b>, the result is unspecified.</p> +</dd> +<dt><b>-U </b><i>name</i></dt> +<dd>Remove any initial definition of <i>name</i>.</dd> +</dl> +<p>Multiple instances of the <b>-D</b>, <b>-I</b>, <b>-L</b>, <b>-l</b>, <b>-R</b>, and <b>-U</b> options can be specified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_11_05" id="tag_20_11_05"></a>OPERANDS</h4> +<blockquote> +<p>The application shall ensure that at least one <i>pathname</i> operand is specified. The following forms for <i>pathname</i> +operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file.</i><b>c</b></dt> +<dd>A C-language source file to be compiled and optionally linked.</dd> +<dt><i>file.</i><b>i</b></dt> +<dd>A text file containing the output of <i>c17</i> <b>-E</b>, to be compiled and optionally linked. The processing already +performed by <i>c17</i> <b>-E</b> when the file was produced shall not be repeated when the file is compiled.</dd> +<dt><i>file.</i><b>a</b></dt> +<dd>A library of static object files typically produced by the <a href="../utilities/ar.html"><i>ar</i></a> utility, and referenced +during the link-edit phase. Implementations may recognize implementation-defined suffixes other than <b>.a</b> as denoting static +object file libraries.</dd> +<dt><i>file.</i><b>so</b></dt> +<dd>A library of shared object files typically produced by the <i>c17</i> utility with the <b>-G</b> option, and referenced during +the link-edit phase. Implementations may recognize implementation-defined suffixes other than <b>.so</b> as denoting shared object +file libraries.</dd> +<dt><i>file.</i><b>o</b></dt> +<dd>An object file produced by <i>c17</i> <b>-c</b> and passed directly to the link editor. Implementations may recognize +implementation-defined suffixes other than <b>.o</b> as denoting object files.</dd> +</dl> +<p>The processing of other files is implementation-defined.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_11_06" id="tag_20_11_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_11_07" id="tag_20_11_07"></a>INPUT FILES</h4> +<blockquote> +<p>Each input file shall be one of the following:</p> +<ul> +<li> +<p>A text file containing a C-language source program or the output of <i>c17</i> <b>-E</b></p> +</li> +<li> +<p>An object file in the format produced by <i>c17</i> <b>-c</b></p> +</li> +<li> +<p>A library of object files in the format produced by archiving zero or more object files using <a href= +"../utilities/ar.html"><i>ar</i></a></p> +</li> +<li> +<p>A shared library in the format produced by <i>c17</i> <b>-G</b></p> +</li> +</ul> +<p>Implementations may supply additional utilities that produce files in these formats. Additional input file formats are +implementation-defined.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_11_08" id="tag_20_11_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>c17</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>TMPDIR</i></dt> +<dd>Provide a pathname that should override the default directory for temporary files, if any. <sup>[<a href= +"javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> On +XSI-conforming systems, provide a pathname that shall override the default directory for temporary files, if any. <img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_11_09" id="tag_20_11_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_11_10" id="tag_20_11_10"></a>STDOUT</h4> +<blockquote> +<p>If more than one <i>pathname</i> operand ending in <b>.c</b> or <b>.i</b> (or possibly other unspecified suffixes) is given, for +each such file:</p> +<pre> +<tt>"%s:\n", <</tt><i>pathname</i><tt>> +</tt></pre> +<p>may be written. These messages, if written, shall precede the processing of each input file; they shall not be written to the +standard output if they are written to the standard error, as described in the STDERR section.</p> +<p>If the <b>-E</b> option is specified, the standard output shall be a text file that represents the results of the preprocessing +stage of the language; it may contain extra information appropriate for subsequent compilation passes and shall contain at least +one line with the format:</p> +<pre> +<tt>"# %d \"%s\"\n", <</tt><i>line</i><tt>>, <</tt><i>pathname</i><tt>> +</tt></pre> +<p>for each file processed as a result of a <b>#include</b> directive, unless no other output generated from that file is present +in the output, where <i>line</i> is a line number and <i>pathname</i> is the pathname used to open the file.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_11_11" id="tag_20_11_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages, except that if more than one <i>pathname</i> operand ending in +<b>.c</b> or <b>.i</b> (or possibly other unspecified suffixes) is given, for each such file:</p> +<pre> +<tt>"%s:\n", <</tt><i>pathname</i><tt>> +</tt></pre> +<p>may be written to allow identification of the diagnostic and warning messages with the appropriate input file. These messages, +if written, shall precede the processing of each input file; they shall not be written to the standard error if they are written to +the standard output, as described in the STDOUT section.</p> +<p>This utility may produce warning messages about certain conditions that do not warrant returning an error (non-zero) exit +value.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_11_12" id="tag_20_11_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>Object files or executable files or both are produced in unspecified formats. If the pathname of an object file or executable +file to be created by <i>c17</i> resolves to an existing directory entry for a file that is not a regular file, it is unspecified +whether <i>c17</i> shall attempt to create the file or shall issue a diagnostic and exit with a non-zero exit status.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_11_13" id="tag_20_11_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<h5><a name="tag_20_11_13_01" id="tag_20_11_13_01"></a>Standard Libraries</h5> +<p>The <i>c17</i> utility shall recognize the following <b>-l</b> options for standard libraries:</p> +<dl compact> +<dd></dd> +<dt><b>-l c</b></dt> +<dd>This option shall make available all interfaces referenced in the System Interfaces volume of POSIX.1-2024, with the possible +exception of those interfaces listed as residing in <a href="../basedefs/aio.h.html"><i><aio.h></i></a>, <a href= +"../basedefs/arpa_inet.h.html"><i><arpa/inet.h></i></a>, <a href="../basedefs/complex.h.html"><i><complex.h></i></a>, +<a href="../basedefs/fenv.h.html"><i><fenv.h></i></a>, <a href="../basedefs/math.h.html"><i><math.h></i></a>, <a href= +"../basedefs/mqueue.h.html"><i><mqueue.h></i></a>, <a href="../basedefs/netdb.h.html"><i><netdb.h></i></a>, <a href= +"../basedefs/net_if.h.html"><i><net/if.h></i></a>, <a href="../basedefs/netinet_in.h.html"><i><netinet/in.h></i></a>, +<a href="../basedefs/pthread.h.html"><i><pthread.h></i></a>, <a href="../basedefs/sched.h.html"><i><sched.h></i></a>, +<a href="../basedefs/semaphore.h.html"><i><semaphore.h></i></a>, <a href= +"../basedefs/spawn.h.html"><i><spawn.h></i></a>, <a href="../basedefs/sys_socket.h.html"><i><sys/socket.h></i></a>, +<a href="../basedefs/threads.h.html"><i><threads.h></i></a>, <a href= +"../functions/pthread_kill.html"><i>pthread_kill</i>()</a> and <a href= +"../functions/pthread_sigmask.html"><i>pthread_sigmask</i>()</a> in <a href= +"../basedefs/signal.h.html"><i><signal.h></i></a>, interfaces marked as optional in <a href= +"../basedefs/sys_mman.h.html"><i><sys/mman.h></i></a>, interfaces marked as ADV (Advisory Information) in <a href= +"../basedefs/fcntl.h.html"><i><fcntl.h></i></a>, and interfaces beginning with the prefix clock_ or timer_ in <a href= +"../basedefs/time.h.html"><i><time.h></i></a>. This option shall not be required to be present to cause a search of this +library.</dd> +<dt><b>-l l</b></dt> +<dd>This option shall make available all interfaces required by the C-language output of <a href= +"../utilities/lex.html"><i>lex</i></a> that are not made available through the <b>-l c</b> option.</dd> +<dt><b>-l pthread</b></dt> +<dd>This option shall make available all interfaces referenced in <a href="../basedefs/pthread.h.html"><i><pthread.h></i></a> +and <a href="../basedefs/threads.h.html"><i><threads.h></i></a>, and also <a href= +"../functions/pthread_kill.html"><i>pthread_kill</i>()</a> and <a href= +"../functions/pthread_sigmask.html"><i>pthread_sigmask</i>()</a> referenced in <a href= +"../basedefs/signal.h.html"><i><signal.h></i></a>. An implementation may search this library in the absence of this +option.</dd> +<dt><b>-l m</b></dt> +<dd>This option shall make available all interfaces referenced in <a href="../basedefs/math.h.html"><i><math.h></i></a>, +<a href="../basedefs/complex.h.html"><i><complex.h></i></a>, and <a href="../basedefs/fenv.h.html"><i><fenv.h></i></a>. +An implementation may search this library in the absence of this option.</dd> +<dt><b>-l rt</b></dt> +<dd>This option shall make available all interfaces referenced in <a href="../basedefs/aio.h.html"><i><aio.h></i></a>, +<a href="../basedefs/mqueue.h.html"><i><mqueue.h></i></a>, <a href="../basedefs/sched.h.html"><i><sched.h></i></a>, +<a href="../basedefs/semaphore.h.html"><i><semaphore.h></i></a>, and <a href= +"../basedefs/spawn.h.html"><i><spawn.h></i></a>, interfaces marked as optional in <a href= +"../basedefs/sys_mman.h.html"><i><sys/mman.h></i></a>, interfaces marked as ADV (Advisory Information) in <a href= +"../basedefs/fcntl.h.html"><i><fcntl.h></i></a>, and interfaces beginning with the prefix clock_ and timer_ in <a href= +"../basedefs/time.h.html"><i><time.h></i></a>. An implementation may search this library in the absence of this option.</dd> +<dt><b>-l xnet</b></dt> +<dd>This option shall make available all interfaces referenced in <a href= +"../basedefs/arpa_inet.h.html"><i><arpa/inet.h></i></a>, <a href="../basedefs/netdb.h.html"><i><netdb.h></i></a>, +<a href="../basedefs/net_if.h.html"><i><net/if.h></i></a>, <a href= +"../basedefs/netinet_in.h.html"><i><netinet/in.h></i></a>, and <a href= +"../basedefs/sys_socket.h.html"><i><sys/socket.h></i></a>. An implementation may search this library in the absence of this +option.</dd> +<dt><b>-l y</b></dt> +<dd>This option shall make available all interfaces required by the C-language output of <a href= +"../utilities/yacc.html"><i>yacc</i></a> that are not made available through the <b>-l c</b> option.</dd> +</dl> +<p>In the absence of options that inhibit invocation of the link editor, such as <b>-c</b> or <b>-E</b>, the <i>c17</i> utility +shall cause the equivalent of a <b>-l c</b> option to be passed to the link editor after the last <i>pathname</i> operand or +<b>-l</b> option, causing it to be searched after all other object files and libraries are loaded.</p> +<p>The libraries <b>c</b>, <b>l</b>, <b>m</b>, <b>pthread</b>, <b>rt</b>, <b>xnet</b>, and <b>y</b> shall be found as shared +libraries when specified as the option-argument to the <b>-l</b> option and may also be found as static libraries but, except for +the shared library version of the <b>c</b> library, need not exist as regular files. The implementation may accept as <b>-l</b> +option-arguments names of additional implementation-defined libraries that do not exist as regular files.</p> +<h5><a name="tag_20_11_13_02" id="tag_20_11_13_02"></a>External Symbols</h5> +<p>The C compiler and link editor shall support the significance of external symbols up to a length of at least 31 bytes; the +action taken upon encountering symbols exceeding the implementation-defined maximum symbol length is unspecified.</p> +<p>The compiler and link editor shall support a minimum of 4095 external identifiers in one translation unit. A diagnostic message +shall be written to the standard output if the implementation-defined limit is exceeded; other actions are unspecified.</p> +<h5><a name="tag_20_11_13_03" id="tag_20_11_13_03"></a>Header Search</h5> +<p>If a file with the same name as one of the standard headers defined in XBD <a href="../basedefs/V1_chap14.html#tag_14"><i>14. +Headers</i></a> , not provided as part of the implementation, is placed in any of the usual places that are searched by default for +headers, the results are unspecified.</p> +<h5><a name="tag_20_11_13_04" id="tag_20_11_13_04"></a>Programming Environments</h5> +<p>All implementations shall support one of the following programming environments as a default. Implementations may support more +than one of the following programming environments. Applications can use the _POSIX_V<i>n</i>_ILP* and _POSIX_V<i>n</i>_LP* +constants in <a href="../basedefs/unistd.h.html"><i><unistd.h></i></a>, and corresponding <a href= +"../functions/sysconf.html"><i>sysconf</i>()</a> and <a href="../utilities/getconf.html"><i>getconf</i></a> calls, to determine +which programming environments are supported.<br></p> +<p class="caption"><a name="tagtcjh_16" id="tagtcjh_16"></a> Table: Programming Environments: Type Sizes</p> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Programming Environment <i>getconf</i> Name</b></p> +</th> +<th align="center"> +<p class="tent"><b>Bits in int</b></p> +</th> +<th align="center"> +<p class="tent"><b>Bits in long</b></p> +</th> +<th align="center"> +<p class="tent"><b>Bits in all pointer types</b></p> +</th> +<th align="center"> +<p class="tent"><b>Bits in off_t</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">_POSIX_V8_ILP32_OFF32</p> +</td> +<td align="left"> +<p class="tent">32</p> +</td> +<td align="left"> +<p class="tent">32</p> +</td> +<td align="left"> +<p class="tent">32</p> +</td> +<td align="left"> +<p class="tent">32</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">_POSIX_V8_ILP32_OFFBIG</p> +</td> +<td align="left"> +<p class="tent">32</p> +</td> +<td align="left"> +<p class="tent">32</p> +</td> +<td align="left"> +<p class="tent">32</p> +</td> +<td align="left"> +<p class="tent">>=64</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">_POSIX_V8_LP64_OFF64</p> +</td> +<td align="left"> +<p class="tent">32</p> +</td> +<td align="left"> +<p class="tent">64</p> +</td> +<td align="left"> +<p class="tent">64</p> +</td> +<td align="left"> +<p class="tent">64</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">_POSIX_V8_LPBIG_OFFBIG</p> +</td> +<td align="left"> +<p class="tent">>=32</p> +</td> +<td align="left"> +<p class="tent">>=64</p> +</td> +<td align="left"> +<p class="tent">>=64</p> +</td> +<td align="left"> +<p class="tent">>=64</p> +</td> +</tr> +</table> +</center> +<p class="tent">All implementations shall support one or more environments where the widths of the following types are no greater +than the width of type <b>long</b>:</p> +<center> +<table cellpadding="3" align="center"> +<tr valign="top"> +<td align="left"> +<p class="tent"><b><br> +blksize_t<br> +cc_t<br> +mode_t<br> +nfds_t<br> +pid_t<br></b></p> +</td> +<td align="left"> +<p class="tent"><b><br> +ptrdiff_t<br> +size_t<br> +speed_t<br> +ssize_t<br> +suseconds_t<br></b></p> +</td> +<td align="left"> +<p class="tent"><b><br> +tcflag_t<br> +wchar_t<br> +wint_t<br></b></p> +</td> +</tr> +</table> +</center> +<p class="tent">The executable files created when these environments are selected shall be in a proper format for execution by the +<i>exec</i> family of functions. Each environment may be one of the ones in <a href="#tagtcjh_16">Programming Environments: Type +Sizes</a> , or it may be another environment. The names for the environments that meet this requirement shall be output by a +<a href="../utilities/getconf.html"><i>getconf</i></a> command using the POSIX_V8_WIDTH_RESTRICTED_ENVS argument, as a +<newline>-separated list of names suitable for use with the <a href="../utilities/getconf.html"><i>getconf</i></a> <b>-v</b> +option. If more than one environment meets the requirement, the names of all such environments shall be output on separate lines. +Any of these names can then be used in a subsequent <a href="../utilities/getconf.html"><i>getconf</i></a> command to obtain the +flags specific to that environment with the following suffixes added as appropriate:</p> +<dl compact> +<dd></dd> +<dt>_CFLAGS</dt> +<dd>To get the C compiler flags.</dd> +<dt>_LDFLAGS</dt> +<dd>To get the linker/loader flags.</dd> +<dt>_LIBS</dt> +<dd>To get the libraries.</dd> +</dl> +<p class="tent">This requirement may be removed in a future version.</p> +<p class="tent">When this utility processes a file containing a function called <i>main</i>(), it shall be defined with a return +type equivalent to <b>int</b>. Using return from the initial call to <i>main</i>() shall be equivalent (other than with respect to +language scope issues) to calling <a href="../functions/exit.html"><i>exit</i>()</a> with the returned value. Reaching the end of +the initial call to <i>main</i>() shall be equivalent to calling <i>exit</i>(0). The implementation shall not declare a prototype +for this function.</p> +<p class="tent">Implementations provide configuration strings for C compiler flags, linker/loader flags, and libraries for each +supported environment. When an application needs to use a specific programming environment rather than the implementation default +programming environment while compiling, the application shall first verify that the implementation supports the desired +environment. If the desired programming environment is supported, the application shall then invoke <i>c17</i> with the appropriate +C compiler flags as the first options for the compile, the appropriate linker/loader flags after any other options except <b>-l</b> +but before any operands or <b>-l</b> options, and the appropriate libraries at the end of the operands and <b>-l</b> options.</p> +<p class="tent">Conforming applications shall not attempt to link together object files compiled for different programming models. +Applications shall also be aware that binary data placed in shared memory or in files might not be recognized by applications built +for other programming models.<br></p> +<p class="caption">Table: Programming Environments: <i>c17</i> Arguments</p> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Programming Environment <i>getconf</i> Name</b></p> +</th> +<th align="center"> +<p class="tent"><b>Use</b></p> +</th> +<th align="center"> +<p class="tent"><b><i>c17</i> Arguments <i>getconf</i> Name</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">_POSIX_V8_ILP32_OFF32</p> +</td> +<td align="left"> +<p class="tent">C Compiler Flags</p> +</td> +<td align="left"> +<p class="tent">POSIX_V8_ILP32_OFF32_CFLAGS</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">Linker/Loader Flags</p> +</td> +<td align="left"> +<p class="tent">POSIX_V8_ILP32_OFF32_LDFLAGS</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">Libraries</p> +</td> +<td align="left"> +<p class="tent">POSIX_V8_ILP32_OFF32_LIBS</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">_POSIX_V8_ILP32_OFFBIG</p> +</td> +<td align="left"> +<p class="tent">C Compiler Flags</p> +</td> +<td align="left"> +<p class="tent">POSIX_V8_ILP32_OFFBIG_CFLAGS</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">Linker/Loader Flags</p> +</td> +<td align="left"> +<p class="tent">POSIX_V8_ILP32_OFFBIG_LDFLAGS</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">Libraries</p> +</td> +<td align="left"> +<p class="tent">POSIX_V8_ILP32_OFFBIG_LIBS</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">_POSIX_V8_LP64_OFF64</p> +</td> +<td align="left"> +<p class="tent">C Compiler Flags</p> +</td> +<td align="left"> +<p class="tent">POSIX_V8_LP64_OFF64_CFLAGS</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">Linker/Loader Flags</p> +</td> +<td align="left"> +<p class="tent">POSIX_V8_LP64_OFF64_LDFLAGS</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">Libraries</p> +</td> +<td align="left"> +<p class="tent">POSIX_V8_LP64_OFF64_LIBS</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">_POSIX_V8_LPBIG_OFFBIG</p> +</td> +<td align="left"> +<p class="tent">C Compiler Flags</p> +</td> +<td align="left"> +<p class="tent">POSIX_V8_LPBIG_OFFBIG_CFLAGS</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">Linker/Loader Flags</p> +</td> +<td align="left"> +<p class="tent">POSIX_V8_LPBIG_OFFBIG_LDFLAGS</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">Libraries</p> +</td> +<td align="left"> +<p class="tent">POSIX_V8_LPBIG_OFFBIG_LIBS</p> +</td> +</tr> +</table> +</center> +<p class="tent">In addition to the type size programming environments above, all implementations also support a multi-threaded +programming environment that is orthogonal to all of the programming environments listed above. The <a href= +"../utilities/getconf.html"><i>getconf</i></a> utility can be used to get flags for the threaded programming environment, as +indicated in <a href="#tagtcjh_16">Programming Environments: Type Sizes</a> .</p> +<p class="caption">Table: Threaded Programming Environment: <i>c17</i> Arguments</p> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Programming Environment <i>getconf</i> Name</b></p> +</th> +<th align="center"> +<p class="tent"><b>Use</b></p> +</th> +<th align="center"> +<p class="tent"><b><i>c17</i> Arguments <i>getconf</i> Name</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">_POSIX_THREADS</p> +</td> +<td align="left"> +<p class="tent">C Compiler Flags</p> +</td> +<td align="left"> +<p class="tent">POSIX_V8_THREADS_CFLAGS</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">Linker/Loader Flags</p> +</td> +<td align="left"> +<p class="tent">POSIX_V8_THREADS_LDFLAGS</p> +</td> +</tr> +</table> +</center> +<p class="tent">These programming environment flags may be used in conjunction with any of the type size programming environments +supported by the implementation.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_11_14" id="tag_20_11_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful compilation or link edit.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_11_15" id="tag_20_11_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>When <i>c17</i> encounters a compilation error that causes an object file not to be created, it shall write a diagnostic to +standard error and continue to compile other source code operands, but it shall not perform the link phase and it shall return a +non-zero exit status. If the link edit is unsuccessful, a diagnostic message shall be written to standard error and <i>c17</i> +exits with a non-zero status. A conforming application shall rely on the exit status of <i>c17</i>, rather than on the existence or +mode of the executable file.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_11_16" id="tag_20_11_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Since the <i>c17</i> utility usually creates files in the current directory during the compilation process, it is typically +necessary to run the <i>c17</i> utility in a directory in which a file can be created.</p> +<p class="tent">On systems providing POSIX Conformance (see XBD <a href="../basedefs/V1_chap02.html#tag_02"><i>2. +Conformance</i></a> ), <i>c17</i> is required only with the C-Language Development option; XSI-conformant systems always provide +<i>c17</i>.</p> +<p class="tent">Since this standard requires that conforming applications define either _POSIX_C_SOURCE or _XOPEN_SOURCE before +inclusion of any header (see XSH <a href="../functions/V2_chap02.html#tag_16_02_01"><i>2.2.1 POSIX.1 Symbols</i></a> ), if +<i>c17</i> is used to compile source code that includes a header without defining one of these feature test macros in the required +manner, the behavior of <i>c17</i> itself and the results of using any files it generates are undefined. When <i>c17</i> is used +this way, implementations are encouraged to make visible in headers from the ISO C standard only the symbols that are allowed +by that standard, and otherwise to behave the same as if _POSIX_C_SOURCE or _XOPEN_SOURCE had been defined, but portable +applications cannot rely on this.</p> +<p class="tent">Some historical implementations have created <b>.o</b> files when <b>-c</b> is not specified and more than one +source file is given. Since this area is left unspecified, the application cannot rely on <b>.o</b> files being created, but it +also must be prepared for any related <b>.o</b> files that already exist being deleted at the completion of the link edit.</p> +<p class="tent">There is the possible implication that if a user supplies versions of the standard functions (before they would be +encountered by an implicit <b>-l c</b> or explicit <b>-l m</b>), that those versions would be used in place of the +standard versions. There are various reasons this might not be true (functions defined as macros, manipulations for clean name +space, and so on), so the existence of files named in the same manner as the standard libraries within the <b>-L</b> directories is +explicitly stated to produce unspecified behavior.</p> +<p class="tent">All of the functions specified in the System Interfaces volume of POSIX.1-2024 may be made visible by +implementations when the Standard C Library is searched. Conforming applications must explicitly request searching the other +standard libraries when functions made visible by those libraries are used.</p> +<p class="tent">In the ISO C standard the mapping from physical source characters to the C source character set is +implementation-defined. Implementations may strip white-space characters before the terminating <newline> of a (physical) +line as part of this mapping and, as a consequence of this, one or more white-space characters (and no other characters) between a +<backslash> character and the <newline> character that terminates the line produces implementation-defined results. +Portable applications should not use such constructs.</p> +<p class="tent">Some <i>c17</i> compilers not conforming to POSIX.1-2024 do not support trigraphs by default.</p> +<p class="tent">Implementations may support multiple programming environments with some of them conforming to this standard and +some not conforming. The _POSIX_V<i>n</i>_ILP* and _POSIX_V<i>n</i>_LP* constants in <a href= +"../basedefs/unistd.h.html"><i><unistd.h></i></a>, and corresponding <a href="../functions/sysconf.html"><i>sysconf</i>()</a> +and <a href="../utilities/getconf.html"><i>getconf</i></a> calls, only indicate whether each programming environment is supported; +they do not indicate anything about conformance of the environments that are supported. For example, an implementation may support +the ILP32_OFF32 environment for legacy reasons with a 32-bit <b>time_t</b>, whereas in a conforming environment <b>time_t</b> is +required to have a width of at least 64 bits. Application writers should consult an implementation's POSIX Conformance Document for +information about the conformance of each supported programming environment.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_11_17" id="tag_20_11_17"></a>EXAMPLES</h4> +<blockquote> +<ol> +<li class="tent">The following usage example compiles <b>foo.c</b> and creates the executable file <b>foo</b>: +<pre> +<tt>c17 -o foo foo.c +</tt></pre> +<p class="tent">The following usage example compiles <b>foo.c</b> and creates the object file <b>foo.o</b>:</p> +<pre> +<tt>c17 -c foo.c +</tt></pre> +<p class="tent">The following usage example compiles <b>foo.c</b> and creates the executable file <b>a.out</b>:</p> +<pre> +<tt>c17 foo.c +</tt></pre> +<p class="tent">The following usage example compiles <b>foo.c</b>, links it with <b>bar.o</b>, and creates the executable file +<b>a.out</b>. It may also create and leave <b>foo.o</b>:</p> +<pre> +<tt>c17 foo.c bar.o +</tt></pre> +<p class="tent">The following usage example preprocesses <b>foo.c</b> and <b>bar.c</b> to create <b>foo.i</b> and <b>bar.i</b>, +compiles <b>foo.i</b> and <b>bar.i</b> to create <b>foo.o</b> and <b>bar.o</b>, then links <b>foo.o</b> and <b>bar.o</b> to create +the executable file <b>foobar</b>. Each <i>c17</i> execution would ideally be invoked from a separate rule in a makefile (see +<a href="../utilities/make.html#"><i>make</i></a> ) with suitable dependencies so that each is only executed when it needs to +be:</p> +<pre> +<tt>c17 -E foo.c > foo.i +c17 -E bar.c > bar.i +c17 -c foo.i +c17 -c bar.i +c17 -o foobar foo.o bar.o +</tt></pre></li> +<li class="tent">The following example shows how an application using threads interfaces can test for support of and use a +programming environment supporting 32-bit <b>int</b>, <b>long</b>, and all pointer types, and an <b>off_t</b> type using at least +64 bits: +<pre> +<tt>offbig_env=$(getconf _POSIX_V8_ILP32_OFFBIG) +if [ $offbig_env != "-1" ] && [ $offbig_env != "undefined" ] +then + c17 $(getconf POSIX_V8_ILP32_OFFBIG_CFLAGS) \ + $(getconf POSIX_V8_THREADS_CFLAGS) -D_XOPEN_SOURCE=800 \ + $(getconf POSIX_V8_ILP32_OFFBIG_LDFLAGS) \ + $(getconf POSIX_V8_THREADS_LDFLAGS) foo.c -o foo \ + $(getconf POSIX_V8_ILP32_OFFBIG_LIBS) \ + -l pthread +else + echo ILP32_OFFBIG programming environment not supported + exit 1 +fi +</tt></pre></li> +<li class="tent">The following examples clarify the use and interactions of <b>-L</b> and <b>-l</b> options. +<p class="tent">Consider the case in which module <b>a.c</b> calls function <i>f</i>() in library <b>libQ.a</b>, and module +<b>b.c</b> calls function <i>g</i>() in library <b>libp.a</b>. Assume that both libraries reside in <b>/a/b/c</b>. The command line +to compile and link in the desired way is:</p> +<pre> +<tt>c17 -L /a/b/c main.o a.c -l Q b.c -l p +</tt></pre> +<p class="tent">In this case the <b>-L</b> option need only precede the first <b>-l</b> option, since both <b>libQ.a</b> and +<b>libp.a</b> reside in the same directory.</p> +<p class="tent">Multiple <b>-L</b> options can be used when library name collisions occur. Building on the previous example, +suppose that the user wants to use a new <b>libp.a</b>, in <b>/a/a/a</b>, but still wants <i>f</i>() from <b>/a/b/c/libQ.a</b>:</p> +<pre> +<tt>c17 -L /a/a/a -L /a/b/c main.o a.c -l Q b.c -l p +</tt></pre> +<p class="tent">In this example, the linker searches the <b>-L</b> options in the order specified, and finds <b>/a/a/a/libp.a</b> +before <b>/a/b/c/libp.a</b> when resolving references for <b>b.c</b>. The order of the <b>-l</b> options is still important, +however.</p> +</li> +<li class="tent">The following example shows how an application can use a programming environment where the widths of the following +types: <b>blksize_t</b>, <b>cc_t</b>, <b>mode_t</b>, <b>nfds_t</b>, <b>pid_t</b>, <b>ptrdiff_t</b>, <b>size_t</b>, <b>speed_t</b>, +<b>ssize_t</b>, <b>suseconds_t</b>, <b>tcflag_t</b>, <b>wchar_t</b>, <b>wint_t</b> +<p class="tent">are no greater than the width of type <b>long</b>:</p> +<pre> +<tt># First choose one of the listed environments ... +<br class="tent"> +# ... if there are no additional constraints, the first one will do: +CENV=$(getconf POSIX_V8_WIDTH_RESTRICTED_ENVS | head -n l) +<br class="tent"> +# ... or, if an environment that supports large files is preferred, +# look for names that contain "OFF64" or "OFFBIG". (This chooses +# the last one in the list if none match.) +for CENV in $(getconf POSIX_V8_WIDTH_RESTRICTED_ENVS) +do + case $CENV in + *OFF64*|*OFFBIG*) break ;; + esac +done +<br class="tent"> +# The chosen environment name can now be used like this: +<br class="tent"> +c17 $(getconf ${CENV}_CFLAGS) -D _POSIX_C_SOURCE=202405L \ +$(getconf ${CENV}_LDFLAGS) foo.c -o foo \ +$(getconf ${CENV}_LIBS) +</tt></pre></li> +<li class="tent">The following example shows how to create a shared library that does not depend on any other shared library: +<pre> +<tt>c17 -G -c foo.c bar.c +c17 -G -o foobar.so foo.o bar.o +</tt></pre></li> +<li class="tent">The following example shows how to create a dynamic executable that loads application specific shared libraries by +searching a specified list of directories when it is executed: +<pre> +<tt>c17 -G -c foo.c +c17 -G -o /path/to/dir1/foo.so foo.o +c17 -G -c bar.c +c17 -G -o /path/to/dir2/bar.so bar.o +c17 -B dynamic -L /path/to/dir1 -L /path/to/dir2 -R /path/to/dir1 \ + -R /path/to/dir2 -o foobar foobar.c -l foo -l bar +</tt></pre></li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_11_18" id="tag_20_11_18"></a>RATIONALE</h4> +<blockquote> +<p>The <i>c17</i> utility is based on the <i>c89</i> utility originally introduced in the ISO POSIX-2:1993 standard.</p> +<p class="tent">Some of the changes from <i>c89</i> include the ability to intersperse options and operands (which many <i>c89</i> +implementations allowed despite it not being specified), the description of <b>-l</b> as an option instead of an operand, and the +modification to the contents of the Standard Libraries section to account for new headers and options; for example, <a href= +"../basedefs/spawn.h.html"><i><spawn.h></i></a> added to the description of <b>-l rt</b>.</p> +<p class="tent">POSIX.1-2024 specifies that the <i>c17</i> utility must be able to use regular files for <b>*.o</b> files and for +<b>a.out</b> files. Implementations are free to overwrite existing files of other types when attempting to create object files and +executable files, but are not required to do so. If something other than a regular file is specified and using it fails for any +reason, <i>c17</i> is required to issue a diagnostic message and exit with a non-zero exit status. But for some file types, the +problem may not be noticed for a long time. For example, if a FIFO named <b>a.out</b> exists in the current directory, <i>c17</i> +may attempt to open <b>a.out</b> and will hang in the <a href="../functions/open.html"><i>open</i>()</a> call until another process +opens the FIFO for reading. Then <i>c17</i> may write most of the <b>a.out</b> to the FIFO and fail when it tries to seek back +close to the start of the file to insert a timestamp (FIFOs are not seekable files). The <i>c17</i> utility is also allowed to +issue a diagnostic immediately if it encounters an <b>a.out</b> or <b>*.o</b> file that is not a regular file. For portable use, +applications should ensure that any <b>a.out</b>, <b>-o</b> option-argument, or <b>*.o</b> files corresponding to any <b>*.c</b> +files do not conflict with names already in use that are not regular files or symbolic links that point to regular files.</p> +<p class="tent">Commands of the form <tt>c17 -c -o ...</tt> are frequently used to directly place the <b>.o</b> file into an +alternative directory without a need to separately rename the output file. This helps to support concurrent compilations and out of +tree builds.</p> +<p class="tent">Some implementations allow <b>-c</b> <b>-o</b> <i>directory</i> to produce +<i>directory</i><b>/</b><i>file</i><b>.o</b> even when there is more than one input file; however, portable applications using +<b>-c</b> with <b>-o</b> must compile only one file at a time and must specify the final destination filename rather than a +directory.</p> +<p class="tent">The shared library version of the <b>c</b> library is required to exist as a regular file because the dynamic +linker needs to be able to load at least one library at execution time. Other standard shared libraries need not exist in their own +right if the interfaces the standard requires them to provide exist in the <b>c</b> library; all that is required is that they are +"found" when specified as <b>-l</b> option-arguments. Static versions of the standard libraries need not exist as regular files, +even if they are found as static libraries when specified as <b>-l</b> option-arguments.</p> +<p class="tent">On many systems, multi-threaded applications run in a programming environment that is distinct from that used by +single-threaded applications. This multi-threaded programming environment (in addition to needing to specify <b>-l pthread</b> at +link time) may require additional flags to be set when headers are processed at compile time (<b>-D_REENTRANT</b> being common). +This programming environment is orthogonal to the type size programming environments discussed above and listed in <a href= +"#tagtcjh_16">Programming Environments: Type Sizes</a> . This version of the standard adds <a href= +"../utilities/getconf.html"><i>getconf</i></a> utility calls to provide the C compiler flags and linker/loader flags needed to +support multi-threaded applications. Note that on a system where single-threaded applications are a special case of a +multi-threaded application, both of these <a href="../utilities/getconf.html"><i>getconf</i></a> calls may return NULL strings; on +other implementations both of these strings may be non-NULL strings.</p> +<p class="tent">The C standardization committee invented trigraphs (e.g., <tt>"??!"</tt> to represent <tt>'|'</tt>) to address +character portability problems in development environments based on national variants of the 7-bit ISO/IEC 646:1991 standard +character set. However, these environments were already obsolete by the time the first ISO C standard was published, and in +practice trigraphs have not been used for their intended purpose, and usually are intended to have their original meaning in +K&R C. For example, in practice a C-language source string like <tt>"What??!"</tt> is usually intended to end in two +<question-mark> characters and an <exclamation-mark>, not in <tt>'|'</tt>.</p> +<p class="tent">When the <b>-E</b> option is used, execution of some <b>#pragma</b> preprocessor directives may simply result in a +copy of the directive being included in the output as part of the allowed extra information used by subsequent compilation passes +(see STDOUT).</p> +<p class="tent">This standard requires that, when <b>-E</b> is used, lines beginning with <tt>'#'</tt> are output identifying the +files processed as a result of <b>#include</b> directives in order that <i>c17</i> <b>-E</b> can be used to generate makefile +dependencies. See <a href="../utilities/make.html#"><i>make</i></a> . Usually such lines are output each time the origin of the +subsequent lines in the output changes, and the line number after the <tt>'#'</tt> is the line number in the named file of the line +from which the next line in the output was derived.</p> +<p class="tent">When the <b>-R</b> option is not included when an executable file or shared library is being created, some +implementations use the environment variables <i>LD_RUN_PATH</i> and <i>LD_LIBRARY_PATH</i> to determine the directories to be +searched for shared libraries.</p> +<p class="tent">Some implementations permit place-holders preceded by a <dollar-sign> character (<tt>'$'</tt>), such as +$ORIGIN, in the <b>-R</b> directory option-argument to be evaluated at load time. Some implementations accept a colon separated +list of directories for the path to search for shared libraries, with the same effect as specifying the <b>-R</b> option multiple +times. However, these features are not universal.</p> +<p class="tent">The name of a shared library usually contains an element named <b>so</b>. Other implementation-defined elements are +allowed for backwards compatibility with historical systems, and so that tools can be developed on conforming systems to create +libraries for multiple environments. For example, Microsoft systems use the filename extension <b>.dll</b> (and do not allow +following text) to denote a shared library. The standard allows additional characters to be used in the name of a library following +an <b>so</b> element to permit shared library versioning information to be at the end of the library filename rather than requiring +that any such strings appear before the final element of the library name.</p> +<p class="tent">The decision to standardize on <b>so</b> as a required element in a shared library name was intentional, as the +alternative would have been standardizing things such as a new make macro $(SHLIB_EXT) that would otherwise be needed to write a +portable makefile that can compile shared libraries despite not having a standardized element name.</p> +<p class="tent">If a combination of direct and indirect dependencies of a shared library would require different versions of +another shared library, options that are not specified by the standard (such as <b>-B direct</b>) will probably need to be used +when linking that shared library, so that at runtime the intended versions are found.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_11_19" id="tag_20_11_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +<p class="tent">If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of +a <newline> character, implementations are encouraged to treat this as an error. A future version of this standard may +require implementations to treat this as an error.</p> +<p class="tent">Unlike all of the other non-OB-shaded utilities in this standard, a utility by this name probably will not appear +in the next version of this standard. This utility's name is tied to the current revision of the ISO C standard at the time +this standard is approved. Since the ISO C standard and this standard are maintained by different organizations on different +schedules, we cannot predict what the compiler will be named in the next version of the standard.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_11_20" id="tag_20_11_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap01.html#tag_18_01_01_04"><i>1.1.1.4 File Read, Write, and Creation</i></a> , <a href= +"../utilities/ar.html#"><i>ar</i></a> , <a href="../utilities/getconf.html#"><i>getconf</i></a> , <a href= +"../utilities/make.html#"><i>make</i></a> , <a href="../utilities/nm.html#"><i>nm</i></a> , <a href= +"../utilities/strip.html#"><i>strip</i></a> , <a href="../utilities/umask.html#tag_20_132"><i>umask</i></a></p> +<p class="tent">XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a> , <a href= +"../basedefs/V1_chap14.html#tag_14"><i>14. Headers</i></a></p> +<p class="tent">XSH <a href="../functions/exec.html#tag_17_129"><i>exec</i></a> , <a href= +"../functions/sysconf.html#"><i>sysconf</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_11_21" id="tag_20_11_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 8. Included for alignment with the ISO/IEC 9899:2018 standard.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/bg.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/cal.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/cal.html b/bdd/cal.html @@ -0,0 +1,203 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>cal</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/c17.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/cat.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="cal" id="cal"></a> <a name="tag_20_12" id="tag_20_12"></a><!-- cal --> +<h4 class="mansect"><a name="tag_20_12_01" id="tag_20_12_01"></a>NAME</h4> +<blockquote>cal — print a calendar</blockquote> +<h4 class="mansect"><a name="tag_20_12_02" id="tag_20_12_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> cal</tt> <b>[[</b><i>month</i><b>]</b> <i>year</i><b>]</b> <tt><img src="../images/opt-end.gif" alt= +"[Option End]" border="0"></tt></code></div> +</blockquote> +<h4 class="mansect"><a name="tag_20_12_03" id="tag_20_12_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>cal</i> utility shall write a calendar to standard output using the Julian calendar for dates from January 1, 1 through +September 2, 1752 and the Gregorian calendar for dates from September 14, 1752 through December 31, 9999 as though the Gregorian +calendar had been adopted on September 14, 1752.</p> +<p>If no operands are given, <i>cal</i> shall produce a one-month calendar for the current month in the current year. If only the +<i>year</i> operand is given, <i>cal</i> shall produce a calendar for all twelve months in the given calendar year. If both +<i>month</i> and <i>year</i> operands are given, <i>cal</i> shall produce a one-month calendar for the given month in the given +year.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_12_04" id="tag_20_12_04"></a>OPTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_12_05" id="tag_20_12_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>month</i></dt> +<dd>Specify the month to be displayed, represented as a decimal integer from 1 (January) to 12 (December).</dd> +<dt><i>year</i></dt> +<dd>Specify the year for which the calendar is displayed, represented as a decimal integer from 1 to 9999.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_12_06" id="tag_20_12_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_12_07" id="tag_20_12_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_12_08" id="tag_20_12_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>cal</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error, and +informative messages written to standard output.</dd> +<dt><i>LC_TIME</i></dt> +<dd>Determine the format and contents of the calendar.</dd> +<dt><i>NLSPATH</i></dt> +<dd>Determine the location of messages objects and message catalogs.</dd> +<dt><i>TZ</i></dt> +<dd>Determine the timezone used to calculate the value of the current month.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_12_09" id="tag_20_12_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_12_10" id="tag_20_12_10"></a>STDOUT</h4> +<blockquote> +<p>The standard output shall be used to display the calendar, in an unspecified format.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_12_11" id="tag_20_12_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_12_12" id="tag_20_12_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_12_13" id="tag_20_12_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_12_14" id="tag_20_12_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_12_15" id="tag_20_12_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_12_16" id="tag_20_12_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Note that:</p> +<pre> +<tt>cal 83 +</tt></pre> +<p>refers to A.D. 83, not 1983.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_12_17" id="tag_20_12_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_12_18" id="tag_20_12_18"></a>RATIONALE</h4> +<blockquote> +<p>Earlier versions of this standard incorrectly required that the command:</p> +<pre> +<tt>cal 2000 +</tt></pre> +<p>write a one-month calendar for the current calendar month (no matter what the current year is) in the year 2000 to standard +output. This did not match historic practice in any known version of the <i>cal</i> utility. The description has been updated to +match historic practice. When only the <i>year</i> operand is given, <i>cal</i> writes a twelve-month calendar for the specified +year.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_12_19" id="tag_20_12_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>A future version of this standard may support locale-specific recognition of the date of adoption of the Gregorian calendar.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_12_20" id="tag_20_12_20"></a>SEE ALSO</h4> +<blockquote> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_12_21" id="tag_20_12_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_12_22" id="tag_20_12_22"></a>Issue 6</h4> +<blockquote> +<p>The DESCRIPTION is updated to allow for traditional behavior for years before the adoption of the Gregorian calendar.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_12_23" id="tag_20_12_23"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0074 [56] and XCU/TC1-2008/0075 [56] are applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_12_24" id="tag_20_12_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/c17.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/cat.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/cat.html b/bdd/cat.html @@ -0,0 +1,271 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>cat</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/cal.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/cd.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="cat" id="cat"></a> <a name="tag_20_13" id="tag_20_13"></a><!-- cat --> +<h4 class="mansect"><a name="tag_20_13_01" id="tag_20_13_01"></a>NAME</h4> +<blockquote>cat — concatenate and print files</blockquote> +<h4 class="mansect"><a name="tag_20_13_02" id="tag_20_13_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>cat</tt> <b>[</b><tt>-u</tt><b>] [</b><i>file</i><tt>...</tt><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_13_03" id="tag_20_13_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>cat</i> utility shall read files in sequence and shall write their contents to the standard output in the same +sequence.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_13_04" id="tag_20_13_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>cat</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following option shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-u</b></dt> +<dd>Write bytes from the input file to the standard output without delay as each is read.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_13_05" id="tag_20_13_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of an input file. If no <i>file</i> operands are specified, the standard input shall be used. If a <i>file</i> is +<tt>'-'</tt>, the <i>cat</i> utility shall read from the standard input at that point in the sequence. The <i>cat</i> utility shall +not close and reopen standard input when it is referenced in this way, but shall accept multiple occurrences of <tt>'-'</tt> as a +<i>file</i> operand.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_13_06" id="tag_20_13_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be used only if no <i>file</i> operands are specified, or if a <i>file</i> operand is <tt>'-'</tt>. See +the INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_13_07" id="tag_20_13_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files can be any file type.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_13_08" id="tag_20_13_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>cat</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_13_09" id="tag_20_13_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_13_10" id="tag_20_13_10"></a>STDOUT</h4> +<blockquote> +<p>The standard output shall contain the sequence of bytes read from the input files. Nothing else shall be written to the standard +output. If the standard output is a regular file, and is the same file as any of the input file operands, the implementation may +treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_13_11" id="tag_20_13_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_13_12" id="tag_20_13_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_13_13" id="tag_20_13_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_13_14" id="tag_20_13_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>All input files were output successfully.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_13_15" id="tag_20_13_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_13_16" id="tag_20_13_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The <b>-u</b> option has value in prototyping non-blocking reads from FIFOs. The intent is to support the following +sequence:</p> +<pre> +<tt>mkfifo foo +cat -u foo > /dev/tty13 & +cat -u > foo +</tt></pre> +<p>It is unspecified whether standard output is or is not buffered in the default case. This is sometimes of interest when standard +output is associated with a terminal, since buffering may delay the output. The presence of the <b>-u</b> option guarantees that +unbuffered I/O is available. It is implementation-defined whether the <i>cat</i> utility buffers output if the <b>-u</b> option is +not specified. Traditionally, the <b>-u</b> option is implemented using the equivalent of the <a href= +"../functions/setvbuf.html"><i>setvbuf</i>()</a> function defined in the System Interfaces volume of POSIX.1-2024.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_13_17" id="tag_20_13_17"></a>EXAMPLES</h4> +<blockquote> +<p>The following command:</p> +<pre> +<tt>cat myfile +</tt></pre> +<p>writes the contents of the file <b>myfile</b> to standard output.</p> +<p>The following command:</p> +<pre> +<tt>cat doc1 doc2 > doc.all +</tt></pre> +<p>concatenates the files <b>doc1</b> and <b>doc2</b> and writes the result to <b>doc.all</b>.</p> +<p>Because of the shell language mechanism used to perform output redirection, a command such as this:</p> +<pre> +<tt>cat doc doc.end > doc +</tt></pre> +<p>causes the original data in <b>doc</b> to be lost before <i>cat</i> even begins execution. This is true whether the <i>cat</i> +command fails with an error or silently succeeds (the specification allows both behaviors). In order to append the contents of +<b>doc.end</b> without losing the original contents of <b>doc</b>, this command should be used instead:</p> +<pre> +<tt>cat doc.end >> doc +</tt></pre> +<p>The command:</p> +<pre> +<tt>cat start - middle - end > file +</tt></pre> +<p>when standard input is a terminal, gets two arbitrary pieces of input from the terminal with a single invocation of <i>cat</i>. +Note, however, that if standard input is a regular file, this would be equivalent to the command:</p> +<pre> +<tt>cat start - middle /dev/null end > file +</tt></pre> +<p>because the entire contents of the file would be consumed by <i>cat</i> the first time <tt>'-'</tt> was used as a <i>file</i> +operand and an end-of-file condition would be detected immediately when <tt>'-'</tt> was referenced the second time.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_13_18" id="tag_20_13_18"></a>RATIONALE</h4> +<blockquote> +<p>Historical versions of the <i>cat</i> utility include the <b>-e</b>, <b>-t</b>, and <b>-v</b>, options which permit the ends of +lines, <tab> characters, and invisible characters, respectively, to be rendered visible in the output. The standard +developers omitted these options because they provide too fine a degree of control over what is made visible, and similar output +can be obtained using a command such as:</p> +<pre> +<tt>sed -n l pathname +</tt></pre> +<p>The latter also has the advantage that its output is unambiguous, whereas the output of historical <i>cat</i> <b>-etv</b> is +not.</p> +<p>The <b>-s</b> option was omitted because it corresponds to different functions in BSD and System V-based systems. The BSD +<b>-s</b> option to squeeze blank lines can be accomplished by the shell script shown in the following example:</p> +<pre> +<tt>sed -n ' +# Write non-empty lines. +/./ { + p + d + } +# Write a single empty line, then look for more empty lines. +/^$/ p +# Get next line, discard the held <newline> (empty line), +# and look for more empty lines. +:Empty +/^$/ { + N + s/.// + b Empty + } +# Write the non-empty line before going back to search +# for the first in a set of empty lines. + p +' +</tt></pre> +<p>The System V <b>-s</b> option to silence error messages can be accomplished by redirecting the standard error. Note that the BSD +documentation for <i>cat</i> uses the term "blank line" to mean the same as the POSIX "empty line": a line consisting only of a +<newline>.</p> +<p>The BSD <b>-n</b> option was omitted because similar functionality can be obtained from the <b>-n</b> option of the <a href= +"../utilities/pr.html"><i>pr</i></a> utility.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_13_19" id="tag_20_13_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_13_20" id="tag_20_13_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/more.html#"><i>more</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/setvbuf.html#"><i>setvbuf</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_13_21" id="tag_20_13_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_13_22" id="tag_20_13_22"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>SD5-XCU-ERN-174 is applied, changing the RATIONALE.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0073 [876] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_13_23" id="tag_20_13_23"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/cal.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/cd.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/cd.html b/bdd/cd.html @@ -0,0 +1,418 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>cd</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/cat.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/cflow.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="cd" id="cd"></a> <a name="tag_20_14" id="tag_20_14"></a><!-- cd --> +<h4 class="mansect"><a name="tag_20_14_01" id="tag_20_14_01"></a>NAME</h4> +<blockquote>cd — change the working directory</blockquote> +<h4 class="mansect"><a name="tag_20_14_02" id="tag_20_14_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>cd</tt> <b>[</b><tt>-L</tt><b>] [</b><i>directory</i><b>]</b> <tt><br> +<br> +cd -P</tt> <b>[</b><tt>-e</tt><b>] [</b><i>directory</i><b>]</b> <tt><br></tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_14_03" id="tag_20_14_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>cd</i> utility shall change the working directory of the current shell execution environment (see <a href= +"../utilities/V3_chap02.html#tag_19_13"><i>2.13 Shell Execution Environment</i></a> ) by executing the following steps in sequence. +(In the following steps, the symbol <b>curpath</b> represents an intermediate value used to simplify the description of the +algorithm used by <i>cd</i>. There is no requirement that <b>curpath</b> be made visible to the application.)</p> +<ol> +<li> +<p>If no <i>directory</i> operand is given and the <i>HOME</i> environment variable is empty or undefined, the default behavior is +implementation-defined and no further steps shall be taken.</p> +</li> +<li> +<p>If no <i>directory</i> operand is given and the <i>HOME</i> environment variable is set to a non-empty value, the <i>cd</i> +utility shall behave as if the directory named in the <i>HOME</i> environment variable was specified as the <i>directory</i> +operand.</p> +</li> +<li> +<p>If the <i>directory</i> operand begins with a <slash> character, set <b>curpath</b> to the operand and proceed to step +7.</p> +</li> +<li> +<p>If the first component of the <i>directory</i> operand is dot or dot-dot, proceed to step 6.</p> +</li> +<li> +<p>Starting with the first pathname in the <colon>-separated pathnames of <i>CDPATH</i> (see the ENVIRONMENT VARIABLES +section) if the pathname is non-null, test if the concatenation of that pathname, a <slash> character if that pathname did +not end with a <slash> character, and the <i>directory</i> operand names a directory. If the pathname is null, test if the +concatenation of dot, a <slash> character, and the operand names a directory. In either case, if the resulting string names +an existing directory, set <b>curpath</b> to that string and proceed to step 7. Otherwise, repeat this step with the next pathname +in <i>CDPATH</i> until all pathnames have been tested.</p> +</li> +<li> +<p>Set <b>curpath</b> to the <i>directory</i> operand.</p> +</li> +<li> +<p>If the <b>-P</b> option is in effect, proceed to step 10. If <b>curpath</b> does not begin with a <slash> character, set +<b>curpath</b> to the string formed by the concatenation of the value of <i>PWD ,</i> a <slash> character if the value of +<i>PWD</i> did not end with a <slash> character, and <b>curpath</b>.</p> +</li> +<li> +<p>The <b>curpath</b> value shall then be converted to canonical form as follows, considering each component from beginning to end, +in sequence:</p> +<ol type="a"> +<li> +<p>Dot components and any <slash> characters that separate them from the next component shall be deleted.</p> +</li> +<li> +<p>For each dot-dot component, if there is a preceding component and it is neither root nor dot-dot, then:</p> +<ol type="i"> +<li> +<p>If the preceding component does not refer (in the context of pathname resolution with symbolic links followed) to a directory, +then the <i>cd</i> utility shall display an appropriate error message and no further steps shall be taken.</p> +</li> +<li> +<p>The preceding component, all <slash> characters separating the preceding component from dot-dot, dot-dot, and all +<slash> characters separating dot-dot from the following component (if any) shall be deleted.</p> +</li> +</ol> +</li> +<li> +<p>An implementation may further simplify <b>curpath</b> by removing any trailing <slash> characters that are not also +leading <slash> characters, replacing multiple non-leading consecutive <slash> characters with a single <slash>, +and replacing three or more leading <slash> characters with a single <slash>. If, as a result of this canonicalization, +the <b>curpath</b> variable is null, no further steps shall be taken.</p> +</li> +</ol> +</li> +<li> +<p>If <b>curpath</b> is longer than {PATH_MAX} bytes (including the terminating null) and the <i>directory</i> operand was not +longer than {PATH_MAX} bytes (including the terminating null), then <b>curpath</b> shall be converted from an absolute pathname to +an equivalent relative pathname if possible. This conversion shall always be considered possible if the value of <i>PWD ,</i> with +a trailing <slash> added if it does not already have one, is an initial substring of <b>curpath</b>. Whether or not it is +considered possible under other circumstances is unspecified. Implementations may also apply this conversion if <b>curpath</b> is +not longer than {PATH_MAX} bytes or the <i>directory</i> operand was longer than {PATH_MAX} bytes.</p> +</li> +<li> +<p>The <i>cd</i> utility shall then perform actions equivalent to the <a href="../functions/chdir.html"><i>chdir</i>()</a> function +called with <b>curpath</b> as the <i>path</i> argument. If these actions fail for any reason, the <i>cd</i> utility shall display +an appropriate error message and the remainder of this step shall not be executed. If the <b>-P</b> option is not in effect, the +<i>PWD</i> environment variable shall be set to the value that <b>curpath</b> had on entry to step 9 (i.e., before conversion to a +relative pathname).</p> +<p>If the <b>-P</b> option is in effect, the <i>PWD</i> environment variable shall be set to the string that would be output by +<a href="../utilities/pwd.html"><i>pwd</i></a> <b>-P</b>. If there is insufficient permission on the new directory, or on any +parent of that directory, to determine the current working directory, the value of the <i>PWD</i> environment variable is +unspecified. If both the <b>-e</b> and the <b>-P</b> options are in effect and <i>cd</i> is unable to determine the pathname of the +current working directory, <i>cd</i> shall complete successfully but return a non-zero exit status.</p> +</li> +</ol> +<p>If, during the execution of the above steps, the <i>PWD</i> environment variable is set, the <i>OLDPWD</i> shell variable shall +also be set to the value of the old working directory (that is the current working directory immediately prior to the call to +<i>cd</i>). It is unspecified whether, when setting <i>OLDPWD ,</i> the shell also causes it to be exported if it was not +already.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_14_04" id="tag_20_14_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>cd</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported by the implementation:</p> +<dl compact> +<dd></dd> +<dt><b>-e</b></dt> +<dd>If the <b>-P</b> option is in effect, the current working directory is successfully changed, and the correct value of the +<i>PWD</i> environment variable cannot be determined, exit with exit status 1.</dd> +<dt><b>-L</b></dt> +<dd>Handle the operand dot-dot logically; symbolic link components shall not be resolved before dot-dot components are processed +(see steps 8. and 9. in the DESCRIPTION).</dd> +<dt><b>-P</b></dt> +<dd>Handle the operand dot-dot physically; symbolic link components shall be resolved before dot-dot components are processed (see +step 7. in the DESCRIPTION).</dd> +</dl> +<p>If both <b>-L</b> and <b>-P</b> options are specified, the last of these options shall be used and all others ignored. If +neither <b>-L</b> nor <b>-P</b> is specified, the operand shall be handled dot-dot logically; see the DESCRIPTION.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_14_05" id="tag_20_14_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>directory</i></dt> +<dd>An absolute or relative pathname of the directory that shall become the new working directory. The interpretation of a relative +pathname by <i>cd</i> depends on the <b>-L</b> option and the <i>CDPATH</i> and <i>PWD</i> environment variables. If +<i>directory</i> is an empty string, <i>cd</i> shall write a diagnostic message to standard error and exit with non-zero status. If +<i>directory</i> consists of a single <tt>'-'</tt> (<hyphen-minus>) character, the <i>cd</i> utility shall behave as if +<i>directory</i> contained the value of the <i>OLDPWD</i> environment variable, except that after it sets the value of <i>PWD</i> +it shall write the new value to standard output. The behavior is unspecified if <i>OLDPWD</i> does not start with a <slash> +character.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_14_06" id="tag_20_14_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_14_07" id="tag_20_14_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_14_08" id="tag_20_14_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>cd</i>:</p> +<dl compact> +<dd></dd> +<dt><i>CDPATH</i></dt> +<dd>A <colon>-separated list of pathnames that refer to directories. The <i>cd</i> utility shall use this list in its attempt +to change the directory, as described in the DESCRIPTION. An empty string in place of a directory pathname represents the current +directory. If <i>CDPATH</i> is not set, it shall be treated as if it were an empty string.</dd> +<dt><i>HOME</i></dt> +<dd>The name of the directory, used when no <i>directory</i> operand is specified.</dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>OLDPWD</i></dt> +<dd>A pathname of the previous working directory, used when the operand is <tt>'-'</tt>. If an application sets or unsets the value +of <i>OLDPWD ,</i> the behavior of <i>cd</i> with a <tt>'-'</tt> operand is unspecified.</dd> +<dt><i>PWD</i></dt> +<dd>This variable shall be set as specified in the DESCRIPTION. If an application sets or unsets the value of <i>PWD ,</i> the +behavior of <i>cd</i> is unspecified.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_14_09" id="tag_20_14_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_14_10" id="tag_20_14_10"></a>STDOUT</h4> +<blockquote> +<p>If a non-empty directory name from <i>CDPATH</i> is used, or if the operand <tt>'-'</tt> is used, and the absolute pathname of +the new working directory can be determined, that pathname shall be written to the standard output as follows:</p> +<pre> +<tt>"%s\n", <</tt><i>new directory</i><tt>> +</tt></pre> +<p>If an absolute pathname of the new current working directory cannot be determined, it is unspecified whether nothing is written +to the standard output or the value of <b>curpath</b> used in step 10, followed by a <newline>, is written to the standard +output.</p> +<p>If a non-empty directory name from <i>CDPATH</i> is not used, and the directory argument is not <tt>'-'</tt>, there shall be no +output.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_14_11" id="tag_20_14_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_14_12" id="tag_20_14_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_14_13" id="tag_20_14_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_14_14" id="tag_20_14_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>The current working directory was successfully changed and the value of the <i>PWD</i> environment variable was set +correctly.</dd> +<dt> 0</dt> +<dd>The current working directory was successfully changed, the <b>-e</b> option is not in effect, the <b>-P</b> option is in +effect, and the correct value of the <i>PWD</i> environment variable could not be determined.</dd> +<dt>>0</dt> +<dd>Either the <b>-e</b> option or the <b>-P</b> option is not in effect, and an error occurred.</dd> +<dt> 1</dt> +<dd>The current working directory was successfully changed, both the <b>-e</b> and the <b>-P</b> options are in effect, and the +correct value of the <i>PWD</i> environment variable could not be determined.</dd> +<dt>>1</dt> +<dd>Both the <b>-e</b> and the <b>-P</b> options are in effect, and an error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_14_15" id="tag_20_14_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>The working directory shall remain unchanged.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_14_16" id="tag_20_14_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>This utility is required to be intrinsic. See <a href="../utilities/V3_chap01.html#tag_18_07"><i>1.7 Intrinsic Utilities</i></a> +for details.</p> +<p>Since <i>cd</i> affects the current shell execution environment, it is always provided as a shell regular built-in. If it is +called in a subshell or separate utility execution environment, such as one of the following:</p> +<pre> +<tt>(cd /tmp) +nohup cd +find . -exec cd {} \; +</tt></pre> +<p>it does not affect the working directory of the caller's environment.</p> +<p>The user must have execute (search) permission in <i>directory</i> in order to change to it.</p> +<p>Since <i>cd</i> treats the operand <tt>'-'</tt> as a special case, applications should not pass arbitrary values as the operand. +For example, instead of:</p> +<pre> +<tt>CDPATH= cd -P -- "$dir" +</tt></pre> +<p>applications should use the following:</p> +<pre> +<tt>case $dir in +(/*) cd -P "$dir";; +("") echo >&2 directory is an empty string; exit 1;; +(*) CDPATH= cd -P "./$dir";; +esac +</tt></pre> +<p>If an absolute pathname of the new current working directory cannot be determined, and a non-empty directory name from +<i>CDPATH</i> is used, <i>cd</i> may write a pathname to standard output that is not an absolute pathname.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_14_17" id="tag_20_14_17"></a>EXAMPLES</h4> +<blockquote> +<p>The following template can be used to perform processing in the directory specified by <i>location</i> and end up in the current +working directory in use before the first <i>cd</i> command was issued:</p> +<pre> +<tt>cd </tt><i>location</i><tt> +if [ $? -ne 0 ] +then + print error message + exit 1 +fi +... do whatever is desired as long as the OLDPWD environment variable + is not modified +cd - +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_14_18" id="tag_20_14_18"></a>RATIONALE</h4> +<blockquote> +<p>The use of the <i>CDPATH</i> was introduced in the System V shell. Its use is analogous to the use of the <i>PATH</i> variable +in the shell. The BSD C shell used a shell parameter <i>cdpath</i> for this purpose.</p> +<p>A common extension when <i>HOME</i> is undefined is to get the login directory from the user database for the invoking user. +This does not occur on System V implementations.</p> +<p>Some historical shells, such as the KornShell, took special actions when the directory name contained a dot-dot component, +selecting the logical parent of the directory, rather than the actual parent directory; that is, it moved up one level toward the +<tt>'/'</tt> in the pathname, remembering what the user typed, rather than performing the equivalent of:</p> +<pre> +<tt>chdir(".."); +</tt></pre> +<p>In such a shell, the following commands would not necessarily produce equivalent output for all directories:</p> +<pre> +<tt>cd .. && ls ls .. +</tt></pre> +<p>This behavior is now the default. It is not consistent with the definition of dot-dot in most historical practice; that is, +while this behavior has been optionally available in the KornShell, other shells have historically not supported this +functionality. The logical pathname is stored in the <i>PWD</i> environment variable when the <i>cd</i> utility completes and this +value is used to construct the next directory name if <i>cd</i> is invoked with the <b>-L</b> option.</p> +<p>When the <b>-P</b> option is in effect, the correct value of the <i>PWD</i> environment variable cannot be determined on some +systems, but still results in a zero exit status. The value of <i>PWD</i> doesn't matter to some shell scripts and in those cases +this is not a problem. In other cases, especially with multiple calls to <i>cd</i>, the values of <i>PWD</i> and <i>OLDPWD</i> are +important but the standard provided no easy way to know that this was the case. The <b>-e</b> option has been added, even though +this was not historic practice, to give script writers a reliable way to know when the value of <i>PWD</i> is not reliable.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_14_19" id="tag_20_14_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_14_20" id="tag_20_14_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19_13"><i>2.13 Shell Execution Environment</i></a> , <a href= +"../utilities/pwd.html#"><i>pwd</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/chdir.html#"><i>chdir</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_14_21" id="tag_20_14_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_14_22" id="tag_20_14_22"></a>Issue 6</h4> +<blockquote> +<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p> +<ul> +<li> +<p>The <i>cd</i> <b>-</b> operand, <i>PWD ,</i> and <i>OLDPWD</i> are added.</p> +</li> +</ul> +<p>The <b>-L</b> and <b>-P</b> options are added to align with the IEEE P1003.2b draft standard. This also includes the +introduction of a new description to include the effect of these options.<br></p> +<p>IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/14 is applied, changing the SYNOPSIS to make it clear that the +<b>-L</b> and <b>-P</b> options are mutually-exclusive.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_14_23" id="tag_20_14_23"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #037 is applied.</p> +<p>Austin Group Interpretation 1003.1-2001 #199 is applied, clarifying how the <i>cd</i> utility handles concatenation of two +pathnames when the first pathname ends in a <slash> character.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>Step 7 of the processing performed by <i>cd</i> is revised to refer to <b>curpath</b> instead of "the operand".</p> +<p>Changes to the <a href="../utilities/pwd.html"><i>pwd</i></a> utility and <i>PWD</i> environment variable have been made to +match the changes to the <a href="../functions/getcwd.html"><i>getcwd</i>()</a> function made for Austin Group Interpretation +1003.1-2001 #140.</p> +<p>POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0076 [230], XCU/TC1-2008/0077 [240], XCU/TC1-2008/0078 [240], and +XCU/TC1-2008/0079 [123] are applied.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0074 [584] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_14_24" id="tag_20_14_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to report an error if a utility is directed to display a +pathname that contains any bytes that have the encoded value of a <newline> character when <newline> is a terminator or +separator in the output format being used.</p> +<p>Austin Group Defect 253 is applied, adding the <b>-e</b> option.</p> +<p>Austin Group Defect 854 is applied, adding a note to the APPLICATION USAGE section that this utility is required to be +intrinsic.</p> +<p>Austin Group Defect 1045 is applied, clarifying the behavior when the <i>directory</i> operand is <tt>'-'</tt>.</p> +<p>Austin Group Defect 1047 is applied, requiring <i>cd</i> to treat an empty <i>directory</i> operand as an error</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1527 is applied, clarifying the behavior when an absolute pathname of the new current working directory +cannot be determined.</p> +<p>Austin Group Defect 1601 is applied, clarifying that when setting <i>OLDPWD ,</i> the shell need not cause it to be exported if +it was not already.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/cat.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/cflow.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/cflow.html b/bdd/cflow.html @@ -0,0 +1,265 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>cflow</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/cd.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/chgrp.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="cflow" id="cflow"></a> <a name="tag_20_15" id="tag_20_15"></a><!-- cflow --> +<h4 class="mansect"><a name="tag_20_15_01" id="tag_20_15_01"></a>NAME</h4> +<blockquote>cflow — generate a C-language flowgraph (<b>DEVELOPMENT</b>)</blockquote> +<h4 class="mansect"><a name="tag_20_15_02" id="tag_20_15_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> cflow</tt> <b>[</b><tt>-r</tt><b>] [</b><tt>-d</tt> <i>num</i><b>] [</b><tt>-D</tt> +<i>name</i><b>[</b><tt>=</tt><i>def</i><b>]]</b><tt>...</tt> <b>[</b><tt>-i</tt> <i>incl</i><b>] [</b><tt>-I</tt> +<i>dir</i><b>]</b><tt>...<br> + </tt> <b>[</b><tt>-U</tt> <i>dir</i><b>]</b><tt>...</tt> <i>file</i><tt>... <img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div> +</blockquote> +<h4 class="mansect"><a name="tag_20_15_03" id="tag_20_15_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>cflow</i> utility shall analyze a collection of object files or assembler, C-language, <a href= +"../utilities/lex.html"><i>lex</i></a>, or <a href="../utilities/yacc.html"><i>yacc</i></a> source files, and attempt to build a +graph, written to standard output, charting the external references.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_15_04" id="tag_20_15_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>cflow</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> , except that the order of the <b>-D</b>, <b>-I</b>, and <b>-U</b> options (which are identical to their +interpretation by <a href="../utilities/c17.html"><i>c17</i></a>) is significant.</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-d </b><i>num</i></dt> +<dd>Indicate the depth at which the flowgraph is cut off. The application shall ensure that the argument <i>num</i> is a decimal +integer. By default this is a very large number (typically greater than 32000). Attempts to set the cut-off depth to a non-positive +integer shall be ignored.</dd> +<dt><b>-i </b><i>incl</i></dt> +<dd>Increase the number of included symbols. The <i>incl</i> option-argument is one of the following characters: +<dl compact> +<dd></dd> +<dt><i>x</i></dt> +<dd>Include external and static data symbols. The default shall be to include only functions in the flowgraph.</dd> +<dt><tt>_</tt></dt> +<dd>(Underscore) Include names that begin with an <underscore>. The default shall be to exclude these functions (and data if +<b>-i x</b> is used).</dd> +</dl> +</dd> +<dt><b>-r</b></dt> +<dd>Reverse the caller:callee relationship, producing an inverted listing showing the callers of each function. The listing shall +also be sorted in lexicographical order by callee.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_15_05" id="tag_20_15_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand is supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>The pathname of a file for which a graph is to be generated. Filenames suffixed by <b>.l</b> shall shall be taken to be +<a href="../utilities/lex.html"><i>lex</i></a> input, <b>.y</b> as <a href="../utilities/yacc.html"><i>yacc</i></a> input, +<b>.c</b> as <a href="../utilities/c17.html"><i>c17</i></a> input, and <b>.i</b> as the output of <a href= +"../utilities/c17.html"><i>c17</i></a> <b>-E</b>. Such files shall be processed as appropriate, determined by their suffix. +<p>Files suffixed by <b>.s</b> (conventionally assembler source) may have more limited information extracted from them.</p> +</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_15_06" id="tag_20_15_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_15_07" id="tag_20_15_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files shall be object files or assembler, C-language, <a href="../utilities/lex.html"><i>lex</i></a>, or <a href= +"../utilities/yacc.html"><i>yacc</i></a> source files.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_15_08" id="tag_20_15_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>cflow</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_COLLATE</i></dt> +<dd><br> +Determine the locale for the ordering of the output when the <b>-r</b> option is used.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd>Determine the location of messages objects and message catalogs.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_15_09" id="tag_20_15_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_15_10" id="tag_20_15_10"></a>STDOUT</h4> +<blockquote> +<p>The flowgraph written to standard output shall be formatted as follows:</p> +<pre> +<tt>"%d %s:%s\n", <</tt><i>reference number</i><tt>>, <</tt><i>global</i><tt>>, <</tt><i>definition</i><tt>> +</tt></pre> +<p>Each line of output begins with a reference (that is, line) number, followed by indentation of at least one column position per +level. This is followed by the name of the global, a <colon>, and its definition. Normally globals are only functions not +defined as an external or beginning with an <underscore>; see the OPTIONS section for the <b>-i</b> inclusion option. For +information extracted from C-language source, the definition consists of an abstract type declaration (for example, <b>char *</b>) +and, delimited by angle brackets, the name of the source file and the line number where the definition was found. Definitions +extracted from object files indicate the filename and location counter under which the symbol appeared (for example, +<i>text</i>).</p> +<p>Once a definition of a name has been written, subsequent references to that name contain only the reference number of the line +where the definition can be found. For undefined references, only <tt>"<>"</tt> shall be written.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_15_11" id="tag_20_15_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_15_12" id="tag_20_15_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_15_13" id="tag_20_15_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_15_14" id="tag_20_15_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_15_15" id="tag_20_15_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_15_16" id="tag_20_15_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Files produced by <a href="../utilities/lex.html"><i>lex</i></a> and <a href="../utilities/yacc.html"><i>yacc</i></a> cause the +reordering of line number declarations, and this can confuse <i>cflow</i>. To obtain proper results, the input of <a href= +"../utilities/yacc.html"><i>yacc</i></a> or <a href="../utilities/lex.html"><i>lex</i></a> must be directed to <i>cflow</i>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_15_17" id="tag_20_15_17"></a>EXAMPLES</h4> +<blockquote> +<p>Given the following in <b>file.c</b>:</p> +<pre> +<tt>int i; +int f(); +int g(); +int h(); +int +main(void) +{ + f(); + g(); + f(); +} +int +f() +{ + i = h(); +} +</tt></pre> +<p>The command:</p> +<pre> +<tt>cflow -i x file.c +</tt></pre> +<p>produces the output:</p> +<pre> +<tt>1 main: int(), <file.c 6> +2 f: int(), <file.c 13> +3 h: <> +4 i: int, <file.c 1> +5 g: <> +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_15_18" id="tag_20_15_18"></a>RATIONALE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_15_19" id="tag_20_15_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_15_20" id="tag_20_15_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/c17.html#"><i>c17</i></a> , <a href="../utilities/lex.html#"><i>lex</i></a> , <a href= +"../utilities/yacc.html#"><i>yacc</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_15_21" id="tag_20_15_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_15_22" id="tag_20_15_22"></a>Issue 6</h4> +<blockquote> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_15_23" id="tag_20_15_23"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_15_24" id="tag_20_15_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1195 is applied, changing "<tt>main()</tt>" to "<tt>main(void)</tt>".</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/cd.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/chgrp.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/chgrp.html b/bdd/chgrp.html @@ -0,0 +1,246 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>chgrp</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/cflow.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/chmod.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="chgrp" id="chgrp"></a> <a name="tag_20_16" id="tag_20_16"></a><!-- chgrp --> +<h4 class="mansect"><a name="tag_20_16_01" id="tag_20_16_01"></a>NAME</h4> +<blockquote>chgrp — change the file group ownership</blockquote> +<h4 class="mansect"><a name="tag_20_16_02" id="tag_20_16_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>chgrp</tt> <b>[</b><tt>-h</tt><b>]</b> <i>group file</i><tt>...<br> +<br> +chgrp -R</tt> <b>[</b><tt>-H|-L|-P</tt><b>]</b> <i>group file</i><tt>...<br></tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_16_03" id="tag_20_16_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>chgrp</i> utility shall set the group ID of the file named by each <i>file</i> operand to the group ID specified by the +<i>group</i> operand.</p> +<p>For each <i>file</i> operand, or, if the <b>-R</b> option is used, each file encountered while walking the directory trees +specified by the <i>file</i> operands, the <i>chgrp</i> utility shall perform actions equivalent to the <a href= +"../functions/chown.html"><i>chown</i>()</a> function defined in the System Interfaces volume of POSIX.1-2024, called with the +following arguments:</p> +<ul> +<li> +<p>The <i>file</i> operand shall be used as the <i>path</i> argument.</p> +</li> +<li> +<p>The user ID of the file shall be used as the <i>owner</i> argument.</p> +</li> +<li> +<p>The specified group ID shall be used as the <i>group</i> argument.</p> +</li> +</ul> +<p>Unless <i>chgrp</i> is invoked by a process with appropriate privileges, the set-user-ID and set-group-ID bits of a regular file +shall be cleared upon successful completion; the set-user-ID and set-group-ID bits of other file types may be cleared.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_16_04" id="tag_20_16_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>chgrp</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported by the implementation:</p> +<dl compact> +<dd></dd> +<dt><b>-h</b></dt> +<dd>For each <i>file</i> operand that names a file of type symbolic link, <i>chgrp</i> shall attempt to set the group ID of the +symbolic link instead of the file referenced by the symbolic link.</dd> +<dt><b>-H</b></dt> +<dd>If the <b>-R</b> option is specified and a symbolic link referencing a file of type directory is specified on the command line, +<i>chgrp</i> shall change the group of the directory referenced by the symbolic link and all files in the file hierarchy below +it.</dd> +<dt><b>-L</b></dt> +<dd>If the <b>-R</b> option is specified and a symbolic link referencing a file of type directory is specified on the command line +or encountered during the traversal of a file hierarchy, <i>chgrp</i> shall change the group of the directory referenced by the +symbolic link and all files in the file hierarchy below it.</dd> +<dt><b>-P</b></dt> +<dd>If the <b>-R</b> option is specified and a symbolic link is specified on the command line or encountered during the traversal +of a file hierarchy, <i>chgrp</i> shall change the group ID of the symbolic link. The <i>chgrp</i> utility shall not follow the +symbolic link to any other part of the file hierarchy.</dd> +<dt><b>-R</b></dt> +<dd>Recursively change file group IDs. For each <i>file</i> operand that names a directory, <i>chgrp</i> shall change the group of +the directory and all files in the file hierarchy below it. Unless a <b>-H</b>, <b>-L</b>, or <b>-P</b> option is specified, it is +unspecified which of these options will be used as the default.</dd> +</dl> +<p>Specifying more than one of the mutually-exclusive options <b>-H</b>, <b>-L</b>, and <b>-P</b> shall not be considered an error. +The last option specified shall determine the behavior of the utility.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_16_05" id="tag_20_16_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>group</i></dt> +<dd>A group name from the group database or a numeric group ID. Either specifies a group ID to be given to each file named by one +of the <i>file</i> operands. If a numeric <i>group</i> operand exists in the group database as a group name, the group ID number +associated with that group name is used as the group ID.</dd> +<dt><i>file</i></dt> +<dd>A pathname of a file whose group ID is to be modified.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_16_06" id="tag_20_16_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_16_07" id="tag_20_16_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_16_08" id="tag_20_16_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>chgrp</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_16_09" id="tag_20_16_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_16_10" id="tag_20_16_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_16_11" id="tag_20_16_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_16_12" id="tag_20_16_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_16_13" id="tag_20_16_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_16_14" id="tag_20_16_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>The utility executed successfully and all requested changes were made.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_16_15" id="tag_20_16_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_16_16" id="tag_20_16_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Only the owner of a file or the user with appropriate privileges may change the owner or group of a file.</p> +<p>Some implementations restrict the use of <i>chgrp</i> to a user with appropriate privileges when the <i>group</i> specified is +not the effective group ID or one of the supplementary group IDs of the calling process.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_16_17" id="tag_20_16_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_16_18" id="tag_20_16_18"></a>RATIONALE</h4> +<blockquote> +<p>The System V and BSD versions use different exit status codes. Some implementations used the exit status as a count of the +number of errors that occurred; this practice is unworkable since it can overflow the range of valid exit status values. The +standard developers chose to mask these by specifying only 0 and >0 as exit values.</p> +<p>The functionality of <i>chgrp</i> is described substantially through references to <a href= +"../functions/chown.html"><i>chown</i>()</a>. In this way, there is no duplication of effort required for describing the +interactions of permissions, multiple groups, and so on.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_16_19" id="tag_20_16_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_16_20" id="tag_20_16_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/chmod.html#tag_20_17"><i>chmod</i></a> , <a href="../utilities/chown.html#tag_20_18"><i>chown</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/chown.html#tag_17_73"><i>chown</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_16_21" id="tag_20_16_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_16_22" id="tag_20_16_22"></a>Issue 6</h4> +<blockquote> +<p>New options <b>-H</b>, <b>-L</b>, and <b>-P</b> are added to align with the IEEE P1003.2b draft standard. These options +affect the processing of symbolic links.</p> +<p>IEEE PASC Interpretation 1003.2 #172 is applied, changing the CONSEQUENCES OF ERRORS section to "Default.".</p> +<p>IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/15 is applied, changing the SYNOPSIS to make it clear that +<b>-h</b> and <b>-R</b> are optional.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_16_23" id="tag_20_16_23"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-8 is applied, removing the <b>-R</b> from the first line of the SYNOPSIS.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0080 [237,341] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_16_24" id="tag_20_16_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/cflow.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/chmod.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/chmod.html b/bdd/chmod.html @@ -0,0 +1,556 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>chmod</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/chgrp.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/chown.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="chmod" id="chmod"></a> <a name="tag_20_17" id="tag_20_17"></a><!-- chmod --> +<h4 class="mansect"><a name="tag_20_17_01" id="tag_20_17_01"></a>NAME</h4> +<blockquote>chmod — change the file modes</blockquote> +<h4 class="mansect"><a name="tag_20_17_02" id="tag_20_17_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>chmod</tt> <b>[</b><tt>-R</tt><b>]</b> <i>mode file</i><tt>...</tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_17_03" id="tag_20_17_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>chmod</i> utility shall change any or all of the file mode bits of the file named by each <i>file</i> operand in the way +specified by the <i>mode</i> operand.</p> +<p>It is implementation-defined whether and how the <i>chmod</i> utility affects any alternate or additional file access control +mechanism (see XBD <a href="../basedefs/V1_chap04.html#tag_04_07"><i>4.7 File Access Permissions</i></a> ) being used for the +specified file.</p> +<p>Only a process whose effective user ID matches the user ID of the file, or a process with appropriate privileges, shall be +permitted to change the file mode bits of a file.</p> +<p>Upon successfully changing the file mode bits of a file, the <i>chmod</i> utility shall mark for update the last file status +change timestamp of the file.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_17_04" id="tag_20_17_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>chmod</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following option shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-R</b></dt> +<dd>Recursively change file mode bits. For each <i>file</i> operand that names a directory, <i>chmod</i> shall change the file mode +bits of the directory and all files in the file hierarchy below it.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_17_05" id="tag_20_17_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>mode</i></dt> +<dd>Represents the change to be made to the file mode bits of each file named by one of the <i>file</i> operands; see the EXTENDED +DESCRIPTION section.</dd> +<dt><i>file</i></dt> +<dd>A pathname of a file whose file mode bits shall be modified.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_17_06" id="tag_20_17_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_17_07" id="tag_20_17_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_17_08" id="tag_20_17_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>chmod</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_17_09" id="tag_20_17_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_17_10" id="tag_20_17_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_17_11" id="tag_20_17_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_17_12" id="tag_20_17_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_17_13" id="tag_20_17_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>The <i>mode</i> operand shall be either a <i>symbolic_mode</i> expression or a non-negative octal integer. The +<i>symbolic_mode</i> form is described by the grammar later in this section.</p> +<p>Each <b>clause</b> shall specify an operation to be performed on the current file mode bits of each <i>file</i>. The operations +shall be performed on each <i>file</i> in the order in which the <b>clause</b>s are specified.</p> +<p>The <b>who</b> symbols <b>u</b>, <b>g</b>, and <b>o</b> shall specify the <i>user</i>, <i>group</i>, and <i>other</i> parts of +the file mode bits, respectively. A <b>who</b> consisting of the symbol <b>a</b> shall be equivalent to <b>ugo</b>.</p> +<p>The <b>perm</b> symbols <b>r</b>, <b>w</b>, and <b>x</b> represent the <i>read</i>, <i>write</i>, and +<i>execute</i>/<i>search</i> portions of file mode bits, respectively. The <b>perm</b> symbol <b>s</b> shall represent the +<i>set-user-ID-on-execution</i> (when <b>who</b> contains or implies <b>u</b>) and <i>set-group-ID-on-execution</i> (when +<b>who</b> contains or implies <b>g</b>) bits.</p> +<p>The <b>perm</b> symbol <b>X</b> shall represent the execute/search portion of the file mode bits if the file is a directory or +if the current (unmodified) file mode bits have at least one of the execute bits (S_IXUSR, S_IXGRP, or S_IXOTH) set. It shall be +ignored if the file is not a directory and none of the execute bits are set in the current file mode bits.</p> +<p>The <b>permcopy</b> symbols <b>u</b>, <b>g</b>, and <b>o</b> shall represent the current permissions associated with the user, +group, and other parts of the file mode bits, respectively. For the remainder of this section, <b>perm</b> refers to the +non-terminals <b>perm</b> and <b>permcopy</b> in the grammar.</p> +<p>If multiple <b>actionlist</b>s are grouped with a single <b>wholist</b> in the grammar, each <b>actionlist</b> shall be applied +in the order specified with that <b>wholist</b>. The <i>op</i> symbols shall represent the operation performed, as follows:</p> +<dl compact> +<dd></dd> +<dt><tt>+</tt></dt> +<dd>If <b>perm</b> is not specified, the <tt>'+'</tt> operation shall not change the file mode bits. +<p>If <b>who</b> is not specified, the file mode bits represented by <b>perm</b> for the owner, group, and other permissions, +except for those with corresponding bits in the file mode creation mask of the invoking process, shall be set.</p> +<p>Otherwise, the file mode bits represented by the specified <b>who</b> and <b>perm</b> values shall be set.</p> +</dd> +<dt><tt>-</tt></dt> +<dd>If <b>perm</b> is not specified, the <tt>'-'</tt> operation shall not change the file mode bits. +<p>If <b>who</b> is not specified, the file mode bits represented by <b>perm</b> for the owner, group, and other permissions, +except for those with corresponding bits in the file mode creation mask of the invoking process, shall be cleared.</p> +<p>Otherwise, the file mode bits represented by the specified <b>who</b> and <b>perm</b> values shall be cleared.</p> +</dd> +<dt><tt>=</tt></dt> +<dd>Clear the file mode bits specified by the <b>who</b> value, or, if no <b>who</b> value is specified, all of the file mode bits +specified in this volume of POSIX.1-2024. +<p>If <b>perm</b> is not specified, the <tt>'='</tt> operation shall make no further modifications to the file mode bits.</p> +<p>If <b>who</b> is not specified, the file mode bits represented by <b>perm</b> for the owner, group, and other permissions, +except for those with corresponding bits in the file mode creation mask of the invoking process, shall be set.</p> +<p>Otherwise, the file mode bits represented by the specified <b>who</b> and <b>perm</b> values shall be set.</p> +</dd> +</dl> +<p>When using the symbolic mode form on a regular file, it is implementation-defined whether or not:</p> +<ul> +<li> +<p>Requests to set the set-user-ID-on-execution or set-group-ID-on-execution bit when all execute bits are currently clear and none +are being set are ignored.</p> +</li> +<li> +<p>Requests to clear all execute bits also clear the set-user-ID-on-execution and set-group-ID-on-execution bits.</p> +</li> +<li> +<p>Requests to clear the set-user-ID-on-execution or set-group-ID-on-execution bits when all execute bits are currently clear are +ignored. However, if the command <a href="../utilities/ls.html"><i>ls</i></a> <b>-l</b> <i>file</i> writes an <i>s</i> in the +position indicating that the set-user-ID-on-execution or set-group-ID-on-execution is set, the commands <i>chmod</i> <b>u-s</b> +<i>file</i> or <i>chmod</i> <b>g-s</b> <i>file</i>, respectively, shall not be ignored.</p> +</li> +</ul> +<p>When using the symbolic mode form on other file types, it is implementation-defined whether or not requests to set or clear the +set-user-ID-on-execution or set-group-ID-on-execution bits are honored.</p> +<p>If the <b>who</b> symbol <b>o</b> is used in conjunction with the <b>perm</b> symbol <b>s</b> with no other <b>who</b> symbols +being specified, the set-user-ID-on-execution and set-group-ID-on-execution bits shall not be modified. It shall not be an error to +specify the <b>who</b> symbol <b>o</b> in conjunction with the <b>perm</b> symbol <b>s</b>.</p> +<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +The <b>perm</b> symbol <b>t</b> shall specify the S_ISVTX bit. When used with a file of type directory, it can be used with the +<b>who</b> symbol <b>a</b>, or with no <b>who</b> symbol. It shall not be an error to specify a <b>who</b> symbol of <b>u</b>, +<b>g</b>, or <b>o</b> in conjunction with the <b>perm</b> symbol <b>t</b>, but the meaning of these combinations is unspecified. +The effect when using the <b>perm</b> symbol <b>t</b> with any file type other than directory is unspecified. <img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></p> +<p>For an octal integer <i>mode</i> operand, the file mode bits shall be set absolutely.</p> +<p>For each bit set in the octal number, the corresponding file permission bit shown in the following table shall be set; all other +file permission bits shall be cleared. For regular files, for each bit set in the octal number corresponding to the +set-user-ID-on-execution or the set-group-ID-on-execution, bits shown in the following table shall be set; if these bits are not +set in the octal number, they are cleared. For other file types, it is implementation-defined whether or not requests to set or +clear the set-user-ID-on-execution or set-group-ID-on-execution bits are honored.</p> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Octal</b></p> +</th> +<th align="center"> +<p class="tent"><b>Mode Bit</b></p> +</th> +<th align="center"> +<p class="tent"><b>Octal</b></p> +</th> +<th align="center"> +<p class="tent"><b>Mode Bit</b></p> +</th> +<th align="center"> +<p class="tent"><b>Octal</b></p> +</th> +<th align="center"> +<p class="tent"><b>Mode Bit</b></p> +</th> +<th align="center"> +<p class="tent"><b>Octal</b></p> +</th> +<th align="center"> +<p class="tent"><b>Mode Bit</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>4000</b></p> +</td> +<td align="left"> +<p class="tent">S_ISUID</p> +</td> +<td align="left"> +<p class="tent"><b>0400</b></p> +</td> +<td align="left"> +<p class="tent">S_IRUSR</p> +</td> +<td align="left"> +<p class="tent"><b>0040</b></p> +</td> +<td align="left"> +<p class="tent">S_IRGRP</p> +</td> +<td align="left"> +<p class="tent"><b>0004</b></p> +</td> +<td align="left"> +<p class="tent">S_IROTH</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>2000</b></p> +</td> +<td align="left"> +<p class="tent">S_ISGID</p> +</td> +<td align="left"> +<p class="tent"><b>0200</b></p> +</td> +<td align="left"> +<p class="tent">S_IWUSR</p> +</td> +<td align="left"> +<p class="tent"><b>0020</b></p> +</td> +<td align="left"> +<p class="tent">S_IWGRP</p> +</td> +<td align="left"> +<p class="tent"><b>0002</b></p> +</td> +<td align="left"> +<p class="tent">S_IWOTH</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b><img src="../images/opt-start.gif" border="0">1000</b></p> +</td> +<td align="left"> +<p class="tent">S_ISVTX<img src="../images/opt-end.gif" border="0"></p> +</td> +<td align="left"> +<p class="tent"><b>0100</b></p> +</td> +<td align="left"> +<p class="tent">S_IXUSR</p> +</td> +<td align="left"> +<p class="tent"><b>0010</b></p> +</td> +<td align="left"> +<p class="tent">S_IXGRP</p> +</td> +<td align="left"> +<p class="tent"><b>0001</b></p> +</td> +<td align="left"> +<p class="tent">S_IXOTH</p> +</td> +</tr> +</table> +</center> +<p class="tent">When bits are set in the octal number other than those listed in the table above, the behavior is unspecified.</p> +<h5><a name="tag_20_17_13_01" id="tag_20_17_13_01"></a>Grammar for chmod</h5> +<p class="tent">The grammar and lexical conventions in this section describe the syntax for the <i>symbolic_mode</i> operand. The +general conventions for this style of grammar are described in <a href="../utilities/V3_chap01.html#tag_18_03"><i>1.3 Grammar +Conventions</i></a> . A valid <i>symbolic_mode</i> can be represented as the non-terminal symbol <i>symbolic_mode</i> in the +grammar. This formal syntax shall take precedence over the preceding text syntax description.</p> +<p class="tent">The lexical processing is based entirely on single characters. Implementations need not allow <blank> +characters within the single argument being processed.</p> +<pre> +<tt>%start symbolic_mode +%% +<br class="tent"> +symbolic_mode : clause + | symbolic_mode ',' clause + ; +<br class="tent"> +clause : actionlist + | wholist actionlist + ; +<br class="tent"> +wholist : who + | wholist who + ; +<br class="tent"> +who : 'u' | 'g' | 'o' | 'a' + ; +<br class="tent"> +actionlist : action + | actionlist action + ; +<br class="tent"> +action : op + | op permlist + | op permcopy + ; +<br class="tent"> +permcopy : 'u' | 'g' | 'o' + ; +<br class="tent"> +op : '+' | '-' | '=' + ; +<br class="tent"> +permlist : perm + | perm permlist + ; +<br class="tent"> +<sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> +perm : 'r' | 'w' | 'x' | 'X' | 's' |<img src="../images/opt-start.gif" border="0"> 't' <img src= +"../images/opt-end.gif" border="0"> + ; +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_17_14" id="tag_20_17_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>The utility executed successfully and all requested changes were made.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_17_15" id="tag_20_17_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_17_16" id="tag_20_17_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Some implementations of the <i>chmod</i> utility change the mode of a directory before the files in the directory when +performing a recursive (<b>-R</b> option) change; others change the directory mode after the files in the directory. If an +application tries to remove read or search permission for a file hierarchy, the removal attempt fails if the directory is changed +first; on the other hand, trying to re-enable permissions to a restricted hierarchy fails if directories are changed last. Users +should not try to make a hierarchy inaccessible to themselves.</p> +<p class="tent">Some implementations of <i>chmod</i> never used the <a href="../utilities/umask.html"><i>umask</i></a> of the +process when changing modes; systems conformant with this volume of POSIX.1-2024 do so when <b>who</b> is not specified. Note the +difference between:</p> +<pre> +<tt>chmod a-w file +</tt></pre> +<p class="tent">which removes all write permissions, and:</p> +<pre> +<tt>chmod -- -w file +</tt></pre> +<p class="tent">which removes write permissions that would be allowed if <b>file</b> was created with the same <a href= +"../utilities/umask.html"><i>umask</i></a>.</p> +<p class="tent">Conforming applications should never assume that they know how the set-user-ID and set-group-ID bits on directories +are interpreted.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_17_17" id="tag_20_17_17"></a>EXAMPLES</h4> +<blockquote> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Mode</b></p> +</th> +<th align="center"> +<p class="tent"><b>Results</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>a</i>+=</p> +</td> +<td align="left"> +<p class="tent">Equivalent to <i>a</i>+,<i>a</i>=; clears all file mode bits.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>go</i>+-w</p> +</td> +<td align="left"> +<p class="tent">Equivalent to <i>go</i>+,<i>go</i>-<i>w</i>; clears group and other write bits.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>g</i>=<i>o</i>-<i>w</i></p> +</td> +<td align="left"> +<p class="tent">Equivalent to <i>g</i>=<i>o</i>,<i>g</i>-<i>w</i>; sets group bit to match other bits and then clears group write +bit.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>g</i>-<i>r</i>+<i>w</i></p> +</td> +<td align="left"> +<p class="tent">Equivalent to <i>g</i>-<i>r</i>,<i>g</i>+<i>w</i>; clears group read bit and sets group write bit.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>uo</i>=<i>g</i></p> +</td> +<td align="left"> +<p class="tent">Sets owner bits to match group bits and sets other bits to match group bits.</p> +</td> +</tr> +</table> +</center> +</blockquote> +<h4 class="mansect"><a name="tag_20_17_18" id="tag_20_17_18"></a>RATIONALE</h4> +<blockquote> +<p>The functionality of <i>chmod</i> is described substantially through references to concepts defined in the System Interfaces +volume of POSIX.1-2024. In this way, there is less duplication of effort required for describing the interactions of permissions. +However, the behavior of this utility is not described in terms of the <a href="../functions/chmod.html"><i>chmod</i>()</a> +function from the System Interfaces volume of POSIX.1-2024 because that specification requires certain side-effects upon alternate +file access control mechanisms that might not be appropriate, depending on the implementation.</p> +<p class="tent">Implementations that support mandatory file and record locking as specified by the 1984 /usr/group standard +historically used the combination of set-group-ID bit set and group execute bit clear to indicate mandatory locking. This condition +is usually set or cleared with the symbolic mode <b>perm</b> symbol <b>l</b> instead of the <b>perm</b> symbols <b>s</b> and +<b>x</b> so that the mandatory locking mode is not changed without explicit indication that that was what the user intended. +Therefore, the details on how the implementation treats these conditions must be defined in the documentation. This volume of +POSIX.1-2024 does not require mandatory locking (nor does the System Interfaces volume of POSIX.1-2024), but does allow it as an +extension. However, this volume of POSIX.1-2024 does require that the <a href="../utilities/ls.html"><i>ls</i></a> and <i>chmod</i> +utilities work consistently in this area. If <a href="../utilities/ls.html"><i>ls</i></a> <b>-l</b> <i>file</i> indicates that the +set-group-ID bit is set, <i>chmod</i> <b>g-s</b> <i>file</i> must clear it (assuming appropriate privileges exist to change +modes).</p> +<p class="tent">The System V and BSD versions use different exit status codes. Some implementations used the exit status as a count +of the number of errors that occurred; this practice is unworkable since it can overflow the range of valid exit status values. +This problem is avoided here by specifying only 0 and >0 as exit values.</p> +<p class="tent">The System Interfaces volume of POSIX.1-2024 indicates that implementation-defined restrictions may cause the +S_ISUID and S_ISGID bits to be ignored. This volume of POSIX.1-2024 allows the <i>chmod</i> utility to choose to modify these bits +before calling <a href="../functions/chmod.html"><i>chmod</i>()</a> (or some function providing equivalent capabilities) for +non-regular files. Among other things, this allows implementations that use the set-user-ID and set-group-ID bits on directories to +enable extended features to handle these extensions in an intelligent manner.</p> +<p class="tent">The <b>X</b> <b>perm</b> symbol was adopted from BSD-based systems because it provides commonly desired +functionality when doing recursive (<b>-R</b> option) modifications. Similar functionality is not provided by the <a href= +"../utilities/find.html"><i>find</i></a> utility. Historical BSD versions of <i>chmod</i>, however, only supported <b>X</b> with +<i>op</i>+; it has been extended in this volume of POSIX.1-2024 because it is also useful with <i>op</i>=. (It has also been added +for <i>op</i>- even though it duplicates <b>x</b>, in this case, because it is intuitive and easier to explain.)</p> +<p class="tent">The grammar was extended with the <i>permcopy</i> non-terminal to allow historical-practice forms of symbolic modes +like <b>o</b>=<b>u</b> <b>-g</b> (that is, set the "other" permissions to the permissions of "owner" minus the permissions of +"group").</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_17_19" id="tag_20_17_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_17_20" id="tag_20_17_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/ls.html#"><i>ls</i></a> , <a href="../utilities/umask.html#tag_20_132"><i>umask</i></a></p> +<p class="tent">XBD <a href="../basedefs/V1_chap04.html#tag_04_07"><i>4.7 File Access Permissions</i></a> , <a href= +"../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 +Utility Syntax Guidelines</i></a></p> +<p class="tent">XSH <a href="../functions/chmod.html#tag_17_72"><i>chmod</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_17_21" id="tag_20_17_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_17_22" id="tag_20_17_22"></a>Issue 6</h4> +<blockquote> +<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p> +<ul> +<li class="tent">Octal modes have been kept and made mandatory despite being marked obsolescent in the ISO POSIX-2:1993 +standard.</li> +</ul> +<p class="tent">IEEE PASC Interpretation 1003.2 #172 is applied, changing the CONSEQUENCES OF ERRORS section to "Default.".</p> +<p class="tent">The Open Group Base Resolution bwg2001-010 is applied, adding the description of the S_ISVTX bit and the +<b>t perm</b> symbol as part of the XSI option.</p> +<p class="tent">IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/16 is applied, changing the XSI shaded text in the +EXTENDED DESCRIPTION from:</p> +<blockquote>"The <b>perm</b> symbol <b>t</b> shall specify the S_ISVTX bit and shall apply to directories only. The effect when +using it with any other file type is unspecified. It can be used with the <b>who</b> symbols <b>o</b>, <b>a</b>, or with no +<b>who</b> symbol. It shall not be an error to specify a <b>who</b> symbol of <b>u</b> or <b>g</b> in conjunction with the +<b>perm</b> symbol <b>t</b>; it shall be ignored for <b>u</b> and <b>g</b>."</blockquote> +<p class="tent">to:</p> +<blockquote>"The <b>perm</b> symbol <b>t</b> shall specify the S_ISVTX bit. When used with a file of type directory, it can be +used with the <b>who</b> symbol <b>a</b>, or with no <b>who</b> symbol. It shall not be an error to specify a <b>who</b> symbol of +<b>u</b>, <b>g</b>, or <b>o</b> in conjunction with the <b>perm</b> symbol <b>t</b>, but the meaning of these combinations is +unspecified. The effect when using the <b>perm</b> symbol <b>t</b> with any file type other than directory is +unspecified."</blockquote> +<p class="tent">This change is to permit historical behavior.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_17_23" id="tag_20_17_23"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p class="tent">Austin Group Interpretation 1003.1-2001 #130 is applied, adding text to the DESCRIPTION about about marking for +update the last file status change timestamp of the file.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_17_24" id="tag_20_17_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/chgrp.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/chown.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/chown.html b/bdd/chown.html @@ -0,0 +1,277 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>chown</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/chmod.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/cksum.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="chown" id="chown"></a> <a name="tag_20_18" id="tag_20_18"></a><!-- chown --> +<h4 class="mansect"><a name="tag_20_18_01" id="tag_20_18_01"></a>NAME</h4> +<blockquote>chown — change the file ownership</blockquote> +<h4 class="mansect"><a name="tag_20_18_02" id="tag_20_18_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>chown</tt> <b>[</b><tt>-h</tt><b>]</b> <i>owner</i><b>[</b><tt>:</tt><i>group</i><b>]</b> <i>file</i><tt>...<br> +<br> +chown -R</tt> <b>[</b><tt>-H|-L|-P</tt><b>]</b> <i>owner</i><b>[</b><tt>:</tt><i>group</i><b>]</b> <i>file</i><tt>...<br></tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_18_03" id="tag_20_18_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>chown</i> utility shall set the user ID of the file named by each <i>file</i> operand to the user ID specified by the +<i>owner</i> operand.</p> +<p>For each <i>file</i> operand, or, if the <b>-R</b> option is used, each file encountered while walking the directory trees +specified by the <i>file</i> operands, the <i>chown</i> utility shall perform actions equivalent to the <a href= +"../functions/chown.html"><i>chown</i>()</a> function defined in the System Interfaces volume of POSIX.1-2024, called with the +following arguments:</p> +<ol> +<li> +<p>The <i>file</i> operand shall be used as the <i>path</i> argument.</p> +</li> +<li> +<p>The user ID indicated by the <i>owner</i> portion of the first operand shall be used as the <i>owner</i> argument.</p> +</li> +<li> +<p>If the <i>group</i> portion of the first operand is given, the group ID indicated by it shall be used as the <i>group</i> +argument; otherwise, the group ownership shall not be changed.</p> +</li> +</ol> +<p>Unless <i>chown</i> is invoked by a process with appropriate privileges, the set-user-ID and set-group-ID bits of a regular file +shall be cleared upon successful completion; the set-user-ID and set-group-ID bits of other file types may be cleared.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_18_04" id="tag_20_18_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>chown</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported by the implementation:</p> +<dl compact> +<dd></dd> +<dt><b>-h</b></dt> +<dd>For each file operand that names a file of type symbolic link, <i>chown</i> shall attempt to set the user ID of the symbolic +link. If a group ID was specified, for each file operand that names a file of type symbolic link, <i>chown</i> shall attempt to set +the group ID of the symbolic link.</dd> +<dt><b>-H</b></dt> +<dd>If the <b>-R</b> option is specified and a symbolic link referencing a file of type directory is specified on the command line, +<i>chown</i> shall change the user ID (and group ID, if specified) of the directory referenced by the symbolic link and all files +in the file hierarchy below it.</dd> +<dt><b>-L</b></dt> +<dd>If the <b>-R</b> option is specified and a symbolic link referencing a file of type directory is specified on the command line +or encountered during the traversal of a file hierarchy, <i>chown</i> shall change the user ID (and group ID, if specified) of the +directory referenced by the symbolic link and all files in the file hierarchy below it.</dd> +<dt><b>-P</b></dt> +<dd>If the <b>-R</b> option is specified and a symbolic link is specified on the command line or encountered during the traversal +of a file hierarchy, <i>chown</i> shall change the owner ID (and group ID, if specified) of the symbolic link. The <i>chown</i> +utility shall not follow the symbolic link to any other part of the file hierarchy.</dd> +<dt><b>-R</b></dt> +<dd>Recursively change file user and group IDs. For each <i>file</i> operand that names a directory, <i>chown</i> shall change the +user ID (and group ID, if specified) of the directory and all files in the file hierarchy below it. Unless a <b>-H</b>, <b>-L</b>, +or <b>-P</b> option is specified, it is unspecified which of these options will be used as the default.</dd> +</dl> +<p>Specifying more than one of the mutually-exclusive options <b>-H</b>, <b>-L</b>, and <b>-P</b> shall not be considered an error. +The last option specified shall determine the behavior of the utility.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_18_05" id="tag_20_18_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>owner</i><b>[</b>:<i>group</i><b>]</b></dt> +<dd>A user ID and optional group ID to be assigned to <i>file</i>. The <i>owner</i> portion of this operand shall be a user name +from the user database or a numeric user ID. Either specifies a user ID which shall be given to each file named by one of the +<i>file</i> operands. If a numeric <i>owner</i> operand exists in the user database as a user name, the user ID number associated +with that user name shall be used as the user ID. Similarly, if the <i>group</i> portion of this operand is present, it shall be a +group name from the group database or a numeric group ID. Either specifies a group ID which shall be given to each file. If a +numeric group operand exists in the group database as a group name, the group ID number associated with that group name shall be +used as the group ID.</dd> +<dt><i>file</i></dt> +<dd>A pathname of a file whose user ID is to be modified.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_18_06" id="tag_20_18_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_18_07" id="tag_20_18_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_18_08" id="tag_20_18_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>chown</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_18_09" id="tag_20_18_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_18_10" id="tag_20_18_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_18_11" id="tag_20_18_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_18_12" id="tag_20_18_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_18_13" id="tag_20_18_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_18_14" id="tag_20_18_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>The utility executed successfully and all requested changes were made.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_18_15" id="tag_20_18_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_18_16" id="tag_20_18_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Only the owner of a file or the user with appropriate privileges may change the owner or group of a file.</p> +<p>Some implementations restrict the use of <i>chown</i> to a user with appropriate privileges.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_18_17" id="tag_20_18_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_18_18" id="tag_20_18_18"></a>RATIONALE</h4> +<blockquote> +<p>The System V and BSD versions use different exit status codes. Some implementations used the exit status as a count of the +number of errors that occurred; this practice is unworkable since it can overflow the range of valid exit status values. These are +masked by specifying only 0 and >0 as exit values.</p> +<p>The functionality of <i>chown</i> is described substantially through references to functions in the System Interfaces volume of +POSIX.1-2024. In this way, there is no duplication of effort required for describing the interactions of permissions, multiple +groups, and so on.</p> +<p>The 4.3 BSD method of specifying both owner and group was included in this volume of POSIX.1-2024 because:</p> +<ul> +<li> +<p>There are cases where the desired end condition could not be achieved using the <a href= +"../utilities/chgrp.html"><i>chgrp</i></a> and <i>chown</i> (that only changed the user ID) utilities. (If the current owner is not +a member of the desired group and the desired owner is not a member of the current group, the <a href= +"../functions/chown.html"><i>chown</i>()</a> function could fail unless both owner and group are changed at the same time.)</p> +</li> +<li> +<p>Even if they could be changed independently, in cases where both are being changed, there is a 100% performance penalty caused +by being forced to invoke both utilities.</p> +</li> +</ul> +<p>The BSD syntax <i>user</i>[.<i>group</i>] was changed to <i>user</i>[:<i>group</i>] in this volume of POSIX.1-2024 because the +<period> is a valid character in login names (as specified by the Base Definitions volume of POSIX.1-2024, login names +consist of characters in the portable filename character set). The <colon> character was chosen as the replacement for the +<period> character because it would never be allowed as a character in a user name or group name on historical +implementations.</p> +<p>The <b>-R</b> option is considered by some observers as an undesirable departure from the historical UNIX system tools approach; +since a tool, <a href="../utilities/find.html"><i>find</i></a>, already exists to recurse over directories, there seemed to be no +good reason to require other tools to have to duplicate that functionality. However, the <b>-R</b> option was deemed an important +user convenience, is far more efficient than forking a separate process for each element of the directory hierarchy, and is in +widespread historical use.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_18_19" id="tag_20_18_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_18_20" id="tag_20_18_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/chgrp.html#"><i>chgrp</i></a> , <a href="../utilities/chmod.html#tag_20_17"><i>chmod</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/chown.html#tag_17_73"><i>chown</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_18_21" id="tag_20_18_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_18_22" id="tag_20_18_22"></a>Issue 6</h4> +<blockquote> +<p>New options <b>-h</b>, <b>-H</b>, <b>-L</b>, and <b>-P</b> are added to align with the IEEE P1003.2b draft standard. These +options affect the processing of symbolic links.</p> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +<p>IEEE PASC Interpretation 1003.2 #172 is applied, changing the CONSEQUENCES OF ERRORS section to "Default.".</p> +<p>The "otherwise, ..." text in item 3. of the DESCRIPTION is changed to "otherwise, the group ownership shall not be +changed".</p> +<p>IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/17 is applied, changing the SYNOPSIS to make it clear that +<b>-h</b> and <b>-R</b> are optional.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_18_23" id="tag_20_18_23"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-9 is applied, removing the <b>-R</b> from the first line of the SYNOPSIS.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>The description of the <b>-h</b> and <b>-P</b> options is revised.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_18_24" id="tag_20_18_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/chmod.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/cksum.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/cksum.html b/bdd/cksum.html @@ -0,0 +1,344 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>cksum</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/chown.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/cmp.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="cksum" id="cksum"></a> <a name="tag_20_19" id="tag_20_19"></a><!-- cksum --> +<h4 class="mansect"><a name="tag_20_19_01" id="tag_20_19_01"></a>NAME</h4> +<blockquote>cksum — write file checksums and sizes</blockquote> +<h4 class="mansect"><a name="tag_20_19_02" id="tag_20_19_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>cksum</tt> <b>[</b><i>file</i><tt>...</tt><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_19_03" id="tag_20_19_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>cksum</i> utility shall calculate and write to standard output a cyclic redundancy check (CRC) for each input file, and +also write to standard output the number of octets in each file. The CRC used is based on the polynomial used for CRC error +checking in the ISO/IEC 8802-3:1996 standard (Ethernet).</p> +<p>The encoding for the CRC checksum is defined by the generating polynomial:</p> +<pre> +<i>G</i><tt>(</tt><i>x</i><tt>)=</tt><i>x</i><tt><sup><small>32</small></sup>+</tt><i>x</i><tt><sup><small>26</small></sup>+</tt><i>x</i><tt><sup><small>23</small></sup>+</tt><i>x</i><tt><sup><small>22</small></sup>+</tt><i>x</i><tt><sup><small>16</small></sup>+</tt><i>x</i><tt><sup><small>12</small></sup>+</tt><i>x</i><tt><sup><small>11</small></sup>+</tt><i>x</i><tt><sup><small>10</small></sup>+</tt><i>x</i><tt><sup><small>8</small></sup>+</tt><i>x</i><tt><sup><small>7</small></sup>+</tt><i>x</i><tt><sup><small>5</small></sup>+</tt><i>x</i><tt><sup><small>4</small></sup>+</tt><i>x</i><tt><sup><small>2</small></sup>+</tt><i>x</i><tt>+1 +</tt></pre> +<p>Mathematically, the CRC value corresponding to a given file shall be defined by the following procedure:</p> +<ol> +<li> +<p>The <i>n</i> bits to be evaluated are considered to be the coefficients of a mod 2 polynomial <i>M</i>(<i>x</i>) of degree +<i>n</i>-1. These <i>n</i> bits are the bits from the file, with the most significant bit being the most significant bit of the +first octet of the file and the last bit being the least significant bit of the last octet, padded with zero bits (if necessary) to +achieve an integral number of octets, followed by one or more octets representing the length of the file as a binary value, least +significant octet first. The smallest number of octets capable of representing this integer shall be used.</p> +</li> +<li> +<p><i>M</i>(<i>x</i>) is multiplied by <i>x</i><sup><small>32</small></sup> (that is, shifted left 32 bits) and divided by +<i>G</i>(<i>x</i>) using mod 2 division, producing a remainder <i>R</i>(<i>x</i>) of degree <= 31.</p> +</li> +<li> +<p>The coefficients of <i>R</i>(<i>x</i>) are considered to be a 32-bit sequence.</p> +</li> +<li> +<p>The bit sequence is complemented and the result is the CRC.</p> +</li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_19_04" id="tag_20_19_04"></a>OPTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_19_05" id="tag_20_19_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of a file to be checked. If no <i>file</i> operands are specified, the standard input shall be used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_19_06" id="tag_20_19_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be used if no <i>file</i> operands are specified, and shall be used if a <i>file</i> operand is +<tt>'-'</tt> and the implementation treats the <tt>'-'</tt> as meaning standard input. Otherwise, the standard input shall not be +used. See the INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_19_07" id="tag_20_19_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files can be any file type.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_19_08" id="tag_20_19_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>cksum</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_19_09" id="tag_20_19_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_19_10" id="tag_20_19_10"></a>STDOUT</h4> +<blockquote> +<p>For each file processed successfully, the <i>cksum</i> utility shall write in the following format:</p> +<pre> +<tt>"%u %d %s\n", <</tt><i>checksum</i><tt>>, <</tt><i># of octets</i><tt>>, <</tt><i>pathname</i><tt>> +</tt></pre> +<p>If no <i>file</i> operand was specified, the pathname and its leading <space> shall be omitted.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_19_11" id="tag_20_19_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_19_12" id="tag_20_19_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_19_13" id="tag_20_19_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_19_14" id="tag_20_19_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>All files were processed successfully.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_19_15" id="tag_20_19_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_19_16" id="tag_20_19_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The <i>cksum</i> utility is typically used to quickly compare a suspect file against a trusted version of the same, such as to +ensure that files transmitted over noisy media arrive intact. However, this comparison cannot be considered cryptographically +secure. This utility should be avoided whenever non-trivial requirements (including safety and security) have to be fulfilled.</p> +<p>Although input files to <i>cksum</i> can be any type, the results need not be what would be expected on character special device +files or on file types not described by the System Interfaces volume of POSIX.1-2024. Since this volume of POSIX.1-2024 does not +specify the block size used when doing input, checksums of character special files need not process all of the data in those +files.</p> +<p>The algorithm is expressed in terms of a bitstream divided into octets. If a file is transmitted between two systems and +undergoes any data transformation (such as changing little-endian byte ordering to big-endian), identical CRC values cannot be +expected. Implementations performing such transformations may extend <i>cksum</i> to handle such situations.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_19_17" id="tag_20_19_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_19_18" id="tag_20_19_18"></a>RATIONALE</h4> +<blockquote> +<p>The <i>cksum</i> utility is included in this standard for reasons of portability but is not suitable for uses where non-trivial +requirements (including safety and security) have to be fulfilled. Implementations are encouraged to provide utilities that +implement hash and integrity checksum algorithms of higher security and to keep up to date with developments in this area.</p> +<p>The following C-language program can be used as a model to describe the algorithm. It assumes that a <b>char</b> is one octet. +It also assumes that the entire file is available for one pass through the function. This was done for simplicity in demonstrating +the algorithm, rather than as an implementation model.</p> +<pre> +<tt>static unsigned long crctab[] = { +0x00000000, +0x04c11db7, 0x09823b6e, 0x0d4326d9, 0x130476dc, 0x17c56b6b, +0x1a864db2, 0x1e475005, 0x2608edb8, 0x22c9f00f, 0x2f8ad6d6, +0x2b4bcb61, 0x350c9b64, 0x31cd86d3, 0x3c8ea00a, 0x384fbdbd, +0x4c11db70, 0x48d0c6c7, 0x4593e01e, 0x4152fda9, 0x5f15adac, +0x5bd4b01b, 0x569796c2, 0x52568b75, 0x6a1936c8, 0x6ed82b7f, +0x639b0da6, 0x675a1011, 0x791d4014, 0x7ddc5da3, 0x709f7b7a, +0x745e66cd, 0x9823b6e0, 0x9ce2ab57, 0x91a18d8e, 0x95609039, +0x8b27c03c, 0x8fe6dd8b, 0x82a5fb52, 0x8664e6e5, 0xbe2b5b58, +0xbaea46ef, 0xb7a96036, 0xb3687d81, 0xad2f2d84, 0xa9ee3033, +0xa4ad16ea, 0xa06c0b5d, 0xd4326d90, 0xd0f37027, 0xddb056fe, +0xd9714b49, 0xc7361b4c, 0xc3f706fb, 0xceb42022, 0xca753d95, +0xf23a8028, 0xf6fb9d9f, 0xfbb8bb46, 0xff79a6f1, 0xe13ef6f4, +0xe5ffeb43, 0xe8bccd9a, 0xec7dd02d, 0x34867077, 0x30476dc0, +0x3d044b19, 0x39c556ae, 0x278206ab, 0x23431b1c, 0x2e003dc5, +0x2ac12072, 0x128e9dcf, 0x164f8078, 0x1b0ca6a1, 0x1fcdbb16, +0x018aeb13, 0x054bf6a4, 0x0808d07d, 0x0cc9cdca, 0x7897ab07, +0x7c56b6b0, 0x71159069, 0x75d48dde, 0x6b93dddb, 0x6f52c06c, +0x6211e6b5, 0x66d0fb02, 0x5e9f46bf, 0x5a5e5b08, 0x571d7dd1, +0x53dc6066, 0x4d9b3063, 0x495a2dd4, 0x44190b0d, 0x40d816ba, +0xaca5c697, 0xa864db20, 0xa527fdf9, 0xa1e6e04e, 0xbfa1b04b, +0xbb60adfc, 0xb6238b25, 0xb2e29692, 0x8aad2b2f, 0x8e6c3698, +0x832f1041, 0x87ee0df6, 0x99a95df3, 0x9d684044, 0x902b669d, +0x94ea7b2a, 0xe0b41de7, 0xe4750050, 0xe9362689, 0xedf73b3e, +0xf3b06b3b, 0xf771768c, 0xfa325055, 0xfef34de2, 0xc6bcf05f, +0xc27dede8, 0xcf3ecb31, 0xcbffd686, 0xd5b88683, 0xd1799b34, +0xdc3abded, 0xd8fba05a, 0x690ce0ee, 0x6dcdfd59, 0x608edb80, +0x644fc637, 0x7a089632, 0x7ec98b85, 0x738aad5c, 0x774bb0eb, +0x4f040d56, 0x4bc510e1, 0x46863638, 0x42472b8f, 0x5c007b8a, +0x58c1663d, 0x558240e4, 0x51435d53, 0x251d3b9e, 0x21dc2629, +0x2c9f00f0, 0x285e1d47, 0x36194d42, 0x32d850f5, 0x3f9b762c, +0x3b5a6b9b, 0x0315d626, 0x07d4cb91, 0x0a97ed48, 0x0e56f0ff, +0x1011a0fa, 0x14d0bd4d, 0x19939b94, 0x1d528623, 0xf12f560e, +0xf5ee4bb9, 0xf8ad6d60, 0xfc6c70d7, 0xe22b20d2, 0xe6ea3d65, +0xeba91bbc, 0xef68060b, 0xd727bbb6, 0xd3e6a601, 0xdea580d8, +0xda649d6f, 0xc423cd6a, 0xc0e2d0dd, 0xcda1f604, 0xc960ebb3, +0xbd3e8d7e, 0xb9ff90c9, 0xb4bcb610, 0xb07daba7, 0xae3afba2, +0xaafbe615, 0xa7b8c0cc, 0xa379dd7b, 0x9b3660c6, 0x9ff77d71, +0x92b45ba8, 0x9675461f, 0x8832161a, 0x8cf30bad, 0x81b02d74, +0x857130c3, 0x5d8a9099, 0x594b8d2e, 0x5408abf7, 0x50c9b640, +0x4e8ee645, 0x4a4ffbf2, 0x470cdd2b, 0x43cdc09c, 0x7b827d21, +0x7f436096, 0x7200464f, 0x76c15bf8, 0x68860bfd, 0x6c47164a, +0x61043093, 0x65c52d24, 0x119b4be9, 0x155a565e, 0x18197087, +0x1cd86d30, 0x029f3d35, 0x065e2082, 0x0b1d065b, 0x0fdc1bec, +0x3793a651, 0x3352bbe6, 0x3e119d3f, 0x3ad08088, 0x2497d08d, +0x2056cd3a, 0x2d15ebe3, 0x29d4f654, 0xc5a92679, 0xc1683bce, +0xcc2b1d17, 0xc8ea00a0, 0xd6ad50a5, 0xd26c4d12, 0xdf2f6bcb, +0xdbee767c, 0xe3a1cbc1, 0xe760d676, 0xea23f0af, 0xeee2ed18, +0xf0a5bd1d, 0xf464a0aa, 0xf9278673, 0xfde69bc4, 0x89b8fd09, +0x8d79e0be, 0x803ac667, 0x84fbdbd0, 0x9abc8bd5, 0x9e7d9662, +0x933eb0bb, 0x97ffad0c, 0xafb010b1, 0xab710d06, 0xa6322bdf, +0xa2f33668, 0xbcb4666d, 0xb8757bda, 0xb5365d03, 0xb1f740b4 +}; +<br> +unsigned long memcrc(const unsigned char *b, size_t n) +{ +/* Input arguments: + * const unsigned char* b == byte sequence to checksum + * size_t n == length of sequence + */ +<br> + register size_t i; + register unsigned c, s = 0; +<br> + for (i = n; i > 0; --i) { + c = *b++; + s = (s << 8) ^ crctab[(s >> 24) ^ c]; + } +<br> + /* Extend with the length of the string. */ + while (n != 0) { + c = n & 0377; + n >>= 8; + s = (s << 8) ^ crctab[(s >> 24) ^ c]; + } +<br> + return ~s; +} +</tt></pre> +<p>The historical practice of writing the number of "blocks" has been changed to writing the number of octets, since the latter +is not only more useful, but also since historical implementations have not been consistent in defining what a "block" meant.</p> +<p>The algorithm used was selected to increase the operational robustness of <i>cksum</i>. Neither the System V nor BSD <i>sum</i> +algorithm was selected. Since each of these was different and each was the default behavior on those systems, no realistic +compromise was available if either were selected—some set of historical applications would break. Therefore, the name was changed +to <i>cksum</i>. Although the historical <i>sum</i> commands will probably continue to be provided for many years, programs +designed for portability across systems should use the new name.</p> +<p>The algorithm selected is based on that used by the ISO/IEC 8802-3:1996 standard (Ethernet) for the frame check sequence +field. The algorithm used does not match the technical definition of a <i>checksum</i>; the term is used for historical reasons. +The length of the file is included in the CRC calculation because this parallels inclusion of a length field by Ethernet in its +CRC, but also because it guards against inadvertent collisions between files that begin with different series of zero octets. The +chance that two different files produce identical CRCs is much greater when their lengths are not considered. Keeping the length +and the checksum of the file itself separate would yield a slightly more robust algorithm, but historical usage has always been +that a single number (the checksum as printed) represents the signature of the file. It was decided that historical usage was the +more important consideration.</p> +<p>Early proposals contained modifications to the Ethernet algorithm that involved extracting table values whenever an intermediate +result became zero. This was demonstrated to be less robust than the current method and mathematically difficult to describe or +justify.</p> +<p>The calculation used is identical to that given in pseudo-code in the referenced Sarwate article. The pseudo-code rendition +is:</p> +<pre> +<tt>X <- 0; Y <- 0; +for i <- m -1 step -1 until 0 do + begin + T <- X(1) ^ A[i]; + X(1) <- X(0); X(0) <- Y(1); Y(1) <- Y(0); Y(0) <- 0; + comment: f[T] and f'[T] denote the T-th words in the + table f and f' ; + X <- X ^ f[T]; Y <- Y ^ f'[T]; + end +</tt></pre> +<p>The pseudo-code is reproduced exactly as given; however, note that in the case of <i>cksum</i>, <b>A[i]</b> represents a byte of +the file, the words <b>X</b> and <b>Y</b> are treated as a single 32-bit value, and the tables <b>f</b> and <b>f'</b> are a single +table containing 32-bit values.</p> +<p>The referenced Sarwate article also discusses generating the table.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_19_19" id="tag_20_19_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_19_20" id="tag_20_19_20"></a>SEE ALSO</h4> +<blockquote> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_19_21" id="tag_20_19_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_19_22" id="tag_20_19_22"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #092 is applied.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0081 [446] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_19_23" id="tag_20_19_23"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to report an error if a utility is directed to display a +pathname that contains any bytes that have the encoded value of a <newline> character when <newline> is a terminator or +separator in the output format being used.</p> +<p>Austin Group Defect 1041 is applied, changing the APPLICATION USAGE and RATIONALE sections.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/chown.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/cmp.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/cmp.html b/bdd/cmp.html @@ -0,0 +1,266 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>cmp</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/cksum.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/comm.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="cmp" id="cmp"></a> <a name="tag_20_20" id="tag_20_20"></a><!-- cmp --> +<h4 class="mansect"><a name="tag_20_20_01" id="tag_20_20_01"></a>NAME</h4> +<blockquote>cmp — compare two files</blockquote> +<h4 class="mansect"><a name="tag_20_20_02" id="tag_20_20_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>cmp</tt> <b>[</b><tt>-l|-s</tt><b>]</b> <i>file1 file2</i></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_20_03" id="tag_20_20_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>cmp</i> utility shall compare two files. The <i>cmp</i> utility shall write no output if the files are the same. Under +default options, if they differ, it shall write to standard output the byte and line number at which the first difference occurred. +Bytes and lines shall be numbered beginning with 1.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_20_04" id="tag_20_20_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>cmp</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-l</b></dt> +<dd>(Lowercase ell.) Write the byte number (decimal) and the differing bytes (octal) for each difference.</dd> +<dt><b>-s</b></dt> +<dd>Write nothing to standard output or standard error when files differ; indicate differing files through exit status only. It is +unspecified whether a diagnostic message is written to standard error when an error is encountered; if a message is not written, +the error is indicated through exit status only.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_20_05" id="tag_20_20_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file1</i></dt> +<dd>A pathname of the first file to be compared. If <i>file1</i> is <tt>'-'</tt>, the standard input shall be used.</dd> +<dt><i>file2</i></dt> +<dd>A pathname of the second file to be compared. If <i>file2</i> is <tt>'-'</tt>, the standard input shall be used.</dd> +</dl> +<p>If both <i>file1</i> and <i>file2</i> refer to standard input or refer to the same FIFO special, block special, or character +special file, the results are undefined.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_20_06" id="tag_20_20_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be used only if the <i>file1</i> or <i>file2</i> operand refers to standard input. See the INPUT FILES +section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_20_07" id="tag_20_20_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files can be any file type.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_20_08" id="tag_20_20_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>cmp</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error and +informative messages written to standard output.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_20_09" id="tag_20_20_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_20_10" id="tag_20_20_10"></a>STDOUT</h4> +<blockquote> +<p>In the POSIX locale, results of the comparison shall be written to standard output. When no options are used, the format shall +be:</p> +<pre> +<tt>"%s %s differ: char %d, line %d\n", </tt><i>file1</i><tt>, </tt><i>file2</i><tt>, + <</tt><i>byte number</i><tt>>, <</tt><i>line number</i><tt>> +</tt></pre> +<p>When the <b>-l</b> option is used, the format shall be:</p> +<pre> +<tt>"%d %o %o\n", <</tt><i>byte number</i><tt>>, <</tt><i>differing byte</i><tt>>, + <</tt><i>differing byte</i><tt>> +</tt></pre> +<p>for each byte that differs. The first <<i>differing byte</i>> number is from <i>file1</i> while the second is from +<i>file2</i>. In both cases, <<i>byte number</i>> shall be relative to the beginning of the file, beginning with 1.</p> +<p>No output shall be written to standard output when the <b>-s</b> option is used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_20_11" id="tag_20_20_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages. If the <b>-l</b> option is used and <i>file1</i> and <i>file2</i> +differ in length, or if the <b>-s</b> option is not used and <i>file1</i> and <i>file2</i> are identical for the entire length of +the shorter file, in the POSIX locale the following diagnostic message shall be written:</p> +<pre> +<tt>"cmp: EOF on %s%s\n", <</tt><i>name of shorter file</i><tt>>, <</tt><i>additional info</i><tt>> +</tt></pre> +<p>The <<i>additional info</i>> field shall either be null or a string that starts with a <blank> and contains no +<newline> characters. Some implementations report on the number of lines in this case.</p> +<p>If the <b>-s</b> option is used and an error occurs, it is unspecified whether a diagnostic message is written to standard +error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_20_12" id="tag_20_20_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_20_13" id="tag_20_20_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_20_14" id="tag_20_20_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>The files are identical.</dd> +<dt> 1</dt> +<dd>The files are different; this includes the case where one file is identical to the first part of the other.</dd> +<dt>>1</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_20_15" id="tag_20_20_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_20_16" id="tag_20_20_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Although input files to <i>cmp</i> can be any type, the results might not be what would be expected on character special device +files or on file types not described by the System Interfaces volume of POSIX.1-2024. Since this volume of POSIX.1-2024 does not +specify the block size used when doing input, comparisons of character special files need not compare all of the data in those +files.</p> +<p>For files which are not text files, line numbers simply reflect the presence of a <newline>, without any implication that +the file is organized into lines.</p> +<p>Since the behavior of <b>-s</b> differs between implementations as to whether error messages are written, the only way to ensure +consistent behavior of <i>cmp</i> when <b>-s</b> is used is to redirect standard error to <b>/dev/null</b>.</p> +<p>If error messages are wanted, instead of using <b>-s</b> standard output should be redirected to <b>/dev/null</b>, and anything +written to standard error should be discarded if the exit status is 1. For example:</p> +<pre> +<tt>silent_cmp() { + # compare files with no output except error messages + message=$(cmp "$@" 2>&1 >/dev/null) + status=$? + case $status in + (0|1) ;; + (*) printf '%s\n' "$message" ;; + esac + return $status +} +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_20_17" id="tag_20_20_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_20_18" id="tag_20_20_18"></a>RATIONALE</h4> +<blockquote> +<p>The global language in <a href="../utilities/V3_chap01.html#tag_18_04"><i>1.4 Utility Description Defaults</i></a> indicates +that using two mutually-exclusive options together produces unspecified results. Some System V implementations consider the option +usage:</p> +<pre> +<tt>cmp -l -s ... +</tt></pre> +<p>to be an error. They also treat:</p> +<pre> +<tt>cmp -s -l ... +</tt></pre> +<p>as if no options were specified. Both of these behaviors are considered bugs, but are allowed.</p> +<p>The word <b>char</b> in the standard output format comes from historical usage, even though it is actually a byte number. When +<i>cmp</i> is supported in other locales, implementations are encouraged to use the word <i>byte</i> or its equivalent in another +language. Users should not interpret this difference to indicate that the functionality of the utility changed between locales.</p> +<p>Some implementations report on the number of lines in the identical-but-shorter file case. This is allowed by the inclusion of +the <<i>additional info</i>> fields in the output format. The restriction on having a leading <blank> and no +<newline> characters is to make parsing for the filename easier. It is recognized that some filenames containing white-space +characters make parsing difficult anyway, but the restriction does aid programs used on systems where the names are predominantly +well behaved.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_20_19" id="tag_20_20_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +<p>Future versions of this standard may require that diagnostic messages are written to standard error when the <b>-s</b> option is +specified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_20_20" id="tag_20_20_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/comm.html#"><i>comm</i></a> , <a href="../utilities/diff.html#"><i>diff</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_20_21" id="tag_20_20_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_20_22" id="tag_20_20_22"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-96 is applied, updating the STDERR section.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0075 [478] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_20_23" id="tag_20_20_23"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to report an error if a utility is directed to display a +pathname that contains any bytes that have the encoded value of a <newline> character when <newline> is a terminator or +separator in the output format being used.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/cksum.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/comm.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/comm.html b/bdd/comm.html @@ -0,0 +1,275 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>comm</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/cmp.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/command.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="comm" id="comm"></a> <a name="tag_20_21" id="tag_20_21"></a><!-- comm --> +<h4 class="mansect"><a name="tag_20_21_01" id="tag_20_21_01"></a>NAME</h4> +<blockquote>comm — select or reject lines common to two files</blockquote> +<h4 class="mansect"><a name="tag_20_21_02" id="tag_20_21_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>comm</tt> <b>[</b><tt>-123</tt><b>]</b> <i>file1 file2</i></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_21_03" id="tag_20_21_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>comm</i> utility shall read <i>file1</i> and <i>file2</i>, which should be ordered in the current collating sequence, and +produce three text columns as output: lines only in <i>file1</i>, lines only in <i>file2</i>, and lines in both files.</p> +<p>If the lines in both files are not ordered according to the collating sequence of the current locale, the results are +unspecified.</p> +<p>If the collating sequence of the current locale does not have a total ordering of all characters (see XBD <a href= +"../basedefs/V1_chap07.html#tag_07_03_02"><i>7.3.2 LC_COLLATE</i></a> ) and any lines from the input files collate equally but are +not identical, <i>comm</i> shall treat them as different lines and shall expect them to be ordered according to a further +byte-by-byte comparison using the collating sequence for the POSIX locale; if they are not ordered in this way, the output of +<i>comm</i> can identify such lines as being both unique to <i>file1</i> and unique to <i>file2</i> instead of being in both +files.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_21_04" id="tag_20_21_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>comm</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-1</b></dt> +<dd>Suppress the output column of lines unique to <i>file1</i>.</dd> +<dt><b>-2</b></dt> +<dd>Suppress the output column of lines unique to <i>file2</i>.</dd> +<dt><b>-3</b></dt> +<dd>Suppress the output column of lines duplicated in <i>file1</i> and <i>file2</i>.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_21_05" id="tag_20_21_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file1</i></dt> +<dd>A pathname of the first file to be compared. If <i>file1</i> is <tt>'-'</tt>, the standard input shall be used.</dd> +<dt><i>file2</i></dt> +<dd>A pathname of the second file to be compared. If <i>file2</i> is <tt>'-'</tt>, the standard input shall be used.</dd> +</dl> +<p>If both <i>file1</i> and <i>file2</i> refer to standard input or to the same FIFO special, block special, or character special +file, the results are undefined.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_21_06" id="tag_20_21_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be used only if one of the <i>file1</i> or <i>file2</i> operands refers to standard input. See the +INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_21_07" id="tag_20_21_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files shall be text files.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_21_08" id="tag_20_21_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>comm</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_COLLATE</i></dt> +<dd><br> +Determine the locale for the collating sequence <i>comm</i> expects to have been used when the input files were sorted.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_21_09" id="tag_20_21_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_21_10" id="tag_20_21_10"></a>STDOUT</h4> +<blockquote> +<p>The <i>comm</i> utility shall produce output depending on the options selected. If the <b>-1</b>, <b>-2</b>, and <b>-3</b> +options are all selected, <i>comm</i> shall write nothing to standard output.</p> +<p>If the <b>-1</b> option is not selected, lines contained only in <i>file1</i> shall be written using the format:</p> +<pre> +<tt>"%s\n", <</tt><i>line in file1</i><tt>> +</tt></pre> +<p>If the <b>-2</b> option is not selected, lines contained only in <i>file2</i> are written using the format:</p> +<pre> +<tt>"%s%s\n", <</tt><i>lead</i><tt>>, <</tt><i>line in file2</i><tt>> +</tt></pre> +<p>where the string <<i>lead</i>> is as follows:</p> +<dl compact> +<dd></dd> +<dt><tab></dt> +<dd>The <b>-1</b> option is not selected.</dd> +<dt>null string</dt> +<dd>The <b>-1</b> option is selected.</dd> +</dl> +<p>If the <b>-3</b> option is not selected, lines contained in both files shall be written using the format:</p> +<pre> +<tt>"%s%s\n", <</tt><i>lead</i><tt>>, <</tt><i>line in both</i><tt>> +</tt></pre> +<p>where the string <<i>lead</i>> is as follows:</p> +<dl compact> +<dd></dd> +<dt><tab><tab></dt> +<dd>Neither the <b>-1</b> nor the <b>-2</b> option is selected.</dd> +<dt><tab></dt> +<dd>Exactly one of the <b>-1</b> and <b>-2</b> options is selected.</dd> +<dt>null string</dt> +<dd>Both the <b>-1</b> and <b>-2</b> options are selected.</dd> +</dl> +<p>If the input files were ordered according to the collating sequence of the current locale, the lines written shall be in the +collating sequence of the current locale. If the input files contained any lines that collated equally but were not identical and +within each file those lines were ordered according to a further byte-by-byte comparison using the collating sequence for the POSIX +locale, then lines written that collate equally but are not identical shall be ordered according to a further byte-by-byte +comparison using the collating sequence for the POSIX locale.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_21_11" id="tag_20_21_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_21_12" id="tag_20_21_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_21_13" id="tag_20_21_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_21_14" id="tag_20_21_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>All input files were successfully output as specified.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_21_15" id="tag_20_21_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_21_16" id="tag_20_21_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>If the input files are not properly presorted, the output of <i>comm</i> might not be useful.</p> +<p>When using <i>comm</i> to process pathnames, it is recommended that LC_ALL, or at least LC_CTYPE and LC_COLLATE, are set to +POSIX or C in the environment, since pathnames can contain byte sequences that do not form valid characters in some locales, in +which case the utility's behavior would be undefined. In the POSIX locale each byte is a valid single-byte character, and therefore +this problem is avoided.</p> +<p>If the collating sequence of the current locale does not have a total ordering of all characters, since <i>comm</i> treats lines +as being the same only if they are identical, some lines can be misleadingly identified as being both unique to <i>file1</i> and +unique to <i>file2</i> if lines that collate equally but are not identical are not ordered in the way that <i>comm</i> expects. If +the input does not come from utilities (such as <a href="../utilities/ls.html"><i>ls</i></a> and <a href= +"../utilities/sort.html"><i>sort</i></a>) which provide this ordering, the problem can be avoided by pre-sorting the input files +using <a href="../utilities/sort.html"><i>sort</i></a>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_21_17" id="tag_20_21_17"></a>EXAMPLES</h4> +<blockquote> +<p>If a file named <b>xcu</b> contains a sorted list of the utilities in this volume of POSIX.1-2024, a file named <b>xpg3</b> +contains a sorted list of the utilities specified in the X/Open Portability Guide, Issue 3, and a file named <b>svid89</b> contains +a sorted list of the utilities in the System V Interface Definition Third Edition:</p> +<pre> +<tt>comm -23 xcu xpg3 | comm -23 - svid89 +</tt></pre> +<p>would print a list of utilities in this volume of POSIX.1-2024 not specified by either of the other documents:</p> +<pre> +<tt>comm -12 xcu xpg3 | comm -12 - svid89 +</tt></pre> +<p>would print a list of utilities specified by all three documents, and:</p> +<pre> +<tt>comm -12 xpg3 svid89 | comm -23 - xcu +</tt></pre> +<p>would print a list of utilities specified by both XPG3 and the SVID, but not specified in this volume of POSIX.1-2024.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_21_18" id="tag_20_21_18"></a>RATIONALE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_21_19" id="tag_20_21_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_21_20" id="tag_20_21_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/cmp.html#"><i>cmp</i></a> , <a href="../utilities/diff.html#"><i>diff</i></a> , <a href= +"../utilities/sort.html#"><i>sort</i></a> , <a href="../utilities/uniq.html#"><i>uniq</i></a></p> +<p>XBD <a href="../basedefs/V1_chap07.html#tag_07_03_02"><i>7.3.2 LC_COLLATE</i></a> , <a href= +"../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 +Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_21_21" id="tag_20_21_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_21_22" id="tag_20_21_22"></a>Issue 6</h4> +<blockquote> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_21_23" id="tag_20_21_23"></a>Issue 7</h4> +<blockquote> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0076 [963], XCU/TC2-2008/0077 [663], and XCU/TC2-2008/0078 [963] are +applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_21_24" id="tag_20_21_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1070 is applied, changing the requirements when any lines from the input files collate equally but are not +identical.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/cmp.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/command.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/command.html b/bdd/command.html @@ -0,0 +1,457 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>command</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/comm.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/compress.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="command" id="command"></a> <a name="tag_20_22" id="tag_20_22"></a><!-- command --> +<h4 class="mansect"><a name="tag_20_22_01" id="tag_20_22_01"></a>NAME</h4> +<blockquote>command — execute a simple command</blockquote> +<h4 class="mansect"><a name="tag_20_22_02" id="tag_20_22_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>command</tt> <b>[</b><tt>-p</tt><b>]</b> <i>command_name</i> <b>[</b><i>argument</i><tt>...</tt><b>]</b> <tt><br> +<br> +command</tt> <b>[</b><tt>-p</tt><b>][</b><tt>-v|-V</tt><b>]</b> <i>command_name</i> <tt><br></tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_22_03" id="tag_20_22_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>command</i> utility shall cause the shell to treat the arguments as a simple command, suppressing the shell function +lookup that is described in <a href="../utilities/V3_chap02.html#tag_19_09_01_04"><i>2.9.1.4 Command Search and Execution</i></a> , +item 1c.</p> +<p>If the <i>command_name</i> is the same as the name of one of the special built-in utilities, the special properties in the +enumerated list at the beginning of <a href="../utilities/V3_chap02.html#tag_19_15"><i>2.15 Special Built-In Utilities</i></a> +shall not occur. In every other respect, if <i>command_name</i> is not the name of a function, the effect of <i>command</i> (with +no options) shall be the same as omitting <i>command</i>, except that <i>command_name</i> does not appear in the command word +position in the <i>command</i> command, and consequently is not subject to alias substitution (see <a href= +"../utilities/V3_chap02.html#tag_19_03_01"><i>2.3.1 Alias Substitution</i></a> ) nor recognized as a reserved word (see <a href= +"../utilities/V3_chap02.html#tag_19_04"><i>2.4 Reserved Words</i></a> ).</p> +<p>When the <b>-v</b> or <b>-V</b> option is used, the <i>command</i> utility shall provide information concerning how a command +name is interpreted by the shell.</p> +<p>The <i>command</i> utility shall be treated as a declaration utility if the first argument passed to the utility is recognized +as a declaration utility. In this case, subsequent words of the form <i>name</i>=<i>word</i> shall be expanded in an assignment +context. See <a href="../utilities/V3_chap02.html#tag_19_09_01_01"><i>2.9.1.1 Order of Processing</i></a> .</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_22_04" id="tag_20_22_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>command</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-p</b></dt> +<dd>Perform the command search using a default value for <i>PATH</i> that is guaranteed to find all of the standard utilities.</dd> +<dt><b>-v</b></dt> +<dd>Write a string to standard output that indicates the pathname or command that will be used by the shell, in the current shell +execution environment (see <a href="../utilities/V3_chap02.html#tag_19_13"><i>2.13 Shell Execution Environment</i></a> ), to invoke +<i>command_name</i>, but do not invoke <i>command_name</i>. +<ul> +<li> +<p>Executable utilities, regular built-in utilities, <i>command_name</i>s including a <slash> character, and any +implementation-provided functions that are found using the <i>PATH</i> variable (as described in <a href= +"../utilities/V3_chap02.html#tag_19_09_01_04"><i>2.9.1.4 Command Search and Execution</i></a> ), shall be written as absolute +pathnames.</p> +</li> +<li> +<p>Shell functions, special built-in utilities, regular built-in utilities not associated with a <i>PATH</i> search, and shell +reserved words shall be written as just their names.</p> +</li> +<li> +<p>An alias shall be written as a command line that represents its alias definition.</p> +</li> +<li> +<p>Otherwise, no output shall be written and the exit status shall reflect that the name was not found.</p> +</li> +</ul> +</dd> +<dt><b>-V</b></dt> +<dd>Write a string to standard output that indicates how the name given in the <i>command_name</i> operand will be interpreted by +the shell, in the current shell execution environment (see <a href="../utilities/V3_chap02.html#tag_19_13"><i>2.13 Shell Execution +Environment</i></a> ), but do not invoke <i>command_name</i>. Although the format of this string is unspecified, it shall indicate +in which of the following categories <i>command_name</i> falls and shall include the information stated: +<ul> +<li> +<p>Executable utilities, regular built-in utilities, and any implementation-provided functions that are found using the <i>PATH</i> +variable (as described in <a href="../utilities/V3_chap02.html#tag_19_09_01_04"><i>2.9.1.4 Command Search and Execution</i></a> ), +shall be identified as such and include the absolute pathname in the string.</p> +</li> +<li> +<p>Other shell functions shall be identified as functions.</p> +</li> +<li> +<p>Aliases shall be identified as aliases and their definitions included in the string.</p> +</li> +<li> +<p>Special built-in utilities shall be identified as special built-in utilities.</p> +</li> +<li> +<p>Regular built-in utilities not associated with a <i>PATH</i> search shall be identified as regular built-in utilities. (The term +"regular" need not be used.)</p> +</li> +<li> +<p>Shell reserved words shall be identified as reserved words.</p> +</li> +</ul> +</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_22_05" id="tag_20_22_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>argument</i></dt> +<dd>One of the strings treated as an argument to <i>command_name</i>.</dd> +<dt><i>command_name</i></dt> +<dd><br> +The name of a utility or a special built-in utility.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_22_06" id="tag_20_22_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_22_07" id="tag_20_22_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_22_08" id="tag_20_22_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>command</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error and +informative messages written to standard output.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>PATH</i></dt> +<dd>Determine the search path used during the command search described in <a href= +"../utilities/V3_chap02.html#tag_19_09_01_04"><i>2.9.1.4 Command Search and Execution</i></a> , except as described under the +<b>-p</b> option.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_22_09" id="tag_20_22_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_22_10" id="tag_20_22_10"></a>STDOUT</h4> +<blockquote> +<p>When the <b>-v</b> option is specified, standard output shall be formatted as:</p> +<pre> +<tt>"%s\n", <</tt><i>pathname or command</i><tt>> +</tt></pre> +<p>When the <b>-V</b> option is specified, standard output shall be formatted as:</p> +<pre> +<tt>"%s\n", <</tt><i>unspecified</i><tt>> +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_22_11" id="tag_20_22_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_22_12" id="tag_20_22_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_22_13" id="tag_20_22_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_22_14" id="tag_20_22_14"></a>EXIT STATUS</h4> +<blockquote> +<p>When the <b>-v</b> or <b>-V</b> options are specified, the following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>The <i>command_name</i> could not be found or an error occurred.</dd> +</dl> +<p>Otherwise, the following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt>126</dt> +<dd>The utility specified by <i>command_name</i> was found but could not be invoked.</dd> +<dt>127</dt> +<dd>An error occurred in the <i>command</i> utility or the utility specified by <i>command_name</i> could not be found.</dd> +</dl> +<p>Otherwise, the exit status of <i>command</i> shall be that of the simple command specified by the arguments to +<i>command</i>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_22_15" id="tag_20_22_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_22_16" id="tag_20_22_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>This utility is required to be intrinsic. See <a href="../utilities/V3_chap01.html#tag_18_07"><i>1.7 Intrinsic Utilities</i></a> +for details.</p> +<p>The order for command search allows functions to override regular built-ins and path searches. This utility is necessary to +allow functions that have the same name as a utility to call the utility (instead of a recursive call to the function).</p> +<p>The system default path is available using <a href="../utilities/getconf.html"><i>getconf</i></a>; however, since <a href= +"../utilities/getconf.html"><i>getconf</i></a> may need to have the <i>PATH</i> set up before it can be called itself, the +following can be used:</p> +<pre> +<tt>command -p getconf PATH +</tt></pre> +<p>There are some advantages to suppressing the special characteristics of special built-ins on occasion. For example:</p> +<pre> +<tt>command exec > </tt><i>unwritable-file</i><tt> +</tt></pre> +<p>does not cause a non-interactive script to abort, so that the output status can be checked by the script.</p> +<p>The <i>command</i>, <a href="../utilities/env.html"><i>env</i></a>, <a href="../utilities/nohup.html"><i>nohup</i></a>, <a href= +"../utilities/time.html"><i>time</i></a>, <a href="../utilities/timeout.html"><i>timeout</i></a>, and <a href= +"../utilities/xargs.html"><i>xargs</i></a> utilities have been specified to use exit code 127 if a utility to be invoked cannot be +found, so that applications can distinguish "failure to find a utility" from "invoked utility exited with an error indication". +However, the <i>command</i> and <a href="../utilities/nohup.html"><i>nohup</i></a> utilities also use exit code 127 when an error +occurs in those utilities, which means exit code 127 is not universally a "not found" indicator. The value 127 was chosen because +it is not commonly used for other meanings; most utilities use small values for "normal error conditions" and the values above +128 can be confused with termination due to receipt of a signal. The value 126 was chosen in a similar manner to indicate that the +utility could be found, but not invoked. Some scripts produce meaningful error messages differentiating the 126 and 127 cases. The +distinction between exit codes 126 and 127 is based on KornShell practice that uses 127 when all attempts to <i>exec</i> the +utility fail with [ENOENT], and uses 126 when any attempt to <i>exec</i> the utility fails for any other reason.</p> +<p>Since the <b>-v</b> and <b>-V</b> options of <i>command</i> produce output in relation to the current shell execution +environment, <i>command</i> is generally provided as a shell regular built-in. If it is called in a subshell or separate utility +execution environment, such as one of the following:</p> +<pre> +<tt>(PATH=foo command -v) + nohup command -v +</tt></pre> +<p>it does not necessarily produce correct results. For example, when called with <a href= +"../utilities/nohup.html"><i>nohup</i></a> or an <i>exec</i> function, in a separate utility execution environment, most +implementations are not able to identify aliases, functions, or special built-ins.</p> +<p>Two types of regular built-ins could be encountered on a system and these are described separately by <i>command</i>. The +description of command search in <a href="../utilities/V3_chap02.html#tag_19_09_01_04"><i>2.9.1.4 Command Search and +Execution</i></a> allows for a standard utility to be implemented as a regular built-in as long as it is found in the appropriate +place in a <i>PATH</i> search. So, for example, <i>command</i> <b>-v</b> <i>true</i> might yield <b>/bin/true</b> or some similar +pathname. Other implementation-defined utilities that are not defined by this volume of POSIX.1-2024 might exist only as built-ins +and have no pathname associated with them. These produce output identified as (regular) built-ins. Applications encountering these +are not able to count on <i>exec</i>ing them, using them with <a href="../utilities/nohup.html"><i>nohup</i></a>, overriding them +with a different <i>PATH ,</i> and so on.</p> +<p>The <i>command</i> utility takes on the expansion behavior of the command that it is wrapping. Therefore, in</p> +<pre> +<tt>command command export a=~ +</tt></pre> +<p><i>command</i> is recognized as a declaration utility, and the command sets the variable <i>a</i> to the value of <tt>$HOME</tt> +because it performs tilde-expansion of an assignment context; while</p> +<pre> +<tt>command echo a=~ +</tt></pre> +outputs the literal string <tt>"a=~"</tt> because regular expansion can only perform tilde-expansion at the beginning of the word. +However, the shell need only perform lexical analysis of the next argument when deciding if command should be treated as a +declaration utility; therefore, with: +<pre> +<tt>var=export; command $var a=~ +</tt></pre> +<p>and</p> +<pre> +<tt>command -- export a=~ +</tt></pre> +<p>it is unspecified whether the word <tt>a=~</tt> is handled in an assignment context or as a regular expansion.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_22_17" id="tag_20_22_17"></a>EXAMPLES</h4> +<blockquote> +<ol> +<li> +<p>Make a version of <a href="../utilities/cd.html"><i>cd</i></a> that always prints out the new working directory exactly +once:</p> +<pre> +<tt>cd() { + command cd "$@" >/dev/null + pwd +} +</tt></pre></li> +<li> +<p>Start off a "secure shell script" in which the script avoids being spoofed by its parent:</p> +<pre> +<tt>IFS=' +' +# The preceding value should be <space><tab><newline>. +# Set IFS to its default value. +<br> +\unalias -a +# Unset all possible aliases. +# Note that unalias is escaped to prevent an alias +# being used for unalias. +<br> +unset -f command +# Ensure command is not a user function. +<br> +PATH="$(command -p getconf PATH):$PATH" +# Put on a reliable PATH prefix. +<br> +# ... +</tt></pre> +<p>At this point, given correct permissions on the directories called by <i>PATH ,</i> the script has the ability to ensure that +any utility it calls is the intended one. It is being very cautious because it assumes that implementation extensions may be +present that would allow user functions to exist when it is invoked; this capability is not specified by this volume of +POSIX.1-2024, but it is not prohibited as an extension. For example, the <i>ENV</i> variable precedes the invocation of the script +with a user start-up script. Such a script could define functions to spoof the application.</p> +</li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_22_18" id="tag_20_22_18"></a>RATIONALE</h4> +<blockquote> +<p>Since <i>command</i> is a regular built-in utility it is always found prior to the <i>PATH</i> search.</p> +<p>There is nothing in the description of <i>command</i> that implies the command line is parsed any differently from that of any +other simple command. For example:</p> +<pre> +<tt>command a | b ; c +</tt></pre> +<p>is not parsed in any special way that causes <tt>'|'</tt> or <tt>';'</tt> to be treated other than a pipe operator or +<semicolon> or that prevents function lookup on <b>b</b> or <b>c</b>. However, some implementations extend the shell's +assignment syntax, for example to allow an array to be populated with a single assignment, and in order for such an extension to be +usable in assignments specified as arguments to <a href="../utilities/export.html"><i>export</i></a> and <a href= +"../utilities/readonly.html"><i>readonly</i></a> these shells have those utility names as separate tokens in their grammar. When +<i>command</i> is used to execute these utilities it also needs to be a separate token in the grammar so that the same extended +assignment syntax can still be recognized in this case. This standard only permits an extension of this nature when the input to +the shell would contain a syntax error according to the standard grammar, and therefore it cannot affect how <tt>'|'</tt> and +<tt>';'</tt> are parsed in the example above. Note that although <i>command</i> can be a separate token in the shell's grammar, it +cannot be a reserved word since <i>command</i> is a candidate for alias substitution whereas reserved words are not (see <a href= +"../utilities/V3_chap02.html#tag_19_03_01"><i>2.3.1 Alias Substitution</i></a> ).</p> +<p>The <i>command</i> utility is somewhat similar to the Eighth Edition shell <i>builtin</i> command, but since <i>command</i> also +goes to the file system to search for utilities, the name <i>builtin</i> would not be intuitive.</p> +<p>The <i>command</i> utility is most likely to be provided as a regular built-in. It is not listed as a special built-in for the +following reasons:</p> +<ul> +<li> +<p>The removal of exportable functions made the special precedence of a special built-in unnecessary.</p> +</li> +<li> +<p>A special built-in has special properties (see <a href="../utilities/V3_chap02.html#tag_19_15"><i>2.15 Special Built-In +Utilities</i></a> ) that were inappropriate for invoking other utilities. For example, two commands such as:</p> +<pre> +<tt>date > </tt><i>unwritable-file</i><tt> +<br> +command date > </tt><i>unwritable-file</i><tt> +</tt></pre> +<p>would have entirely different results; in a non-interactive script, the former would continue to execute the next command, the +latter would abort. Introducing this semantic difference along with suppressing functions was seen to be non-intuitive.</p> +</li> +</ul> +<p>The <b>-p</b> option is present because it is useful to be able to ensure a safe path search that finds all the standard +utilities. This search might not be identical to the one that occurs through one of the <i>exec</i> functions (as defined in the +System Interfaces volume of POSIX.1-2024) when <i>PATH</i> is unset. At the very least, this feature is required to allow the +script to access the correct version of <a href="../utilities/getconf.html"><i>getconf</i></a> so that the value of the default +path can be accurately retrieved.</p> +<p>The <i>command</i> <b>-v</b> and <b>-V</b> options were added to satisfy requirements from users that are currently accomplished +by three different historical utilities: <a href="../utilities/type.html"><i>type</i></a> in the System V shell, <i>whence</i> in +the KornShell, and <i>which</i> in the C shell. Since there is no historical agreement on how and what to accomplish here, the +POSIX <i>command</i> utility was enhanced and the historical utilities were left unmodified. The C shell <i>which</i> merely +conducts a path search. The KornShell <i>whence</i> is more elaborate—in addition to the categories required by POSIX, it also +reports on tracked aliases, exported aliases, and undefined functions.</p> +<p>The output format of <b>-V</b> was left mostly unspecified because human users are its only audience. Applications should not be +written to care about this information; they can use the output of <b>-v</b> to differentiate between various types of commands, +but the additional information that may be emitted by the more verbose <b>-V</b> is not needed and should not be arbitrarily +constrained in its verbosity or localization for application parsing reasons.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_22_19" id="tag_20_22_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_22_20" id="tag_20_22_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19_09_01_04"><i>2.9.1.4 Command Search and Execution</i></a> , <a href= +"../utilities/V3_chap02.html#tag_19_09_01_01"><i>2.9.1.1 Order of Processing</i></a> , <a href= +"../utilities/V3_chap02.html#tag_19_13"><i>2.13 Shell Execution Environment</i></a> , <a href= +"../utilities/V3_chap02.html#tag_19_15"><i>2.15 Special Built-In Utilities</i></a> , <a href="../utilities/sh.html#"><i>sh</i></a> +, <a href="../utilities/type.html#"><i>type</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/exec.html#tag_17_129"><i>exec</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_22_21" id="tag_20_22_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_22_22" id="tag_20_22_22"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #196 is applied, changing the SYNOPSIS to allow <b>-p</b> to be used with <b>-v</b> (or +<b>-V</b>).</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>The <i>command</i> utility is moved from the User Portability Utilities option to the Base. User Portability Utilities is now an +option for interactive utilities.</p> +<p>The APPLICATION USAGE and EXAMPLES are revised to replace the non-standard <a href= +"../utilities/getconf.html"><i>getconf</i></a>_CS_PATH with <a href="../utilities/getconf.html"><i>getconf</i></a> <i>PATH +.</i></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_22_23" id="tag_20_22_23"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to report an error if a utility is directed to display a +pathname that contains any bytes that have the encoded value of a <newline> character when <newline> is a terminator or +separator in the output format being used.</p> +<p>Austin Group Defects 351 and 1393 are applied, requiring <i>command</i> to be a declaration utility if the first argument passed +to the utility is recognized as a declaration utility.</p> +<p>Austin Group Defect 854 is applied, adding a note to the APPLICATION USAGE section that this utility is required to be +intrinsic.</p> +<p>Austin Group Defect 1117 is applied, changing "implementation-defined" to "implementation-provided".</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1161 is applied, changing "Utilities" to "Executable utilities" in the descriptions of the <b>-v</b> and +<b>-V</b> options.</p> +<p>Austin Group Defect 1431 is applied, changing "item 1b" to "item 1c".</p> +<p>Austin Group Defect 1586 is applied, adding the <a href="../utilities/timeout.html"><i>timeout</i></a> utility.</p> +<p>Austin Group Defect 1594 is applied, changing the APPLICATION USAGE section.</p> +<p>Austin Group Defect 1637 is applied, clarifying that (when no options are specified) <i>command_name</i> is not subject to alias +substitution nor recognized as a reserved word.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/comm.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/compress.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/compress.html b/bdd/compress.html @@ -0,0 +1,627 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!doctype HTML> +<html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><link type="text/css" rel="stylesheet" href="style.css"> +<!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>compress</title> +</head><body bgcolor="white"><DIV CLASS="NAVHEADER"> +<TABLE SUMMARY="Header navigation table" class="nav" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0"> +<TR class="nav"><TD class="nav" WIDTH="15%" ALIGN="left" VALIGN="bottom"><A href="../utilities/command.html" ACCESSKEY="P" ><<< Previous</A></TD><TD class="nav" WIDTH="70%" ALIGN="center" VALIGN="bottom" ><a href="contents.html">Home</a></TD><TD class="nav" WIDTH="15%" ALIGN="right" VALIGN="bottom"> <A href="../utilities/cp.html" ACCESSKEY="N" >Next >>></A></TD></TR></TABLE><HR ALIGN="LEFT" WIDTH="100%"></DIV> +<script LANGUAGE="JavaScript" src="../jscript/codes.js"></script><basefont size=3> +<center><font size="2"> +The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top"></a> + +<a name="compress"></a> +<a name = "tag_20_23"></a><!-- compress --> + + + +<h4 class="mansect"><a name = "tag_20_23_01"></a>NAME</h4><blockquote> +compress, uncompress, zcat — compress and decompress data + + + + + + +</blockquote><h4 class="mansect"><a name = "tag_20_23_02"></a>SYNOPSIS</h4><blockquote class="synopsis"> +<p> +<p> +<tt><div class="box"><code><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> +<img src="../images/opt-start.gif" alt="[Option Start]" border=0> +compress </tt><b>[</b><tt>-fv</tt><b>] [</b><tt>-b </tt><i>value</i><b>] [</b><tt>-g | -m </tt><i>algo</i><b>] [</b><i>file</i><tt>...</tt><b>]</b><tt> +<br> +<br> +compress -c </tt><b>[</b><tt>-fv</tt><b>] [</b><tt>-b </tt><i>value</i><b>] [</b><tt>-g | -m </tt><i>algo</i><b>] [</b><i>file</i><b>]</b><tt> +<br> +<br> +compress -d </tt><b>[</b><tt>-cfv</tt><b>] [</b><i>file</i><tt>...</tt><b>]</b><tt> +<br> +<br> +uncompress </tt><b>[</b><tt>-cfv</tt><b>] [</b><i>file</i><tt>...</tt><b>]</b><tt> +<br> +<br> +zcat </tt><b>[</b><i>file</i><tt>...</tt><b>]</b><tt> +<img src="../images/opt-end.gif" alt="[Option End]" border=0> +</code></div> +<br> +</tt> +</blockquote><h4 class="mansect"><a name = "tag_20_23_03"></a>DESCRIPTION</h4><blockquote> +<p> +The +<i>compress</i> +utility, when the +<b>-d</b> +option is not specified, shall apply the compression algorithm identified +by the +<b>-g</b> +option or the +<b>-m</b> +<i>algo</i> +option to the named files to attempt to reduce their size without loss +of information. The compress utility with the +<b>-d</b> +option shall apply the appropriate decompression algorithm to the +named files to restore the data to their original state. +<p> +The +<i>uncompress</i> +utility shall be equivalent to +<i>compress</i> +<b>-d</b>. +The +<i>zcat</i> +utility shall be equivalent to +<i>compress</i> +<b>-c -d</b>. +If multiple +<i>file</i> +operands are specified, the decompressed data from each input file +shall be concatenated to standard output. +<p> +When compressing data, unless the +<b>-c</b> +option is specified, after an input file other than standard input has +been compressed, the compressed data from the input file shall be +stored in a file with the same pathname as the input file but with an +added suffix. The added suffix shall be the suffix associated with the +algorithm (see the algorithms in +<a href="#tagtcjh_17"> +Compression algorithms, algo option-argument values, and suffixes +</a> +). +If appending the suffix would make the size of the last component of +the output file's pathname exceed +{NAME_MAX} +bytes, the command shall fail. If appending the suffix would make the +size of the pathname exceed +{PATH_MAX} +bytes, the command may fail. +<p> +When decompressing data, unless the +<b>-c</b> +option is specified, after an input file other than standard input has +been decompressed, the decompressed data from the input file shall be +stored in a file with the same pathname as the input file but with the +suffix associated with the algorithm removed. +<sup>[<a href="javascript:open_code('OB')">OB</a>]</sup> +<img src="../images/opt-start.gif" alt="[Option Start]" border=0> + If +<i>file</i> +has no suffix associated with a known compression algorithm or +<i>file</i> +does not exist and does not have a +<b>.Z</b> +suffix, +<i>file</i> +shall be used as the name of the output file, and the default suffix +<b>.Z</b> +shall be appended to +<i>file</i> +to form the input pathname. +<img src="../images/opt-end.gif" alt="[Option End]" border=0> +The behavior is unspecified if the input pathname ends with a suffix +other than the suffix associated with the algorithm used to compress +the data. When the +<b>-c</b> +option is specified, +<i>file</i> +can have any suffix, or no suffix, and the utility shall use +<i>file</i> +as the input file and examine the file's contents to determine which +algorithm to use to decompress the data (it is not an error if +<i>file</i> +does not have a suffix that matches the suffix associated with the +compression algorithm). +<p> +When compressing or decompressing a file other than standard input and the +<b>-c</b> +option is not specified, if the invoking process has sufficient privilege, +the ownership, modes, access time, and modification time of the output +file shall match the ownership, modes, access time, and modification +time of the input file. After the output file has been successfully +created, the input file shall be removed if the invoking process has +sufficient privileges. If the invoking process does not have sufficient +privileges to remove the input file (for example, if the directory has +the S_ISVTX bit set) the behavior depends on whether the +<b>-f</b> +option is specified: if +<b>-f</b> +is not specified, the output file shall be removed, a diagnostic +message shall be written and the utility shall continue processing +other files but the final exit status shall be non-zero; if +<b>-f</b> +is specified, the output file shall not be removed and it is +unspecified whether the inability to remove the input file is treated +as an error. If it is not treated as an error, a warning message may +be written to standard error +<p> +If no +<i>file</i> +operands are specified, standard input shall be compressed or +decompressed to standard output. +<p> +<sup>[<a href="javascript:open_code('OB')">OB</a>]</sup> +<img src="../images/opt-start.gif" alt="[Option Start]" border=0> +If an input file that is to be removed after processing has multiple +hard links, the +<i>compress</i> +and +<i>uncompress</i> +utilities may write a diagnostic message to standard error and do +nothing with the file; this behavior may depend on whether the +<b>-f</b> +option is specified. If a diagnostic message is written, the final +exit status shall be non-zero. +<img src="../images/opt-end.gif" alt="[Option End]" border=0> +</blockquote><h4 class="mansect"><a name = "tag_20_23_04"></a>OPTIONS</h4><blockquote> +<p> +The +<i>compress</i>, +<i>uncompress</i>, +and +<i>zcat</i> +utilities shall conform to XBD +<a href="../basedefs/V1_chap12.html#tag_12_02"> +<i>12.2 Utility Syntax Guidelines</i> +</a> +, +except that Guideline 1 does not apply to +<i>uncompress</i> +since the utility name has ten letters. +<p> +The following options shall be supported: +<dl compact><dd> +<p><dt><b>-b </b><i>value</i><dd>If the compression algorithm is LZW, +<i>value</i> +specifies the maximum number of bits to use in a code. For a +conforming application, the +<i>value</i> +argument shall be: +<pre> +<tt>9 <= </tt><i>value</i><tt> <= 16 +</tt></pre> +<p> +The implementation may allow values of greater than 16. The default +shall be 14, 15, or 16. +<p> +If the compression algorithm is DEFLATE, +<i>value</i> +specifies the compression level. For a conforming application, the +<i>value</i> +argument shall be: +<pre> +<tt>1 <= </tt><i>value</i><tt> <= 9 +</tt></pre> +<p> +The default shall be 6. +<p> +For other algorithms, value specifies implementation-defined tuning. +<p><dt><b>-c</b><dd>Write to standard output; the input files shall not be changed, and no +output files shall be created. +<p><dt><b>-d</b><dd>Decompress files. When invoked with the +<b>-d</b> +option, the +<i>compress</i> +utility shall restore previously compressed files to their original state. +<p><dt><b>-f</b><dd>Force compression or decompression of file, even if it does not (for +compression) actually reduce the size of the file, or if the +corresponding output file already exists. If the +<b>-f</b> +option is not given and the standard input is a terminal, the user +shall be prompted as to whether an existing output file should be +overwritten. If the response is affirmative, the existing file shall +be overwritten. If the standard input is not a terminal and +<b>-f</b> +is not given, +<i>compress</i> +or +<i>uncompress</i> +shall write a diagnostic message to standard error, the existing file +shall not be overwritten, and the utility shall exit with a status +greater than zero. If the +<b>-f</b> +option is specified and an input file other than standard input has +multiple hard links, it is implementation-defined whether the input +file is unlinked after the corresponding output file is successfully +written, or if processing of that file is skipped and a diagnostic +message is written to standard error. +<p><dt><b>-g</b><dd>Equivalent to +<b>-m</b> +<i>gzip</i>. +<p><dt><b>-m </b><i>algo</i><dd>Use the algorithm defined by +<i>algo</i> +to compress the files. The following algorithms shall be supported: +<br> +<p class="caption"><xref table="Compression algorithms, algo option-argument values, and suffixes"><a name="tagtcjh_17"></a> +Table: Compression algorithms, algo option-argument values, and suffixes</p> + + +<p> +<center> +<p> +<table border=1 cellpadding=3 align=center> +<tr valign=top><th align=center><p class="tent"><b>Algorithm</b></p></th> +<th align=center><p class="tent">algo</p></th> +<th align=center><p class="tent"><b>Filename Suffix</b></p></th> +</p></tr> +<tr valign=top><td align=left><p class="tent">Adaptive LZW +<td align=left><p class="tent"><b>lzw</b> +<td align=left><p class="tent"><b>.Z</b> +</p></tr> +<tr valign=top><td align=left><p class="tent">RFC1951 DEFLATE +<td align=left><p class="tent"><b>deflate</b> +<td align=left><p class="tent"><b>.gz</b> +</p></tr> +<tr valign=top><td align=left><p class="tent">Synonym for DEFLATE +<td align=left><p class="tent"><b>gzip</b> +<td align=left><p class="tent"><b>.gz</b> +</tr> +</table> +</center> +<p class="tent"> +Other implementation-defined algorithms may be supported. +<p class="tent"> +If neither of the +<b>-m</b> +<i>algo</i> +and +<b>-g</b> +options is specified, +<b>lzw</b> +shall be used as a default +<i>algo</i> +value. Specifying more than one of the mutually exclusive +<b>-g</b> +and +<b>-m</b> +<i>algo</i> +options, or multiple +<b>-m</b> +<i>algo</i> +options, shall not be considered an error. The last option specified +shall determine the behavior of the utility. +<p class="tent"> +On systems not supporting the selected algorithm, the input files +shall not be changed and an exit status greater than two shall be +returned. +<basefont size=2> +<dl><dt><b>Note:</b> +<dd>The Lempel-Ziv compression algorithm is described in the now-expired +US Patent 4464650, which was issued to William Eastman, Abraham Lempel, +Jacob Ziv, and Martin Cohn on August 7th, 1984 and assigned to Sperry +Corporation. +<p class="tent"> +The Lempel-Ziv-Welch compression algorithm is described in the +now-expired US Patent 4558302, which was issued to Terry A. Welch on +December 10th, 1985 and assigned to Sperry Corporation. +</dl> +<basefont size=3> +<p><dt><b>-v</b><dd>For +<i>compress</i>, +write the percentage reduction of each file to standard error. For +<i>uncompress</i>, +write messages to standard error concerning the expansion of each file. +</dl> +</blockquote><h4 class="mansect"><a name = "tag_20_23_05"></a>OPERANDS</h4><blockquote> +<p> +The following operand shall be supported: +<dl compact><dd> +<p><dt><i>file</i><dd>A pathname of a file to be compressed or decompressed. If a +<i>file</i> +is +<tt>'-'</tt>, +the utility shall read from standard input at that point in the +sequence and write to standard output. If more than one +<i>file</i> +operand is +<tt>'-'</tt>, +the behavior is unspecified. +</dl> +</blockquote><h4 class="mansect"><a name = "tag_20_23_06"></a>STDIN</h4><blockquote> +<p> +The standard input shall be used only if no +<i>file</i> +operands are specified, or if a +<i>file</i> +operand is +<tt>'-'</tt>. +</blockquote><h4 class="mansect"><a name = "tag_20_23_07"></a>INPUT FILES</h4><blockquote> +<p> +If +<i>file</i> +operands are specified, the corresponding input files contain the data +to be compressed or decompressed. +</blockquote><h4 class="mansect"><a name = "tag_20_23_08"></a>ENVIRONMENT VARIABLES</h4><blockquote> +<p> +The following environment variables shall affect the execution of +<i>compress</i>: +<dl compact><dd> +<p><dt><i>LANG</i><dd>Provide a default value for the internationalization variables that are +unset or null. (See XBD +<a href="../basedefs/V1_chap08.html#tag_08_02"> +<i>8.2 Internationalization Variables</i> +</a> +for the precedence of internationalization variables used to determine +the values of locale categories.) +<p><dt><i>LC_ALL</i><dd>If set to a non-empty string value, override the values of all the +other internationalization variables. +<p><dt><i>LC_COLLATE</i><dd><br> +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements used in the extended regular +expression defined for the +<b>yesexpr</b> +locale keyword in the +<i>LC_MESSAGES</i> +category. +<p><dt><i>LC_CTYPE</i><dd>Determine the locale for the interpretation of sequences of bytes of text +data as characters (for example, single-byte as opposed to multi-byte +characters in arguments), the behavior of character classes used in the +extended regular expression defined for the +<b>yesexpr</b> +locale keyword in the +<i>LC_MESSAGES</i> +category. +<p><dt><i>LC_MESSAGES</i><dd><br> +Determine the locale used to process affirmative responses, and the +locale used to affect the format and contents of diagnostic messages, +prompts, and the output from the +<b>-v</b> +option written to standard error. +<p><dt><i>NLSPATH</i><dd>Determine the location of messages objects and message catalogs. +</dl> +</blockquote><h4 class="mansect"><a name = "tag_20_23_09"></a>ASYNCHRONOUS EVENTS</h4><blockquote> +<p> +Default. +</blockquote><h4 class="mansect"><a name = "tag_20_23_10"></a>STDOUT</h4><blockquote> +<p> +For the +<i>compress</i> +and +<i>uncompress</i> +utilities, the standard output shall be used if no +<i>file</i> +operands are specified, if a +<i>file</i> +operand is +<tt>'-'</tt>, +or if the +<b>-c</b> +option is specified. Otherwise, the standard output shall not be used. +<p class="tent"> +The +<i>zcat</i> +utility shall write the decompressed data to the standard output. +</blockquote><h4 class="mansect"><a name = "tag_20_23_11"></a>STDERR</h4><blockquote> +<p> +The standard error shall be used only for diagnostic and prompt +messages, the optional warning message described in DESCRIPTION, and +the output from +<b>-v</b>. +</blockquote><h4 class="mansect"><a name = "tag_20_23_12"></a>OUTPUT FILES</h4><blockquote> +<p> +When decompressing input files other than standard input, the +corresponding output files shall contain the decompressed input data. +When compressing input files other than standard input, the +corresponding output files shall contain the compressed input data. +If the selected +<i>algo</i> +is +<b>deflate</b> +or +<b>gzip</b>, +the compressed output shall be in the GZIP format described in RFC 1952. +For other algorithms, the compressed output file format is +implementation-defined and interchange of such files between +implementations (including access via unspecified file sharing +mechanisms) is not required by POSIX.1-2024. +</blockquote><h4 class="mansect"><a name = "tag_20_23_13"></a>EXTENDED DESCRIPTION</h4><blockquote> +<p> +None. +</blockquote><h4 class="mansect"><a name = "tag_20_23_14"></a>EXIT STATUS</h4><blockquote> +<p> +The following exit values shall be returned for +<i>compress</i>: +<dl compact><dd> +<p><dt> 0<dd>Successful completion. +<p><dt> 1<dd>An error occurred. +<p><dt> 2<dd>One or more files were not compressed because they would have increased +in size (and the +<b>-f</b> +option was not specified). +<p><dt>>2<dd>An error occurred. +</dl> +<p class="tent"> +The following exit values shall be returned for +<i>uncompress</i> +and +<i>zcat</i>: +<dl compact><dd> +<p><dt> 0<dd>Successful completion. +<p><dt>>0<dd>An error occurred. +</dl> +</blockquote><h4 class="mansect"><a name = "tag_20_23_15"></a>CONSEQUENCES OF ERRORS</h4><blockquote> +<p> +If an error occurs while compressing or decompressing an input file +other than standard input, the input file shall remain unmodified. +</blockquote> +<hr><div class="box"><em>The following sections are informative.</em></div> +<blockquote> +</blockquote><h4 class="mansect"><a name = "tag_20_23_16"></a>APPLICATION USAGE</h4><blockquote> +<p> +The amount of compression obtained depends on the size of the input, +the number of bits +per code, and the distribution of common substrings. Typically, text +such as source code or English is reduced by 50-60%. Compression is +generally much better than that achieved by Huffman coding +or adaptive Huffman coding (<i>compact</i>), +and takes less time to compute. +<p class="tent"> +Although +<i>compress</i> +strictly follows the default actions upon receipt of a signal or when +an error occurs, some unexpected results may occur. In some +implementations it is likely that a partially compressed file is left +in place, alongside its uncompressed input file. Since the general +operation of +<i>compress</i> +is to delete the uncompressed file only after the +<b>.Z</b> +file has been successfully filled, an application should always +carefully check the exit status of +<i>compress</i> +before arbitrarily deleting files that have like-named neighbors with +<b>.Z</b> +suffixes. +<p class="tent"> +In addition to trying +<i>file</i> +and +<i>file</i><b>.Z</b> +when looking for a file to decompress, some implementations of +<i>uncompress</i> +and +<i>zcat</i> +also try suffixes for other known compression algorithms if neither +<i>file</i> +nor +<i>file</i><b>.Z</b> +is found. This version of the standard allows, but does not require +this behavior. Portable applications should always specify the full +pathname (including the suffix) of files to be decompressed. +</blockquote><h4 class="mansect"><a name = "tag_20_23_17"></a>EXAMPLES</h4><blockquote> +<p> +None. +</blockquote><h4 class="mansect"><a name = "tag_20_23_18"></a>RATIONALE</h4><blockquote> +<p> +Earlier versions of this standard limited the number of bits used by +conforming applications for the +<b>lzw</b> +algorithm to 14 due to address space limitations on 16-bit +architectures. Using 15 or 16 is a much more common default when using +current hardware. +<p class="tent"> +Earlier versions of this standard only supported LZW compression. The +standard developers noted that existing implementations added other +compression utilities, such as +<i>gzip</i>, +and found it desirable to support this widespread usage. Some +implementations had extended the +<i>compress</i> +utility to support such other schemes. The standard developers +generalized this practice by the addition of the +<b>-m</b> +option, even though this was not previous practice. +<p class="tent"> +The +<i>uncompress</i> +<b>-d</b> +option is added to match undocumented existing practice of tested +implementations. +</blockquote><h4 class="mansect"><a name = "tag_20_23_19"></a>FUTURE DIRECTIONS</h4><blockquote> +<p> +If this utility is directed to create a new directory entry that +contains any bytes that have the encoded value of a +<newline> +character, implementations are encouraged to treat this as an error. +A future version of this standard may require implementations to treat +this as an error. +<p class="tent"> +When decompressing a file, the requirement to add +<b>.Z</b> +to a +<i>file</i> +operand if the given pathname does not include a suffix associated +with a known compression algorithm or if +<i>file</i> +does not exist and does not already have a +<b>.Z</b> +extension is an obsolescent feature and may be removed in a future version. +</blockquote><h4 class="mansect"><a name = "tag_20_23_20"></a>SEE ALSO</h4><blockquote> +<p> +XBD +<a href="../basedefs/V1_chap08.html#tag_08"> +<i>8. Environment Variables</i> +</a> +, +<a href="../basedefs/V1_chap12.html#tag_12_02"> +<i>12.2 Utility Syntax Guidelines</i> +</a> +</blockquote><h4 class="mansect"><a name = "tag_20_23_21"></a>CHANGE HISTORY</h4><blockquote> +<p> +First released in Issue 4. +</blockquote><h4 class="mansect"><a name = "tag_20_23_22"></a>Issue 6</h4><blockquote> +<p> +The normative text is reworded to avoid use of the term "must" +for application requirements. +<p class="tent"> +An error case is added for systems not supporting adaptive Lempel-Ziv +coding. +</blockquote><h4 class="mansect"><a name = "tag_20_23_23"></a>Issue 7</h4><blockquote> +<p> +SD5-XCU-ERN-97 is applied, updating the SYNOPSIS. +<p class="tent"> +Austin Group Interpretation 1003.1-2001 #125 is applied, revising +the ENVIRONMENT VARIABLES section. +</blockquote><h4 class="mansect"><a name = "tag_20_23_24"></a>Issue 8</h4><blockquote> +<p> +Austin Group Defect 251 is applied, encouraging implementations to +disallow the creation of filenames containing any bytes that have the +encoded value of a +<newline> +character. +<p class="tent"> +Austin Group Defect 1041 is applied, combining the +<i>compress</i>, +<i>uncompress</i> +and +<i>zcat</i> +pages into one and extensively modifying most sections. +<p class="tent"> +Austin Group Defect 1122 is applied, changing the description of +<i>NLSPATH . +</i></blockquote> +<div class="box"><em>End of informative text.</em></div><hr> +<blockquote> +</blockquote> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | +<a href="../basedefs/contents.html">XBD</a> | +<a href="../functions/contents.html">XSH</a> | +<a href="../utilities/contents.html">XCU</a> | +<a href="../xrat/contents.html">XRAT</a> ] +</font></center> +<hr size="2" noshade> + +<DIV CLASS="NAVHEADER"> +<TABLE SUMMARY="Header navigation table" class="nav" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0"> +<TR class="nav"><TD class="nav" WIDTH="15%" ALIGN="left" VALIGN="bottom"><A href="../utilities/command.html" ACCESSKEY="P" ><<< Previous</A></TD><TD class="nav" WIDTH="70%" ALIGN="center" VALIGN="bottom" ><a href="contents.html">Home</a></TD><TD class="nav" WIDTH="15%" ALIGN="right" VALIGN="bottom"> <A href="../utilities/cp.html" ACCESSKEY="N" >Next >>></A></TD></TR></TABLE><HR ALIGN="LEFT" WIDTH="100%"></DIV></body></html> diff --git a/bdd/cp.html b/bdd/cp.html @@ -0,0 +1,515 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>cp</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/compress.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/crontab.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="cp" id="cp"></a> <a name="tag_20_24" id="tag_20_24"></a><!-- cp --> +<h4 class="mansect"><a name="tag_20_24_01" id="tag_20_24_01"></a>NAME</h4> +<blockquote>cp — copy files</blockquote> +<h4 class="mansect"><a name="tag_20_24_02" id="tag_20_24_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>cp</tt> <b>[</b><tt>-Pfip</tt><b>]</b> <i>source_file target_file</i> <tt><br> +<br> +cp</tt> <b>[</b><tt>-Pfip</tt><b>]</b> <i>source_file</i><tt>...</tt> <i>target</i> <tt><br> +<br> +cp -R</tt> <b>[</b><tt>-H|-L|-P</tt><b>] [</b><tt>-fip</tt><b>]</b> <i>source_file</i><tt>...</tt> <i>target</i> <tt><br></tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_24_03" id="tag_20_24_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The first synopsis form is denoted by two operands, neither of which are existing files of type directory. The <i>cp</i> utility +shall copy the contents of <i>source_file</i> (or, if <i>source_file</i> is a file of type symbolic link, the contents of the file +referenced by <i>source_file</i>) to the destination path named by <i>target_file.</i></p> +<p>The second synopsis form is denoted by two or more operands where the <b>-R</b> option is not specified and the first synopsis +form is not applicable. It shall be an error if any <i>source_file</i> is a file of type directory, if <i>target</i> does not +exist, or if <i>target</i> does not name a directory. The <i>cp</i> utility shall copy the contents of each <i>source_file</i> (or, +if <i>source_file</i> is a file of type symbolic link, the contents of the file referenced by <i>source_file</i>) to the +destination path named by the concatenation of <i>target</i>, a single <slash> character if <i>target</i> did not end in a +<slash>, and the last component of <i>source_file</i>.</p> +<p>The third synopsis form is denoted by two or more operands where the <b>-R</b> option is specified. The <i>cp</i> utility shall +copy each file in the file hierarchy rooted in each <i>source_file</i> to a destination path named as follows:</p> +<ul> +<li> +<p>If <i>target</i> exists and names an existing directory, the name of the corresponding destination path for each file in the +file hierarchy shall be the concatenation of <i>target</i>, a single <slash> character if <i>target</i> did not end in a +<slash>, and the pathname of the file relative to the directory containing <i>source_file</i>.</p> +</li> +<li> +<p>If <i>target</i> does not exist and two operands are specified, the name of the corresponding destination path for +<i>source_file</i> shall be <i>target</i>; the name of the corresponding destination path for all other files in the file hierarchy +shall be the concatenation of <i>target</i>, a <slash> character, and the pathname of the file relative to +<i>source_file</i>.</p> +</li> +</ul> +<p>It shall be an error if <i>target</i> does not exist and more than two operands are specified, or if <i>target</i> exists and +does not name a directory.</p> +<p>In the following description, the term <i>dest_file</i> refers to the file named by the destination path. The term +<i>source_file</i> refers to the file that is being copied, whether specified as an operand or a file in a file hierarchy rooted in +a <i>source_file</i> operand. If <i>source_file</i> is a file of type symbolic link:</p> +<ul> +<li> +<p>If the <b>-R</b> option was not specified, <i>cp</i> shall take actions based on the type and contents of the file referenced by +the symbolic link, and not by the symbolic link itself, unless the <b>-P</b> option was specified.</p> +</li> +<li> +<p>If the <b>-R</b> option was specified:</p> +<ul> +<li> +<p>If none of the options <b>-H</b>, <b>-L</b>, nor <b>-P</b> were specified, it is unspecified which of <b>-H</b>, <b>-L</b>, or +<b>-P</b> will be used as a default.</p> +</li> +<li> +<p>If the <b>-H</b> option was specified, <i>cp</i> shall take actions based on the type and contents of the file referenced by any +symbolic link specified as a <i>source_file</i> operand.</p> +</li> +<li> +<p>If the <b>-L</b> option was specified, <i>cp</i> shall take actions based on the type and contents of the file referenced by any +symbolic link specified as a <i>source_file</i> operand or any symbolic links encountered during traversal of a file hierarchy.</p> +</li> +<li> +<p>If the <b>-P</b> option was specified, <i>cp</i> shall copy any symbolic link specified as a <i>source_file</i> operand and any +symbolic links encountered during traversal of a file hierarchy, and shall not follow any symbolic links.</p> +</li> +</ul> +</li> +</ul> +<p>For each <i>source_file</i>, the following steps shall be taken:</p> +<ol> +<li> +<p>If <i>source_file</i> references the same file as <i>dest_file</i>, <i>cp</i> may write a diagnostic message to standard error; +it shall do nothing more with <i>source_file</i> and shall go on to any remaining files.</p> +</li> +<li> +<p>If <i>source_file</i> is of type directory, the following steps shall be taken:</p> +<ol type="a"> +<li> +<p>If the <b>-R</b> option was not specified, <i>cp</i> shall write a diagnostic message to standard error, do nothing more with +<i>source_file</i>, and go on to any remaining files.</p> +</li> +<li> +<p>If <i>source_file</i> was not specified as an operand and <i>source_file</i> is dot or dot-dot, <i>cp</i> shall do nothing more +with <i>source_file</i> and go on to any remaining files.</p> +</li> +<li> +<p>If <i>dest_file</i> exists and it is a file type not specified by the System Interfaces volume of POSIX.1-2024, the behavior is +implementation-defined.</p> +</li> +<li> +<p>If <i>dest_file</i> exists and it is not of type directory, <i>cp</i> shall write a diagnostic message to standard error, do +nothing more with <i>source_file</i> or any files below <i>source_file</i> in the file hierarchy, and go on to any remaining +files.</p> +</li> +<li> +<p>If the directory <i>dest_file</i> does not exist, it shall be created with file permission bits set to the same value as those +of <i>source_file</i>, modified by the file creation mask of the user if the <b>-p</b> option was not specified, and then +bitwise-inclusively OR'ed with S_IRWXU. If <i>dest_file</i> cannot be created, <i>cp</i> shall write a diagnostic message to +standard error, do nothing more with <i>source_file</i>, and go on to any remaining files. It is unspecified if <i>cp</i> attempts +to copy files in the file hierarchy rooted in <i>source_file</i>.</p> +</li> +<li> +<p>The files in the directory <i>source_file</i> shall be copied to the directory <i>dest_file</i>, taking the four steps (1 to 4) +listed here with the files as <i>source_file</i>s.</p> +</li> +<li> +<p>If <i>dest_file</i> was created, its file permission bits shall be changed (if necessary) to be the same as those of +<i>source_file</i>, modified by the file creation mask of the user if the <b>-p</b> option was not specified.</p> +</li> +<li> +<p>The <i>cp</i> utility shall do nothing more with <i>source_file</i> and go on to any remaining files.</p> +</li> +</ol> +</li> +<li> +<p>If <i>source_file</i> is of type regular file, the following steps shall be taken:</p> +<ol type="a"> +<li> +<p>The behavior is unspecified if <i>dest_file</i> exists and was written by a previous step. Otherwise, if <i>dest_file</i> +exists, the following steps shall be taken:</p> +<ol type="i"> +<li> +<p>If the <b>-i</b> option is in effect, the <i>cp</i> utility shall write a prompt to the standard error and read a line from the +standard input. If the response is not affirmative, <i>cp</i> shall do nothing more with <i>source_file</i> and go on to any +remaining files.</p> +</li> +<li> +<p>A file descriptor for <i>dest_file</i> shall be obtained by performing actions equivalent to the <a href= +"../functions/open.html"><i>open</i>()</a> function defined in the System Interfaces volume of POSIX.1-2024 called using +<i>dest_file</i> as the <i>path</i> argument, and the bitwise-inclusive OR of O_WRONLY and O_TRUNC as the <i>oflag</i> +argument.</p> +</li> +<li> +<p>If the attempt to obtain a file descriptor fails and the <b>-f</b> option is in effect, <i>cp</i> shall attempt to remove the +file by performing actions equivalent to the <a href="../functions/unlink.html"><i>unlink</i>()</a> function defined in the System +Interfaces volume of POSIX.1-2024 called using <i>dest_file</i> as the <i>path</i> argument. If this attempt succeeds, <i>cp</i> +shall continue with step 3b.</p> +</li> +</ol> +</li> +<li> +<p>If <i>dest_file</i> does not exist, a file descriptor shall be obtained by performing actions equivalent to the <a href= +"../functions/open.html"><i>open</i>()</a> function defined in the System Interfaces volume of POSIX.1-2024 called using +<i>dest_file</i> as the <i>path</i> argument, and the bitwise-inclusive OR of O_WRONLY and O_CREAT as the <i>oflag</i> argument. +The file permission bits of <i>source_file</i> shall be the <i>mode</i> argument.</p> +</li> +<li> +<p>If the attempt to obtain a file descriptor fails, <i>cp</i> shall write a diagnostic message to standard error, do nothing more +with <i>source_file</i>, and go on to any remaining files.</p> +</li> +<li> +<p>The contents of <i>source_file</i> shall be written to the file descriptor. Any write errors shall cause <i>cp</i> to write a +diagnostic message to standard error and continue to step 3e.</p> +</li> +<li> +<p>The file descriptor shall be closed.</p> +</li> +<li> +<p>The <i>cp</i> utility shall do nothing more with <i>source_file</i>. If a write error occurred in step 3d, it is unspecified if +<i>cp</i> continues with any remaining files. If no write error occurred in step 3d, <i>cp</i> shall go on to any remaining +files.</p> +</li> +</ol> +</li> +<li> +<p>Otherwise, the <b>-R</b> option was specified, and the following steps shall be taken:</p> +<ol type="a"> +<li> +<p>The <i>dest_file</i> shall be created with the same file type as <i>source_file</i>.</p> +</li> +<li> +<p>If <i>source_file</i> is a file of type FIFO, the file permission bits shall be the same as those of <i>source_file,</i> +modified by the file creation mask of the user if the <b>-p</b> option was not specified. Otherwise, the permissions, owner ID, and +group ID of <i>dest_file</i> are implementation-defined.</p> +<p>If this creation fails for any reason, <i>cp</i> shall write a diagnostic message to standard error, do nothing more with +<i>source_file</i>, and go on to any remaining files.</p> +</li> +<li> +<p>If <i>source_file</i> is a file of type symbolic link, and the options require the symbolic link itself to be acted upon, the +pathname contained in <i>dest_file</i> shall be the same as the pathname contained in <i>source_file</i>.</p> +<p>If this fails for any reason, <i>cp</i> shall write a diagnostic message to standard error, do nothing more with +<i>source_file</i>, and go on to any remaining files.</p> +</li> +</ol> +</li> +</ol> +<p>If the implementation provides additional or alternate access control mechanisms (see XBD <a href= +"../basedefs/V1_chap04.html#tag_04_07"><i>4.7 File Access Permissions</i></a> ), their effect on copies of files is +implementation-defined.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_24_04" id="tag_20_24_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>cp</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-f</b></dt> +<dd>If a file descriptor for a destination file cannot be obtained, as described in step 3.a.ii., attempt to unlink the destination +file and proceed.</dd> +<dt><b>-H</b></dt> +<dd>Take actions based on the type and contents of the file referenced by any symbolic link specified as a <i>source_file</i> +operand.</dd> +<dt><b>-i</b></dt> +<dd>Write a prompt to standard error before copying to any existing non-directory destination file. If the response from the +standard input is affirmative, the copy shall be attempted; otherwise, it shall not.</dd> +<dt><b>-L</b></dt> +<dd>Take actions based on the type and contents of the file referenced by any symbolic link specified as a <i>source_file</i> +operand or any symbolic links encountered during traversal of a file hierarchy.</dd> +<dt><b>-P</b></dt> +<dd>Take actions on any symbolic link specified as a <i>source_file</i> operand or any symbolic link encountered during traversal +of a file hierarchy.</dd> +<dt><b>-p</b></dt> +<dd>Duplicate the following characteristics of each source file in the corresponding destination file: +<ol> +<li> +<p>The time of last data modification and time of last access. If this duplication fails for any reason, <i>cp</i> shall write a +diagnostic message to standard error.</p> +</li> +<li> +<p>The user ID and group ID. If this duplication fails for any reason, it is unspecified whether <i>cp</i> writes a diagnostic +message to standard error.</p> +</li> +<li> +<p>The file permission bits and the S_ISUID and S_ISGID bits. Other, implementation-defined, bits may be duplicated as well. If +this duplication fails for any reason, <i>cp</i> shall write a diagnostic message to standard error.</p> +</li> +</ol> +<p>If the user ID or the group ID cannot be duplicated, the file permission bits S_ISUID and S_ISGID shall be cleared. If these +bits are present in the source file but are not duplicated in the destination file, it is unspecified whether <i>cp</i> writes a +diagnostic message to standard error.</p> +<p>The order in which the preceding characteristics are duplicated is unspecified. The <i>dest_file</i> shall not be deleted if +these characteristics cannot be preserved.</p> +</dd> +<dt><b>-R</b></dt> +<dd>Copy file hierarchies.</dd> +</dl> +<p>Specifying more than one of the mutually-exclusive options <b>-H</b>, <b>-L</b>, and <b>-P</b> shall not be considered an error. +The last option specified shall determine the behavior of the utility.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_24_05" id="tag_20_24_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>source_file</i></dt> +<dd>A pathname of a file to be copied. If a <i>source_file</i> operand is <tt>'-'</tt>, it shall refer to a file named <b>-</b>; +implementations shall not treat it as meaning standard input.</dd> +<dt><i>target_file</i></dt> +<dd>A pathname of an existing or nonexistent file, used for the output when a single file is copied. If a <i>target_file</i> +operand is <tt>'-'</tt>, it shall refer to a file named <b>-</b>; implementations shall not treat it as meaning standard +output.</dd> +<dt><i>target</i></dt> +<dd>A pathname of a directory to contain the copied files.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_24_06" id="tag_20_24_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be used to read an input line in response to each prompt specified in the STDERR section. Otherwise, +the standard input shall not be used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_24_07" id="tag_20_24_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files specified as operands may be of any file type.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_24_08" id="tag_20_24_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>cp</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_COLLATE</i></dt> +<dd><br> +Determine the locale for the behavior of ranges, equivalence classes, and multi-character collating elements used in the extended +regular expression defined for the <b>yesexpr</b> locale keyword in the <i>LC_MESSAGES</i> category.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files) and the behavior of character classes used in the extended regular +expression defined for the <b>yesexpr</b> locale keyword in the <i>LC_MESSAGES</i> category.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale used to process affirmative responses, and the locale used to affect the format and contents of diagnostic +messages and prompts written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_24_09" id="tag_20_24_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_24_10" id="tag_20_24_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_24_11" id="tag_20_24_11"></a>STDERR</h4> +<blockquote> +<p>A prompt shall be written to standard error under the conditions specified in the DESCRIPTION section. The prompt shall contain +the destination pathname, but its format is otherwise unspecified. Otherwise, the standard error shall be used only for diagnostic +messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_24_12" id="tag_20_24_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>The output files may be of any type.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_24_13" id="tag_20_24_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_24_14" id="tag_20_24_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>All requested files (excluding files where a non-affirmative response was given to a request for confirmation) were +successfully copied.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_24_15" id="tag_20_24_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>If <i>cp</i> is prematurely terminated by a signal or error, files or file hierarchies may be only partially copied and files +and directories may have incorrect permissions or access and modification times.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_24_16" id="tag_20_24_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The set-user-ID and set-group-ID bits are explicitly cleared when files are created. This is to prevent users from creating +programs that are set-user-ID or set-group-ID to them when copying files or to make set-user-ID or set-group-ID files accessible to +new groups of users. For example, if a file is set-user-ID and the copy has a different group ID than the source, a new group of +users has execute permission to a set-user-ID program than did previously. In particular, this is a problem for superusers copying +users' trees.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_24_17" id="tag_20_24_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_24_18" id="tag_20_24_18"></a>RATIONALE</h4> +<blockquote> +<p>The <b>-i</b> option exists on BSD systems, giving applications and users a way to avoid accidentally removing files when +copying. Although the 4.3 BSD version does not prompt if the standard input is not a terminal, the standard developers decided that +use of <b>-i</b> is a request for interaction, so when the destination path exists, the utility takes instructions from whatever +responds on standard input.</p> +<p>The exact format of the interactive prompts is unspecified. Only the general nature of the contents of prompts are specified +because implementations may desire more descriptive prompts than those used on historical implementations. Therefore, an +application using the <b>-i</b> option relies on the system to provide the most suitable dialog directly with the user, based on +the behavior specified.</p> +<p>The <b>-p</b> option is historical practice on BSD systems, duplicating the time of last data modification and time of last +access. This volume of POSIX.1-2024 extends it to preserve the user and group IDs, as well as the file permissions. This +requirement has obvious problems in that the directories are almost certainly modified after being copied. This volume of +POSIX.1-2024 requires that the modification times be preserved. The statement that the order in which the characteristics are +duplicated is unspecified is to permit implementations to provide the maximum amount of security for the user. Implementations +should take into account the obvious security issues involved in setting the owner, group, and mode in the wrong order or creating +files with an owner, group, or mode different from the final value.</p> +<p>It is unspecified whether <i>cp</i> writes diagnostic messages when the user and group IDs cannot be set due to the widespread +practice of users using <b>-p</b> to duplicate some portion of the file characteristics, indifferent to the duplication of others. +Historic implementations only write diagnostic messages on errors other than [EPERM].</p> +<p>Earlier versions of this standard included support for the <b>-r</b> option to copy file hierarchies. The <b>-r</b> option is +historical practice on BSD and BSD-derived systems. This option is no longer specified by POSIX.1-2024 but may be present in some +implementations. The <b>-R</b> option was added as a close synonym to the <b>-r</b> option, selected for consistency with all other +options in this volume of POSIX.1-2024 that do recursive directory descent.</p> +<p>The difference between <b>-R</b> and the removed <b>-r</b> option is in the treatment by <i>cp</i> of file types other than +regular and directory. It was implementation-defined how the <b>-</b> option treated special files to allow both historical +implementations and those that chose to support <b>-r</b> with the same abilities as <b>-R</b> defined by this volume of +POSIX.1-2024. The original <b>-r</b> flag, for historic reasons, did not handle special files any differently from regular files, +but always read the file and copied its contents. This had obvious problems in the presence of special file types; for example, +character devices, FIFOs, and sockets.</p> +<p>When a failure occurs during the copying of a file hierarchy, <i>cp</i> is required to attempt to copy files that are on the +same level in the hierarchy or above the file where the failure occurred. It is unspecified if <i>cp</i> shall attempt to copy +files below the file where the failure occurred (which cannot succeed in any case).</p> +<p>Permissions, owners, and groups of created special file types have been deliberately left as implementation-defined. This is to +allow systems to satisfy special requirements (for example, allowing users to create character special devices, but requiring them +to be owned by a certain group). In general, it is strongly suggested that the permissions, owner, and group be the same as if the +user had run the historical <i>mknod</i>, <a href="../utilities/ln.html"><i>ln</i></a>, or other utility to create the file. It is +also probable that additional privileges are required to create block, character, or other implementation-defined special file +types.</p> +<p>Additionally, the <b>-p</b> option explicitly requires that all set-user-ID and set-group-ID permissions be discarded if any of +the owner or group IDs cannot be set. This is to keep users from unintentionally giving away special privilege when copying +programs.</p> +<p>When creating regular files, historical versions of <i>cp</i> use the mode of the source file as modified by the file mode +creation mask. Other choices would have been to use the mode of the source file unmodified by the creation mask or to use the same +mode as would be given to a new file created by the user (plus the execution bits of the source file) and then modify it by the +file mode creation mask. In the absence of any strong reason to change historic practice, it was in large part retained.</p> +<p>When creating directories, historical versions of <i>cp</i> use the mode of the source directory, plus read, write, and search +bits for the owner, as modified by the file mode creation mask. This is done so that <i>cp</i> can copy trees where the user has +read permission, but the owner does not. A side-effect is that if the file creation mask denies the owner permissions, <i>cp</i> +fails. Also, once the copy is done, historical versions of <i>cp</i> set the permissions on the created directory to be the same as +the source directory, unmodified by the file creation mask.</p> +<p>This behavior has been modified so that <i>cp</i> is always able to create the contents of the directory, regardless of the file +creation mask. After the copy is done, the permissions are set to be the same as the source directory, as modified by the file +creation mask. This latter change from historical behavior is to prevent users from accidentally creating directories with +permissions beyond those they would normally set and for consistency with the behavior of <i>cp</i> in creating files.</p> +<p>It is not a requirement that <i>cp</i> detect attempts to copy a file to itself; however, implementations are strongly +encouraged to do so. Historical implementations have detected the attempt in most cases.</p> +<p>There are two methods of copying subtrees in this volume of POSIX.1-2024. The other method is described as part of the <a href= +"../utilities/pax.html"><i>pax</i></a> utility (see <a href="../utilities/pax.html#"><i>pax</i></a> ). Both methods are historical +practice. The <i>cp</i> utility provides a simpler, more intuitive interface, while <a href="../utilities/pax.html"><i>pax</i></a> +offers a finer granularity of control. Each provides additional functionality to the other; in particular, <a href= +"../utilities/pax.html"><i>pax</i></a> maintains the hard-link structure of the hierarchy, while <i>cp</i> does not. It is the +intention of the standard developers that the results be similar (using appropriate option combinations in both utilities). The +results are not required to be identical; there seemed insufficient gain to applications to balance the difficulty of +implementations having to guarantee that the results would be exactly identical.</p> +<p>The wording allowing <i>cp</i> to copy a directory to implementation-defined file types not specified by the System Interfaces +volume of POSIX.1-2024 is provided so that implementations supporting symbolic links are not required to prohibit copying +directories to symbolic links. Other extensions to the System Interfaces volume of POSIX.1-2024 file types may need to use this +loophole as well.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_24_19" id="tag_20_24_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a +<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require +implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_24_20" id="tag_20_24_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/mv.html#"><i>mv</i></a> , <a href="../utilities/find.html#"><i>find</i></a> , <a href= +"../utilities/ln.html#"><i>ln</i></a> , <a href="../utilities/pax.html#"><i>pax</i></a></p> +<p>XBD <a href="../basedefs/V1_chap04.html#tag_04_07"><i>4.7 File Access Permissions</i></a> , <a href= +"../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 +Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/open.html#"><i>open</i></a> , <a href="../functions/unlink.html#tag_17_649"><i>unlink</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_24_21" id="tag_20_24_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_24_22" id="tag_20_24_22"></a>Issue 6</h4> +<blockquote> +<p>The <b>-r</b> option is marked obsolescent.</p> +<p>The new options <b>-H</b>, <b>-L</b>, and <b>-P</b> are added to align with the IEEE P1003.2b draft standard. These options +affect the processing of symbolic links.</p> +<p>IEEE PASC Interpretation 1003.2 #194 is applied, adding a description of the <b>-P</b> option.</p> +<p>IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/18 is applied, correcting an error in the SEE ALSO section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_24_23" id="tag_20_24_23"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #126 is applied, changing the description of the <i>LC_MESSAGES</i> environment +variable.</p> +<p>Austin Group Interpretations 1003.1-2001 #092, #164, #165, and #168 are applied.</p> +<p>SD5-XCU-ERN-31 and SD5-XCU-ERN-42 are applied, updating the DESCRIPTION.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>SD5-XCU-ERN-102 is applied, clarifying the <b>-i</b> option within the OPTIONS section.</p> +<p>The obsolescent <b>-r</b> option is removed.</p> +<p>The <b>-P</b> option is added to the SYNOPSIS and to the DESCRIPTION with respect to the <b>-R</b> option.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_24_24" id="tag_20_24_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to disallow the creation of filenames containing any bytes that +have the encoded value of a <newline> character.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1732 is applied, changing the EXIT STATUS section.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/compress.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/crontab.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/crontab.html b/bdd/crontab.html @@ -0,0 +1,321 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>crontab</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/cp.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/csplit.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="crontab" id="crontab"></a> <a name="tag_20_25" id="tag_20_25"></a><!-- crontab --> +<h4 class="mansect"><a name="tag_20_25_01" id="tag_20_25_01"></a>NAME</h4> +<blockquote>crontab — schedule periodic background work</blockquote> +<h4 class="mansect"><a name="tag_20_25_02" id="tag_20_25_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>crontab</tt> <b>[</b><i>file</i><b>]</b> <tt><br> +<br> +<sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> crontab</tt> <b>[</b><tt><img src="../images/opt-start.gif" border= +"0">-e<img src="../images/opt-end.gif" border="0">|-l|-r</tt><b>]</b> <tt><br></tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_25_03" id="tag_20_25_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>crontab</i> utility shall create, replace, <sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src= +"../images/opt-start.gif" alt="[Option Start]" border="0"> or edit a user's crontab entry; <img src="../images/opt-end.gif" +alt="[Option End]" border="0"> a crontab entry is a list of commands and the times at which they shall be executed. The new +crontab entry can be input by specifying <i>file</i> or input from standard input if no <i>file</i> operand is specified, +<sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> + or by using an editor, if <b>-e</b> is specified. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p> +<p>Upon execution of a command from a crontab entry, the implementation shall supply a default environment, defining at least the +following environment variables:</p> +<dl compact> +<dd></dd> +<dt><i>HOME</i></dt> +<dd>A pathname of the user's home directory.</dd> +<dt><i>LOGNAME</i></dt> +<dd>The user's login name.</dd> +<dt><i>PATH</i></dt> +<dd>A string representing a search path guaranteed to find all of the standard utilities.</dd> +<dt><i>SHELL</i></dt> +<dd>A pathname of the command interpreter. When <i>crontab</i> is invoked as specified by this volume of POSIX.1-2024, the value +shall be a pathname for <a href="../utilities/sh.html"><i>sh</i></a>.</dd> +</dl> +<p>The values of these variables when <i>crontab</i> is invoked as specified by this volume of POSIX.1-2024 shall not affect the +default values provided when the scheduled command is run.</p> +<p>If standard output and standard error are not redirected by commands executed from the crontab entry, any generated output or +errors shall be mailed, via an implementation-defined method, to the user.</p> +<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Users shall be permitted to use <i>crontab</i> if their names appear in the file <b>cron.allow</b> which is located in an +implementation-defined directory. If that file does not exist, the file <b>cron.deny</b>, which is located in an +implementation-defined directory, shall be checked to determine whether the user shall be denied access to <i>crontab</i>. If +neither file exists, only a process with appropriate privileges shall be allowed to submit a job. If only <b>cron.deny</b> exists +and is empty, global usage shall be permitted. The <b>cron.allow</b> and <b>cron.deny</b> files shall consist of one user name per +line. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_25_04" id="tag_20_25_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>crontab</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-e</b></dt> +<dd><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Edit a copy of the invoking user's crontab entry, or create an empty entry to edit if the crontab entry does not exist. When +editing is complete, the entry shall be installed as the user's crontab entry. <img src="../images/opt-end.gif" alt="[Option End]" +border="0"></dd> +<dt><b>-l</b></dt> +<dd>(The letter ell.) List the invoking user's crontab entry.</dd> +<dt><b>-r</b></dt> +<dd>Remove the invoking user's crontab entry.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_25_05" id="tag_20_25_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>The pathname of a file that contains specifications, in the format defined in the INPUT FILES section, for crontab +entries.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_25_06" id="tag_20_25_06"></a>STDIN</h4> +<blockquote> +<p>See the INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_25_07" id="tag_20_25_07"></a>INPUT FILES</h4> +<blockquote> +<p>In the POSIX locale, the user or application shall ensure that a crontab entry is a text file consisting of lines of six fields +each. The fields shall be separated by <blank> characters. The first five fields shall be integer patterns that specify the +following:</p> +<ol> +<li> +<p>Minute [0,59]</p> +</li> +<li> +<p>Hour [0,23]</p> +</li> +<li> +<p>Day of the month [1,31]</p> +</li> +<li> +<p>Month of the year [1,12]</p> +</li> +<li> +<p>Day of the week ([0,6] with 0=Sunday)</p> +</li> +</ol> +<p>Each of these patterns can be either an <asterisk> (meaning all valid values), an element, or a list of elements separated +by <comma> characters. An element shall be either a number or two numbers separated by a <hyphen-minus> (meaning an +inclusive range). The specification of days can be made by two fields (day of the month and day of the week). If month, day of +month, and day of week are all <asterisk> characters, every day shall be matched. If either the month or day of month is +specified as an element or list, but the day of week is an <asterisk>, the month and day of month fields shall specify the +days that match. If both month and day of month are specified as an <asterisk>, but day of week is an element or list, then +only the specified days of the week match. Finally, if either the month or day of month is specified as an element or list, and the +day of week is also specified as an element or list, then any day matching either the month and day of month, or the day of week, +shall be matched.</p> +<p>The sixth field of a line in a crontab entry is a string that shall be executed by <a href="../utilities/sh.html"><i>sh</i></a> +at the specified times. A <percent-sign> character in this field shall be translated to a <newline>. Any character +preceded by a <backslash> (including the <tt>'%'</tt>) shall cause that character to be treated literally. Only the first +line (up to a <tt>'%'</tt> or end-of-line) of the command field shall be executed by the command interpreter. The other lines shall +be made available to the command as standard input.</p> +<p>Blank lines and those whose first non-<blank> is <tt>'#'</tt> shall be ignored.</p> +<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +The text files <b>cron.allow</b> and <b>cron.deny</b>, which are located in an implementation-defined directory, shall contain zero +or more user names, one per line, of users who are, respectively, authorized or denied access to the service underlying the +<i>crontab</i> utility. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_25_08" id="tag_20_25_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>crontab</i>:</p> +<dl compact> +<dd></dd> +<dt><i>EDITOR</i></dt> +<dd>Determine the editor to be invoked when the <b>-e</b> option is specified. The default editor shall be <a href= +"../utilities/vi.html"><i>vi</i></a>.</dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_25_09" id="tag_20_25_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_25_10" id="tag_20_25_10"></a>STDOUT</h4> +<blockquote> +<p>If the <b>-l</b> option is specified, the crontab entry shall be written to the standard output.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_25_11" id="tag_20_25_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_25_12" id="tag_20_25_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_25_13" id="tag_20_25_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_25_14" id="tag_20_25_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_25_15" id="tag_20_25_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>The user's crontab entry is not submitted, removed, <sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src= +"../images/opt-start.gif" alt="[Option Start]" border="0"> edited, <img src="../images/opt-end.gif" alt="[Option End]" +border="0"> or listed.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_25_16" id="tag_20_25_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The format of the crontab entry shown here is guaranteed only for the POSIX locale. Other cultures may be supported with +substantially different interfaces, although implementations are encouraged to provide comparable levels of functionality.</p> +<p>The default settings of the <i>HOME ,</i> <i>LOGNAME ,</i> <i>PATH ,</i> and <i>SHELL</i> variables that are given to the +scheduled job are not affected by the settings of those variables when <i>crontab</i> is run; as stated, they are defaults. The +text about "invoked as specified by this volume of POSIX.1-2024" means that the implementation may provide extensions that allow +these variables to be affected at runtime, but that the user has to take explicit action in order to access the extension, such as +give a new option flag or modify the format of the crontab entry.</p> +<p>A typical user error is to type only <i>crontab</i>; this causes the system to wait for the new crontab entry on standard input. +If end-of-file is typed (generally <control>-D), the crontab entry is replaced by an empty file. In this case, the user +should type the interrupt character, which prevents the crontab entry from being replaced.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_25_17" id="tag_20_25_17"></a>EXAMPLES</h4> +<blockquote> +<ol> +<li> +<p>Clean up files named <b>core</b> every weekday morning at 3:15 am:</p> +<pre> +<tt>15 3 * * 1-5 find "$HOME" -name core -exec rm -f {} + 2>/dev/null +</tt></pre></li> +<li> +<p>Mail a birthday greeting:</p> +<pre> +<tt>0 12 14 2 * mailx john%Happy Birthday!%Time for lunch. +</tt></pre></li> +<li> +<p>As an example of specifying the two types of days:</p> +<pre> +<tt>0 0 1,15 * 1 +</tt></pre> +<p>would run a command on the first and fifteenth of each month, as well as on every Monday. To specify days by only one field, the +other field should be set to <tt>'*'</tt>; for example:</p> +<pre> +<tt>0 0 * * 1 +</tt></pre> +<p>would run a command only on Mondays.</p> +</li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_25_18" id="tag_20_25_18"></a>RATIONALE</h4> +<blockquote> +<p>All references to a <i>cron</i> daemon and to <i>cron</i> <i>files</i> have been omitted. Although historical implementations +have used this arrangement, there is no reason to limit future implementations.</p> +<p>This description of <i>crontab</i> is designed to support only users with normal privileges. The format of the input is based on +the System V <i>crontab</i>; however, there is no requirement here that the actual system database used by the <i>cron</i> daemon +(or a similar mechanism) use this format internally. For example, systems derived from BSD are likely to have an additional field +appended that indicates the user identity to be used when the job is submitted.</p> +<p>The <b>-e</b> option was adopted from the SVID as a user convenience, although it does not exist in all historical +implementations.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_25_19" id="tag_20_25_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_25_20" id="tag_20_25_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/at.html#"><i>at</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_25_21" id="tag_20_25_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_25_22" id="tag_20_25_22"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_25_23" id="tag_20_25_23"></a>Issue 7</h4> +<blockquote> +<p>The <i>crontab</i> utility (except for the <b>-e</b> option) is moved from the User Portability Utilities option to the Base. +User Portability Utilities is now an option for interactive utilities.</p> +<p>SD5-XCU-ERN-95 is applied, removing the references to fixed locations for the files referenced by the <i>crontab</i> +utility.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>The first example is changed to remove the unreliable use of <a href="../utilities/find.html"><i>find</i></a> | <a href= +"../utilities/xargs.html"><i>xargs</i></a>.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0079 [584] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_25_24" id="tag_20_25_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1141 is applied, changing "core files" to "files named core".</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/cp.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/csplit.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/csplit.html b/bdd/csplit.html @@ -0,0 +1,280 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>csplit</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/crontab.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/ctags.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="csplit" id="csplit"></a> <a name="tag_20_26" id="tag_20_26"></a><!-- csplit --> +<h4 class="mansect"><a name="tag_20_26_01" id="tag_20_26_01"></a>NAME</h4> +<blockquote>csplit — split files based on context</blockquote> +<h4 class="mansect"><a name="tag_20_26_02" id="tag_20_26_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>csplit</tt> <b>[</b><tt>-ks</tt><b>] [</b><tt>-f</tt> <i>prefix</i><b>] [</b><tt>-n</tt> <i>number</i><b>]</b> <i>file +arg</i><tt>...</tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_26_03" id="tag_20_26_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>csplit</i> utility shall read the file named by the <i>file</i> operand, write all or part of that file into other files +as directed by the <i>arg</i> operands, and write the sizes of the files.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_26_04" id="tag_20_26_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>csplit</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-f </b><i>prefix</i></dt> +<dd>Name the created files <i>prefix</i><b>00</b>, <i>prefix</i><b>01</b>, ..., <i>prefixn</i>. The default is <b>xx00</b> ... +<b>xx</b><i>n</i>. If the <i>prefix</i> argument would create a filename exceeding {NAME_MAX} bytes, an error shall result, +<i>csplit</i> shall exit with a diagnostic message, and no files shall be created.</dd> +<dt><b>-k</b></dt> +<dd>Leave previously created files intact. By default, <i>csplit</i> shall remove created files if an error occurs.</dd> +<dt><b>-n </b><i>number</i></dt> +<dd>Use <i>number</i> decimal digits to form filenames for the file pieces. The default shall be 2.</dd> +<dt><b>-s</b></dt> +<dd>Suppress the output of file size messages.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_26_05" id="tag_20_26_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>The pathname of a text file to be split. If <i>file</i> is <tt>'-'</tt>, the standard input shall be used.</dd> +</dl> +<p>Each <i>arg</i> operand can be one of the following:</p> +<dl compact> +<dd></dd> +<dt>/<i>rexp</i>/<b>[</b><i>offset</i><b>]</b></dt> +<dd><br> +A file shall be created using the content of the lines from the current line up to, but not including, the line that results from +the evaluation of the regular expression with <i>offset</i>, if any, applied. The regular expression <i>rexp</i> shall follow the +rules for basic regular expressions described in XBD <a href="../basedefs/V1_chap09.html#tag_09_03"><i>9.3 Basic Regular +Expressions</i></a> . The application shall use the sequence <tt>"\/"</tt> to specify a <slash> character within the +<i>rexp</i>. The optional offset shall be a positive or negative integer value representing a number of lines. A positive integer +value can be preceded by <tt>'+'</tt>. If the selection of lines from an <i>offset</i> expression of this type would create a file +with zero lines, or one with greater than the number of lines left in the input file, the results are unspecified. After the +section is created, the current line shall be set to the line that results from the evaluation of the regular expression with any +offset applied. If the current line is the first line in the file and a regular expression operation has not yet been performed, +the pattern match of <i>rexp</i> shall be applied from the current line to the end of the file. Otherwise, the pattern match of +<i>rexp</i> shall be applied from the line following the current line to the end of the file.</dd> +<dt>%<i>rexp</i>%<b>[</b><i>offset</i><b>]</b></dt> +<dd><br> +Equivalent to /<i>rexp</i>/<b>[</b><i>offset</i><b>]</b>, except that no file shall be created for the selected section of the +input file. The application shall use the sequence <tt>"\%"</tt> to specify a <percent-sign> character within the +<i>rexp</i>.</dd> +<dt><i>line_no</i></dt> +<dd>Create a file from the current line up to (but not including) the line number <i>line_no</i>. Lines in the file shall be +numbered starting at one. The current line becomes <i>line_no</i>.</dd> +<dt>{<i>num</i>}</dt> +<dd>Repeat operand. This operand can follow any of the operands described previously. If it follows a <i>rexp</i> type operand, +that operand shall be applied <i>num</i> more times. If it follows a <i>line_no</i> operand, the file shall be split every +<i>line_no</i> lines, <i>num</i> times, from that point.</dd> +</dl> +<p>An error shall be reported if an operand does not reference a line between the current position and the end of the file.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_26_06" id="tag_20_26_06"></a>STDIN</h4> +<blockquote> +<p>See the INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_26_07" id="tag_20_26_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input file shall be a text file.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_26_08" id="tag_20_26_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>csplit</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_COLLATE</i></dt> +<dd><br> +Determine the locale for the behavior of ranges, equivalence classes, and multi-character collating elements within regular +expressions.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files) and the behavior of character classes within regular +expressions.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_26_09" id="tag_20_26_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>If the <b>-k</b> option is specified, created files shall be retained. Otherwise, the default action occurs.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_26_10" id="tag_20_26_10"></a>STDOUT</h4> +<blockquote> +<p>Unless the <b>-s</b> option is used, the standard output shall consist of one line per file created, with a format as +follows:</p> +<pre> +<tt>"%d\n", <</tt><i>file size in bytes</i><tt>> +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_26_11" id="tag_20_26_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_26_12" id="tag_20_26_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>The output files shall contain portions of the original input file; otherwise, unchanged.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_26_13" id="tag_20_26_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_26_14" id="tag_20_26_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_26_15" id="tag_20_26_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>By default, created files shall be removed if an error occurs. When the <b>-k</b> option is specified, created files shall not +be removed if an error occurs.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_26_16" id="tag_20_26_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_26_17" id="tag_20_26_17"></a>EXAMPLES</h4> +<blockquote> +<ol> +<li> +<p>This example creates four files, <b>cobol00</b> ... <b>cobol03</b>:</p> +<pre> +<tt>csplit -f cobol file '/procedure division/' /par5./ /par16./ +</tt></pre> +<p>After editing the split files, they can be recombined as follows:</p> +<pre> +<tt>cat cobol0[0-3] > file +</tt></pre> +<p>Note that this example overwrites the original file.</p> +</li> +<li> +<p>This example would split the file after the first 99 lines, and every 100 lines thereafter, up to 9999 lines; this is because +lines in the file are numbered from 1 rather than zero, for historical reasons:</p> +<pre> +<tt>csplit -k file 100 {99} +</tt></pre></li> +<li> +<p>Assuming that <b>prog.c</b> follows the C-language coding convention of ending routines with a <tt>'}'</tt> at the beginning of +the line, this example creates a file containing each separate C routine (up to 21) in <b>prog.c</b>:</p> +<pre> +<tt>csplit -k prog.c '%main(%' '/^}/+1' {20} +</tt></pre></li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_26_18" id="tag_20_26_18"></a>RATIONALE</h4> +<blockquote> +<p>The <b>-n</b> option was added to extend the range of filenames that could be handled.</p> +<p>Consideration was given to adding a <b>-a</b> flag to use the alphabetic filename generation used by the historical <a href= +"../utilities/split.html"><i>split</i></a> utility, but the functionality added by the <b>-n</b> option was deemed to make +alphabetic naming unnecessary.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_26_19" id="tag_20_26_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a +<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require +implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_26_20" id="tag_20_26_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/sed.html#"><i>sed</i></a> , <a href="../utilities/split.html#"><i>split</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap09.html#tag_09_03"><i>9.3 Basic Regular Expressions</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_26_21" id="tag_20_26_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_26_22" id="tag_20_26_22"></a>Issue 5</h4> +<blockquote> +<p>The FUTURE DIRECTIONS section is added.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_26_23" id="tag_20_26_23"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +<p>The APPLICATION USAGE section is added.</p> +<p>The description of regular expression operands is changed to align with the IEEE P1003.2b draft standard.</p> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_26_24" id="tag_20_26_24"></a>Issue 7</h4> +<blockquote> +<p>The <i>csplit</i> utility is moved from the User Portability Utilities option to the Base. User Portability Utilities is now an +option for interactive utilities.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>The SYNOPSIS and OPERANDS sections are revised to use a single <i>arg</i> to split a file into two pieces.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_26_25" id="tag_20_26_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to disallow the creation of filenames containing any bytes that +have the encoded value of a <newline> character.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/crontab.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/ctags.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/ctags.html b/bdd/ctags.html @@ -0,0 +1,354 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>ctags</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/csplit.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/cut.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="ctags" id="ctags"></a> <a name="tag_20_27" id="tag_20_27"></a><!-- ctags --> +<h4 class="mansect"><a name="tag_20_27_01" id="tag_20_27_01"></a>NAME</h4> +<blockquote>ctags — create a tags file (<b>DEVELOPMENT</b>)</blockquote> +<h4 class="mansect"><a name="tag_20_27_02" id="tag_20_27_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('CD%20SD')">CD SD</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> ctags</tt> <b>[</b><tt>-a</tt><b>] [</b><tt>-f</tt> <i>tagsfile</i><b>]</b> <i>pathname</i><tt>...<br> +<br> +ctags -x</tt> <i>pathname</i><tt>... <img src="../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div> +<tt><br></tt></blockquote> +<h4 class="mansect"><a name="tag_20_27_03" id="tag_20_27_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>ctags</i> utility shall write a <i>tagsfile</i> or an index of objects from C-language source files specified by the +<i>pathname</i> operands. The <i>tagsfile</i> shall list the locators of C-language objects within the source files. A locator +consists of a name, pathname, and either a search pattern or a line number that can be used in searching for the object definition. +The objects that shall be recognized are specified in the EXTENDED DESCRIPTION section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_27_04" id="tag_20_27_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>ctags</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-a</b></dt> +<dd>Append to <i>tagsfile</i>.</dd> +<dt><b>-f </b><i>tagsfile</i></dt> +<dd>Write the object locator lists into <i>tagsfile</i> instead of the default file named <b>tags</b> in the current +directory.</dd> +<dt><b>-x</b></dt> +<dd>Produce a list of object names, the line number, and filename in which each is defined, as well as the text of that line, and +write this to the standard output. A <i>tagsfile</i> shall not be created when <b>-x</b> is specified.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_27_05" id="tag_20_27_05"></a>OPERANDS</h4> +<blockquote> +<p>The following <i>pathname</i> operands are supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i><b>.c</b></dt> +<dd>Files with basenames ending with the <b>.c</b> suffix shall be treated as C-language source code. Such files that are not valid +input to <a href="../utilities/c17.html"><i>c17</i></a> produce unspecified results.</dd> +<dt><i>file</i><b>.h</b></dt> +<dd>Files with basenames ending with the <b>.h</b> suffix shall be treated as C-language source code. Such files that are not valid +input to <a href="../utilities/c17.html"><i>c17</i></a> produce unspecified results.</dd> +</dl> +<p>The handling of other files is implementation-defined.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_27_06" id="tag_20_27_06"></a>STDIN</h4> +<blockquote> +<p>See the INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_27_07" id="tag_20_27_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files shall be text files containing C-language source code.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_27_08" id="tag_20_27_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>ctags</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_COLLATE</i></dt> +<dd><br> +Determine the order in which output is sorted for the <b>-x</b> option. The POSIX locale determines the order in which the +<i>tagsfile</i> is written.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). If the locale is not compatible with the C locale described by the +ISO C standard, the results are unspecified.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_27_09" id="tag_20_27_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_27_10" id="tag_20_27_10"></a>STDOUT</h4> +<blockquote> +<p>The list of object name information produced by the <b>-x</b> option shall be written to standard output in the following +format:</p> +<pre> +<tt>"%s %d %s %s", <</tt><i>object-name</i><tt>>, <</tt><i>line-number</i><tt>>, <</tt><i>filename</i><tt>>, <</tt><i>text</i><tt>> +</tt></pre> +<p>where <<i>text</i>> is the text of line <<i>line-number</i>> of file <<i>filename</i>>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_27_11" id="tag_20_27_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_27_12" id="tag_20_27_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>When the <b>-x</b> option is not specified, the format of the output file shall be:</p> +<pre> +<tt>"%s\t%s\t/%s/\n", <</tt><i>identifier</i><tt>>, <</tt><i>filename</i><tt>>, <</tt><i>pattern</i><tt>> +</tt></pre> +<p>where <<i>pattern</i>> is a search pattern that could be used by an editor to find the defining instance of +<<i>identifier</i>> in <<i>filename</i>> (where <i>defining instance</i> is indicated by the declarations listed in the +EXTENDED DESCRIPTION).</p> +<p>An optional <circumflex> (<tt>'^'</tt>) can be added as a prefix to <<i>pattern</i>>, and an optional +<dollar-sign> can be appended to <<i>pattern</i>> to indicate that the pattern is anchored to the beginning (end) of a +line of text. Any <slash> or <backslash> characters in <<i>pattern</i>> shall be preceded by a <backslash> +character. The anchoring <circumflex>, <dollar-sign>, and escaping <backslash> characters shall not be considered +part of the search pattern. All other characters in the search pattern shall be considered literal characters.<br></p> +<p>An alternative format is:</p> +<pre> +<tt>"%s\t%s\t?%s?\n", <</tt><i>identifier</i><tt>>, <</tt><i>filename</i><tt>>, <</tt><i>pattern</i><tt>> +</tt></pre> +<p>which is identical to the first format except that <slash> characters in <<i>pattern</i>> shall not be preceded by +escaping <backslash> characters, and <question-mark> characters in <<i>pattern</i>> shall be preceded by +<backslash> characters.</p> +<p>A second alternative format is:</p> +<pre> +<tt>"%s\t%s\t%d\n", <</tt><i>identifier</i><tt>>, <</tt><i>filename</i><tt>>, <</tt><i>lineno</i><tt>> +</tt></pre> +<p>where <<i>lineno</i>> is a decimal line number that could be used by an editor to find <<i>identifier</i>> in +<<i>filename</i>>.</p> +<p>Neither alternative format shall be produced by <i>ctags</i> when it is used as described by POSIX.1-2024, but the standard +utilities that process tags files shall be able to process those formats as well as the first format.</p> +<p>In any of these formats, the file shall be sorted by identifier, based on the collation sequence in the POSIX locale.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_27_13" id="tag_20_27_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>The <i>ctags</i> utility shall attempt to produce an output line for each of the following objects:</p> +<ul> +<li> +<p>Function definitions</p> +</li> +<li> +<p>Type definitions</p> +</li> +<li> +<p>Macros with arguments</p> +</li> +</ul> +<p>It may also produce output for any of the following objects:</p> +<ul> +<li> +<p>Function prototypes</p> +</li> +<li> +<p>Structures</p> +</li> +<li> +<p>Unions</p> +</li> +<li> +<p>Global variable definitions</p> +</li> +<li> +<p>Enumeration types</p> +</li> +<li> +<p>Macros without arguments</p> +</li> +<li> +<p><b>#define</b> statements</p> +</li> +<li> +<p><b>#line</b> statements</p> +</li> +</ul> +<p>Any <b>#if</b> and <b>#ifdef</b> statements shall produce no output. The tag <b>main</b> is treated specially in C programs. The +tag formed shall be created by prefixing <b>M</b> to the name of the file, with the trailing <b>.c</b>, and leading pathname +components (if any) removed.</p> +<p>It is implementation-defined what other objects (including duplicate identifiers) produce output.</p> +<p>On systems that do not support the C-Language Development Utilities option, if <i>ctags</i> is supported it produces unspecified +results for C-language source code files. It should write to standard error a message identifying this condition and cause a +non-zero exit status to be produced.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_27_14" id="tag_20_27_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_27_15" id="tag_20_27_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_27_16" id="tag_20_27_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The output with <b>-x</b> is meant to be a simple index that can be written out as an off-line readable function index. If the +input files to <i>ctags</i> (such as <b>.c</b> files) were not created using the same locale as that in effect when <i>ctags</i> +<b>-x</b> is run, results might not be as expected.</p> +<p>The description of C-language processing says "attempts to" because the C language can be greatly confused, especially through +the use of <b>#define</b>s, and this utility would be of no use if the real C preprocessor were run to identify them. The output +from <i>ctags</i> may be fooled and incorrect for various constructs.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_27_17" id="tag_20_27_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_27_18" id="tag_20_27_18"></a>RATIONALE</h4> +<blockquote> +<p>The option list was significantly reduced from that provided by historical implementations. The <b>-F</b> option was omitted as +redundant, since it is the default. The <b>-B</b> option was omitted as being of very limited usefulness. The <b>-t</b> option was +omitted since the recognition of <b>typedef</b>s is now required for C source files. The <b>-u</b> option was omitted because the +update function was judged to be not only inefficient, but also rarely needed.</p> +<p>An early proposal included a <b>-w</b> option to suppress warning diagnostics. Since the types of such diagnostics could not be +described, the option was omitted as being not useful.</p> +<p>The text for <i>LC_CTYPE</i> about compatibility with the C locale acknowledges that the ISO C standard imposes +requirements on the locale used to process C source. This could easily be a superset of that known as "the C locale" by way of +implementation extensions, or one of a few alternative locales for systems supporting different codesets.</p> +<p>The collation sequence of the tags file is not affected by <i>LC_COLLATE</i> because it is typically not used by human readers, +but only by programs such as <a href="../utilities/vi.html"><i>vi</i></a> to locate the tag within the source files. Using the +POSIX locale eliminates some of the problems of coordinating locales between the <i>ctags</i> file creator and the <a href= +"../utilities/vi.html"><i>vi</i></a> file reader.</p> +<p>Historically, the tags file has been used only by <a href="../utilities/ex.html"><i>ex</i></a> and <a href= +"../utilities/vi.html"><i>vi</i></a>. However, the format of the tags file has been published to encourage other programs to use +the tags in new ways. The format allows either patterns or line numbers to find the identifiers because the historical <a href= +"../utilities/vi.html"><i>vi</i></a> recognizes either. The <i>ctags</i> utility does not produce the format using line numbers +because it is not useful following any source file changes that add or delete lines. The documented search patterns match +historical practice. It should be noted that literal leading <circumflex> or trailing <dollar-sign> characters in the +search pattern will only behave correctly if anchored to the beginning of the line or end of the line by an additional +<circumflex> or <dollar-sign> character.</p> +<p>Historical implementations also understand the objects used by the languages FORTRAN, Pascal, and sometimes LISP, and they +understand the C source output by <a href="../utilities/lex.html"><i>lex</i></a> and <a href= +"../utilities/yacc.html"><i>yacc</i></a>. The <i>ctags</i> utility is not required to accommodate these languages, although +implementors are encouraged to do so.</p> +<p>The following historical option was not specified, as <i>vgrind</i> is not included in this volume of POSIX.1-2024:</p> +<dl compact> +<dd></dd> +<dt><b>-v</b></dt> +<dd>If the <b>-v</b> flag is given, an index of the form expected by <i>vgrind</i> is produced on the standard output. This listing +contains the function name, filename, and page number (assuming 64-line pages). Since the output is sorted into lexicographic +order, it may be desired to run the output through <a href="../utilities/sort.html"><i>sort</i></a> <b>-f</b>. Sample use: +<pre> +<tt>ctags -v files | sort -f > index +vgrind -x index +</tt></pre></dd> +</dl> +<p>The special treatment of the tag <b>main</b> makes the use of <i>ctags</i> practical in directories with more than one +program.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_27_19" id="tag_20_27_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +<p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a +<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require +implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_27_20" id="tag_20_27_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/c17.html#"><i>c17</i></a> , <a href="../utilities/vi.html#"><i>vi</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_27_21" id="tag_20_27_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_27_22" id="tag_20_27_22"></a>Issue 5</h4> +<blockquote> +<p>The FUTURE DIRECTIONS section is added.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_27_23" id="tag_20_27_23"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +<p>The OUTPUT FILES section is changed to align with the IEEE P1003.2b draft standard.</p> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +<p>IEEE PASC Interpretation 1003.2 #168 is applied, changing "create" to "write" in the DESCRIPTION.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_27_24" id="tag_20_27_24"></a>Issue 7</h4> +<blockquote> +<p>The <i>ctags</i> utility is no longer dependent on support for the User Portability Utilities option.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_27_25" id="tag_20_27_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to behave as follows:</p> +<ol type="a"> +<li> +<p>Report an error if a utility is directed to display a pathname that contains any bytes that have the encoded value of a +<newline> character when <newline> is a terminator or separator in the output format being used.</p> +</li> +<li> +<p>Disallow the creation of filenames containing any bytes that have the encoded value of a <newline> character.</p> +</li> +</ol> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1312 is applied, inserting a missing line break in the example commands in the RATIONALE section.</p> +<p>Austin Group Defect 1330 is applied, removing obsolescent interfaces.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/csplit.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/cut.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/cut.html b/bdd/cut.html @@ -0,0 +1,319 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>cut</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/ctags.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/cxref.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="cut" id="cut"></a> <a name="tag_20_28" id="tag_20_28"></a><!-- cut --> +<h4 class="mansect"><a name="tag_20_28_01" id="tag_20_28_01"></a>NAME</h4> +<blockquote>cut — cut out selected fields of each line of a file</blockquote> +<h4 class="mansect"><a name="tag_20_28_02" id="tag_20_28_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>cut -b</tt> <i>list</i> <b>[</b><tt>-n</tt><b>] [</b><i>file</i><tt>...</tt><b>]</b> <tt><br> +<br> +cut -c</tt> <i>list</i> <b>[</b><i>file</i><tt>...</tt><b>]</b> <tt><br> +<br> +cut -f</tt> <i>list</i> <b>[</b><tt>-d</tt> <i>delim</i><b>] [</b><tt>-s</tt><b>] [</b><i>file</i><tt>...</tt><b>]</b> <tt><br> +</tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_28_03" id="tag_20_28_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>cut</i> utility shall cut out bytes (<b>-b</b> option), characters (<b>-c</b> option), or character-delimited fields +(<b>-f</b> option) from each line in one or more files, concatenate them, and write them to standard output.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_28_04" id="tag_20_28_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>cut</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The application shall ensure that the option-argument <i>list</i> (see options <b>-b</b>, <b>-c</b>, and <b>-f</b> below) is a +<comma>-separated list or <blank>-separated list of positive numbers and ranges. Ranges can be in three forms. The +first is two positive numbers separated by a <hyphen-minus> (<i>low</i>-<i>high</i>), which represents all fields from the +first number to the second number. The second is a positive number preceded by a <hyphen-minus> (-<i>high</i>), which +represents all fields from field number 1 to that number. The third is a positive number followed by a <hyphen-minus> +(<i>low</i>-), which represents that number to the last field, inclusive. The elements in <i>list</i> can be repeated, can overlap, +and can be specified in any order, but the bytes, characters, or fields selected shall be written in the order of the input data. +If an element appears in the selection list more than once, it shall be written exactly once.</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-b </b><i>list</i></dt> +<dd>Cut based on a <i>list</i> of bytes. Each selected byte shall be output unless the <b>-n</b> option is also specified. It shall +not be an error to select bytes not present in the input line.</dd> +<dt><b>-c </b><i>list</i></dt> +<dd>Cut based on a <i>list</i> of characters. Each selected character shall be output. It shall not be an error to select +characters not present in the input line.</dd> +<dt><b>-d </b><i>delim</i></dt> +<dd>Set the field delimiter to the character <i>delim</i>. The default is the <tab>.</dd> +<dt><b>-f </b><i>list</i></dt> +<dd>Cut based on a <i>list</i> of fields, assumed to be separated in the file by a delimiter character (see <b>-d</b>). Each +selected field shall be output. Output fields shall be separated by a single occurrence of the field delimiter character. Lines +with no field delimiters shall be passed through intact, unless <b>-s</b> is specified. It shall not be an error to select fields +not present in the input line.</dd> +<dt><b>-n</b></dt> +<dd>Do not split characters. When specified with the <b>-b</b> option, each element in <i>list</i> of the form +<i>low</i>-<i>high</i> (<hyphen-minus>-separated numbers) shall be modified as follows: +<ul> +<li> +<p>If the byte selected by <i>low</i> is not the first byte of a character, <i>low</i> shall be decremented to select the first +byte of the character originally selected by <i>low</i>. If the byte selected by <i>high</i> is not the last byte of a character, +<i>high</i> shall be decremented to select the last byte of the character prior to the character originally selected by +<i>high</i>, or zero if there is no prior character. If the resulting range element has <i>high</i> equal to zero or <i>low</i> +greater than <i>high</i>, the list element shall be dropped from <i>list</i> for that input line without causing an error.</p> +</li> +</ul> +<p>Each element in <i>list</i> of the form <i>low</i>- shall be treated as above with <i>high</i> set to the number of bytes in the +current line, not including the terminating <newline>. Each element in <i>list</i> of the form -<i>high</i> shall be treated +as above with <i>low</i> set to 1. Each element in <i>list</i> of the form <i>num</i> (a single number) shall be treated as above +with <i>low</i> set to <i>num</i> and <i>high</i> set to <i>num</i>.</p> +</dd> +<dt><b>-s</b></dt> +<dd>Suppress lines with no delimiter characters, when used with the <b>-f</b> option. Unless specified, lines with no delimiters +shall be passed through untouched.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_28_05" id="tag_20_28_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of an input file. If no <i>file</i> operands are specified, or if a <i>file</i> operand is <tt>'-'</tt>, the +standard input shall be used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_28_06" id="tag_20_28_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be used only if no <i>file</i> operands are specified, or if a <i>file</i> operand is <tt>'-'</tt>. See +the INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_28_07" id="tag_20_28_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files shall be text files, except that line lengths shall be unlimited.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_28_08" id="tag_20_28_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>cut</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_28_09" id="tag_20_28_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_28_10" id="tag_20_28_10"></a>STDOUT</h4> +<blockquote> +<p>The <i>cut</i> utility output shall be a concatenation of the selected bytes, characters, or fields (one of the following):</p> +<pre> +<tt>"%s\n", <</tt><i>concatenation of bytes</i><tt>> +<br> +"%s\n", <</tt><i>concatenation of characters</i><tt>> +<br> +"%s\n", <</tt><i>concatenation of fields and field delimiters</i><tt>> +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_28_11" id="tag_20_28_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_28_12" id="tag_20_28_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_28_13" id="tag_20_28_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_28_14" id="tag_20_28_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>All input files were output successfully.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_28_15" id="tag_20_28_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_28_16" id="tag_20_28_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The <i>cut</i> and <a href="../utilities/fold.html"><i>fold</i></a> utilities can be used to create text files out of files with +arbitrary line lengths. The <i>cut</i> utility should be used when the number of lines (or records) needs to remain constant. The +<a href="../utilities/fold.html"><i>fold</i></a> utility should be used when the contents of long lines need to be kept +contiguous.</p> +<p>Earlier versions of the <i>cut</i> utility worked in an environment where bytes and characters were considered equivalent +(modulo <backspace> and <tab> processing in some implementations). In the extended world of multi-byte characters, the +new <b>-b</b> option has been added. The <b>-n</b> option (used with <b>-b</b>) allows it to be used to act on bytes rounded to +character boundaries. The algorithm specified for <b>-n</b> guarantees that:</p> +<pre> +<tt>cut -b 1-500 -n file > file1 +cut -b 501- -n file > file2 +</tt></pre> +<p>ends up with all the characters in <b>file</b> appearing exactly once in <b>file1</b> or <b>file2</b>. (There is, however, a +<newline> in both <b>file1</b> and <b>file2</b> for each <newline> in <b>file</b>.)</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_28_17" id="tag_20_28_17"></a>EXAMPLES</h4> +<blockquote> +<p>Examples of the option qualifier list:</p> +<dl compact> +<dd></dd> +<dt>1,4,7</dt> +<dd>Select the first, fourth, and seventh bytes, characters, or fields and field delimiters.</dd> +<dt>1-3,8</dt> +<dd>Equivalent to 1,2,3,8.</dd> +<dt>-5,10</dt> +<dd>Equivalent to 1,2,3,4,5,10.</dd> +<dt>3-</dt> +<dd>Equivalent to third to last, inclusive.</dd> +</dl> +<p>The <i>low</i>-<i>high</i> forms are not always equivalent when used with <b>-b</b> and <b>-n</b> and multi-byte characters; see +the description of <b>-n</b>.</p> +<p>The following command:</p> +<pre> +<tt>cut -d : -f 1,6 /etc/passwd +</tt></pre> +<p>reads the System V password file (user database) and produces lines of the form:</p> +<pre> +<tt><</tt><i>user ID</i><tt>>:<</tt><i>home directory</i><tt>> +</tt></pre> +<p>Most utilities in this volume of POSIX.1-2024 work on text files. The <i>cut</i> utility can be used to turn files with +arbitrary line lengths into a set of text files containing the same data. The <a href="../utilities/paste.html"><i>paste</i></a> +utility can be used to create (or recreate) files with arbitrary line lengths. For example, if <b>file</b> contains long lines:</p> +<pre> +<tt>cut -b 1-500 -n file > file1 +cut -b 501- -n file > file2 +</tt></pre> +<p>creates <b>file1</b> (a text file) with lines no longer than 500 bytes (plus the <newline>) and <b>file2</b> that contains +the remainder of the data from <b>file</b>. (Note that <b>file2</b> is not a text file if there are lines in <b>file</b> that are +longer than 500 + {LINE_MAX} bytes.) The original file can be recreated from <b>file1</b> and <b>file2</b> using the command:</p> +<pre> +<tt>paste -d "\0" file1 file2 > file +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_28_18" id="tag_20_28_18"></a>RATIONALE</h4> +<blockquote> +<p>Some historical implementations do not count <backspace> characters in determining character counts with the <b>-c</b> +option. This may be useful for using <i>cut</i> for processing <i>nroff</i> output. It was deliberately decided not to have the +<b>-c</b> option treat either <backspace> or <tab> characters in any special fashion. The <a href= +"../utilities/fold.html"><i>fold</i></a> utility does treat these characters specially.</p> +<p>Unlike other utilities, some historical implementations of <i>cut</i> exit after not finding an input file, rather than +continuing to process the remaining <i>file</i> operands. This behavior is prohibited by this volume of POSIX.1-2024, where only +the exit status is affected by this problem.</p> +<p>The behavior of <i>cut</i> when provided with either mutually-exclusive options or options that do not work logically together +has been deliberately left unspecified in favor of global wording in <a href="../utilities/V3_chap01.html#tag_18_04"><i>1.4 Utility +Description Defaults</i></a> .</p> +<p>The OPTIONS section was changed in response to IEEE PASC Interpretation 1003.2 #149. The change represents historical practice +on all known systems. The original standard was ambiguous on the nature of the output.</p> +<p>The <i>list</i> option-arguments are historically used to select the portions of the line to be written, but do not affect the +order of the data. For example:</p> +<pre> +<tt>echo abcdefghi | cut -c6,2,4-7,1 +</tt></pre> +<p>yields <tt>"abdefg"</tt>.</p> +<p>A proposal to enhance <i>cut</i> with the following option:</p> +<dl compact> +<dd></dd> +<dt><b>-o</b></dt> +<dd>Preserve the selected field order. When this option is specified, each byte, character, or field (or ranges of such) shall be +written in the order specified by the <i>list</i> option-argument, even if this requires multiple outputs of the same bytes, +characters, or fields.</dd> +</dl> +<p>was rejected because this type of enhancement is outside the scope of the IEEE P1003.2b draft standard.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_28_19" id="tag_20_28_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_28_20" id="tag_20_28_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19_05"><i>2.5 Parameters and Variables</i></a> , <a href= +"../utilities/fold.html#"><i>fold</i></a> , <a href="../utilities/grep.html#"><i>grep</i></a> , <a href= +"../utilities/paste.html#"><i>paste</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_28_21" id="tag_20_28_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_28_22" id="tag_20_28_22"></a>Issue 6</h4> +<blockquote> +<p>The OPTIONS section is changed to align with the IEEE P1003.2b draft standard.</p> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_28_23" id="tag_20_28_23"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>SD5-XCU-ERN-171 is applied, adding APPLICATION USAGE.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0080 [584] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_28_24" id="tag_20_28_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/ctags.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/cxref.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/cxref.html b/bdd/cxref.html @@ -0,0 +1,233 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>cxref</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/cut.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/date.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="cxref" id="cxref"></a> <a name="tag_20_29" id="tag_20_29"></a><!-- cxref --> +<h4 class="mansect"><a name="tag_20_29_01" id="tag_20_29_01"></a>NAME</h4> +<blockquote>cxref — generate a C-language program cross-reference table (<b>DEVELOPMENT</b>)</blockquote> +<h4 class="mansect"><a name="tag_20_29_02" id="tag_20_29_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> cxref</tt> <b>[</b><tt>-cs</tt><b>] [</b><tt>-o</tt> <i>file</i><b>] [</b><tt>-w</tt> <i>num</i><b>] +[</b><tt>-D</tt> <i>name</i><b>[</b><tt>=</tt><i>def</i><b>]]</b><tt>...</tt> <b>[</b><tt>-I</tt> <i>dir</i><b>]</b><tt>...<br> + </tt> <b>[</b><tt>-U</tt> <i>name</i><b>]</b><tt>...</tt> <i>file</i><tt>... <img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div> +</blockquote> +<h4 class="mansect"><a name="tag_20_29_03" id="tag_20_29_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>cxref</i> utility shall analyze a collection of C-language <i>file</i>s and attempt to build a cross-reference table. +Information from <b>#define</b> lines shall be included in the symbol table. A sorted listing shall be written to standard output +of all symbols (auto, static, and global) in each <i>file</i> separately, or with the <b>-c</b> option, in combination. Each symbol +shall contain an <asterisk> before the declaring reference.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_29_04" id="tag_20_29_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>cxref</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> , except that the order of the <b>-D</b>, <b>-I</b>, and <b>-U</b> options (which are identical to their +interpretation by <a href="../utilities/c17.html"><i>c17</i></a>) is significant. The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-c</b></dt> +<dd>Write a combined cross-reference of all input files.</dd> +<dt><b>-s</b></dt> +<dd>Operate silently; do not print input filenames.</dd> +<dt><b>-o </b><i>file</i></dt> +<dd>Direct output to named <i>file</i>.</dd> +<dt><b>-w </b><i>num</i></dt> +<dd>Format output no wider than <i>num</i> (decimal) columns. This option defaults to 80 if <i>num</i> is not specified or is less +than 51.</dd> +<dt><b>-D</b></dt> +<dd>Equivalent to <a href="../utilities/c17.html"><i>c17</i></a>.</dd> +<dt><b>-I</b></dt> +<dd>Equivalent to <a href="../utilities/c17.html"><i>c17</i></a>.</dd> +<dt><b>-U</b></dt> +<dd>Equivalent to <a href="../utilities/c17.html"><i>c17</i></a>.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_29_05" id="tag_20_29_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of a C-language source file.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_29_06" id="tag_20_29_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_29_07" id="tag_20_29_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files are C-language source files.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_29_08" id="tag_20_29_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>cxref</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_COLLATE</i></dt> +<dd><br> +Determine the locale for the ordering of the output.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd>Determine the location of messages objects and message catalogs.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_29_09" id="tag_20_29_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_29_10" id="tag_20_29_10"></a>STDOUT</h4> +<blockquote> +<p>The standard output shall be used for the cross-reference listing, unless the <b>-o</b> option is used to select a different +output file.</p> +<p>The format of standard output is unspecified, except that the following information shall be included:</p> +<ul> +<li> +<p>If the <b>-c</b> option is not specified, each portion of the listing shall start with the name of the input file on a separate +line.</p> +</li> +<li> +<p>The name line shall be followed by a sorted list of symbols, each with its associated location pathname, the name of the +function in which it appears (if it is not a function name itself), and line number references.</p> +</li> +<li> +<p>Each line number may be preceded by an <asterisk> (<tt>'*'</tt>) flag, meaning that this is the declaring reference. Other +single-character flags, with implementation-defined meanings, may be included.</p> +</li> +</ul> +</blockquote> +<h4 class="mansect"><a name="tag_20_29_11" id="tag_20_29_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_29_12" id="tag_20_29_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>The output file named by the <b>-o</b> option shall be used instead of standard output.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_29_13" id="tag_20_29_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_29_14" id="tag_20_29_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_29_15" id="tag_20_29_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_29_16" id="tag_20_29_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_29_17" id="tag_20_29_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_29_18" id="tag_20_29_18"></a>RATIONALE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_29_19" id="tag_20_29_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_29_20" id="tag_20_29_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/c17.html#"><i>c17</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_29_21" id="tag_20_29_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_29_22" id="tag_20_29_22"></a>Issue 5</h4> +<blockquote> +<p>In the SYNOPSIS, [<b>-U</b> <i>dir</i>] is changed to [<b>-U</b> <i>name</i>].</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_29_23" id="tag_20_29_23"></a>Issue 6</h4> +<blockquote> +<p>The APPLICATION USAGE section is added.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_29_24" id="tag_20_29_24"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_29_25" id="tag_20_29_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to report an error if a utility is directed to display a +pathname that contains any bytes that have the encoded value of a <newline> character when <newline> is a terminator or +separator in the output format being used.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/cut.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/date.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/date.html b/bdd/date.html @@ -0,0 +1,364 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>date</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/cxref.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/dd.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="date" id="date"></a> <a name="tag_20_30" id="tag_20_30"></a><!-- date --> +<h4 class="mansect"><a name="tag_20_30_01" id="tag_20_30_01"></a>NAME</h4> +<blockquote>date — write the date and time</blockquote> +<h4 class="mansect"><a name="tag_20_30_02" id="tag_20_30_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>date</tt> <b>[</b><tt>-u</tt><b>] [</b><tt>+</tt><i>format</i><b>]</b> <tt><br> +<br></tt></code></p> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> date</tt> <b>[</b><tt>-u</tt><b>]</b> <i>mmddhhmm</i><b>[[</b><i>cc</i><b>]</b><i>yy</i><b>]</b> +<tt><img src="../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div> +<tt><br></tt></blockquote> +<h4 class="mansect"><a name="tag_20_30_03" id="tag_20_30_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>date</i> utility shall write the date and time to standard output <sup>[<a href= +"javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> or attempt +to set the system date and time. <img src="../images/opt-end.gif" alt="[Option End]" border="0"> By default, the current date and +time shall be written. If an operand beginning with <tt>'+'</tt> is specified, the output format of <i>date</i> shall be controlled +by the conversion specifications and other text in the operand.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_30_04" id="tag_20_30_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>date</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following option shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-u</b></dt> +<dd>Perform operations as if the <i>TZ</i> environment variable was set to the string <tt>"UTC0"</tt>, or its equivalent historical +value of <tt>"GMT0"</tt>. Otherwise, <i>date</i> shall use the timezone indicated by the <i>TZ</i> environment variable or the +system default if that variable is unset or null.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_30_05" id="tag_20_30_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt>+<i>format</i></dt> +<dd>When the format is specified, the output shall be formatted as if by <a href="../functions/strftime.html"><i>strftime</i>()</a> +with the specified format string, and a <i>timeptr</i> argument that is the equivalent of <i>localtime</i>(&<i>now</i>) if +<b>-u</b> is not specified or <i>gmtime</i>(&<i>now</i>) if <b>-u</b> is specified, where <i>now</i> is an object of type +<b>time_t</b> containing the return value of <i>time</i>(0). +<p>A <newline> shall always be appended to the output of <a href="../functions/strftime.html"><i>strftime</i>()</a>.</p> +</dd> +<dt><i>mmddhhmm</i><b>[[</b><i>cc</i><b>]</b><i>yy</i><b>]</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border= +"0"><br> +Attempt to set the system date and time from the value given in the operand. This is only possible if the user has appropriate +privileges and the system permits the setting of the system date and time. The first <i>mm</i> is the month (number); <i>dd</i> is +the day (number); <i>hh</i> is the hour (number, 24-hour system); the second <i>mm</i> is the minute (number); <i>cc</i> is the +century and is the first two digits of the year (this is optional); <i>yy</i> is the last two digits of the year and is optional. +If century is not specified, then values in the range [69,99] shall refer to years 1969 to 1999 inclusive, and values in the range +[00,68] shall refer to years 2000 to 2068 inclusive. The current year is the default if <i>yy</i> is omitted. <img src= +"../images/opt-end.gif" alt="[Option End]" border="0"> <basefont size="2"> +<dl> +<dt><b>Note:</b></dt> +<dd>It is expected that in a future version of this standard the default century inferred from a 2-digit year will change. (This +would apply to all commands accepting a 2-digit year as input.)</dd> +</dl> +<basefont size="3"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_30_06" id="tag_20_30_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_30_07" id="tag_20_30_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_30_08" id="tag_20_30_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>date</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>LC_TIME</i></dt> +<dd>Determine the format and contents of date and time strings written by <i>date</i>.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>TZ</i></dt> +<dd>Determine the timezone in which the time and date are written, unless the <b>-u</b> option is specified. If the <i>TZ</i> +variable is unset or null and <b>-u</b> is not specified, an unspecified system default timezone is used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_30_09" id="tag_20_30_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_30_10" id="tag_20_30_10"></a>STDOUT</h4> +<blockquote> +<p>When no formatting operand is specified, the output in the POSIX locale shall be equivalent to specifying:</p> +<pre> +<tt>date "+%a %b %e %H:%M:%S %Z %Y" +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_30_11" id="tag_20_30_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_30_12" id="tag_20_30_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_30_13" id="tag_20_30_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_30_14" id="tag_20_30_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>The date was written successfully.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_30_15" id="tag_20_30_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_30_16" id="tag_20_30_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Conversion specifiers are of unspecified format when not in the POSIX locale. Some of them can contain <newline> +characters in some locales, so it may be difficult to use the format shown in standard output for parsing the output of <i>date</i> +in those locales.</p> +<p>Since the default <i>date</i> utility format for locales other than the POSIX or C locale is not required to include anything +beyond the date and time, whereas for the POSIX or C locale it also includes the day name and time zone, it may be necessary to +specify a format (or override the locale-selection environment variables) to ensure this information is included when desired.</p> +<p>The range of values for <tt>%S</tt> extends from 0 to 60 seconds to accommodate the occasional leap second.</p> +<p>Although certain of the conversion specifiers in the POSIX locale (such as the name of the month) are shown with initial capital +letters, this need not be the case in other locales. Programs using these fields may need to adjust the capitalization if the +output is going to be used at the beginning of a sentence.</p> +<p>The date string formatting capabilities are intended for use in Gregorian-style calendars, possibly with a different starting +year (or years). The <tt>%x</tt> and <tt>%c</tt> conversion specifications, however, are intended for local representation; these +may be based on a different, non-Gregorian calendar.</p> +<p>The <tt>%C</tt> conversion specification was introduced to allow a fallback for the <tt>%EC</tt> (alternative year format base +year); it can be viewed as the base of the current subdivision in the Gregorian calendar. The century number is calculated as the +year divided by 100 and truncated to an integer; it should not be confused with the use of ordinal numbers for centuries (for +example, "twenty-first century".) Both the <tt>%Ey</tt> and <tt>%y</tt> can then be viewed as the offset from <tt>%EC</tt> and +<tt>%C</tt>, respectively.</p> +<p>The <tt>E</tt> and <tt>O</tt> modifiers modify the traditional conversion specifiers, so that they can always be used, even if +the implementation (or the current locale) does not support the modifier.</p> +<p>The <tt>E</tt> modifier supports alternative date formats, such as the Japanese Emperor's Era, as long as these are based on the +Gregorian calendar system. Extending the <tt>E</tt> modifiers to other date elements may provide an implementation-defined +extension capable of supporting other calendar systems, especially in combination with the <tt>O</tt> modifier.</p> +<p>The <tt>O</tt> modifier supports time and date formats using the locale's alternative numerical symbols, such as Kanji or Hindi +digits or ordinal number representation.</p> +<p>Non-European locales, whether they use Latin digits in computational items or not, often have local forms of the digits for use +in date formats. This is not totally unknown even in Europe; a variant of dates uses Roman numerals for the months: the third day +of September 1991 would be written as 3.IX.1991. In Japan, Kanji digits are regularly used for dates; in Arabic-speaking countries, +Hindi digits are used. The <tt>%d</tt>, <tt>%e</tt>, <tt>%H</tt>, <tt>%I</tt>, <tt>%m</tt>, <tt>%S</tt>, <tt>%U</tt>, <tt>%w</tt>, +<tt>%W</tt>, and <tt>%y</tt> conversion specifications always return the date and time field in Latin digits (that is, 0 to 9). The +<tt>%O</tt> modifier was introduced to support the use for display purposes of non-Latin digits. In the <i>LC_TIME</i> category in +<a href="../utilities/localedef.html"><i>localedef</i></a>, the optional <b>alt_digits</b> keyword is intended for this purpose. As +an example, assume the following (partial) <a href="../utilities/localedef.html"><i>localedef</i></a> source:</p> +<pre> +<tt>alt_digits "";"I";"II";"III";"IV";"V";"VI";"VII";"VIII" \ + "IX";"X";"XI";"XII" +d_fmt "%e.%Om.%Y" +</tt></pre> +<p>With the above date, the command:</p> +<pre> +<tt>date "+%x" +</tt></pre> +<p>would yield 3.IX.1991. With the same <b>d_fmt</b>, but without the <b>alt_digits</b>, the command would yield 3.9.1991.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_30_17" id="tag_20_30_17"></a>EXAMPLES</h4> +<blockquote> +<ol> +<li> +<p>The following are input/output examples of <i>date</i> used at arbitrary times in the POSIX locale:</p> +<pre> +<b>$ </b><tt>date +</tt><b>Tue Jun 26 09:58:10 PDT 1990 +<br> +$ </b><tt>date "+DATE: %m/%d/%y%nTIME: %H:%M:%S" +</tt><b>DATE: 11/02/91 +TIME: 13:36:16 +<br> +$ </b><tt>date "+TIME: %r" +</tt><b>TIME: 01:36:32 PM</b><tt> +</tt></pre></li> +<li> +<p>Examples for Denmark, where the default date and time format is <tt>%a</tt> <tt>%d</tt> <tt>%b</tt> <tt>%Y</tt> <tt>%T</tt> +<tt>%Z</tt>:</p> +<pre> +<b>$ </b><tt>LANG=da_DK.iso_8859-1 date +</tt><b>ons 02 okt 1991 15:03:32 CET +<br> +$ </b><tt>LANG=da_DK.iso_8859-1 \ + date "+DATO: %A den %e. %B %Y%nKLOKKEN: %H:%M:%S" +</tt><b>DATO: onsdag den 2. oktober 1991 +KLOKKEN: 15:03:56</b><tt> +</tt></pre></li> +<li> +<p>Examples for Germany, where the default date and time format is <tt>%a</tt> <tt>%d</tt>.<tt>%h</tt>.<tt>%Y</tt>, <tt>%T</tt> +<tt>%Z</tt>:</p> +<pre> +<b>$ </b><tt>LANG=De_DE.88591 date +</tt><b>Mi 02.Okt.1991, 15:01:21 MEZ +<br> +$ </b><tt>LANG=De_DE.88591 date "+DATUM: %A, %d. %B %Y%nZEIT: %H:%M:%S" +</tt><b>DATUM: Mittwoch, 02. Oktober 1991 +ZEIT: 15:02:02</b><tt> +</tt></pre></li> +<li> +<p>Examples for France, where the default date and time format is <tt>%a</tt> <tt>%d</tt> <tt>%h</tt> <tt>%Y</tt> <tt>%Z</tt> +<tt>%T</tt>:</p> +<pre> +<b>$ </b><tt>LANG=Fr_FR.88591 date +</tt><b>Mer 02 oct 1991 MET 15:03:32 +<br> +$ </b><tt>LANG=Fr_FR.88591 date "+JOUR: %A %d %B %Y%nHEURE: %H:%M:%S" +</tt><b>JOUR: Mercredi 02 octobre 1991 +HEURE: 15:03:56</b><tt> +</tt></pre></li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_30_18" id="tag_20_30_18"></a>RATIONALE</h4> +<blockquote> +<p>Some of the new options for formatting are from the ISO C standard. The <b>-u</b> option was introduced to allow portable +access to Coordinated Universal Time (UTC). The string <tt>"GMT0"</tt> is allowed as an equivalent <i>TZ</i> value to be compatible +with all of the systems using the BSD implementation, where this option originated.</p> +<p>The <tt>%e</tt> format conversion specification (adopted from System V) was added because the ISO C standard conversion +specifications did not provide any way to produce the historical default <i>date</i> output during the first nine days of any +month.</p> +<p>There are two varieties of day and week numbering supported (in addition to any others created with the locale-dependent +<tt>%E</tt> and <tt>%O</tt> modifier characters):</p> +<ul> +<li> +<p>The historical variety in which Sunday is the first day of the week and the weekdays preceding the first Sunday of the year are +considered week 0. These are represented by <tt>%w</tt> and <tt>%U</tt>. A variant of this is <tt>%W</tt>, using Monday as the +first day of the week, but still referring to week 0. This view of the calendar was retained because so many historical +applications depend on it and the ISO C standard <a href="../functions/strftime.html"><i>strftime</i>()</a> function, on which +many <i>date</i> implementations are based, was defined in this way.</p> +</li> +<li> +<p>The international standard, based on the ISO 8601:2019 standard where Monday is the first weekday and the algorithm for the +first week number is more complex: If the week (Monday to Sunday) containing January 1 has four or more days in the new year, then +it is week 1; otherwise, it is week 53 of the previous year, and the next week is week 1. These are represented by the new +conversion specifications <tt>%u</tt> and <tt>%V</tt>, added as a result of international comments.</p> +</li> +</ul> +<p>Although this standard only requires the default <i>date</i> utility format, for locales other than the POSIX or C locale, to +include the date and time, it is common for implementations to include day name and time zone information as well. (For the POSIX +locale this is required, with the day name in <tt>%a</tt> format at the beginning and the time zone in <tt>%Z</tt> format before +the year.) Implementations are encouraged to include the day name (in <tt>%a</tt> or <tt>%A</tt> format) and the time zone (in +<tt>%Z</tt> or <tt>%z</tt> format) in the default <i>date</i> utility format for all of the locales they provide.</p> +<p>Some implementations have a <b>date_fmt</b> locale keyword (see <a href="../basedefs/V1_chap07.html#tag_07_03_05"><i>7.3.5 +LC_TIME</i></a> ) as an extension, to specify the default <i>date</i> utility format for each locale. On such implementations, if +the <a href="../utilities/localedef.html"><i>localedef</i></a> utility is used to create a locale that does not have this +information, the <i>date</i> utility must by default still produce output for that locale that includes both the time and the +date.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_30_19" id="tag_20_30_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_30_20" id="tag_20_30_20"></a>SEE ALSO</h4> +<blockquote> +<p>XBD <a href="../basedefs/V1_chap07.html#tag_07_03_05"><i>7.3.5 LC_TIME</i></a> , <a href= +"../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 +Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/fprintf.html#"><i>fprintf</i></a> , <a href="../functions/strftime.html#"><i>strftime</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_30_21" id="tag_20_30_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_30_22" id="tag_20_30_22"></a>Issue 5</h4> +<blockquote> +<p>Changes are made for Year 2000 alignment.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_30_23" id="tag_20_30_23"></a>Issue 6</h4> +<blockquote> +<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p> +<ul> +<li> +<p>The <tt>%EX</tt> modified conversion specification is added.</p> +</li> +</ul> +<p>The Open Group Corrigendum U048/2 is applied, correcting the examples.</p> +<p>The DESCRIPTION is updated to refer to conversion specifications, instead of field descriptors for consistency with the +<i>LC_TIME</i> category.</p> +<p>A clarification is made such that the current year is the default if the <i>yy</i> argument is omitted when setting the system +date and time.</p> +<p>IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/19 is applied, correcting the CHANGE HISTORY section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_30_24" id="tag_20_30_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 466 is applied, replacing the list of conversion specifications for the +<i>format</i> operand with a +requirement that the output is formatted as if by a call to <a href="../functions/strftime.html"><i>strftime</i>()</a> with +specific arguments.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1345 is applied, adding paragraphs to APPLICATION USAGE and RATIONALE about the default <i>date</i> utility +format.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/cxref.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/dd.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/dd.html b/bdd/dd.html @@ -0,0 +1,480 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>dd</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/date.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/delta.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="dd" id="dd"></a> <a name="tag_20_31" id="tag_20_31"></a><!-- dd --> +<h4 class="mansect"><a name="tag_20_31_01" id="tag_20_31_01"></a>NAME</h4> +<blockquote>dd — convert and copy a file</blockquote> +<h4 class="mansect"><a name="tag_20_31_02" id="tag_20_31_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>dd</tt> <b>[</b><i>operand</i><tt>...</tt><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_31_03" id="tag_20_31_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>dd</i> utility shall copy the specified input file to the specified output file with possible conversions using specific +input and output block sizes. It shall read the input one block at a time, using the specified input block size; it shall then +process the block of data actually returned, which could be smaller than the requested block size. It shall apply any conversions +that have been specified and write the resulting data to the output in blocks of the specified output block size. If the +<b>bs</b>=<i>expr</i> operand is specified and no conversions other than <b>sync</b>, <b>noerror</b>, or <b>notrunc</b> are +requested, the data returned from each input block shall be written as a separate output block; if the read returns less than a +full block and the <b>sync</b> conversion is not specified, the resulting output block shall be the same size as the input block. +If the <b>bs</b>=<i>expr</i> operand is not specified, or a conversion other than <b>sync</b>, <b>noerror</b>, or <b>notrunc</b> is +requested, the input shall be processed and collected into full-sized output blocks until the end of the input is reached.</p> +<p>The processing order shall be as follows:</p> +<ol> +<li> +<p>An input block is read. If the <b>iflags</b>=fullblock operand is specified, this might entail multiple reads; otherwise, the +input block shall be used even if the read was shorter than the specified block size.</p> +</li> +<li> +<p>If the input block is shorter than the specified input block size and the <b>sync</b> conversion is specified, null bytes shall +be appended to the input data up to the specified size. (If either <b>block</b> or <b>unblock</b> is also specified, <space> +characters shall be appended instead of null bytes.) The remaining conversions and output shall include the pad characters as if +they had been read from the input.</p> +</li> +<li> +<p>If the <b>bs</b>=<i>expr</i> operand is specified and no conversion other than <b>sync</b> or <b>noerror</b> is requested, the +resulting data shall be written to the output as a single block, and the remaining steps are omitted.</p> +</li> +<li> +<p>If the <b>swab</b> conversion is specified, each pair of input data bytes shall be swapped. If there is an odd number of bytes +in the input block, the last byte in the input record shall not be swapped.</p> +</li> +<li> +<p>Any remaining conversions (<b>block</b>, <b>unblock</b>, <b>lcase</b>, and <b>ucase</b>) shall be performed. These conversions +shall operate on the input data independently of the input blocking; an input or output fixed-length record may span block +boundaries.</p> +</li> +<li> +<p>The data resulting from input or conversion or both shall be aggregated into output blocks of the specified size. After the end +of input is reached, any remaining output shall be written as a block without padding if <b>conv</b>=<b>sync</b> is not specified; +thus, the final output block may be shorter than the output block size.</p> +</li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_31_04" id="tag_20_31_04"></a>OPTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_31_05" id="tag_20_31_05"></a>OPERANDS</h4> +<blockquote> +<p>All of the operands shall be processed before any input is read. The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>if</b>=<i>file</i></dt> +<dd>Specify the input pathname; the default is standard input.</dd> +<dt><b>of</b>=<i>file</i></dt> +<dd>Specify the output pathname; the default is standard output. If the <b>seek</b>=<i>expr</i> conversion is not also specified, +the output file shall be truncated before the copy begins if an explicit <b>of</b>=<i>file</i> operand is specified, unless +<b>conv</b>=<b>notrunc</b> is specified. If <b>seek</b>=<i>expr</i> is specified, but <b>conv</b>=<b>notrunc</b> is not, the effect +of the copy shall be to preserve the blocks in the output file over which <i>dd</i> seeks, but no other portion of the output file +shall be preserved. (If the size of the seek plus the size of the input file is less than the previous size of the output file, the +output file shall be shortened by the copy. If the input file is empty and either the size of the seek is greater than the previous +size of the output file or the output file did not previously exist, the size of the output file shall be set to the file offset +after the seek.)</dd> +<dt><b>ibs</b>=<i>expr</i></dt> +<dd>Specify the input block size, in bytes, by <i>expr</i> (default is 512).</dd> +<dt><b>obs</b>=<i>expr</i></dt> +<dd>Specify the output block size, in bytes, by <i>expr</i> (default is 512).</dd> +<dt><b>bs</b>=<i>expr</i></dt> +<dd>Set both input and output block sizes to <i>expr</i> bytes, superseding <b>ibs</b>= and <b>obs</b>=. If no conversion other +than <b>sync</b>, <b>noerror</b>, and <b>notrunc</b> is specified, each input block shall be copied to the output as a single block +without aggregating short blocks.</dd> +<dt><b>cbs</b>=<i>expr</i></dt> +<dd>Specify the conversion block size for <b>block</b> and <b>unblock</b> in bytes by <i>expr</i> (default is zero). If <b>cbs</b>= +is omitted or given a value of zero, using <b>block</b> or <b>unblock</b> produces unspecified results. +<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +The application shall ensure that this operand is also specified if the <b>conv</b>= operand is specified with a value of +<b>ascii</b>, <b>ebcdic</b>, or <b>ibm</b>. For a <b>conv</b>= operand with an <b>ascii</b> value, the input is handled as +described for the <b>unblock</b> value, except that characters are converted to ASCII before any trailing <space> characters +are deleted. For <b>conv</b>= operands with <b>ebcdic</b> or <b>ibm</b> values, the input is handled as described for the +<b>block</b> value except that the characters are converted to EBCDIC or IBM EBCDIC, respectively, after any trailing <space> +characters are added. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p> +</dd> +<dt><b>skip</b>=<i>n</i></dt> +<dd>Skip <i>n</i> input blocks (using the specified input block size) before starting to copy. On seekable files, the +implementation shall read the blocks or seek past them; on non-seekable files, the blocks shall be read and the data shall be +discarded.</dd> +<dt><b>seek</b>=<i>n</i></dt> +<dd>Skip <i>n</i> blocks (using the specified output block size) from the beginning of the output file before copying. On +non-seekable files, existing blocks shall be read and space from the current end-of-file to the specified offset, if any, filled +with null bytes; on seekable files, the implementation shall seek to the specified offset or read the blocks as described for +non-seekable files.</dd> +<dt><b>count</b>=<i>n</i></dt> +<dd>Copy only <i>n</i> input blocks. If <i>n</i> is zero, it is unspecified whether no blocks or all blocks are copied.</dd> +<dt><b>conv</b>=<i>value</i><b>[</b>,<i>value</i> ...<b>]</b></dt> +<dd><br> +Where <i>value</i>s are <comma>-separated symbols from the following list: +<dl compact> +<dd></dd> +<dt><b>ascii</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Convert EBCDIC to ASCII; see <a href="#tagtcjh_18">ASCII to EBCDIC Conversion</a> . <img src="../images/opt-end.gif" alt= +"[Option End]" border="0"></dd> +<dt><b>ebcdic</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Convert ASCII to EBCDIC; see <a href="#tagtcjh_18">ASCII to EBCDIC Conversion</a> . <img src="../images/opt-end.gif" alt= +"[Option End]" border="0"></dd> +<dt><b>ibm</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Convert ASCII to a different EBCDIC set; see <a href="#tagtcjh_19">ASCII to IBM EBCDIC Conversion</a> . <img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></dd> +</dl> +<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +The <b>ascii</b>, <b>ebcdic</b>, and <b>ibm</b> values are mutually-exclusive. <img src="../images/opt-end.gif" alt="[Option End]" +border="0"></p> +<dl compact> +<dd></dd> +<dt><b>block</b></dt> +<dd>Treat the input as a sequence of <newline>-terminated or end-of-file-terminated variable-length records independent of +the input block boundaries. Each record shall be converted to a record with a fixed length specified by the conversion block size. +Any <newline> shall be removed from the input line; <space> characters shall be appended to lines that are shorter than +their conversion block size to fill the block. Lines that are longer than the conversion block size shall be truncated to the +largest number of characters that fit into that size; the number of truncated lines shall be reported (see the STDERR section). +<p>The <b>block</b> and <b>unblock</b> values are mutually-exclusive.</p> +</dd> +<dt><b>unblock</b></dt> +<dd>Convert fixed-length records to variable length. Read a number of bytes equal to the conversion block size (or the number of +bytes remaining in the input, if less than the conversion block size), delete all trailing <space> characters, and append a +<newline>.</dd> +<dt><b>lcase</b></dt> +<dd>Map uppercase characters specified by the <i>LC_CTYPE</i> keyword <b>tolower</b> to the corresponding lowercase character. +Characters for which no mapping is specified shall not be modified by this conversion. +<p>The <b>lcase</b> and <b>ucase</b> symbols are mutually-exclusive.</p> +</dd> +<dt><b>ucase</b></dt> +<dd>Map lowercase characters specified by the <i>LC_CTYPE</i> keyword <b>toupper</b> to the corresponding uppercase character. +Characters for which no mapping is specified shall not be modified by this conversion.</dd> +<dt><b>swab</b></dt> +<dd>Swap every pair of input bytes.</dd> +<dt><b>noerror</b></dt> +<dd>Do not stop processing on an input error. When an input error occurs, a diagnostic message shall be written on standard error, +followed by the current input and output block counts in the same format as used at completion (see the STDERR section). If the +<b>sync</b> conversion is specified, the missing input shall be replaced with null bytes and processed normally; otherwise, the +input block shall be omitted from the output.</dd> +<dt><b>notrunc</b></dt> +<dd>Do not truncate the output file. Preserve blocks in the output file not explicitly written by this invocation of the <i>dd</i> +utility. (See also the preceding <b>of</b>=<i>file</i> operand.)</dd> +<dt><b>sync</b></dt> +<dd>Pad every input block to the size of the <b>ibs</b>= buffer, appending null bytes. (If either <b>block</b> or <b>unblock</b> is +also specified, append <space> characters, rather than null bytes.)</dd> +</dl> +</dd> +<dt><b>iflags</b>=fullblock</dt> +<dd><br> +Perform as many reads as required to reach the full input block size or end of file, rather than acting on partial reads. If this +operand is in effect, then the <b>count</b>= operand refers to the number of full input blocks rather than reads. The behavior is +unspecified if <b>iflags</b>=fullblock is requested alongside the <b>sync</b>, <b>block</b>, or <b>unblock</b> conversions.</dd> +</dl> +<p>The behavior is unspecified if operands other than <b>conv</b>= are specified more than once.</p> +<p>For the <b>bs</b>=, <b>cbs</b>=, <b>ibs</b>=, and <b>obs</b>= operands, the application shall supply an expression specifying a +size in bytes. The expression, <i>expr</i>, can be:</p> +<ol> +<li> +<p>A positive decimal number</p> +</li> +<li> +<p>A positive decimal number followed by <i>k</i>, specifying multiplication by 1024</p> +</li> +<li> +<p>A positive decimal number followed by <i>b</i>, specifying multiplication by 512</p> +</li> +<li> +<p>Two or more positive decimal numbers (with or without <i>k</i> or <i>b</i>) separated by <i>x</i>, specifying the product of the +indicated values</p> +</li> +</ol> +<p>All of the operands are processed before any input is read.</p> +<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +The following two tables display the octal number character values used for the <b>ascii</b> and <b>ebcdic</b> conversions (first +table) and for the <b>ibm</b> conversion (second table). In both tables, the ASCII values are the row and column headers and the +EBCDIC values are found at their intersections. For example, ASCII 0012 (LF) is the second row, third column, yielding 0045 in +EBCDIC. The inverted tables (for EBCDIC to ASCII conversion) are not shown, but are in one-to-one correspondence with these tables. +The differences between the two tables are highlighted by small boxes drawn around five entries. <img src="../images/opt-end.gif" +alt="[Option End]" border="0"><br></p> +<p class="caption"><a name="tagtcjh_18" id="tagtcjh_18"></a> Table: ASCII to EBCDIC Conversion</p> +<img src=".././Figures/ascebc.gif"> +<p class="caption"><a name="tagtcjh_19" id="tagtcjh_19"></a> Table: ASCII to IBM EBCDIC Conversion</p> +<img src=".././Figures/ascibm.gif"></blockquote> +<h4 class="mansect"><a name="tag_20_31_06" id="tag_20_31_06"></a>STDIN</h4> +<blockquote> +<p>If no <b>if</b>= operand is specified, the standard input shall be used. See the INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_31_07" id="tag_20_31_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input file can be any file type.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_31_08" id="tag_20_31_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>dd</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files), the classification of characters as uppercase or lowercase, and the +mapping of characters from one case to the other.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error and +informative messages written to standard output.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_31_09" id="tag_20_31_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>For SIGINT, the <i>dd</i> utility shall interrupt its current processing, write status information to standard error, and +terminate abnormally as if by the default action for SIGINT. One or more implementation defined non-job-control signals other than +SIGABRT, SIGHUP, and SIGTERM may write status information to standard error and continue processing. All other signals (including +job control signals, SIGABRT, SIGHUP, and SIGTERM) shall take their default action; see the ASYNCHRONOUS EVENTS section in <a href= +"../utilities/V3_chap01.html#tag_18_04"><i>1.4 Utility Description Defaults</i></a> .</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_31_10" id="tag_20_31_10"></a>STDOUT</h4> +<blockquote> +<p>If no <b>of</b>= operand is specified, the standard output shall be used. The nature of the output depends on the operands +selected.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_31_11" id="tag_20_31_11"></a>STDERR</h4> +<blockquote> +<p>On completion, <i>dd</i> shall write the number of input and output blocks to standard error. In the POSIX locale the following +formats shall be used:</p> +<pre> +<tt>"%u+%u records in\n", <</tt><i>number of whole input blocks</i><tt>>, + <</tt><i>number of partial input blocks</i><tt>> +<br> +"%u+%u records out\n", <</tt><i>number of whole output blocks</i><tt>>, + <</tt><i>number of partial output blocks</i><tt>> +</tt></pre> +<p>A partial input block is one for which <a href="../functions/read.html"><i>read</i>()</a> returned less than the input block +size. A partial output block is one that was written with fewer bytes than specified by the output block size.</p> +<p>In addition, when there is at least one truncated block, the number of truncated blocks shall be written to standard error. In +the POSIX locale, the format shall be:</p> +<pre> +<tt>"%u truncated %s\n", <</tt><i>number of truncated blocks</i><tt>>, "record" (if + <</tt><i>number of truncated blocks</i><tt>> is one) "records" (otherwise) +</tt></pre> +<p>Diagnostic messages may also be written to standard error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_31_12" id="tag_20_31_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>If the <b>of</b>= operand is used, the output shall be the same as described in the STDOUT section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_31_13" id="tag_20_31_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_31_14" id="tag_20_31_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_31_15" id="tag_20_31_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>If an input error is detected and the <b>noerror</b> conversion has not been specified, any partial output block shall be +written to the output file, a diagnostic message shall be written, and the copy operation shall be discontinued. If some other +error is detected, a diagnostic message shall be written and the copy operation shall be discontinued.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_31_16" id="tag_20_31_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The input and output block size can be specified to take advantage of raw physical I/O.</p> +<p>There are many different versions of the EBCDIC codesets. The ASCII and EBCDIC conversions specified for the <i>dd</i> utility +perform conversions for the version specified by the tables.</p> +<p>Using the <b>count</b>= operand of <i>dd</i> with a pipe or FIFO as the input can lead to surprising results, since these file +types are prone to encountering short reads for any input block size other than 1. Unless the <b>iflags</b>=fullblock operand is in +effect, <i>dd</i> will stop after the specified number of reads, rather than full input blocks, and therefore can often result in +fewer bytes being output than the product of the count and input block size.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_31_17" id="tag_20_31_17"></a>EXAMPLES</h4> +<blockquote> +<p>The following command:</p> +<pre> +<tt>dd if=/dev/rmt0h of=/dev/rmt1h +</tt></pre> +<p>copies from tape drive 0 to tape drive 1, using a common historical device naming convention.</p> +<p>The following command:</p> +<pre> +<tt>dd ibs=10 skip=1 +</tt></pre> +<p>strips the first 10 bytes from standard input.</p> +<p>This example reads an EBCDIC tape blocked ten 80-byte EBCDIC card images per block into the ASCII file <b>x</b>:</p> +<pre> +<tt>dd if=/dev/tape of=x ibs=800 cbs=80 conv=ascii,lcase +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_31_18" id="tag_20_31_18"></a>RATIONALE</h4> +<blockquote> +<p>The OPTIONS section is listed as "None" because there are no options recognized by historical <i>dd</i> utilities. Certainly, +many of the operands could have been designed to use the Utility Syntax Guidelines, which would have resulted in the classic +hyphenated option letters. In this version of this volume of POSIX.1-2024, <i>dd</i> retains its curious JCL-like syntax due to the +large number of applications that depend on the historical implementation.</p> +<p>A suggested implementation technique for <b>conv</b>=<b>noerror</b>,<b>sync</b> is to zero (or <space>-fill, if +<b>block</b>ing or <b>unblock</b>ing) the input buffer before each read and to write the contents of the input buffer to the output +even after an error. In this manner, any data transferred to the input buffer before the error was detected is preserved. Another +point is that a failed read on a regular file or a disk generally does not increment the file offset, and <i>dd</i> must then seek +past the block on which the error occurred; otherwise, the input error occurs repetitively. When the input is a magnetic tape, +however, the tape normally has passed the block containing the error when the error is reported, and thus no seek is necessary.</p> +<p>The default <b>ibs</b>= and <b>obs</b>= sizes are specified as 512 bytes because there are historical (largely portable) scripts +that assume these values. If they were left unspecified, unusual results could occur if an implementation chose an odd block +size.</p> +<p>Historical implementations of <i>dd</i> used <a href="../functions/creat.html"><i>creat</i>()</a> when processing +<b>of</b>=<i>file</i>. This makes the <b>seek</b>= operand unusable except on special files. The <b>conv</b>=<b>notrunc</b> feature +was added because more recent BSD-based implementations use <a href="../functions/open.html"><i>open</i>()</a> (without O_TRUNC) +instead of <a href="../functions/creat.html"><i>creat</i>()</a>, but they fail to delete output file contents after the data +copied.</p> +<p>The <i>w</i> multiplier (historically meaning <i>word</i>), is used in System V to mean 2 and in 4.2 BSD to mean 4. Since +<i>word</i> is inherently non-portable, its use is not supported by this volume of POSIX.1-2024.</p> +<p>Standard EBCDIC does not have the characters <tt>'['</tt> and <tt>']'</tt>. The values used in the table are taken from a common +print train that does contain them. Other than those characters, the print train values are not filled in, but appear to provide +some of the motivation for the historical choice of translations reflected here.</p> +<p>The Standard EBCDIC table provides a 1:1 translation for all 256 bytes.</p> +<p>The IBM EBCDIC table does not provide such a translation. The marked cells in the tables differ in such a way that:</p> +<ol> +<li> +<p>EBCDIC 0112 (<tt>'¢'</tt>) and 0152 (broken pipe) do not appear in the table.</p> +</li> +<li> +<p>EBCDIC 0137 (<tt>'¬'</tt>) translates to/from ASCII 0236 (<tt>'^'</tt>). In the standard table, EBCDIC 0232 (no graphic) is +used.</p> +</li> +<li> +<p>EBCDIC 0241 (<tt>'~'</tt>) translates to/from ASCII 0176 (<tt>'~'</tt>). In the standard table, EBCDIC 0137 (<tt>'¬'</tt>) is +used.</p> +</li> +<li> +<p>0255 (<tt>'['</tt>) and 0275 (<tt>']'</tt>) appear twice, once in the same place as for the standard table and once in place of +0112 (<tt>'¢'</tt>) and 0241 (<tt>'~'</tt>).</p> +</li> +</ol> +<p>In net result:</p> +<blockquote>EBCDIC 0275 (<tt>']'</tt>) displaced EBCDIC 0241 (<tt>'~'</tt>) in cell 0345. +<p> That displaced EBCDIC 0137 (<tt>'¬'</tt>) in cell 0176.</p> +<p> That displaced EBCDIC 0232 (no graphic) in cell 0136.</p> +<p> That replaced EBCDIC 0152 (broken pipe) in cell 0313.</p> +<p>EBCDIC 0255 (<tt>'['</tt>) replaced EBCDIC 0112 (<tt>'¢'</tt>).</p> +</blockquote> +<p>This translation, however, reflects historical practice that (ASCII) <tt>'~'</tt> and <tt>'¬'</tt> were often mapped to each +other, as were <tt>'['</tt> and <tt>'¢'</tt>; and <tt>']'</tt> and (EBCDIC) <tt>'~'</tt>.</p> +<p>The <b>cbs</b> operand is required if any of the <b>ascii</b>, <b>ebcdic</b>, or <b>ibm</b> operands are specified. For the +<b>ascii</b> operand, the input is handled as described for the <b>unblock</b> operand except that characters are converted to +ASCII before the trailing <space> characters are deleted. For the <b>ebcdic</b> and <b>ibm</b> operands, the input is handled +as described for the <b>block</b> operand except that the characters are converted to EBCDIC or IBM EBCDIC after the trailing +<space> characters are added.</p> +<p>The <b>block</b> and <b>unblock</b> keywords are from historical BSD practice.</p> +<p>The consistent use of the word <b>record</b> in standard error messages matches most historical practice. An earlier version of +System V used <b>block</b>, but this has been updated in more recent releases.</p> +<p>Early proposals only allowed two numbers separated by <b>x</b> to be used in a product when specifying <b>bs</b>=, <b>cbs</b>=, +<b>ibs</b>=, and <b>obs</b>= sizes. This was changed to reflect the historical practice of allowing multiple numbers in the product +as provided by Version 7 and all releases of System V and BSD.</p> +<p>A change to the <b>swab</b> conversion is required to match historical practice and is the result of IEEE PASC Interpretations +1003.2 #03 and #04, submitted for the ISO POSIX-2:1993 standard.</p> +<p>A change to the handling of SIGINT is required to match historical practice and is the result of IEEE PASC Interpretation 1003.2 +#06 submitted for the ISO POSIX-2:1993 standard.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_31_19" id="tag_20_31_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a +<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require +implementations to treat this as an error.</p> +<p>A future version of this standard may introduce the SIGINFO signal; on platforms where such a signal is available, it is +recommended that this signal be used for reporting status without terminating the process.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_31_20" id="tag_20_31_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap01.html#tag_18_04"><i>1.4 Utility Description Defaults</i></a> , <a href= +"../utilities/sed.html#"><i>sed</i></a> , <a href="../utilities/tr.html#"><i>tr</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_31_21" id="tag_20_31_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_31_22" id="tag_20_31_22"></a>Issue 5</h4> +<blockquote> +<p>The second paragraph of the <b>cbs</b>= description is reworded and marked EX.</p> +<p>The FUTURE DIRECTIONS section is added.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_31_23" id="tag_20_31_23"></a>Issue 6</h4> +<blockquote> +<p>Changes are made to <b>swab</b> conversion and SIGINT handling to align with the IEEE P1003.2b draft standard.</p> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +<p>IEEE PASC Interpretation 1003.2 #209 is applied, clarifying the interaction between <i>dd</i> <b>of</b>=<i>file</i> and +<b>conv</b>=<b>notrunc</b>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_31_24" id="tag_20_31_24"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #102 is applied.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0081 [907] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_31_25" id="tag_20_31_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to disallow the creation of filenames containing any bytes that +have the encoded value of a <newline> character.</p> +<p>Austin Group Defect 406 is applied, adding the <b>iflags</b>=fullblock operand.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1159 is applied, changing the ASYNCHRONOUS EVENTS and FUTURE DIRECTIONS sections.</p> +<p>Austin Group Defect 1497 is applied, changing the EXIT STATUS section.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/date.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/delta.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/delta.html b/bdd/delta.html @@ -0,0 +1,317 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>delta</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/dd.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/df.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="delta" id="delta"></a> <a name="tag_20_32" id="tag_20_32"></a><!-- delta --> +<h4 class="mansect"><a name="tag_20_32_01" id="tag_20_32_01"></a>NAME</h4> +<blockquote>delta — make a delta (change) to an SCCS file (<b>DEVELOPMENT</b>)</blockquote> +<h4 class="mansect"><a name="tag_20_32_02" id="tag_20_32_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> delta</tt> <b>[</b><tt>-nps</tt><b>] [</b><tt>-g</tt> <i>list</i><b>] [</b><tt>-m</tt> +<i>mrlist</i><b>] [</b><tt>-r</tt> <i>SID</i><b>] [</b><tt>-y</tt><b>[</b><i>comment</i><b>]]</b> <i>file</i><tt>... <img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div> +</blockquote> +<h4 class="mansect"><a name="tag_20_32_03" id="tag_20_32_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>delta</i> utility shall be used to permanently introduce into the named SCCS files changes that were made to the files +retrieved by <a href="../utilities/get.html"><i>get</i></a> (called the <i>g-files</i>, or generated files).</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_32_04" id="tag_20_32_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>delta</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> , except that the <b>-y</b> option has an optional option-argument. This optional option-argument shall not be +presented as a separate argument.</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-r </b><i>SID</i></dt> +<dd>Uniquely identify which delta is to be made to the SCCS file. The use of this option shall be necessary only if two or more +outstanding <a href="../utilities/get.html"><i>get</i></a> commands for editing (<a href="../utilities/get.html"><i>get</i></a> +<b>-e</b>) on the same SCCS file were done by the same person (login name). The SID value specified with the <b>-r</b> option can +be either the SID specified on the <a href="../utilities/get.html"><i>get</i></a> command line or the SID to be made as reported by +the <a href="../utilities/get.html"><i>get</i></a> utility; see <a href="../utilities/get.html#"><i>get</i></a> .</dd> +<dt><b>-s</b></dt> +<dd>Suppress the report to standard output of the activity associated with each <i>file</i>. See the STDOUT section.</dd> +<dt><b>-n</b></dt> +<dd>Specify retention of the edited <i>g-file</i> (normally removed at completion of delta processing).</dd> +<dt><b>-g </b><i>list</i></dt> +<dd>Specify a <i>list</i> (see <a href="../utilities/get.html#"><i>get</i></a> for the definition of <i>list</i>) of deltas that +shall be ignored when the file is accessed at the change level (SID) created by this delta.</dd> +<dt><b>-m </b><i>mrlist</i></dt> +<dd>Specify a modification request (MR) number that the application shall supply as the reason for creating the new delta. This +shall be used if the SCCS file has the <b>v</b> flag set; see <a href="../utilities/admin.html#"><i>admin</i></a> . +<p>If <b>-m</b> is not used and <tt>'-'</tt> is not specified as a file argument, and the standard input is a terminal, the prompt +described in the STDOUT section shall be written to standard output before the standard input is read; if the standard input is not +a terminal, no prompt shall be issued.</p> +<p>MRs in a list shall be separated by <blank> characters or escaped <newline> characters. An unescaped <newline> +shall terminate the MR list. The escape character is <backslash>.</p> +<p>If the <b>v</b> flag has a value, it shall be taken to be the name of a program which validates the correctness of the MR +numbers. If a non-zero exit status is returned from the MR number validation program, the <i>delta</i> utility shall terminate. (It +is assumed that the MR numbers were not all valid.)</p> +</dd> +<dt><b>-y[</b><i>comment</i><b>]</b></dt> +<dd>Describe the reason for making the delta. The <i>comment</i> shall be an arbitrary group of lines that would meet the +definition of a text file. Implementations shall support <i>comment</i>s from zero to 512 bytes and may support longer values. A +null string (specified as either <b>-y</b>, <b>-y</b><tt>""</tt>, or in response to a prompt for a comment) shall be considered a +valid <i>comment</i>. +<p>If <b>-y</b> is not specified and <tt>'-'</tt> is not specified as a file argument, and the standard input is a terminal, the +prompt described in the STDOUT section shall be written to standard output before the standard input is read; if the standard input +is not a terminal, no prompt shall be issued. An unescaped <newline> shall terminate the comment text. The escape character +is <backslash>.</p> +<p>The <b>-y</b> option shall be required if the <i>file</i> operand is specified as <tt>'-'</tt>.</p> +</dd> +<dt><b>-p</b></dt> +<dd>Write (to standard output) the SCCS file differences before and after the delta is applied in <a href= +"../utilities/diff.html"><i>diff</i></a> format; see <a href="../utilities/diff.html#"><i>diff</i></a> .</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_32_05" id="tag_20_32_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of an existing SCCS file or a directory. If <i>file</i> is a directory, the <i>delta</i> utility shall behave as +though each file in the directory were specified as a named file, except that non-SCCS files (last component of the pathname does +not begin with <b>s.</b>) and unreadable files shall be silently ignored. +<p>If exactly one <i>file</i> operand appears, and it is <tt>'-'</tt>, the standard input shall be read; each line of the standard +input shall be taken to be the name of an SCCS file to be processed. Non-SCCS files and unreadable files shall be silently +ignored.</p> +</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_32_06" id="tag_20_32_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be a text file used only in the following cases:</p> +<ul> +<li> +<p>To read an <i>mrlist</i> or a <i>comment</i> (see the <b>-m</b> and <b>-y</b> options).</p> +</li> +<li> +<p>A <i>file</i> operand shall be specified as <tt>'-'</tt>. In this case, the <b>-y</b> option needs to be used to specify the +comment, and if the SCCS file has the <b>v</b> flag set, the <b>-m</b> option also needs to be used to specify the MR list.</p> +</li> +</ul> +</blockquote> +<h4 class="mansect"><a name="tag_20_32_07" id="tag_20_32_07"></a>INPUT FILES</h4> +<blockquote> +<p>Input files shall be text files whose data is to be included in the SCCS files. If the first character of any line of an input +file is <SOH> in the POSIX locale, the results are unspecified. If this file contains more than 99999 lines, the number of +lines recorded in the header for this file shall be 99999 for this delta.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_32_08" id="tag_20_32_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>delta</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error, and +informative messages written to standard output.</dd> +<dt><i>NLSPATH</i></dt> +<dd>Determine the location of messages objects and message catalogs.</dd> +<dt><i>TZ</i></dt> +<dd>Determine the timezone in which the time and date are written in the SCCS file. If the <i>TZ</i> variable is unset or NULL, an +unspecified system default timezone is used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_32_09" id="tag_20_32_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>If SIGINT is caught, temporary files shall be cleaned up and <i>delta</i> shall exit with a non-zero exit code. The standard +action shall be taken for all other signals; see <a href="../utilities/V3_chap01.html#tag_18_04"><i>1.4 Utility Description +Defaults</i></a> .</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_32_10" id="tag_20_32_10"></a>STDOUT</h4> +<blockquote> +<p>The standard output shall be used only for the following messages in the POSIX locale:</p> +<ul> +<li> +<p>Prompts (see the <b>-m</b> and <b>-y</b> options) in the following formats:</p> +<pre> +<tt>"MRs? " +<br> +"comments? " +</tt></pre> +<p>The MR prompt, if written, shall always precede the comments prompt.</p> +</li> +<li> +<p>A report of each file's activities (unless the <b>-s</b> option is specified) in the following format:</p> +<pre> +<tt>"%s\n%d inserted\n%d deleted\n%d unchanged\n", <</tt><i>New SID</i><tt>>, + <</tt><i>number of lines inserted</i><tt>>, <</tt><i>number of lines deleted</i><tt>>, + <</tt><i>number of lines unchanged</i><tt>> +</tt></pre></li> +</ul> +</blockquote> +<h4 class="mansect"><a name="tag_20_32_11" id="tag_20_32_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_32_12" id="tag_20_32_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>Any SCCS files updated shall be files of an unspecified format.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_32_13" id="tag_20_32_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<h5><a name="tag_20_32_13_01" id="tag_20_32_13_01"></a>System Date and Time</h5> +<p>When a delta is added to an SCCS file, the system date and time shall be recorded for the new delta. If a <a href= +"../utilities/get.html"><i>get</i></a> is performed using an SCCS file with a date recorded apparently in the future, the behavior +is unspecified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_32_14" id="tag_20_32_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_32_15" id="tag_20_32_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_32_16" id="tag_20_32_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Problems can arise if the system date and time have been modified (for example, put forward and then back again, or +unsynchronized clocks across a network) and can also arise when different values of the <i>TZ</i> environment variable are +used.</p> +<p>Problems of a similar nature can also arise for the operation of the <a href="../utilities/get.html"><i>get</i></a> utility, +which records the date and time in the file body.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_32_17" id="tag_20_32_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_32_18" id="tag_20_32_18"></a>RATIONALE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_32_19" id="tag_20_32_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +<p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a +<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require +implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_32_20" id="tag_20_32_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap01.html#tag_18_04"><i>1.4 Utility Description Defaults</i></a> , <a href= +"../utilities/admin.html#"><i>admin</i></a> , <a href="../utilities/diff.html#"><i>diff</i></a> , <a href= +"../utilities/get.html#"><i>get</i></a> , <a href="../utilities/prs.html#"><i>prs</i></a> , <a href= +"../utilities/rmdel.html#"><i>rmdel</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_32_21" id="tag_20_32_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_32_22" id="tag_20_32_22"></a>Issue 5</h4> +<blockquote> +<p>The output format description in the STDOUT section is corrected.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_32_23" id="tag_20_32_23"></a>Issue 6</h4> +<blockquote> +<p>The APPLICATION USAGE section is added.</p> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +<p>The Open Group Base Resolution bwg2001-007 is applied as follows:</p> +<ul> +<li> +<p>The use of <tt>'-'</tt> as a file argument is clarified.</p> +</li> +<li> +<p>The use of STDIN is added.</p> +</li> +<li> +<p>The ASYNCHRONOUS EVENTS section is updated to remove the implicit requirement that implementations re-signal themselves when +catching a normally fatal signal.</p> +</li> +<li> +<p>New text is added to the INPUT FILES section warning that the maximum lines recorded in the file is 99999.</p> +</li> +</ul> +<p>New text is added to the EXTENDED DESCRIPTION and APPLICATION USAGE sections regarding how the system date and time may be taken +into account, and the <i>TZ</i> environment variable is added to the ENVIRONMENT VARIABLES section as per The Open Group Base +Resolution bwg2001-007.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_32_24" id="tag_20_32_24"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_32_25" id="tag_20_32_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to behave as follows:</p> +<ol type="a"> +<li> +<p>Report an error if a utility is directed to display a pathname that contains any bytes that have the encoded value of a +<newline> character when <newline> is a terminator or separator in the output format being used.</p> +</li> +<li> +<p>Disallow the creation of filenames containing any bytes that have the encoded value of a <newline> character.</p> +</li> +</ol> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/dd.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/df.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/df.html b/bdd/df.html @@ -0,0 +1,300 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>df</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/delta.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/diff.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="df" id="df"></a> <a name="tag_20_33" id="tag_20_33"></a><!-- df --> +<h4 class="mansect"><a name="tag_20_33_01" id="tag_20_33_01"></a>NAME</h4> +<blockquote>df — report free disk space</blockquote> +<h4 class="mansect"><a name="tag_20_33_02" id="tag_20_33_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> df</tt> <b>[</b><tt>-k</tt><b>] [</b><tt>-P|<img src= +"../images/opt-start.gif" border="0">-t</tt><b><img src="../images/opt-end.gif" border="0">] +[</b><i>file</i><tt>...</tt><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_33_03" id="tag_20_33_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>df</i> utility shall write the amount of available space <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> +<img src="../images/opt-start.gif" alt="[Option Start]" border="0"> and file slots <img src="../images/opt-end.gif" alt= +"[Option End]" border="0"> for file systems on which the invoking user has appropriate read access. File systems shall be specified +by the <i>file</i> operands; when none are specified, information shall be written for all file systems. The format of the default +output from <i>df</i> is unspecified, but all space figures are reported in 512-byte units, unless the <b>-k</b> option is +specified. This output shall contain at least the file system names, amount of available space on each of these file systems, +<sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> + and, if no options other than <b>-t</b> are specified, the number of free file slots, or <i>inode</i>s, available; when +<b>-t</b> is specified, the output shall contain the total allocated space as well. <img src="../images/opt-end.gif" alt= +"[Option End]" border="0"></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_33_04" id="tag_20_33_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>df</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-k</b></dt> +<dd>Use 1024-byte units, instead of the default 512-byte units, when writing space figures.</dd> +<dt><b>-P</b></dt> +<dd>Produce output in the format described in the STDOUT section.</dd> +<dt><b>-t</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Include total allocated-space figures in the output. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_33_05" id="tag_20_33_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of a file within the hierarchy of the desired file system. If a file other than a FIFO, a regular file, a directory, +<sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> + or a special file representing the device containing the file system (for example, <b>/dev/dsk/0s1</b>) <img src= +"../images/opt-end.gif" alt="[Option End]" border="0"> is specified, the results are unspecified. If the <i>file</i> operand names +a file other than a special file containing a file system, <i>df</i> shall write the amount of free space in the file system +containing the specified <i>file</i> operand. <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src= +"../images/opt-start.gif" alt="[Option Start]" border="0"> Otherwise, <i>df</i> shall write the amount of free space in that +file system. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_33_06" id="tag_20_33_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_33_07" id="tag_20_33_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_33_08" id="tag_20_33_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>df</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error and +informative messages written to standard output.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_33_09" id="tag_20_33_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_33_10" id="tag_20_33_10"></a>STDOUT</h4> +<blockquote> +<p>When both the <b>-k</b> and <b>-P</b> options are specified, the following header line shall be written (in the POSIX +locale):</p> +<pre> +<tt>"Filesystem 1024-blocks Used Available Capacity Mounted on\n" +</tt></pre> +<p>When the <b>-P</b> option is specified without the <b>-k</b> option, the following header line shall be written (in the POSIX +locale):</p> +<pre> +<tt>"Filesystem 512-blocks Used Available Capacity Mounted on\n" +</tt></pre> +<p>The implementation may adjust the spacing of the header line and the individual data lines so that the information is presented +in orderly columns.</p> +<p>The remaining output with <b>-P</b> shall consist of one line of information for each specified file system. These lines shall +be formatted as follows:</p> +<pre> +<tt>"%s %d %d %d %d%% %s\n", <</tt><i>file system name</i><tt>>, <</tt><i>total space</i><tt>>, + <</tt><i>space used</i><tt>>, <</tt><i>space free</i><tt>>, <</tt><i>percentage used</i><tt>>, + <</tt><i>file system root</i><tt>> +</tt></pre> +<p>In the following list, all quantities expressed in 512-byte units (1024-byte when <b>-k</b> is specified) shall be rounded up to +the next higher unit. The fields are:</p> +<dl compact> +<dd></dd> +<dt><<i>file system name</i>></dt> +<dd><br> +The name of the file system, in an implementation-defined format.</dd> +<dt><<i>total space</i>></dt> +<dd>The total size of the file system in 512-byte units. The exact meaning of this figure is implementation-defined, but should +include <<i>space used</i>>, <<i>space free</i>>, plus any space reserved by the system not normally +available to a user.</dd> +<dt><<i>space used</i>></dt> +<dd>The total amount of space allocated to existing files in the file system, in 512-byte units.</dd> +<dt><<i>space free</i>></dt> +<dd>The total amount of space available within the file system for the creation of new files by unprivileged users, in 512-byte +units. When this figure is less than or equal to zero, it shall not be possible to create any new files on the file system without +first deleting others, unless the process has appropriate privileges. The figure written may be less than zero.</dd> +<dt><<i>percentage used</i>></dt> +<dd><br> +The percentage of the normally available space that is currently allocated to all files on the file system. This shall be +calculated using the fraction: +<pre> +<tt><</tt><i>space used</i><tt>>/( <</tt><i>space used</i><tt>>+ <</tt><i>space free</i><tt>>) +</tt></pre> +<p>expressed as a percentage. This percentage may be greater than 100 if <<i>space free</i>> is less than zero. The +percentage value shall be expressed as a positive integer, with any fractional result causing it to be rounded to the next highest +integer.</p> +</dd> +<dt><<i>file system root</i>></dt> +<dd><br> +The directory below which the file system hierarchy appears.</dd> +</dl> +<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +The output format is unspecified when <b>-t</b> is used. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_33_11" id="tag_20_33_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_33_12" id="tag_20_33_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_33_13" id="tag_20_33_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_33_14" id="tag_20_33_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_33_15" id="tag_20_33_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_33_16" id="tag_20_33_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>On most systems, the "name of the file system, in an implementation-defined format" is the special file on which the file +system is mounted.</p> +<p>On large file systems, the calculation specified for percentage used can create huge rounding errors.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_33_17" id="tag_20_33_17"></a>EXAMPLES</h4> +<blockquote> +<ol> +<li> +<p>The following example writes portable information about the <b>/usr</b> file system:</p> +<pre> +<tt>df -P /usr +</tt></pre></li> +<li> +<p>Assuming that <b>/usr/src</b> is part of the <b>/usr</b> file system, the following produces the same output as the previous +example:</p> +<pre> +<tt>df -P /usr/src +</tt></pre></li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_33_18" id="tag_20_33_18"></a>RATIONALE</h4> +<blockquote> +<p>The behavior of <i>df</i> with the <b>-P</b> option is the default action of the 4.2 BSD <i>df</i> utility. The uppercase +<b>-P</b> was selected to avoid collision with a known industry extension using <b>-p</b>.</p> +<p>Historical <i>df</i> implementations vary considerably in their default output. It was therefore necessary to describe the +default output in a loose manner to accommodate all known historical implementations and to add a portable option (<b>-P</b>) to +provide information in a portable format.</p> +<p>The use of 512-byte units is historical practice and maintains compatibility with <a href="../utilities/ls.html"><i>ls</i></a> +and other utilities in this volume of POSIX.1-2024. This does not mandate that the file system itself be based on 512-byte blocks. +The <b>-k</b> option was added as a compromise measure. It was agreed by the standard developers that 512 bytes was the best +default unit because of its complete historical consistency on System V (<i>versus</i> the mixed 512/1024-byte usage on BSD +systems), and that a <b>-k</b> option to switch to 1024-byte units was a good compromise. Users who prefer the more logical +1024-byte quantity can easily alias <i>df</i> to <i>df</i> <b>-k</b> without breaking many historical scripts relying on the +512-byte units.</p> +<p>It was suggested that <i>df</i> and the various related utilities be modified to access a <i>BLOCKSIZE</i> environment variable +to achieve consistency and user acceptance. Since this is not historical practice on any system, it is left as a possible area for +system extensions and will be re-evaluated in a future version if it is widely implemented.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_33_19" id="tag_20_33_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_33_20" id="tag_20_33_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/find.html#"><i>find</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_33_21" id="tag_20_33_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_33_22" id="tag_20_33_22"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_33_23" id="tag_20_33_23"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #099 is applied.</p> +<p>The <i>df</i> utility is removed from the User Portability Utilities option. User Portability Utilities is now an option for +interactive utilities.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0082 [156] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_33_24" id="tag_20_33_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to report an error if a utility is directed to display a +pathname that contains any bytes that have the encoded value of a <newline> character when <newline> is a terminator or +separator in the output format being used.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/delta.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/diff.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/diff.html b/bdd/diff.html @@ -0,0 +1,546 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>diff</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/df.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/dirname.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="diff" id="diff"></a> <a name="tag_20_34" id="tag_20_34"></a><!-- diff --> +<h4 class="mansect"><a name="tag_20_34_01" id="tag_20_34_01"></a>NAME</h4> +<blockquote>diff — compare two files</blockquote> +<h4 class="mansect"><a name="tag_20_34_02" id="tag_20_34_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>diff</tt> <b>[</b><tt>-c|-e|-f|-u|-C</tt> <i>n</i><tt>|-U</tt> <i>n</i><b>] [</b><tt>-br</tt><b>]</b> <i>file1 file2</i></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_34_03" id="tag_20_34_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>diff</i> utility shall compare the contents of <i>file1</i> and <i>file2</i> and write to standard output a list of +changes necessary to convert <i>file1</i> into <i>file2</i>. This list should be minimal. No output shall be produced if the files +are identical.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_34_04" id="tag_20_34_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>diff</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-b</b></dt> +<dd>Cause any amount of white space at the end of a line to be treated as a single <newline> (that is, the white-space +characters preceding the <newline> are ignored) and other strings of white-space characters, not including <newline> +characters, to compare equal.</dd> +<dt><b>-c</b></dt> +<dd>Produce output in a form that provides three lines of copied context.</dd> +<dt><b>-C </b><i>n</i></dt> +<dd>Produce output in a form that provides <i>n</i> lines of copied context (where <i>n</i> shall be interpreted as a positive +decimal integer).</dd> +<dt><b>-e</b></dt> +<dd>Produce output in a form suitable as input for the <a href="../utilities/ed.html"><i>ed</i></a> utility, which can then be used +to convert <i>file1</i> into <i>file2</i>.</dd> +<dt><b>-f</b></dt> +<dd>Produce output in an alternative form, similar in format to <b>-e</b>, but not intended to be suitable as input for the +<a href="../utilities/ed.html"><i>ed</i></a> utility, and in the opposite order.</dd> +<dt><b>-r</b></dt> +<dd>Apply <i>diff</i> recursively to files and directories of the same name when <i>file1</i> and <i>file2</i> are both +directories. +<p>The <i>diff</i> utility shall detect infinite loops; that is, entering a previously visited directory that is an ancestor of the +last file encountered. When it detects an infinite loop, <i>diff</i> shall write a diagnostic message to standard error and shall +either recover its position in the hierarchy or terminate.</p> +</dd> +<dt><b>-u</b></dt> +<dd>Produce output in a form that provides three lines of unified context.</dd> +<dt><b>-U </b><i>n</i></dt> +<dd>Produce output in a form that provides <i>n</i> lines of unified context (where <i>n</i> shall be interpreted as a non-negative +decimal integer).</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_34_05" id="tag_20_34_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file1</i>, <i>file2</i></dt> +<dd>A pathname of a file to be compared. If either the <i>file1</i> or <i>file2</i> operand is <tt>'-'</tt>, the standard input +shall be used in its place.</dd> +</dl> +<p>If both <i>file1</i> and <i>file2</i> are directories, <i>diff</i> shall not compare block special files, character special +files, or FIFO special files to any files and shall not compare regular files to directories. Further details are as specified in +<a href="#tag_20_34_10_01">Diff Directory Comparison Format</a> . The behavior of <i>diff</i> on other file types is +implementation-defined when found in directories.</p> +<p>If only one of <i>file1</i> and <i>file2</i> is a directory, <i>diff</i> shall be applied to the non-directory file and the file +contained in the directory file with a filename that is the same as the last component of the non-directory file.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_34_06" id="tag_20_34_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be used only if one of the <i>file1</i> or <i>file2</i> operands references standard input. See the +INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_34_07" id="tag_20_34_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files may be of any type.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_34_08" id="tag_20_34_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>diff</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error and +informative messages written to standard output.</dd> +<dt><i>LC_TIME</i></dt> +<dd>Determine the locale for affecting the format of file timestamps written with the <b>-C</b> and <b>-c</b> options.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>TZ</i></dt> +<dd>Determine the timezone used for calculating file timestamps written with a context format. If <i>TZ</i> is unset or null, an +unspecified default timezone shall be used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_34_09" id="tag_20_34_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_34_10" id="tag_20_34_10"></a>STDOUT</h4> +<blockquote> +<h5><a name="tag_20_34_10_01" id="tag_20_34_10_01"></a>Diff Directory Comparison Format</h5> +<p>If both <i>file1</i> and <i>file2</i> are directories, the following output formats shall be used.</p> +<p>In the POSIX locale, each file that is present in only one directory shall be reported using the following format:</p> +<pre> +<tt>"Only in %s: %s\n", <</tt><i>directory pathname</i><tt>>, <</tt><i>filename</i><tt>> +</tt></pre> +<p>In the POSIX locale, subdirectories that are common to the two directories may be reported with the following format:</p> +<pre> +<tt>"Common subdirectories: %s and %s\n", <</tt><i>directory1 pathname</i><tt>>, + <</tt><i>directory2 pathname</i><tt>> +</tt></pre> +<p>For each file common to the two directories, if the two files are not to be compared: if the two files have the same device ID +and file serial number, or are both block special files that refer to the same device, or are both character special files that +refer to the same device, in the POSIX locale the output format is unspecified. Otherwise, in the POSIX locale an unspecified +format shall be used that contains the pathnames of the two files.</p> +<p>For each file common to the two directories, if the files are compared and are identical, no output shall be written. If the two +files differ, the following format is written:</p> +<pre> +<tt>"diff %s %s %s\n", <</tt><i>diff_options</i><tt>>, <</tt><i>filename1</i><tt>>, <</tt><i>filename2</i><tt>> +</tt></pre> +<p>where <<i>diff_options</i>> are the options as specified on the command line.</p> +<p>All directory pathnames listed in this section shall be relative to the original command line arguments. All other names of +files listed in this section shall be filenames (pathname components).</p> +<h5><a name="tag_20_34_10_02" id="tag_20_34_10_02"></a>Diff Binary Output Format</h5> +<p>In the POSIX locale, if one or both of the files being compared are not text files, it is implementation-defined whether +<i>diff</i> uses the binary file output format or the other formats as specified below. The binary file output format shall contain +the pathnames of two files being compared and the string <tt>"differ"</tt>.</p> +<p>If both files being compared are text files, depending on the options specified, one of the following formats shall be used to +write the differences.</p> +<h5><a name="tag_20_34_10_03" id="tag_20_34_10_03"></a>Diff Default Output Format</h5> +<p>The default (without <b>-e</b>, <b>-f</b>, <b>-c</b>, <b>-C</b>, <b>-u</b>, or <b>-U</b> options) <i>diff</i> utility output +shall contain lines of these forms:</p> +<pre> +<tt>"%da%d\n", <</tt><i>num1</i><tt>>, <</tt><i>num2</i><tt>> +<br> +"%da%d,%d\n", <</tt><i>num1</i><tt>>, <</tt><i>num2</i><tt>>, <</tt><i>num3</i><tt>> +<br> +"%dd%d\n", <</tt><i>num1</i><tt>>, <</tt><i>num2</i><tt>> +<br> +"%d,%dd%d\n", <</tt><i>num1</i><tt>>, <</tt><i>num2</i><tt>>, <</tt><i>num3</i><tt>> +<br> +"%dc%d\n", <</tt><i>num1</i><tt>>, <</tt><i>num2</i><tt>> +<br> +"%d,%dc%d\n", <</tt><i>num1</i><tt>>, <</tt><i>num2</i><tt>>, <</tt><i>num3</i><tt>> +<br> +"%dc%d,%d\n", <</tt><i>num1</i><tt>>, <</tt><i>num2</i><tt>>, <</tt><i>num3</i><tt>> +<br> +"%d,%dc%d,%d\n", <</tt><i>num1</i><tt>>, <</tt><i>num2</i><tt>>, <</tt><i>num3</i><tt>>, <</tt><i>num4</i><tt>> +</tt></pre> +<p>These lines resemble <a href="../utilities/ed.html"><i>ed</i></a> subcommands to convert <i>file1</i> into <i>file2</i>. The +line numbers before the action letters shall pertain to <i>file1</i>; those after shall pertain to <i>file2</i>. Thus, by +exchanging <i>a</i> for <i>d</i> and reading the line in reverse order, one can also determine how to convert <i>file2</i> into +<i>file1</i>. As in <a href="../utilities/ed.html"><i>ed</i></a>, identical pairs (where <i>num1</i>= <i>num2</i>) are abbreviated +as a single number.</p> +<p>Following each of these lines, <i>diff</i> shall write to standard output all lines affected in the first file using the +format:</p> +<pre> +<tt>"<Δ%s", <</tt><i>line</i><tt>> +</tt></pre> +<p>and all lines affected in the second file using the format:</p> +<pre> +<tt>">Δ%s", <</tt><i>line</i><tt>> +</tt></pre> +<p>If there are lines affected in both <i>file1</i> and <i>file2</i> (as with the <b>c</b> subcommand), the changes are separated +with a line consisting of three <hyphen-minus> characters:</p> +<pre> +<tt>"---\n" +</tt></pre> +<h5><a name="tag_20_34_10_04" id="tag_20_34_10_04"></a>Diff -e Output Format</h5> +<p>With the <b>-e</b> option, a script shall be produced that shall, when provided as input to <a href= +"../utilities/ed.html"><i>ed</i></a>, along with an appended <b>w</b> (write) command, convert <i>file1</i> into <i>file2</i>. Only +the <b>a</b> (append), <b>c</b> (change), <b>d</b> (delete), <b>i</b> (insert), and <b>s</b> (substitute) commands of <a href= +"../utilities/ed.html"><i>ed</i></a> shall be used in this script. Text lines, except those consisting of the single character +<period> (<tt>'.'</tt>), shall be output as they appear in the file.</p> +<h5><a name="tag_20_34_10_05" id="tag_20_34_10_05"></a>Diff -f Output Format</h5> +<p>With the <b>-f</b> option, an alternative format of script shall be produced. It is similar to that produced by <b>-e</b>, with +the following differences:</p> +<ol> +<li> +<p>It is expressed in reverse sequence; the output of <b>-e</b> orders changes from the end of the file to the beginning; the +<b>-f</b> from beginning to end.</p> +</li> +<li> +<p>The command form <<i>lines</i>> <<i>command-letter</i>> used by <b>-e</b> is reversed. For example, 10<i>c</i> with +<b>-e</b> would be <i>c</i>10 with <b>-f</b>.</p> +</li> +<li> +<p>The form used for ranges of line numbers is <space>-separated, rather than <comma>-separated.</p> +</li> +</ol> +<h5><a name="tag_20_34_10_06" id="tag_20_34_10_06"></a>Diff -c or -C Output Format</h5> +<p>With the <b>-c</b> or <b>-C</b> option, the output format shall consist of affected lines along with surrounding lines of +context. The affected lines shall show which ones need to be deleted or changed in <i>file1</i>, and those added from <i>file2</i>. +With the <b>-c</b> option, three lines of context, if available, shall be written before and after the affected lines. With the +<b>-C</b> option, the user can specify how many lines of context are written. The exact format follows.</p> +<p>The name and last modification time of each file shall be output in the following format:</p> +<pre> +<tt>"*** %s %s\n", </tt><i>file1</i><tt>, <</tt><i>file1 timestamp</i><tt>> +"--- %s %s\n", </tt><i>file2</i><tt>, <</tt><i>file2 timestamp</i><tt>> +</tt></pre> +<p>Each <<i>file</i>> field shall be the pathname of the corresponding file being compared. The pathname written for standard +input is unspecified.</p> +<p>In the POSIX locale, each <<i>timestamp</i>> field shall be equivalent to the output from the following command:</p> +<pre> +<tt>date "+%a %b %e %T %Y" +</tt></pre> +<p>without the trailing <newline>, executed at the time of last modification of the corresponding file (or the current time, +if the file is standard input).</p> +<p>Then, the following output formats shall be applied for every set of changes.</p> +<p>First, a line shall be written in the following format:</p> +<pre> +<tt>"***************\n" +</tt></pre> +<p>Next, the range of lines in <i>file1</i> shall be written in the following format if the range contains two or more lines:</p> +<pre> +<tt>"*** %d,%d ****\n", <</tt><i>beginning line number</i><tt>>, <</tt><i>ending line number</i><tt>> +</tt></pre> +<p>and the following format otherwise:</p> +<pre> +<tt>"*** %d ****\n", <</tt><i>ending line number</i><tt>> +</tt></pre> +<p>The ending line number of an empty range shall be the number of the preceding line, or 0 if the range is at the start of the +file.</p> +<p>Next, the affected lines along with lines of context (unaffected lines) shall be written. Unaffected lines shall be written in +the following format:</p> +<pre> +<tt>"ΔΔ%s", <</tt><i>unaffected_line</i><tt>> +</tt></pre> +<p>Deleted lines shall be written as:</p> +<pre> +<tt>"-Δ%s", <</tt><i>deleted_line</i><tt>> +</tt></pre> +<p>Changed lines shall be written as:</p> +<pre> +<tt>"!Δ%s", <</tt><i>changed_line</i><tt>> +</tt></pre> +<p>Next, the range of lines in <i>file2</i> shall be written in the following format if the range contains two or more lines:</p> +<pre> +<tt>"--- %d,%d ----\n", <</tt><i>beginning line number</i><tt>>, <</tt><i>ending line number</i><tt>> +</tt></pre> +<p>and the following format otherwise:</p> +<pre> +<tt>"--- %d ----\n", <</tt><i>ending line number</i><tt>> +</tt></pre> +<p>Then, lines of context and changed lines shall be written as described in the previous formats. Lines added from <i>file2</i> +shall be written in the following format:</p> +<pre> +<tt>"+Δ%s", <</tt><i>added_line</i><tt>> +</tt></pre> +<h5><a name="tag_20_34_10_07" id="tag_20_34_10_07"></a>Diff -u or -U Output Format</h5> +<p>The <b>-u</b> or <b>-U</b> options behave like the <b>-c</b> or <b>-C</b> options, except that the context lines are not +repeated; instead, the context, deleted, and added lines are shown together, interleaved. The exact format follows.</p> +<p>The name and last modification time of each file shall be output in the following format:</p> +<pre> +<tt>"---Δ%s\t%s%sΔ%s\n", file1, <file1 timestamp>, <file1 frac>, <file1 zone> +"+++Δ%s\t%s%sΔ%s\n", file2, <file2 timestamp>, <file2 frac>, <file2 zone> +</tt></pre> +<p>Each <<i>file</i>> field shall be the pathname of the corresponding file being compared, or the single character +<tt>'-'</tt> if standard input is being compared. However, if the pathname contains a <tab> or a <newline>, or if it +does not consist entirely of characters taken from the portable character set, the behavior is implementation-defined.</p> +<p>Each <<i>timestamp</i>> field shall be equivalent to the output from the following command:</p> +<pre> +<tt>date '+%Y-%m-%dΔ%H:%M:%S' +</tt></pre> +<p>without the trailing <newline>, executed at the time of last modification of the corresponding file (or the current time, +if the file is standard input).</p> +<p>Each <<i>frac</i>> field shall be either empty, or a decimal point followed by at least one decimal digit, indicating the +fractional-seconds part (if any) of the file timestamp. The number of fractional digits shall be at least the number needed to +represent the file's timestamp without loss of information.</p> +<p>Each <<i>zone</i>> field shall be of the form <tt>"shhmm"</tt>, where <tt>"shh"</tt> is a signed two-digit decimal number +in the range -24 through +25, and <tt>"mm"</tt> is an unsigned two-digit decimal number in the range 00 through 59. It represents +the timezone of the timestamp as the number of hours (hh) and minutes (mm) east (+) or west (-) of UTC for the timestamp. If the +hours and minutes are both zero, the sign shall be <tt>'+'</tt>. However, if the timezone is not an integral number of minutes away +from UTC, the <<i>zone</i>> field is implementation-defined.</p> +<p>Then, the following output formats shall be applied for every set of changes.</p> +<p>First, the range of lines in each file shall be written in the following format:</p> +<pre> +<tt>"@@Δ-%sΔ+%sΔ@@", <file1 range>, <file2 range> +</tt></pre> +<p>Each <<i>range</i>> field shall be of the form:</p> +<pre> +<tt>"%1d", <beginning line number> +</tt></pre> +<p>or:</p> +<pre> +<tt>"%1d,1", <beginning line number> +</tt></pre> +<p>if the range contains exactly one line, and:</p> +<pre> +<tt>"%1d,%1d", <beginning line number>, <number of lines> +</tt></pre> +<p>otherwise. If a range is empty, its beginning line number shall be the number of the line just before the range, or 0 if the +empty range starts the file.</p> +<p>Next, the affected lines along with lines of context shall be written. Each non-empty unaffected line shall be written in the +following format:</p> +<pre> +<tt>"Δ%s", <unaffected_line> +</tt></pre> +<p>where the contents of the unaffected line shall be taken from <i>file1</i>. It is implementation-defined whether an empty +unaffected line is written as an empty line or a line containing a single <space> character. This line also represents the +same line of <i>file2</i>, even though <i>file2</i>'s line may contain different contents due to the <b>-b</b>. Deleted lines shall +be written as:</p> +<pre> +<tt>"-%s", <deleted_line> +</tt></pre> +<p>Added lines shall be written as:</p> +<pre> +<tt>"+%s", <added_line> +</tt></pre> +<p>The order of lines written shall be the same as that of the corresponding file. A deleted line shall never be written +immediately after an added line.</p> +<p>If <b>-U</b> <i>n</i> is specified, the output shall contain no more than 2<i>n</i> consecutive unaffected lines; and if the +output contains an affected line and this line is adjacent to up to <i>n</i> consecutive unaffected lines in the corresponding +file, the output shall contain these unaffected lines. <b>-u</b> shall act like <b>-U</b>3.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_34_11" id="tag_20_34_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_34_12" id="tag_20_34_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_34_13" id="tag_20_34_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_34_14" id="tag_20_34_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>No differences were found.</dd> +<dt> 1</dt> +<dd>Differences were found and all differences were successfully output.</dd> +<dt>>1</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_34_15" id="tag_20_34_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_34_16" id="tag_20_34_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>If lines at the end of a file are changed and other lines are added, <i>diff</i> output may show this as a delete and add, as a +change, or as a change and add; <i>diff</i> is not expected to know which happened and users should not care about the difference +in output as long as it clearly shows the differences between the files.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_34_17" id="tag_20_34_17"></a>EXAMPLES</h4> +<blockquote> +<p>If <b>dir1</b> is a directory containing a directory named <b>x</b>, <b>dir2</b> is a directory containing a directory named +<b>x</b>, <b>dir1/x</b> and <b>dir2/x</b> both contain files named <b>date.out</b>, and <b>dir2/x</b> contains a file named +<b>y</b>, the command:</p> +<pre> +<tt>diff -r dir1 dir2 +</tt></pre> +<p>could produce output similar to:</p> +<pre> +<tt>Common subdirectories: dir1/x and dir2/x +Only in dir2/x: y +diff -r dir1/x/date.out dir2/x/date.out +1c1 +< Mon Jul 2 13:12:16 PDT 1990 +--- +> Tue Jun 19 21:41:39 PDT 1990 +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_34_18" id="tag_20_34_18"></a>RATIONALE</h4> +<blockquote> +<p>The <b>-h</b> option was omitted because it was insufficiently specified and does not add to applications portability.</p> +<p>Historical implementations employ algorithms that do not always produce a minimum list of differences; the current language +about making every effort is the best this volume of POSIX.1-2024 can do, as there is no metric that could be employed to judge the +quality of implementations against any and all file contents. The statement "This list should be minimal" clearly implies that +implementations are not expected to provide the following output when comparing two 100-line files that differ in only one +character on a single line:</p> +<pre> +<tt>1,100c1,100 +all 100 lines from file1 preceded with "< " +--- +all 100 lines from file2 preceded with "> " +</tt></pre> +<p>The "Only in" messages required when the <b>-r</b> option is specified are not used by most historical implementations if the +<b>-e</b> option is also specified. It is required here because it provides useful information that must be provided to update a +target directory hierarchy to match a source hierarchy. The "Common subdirectories" messages are written by System V and 4.3 BSD +when the <b>-r</b> option is specified. They are allowed here but are not required because they are reporting on something that is +the same, not reporting a difference, and are not needed to update a target hierarchy.</p> +<p>The <b>-c</b> option, which writes output in a format using lines of context, has been included. The format is useful for a +variety of reasons, among them being much improved readability and the ability to understand difference changes when the target +file has line numbers that differ from another similar, but slightly different, copy. The <a href= +"../utilities/patch.html"><i>patch</i></a> utility is most valuable when working with difference listings using a context format. +The BSD version of <b>-c</b> takes an optional argument specifying the amount of context. Rather than overloading <b>-c</b> and +breaking the Utility Syntax Guidelines for <i>diff</i>, the standard developers decided to add a separate option for specifying a +context diff with a specified amount of context (<b>-C</b>). Also, the format for context <i>diff</i>s was extended slightly in 4.3 +BSD to allow multiple changes that are within context lines from each other to be merged together. The output format contains an +additional four <asterisk> characters after the range of affected lines in the first filename. This was to provide a flag for +old programs (like old versions of <a href="../utilities/patch.html"><i>patch</i></a>) that only understand the old context format. +The version of context described here does not require that multiple changes within context lines be merged, but it does not +prohibit it either. The extension is upwards-compatible, so any vendors that wish to retain the old version of <i>diff</i> can do +so by adding the extra four <asterisk> characters (that is, utilities that currently use <i>diff</i> and understand the new +merged format will also understand the old unmerged format, but not <i>vice versa</i>).</p> +<p>The <b>-u</b> and <b>-U</b> options of GNU <i>diff</i> have been included. Their output format, designed by Wayne Davison, takes +up less space than <b>-c</b> and <b>-C</b> format, and in many cases is easier to read. The format's timestamps do not vary by +locale, so <i>LC_TIME</i> does not affect it. The format's line numbers are rendered with the <tt>%1d</tt> format, not <tt>%d</tt>, +because the file format notation rules would allow extra <blank> characters to appear around the numbers.</p> +<p>The substitute command was added as an additional format for the <b>-e</b> option. This was added to provide implementations +with a way to fix the classic "dot alone on a line" bug present in many versions of <i>diff</i>. Since many implementations have +fixed this bug, the standard developers decided not to standardize broken behavior, but rather to provide the necessary tool for +fixing the bug. One way to fix this bug is to output two periods whenever a lone period is needed, then terminate the append +command with a period, and then use the substitute command to convert the two periods into one period.</p> +<p>The BSD-derived <b>-r</b> option was added to provide a mechanism for using <i>diff</i> to compare two file system trees. This +behavior is useful, is standard practice on all BSD-derived systems, and is not easily reproducible with the <a href= +"../utilities/find.html"><i>find</i></a> utility.</p> +<p>The requirement that <i>diff</i> not compare files in some circumstances, even though they have the same name, is based on the +actual output of historical implementations. The specified behavior precludes the problems arising from running into FIFOs and +other files that would cause <i>diff</i> to hang waiting for input with no indication to the user that <i>diff</i> was hung. An +earlier version of this standard specified the output format more precisely, but in practice this requirement was widely ignored +and the benefit of standardization seemed small, so it is now unspecified. In most common usage, <i>diff</i> <b>-r</b> should +indicate differences in the file hierarchies, not the difference of contents of devices pointed to by the hierarchies.</p> +<p>Many early implementations of <i>diff</i> require seekable files. Since the System Interfaces volume of POSIX.1-2024 supports +named pipes, the standard developers decided that such a restriction was unreasonable. Note also that the allowed filename <b>-</b> +almost always refers to a pipe.</p> +<p>No directory search order is specified for <i>diff</i>. The historical ordering is, in fact, not optimal, in that it prints out +all of the differences at the current level, including the statements about all common subdirectories before recursing into those +subdirectories.</p> +<p>The message:</p> +<pre> +<tt>"diff %s %s %s\n", <</tt><i>diff_options</i><tt>>, <</tt><i>filename1</i><tt>>, <</tt><i>filename2</i><tt>> +</tt></pre> +<p>does not vary by locale because it is the representation of a command, not an English sentence.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_34_19" id="tag_20_34_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_34_20" id="tag_20_34_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/cmp.html#"><i>cmp</i></a> , <a href="../utilities/comm.html#"><i>comm</i></a> , <a href= +"../utilities/ed.html#"><i>ed</i></a> , <a href="../utilities/find.html#"><i>find</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_34_21" id="tag_20_34_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_34_22" id="tag_20_34_22"></a>Issue 5</h4> +<blockquote> +<p>The FUTURE DIRECTIONS section is added.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_34_23" id="tag_20_34_23"></a>Issue 6</h4> +<blockquote> +<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p> +<ul> +<li> +<p>The <b>-f</b> option is added.</p> +</li> +</ul> +<p>The output format for <b>-c</b> or <b>-C</b> format is changed to align with changes to the IEEE P1003.2b draft standard +resulting from IEEE PASC Interpretation 1003.2 #71.</p> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +<p>IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/20 is applied, changing the STDOUT section. This changes the +specification of <i>diff</i> <b>-c</b> so that it agrees with existing practice when contexts contain zero lines or one line.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_34_24" id="tag_20_34_24"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretations 1003.1-2001 #115 and #114 are applied.</p> +<p>Austin Group Interpretation 1003.1-2001 #192 is applied, clarifying the behavior if both files are non-text files.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>SD5-XCU-ERN-103 and SD5-XCU-ERN-120 are applied, adding the <b>-u</b> option.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0082 [584], XCU/TC2-2008/0083 [950], XCU/TC2-2008/0084 [969], and +XCU/TC2-2008/0085 [929] are applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_34_25" id="tag_20_34_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to report an error if a utility is directed to display a +pathname that contains any bytes that have the encoded value of a <newline> character when <newline> is a terminator or +separator in the output format being used.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1498 is applied, changing the EXIT STATUS section.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/df.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/dirname.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/dirname.html b/bdd/dirname.html @@ -0,0 +1,228 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>dirname</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/diff.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/du.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="dirname" id="dirname"></a> <a name="tag_20_35" id="tag_20_35"></a><!-- dirname --> +<h4 class="mansect"><a name="tag_20_35_01" id="tag_20_35_01"></a>NAME</h4> +<blockquote>dirname — return the directory portion of a pathname</blockquote> +<h4 class="mansect"><a name="tag_20_35_02" id="tag_20_35_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>dirname</tt> <i>string</i></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_35_03" id="tag_20_35_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>string</i> operand shall be treated as a pathname, as defined in XBD <a href= +"../basedefs/V1_chap03.html#tag_03_254"><i>3.254 Pathname</i></a> , and shall be converted to a pathname of the directory +containing the entry of the final pathname component. The resulting string shall be written to standard output. The <i>dirname</i> +utility shall not perform pathname resolution; the result shall not be affected by whether or not a file with the pathname +<i>string</i> exists or by its file type. Trailing <tt>'/'</tt> characters in <i>string</i> that are not also leading <tt>'/'</tt> +characters shall not be counted as part of the pathname. If the pathname does not contain a <tt>'/'</tt>, the resulting string +shall be <tt>"."</tt>. If <i>string</i> is an empty string, the resulting string shall be <tt>"."</tt>.</p> +<p>It is unspecified whether redundant <tt>'/'</tt> characters and <tt>'.'</tt> pathname components in <i>string</i> are removed +after determining the pathname to output. However, <tt>".."</tt> pathname components occurring prior to the final component shall +not be removed.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_35_04" id="tag_20_35_04"></a>OPTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_35_05" id="tag_20_35_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>string</i></dt> +<dd>A string.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_35_06" id="tag_20_35_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_35_07" id="tag_20_35_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_35_08" id="tag_20_35_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>dirname</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_35_09" id="tag_20_35_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_35_10" id="tag_20_35_10"></a>STDOUT</h4> +<blockquote> +<p>The <i>dirname</i> utility shall write a line to the standard output in the following format:</p> +<pre> +<tt>"%s\n", <</tt><i>resulting string</i><tt>> +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_35_11" id="tag_20_35_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_35_12" id="tag_20_35_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_35_13" id="tag_20_35_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_35_14" id="tag_20_35_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_35_15" id="tag_20_35_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_35_16" id="tag_20_35_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The definition of <i>pathname</i> specifies implementation-defined behavior for pathnames starting with two <slash> +characters. Therefore, applications shall not arbitrarily add <slash> characters to the beginning of a pathname unless they +can ensure that there are more or less than two or are prepared to deal with the implementation-defined consequences.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_35_17" id="tag_20_35_17"></a>EXAMPLES</h4> +<blockquote> +<p>The EXAMPLES section of the <a href="../functions/basename.html"><i>basename</i>()</a> function (see XSH <a href= +"../functions/basename.html#tag_17_42"><i>basename</i></a> ) includes a table showing examples of the results of processing several +sample pathnames by the <a href="../functions/basename.html"><i>basename</i>()</a> and <a href= +"../functions/dirname.html"><i>dirname</i>()</a> functions and by the <a href="../utilities/basename.html"><i>basename</i></a> and +<i>dirname</i> utilities.</p> +<p>See also the examples for the <a href="../utilities/basename.html"><i>basename</i></a> utility.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_35_18" id="tag_20_35_18"></a>RATIONALE</h4> +<blockquote> +<p>The behaviors of <a href="../utilities/basename.html"><i>basename</i></a> and <i>dirname</i> in this volume of POSIX.1-2024 have +been coordinated so that when <i>string</i> is a valid pathname:</p> +<pre> +<tt>$(basename -- "</tt><i>string</i><tt>") +</tt></pre> +<p>would be a valid filename for the file in the directory:</p> +<pre> +<tt>$(dirname -- "</tt><i>string</i><tt>") +</tt></pre> +<p>This would not work for the versions of these utilities in early proposals due to the way processing of trailing <slash> +characters was specified. Consideration was given to leaving processing unspecified if there were trailing <slash> +characters, but this cannot be done; XBD <a href="../basedefs/V1_chap03.html#tag_03_254"><i>3.254 Pathname</i></a> allows trailing +<slash> characters. The <a href="../utilities/basename.html"><i>basename</i></a> and <i>dirname</i> utilities have to specify +consistent handling for all valid pathnames.</p> +<p>The <i>dirname</i> utility is not specified in terms of the <a href="../functions/dirname.html"><i>dirname</i>()</a> function, +because the two may produce slightly different output where both output forms are still compliant. An implementation should prefer +the shortest output possible; however, this is not required, in part because earlier versions of the standard did not permit +elision of redundant <slash> characters or dot (<tt>'.'</tt>) components. Removal of the dot-dot (<tt>".."</tt>) pathname +component is not permitted, because eliding it correctly would require performing pathname resolution to ensure the resulting +string would still point to the correct pathname if the original string resolved as a pathname. On implementations where pathname +<tt>"//"</tt> has an implementation-defined meaning distinct from the pathname <tt>"/"</tt>, the dirname of <tt>"//"</tt> will be +<tt>"//"</tt>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_35_19" id="tag_20_35_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_35_20" id="tag_20_35_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19_05"><i>2.5 Parameters and Variables</i></a> , <a href= +"../utilities/basename.html#tag_20_07"><i>basename</i></a></p> +<p>XBD <a href="../basedefs/V1_chap03.html#tag_03_254"><i>3.254 Pathname</i></a> , <a href= +"../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a></p> +<p>XSH <a href="../functions/basename.html#tag_17_42"><i>basename</i></a> , <a href= +"../functions/dirname.html#tag_17_108"><i>dirname</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_35_21" id="tag_20_35_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_35_22" id="tag_20_35_22"></a>Issue 7</h4> +<blockquote> +<p>POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0083 [192,430], XCU/TC1-2008/0084 [192], and XCU/TC1-2008/0085 [192] are +applied.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0086 [612], XCU/TC2-2008/0087 [620], and XCU/TC2-2008/0088 [612] are +applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_35_23" id="tag_20_35_23"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to report an error if a utility is directed to display a +pathname that contains any bytes that have the encoded value of a <newline> character when <newline> is a terminator or +separator in the output format being used.</p> +<p>Austin Group Defect 1073 is applied, replacing the DESCRIPTION section with one that matches the <a href= +"../functions/dirname.html"><i>dirname</i>()</a> function.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/diff.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/du.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/du.html b/bdd/du.html @@ -0,0 +1,267 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>du</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/dirname.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/echo.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="du" id="du"></a> <a name="tag_20_36" id="tag_20_36"></a><!-- du --> +<h4 class="mansect"><a name="tag_20_36_01" id="tag_20_36_01"></a>NAME</h4> +<blockquote>du — estimate file space usage</blockquote> +<h4 class="mansect"><a name="tag_20_36_02" id="tag_20_36_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>du</tt> <b>[</b><tt>-a|-s</tt><b>] [</b><tt>-kx</tt><b>] [</b><tt>-H|-L</tt><b>] [</b><i>file</i><tt>...</tt><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_36_03" id="tag_20_36_03"></a>DESCRIPTION</h4> +<blockquote> +<p>By default, the <i>du</i> utility shall write to standard output the size of the file space allocated to, and the size of the +file space allocated to each subdirectory of, the file hierarchy rooted in each of the specified files. By default, when a symbolic +link is encountered on the command line or in the file hierarchy, <i>du</i> shall count the size of the symbolic link (rather than +the file referenced by the link), and shall not follow the link to another portion of the file hierarchy. The size of the file +space allocated to a file of type directory shall be defined as the sum total of space allocated to all files in the file hierarchy +rooted in the directory plus the space allocated to the directory itself.</p> +<p>When <i>du</i> cannot <a href="../functions/stat.html"><i>stat</i>()</a> files or <a href= +"../functions/stat.html"><i>stat</i>()</a> or read directories, it shall report an error condition and the final exit status is +affected. A file that occurs multiple times shall be counted and written for only one entry, even if the occurrences are under +different file operands. The directory entry that is selected in the report is unspecified. By default, file sizes shall be written +in 512-byte units, rounded up to the next 512-byte unit.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_36_04" id="tag_20_36_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>du</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-a</b></dt> +<dd>In addition to the default output, report the size of each file not of type directory in the file hierarchy rooted in the +specified file. The <b>-a</b> option shall not affect whether non-directories given as <i>file</i> operands are listed.</dd> +<dt><b>-H</b></dt> +<dd>If a symbolic link is specified on the command line, <i>du</i> shall count the size of the file or file hierarchy referenced by +the link.</dd> +<dt><b>-k</b></dt> +<dd>Write the files sizes in units of 1024 bytes, rather than the default 512-byte units.</dd> +<dt><b>-L</b></dt> +<dd>If a symbolic link is specified on the command line or encountered during the traversal of a file hierarchy, <i>du</i> shall +count the size of the file or file hierarchy referenced by the link.</dd> +<dt><b>-s</b></dt> +<dd>Instead of the default output, report only the total sum for each of the specified files.</dd> +<dt><b>-x</b></dt> +<dd>When evaluating file sizes, evaluate only those files that have the same device as the file specified by the <i>file</i> +operand.</dd> +</dl> +<p>Specifying more than one of the mutually-exclusive options <b>-H</b> and <b>-L</b> shall not be considered an error. The last +option specified shall determine the behavior of the utility.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_36_05" id="tag_20_36_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>The pathname of a file whose size is to be written. If no <i>file</i> is specified, the current directory shall be used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_36_06" id="tag_20_36_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_36_07" id="tag_20_36_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_36_08" id="tag_20_36_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>du</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_36_09" id="tag_20_36_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_36_10" id="tag_20_36_10"></a>STDOUT</h4> +<blockquote> +<p>The output from <i>du</i> shall consist of the amount of space allocated to a file and the name of the file, in the following +format:</p> +<pre> +<tt>"%d %s\n", <</tt><i>size</i><tt>>, <</tt><i>pathname</i><tt>> +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_36_11" id="tag_20_36_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_36_12" id="tag_20_36_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_36_13" id="tag_20_36_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_36_14" id="tag_20_36_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_36_15" id="tag_20_36_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_36_16" id="tag_20_36_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_36_17" id="tag_20_36_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_36_18" id="tag_20_36_18"></a>RATIONALE</h4> +<blockquote> +<p>The use of 512-byte units is historical practice and maintains compatibility with <a href="../utilities/ls.html"><i>ls</i></a> +and other utilities in this volume of POSIX.1-2024. This does not mandate that the file system itself be based on 512-byte blocks. +The <b>-k</b> option was added as a compromise measure. It was agreed by the standard developers that 512 bytes was the best +default unit because of its complete historical consistency on System V (<i>versus</i> the mixed 512/1024-byte usage on BSD +systems), and that a <b>-k</b> option to switch to 1024-byte units was a good compromise. Users who prefer the 1024-byte quantity +can easily alias <i>du</i> to <i>du</i> <b>-k</b> without breaking the many historical scripts relying on the 512-byte units.</p> +<p>The <b>-b</b> option was added to an early proposal to provide a resolution to the situation where System V and BSD systems give +figures for file sizes in <i>blocks</i>, which is an implementation-defined concept. (In common usage, the block size is 512 bytes +for System V and 1024 bytes for BSD systems.) However, <b>-b</b> was later deleted, since the default was eventually decided as +512-byte units.</p> +<p>Historical file systems provided no way to obtain exact figures for the space allocation given to files. There are two known +areas of inaccuracies in historical file systems: cases of <i>indirect blocks</i> being used by the file system or <i>sparse</i> +files yielding incorrectly high values. An indirect block is space used by the file system in the storage of the file, but that +need not be counted in the space allocated to the file. A <i>sparse</i> file is one in which an <a href= +"../functions/lseek.html"><i>lseek</i>()</a> call has been made to a position beyond the end of the file and data has subsequently +been written at that point. A file system need not allocate all the intervening zero-filled blocks to such a file. It is up to the +implementation to define exactly how accurate its methods are.</p> +<p>The <b>-a</b> and <b>-s</b> options were mutually-exclusive in the original version of <i>du</i>. The POSIX Shell and Utilities +description is implied by the language in the SVID where <b>-s</b> is described as causing "only the grand total" to be reported. +Some systems may produce output for <b>-sa</b>, but a Strictly Conforming POSIX Shell and Utilities Application cannot use that +combination.</p> +<p>The <b>-a</b> and <b>-s</b> options were adopted from the SVID except that the System V behavior of not listing non-directories +explicitly given as operands, unless the <b>-a</b> option is specified, was considered a bug; the BSD-based behavior (report for +all operands) is mandated. The default behavior of <i>du</i> in the SVID with regard to reporting the failure to read files (it +produces no messages) was considered counter-intuitive, and thus it was specified that the POSIX Shell and Utilities default +behavior shall be to produce such messages. These messages can be turned off with shell redirection to achieve the System V +behavior.</p> +<p>The <b>-x</b> option is historical practice on recent BSD systems. It has been adopted by this volume of POSIX.1-2024 because +there was no other historical method of limiting the <i>du</i> search to a single file hierarchy. This limitation of the search is +necessary to make it possible to obtain file space usage information about a file system on which other file systems are mounted, +without having to resort to a lengthy <a href="../utilities/find.html"><i>find</i></a> and <a href= +"../utilities/awk.html"><i>awk</i></a> script.</p> +<p>The use of the <b>-L</b> option, or of multiple <i>file</i> operands, requires that <i>du</i> track all file entries +encountered, even with a link count of one. However, when <b>-L</b> is not used and only a single <i>file</i> operand is given, an +implementation can optimize by only tracking files with a link count greater than one, since in that scenario, those are the only +files that could be encountered more than once.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_36_19" id="tag_20_36_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_36_20" id="tag_20_36_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/ls.html#"><i>ls</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/fstatat.html#"><i>fstatat</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_36_21" id="tag_20_36_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_36_22" id="tag_20_36_22"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +<p>The APPLICATION USAGE section is added.</p> +<p>The obsolescent <b>-r</b> option is removed.</p> +<p>The Open Group Corrigendum U025/3 is applied. The <i>du</i> utility is reinstated, as it had incorrectly been marked LEGACY in +Issue 5.</p> +<p>The <b>-H</b> and <b>-L</b> options for symbolic links are added as described in the IEEE P1003.2b draft standard.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_36_23" id="tag_20_36_23"></a>Issue 7</h4> +<blockquote> +<p>The <i>du</i> utility is moved from the User Portability Utilities option to the Base. User Portability Utilities is now an +option for interactive utilities.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0089 [527] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_36_24" id="tag_20_36_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to report an error if a utility is directed to display a +pathname that contains any bytes that have the encoded value of a <newline> character when <newline> is a terminator or +separator in the output format being used.</p> +<p>Austin Group Defect 539 is applied, requiring a file that occurs multiple times to be counted and written for only one +entry.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/dirname.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/echo.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/echo.html b/bdd/echo.html @@ -0,0 +1,285 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>echo</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/du.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/ed.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="echo" id="echo"></a> <a name="tag_20_37" id="tag_20_37"></a><!-- echo --> +<h4 class="mansect"><a name="tag_20_37_01" id="tag_20_37_01"></a>NAME</h4> +<blockquote>echo — write arguments to standard output</blockquote> +<h4 class="mansect"><a name="tag_20_37_02" id="tag_20_37_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>echo</tt> <b>[</b><i>string</i><tt>...</tt><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_37_03" id="tag_20_37_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>echo</i> utility writes its arguments to standard output, followed by a <newline>. If there are no arguments, only +the <newline> is written.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_37_04" id="tag_20_37_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>echo</i> utility shall not recognize the <tt>"--"</tt> argument in the manner specified by Guideline 10 of XBD <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a> ; <tt>"--"</tt> shall be recognized as a string +operand.</p> +<p>Implementations shall not support any options.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_37_05" id="tag_20_37_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>string</i></dt> +<dd>A string to be written to standard output. If the first operand consists of a <tt>'-'</tt> followed by one or more characters +from the set {<tt>'e'</tt>, <tt>'E'</tt>, <tt>'n'</tt>}, or if any of the operands contain a <backslash> character, the +results are implementation-defined. +<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +On XSI-conformant systems, if the first operand consists of a <tt>'-'</tt> followed by one or more characters from the set +{<tt>'e'</tt>, <tt>'E'</tt>, <tt>'n'</tt>}, it shall be treated as a string to be written. The following character sequences shall +be recognized on XSI-conformant systems within any of the arguments:</p> +<dl compact> +<dd></dd> +<dt><tt>\a</tt></dt> +<dd>Write an <alert>.</dd> +<dt><tt>\b</tt></dt> +<dd>Write a <backspace>.</dd> +<dt><tt>\c</tt></dt> +<dd>Suppress the <newline> that otherwise follows the final argument in the output. All characters following the +<tt>'\c'</tt> in the arguments shall be ignored.</dd> +<dt><tt>\f</tt></dt> +<dd>Write a <form-feed>.</dd> +<dt><tt>\n</tt></dt> +<dd>Write a <newline>.</dd> +<dt><tt>\r</tt></dt> +<dd>Write a <carriage-return>.</dd> +<dt><tt>\t</tt></dt> +<dd>Write a <tab>.</dd> +<dt><tt>\v</tt></dt> +<dd>Write a <vertical-tab>.</dd> +<dt><tt>\\</tt></dt> +<dd>Write a <backslash> character.</dd> +<dt><tt>\0</tt><i>num</i></dt> +<dd>Write an 8-bit value that is the zero, one, two, or three-digit octal number <i>num</i>.</dd> +</dl> +</dd> +</dl> +<img src="../images/opt-end.gif" alt="[Option End]" border="0"></blockquote> +<h4 class="mansect"><a name="tag_20_37_06" id="tag_20_37_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_37_07" id="tag_20_37_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_37_08" id="tag_20_37_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>echo</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as opposed +to multi-byte characters in arguments). <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_37_09" id="tag_20_37_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_37_10" id="tag_20_37_10"></a>STDOUT</h4> +<blockquote> +<p>The <i>echo</i> utility arguments shall be separated by single <space> characters and a <newline> character shall +follow the last argument. <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> Output transformations shall occur based on the escape sequences in the input. See the OPERANDS +section. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_37_11" id="tag_20_37_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_37_12" id="tag_20_37_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_37_13" id="tag_20_37_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_37_14" id="tag_20_37_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_37_15" id="tag_20_37_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_37_16" id="tag_20_37_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>It is not possible to use <i>echo</i> portably across all POSIX systems unless escape sequences are omitted, and the first +argument does not consist of a <tt>'-'</tt> followed by one or more characters from the set {<tt>'e'</tt>, <tt>'E'</tt>, +<tt>'n'</tt>}.</p> +<p>The <a href="../utilities/printf.html"><i>printf</i></a> utility can be used portably to emulate any of the traditional +behaviors of the <i>echo</i> utility as follows (assuming that <i>IFS</i> has its standard value or is unset):</p> +<ul> +<li> +<p>The historic System V <i>echo</i> and the requirements on XSI implementations in this volume of POSIX.1-2024 are equivalent +to:</p> +<pre> +<tt>printf "%b\n" "$*" +</tt></pre></li> +<li> +<p>The BSD <i>echo</i> is equivalent to:</p> +<pre> +<tt>if [ "X$1" = "X-n" ] +then + shift + printf "%s" "$*" +else + printf "%s\n" "$*" +fi +</tt></pre></li> +</ul> +<p>New applications are encouraged to use <a href="../utilities/printf.html"><i>printf</i></a> instead of <i>echo</i>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_37_17" id="tag_20_37_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_37_18" id="tag_20_37_18"></a>RATIONALE</h4> +<blockquote> +<p>The <i>echo</i> utility has not been made obsolescent because of its extremely widespread use in historical applications. +Conforming applications that wish to do prompting without <newline> characters or that could possibly be expecting to echo a +string consisting of a <tt>'-'</tt> followed by one or more characters from the set {<tt>'e'</tt>, <tt>'E'</tt>, <tt>'n'</tt>} +should use the <a href="../utilities/printf.html"><i>printf</i></a> utility.</p> +<p>At the time that the IEEE Std 1003.2-1992 standard was being developed, the two different historical versions of +<i>echo</i> that were considered for standardization varied in incompatible ways.</p> +<p>The BSD <i>echo</i> checked the first argument for the string <b>-n</b> which caused it to suppress the <newline> that +would otherwise follow the final argument in the output.</p> +<p>The System V <i>echo</i> treated all arguments as strings to be written, but allowed escape sequences within them, as described +for XSI implementations in the OPERANDS section, including <tt>\c</tt> to suppress a trailing <newline>.</p> +<p>Thus the IEEE Std 1003.2-1992 standard said that the behavior was implementation-defined if the first operand is +<b>-n</b> or if any of the operands contain a <backslash> character. It also specified that the <i>echo</i> utility does not +support Utility Syntax Guideline 10 because historical applications depended on <i>echo</i> to echo <i>all</i> of its arguments, +except for the <b>-n</b> first argument in the BSD version.</p> +<p>The Single UNIX Specification, Version 1 required the System V behavior, and this became the XSI requirement when Version 2 and +POSIX.2 were merged with POSIX.1 to form the joint IEEE Std 1003.1-2001 / Single UNIX Specification, Version 3 +standard.</p> +<p>This standard now treats a first operand of <b>-e</b> or <b>-E</b> the same as <b>-n</b> in recognition that support for them +has become more widespread in non-XSI implementations. Where supported, <b>-e</b> enables processing of escape sequences in the +remaining operands (in situations where it is disabled by default), and <b>-E</b> disables it (in situations where it is enabled by +default). A first operand containing a combination of these three letters, in the same manner as option grouping, also results in +implementation-defined behavior.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_37_19" id="tag_20_37_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_37_20" id="tag_20_37_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/printf.html#tag_20_96"><i>printf</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_37_21" id="tag_20_37_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_37_22" id="tag_20_37_22"></a>Issue 5</h4> +<blockquote> +<p>In the OPTIONS section, the last sentence is changed to indicate that implementations "do not" support any options; in the +previous issue this said "need not".</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_37_23" id="tag_20_37_23"></a>Issue 6</h4> +<blockquote> +<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p> +<ul> +<li> +<p>A set of character sequences is defined as <i>string</i> operands.</p> +</li> +<li> +<p><i>LC_CTYPE</i> is added to the list of environment variables affecting <i>echo</i>.</p> +</li> +<li> +<p>In the OPTIONS section, implementations shall not support any options.</p> +</li> +</ul> +<p>IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/21 is applied, so that the <i>echo</i> utility can accommodate +historical BSD behavior.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_37_24" id="tag_20_37_24"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_37_25" id="tag_20_37_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1222 is applied, making the results implementation-defined, on systems that are not XSI-conformant, if the +first operand consists of a <tt>'-'</tt> followed by one or more characters from the set {<tt>'e'</tt>, <tt>'E'</tt>, +<tt>'n'</tt>}.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/du.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/ed.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/ed.html b/bdd/ed.html @@ -0,0 +1,1503 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>ed</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/echo.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/env.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="ed" id="ed"></a> <a name="tag_20_38" id="tag_20_38"></a><!-- ed --> +<h4 class="mansect"><a name="tag_20_38_01" id="tag_20_38_01"></a>NAME</h4> +<blockquote>ed — edit text</blockquote> +<h4 class="mansect"><a name="tag_20_38_02" id="tag_20_38_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>ed</tt> <b>[</b><tt>-p</tt> <i>string</i><b>] [</b><tt>-s</tt><b>] [</b><i>file</i><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_38_03" id="tag_20_38_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>ed</i> utility is a line-oriented text editor that uses two modes: <i>command mode</i> and <i>input mode</i>. In command +mode the input characters shall be interpreted as commands, and in input mode they shall be interpreted as text. See the EXTENDED +DESCRIPTION section.</p> +<p>If an operand is <tt>'-'</tt>, the results are unspecified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_38_04" id="tag_20_38_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>ed</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> , except for the unspecified usage of <tt>'-'</tt>.</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-p </b><i>string</i></dt> +<dd>Use <i>string</i> as the prompt string when in command mode. By default, there shall be no prompt string.</dd> +<dt><b>-s</b></dt> +<dd>Suppress the writing of byte counts by <b>e</b>, <b>E</b>, <b>r</b>, and <b>w</b> commands and of the <tt>'!'</tt> prompt after +a !<i>command</i>.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_38_05" id="tag_20_38_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>If the <i>file</i> argument is given, <i>ed</i> shall perform the effect of an <b>e</b> command on the pathname <i>file</i> +before accepting commands from the standard input, except that <i>file</i> can contain a <newline>, even though this is not +possible for the argument to the <b>e</b> command.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_38_06" id="tag_20_38_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be a text file consisting of commands, as described in the EXTENDED DESCRIPTION section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_38_07" id="tag_20_38_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files shall be text files.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_38_08" id="tag_20_38_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>ed</i>:</p> +<dl compact> +<dd></dd> +<dt><i>HOME</i></dt> +<dd>Determine the pathname of the user's home directory.</dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_COLLATE</i></dt> +<dd><br> +Determine the locale for the behavior of ranges, equivalence classes, and multi-character collating elements within regular +expressions.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files) and the behavior of character classes within regular +expressions.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error and +informative messages written to standard output.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_38_09" id="tag_20_38_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>The <i>ed</i> utility shall take the standard action for all signals (see the ASYNCHRONOUS EVENTS section in <a href= +"../utilities/V3_chap01.html#tag_18_04"><i>1.4 Utility Description Defaults</i></a> ) with the following exceptions:</p> +<dl compact> +<dd></dd> +<dt>SIGINT</dt> +<dd>The <i>ed</i> utility shall interrupt its current activity, write the string <tt>"?\n"</tt> to standard output, and return to +command mode (see the EXTENDED DESCRIPTION section).</dd> +<dt>SIGHUP</dt> +<dd>If the buffer is not empty and the buffer change flag is currently set to either <b>changed</b> or <b>changed-and-warned</b> +(see the EXTENDED DESCRIPTION section), the <i>ed</i> utility shall attempt to write a copy of the buffer in a file. First, the +file named <b>ed.hup</b> in the current directory shall be used; if that fails, the file named <b>ed.hup</b> in the directory named +by the <i>HOME</i> environment variable shall be used. In any case, the <i>ed</i> utility shall exit without writing the file to +the currently remembered pathname and without returning to command mode.</dd> +<dt>SIGQUIT</dt> +<dd>The <i>ed</i> utility shall ignore this event.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_38_10" id="tag_20_38_10"></a>STDOUT</h4> +<blockquote> +<p>Various editing commands and the prompting feature (see <b>-p</b>) write to standard output, as described in the EXTENDED +DESCRIPTION section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_38_11" id="tag_20_38_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used for diagnostic messages and may be used for warning messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_38_12" id="tag_20_38_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>The output files shall be text files whose formats are dependent on the editing commands given.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_38_13" id="tag_20_38_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>The <i>ed</i> utility shall operate on a copy of the file it is editing; changes made to the copy shall have no effect on the +file until a <b>w</b> (write) command is given. The copy of the text is called the <i>buffer</i>. The <i>ed</i> utility shall keep +track of whether the buffer has been modified. This shall be maintained as if via a tri-state internal flag with the state values +<b>unchanged</b>, <b>changed</b>, and <b>changed-and-warned</b>, which is:</p> +<ul> +<li> +<p>Initially set to <b>unchanged</b></p> +</li> +<li> +<p>Set to <b>changed</b> by any command that modifies the buffer</p> +</li> +<li> +<p>Set to <b>unchanged</b> by an <b>e</b> or <b>E</b> command that reloads (or empties) the buffer, or a <b>w</b> command that +writes the entire buffer</p> +</li> +<li> +<p>Set to either <b>changed-and-warned</b> or <b>unchanged</b> by an <b>e</b> or <b>q</b> command that warns an attempt was made to +destroy the editor buffer</p> +</li> +</ul> +<p>A command that makes changes to the buffer in such a way that its contents are the same after the command (for example +<b>s/a/a/</b>) shall be considered to have modified the buffer, unless explicitly stated otherwise. In the remainder of the +description, this flag is referred to as the <i>buffer change flag</i>.</p> +<p>Commands to <i>ed</i> have a simple and regular structure: zero, one, or two <i>addresses</i> followed by a single-character +<i>command</i>, possibly followed by parameters to that command. These addresses specify one or more lines in the buffer. Every +command that requires addresses has default addresses, so that the addresses very often can be omitted. If the <b>-p</b> option is +specified, the prompt string shall be written to standard output before each command is read.</p> +<p>In general, only one command can appear on a line. Certain commands allow text to be input. This text is placed in the +appropriate place in the buffer. While <i>ed</i> is accepting text, it is said to be in <i>input mode</i>. In this mode, no +commands shall be recognized; all input is merely collected. Input mode is terminated by entering a line consisting of two +characters: a <period> (<tt>'.'</tt>) followed by a <newline>. This line is not considered part of the input text.</p> +<h5><a name="tag_20_38_13_01" id="tag_20_38_13_01"></a>Regular Expressions in ed</h5> +<p>The <i>ed</i> utility shall support basic regular expressions, as described in XBD <a href= +"../basedefs/V1_chap09.html#tag_09_03"><i>9.3 Basic Regular Expressions</i></a> . Since regular expressions in <i>ed</i> are always +matched against single lines (excluding the terminating <newline> characters), never against any larger section of text, +there is no way for a regular expression to match a <newline>.</p> +<p>A null RE shall be equivalent to the last RE encountered.</p> +<p>Regular expressions are used in addresses to specify lines, and in some commands (for example, the <b>s</b> substitute command) +to specify portions of a line to be substituted.</p> +<p>The start and end of a regular expression (RE) are marked by a delimiter character (although in some circumstances the end +delimiter can be omitted). In addresses, the delimiter is either <slash> or <question-mark>. In commands, other +characters can be used as the delimiter, as specified in the description of the command. Within the RE (as an <i>ed</i> extension +to the BRE syntax), the delimiter shall not terminate the RE if it is the second character of an escape sequence (see XBD <a href= +"../basedefs/V1_chap09.html#tag_09_01"><i>9.1 Regular Expression Definitions</i></a> ) and the escaped delimiter shall be treated +as that literal character in the RE (losing any special meaning it would have had if it was not used as the delimiter and was not +escaped). In addition, the delimiter character shall not terminate the RE when it appears within a bracket expression, and shall +have its normal meaning in the bracket expression. For example, the command <tt>"g%[%]%p"</tt> is equivalent to <tt>"g/[%]/p"</tt>, +and the command <tt>"s-[0-9]--g"</tt> is equivalent to <tt>"s/[0-9]//g"</tt>.</p> +<h5><a name="tag_20_38_13_02" id="tag_20_38_13_02"></a>Addresses in ed</h5> +<p>Addressing in <i>ed</i> relates to the current line. Generally, the current line is the last line affected by a command. The +current line number is the address of the current line. If the edit buffer is not empty, the initial value for the current line +shall be the last line in the edit buffer; otherwise, zero.</p> +<p>Addresses shall be constructed as follows:</p> +<ol> +<li> +<p>The <period> character (<tt>'.'</tt>) shall address the current line.</p> +</li> +<li> +<p>The <dollar-sign> character (<tt>'$'</tt>) shall address the last line of the edit buffer.</p> +</li> +<li> +<p>The positive decimal number <i>n</i> shall address the <i>n</i>th line of the edit buffer.</p> +</li> +<li> +<p>The <apostrophe>-x character pair (<tt>"'x"</tt>) shall address the line marked with the mark name character <i>x</i>, +which shall be a lowercase letter from the portable character set. It shall be an error if the character has not been set to mark a +line or if the line that was marked is not currently present in the edit buffer.</p> +</li> +<li> +<p>A BRE enclosed by <slash> characters (<tt>'/'</tt>) shall address the first line found by searching forwards from the line +following the current line toward the end of the edit buffer and stopping at the first line for which the line excluding the +terminating <newline> matches the BRE. The BRE consisting of a null BRE delimited by a pair of <slash> characters shall +address the next line for which the line excluding the terminating <newline> matches the last BRE encountered. In addition, +the second <slash> can be omitted at the end of a command line. Within the BRE, a <backslash>-<slash> pair +(<tt>"\/"</tt>) shall represent a literal <slash> instead of the BRE delimiter. If necessary, the search shall wrap around to +the beginning of the buffer and continue up to and including the current line, so that the entire buffer is searched.</p> +</li> +<li> +<p>A BRE enclosed by <question-mark> characters (<tt>'?'</tt>) shall address the first line found by searching backwards from +the line preceding the current line toward the beginning of the edit buffer and stopping at the first line for which the line +excluding the terminating <newline> matches the BRE. The BRE consisting of a null BRE delimited by a pair of +<question-mark> characters (<tt>"??"</tt>) shall address the previous line for which the line excluding the terminating +<newline> matches the last BRE encountered. In addition, the second <question-mark> can be omitted at the end of a +command line. Within the BRE, a <backslash>-<question-mark> pair (<tt>"\?"</tt>) shall represent a literal +<question-mark> instead of the BRE delimiter. If necessary, the search shall wrap around to the end of the buffer and +continue up to and including the current line, so that the entire buffer is searched.</p> +</li> +<li> +<p>A <plus-sign> (<tt>'+'</tt>) or <hyphen-minus> character (<tt>'-'</tt>) followed by a decimal number shall address +the current line plus or minus the number. A <plus-sign> or <hyphen-minus> character not followed by a decimal number +shall address the current line plus or minus 1.</p> +</li> +</ol> +<p>Addresses can be followed by zero or more address offsets, optionally <blank>-separated. Address offsets are constructed +as follows:</p> +<ul> +<li> +<p>A <plus-sign> or <hyphen-minus> character followed by a decimal number shall add or subtract, respectively, the +indicated number of lines to or from the address. A <plus-sign> or <hyphen-minus> character not followed by a decimal +number shall add or subtract 1 to or from the address.</p> +</li> +<li> +<p>A decimal number shall add the indicated number of lines to the address.</p> +</li> +</ul> +<p>It shall not be an error for an intermediate address value to be less than zero or greater than the last line in the edit +buffer. It shall be an error for the final address value to be less than zero or greater than the last line in the edit buffer. It +shall be an error if a search for a BRE fails to find a matching line.</p> +<p>Commands accept zero, one, or two addresses. If one or more addresses are provided to a command that requires zero addresses, it +shall be an error. Otherwise, if more than the maximum number of accepted addresses are provided to a command, the addresses shall +be evaluated from first to last and then discarded, until the maximum number of accepted addresses for that command remain.</p> +<p>Addresses shall be separated from each other by a <comma> (<tt>','</tt>) or <semicolon> character (<tt>';'</tt>). In +the case of a <semicolon> separator, the current line (<tt>'.'</tt>) shall be set to the first address, and only then shall +the second address be calculated. This feature can be used to determine the starting line for forwards and backwards searches; see +rules 5. and 6.</p> +<p>Addresses can be omitted on either side of the <comma> or <semicolon> separator, in which case the resulting address +pairs shall be as follows:</p> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Specified</b></p> +</th> +<th align="center"> +<p class="tent"><b>Resulting</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">,</p> +</td> +<td align="left"> +<p class="tent">1 , $</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">, addr</p> +</td> +<td align="left"> +<p class="tent">1 , addr</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">addr ,</p> +</td> +<td align="left"> +<p class="tent">addr , addr</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">;</p> +</td> +<td align="left"> +<p class="tent">. ; $</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">; addr</p> +</td> +<td align="left"> +<p class="tent">. ; addr</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">addr ;</p> +</td> +<td align="left"> +<p class="tent">addr ; addr</p> +</td> +</tr> +</table> +</center> +<p class="tent">If an address is omitted between two separators, the rule shall be applied to the first separator and the resulting +second address shall be used as the first address for the second separator. For example, with the address list <tt>",,"</tt> the +first <tt>','</tt> becomes <tt>"1,$"</tt> and the <tt>'$'</tt> is treated as the first address for the second <tt>','</tt>, +resulting in <tt>"1,$,$"</tt>.</p> +<p class="tent">Any <blank> characters included between addresses, address separators, or address offsets shall be +ignored.</p> +<h5><a name="tag_20_38_13_03" id="tag_20_38_13_03"></a>Commands in ed</h5> +<p class="tent">In the following list of <i>ed</i> commands, the default addresses are shown in parentheses. The number of +addresses shown in the default shall be the number expected by the command. The parentheses are not part of the address; they show +that the given addresses are the default.</p> +<p class="tent">It is generally invalid for more than one command to appear on a line. However, any command (except <b>e</b>, +<b>E</b>, <b>f</b>, <b>q</b>, <b>Q</b>, <b>r</b>, <b>w</b>, and <b>!</b>) can be suffixed by the letter <b>l</b>, <b>n</b>, or +<b>p</b>; in which case, except for the <b>l</b>, <b>n</b>, and <b>p</b> commands, the command shall be executed and then the new +current line shall be written as described below under the <b>l</b>, <b>n</b>, and <b>p</b> commands. When an <b>l</b>, <b>n</b>, +or <b>p</b> suffix is used with an <b>l</b>, <b>n</b>, or <b>p</b> command, the command shall write to standard output as described +below, but it is unspecified whether the suffix writes the current line again in the requested format or whether the suffix has no +effect. For example, the <b>pl</b> command (base <b>p</b> command with an <b>l</b> suffix) shall either write just the current line +or write it twice—once as specified for <b>p</b> and once as specified for <b>l</b>. Also, the <b>g</b>, <b>G</b>, <b>v</b>, and +<b>V</b> commands shall take a command as a parameter.</p> +<p class="tent">Each address component can be preceded by zero or more <blank> characters. The command letter can be preceded +by zero or more <blank> characters. If a suffix letter (<b>l</b>, <b>n</b>, or <b>p</b>) is given, the application shall +ensure that it immediately follows the command.</p> +<p class="tent">The <b>e</b>, <b>E</b>, <b>f</b>, <b>r</b>, and <b>w</b> commands shall take an optional <i>file</i> parameter, +separated from the command letter by one or more <blank> characters.</p> +<p class="tent">If the buffer change flag is currently set to <b>changed</b>, <i>ed</i> shall warn the user if an attempt is made +to destroy the editor buffer via the <b>e</b> or <b>q</b> commands. The <i>ed</i> utility shall write the string:</p> +<pre> +<tt>"?\n" +</tt></pre> +<p class="tent">(followed by an explanatory message if <i>help mode</i> has been enabled via the <b>H</b> command) to standard +output and shall continue in command mode with the buffer change flag set to either <b>changed-and-warned</b> or <b>unchanged</b> +and the current line number unchanged. If another <b>e</b> or <b>q</b> command is then attempted with no intervening command that +sets the buffer change flag to <b>changed</b>, it shall take effect.</p> +<p class="tent">If a terminal disconnect (see XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal +Interface</i></a> , Modem Disconnect and Closing a Device Terminal), is detected:</p> +<ul> +<li class="tent">If accompanied by a SIGHUP signal, the <i>ed</i> utility shall operate as described in the ASYNCHRONOUS EVENTS +section for a SIGHUP signal.</li> +<li class="tent">If not accompanied by a SIGHUP signal, the <i>ed</i> utility shall act as if an end-of-file had been detected on +standard input.</li> +</ul> +<p class="tent">If an end-of-file is detected on standard input:</p> +<ul> +<li class="tent">If the <i>ed</i> utility is in input mode, <i>ed</i> shall terminate input mode and return to command mode. It is +unspecified if any partially entered lines (that is, input text without a terminating <newline>) are discarded from the input +text.</li> +<li class="tent">If the <i>ed</i> utility is in command mode, it shall act as if a <b>q</b> command had been entered.</li> +</ul> +<p class="tent">In the following commands, if a closing delimiter would be the last character before a <newline> then that +character can be omitted with the behavior shown:</p> +<ul> +<li class="tent">For the <b>g</b> and <b>v</b> commands the addressed line(s) shall be written as if a closing delimiter followed +by a <b>p</b> were appended to the command.</li> +<li class="tent">For the <b>G</b> and <b>V</b> commands no additional action shall be taken.</li> +<li class="tent">For the <b>s</b> command, only the closing delimiter of the replacement can be omitted, in which case the result +of the substitution shall be written as if the <b>p</b> flag were appended.</li> +<li class="tent">For the null command, the addressed line(s) shall be written as if the closing delimiter were appended.</li> +</ul> +<p class="tent">For example, the following pairs of commands are equivalent:</p> +<pre> +<tt>s/s1/s2 s/s1/s2/p +g/s1 g/s1/p +?s1 ?s1? +</tt></pre> +<p class="tent">If an invalid command is entered, <i>ed</i> shall write the string:</p> +<pre> +<tt>"?\n" +</tt></pre> +<p class="tent">(followed by an explanatory message if <i>help mode</i> has been enabled via the <b>H</b> command) to standard +output and shall continue in command mode with the current line number unchanged.</p> +<h5><a name="tag_20_38_13_04" id="tag_20_38_13_04"></a>Append Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>(.)a +<</tt><i>text</i><tt>> +. +</tt></pre></dd> +</dl> +<p class="tent">The <b>a</b> command shall read the given text and append it after the addressed line; the current line number +shall become the address of the last inserted line or, if there were none, the addressed line. Address 0 shall be valid for this +command; it shall cause the appended text to be placed at the beginning of the buffer. If <<i>text</i>> is empty (that is, +the terminating <tt>'.'</tt> immediately follows the <tt>'a'</tt>), the buffer change flag shall not be altered.</p> +<h5><a name="tag_20_38_13_05" id="tag_20_38_13_05"></a>Change Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>(.,.)c +<</tt><i>text</i><tt>> +. +</tt></pre></dd> +</dl> +<p class="tent">The <b>c</b> command shall delete the addressed lines, then accept input text that replaces these lines; the +current line shall be set to the address of the last line input; or, if there were none, at the line after the last line deleted; +if the lines deleted were originally at the end of the buffer, the current line number shall be set to the address of the new last +line; if no lines remain in the buffer, the current line number shall be set to zero.</p> +<h5><a name="tag_20_38_13_06" id="tag_20_38_13_06"></a>Delete Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>(.,.)d +</tt></pre></dd> +</dl> +<p class="tent">The <b>d</b> command shall delete the addressed lines from the buffer. The address of the line after the last line +deleted shall become the current line number; if the lines deleted were originally at the end of the buffer, the current line +number shall be set to the address of the new last line; if no lines remain in the buffer, the current line number shall be set to +zero.</p> +<h5><a name="tag_20_38_13_07" id="tag_20_38_13_07"></a>Edit Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>e </tt><b>[</b><i>file</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">The <b>e</b> command shall delete the entire contents of the buffer and then read in the file named by the pathname +<i>file</i>. The current line number shall be set to the address of the last line of the buffer. If no pathname is given, the +currently remembered pathname, if any, shall be used (see the <b>f</b> command). If the pathname names a file that does not exist +and the buffer change flag is currently set to <b>unchanged</b>, it is unspecified whether this is treated as an error, or whether +the resulting buffer is emptied and a warning is written to standard error instead of writing the byte count to standard out. The +number of bytes read shall be written to standard output, unless the <b>-s</b> option was specified, in the following format:</p> +<pre> +<tt>"%d\n", <</tt><i>number of bytes read</i><tt>> +</tt></pre> +<p class="tent">The name <i>file</i> shall be remembered for possible use as a default pathname in subsequent <b>e</b>, <b>E</b>, +<b>r</b>, and <b>w</b> commands. If <i>file</i> is replaced by <tt>'!'</tt>, the rest of the line shall be taken to be a shell +command line whose output is to be read. Such a shell command line shall not be remembered as the current <i>file</i>. All marks +shall be discarded upon the completion of a successful <b>e</b> command. If the buffer change flag is currently set to +<b>changed</b>, the user shall be warned, as described previously.</p> +<h5><a name="tag_20_38_13_08" id="tag_20_38_13_08"></a>Edit Without Checking Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>E </tt><b>[</b><i>file</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">The <b>E</b> command shall possess all properties and restrictions of the <b>e</b> command except that the editor +shall not check the current state of the buffer change flag.</p> +<h5><a name="tag_20_38_13_09" id="tag_20_38_13_09"></a>Filename Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>f </tt><b>[</b><i>file</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">If <i>file</i> is given, the <b>f</b> command shall change the currently remembered pathname to <i>file</i>, +whether or not <i>file</i> names an existing file; whether the name is changed or not, it shall then write the (possibly new) +currently remembered pathname to the standard output in the following format:</p> +<pre> +<tt>"%s\n", <</tt><i>pathname</i><tt>> +</tt></pre> +<p class="tent">The current line number shall be unchanged.</p> +<h5><a name="tag_20_38_13_10" id="tag_20_38_13_10"></a>Global Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>(1,$)g/</tt><i>RE</i><tt>/</tt><i>command list</i><tt> +</tt></pre></dd> +</dl> +<p class="tent">In the <b>g</b> command, the first step shall be to mark every line for which the line excluding the terminating +<newline> matches the given RE. Then, going sequentially from the beginning of the file to the end of the file, the given +<i>command list</i> shall be executed for each marked line, with the current line number set to the address of that line. Any line +modified by the <i>command list</i> shall be unmarked. When the <b>g</b> command completes, the current line number shall have the +value assigned by the last command in the <i>command list</i>. If there were no matching lines, the current line number shall not +be changed. A single command or the first of a list of commands shall appear on the same line as the global command. All lines of a +multi-line list except the last line shall be ended with a <backslash> preceding the terminating <newline>; the +<b>a</b>, <b>i</b>, and <b>c</b> commands and associated input are permitted. The <tt>'.'</tt> terminating input mode can be +omitted if it would be the last line of the <i>command list</i>. An empty <i>command list</i> shall be equivalent to the <b>p</b> +command. The use of the <b>g</b>, <b>G</b>, <b>v</b>, <b>V</b>, and <b>!</b> commands in the <i>command list</i> produces undefined +results. Any character other than <backslash>, <space>, or <newline> can be used instead of a <slash> to +delimit the RE. Within the RE, in certain circumstances the RE delimiter can be used as a literal character; see <a href= +"#tag_20_38_13_01">Regular Expressions in ed</a> .</p> +<h5><a name="tag_20_38_13_11" id="tag_20_38_13_11"></a>Interactive Global Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>(1,$)G/</tt><i>RE</i><tt>/ +</tt></pre></dd> +</dl> +<p class="tent">In the <b>G</b> command, the first step shall be to mark every line for which the line excluding the terminating +<newline> matches the given RE. Then, for every such line, that line shall be written, the current line number shall be set +to the address of that line, and any one command (other than one of the <b>a</b>, <b>c</b>, <b>i</b>, <b>g</b>, <b>G</b>, <b>v</b>, +and <b>V</b> commands) shall be read and executed. A <newline> shall act as a null command (causing no action to be taken on +the current line); an <tt>'&'</tt> shall cause the re-execution of the most recent non-null command executed within the current +invocation of <b>G</b>. Note that the commands input as part of the execution of the <b>G</b> command can address and affect any +lines in the buffer. Any line modified by the command shall be unmarked. The final value of the current line number shall be the +value set by the last command successfully executed. (Note that the last command successfully executed shall be the <b>G</b> +command itself if a command fails or the null command is specified.) If there were no matching lines, the current line number shall +not be changed. The <b>G</b> command can be terminated by a SIGINT signal. Any character other than <backslash>, +<space>, or <newline> can be used instead of a <slash> to delimit the RE. Within the RE, in certain circumstances +the RE delimiter can be used as a literal character; see <a href="#tag_20_38_13_01">Regular Expressions in ed</a> .</p> +<h5><a name="tag_20_38_13_12" id="tag_20_38_13_12"></a>Help Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>h +</tt></pre></dd> +</dl> +<p class="tent">The <b>h</b> command shall write a short message to standard output that explains the reason for the most recent +<tt>'?'</tt> notification. The current line number shall be unchanged.</p> +<h5><a name="tag_20_38_13_13" id="tag_20_38_13_13"></a>Help-Mode Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>H +</tt></pre></dd> +</dl> +<p class="tent">The <b>H</b> command shall cause <i>ed</i> to enter a mode in which help messages (see the <b>h</b> command) shall +be written to standard output for all subsequent <tt>'?'</tt> notifications. The <b>H</b> command alternately shall turn this mode +on and off; it is initially off. If the help-mode is being turned on, the <b>H</b> command also explains the previous <tt>'?'</tt> +notification, if there was one. The current line number shall be unchanged.</p> +<h5><a name="tag_20_38_13_14" id="tag_20_38_13_14"></a>Insert Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>(.)i +<</tt><i>text</i><tt>> +. +</tt></pre></dd> +</dl> +<p class="tent">The <b>i</b> command shall insert the given text before the addressed line; the current line is set to the last +inserted line or, if there was none, to the addressed line. This command differs from the <b>a</b> command only in the placement of +the input text. Address 0 shall be valid for this command; it is unspecified whether it causes the inserted text to be placed at +the beginning of the buffer or it is interpreted as if address 1 were specified. (These two allowed behaviors differ in the case +that the buffer is empty.) If <<i>text</i>> is empty (that is, the terminating <tt>'.'</tt> immediately follows the +<tt>'i'</tt>), the buffer change flag shall not be altered.</p> +<h5><a name="tag_20_38_13_15" id="tag_20_38_13_15"></a>Join Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>(.,.+1)j +</tt></pre></dd> +</dl> +<p class="tent">The <b>j</b> command shall join contiguous lines by removing the appropriate <newline> characters. If exactly +one address is given, this command shall do nothing. If lines are joined, the current line number shall be set to the address of +the joined line; otherwise, the current line number shall be unchanged.</p> +<h5><a name="tag_20_38_13_16" id="tag_20_38_13_16"></a>Mark Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>(.)k</tt><i>x</i><tt> +</tt></pre></dd> +</dl> +<p class="tent">The <b>k</b> command shall mark the addressed line with name <i>x</i>, which the application shall ensure is a +lowercase letter from the portable character set. The address <tt>"'x"</tt> shall then refer to this line; the current line number +shall be unchanged.</p> +<h5><a name="tag_20_38_13_17" id="tag_20_38_13_17"></a>List Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>(.,.)l +</tt></pre></dd> +</dl> +<p class="tent">The <b>l</b> command shall write to standard output the addressed lines in a visually unambiguous form. The +characters listed in XBD <a href="../basedefs/V1_chap05.html#tagtcjh_2"><i>Escape Sequences and Associated Actions</i></a> +(<tt>'\\'</tt>, <tt>'\a'</tt>, <tt>'\b'</tt>, <tt>'\f'</tt>, <tt>'\r'</tt>, <tt>'\t'</tt>, <tt>'\v'</tt>) shall be written as the +corresponding escape sequence; the <tt>'\n'</tt> in that table is not applicable. Non-printable characters not in the table shall +be written as one three-digit octal number (with a preceding <backslash> character) for each byte in the character (most +significant byte first).</p> +<p class="tent">Long lines shall be folded, with the point of folding indicated by <newline> preceded by a <backslash>; +the length at which folding occurs is unspecified, but should be appropriate for the output device. The end of each line shall be +marked with a <tt>'$'</tt>, and <tt>'$'</tt> characters within the text shall be written with a preceding <backslash>. An +<b>l</b> command can be appended to any other command other than <b>e</b>, <b>E</b>, <b>f</b>, <b>q</b>, <b>Q</b>, <b>r</b>, +<b>w</b>, or <b>!</b>. The current line number shall be set to the address of the last line written.</p> +<h5><a name="tag_20_38_13_18" id="tag_20_38_13_18"></a>Move Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>(.,.)m</tt><i>address</i><tt> +</tt></pre></dd> +</dl> +<p class="tent">The <b>m</b> command shall reposition the addressed lines after the line addressed by <i>address</i>. Address 0 +shall be valid for <i>address</i> and cause the addressed lines to be moved to the beginning of the buffer. It shall be an error if +address <i>address</i> falls within the range of moved lines. The current line number shall be set to the address of the last line +moved.</p> +<h5><a name="tag_20_38_13_19" id="tag_20_38_13_19"></a>Number Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>(.,.)n +</tt></pre></dd> +</dl> +<p class="tent">The <b>n</b> command shall write to standard output the addressed lines, preceding each line by its line number and +a <tab>; the current line number shall be set to the address of the last line written. The <b>n</b> command can be appended +to any command other than <b>e</b>, <b>E</b>, <b>f</b>, <b>q</b>, <b>Q</b>, <b>r</b>, <b>w</b>, or <b>!</b>.</p> +<h5><a name="tag_20_38_13_20" id="tag_20_38_13_20"></a>Print Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>(.,.)p +</tt></pre></dd> +</dl> +<p class="tent">The <b>p</b> command shall write to standard output the addressed lines; the current line number shall be set to +the address of the last line written. The <b>p</b> command can be appended to any command other than <b>e</b>, <b>E</b>, <b>f</b>, +<b>q</b>, <b>Q</b>, <b>r</b>, <b>w</b>, or <b>!</b>.</p> +<h5><a name="tag_20_38_13_21" id="tag_20_38_13_21"></a>Prompt Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>P +</tt></pre></dd> +</dl> +<p class="tent">The <b>P</b> command shall cause <i>ed</i> to prompt with an <asterisk> (<tt>'*'</tt>) (or <i>string</i>, if +<b>-p</b> is specified) for all subsequent commands. The <b>P</b> command alternatively shall turn this mode on and off; it shall +be initially on if the <b>-p</b> option is specified; otherwise, off. The current line number shall be unchanged.</p> +<h5><a name="tag_20_38_13_22" id="tag_20_38_13_22"></a>Quit Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>q +</tt></pre></dd> +</dl> +<p class="tent">The <b>q</b> command shall cause <i>ed</i> to exit. If the buffer change flag is currently set to <b>changed</b>, +the user shall be warned, as described previously.</p> +<h5><a name="tag_20_38_13_23" id="tag_20_38_13_23"></a>Quit Without Checking Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>Q +</tt></pre></dd> +</dl> +<p class="tent">The <b>Q</b> command shall cause <i>ed</i> to exit without checking the current state of the buffer change +flag.</p> +<h5><a name="tag_20_38_13_24" id="tag_20_38_13_24"></a>Read Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>($)r</tt><b> [</b><i>file</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">The <b>r</b> command shall read in the file named by the pathname <i>file</i> and append it after the addressed +line. If no <i>file</i> argument is given, the currently remembered pathname, if any, shall be used (see the <b>e</b> and <b>f</b> +commands). The currently remembered pathname shall not be changed unless there is no remembered pathname. Address 0 shall be valid +for <b>r</b> and shall cause the file to be read at the beginning of the buffer. If the read is successful, and <b>-s</b> was not +specified, the number of bytes read shall be written to standard output in the following format:</p> +<pre> +<tt>"%d\n", <</tt><i>number of bytes read</i><tt>> +</tt></pre> +<p class="tent">The current line number shall be set to the address of the last line read in. If <i>file</i> is replaced by +<tt>'!'</tt>, the rest of the line shall be taken to be a shell command line whose output is to be read. Such a shell command line +shall not be remembered as the current pathname.</p> +<p class="tent">If the number of bytes read is 0 it is unspecified whether the buffer change flag is set to <b>changed</b> or left +unaltered.</p> +<h5><a name="tag_20_38_13_25" id="tag_20_38_13_25"></a>Substitute Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>(.,.)s/</tt><i>RE</i><tt>/</tt><i>replacement</i><tt>/</tt><i>flags</i><tt> +</tt></pre></dd> +</dl> +<p class="tent">The <b>s</b> command shall search each addressed line for an occurrence of the specified RE and replace either the +first or all (non-overlapped) matched strings with the <i>replacement</i>; see the following description of the <b>g</b> suffix. +Any character other than <backslash>, <space>, or <newline> can be used instead of a <slash> to delimit the +RE and the replacement. Within the RE, in certain circumstances the RE delimiter can be used as a literal character; see <a href= +"#tag_20_38_13_01">Regular Expressions in ed</a> . Within the replacement, the delimiter shall not terminate the replacement if it +is the second character of an escape sequence (see XBD <a href="../basedefs/V1_chap09.html#tag_09_01"><i>9.1 Regular Expression +Definitions</i></a> ) and the escaped delimiter shall be treated as that literal character in the replacement (losing any special +meaning it would have had if it was not used as the delimiter and was not escaped). It shall be an error if the substitution fails +on every addressed line. The current line shall be set to the address of the last line on which a substitution occurred.</p> +<p class="tent">An unescaped <ampersand> (<tt>'&'</tt>) appearing in the replacement shall be replaced by the string +matching the RE on the current line. As a more general feature, the characters <tt>'\n'</tt>, where the <backslash> is +unescaped and <i>n</i> is a digit, shall be replaced by the text matched by the corresponding back-reference expression. If the +corresponding back-reference expression does not match, then the characters <tt>'\n'</tt> shall be replaced by the empty string. +When the character <tt>'%'</tt> is the only character in <i>replacement</i>, the <i>replacement</i> used in the most recent +substitute command shall be used as <i>replacement</i> in the current substitute command; if there was no previous substitute +command, the use of <tt>'%'</tt> in this manner shall be an error. The <tt>'%'</tt> shall lose its special meaning when it is in a +replacement string of more than one character or is escaped. It is unspecified what special meaning is given to any character other +than <backslash>, <tt>'&'</tt>, <tt>'%'</tt>, or digits.</p> +<p class="tent">A line can be split by substituting a <newline> into it. The application shall ensure it escapes the +<newline> in the <i>replacement</i> by preceding it by <backslash>. Such substitution cannot be done as part of a +<b>g</b> or <b>v</b> <i>command list</i>. The current line number shall be set to the address of the last line on which a +substitution is performed. If no substitution is performed, the current line number shall be unchanged. If a line is split, a +substitution shall be considered to have been performed on each of the new lines for the purpose of determining the new current +line number. A substitution shall be considered to have been performed even if the replacement string is identical to the string +that it replaces.</p> +<p class="tent">The application shall ensure that the value of <i>flags</i> is zero or more of:</p> +<dl compact> +<dd></dd> +<dt><i>count</i></dt> +<dd>Substitute for the <i>count</i>th occurrence only of the RE found on each addressed line.</dd> +<dt><b>g</b></dt> +<dd>Globally substitute for all non-overlapping instances of the RE rather than just the first one. If both <b>g</b> and +<i>count</i> are specified, the results are unspecified.</dd> +<dt><b>l</b></dt> +<dd>Write to standard output the final line in which a substitution was made. The line shall be written in the format specified for +the <b>l</b> command.</dd> +<dt><b>n</b></dt> +<dd>Write to standard output the final line in which a substitution was made. The line shall be written in the format specified for +the <b>n</b> command.</dd> +<dt><b>p</b></dt> +<dd>Write to standard output the final line in which a substitution was made. The line shall be written in the format specified for +the <b>p</b> command.</dd> +</dl> +<h5><a name="tag_20_38_13_26" id="tag_20_38_13_26"></a>Copy Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>(.,.)t</tt><i>address</i><tt> +</tt></pre></dd> +</dl> +<p class="tent">The <b>t</b> command shall be equivalent to the <b>m</b> command, except that a copy of the addressed lines shall +be placed after address <i>address</i> (which can be 0); the current line number shall be set to the address of the last line +added.</p> +<h5><a name="tag_20_38_13_27" id="tag_20_38_13_27"></a>Undo Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>u +</tt></pre></dd> +</dl> +<p class="tent">The <b>u</b> command shall nullify the effect of the most recent command that modified anything in the buffer, +namely the most recent <b>a</b>, <b>c</b>, <b>d</b>, <b>g</b>, <b>i</b>, <b>j</b>, <b>m</b>, <b>r</b>, <b>s</b>, <b>t</b>, +<b>u</b>, <b>v</b>, <b>G</b>, or <b>V</b> command. All changes made to the buffer by a <b>g</b>, <b>G</b>, <b>v</b>, or <b>V</b> +global command shall be undone as a single change; if no changes were made by the global command (such as with +<b>g</b>/RE/<b>p</b>), the <b>u</b> command shall have no effect. The current line number shall be set to the value it had +immediately before the command being undone started.</p> +<h5><a name="tag_20_38_13_28" id="tag_20_38_13_28"></a>Global Non-Matched Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>(1,$)v/</tt><i>RE</i><tt>/</tt><i>command list</i><tt> +</tt></pre></dd> +</dl> +<p class="tent">This command shall be equivalent to the global command <b>g</b> except that the lines that are marked during the +first step shall be those for which the line excluding the terminating <newline> does not match the RE.</p> +<h5><a name="tag_20_38_13_29" id="tag_20_38_13_29"></a>Interactive Global Not-Matched Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>(1,$)V/</tt><i>RE</i><tt>/ +</tt></pre></dd> +</dl> +<p class="tent">This command shall be equivalent to the interactive global command <b>G</b> except that the lines that are marked +during the first step shall be those for which the line excluding the terminating <newline> does not match the RE.</p> +<h5><a name="tag_20_38_13_30" id="tag_20_38_13_30"></a>Write Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>(1,$)w</tt><b> [</b><i>file</i><b>] +</b></pre></dd> +</dl> +<p class="tent">The <b>w</b> command shall write the addressed lines into the file named by the pathname <i>file</i>. The command +shall create the file, if it does not exist, or shall replace the contents of the existing file. The currently remembered pathname +shall not be changed unless there is no remembered pathname. If no pathname is given, the currently remembered pathname, if any, +shall be used (see the <b>e</b> and <b>f</b> commands); the current line number shall be unchanged. If the command is successful, +the number of bytes written shall be written to standard output, unless the <b>-s</b> option was specified, in the following +format:</p> +<pre> +<tt>"%d\n", <</tt><i>number of bytes written</i><tt>> +</tt></pre> +<p class="tent">If <i>file</i> begins with <tt>'!'</tt>, the rest of the line shall be taken to be a shell command line whose +standard input shall be the addressed lines. Such a shell command line shall not be remembered as the current pathname. This usage +of the <b>w</b> command with <tt>'!'</tt> shall not alter the buffer change flag; thus, this alone shall not prevent the warning to +the user if an attempt is made to destroy the editor buffer via the <b>e</b> or <b>q</b> commands.</p> +<h5><a name="tag_20_38_13_31" id="tag_20_38_13_31"></a>Line Number Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>($)= +</tt></pre></dd> +</dl> +<p class="tent">The line number of the addressed line shall be written to standard output in the following format:</p> +<pre> +<tt>"%d\n", <</tt><i>line number</i><tt>> +</tt></pre> +<p class="tent">The current line number shall be unchanged by this command.</p> +<h5><a name="tag_20_38_13_32" id="tag_20_38_13_32"></a>Shell Escape Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>!</tt><i>command</i><tt> +</tt></pre></dd> +</dl> +<p class="tent">The remainder of the line after the <tt>'!'</tt> shall be sent to the command interpreter to be interpreted as a +shell command line. Within the text of that shell command line, the unescaped character <tt>'%'</tt> shall be replaced with the +remembered pathname; if a <tt>'!'</tt> appears as the first character of the command, it shall be replaced with the text of the +previous shell command executed via <tt>'!'</tt>. Thus, <tt>"!!"</tt> shall repeat the previous !<i>command</i>. If any +replacements of <tt>'%'</tt> or <tt>'!'</tt> are performed, the modified line shall be written to the standard output before +<i>command</i> is executed. The <b>!</b> command shall write:</p> +<pre> +<tt>"!\n" +</tt></pre> +<p class="tent">to standard output upon completion, unless the <b>-s</b> option is specified. The current line number shall be +unchanged.</p> +<h5><a name="tag_20_38_13_33" id="tag_20_38_13_33"></a>Null Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>(.+1) +</tt></pre></dd> +</dl> +<p class="tent">An address alone on a line shall cause the addressed line to be written. A <newline> alone shall be +equivalent to <tt>"+1p"</tt>. The current line number shall be set to the address of the written line.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_38_14" id="tag_20_38_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion without any file or command errors.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_38_15" id="tag_20_38_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>When an error in the input script is encountered, or when an error is detected that is a consequence of the data (not) present +in the file or due to an external condition such as a read or write error:</p> +<ul> +<li class="tent">If the standard input is a terminal device file, all input shall be flushed, and a new command read.</li> +<li class="tent">If the standard input is not a terminal device file, <i>ed</i> shall behave as described under CONSEQUENCES OF +ERRORS in <a href="../utilities/V3_chap01.html#tag_18_04"><i>1.4 Utility Description Defaults</i></a> .</li> +</ul> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_38_16" id="tag_20_38_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Because of the extremely terse nature of the default error messages, the prudent script writer begins the <i>ed</i> input +commands with an <b>H</b> command, so that if any errors do occur at least some clue as to the cause is made available.</p> +<p class="tent">In earlier versions of this standard, an obsolescent <b>-</b> option was described. This is no longer specified. +Applications should use the <b>-s</b> option. Using <b>-</b> as a <i>file</i> operand now produces unspecified results. This allows +implementations to continue to support the former required behavior.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_38_17" id="tag_20_38_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_38_18" id="tag_20_38_18"></a>RATIONALE</h4> +<blockquote> +<p>The initial description of this utility was adapted from the SVID. It contains some features not found in Version 7 or +BSD-derived systems. Some of the differences between the POSIX and BSD <i>ed</i> utilities include, but need not be limited to:</p> +<ul> +<li class="tent">The BSD <b>-</b> option does not suppress the <tt>'!'</tt> prompt after a <b>!</b> command.</li> +<li class="tent">BSD does not support the special meanings of the <tt>'%'</tt> and <tt>'!'</tt> characters within a <b>!</b> +command.</li> +<li class="tent">BSD does not support the <i>addresses</i> <tt>';'</tt> and <tt>','</tt>.</li> +<li class="tent">BSD allows the command/suffix pairs <b>pp</b>, <b>ll</b>, and so on, which are unspecified in this volume of +POSIX.1-2024.</li> +<li class="tent">BSD does not support the <tt>'!'</tt> character part of the <b>e</b>, <b>r</b>, or <b>w</b> commands.</li> +<li class="tent">A failed <b>g</b> command in BSD sets the line number to the last line searched if there are no matches.</li> +<li class="tent">BSD does not default the <i>command list</i> to the <b>p</b> command.</li> +<li class="tent">BSD does not support the <b>G</b>, <b>h</b>, <b>H</b>, <b>n</b>, or <b>V</b> commands.</li> +<li class="tent">On BSD, if there is no inserted text, the insert command changes the current line to the referenced line -1; that +is, the line before the specified line.</li> +<li class="tent">On BSD, the <b>j</b> command with only a single address changes the current line to that address.</li> +<li class="tent">BSD does not support the <b>P</b> command; moreover, in BSD it is synonymous with the <b>p</b> command.</li> +<li class="tent">BSD does not support the <i>undo</i> of the commands <b>j</b>, <b>m</b>, <b>r</b>, <b>s</b>, or <b>t</b>.</li> +<li class="tent">The Version 7 <i>ed</i> command <b>W</b>, and the BSD <i>ed</i> commands <b>W</b>, <b>wq</b>, and <b>z</b> are not +present in this volume of POSIX.1-2024.</li> +</ul> +<p class="tent">The <b>-s</b> option was added to allow the functionality of the removed <b>-</b> option in a manner compatible +with the Utility Syntax Guidelines.</p> +<p class="tent">In early proposals there was a limit, {ED_FILE_MAX}, that described the historical limitations of some <i>ed</i> +utilities in their handling of large files; some of these have had problems with files larger than 100000 bytes. It was this +limitation that prompted much of the desire to include a <a href="../utilities/split.html"><i>split</i></a> command in this volume +of POSIX.1-2024. Since this limit was removed, this volume of POSIX.1-2024 requires that implementations document the file size +limits imposed by <i>ed</i> in the conformance document. The limit {ED_LINE_MAX} was also removed; therefore, the global limit +{LINE_MAX} is used for input and output lines.</p> +<p class="tent">The manner in which the <b>l</b> command writes non-printable characters was changed to avoid the historical +backspace-overstrike method. On video display terminals, the overstrike is ambiguous because most terminals simply replace +overstruck characters, making the <b>l</b> format not useful for its intended purpose of unambiguously understanding the content of +the line. The historical <backslash>-escapes were also ambiguous. (The string <tt>"a\0011"</tt> could represent a line +containing those six characters or a line containing the three characters <tt>'a'</tt>, a byte with a binary value of 1, and a 1.) +In the format required here, a <backslash> appearing in the line is written as <tt>"\\"</tt> so that the output is truly +unambiguous. The method of marking the ends of lines was adopted from the <a href="../utilities/ex.html"><i>ex</i></a> editor and +is required for any line ending in <space> characters; the <tt>'$'</tt> is placed on all lines so that a real <tt>'$'</tt> at +the end of a line cannot be misinterpreted.</p> +<p class="tent">Earlier versions of this standard allowed for implementations with bytes other than eight bits, but this has been +modified in this version.</p> +<p class="tent">The description of how a NUL is written was removed. The NUL character cannot be in text files, and this volume of +POSIX.1-2024 should not dictate behavior in the case of undefined, erroneous input.</p> +<p class="tent">Unlike some of the other editing utilities, the filenames accepted by the <b>E</b>, <b>e</b>, <b>R</b>, and +<b>r</b> commands are not patterns.</p> +<p class="tent">Early proposals stated that the <b>-p</b> option worked only when standard input was associated with a terminal +device. This has been changed to conform to historical implementations, thereby allowing applications to interpose themselves +between a user and the <i>ed</i> utility.</p> +<p class="tent">The form of the substitute command that uses the <b>n</b> suffix was limited in some historical documentation +(where this was described incorrectly as "backreferencing"). This limit has been omitted because there is no reason why an editor +processing lines of {LINE_MAX} length should have this restriction. The command <b>s/x/X/2047</b> should be able to substitute the +2047th occurrence of <tt>'x'</tt> on a line.</p> +<p class="tent">The use of printing commands with printing suffixes (such as <b>pn</b>, <b>lp</b>, and so on) was made unspecified +because BSD-based systems allow this, whereas System V does not.</p> +<p class="tent">Some BSD-based systems exit immediately upon receipt of end-of-file if all of the lines in the file have been +deleted. Since this volume of POSIX.1-2024 refers to the <b>q</b> command in this instance, such behavior is not allowed.</p> +<p class="tent">Some historical implementations returned exit status zero even if command errors had occurred; this is not allowed +by this volume of POSIX.1-2024.</p> +<p class="tent">Some historical implementations contained a bug that allowed a single <period> to be entered in input mode as +<backslash> <period> <newline>. This is not allowed by <i>ed</i> because there is no description of escaping any +of the characters in input mode; <backslash> characters are entered into the buffer exactly as typed. The typical method of +entering a single <period> has been to precede it with another character and then use the substitute command to delete that +character.</p> +<p class="tent">It is difficult under some modes of some versions of historical operating system terminal drivers to distinguish +between an end-of-file condition and terminal disconnect. POSIX.1-2024 does not require implementations to distinguish between the +two situations, which permits historical implementations of the <i>ed</i> utility on historical platforms to conform. +Implementations are encouraged to distinguish between the two, if possible, and take appropriate action on terminal disconnect.</p> +<p class="tent">Historically, <i>ed</i> accepted a zero address for the <b>a</b> and <b>r</b> commands in order to insert text at +the start of the edit buffer. When the buffer was empty the command <b>.=</b> returned zero. POSIX.1-2024 requires conformance to +historical practice.</p> +<p class="tent">For consistency with the <b>a</b> and <b>r</b> commands and better user functionality, the <b>i</b> command also +accepts an address of 0. However, it is unspecified if <tt>0i</tt> is treated as <tt>1i</tt> (which will fail if the buffer is +empty), or means insert at the beginning of the buffer (which will succeed even if the buffer is empty). Earlier versions of this +standard required address 0 for the <b>c</b> command to be treated as 1 also, but this requirement has been removed, though +implementations are permitted to do this as an extension.</p> +<p class="tent">All of the following are valid addresses:</p> +<dl compact> +<dd></dd> +<dt><tt>+++</tt></dt> +<dd>Three lines after the current line.</dd> +<dt><tt>/</tt><i>pattern</i><tt>/-</tt></dt> +<dd>One line before the next occurrence of pattern.</dd> +<dt><tt>-2</tt></dt> +<dd>Two lines before the current line.</dd> +<dt><tt>3 ---- 2</tt></dt> +<dd>Line one (note the intermediate negative address).</dd> +<dt><tt>1 2 3</tt></dt> +<dd>Line six.</dd> +</dl> +<p class="tent">More than the maximum number of accepted addresses can be provided to commands taking addresses; for example, +<tt>"1,2,3,4,5p"</tt> prints lines 4 and 5, because two is the maximum number of addresses accepted by the <b>print</b> command. +This, in combination with the <semicolon> delimiter, permits users to create commands based on ordered patterns in the file. +For example, the command <tt>"3;/foo/;+2p"</tt> will display the first line after line 3 that contains the pattern <i>foo</i>, plus +the next two lines. Note that the address <tt>"3;"</tt> must still be evaluated before being discarded, because the search origin +for the <tt>"/foo/"</tt> address depends on this.</p> +<p class="tent">Historically, <i>ed</i> disallowed address chains, as discussed above, consisting solely of <comma> or +<semicolon> separators; for example, <tt>",,,"</tt> or <tt>";;;"</tt> were considered an error. For consistency of address +specification, this restriction is removed. The following table lists some of the address forms now possible:</p> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Address</b></p> +</th> +<th align="center"> +<p class="tent"><b>Addr1</b></p> +</th> +<th align="center"> +<p class="tent"><b>Addr2</b></p> +</th> +<th align="center"> +<p class="tent"><b>Status</b></p> +</th> +<th align="center"> +<p class="tent"><b>Comment</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">7,</p> +</td> +<td align="left"> +<p class="tent">7</p> +</td> +<td align="left"> +<p class="tent">7</p> +</td> +<td align="left"> +<p class="tent">Historical</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">7,5,</p> +</td> +<td align="left"> +<p class="tent">5</p> +</td> +<td align="left"> +<p class="tent">5</p> +</td> +<td align="left"> +<p class="tent">Historical</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">7,5,9</p> +</td> +<td align="left"> +<p class="tent">5</p> +</td> +<td align="left"> +<p class="tent">9</p> +</td> +<td align="left"> +<p class="tent">Historical</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">7,9</p> +</td> +<td align="left"> +<p class="tent">7</p> +</td> +<td align="left"> +<p class="tent">9</p> +</td> +<td align="left"> +<p class="tent">Historical</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">7,+</p> +</td> +<td align="left"> +<p class="tent">7</p> +</td> +<td align="left"> +<p class="tent">.+</p> +</td> +<td align="left"> +<p class="tent">Historical</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">,</p> +</td> +<td align="left"> +<p class="tent">1</p> +</td> +<td align="left"> +<p class="tent">$</p> +</td> +<td align="left"> +<p class="tent">Historical</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">,7</p> +</td> +<td align="left"> +<p class="tent">1</p> +</td> +<td align="left"> +<p class="tent">7</p> +</td> +<td align="left"> +<p class="tent">Extension</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">,,</p> +</td> +<td align="left"> +<p class="tent">$</p> +</td> +<td align="left"> +<p class="tent">$</p> +</td> +<td align="left"> +<p class="tent">Extension</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">,;</p> +</td> +<td align="left"> +<p class="tent">$</p> +</td> +<td align="left"> +<p class="tent">$</p> +</td> +<td align="left"> +<p class="tent">Extension</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">7;</p> +</td> +<td align="left"> +<p class="tent">7</p> +</td> +<td align="left"> +<p class="tent">7</p> +</td> +<td align="left"> +<p class="tent">Historical</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">7;5;</p> +</td> +<td align="left"> +<p class="tent">5</p> +</td> +<td align="left"> +<p class="tent">5</p> +</td> +<td align="left"> +<p class="tent">Historical</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">7;5;9</p> +</td> +<td align="left"> +<p class="tent">5</p> +</td> +<td align="left"> +<p class="tent">9</p> +</td> +<td align="left"> +<p class="tent">Historical</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">7;5,9</p> +</td> +<td align="left"> +<p class="tent">5</p> +</td> +<td align="left"> +<p class="tent">9</p> +</td> +<td align="left"> +<p class="tent">Historical</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">7;$;4</p> +</td> +<td align="left"> +<p class="tent">$</p> +</td> +<td align="left"> +<p class="tent">4</p> +</td> +<td align="left"> +<p class="tent">Historical</p> +</td> +<td align="left"> +<p class="tent">Valid, but erroneous.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">7;9</p> +</td> +<td align="left"> +<p class="tent">7</p> +</td> +<td align="left"> +<p class="tent">9</p> +</td> +<td align="left"> +<p class="tent">Historical</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">7;+</p> +</td> +<td align="left"> +<p class="tent">7</p> +</td> +<td align="left"> +<p class="tent">8</p> +</td> +<td align="left"> +<p class="tent">Historical</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">;</p> +</td> +<td align="left"> +<p class="tent">.</p> +</td> +<td align="left"> +<p class="tent">$</p> +</td> +<td align="left"> +<p class="tent">Historical</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">;7</p> +</td> +<td align="left"> +<p class="tent">.</p> +</td> +<td align="left"> +<p class="tent">7</p> +</td> +<td align="left"> +<p class="tent">Extension</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">;;</p> +</td> +<td align="left"> +<p class="tent">$</p> +</td> +<td align="left"> +<p class="tent">$</p> +</td> +<td align="left"> +<p class="tent">Extension</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">;,</p> +</td> +<td align="left"> +<p class="tent">$</p> +</td> +<td align="left"> +<p class="tent">$</p> +</td> +<td align="left"> +<p class="tent">Extension</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +</tr> +</table> +</center> +<p class="tent">Historically, <i>ed</i> accepted the <tt>'^'</tt> character as an address, in which case it was identical to the +<hyphen-minus> character. POSIX.1-2024 does not require or prohibit this behavior.</p> +<p class="tent">Implementations are encouraged to set the buffer change flag to <b>changed-and-warned</b> when an <b>e</b> or +<b>q</b> command warns that an attempt was made to destroy the editor buffer. Some existing implementations set it to +<b>unchanged</b>, but this has the undesirable side-effect that a SIGHUP received after the warning is given does not write the +buffer to <b>ed.hup</b>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_38_19" id="tag_20_38_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a +<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require +implementations to treat this as an error.</p> +<p class="tent">A future version of this standard may require that the buffer change flag is set to <b>changed-and-warned</b> when +an <b>e</b> or <b>q</b> command warns that an attempt was made to destroy the editor buffer.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_38_20" id="tag_20_38_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap01.html#tag_18_04"><i>1.4 Utility Description Defaults</i></a> , <a href= +"../utilities/ex.html#"><i>ex</i></a> , <a href="../utilities/sed.html#"><i>sed</i></a> , <a href= +"../utilities/sh.html#"><i>sh</i></a> , <a href="../utilities/vi.html#"><i>vi</i></a></p> +<p class="tent">XBD <a href="../basedefs/V1_chap05.html#tagtcjh_2"><i>Escape Sequences and Associated Actions</i></a> , <a href= +"../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href="../basedefs/V1_chap09.html#tag_09_03"><i>9.3 +Basic Regular Expressions</i></a> , <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> , +<a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_38_21" id="tag_20_38_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_38_22" id="tag_20_38_22"></a>Issue 5</h4> +<blockquote> +<p>In the OPTIONS section, the meaning of <b>-s</b> and <b>-</b> is clarified.</p> +<p class="tent">A second FUTURE DIRECTION is added.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_38_23" id="tag_20_38_23"></a>Issue 6</h4> +<blockquote> +<p>The obsolescent single-minus form is removed.</p> +<p class="tent">A second APPLICATION USAGE note is added.</p> +<p class="tent">The Open Group Corrigendum U025/2 is applied, correcting the description of the Edit section.</p> +<p class="tent">The <i>ed</i> utility is updated to align with the IEEE P1003.2b draft standard. This includes addition of the +treatment of the SIGQUIT signal, changes to <i>ed</i> addressing, and changes to processing when end-of-file is detected and when +terminal disconnect is detected.</p> +<p class="tent">The normative text is reworded to avoid use of the term "must" for application requirements.</p> +<p class="tent">IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/22 is applied, adding the text: "Any line modified +by the <i>command list</i> shall be unmarked." to the <b>G</b> command. This change corresponds to a similar change made to the +<b>g</b> command in the first version of this standard.</p> +<p class="tent">IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/7 is applied, removing text describing behavior on +systems with bytes consisting of more than eight bits.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_38_24" id="tag_20_38_24"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #027 is applied, clarifying the behavior if an operand is <tt>'-'</tt>.</p> +<p class="tent">Austin Group Interpretation 1003.1-2001 #036 is applied, clarifying the behavior for BREs.</p> +<p class="tent">SD5-XCU-ERN-94 is applied, updating text in the EXTENDED DESCRIPTION where a terminal disconnect is detected (in +Commands in <i>ed</i>).</p> +<p class="tent">SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p class="tent">SD5-XCU-ERN-135 is applied, removing some RATIONALE text that is no longer applicable.</p> +<p class="tent">POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0090 [584], XCU/TC2-2008/0091 [584], and XCU/TC2-2008/0092 +[584] are applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_38_25" id="tag_20_38_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to disallow the creation of filenames containing any bytes that +have the encoded value of a <newline> character.</p> +<p class="tent">Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p class="tent">Austin Group Defect 1130 is applied, removing the requirement for the <b>c</b> command to accept an address of 0 +and updating the information about address 0 in the RATIONALE section.</p> +<p class="tent">Austin Group Defect 1131 is applied, changing the address 0 requirements for the <b>i</b> command.</p> +<p class="tent">Austin Group Defect 1204 is applied, clarifying the behavior when a closing delimiter that would be the last +character before a <newline> is omitted.</p> +<p class="tent">Austin Group Defect 1281 is applied, moving some text in the description of the <b>s</b> command and changing it to +use "shall".</p> +<p class="tent">Austin Group Defect 1298 is applied, changing the CONSEQUENCES OF ERRORS section.</p> +<p class="tent">Austin Group Defect 1308 is applied, changing the <b>Addr2</b> value for address <tt>7,+</tt> in the table of +address forms in the RATIONALE section.</p> +<p class="tent">Austin Group Defect 1311 is applied, changing "<i>join</i> command" to "<b>j</b> command" in the RATIONALE +section.</p> +<p class="tent">Austin Group Defect 1582 is applied, clarifying the behavior when an address is omitted between two address +separators.</p> +<p class="tent">Austin Group Defect 1607 is applied, clarifying the behavior when more than the maximum number of accepted +addresses are provided to a command.</p> +<p class="tent">Austin Group Defect 1662 is applied, clarifying requirements relating to delimiters in addresses and in <b>s</b> +commands.</p> +<p class="tent">Austin Group Defect 1786 is applied, clarifying the behavior when an <b>e</b> command names a file that does not +exist, and clarifying how the <i>ed</i> utility keeps track of whether the buffer has been modified.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/echo.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/env.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/env.html b/bdd/env.html @@ -0,0 +1,277 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>env</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/ed.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/ex.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="env" id="env"></a> <a name="tag_20_39" id="tag_20_39"></a><!-- env --> +<h4 class="mansect"><a name="tag_20_39_01" id="tag_20_39_01"></a>NAME</h4> +<blockquote>env — set the environment for command invocation</blockquote> +<h4 class="mansect"><a name="tag_20_39_02" id="tag_20_39_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>env</tt> <b>[</b><tt>-i</tt><b>] [</b><i>name</i><tt>=</tt><i>value</i><b>]</b><tt>...</tt> <b>[</b><i>utility</i> +<b>[</b><i>argument</i><tt>...</tt><b>]]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_39_03" id="tag_20_39_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>env</i> utility shall obtain the current environment, modify it according to its arguments, then invoke the utility named +by the <i>utility</i> operand with the modified environment.</p> +<p>Optional arguments shall be passed to <i>utility</i>.</p> +<p>If no <i>utility</i> operand is specified, the resulting environment shall be written to the standard output, with one +<i>name</i>=<i>value</i> pair per line.</p> +<p>If the first argument is <tt>'-'</tt>, the results are unspecified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_39_04" id="tag_20_39_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>env</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> , except for the unspecified usage of <tt>'-'</tt>.</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-i</b></dt> +<dd>Invoke <i>utility</i> with exactly the environment specified by the arguments; the inherited environment shall be ignored +completely.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_39_05" id="tag_20_39_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>name</i>=<i>value</i></dt> +<dd>Arguments of the form <i>name</i>=<i>value</i> shall modify the execution environment, and shall be placed into the inherited +environment before the <i>utility</i> is invoked.</dd> +<dt><i>utility</i></dt> +<dd>The name of the utility to be invoked. If the <i>utility</i> operand names any of the special built-in utilities in <a href= +"../utilities/V3_chap02.html#tag_19_15"><i>2.15 Special Built-In Utilities</i></a> , the results are undefined.</dd> +<dt><i>argument</i></dt> +<dd>A string to pass as an argument for the invoked utility.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_39_06" id="tag_20_39_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_39_07" id="tag_20_39_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_39_08" id="tag_20_39_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>env</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>PATH</i></dt> +<dd>Determine the location of the <i>utility</i>, as described in XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment +Variables</i></a> . If <i>PATH</i> is specified as a <i>name</i>=<i>value</i> operand to <i>env</i>, the <i>value</i> given shall +be used in the search for <i>utility</i>.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_39_09" id="tag_20_39_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_39_10" id="tag_20_39_10"></a>STDOUT</h4> +<blockquote> +<p>If no <i>utility</i> operand is specified, each <i>name</i>=<i>value</i> pair in the resulting environment shall be written in +the form:</p> +<pre> +<tt>"%s=%s\n", <</tt><i>name</i><tt>>, <</tt><i>value</i><tt>> +</tt></pre> +<p>If the <i>utility</i> operand is specified, the <i>env</i> utility shall not write to standard output.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_39_11" id="tag_20_39_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_39_12" id="tag_20_39_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_39_13" id="tag_20_39_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_39_14" id="tag_20_39_14"></a>EXIT STATUS</h4> +<blockquote> +<p>If <i>utility</i> is invoked, the exit status of <i>env</i> shall be the exit status of <i>utility</i>; otherwise, the +<i>env</i> utility shall exit with one of the following values:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>The <i>env</i> utility completed successfully.</dd> +<dt>1-125</dt> +<dd>An error occurred in the <i>env</i> utility.</dd> +<dt> 126</dt> +<dd>The utility specified by <i>utility</i> was found but could not be invoked.</dd> +<dt> 127</dt> +<dd>The utility specified by <i>utility</i> could not be found.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_39_15" id="tag_20_39_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_39_16" id="tag_20_39_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The <a href="../utilities/command.html"><i>command</i></a>, <i>env</i>, <a href="../utilities/nice.html"><i>nice</i></a>, +<a href="../utilities/nohup.html"><i>nohup</i></a>, <a href="../utilities/time.html"><i>time</i></a>, <a href= +"../utilities/timeout.html"><i>timeout</i></a>, and <a href="../utilities/xargs.html"><i>xargs</i></a> utilities have been +specified to use exit code 127 if a utility to be invoked cannot be found, so that applications can distinguish "failure to find a +utility" from "invoked utility exited with an error indication". The value 127 was chosen because it is not commonly used for +other meanings; most utilities use small values for "normal error conditions" and the values above 128 can be confused with +termination due to receipt of a signal. The value 126 was chosen in a similar manner to indicate that the utility could be found, +but not invoked. Some scripts produce meaningful error messages differentiating the 126 and 127 cases. The distinction between exit +codes 126 and 127 is based on KornShell practice that uses 127 when all attempts to <i>exec</i> the utility fail with [ENOENT], and +uses 126 when any attempt to <i>exec</i> the utility fails for any other reason.</p> +<p>Historical implementations of the <i>env</i> utility use the <a href="../functions/execvp.html"><i>execvp</i>()</a> or <a href= +"../functions/execlp.html"><i>execlp</i>()</a> functions defined in the System Interfaces volume of POSIX.1-2024 to invoke the +specified utility; this provides better performance and keeps users from having to escape characters with special meaning to the +shell. Therefore, shell functions, special built-ins, and built-ins that are only provided by the shell are not found by this type +of <i>env</i> implementation. However, <i>env</i> can be implemented as a shell built-in, in which case it may be able to execute +shell functions and built-ins. An application wishing to ensure execution of a non-built-in utility can use <a href= +"../utilities/exec.html"><i>exec</i></a> in a subshell for this purpose.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_39_17" id="tag_20_39_17"></a>EXAMPLES</h4> +<blockquote> +<p>The following command:</p> +<pre> +<tt>env -i PATH=/mybin:"$PATH" $(getconf V7_ENV) mygrep xyz myfile +</tt></pre> +<p>invokes the command <i>mygrep</i> with a new <i>PATH</i> value as the only entry in its environment other than any variables +required by the implementation for conformance. In this case, <i>PATH</i> is used to locate <i>mygrep</i>, which is expected to +reside in <b>/mybin</b>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_39_18" id="tag_20_39_18"></a>RATIONALE</h4> +<blockquote> +<p>As with all other utilities that invoke other utilities, this volume of POSIX.1-2024 only specifies what <i>env</i> does with +standard input, standard output, standard error, input files, and output files. If a utility is executed, it is not constrained by +the specification of input and output by <i>env</i>.</p> +<p>The <b>-i</b> option was added to allow the functionality of the removed <b>-</b> option in a manner compatible with the Utility +Syntax Guidelines. It is possible to create a non-conforming environment using the <b>-i</b> option, as it may remove environment +variables required by the implementation for conformance. The following will preserve these environment variables as well as +preserve the <i>PATH</i> for conforming utilities:</p> +<pre> +<tt>IFS=' +' +# The preceding value should be <space><tab><newline>. +# Set IFS to its default value. +<br> +set -f +# disable pathname expansion +<br> +\unalias -a +# Unset all possible aliases. +# Note that unalias is escaped to prevent an alias +# being used for unalias. +# This step is not strictly necessary, since aliases are not inherited, +# and the ENV environment variable is only used by interactive shells, +# the only way any aliases can exist in a script is if it defines them +# itself. +<br> +unset -f env getconf +# Ensure env and getconf are not user functions. +<br> +env -i $(getconf V7_ENV) PATH="$(getconf PATH)" command +</tt></pre> +<p>Some have suggested that <i>env</i> is redundant since the same effect is achieved by:</p> +<pre> +<tt>name=value ... utility </tt><b>[</b><tt> argument ... </tt><b>]</b><tt> +</tt></pre> +<p>The example is equivalent to <i>env</i> when an environment variable is being added to the environment of the command, but not +when the environment is being set to the given value. The <i>env</i> utility also writes out the current environment if invoked +without arguments. There is sufficient functionality beyond what the example provides to justify inclusion of <i>env</i>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_39_19" id="tag_20_39_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_39_20" id="tag_20_39_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19_15"><i>2.15 Special Built-In Utilities</i></a> , <a href= +"../utilities/V3_chap02.html#tag_19_05"><i>2.5 Parameters and Variables</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_39_21" id="tag_20_39_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_39_22" id="tag_20_39_22"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #027 is applied, clarifying the behavior if the first argument is <tt>'-'</tt>.</p> +<p>Austin Group Interpretation 1003.1-2001 #047 is applied, providing RATIONALE on how to use the <i>env</i> utility to preserve a +conforming environment.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>The EXAMPLES section is revised to change the use of <i>env</i> <b>-i</b>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_39_23" id="tag_20_39_23"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1157 is applied, adding a note about shell built-in implementations of <i>env</i> to the APPLICATION USAGE +section.</p> +<p>Austin Group Defect 1586 is applied, adding the <a href="../utilities/timeout.html"><i>timeout</i></a> utility.</p> +<p>Austin Group Defect 1594 is applied, changing the APPLICATION USAGE section.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/ed.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/ex.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/ex.html b/bdd/ex.html @@ -0,0 +1,3808 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>ex</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/env.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/expand.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="ex" id="ex"></a> <a name="tag_20_40" id="tag_20_40"></a><!-- ex --> +<h4 class="mansect"><a name="tag_20_40_01" id="tag_20_40_01"></a>NAME</h4> +<blockquote>ex — text editor</blockquote> +<h4 class="mansect"><a name="tag_20_40_02" id="tag_20_40_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> ex</tt> <b>[</b><tt>-rR</tt><b>] [</b><tt>-s|-v</tt><b>] [</b><tt>-c</tt> <i>command</i><b>] +[</b><tt>-t</tt> <i>tagstring</i><b>] [</b><tt>-w</tt> <i>size</i><b>] [</b><i>file</i><tt>...</tt><b>]</b> <tt><img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div> +</blockquote> +<h4 class="mansect"><a name="tag_20_40_03" id="tag_20_40_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>ex</i> utility is a line-oriented text editor. There are two other modes of the editor—open and visual—in which +screen-oriented editing is available. This is described more fully by the <i>ex</i> <b>open</b> and <b>visual</b> commands and in +<a href="../utilities/vi.html#"><i>vi</i></a> .</p> +<p>If an operand is <tt>'-'</tt>, the results are unspecified.</p> +<p>This section uses the term <i>edit buffer</i> to describe the current working text. No specific implementation is implied by +this term. All editing changes are performed on the edit buffer, and no changes to it shall affect any file until an editor command +writes the file.</p> +<p>Certain terminals do not have all the capabilities necessary to support the complete <i>ex</i> definition, such as the +full-screen editing commands (<i>visual mode</i> or <i>open mode</i>). When these commands cannot be supported on such terminals, +this condition shall not produce an error message such as "not an editor command" or report a syntax error. The implementation +may either accept the commands and produce results on the screen that are the result of an unsuccessful attempt to meet the +requirements of this volume of POSIX.1-2024 or report an error describing the terminal-related deficiency.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_40_04" id="tag_20_40_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>ex</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> , except for the unspecified usage of <tt>'-'</tt>, and that <tt>'+'</tt> may be recognized as an option +delimiter as well as <tt>'-'</tt>.</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-c </b><i>command</i></dt> +<dd>Specify an initial command to be executed in the first edit buffer loaded from an existing file (see the EXTENDED DESCRIPTION +section). Implementations may support more than a single <b>-c</b> option. In such implementations, the specified commands shall be +executed in the order specified on the command line.</dd> +<dt><b>-r</b></dt> +<dd>Recover the named files (see the EXTENDED DESCRIPTION section). Recovery information for a file shall be saved during an editor +or system crash (for example, when the editor is terminated by a signal which the editor can catch), or after the use of an +<i>ex</i> <b>preserve</b> command. +<p>A <i>crash</i> in this context is an unexpected failure of the system or utility that requires restarting the failed system or +utility. A system crash implies that any utilities running at the time also crash. In the case of an editor or system crash, the +number of changes to the edit buffer (since the most recent <b>preserve</b> command) that will be recovered is unspecified.</p> +<p>If no <i>file</i> operands are given and the <b>-t</b> option is not specified, all other options, the <i>EXINIT</i> variable, +and any <b>.exrc</b> files shall be ignored; a list of all recoverable files available to the invoking user shall be written, and +the editor shall exit normally without further action.</p> +</dd> +<dt><b>-R</b></dt> +<dd>Set <b>readonly</b> edit option.</dd> +<dt><b>-s</b></dt> +<dd>Prepare <i>ex</i> for batch use by taking the following actions: +<ul> +<li> +<p>Suppress writing prompts and informational (but not diagnostic) messages.</p> +</li> +<li> +<p>Ignore the value of <i>TERM</i> and any implementation default terminal type and assume the terminal is a type incapable of +supporting open or visual modes; see the <b>visual</b> command and the description of <a href="../utilities/vi.html#"><i>vi</i></a> +.</p> +</li> +<li> +<p>Suppress the use of the <i>EXINIT</i> environment variable and the reading of any <b>.exrc</b> file; see the EXTENDED +DESCRIPTION section.</p> +</li> +<li> +<p>Suppress autoindentation, ignoring the value of the <b>autoindent</b> edit option.</p> +</li> +</ul> +</dd> +<dt><b>-t </b><i>tagstring</i></dt> +<dd>Edit the file containing the specified <i>tagstring</i>; see <a href="../utilities/ctags.html#"><i>ctags</i></a> . The tags +feature represented by <b>-t</b> <i>tagstring</i> and the <b>tag</b> command is optional. It shall be provided on any system that +also provides a conforming implementation of <a href="../utilities/ctags.html"><i>ctags</i></a>; otherwise, the use of <b>-t</b> +produces undefined results. On any system, it shall be an error to specify more than a single <b>-t</b> option.</dd> +<dt><b>-v</b></dt> +<dd>Begin in visual mode (see <a href="../utilities/vi.html#"><i>vi</i></a> ).</dd> +<dt><b>-w </b><i>size</i></dt> +<dd>Set the value of the <i>window</i> editor option to <i>size</i>.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_40_05" id="tag_20_40_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of a file to be edited.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_40_06" id="tag_20_40_06"></a>STDIN</h4> +<blockquote> +<p>The standard input consists of a series of commands and input text, as described in the EXTENDED DESCRIPTION section. The +implementation may limit each line of standard input to a length of {LINE_MAX}.</p> +<p>If the standard input is not a terminal device, it shall be as if the <b>-s</b> option had been specified.</p> +<p>If a read from the standard input returns an error, or if the editor detects an end-of-file condition from the standard input, +it shall be equivalent to a SIGHUP asynchronous event.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_40_07" id="tag_20_40_07"></a>INPUT FILES</h4> +<blockquote> +<p>Input files shall be text files or files that would be text files except for an incomplete last line that is not longer than +{LINE_MAX}-1 bytes in length and contains no NUL characters. By default, any incomplete last line shall be treated as if it had a +trailing <newline>. The editing of other forms of files may optionally be allowed by <i>ex</i> implementations.</p> +<p>The <b>.exrc</b> files and source files shall be text files consisting of <i>ex</i> commands; see the EXTENDED DESCRIPTION +section.</p> +<p>By default, the editor shall read lines from the files to be edited without interpreting any of those lines as any form of +editor command.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_40_08" id="tag_20_40_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>ex</i>:</p> +<dl compact> +<dd></dd> +<dt><i>COLUMNS</i></dt> +<dd>Override the system-selected horizontal screen size. See XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment +Variables</i></a> for valid values and results when it is unset or null.</dd> +<dt><i>EXINIT</i></dt> +<dd>Determine a list of <i>ex</i> commands that are executed on editor start-up. See the EXTENDED DESCRIPTION section for more +details of the initialization phase.</dd> +<dt><i>HOME</i></dt> +<dd>Determine a pathname of a directory that shall be searched for an editor start-up file named <b>.exrc</b>; see the EXTENDED +DESCRIPTION section.</dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_COLLATE</i></dt> +<dd><br> +Determine the locale for the behavior of ranges, equivalence classes, and multi-character collating elements within regular +expressions.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files), the behavior of character classes within regular expressions, the +classification of characters as uppercase or lowercase letters, the case conversion of letters, and the detection of word +boundaries.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale used to process affirmative responses, and the locale that should be used to affect the format and contents of +diagnostic messages written to standard error.</dd> +<dt><i>LINES</i></dt> +<dd>Override the system-selected vertical screen size, used as the number of lines in a screenful and the vertical screen size in +visual mode. See XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> for valid values and results +when it is unset or null.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>PATH</i></dt> +<dd>Determine the search path for the shell command specified in the <i>ex</i> editor commands <b>!</b>, <b>shell</b>, <b>read</b>, +and <b>write</b>, and the open and visual mode command <b>!</b>; see the description of command search and execution in <a href= +"../utilities/V3_chap02.html#tag_19_09_01_04"><i>2.9.1.4 Command Search and Execution</i></a> .</dd> +<dt><i>SHELL</i></dt> +<dd>Determine the preferred command line interpreter for use as the default value of the <b>shell</b> edit option.</dd> +<dt><i>TERM</i></dt> +<dd>Determine the name of the terminal type. If this variable is unset or null, an unspecified default terminal type shall be +used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_40_09" id="tag_20_40_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>The following term is used in this and following sections to specify command and asynchronous event actions:</p> +<dl compact> +<dd></dd> +<dt><i>complete write</i></dt> +<dd><br> +A complete write is a write of the entire contents of the edit buffer to a file of a type other than a terminal device, or the +saving of the edit buffer caused by the user executing the <i>ex</i> <b>preserve</b> command. Writing the contents of the edit +buffer to a temporary file that will be removed when the editor exits shall not be considered a complete write.</dd> +</dl> +<p>The following actions shall be taken upon receipt of signals:</p> +<dl compact> +<dd></dd> +<dt>SIGINT</dt> +<dd>If the standard input is not a terminal device, <i>ex</i> shall not write the file or return to command or text input mode, and +shall exit with a non-zero exit status. +<p>Otherwise, if executing an open or visual text input mode command, <i>ex</i> in receipt of SIGINT shall behave identically to +its receipt of the <ESC> character.</p> +<p>Otherwise:</p> +<ol> +<li> +<p>If executing an <i>ex</i> text input mode command, all input lines that have been completely entered shall be resolved into the +edit buffer, and any partially entered line shall be discarded.</p> +</li> +<li> +<p>If there is a currently executing command, it shall be aborted and a message displayed. Unless otherwise specified by the +<i>ex</i> or <a href="../utilities/vi.html"><i>vi</i></a> command descriptions, it is unspecified whether any lines modified by the +executing command appear modified, or as they were before being modified by the executing command, in the buffer.</p> +<p>If the currently executing command was a motion command, its associated command shall be discarded.</p> +</li> +<li> +<p>If in open or visual command mode, the terminal shall be alerted.</p> +</li> +<li> +<p>The editor shall then return to command mode.</p> +</li> +</ol> +</dd> +<dt>SIGCONT</dt> +<dd>If <i>ex</i> is in open mode or visual mode, the actions described below for SIGWINCH shall be taken, except that the screen +shall always be refreshed (regardless of whether the terminal window size changed).</dd> +<dt>SIGHUP</dt> +<dd>If the edit buffer has been modified since the last complete write, <i>ex</i> shall attempt to save the edit buffer so that it +can be recovered later using the <b>-r</b> option or the <i>ex</i> <b>recover</b> command. The editor shall not write the file or +return to command or text input mode, and shall terminate with a non-zero exit status.</dd> +<dt>SIGTERM</dt> +<dd>Refer to SIGHUP.</dd> +<dt>SIGWINCH</dt> +<dd>If <i>ex</i> is in open mode or visual mode, the current terminal window size associated with the terminal on standard output +shall be obtained, as if by a call to XSH <a href="../functions/tcgetwinsize.html#"><i>tcgetwinsize</i></a> . If the terminal +window size is successfully obtained, it shall be used as follows: +<ul> +<li> +<p>If the <i>COLUMNS</i> environment variable is unset or does not contain a number, the horizontal screen size shall be set to the +number of columns in the obtained terminal window size.</p> +</li> +<li> +<p>If <i>ex</i> is in visual mode, the <b>-w</b> option was not specified and the <i>LINES</i> environment variable is unset or +does not contain a number, the vertical screen size shall be set to the number of rows in the obtained terminal window size.</p> +</li> +</ul> +<p>If the above resulted in either the vertical screen size or the horizontal screen size (or both) changing to a different value, +<i>ex</i> shall update the values it has for the number of lines and columns in the display and shall adjust the <b>window</b> edit +option and the column number at which the <b>wrapmargin</b> edit option takes effect (if non-zero) accordingly (see <a href= +"#tag_20_40_13_60">Edit Options in ex</a> ) and refresh the screen; otherwise, <i>ex</i> may refresh the screen.</p> +</dd> +</dl> +<p>The action taken for all other signals is unspecified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_40_10" id="tag_20_40_10"></a>STDOUT</h4> +<blockquote> +<p>The standard output shall be used only for writing prompts to the user, for informational messages, and for writing lines from +the file.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_40_11" id="tag_20_40_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_40_12" id="tag_20_40_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>The output from <i>ex</i> shall be text files.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_40_13" id="tag_20_40_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>Only the <i>ex</i> mode of the editor is described in this section. See <a href="../utilities/vi.html#"><i>vi</i></a> for +additional editing capabilities available in <i>ex</i>.</p> +<p>When an error occurs, <i>ex</i> shall write a message. If the terminal supports a standout mode (such as inverse video), the +message shall be written in standout mode. If the terminal does not support a standout mode, and the edit option <b>errorbells</b> +is set, an alert action shall precede the error message.</p> +<p>By default, <i>ex</i> shall start in command mode, which shall be indicated by a <b>:</b> prompt; see the <b>prompt</b> command. +Text input mode can be entered by the <b>append</b>, <b>insert</b>, or <b>change</b> commands; it can be exited (and command mode +re-entered) by typing a <period> (<tt>'.'</tt>) alone at the beginning of a line.</p> +<h5><a name="tag_20_40_13_01" id="tag_20_40_13_01"></a>Initialization in ex and vi</h5> +<p>The following symbols are used in this and following sections to specify locations in the edit buffer:</p> +<dl compact> +<dd></dd> +<dt><i>alternate and current pathnames</i></dt> +<dd><br> +Two pathnames, named <i>current</i> and <i>alternate</i>, are maintained by the editor. Any <i>ex</i> commands that take filenames +as arguments shall set them as follows: +<ol> +<li> +<p>If a <i>file</i> argument is specified to the <i>ex</i> <b>edit</b>, <b>ex</b>, or <b>recover</b> commands, or if an <i>ex</i> +<b>tag</b> command replaces the contents of the edit buffer.</p> +<ol type="a"> +<li> +<p>If the command replaces the contents of the edit buffer, the current pathname shall be set to the <i>file</i> argument or the +file indicated by the tag, and the alternate pathname shall be set to the previous value of the current pathname.</p> +</li> +<li> +<p>Otherwise, the alternate pathname shall be set to the <i>file</i> argument.</p> +</li> +</ol> +</li> +<li> +<p>If a <i>file</i> argument is specified to the <i>ex</i> <b>next</b> command:</p> +<ol type="a"> +<li> +<p>If the command replaces the contents of the edit buffer, the current pathname shall be set to the first <i>file</i> argument, +and the alternate pathname shall be set to the previous value of the current pathname.</p> +</li> +</ol> +</li> +<li> +<p>If a <i>file</i> argument is specified to the <i>ex</i> <b>file</b> command, the current pathname shall be set to the +<i>file</i> argument, and the alternate pathname shall be set to the previous value of the current pathname.</p> +</li> +<li> +<p>If a <i>file</i> argument is specified to the <i>ex</i> <b>read</b> and <b>write</b> commands (that is, when reading or writing +a file, and not to the program named by the <b>shell</b> edit option), or a <i>file</i> argument is specified to the <i>ex</i> +<b>xit</b> command:</p> +<ol type="a"> +<li> +<p>If the current pathname has no value, the current pathname shall be set to the <i>file</i> argument.</p> +</li> +<li> +<p>Otherwise, the alternate pathname shall be set to the <i>file</i> argument.</p> +</li> +</ol> +</li> +</ol> +<p>If the alternate pathname is set to the previous value of the current pathname when the current pathname had no previous value, +then the alternate pathname shall have no value as a result.</p> +</dd> +<dt><i>current line</i></dt> +<dd><br> +The line of the edit buffer referenced by the cursor. Each command description specifies the current line after the command has +been executed, as the <i>current line value</i>. When the edit buffer contains no lines, the current line shall be zero; see +<a href="#tag_20_40_13_02">Addressing in ex</a> .</dd> +<dt><i>current column</i></dt> +<dd><br> +The current display line column occupied by the cursor. (The columns shall be numbered beginning at 1.) Each command description +specifies the current column after the command has been executed, as the <i>current column</i> value. This column is an +<i>ideal</i> column that is remembered over the lifetime of the editor. The actual display line column upon which the cursor rests +may be different from the current column; see the cursor positioning discussion in <a href= +"../utilities/vi.html#tag_20_146_13_02"><i>Command Descriptions in vi</i></a> .</dd> +<dt><i>set to non-<blank></i></dt> +<dd><br> +A description for a current column value, meaning that the current column shall be set to the last display line column on which is +displayed any part of the first non-<blank> of the line. If the line has no non-<blank> non-<newline> characters, +the current column shall be set to the last display line column on which is displayed any part of the last non-<newline> +character in the line. If the line is empty, the current column shall be set to column position 1.</dd> +</dl> +<p>The length of lines in the edit buffer may be limited to {LINE_MAX} bytes. In open and visual mode, the length of lines in the +edit buffer may be limited to the number of characters that will fit in the display. If either limit is exceeded during editing, an +error message shall be written. If either limit is exceeded by a line read in from a file, an error message shall be written and +the edit session may be terminated.</p> +<p>If the editor stops running due to any reason other than a user command, and the edit buffer has been modified since the last +complete write, it shall be equivalent to a SIGHUP asynchronous event. If the system crashes, it shall be equivalent to a SIGHUP +asynchronous event.</p> +<p>During initialization (before the first file is copied into the edit buffer or any user commands from the terminal are +processed) the following shall occur:</p> +<ol> +<li> +<p>If the environment variable <i>EXINIT</i> is set, the editor shall execute the <i>ex</i> commands contained in that +variable.</p> +</li> +<li> +<p>If the <i>EXINIT</i> variable is not set, and all of the following are true:</p> +<ol type="a"> +<li> +<p>The <i>HOME</i> environment variable is not null and not empty.</p> +</li> +<li> +<p>The file <b>.exrc</b> in the directory referred to by the <i>HOME</i> environment variable:</p> +<ol type="i"> +<li> +<p>Exists</p> +</li> +<li> +<p>Is owned by the same user ID as the real user ID of the process or the process has appropriate privileges</p> +</li> +<li> +<p>Is not writable by anyone other than the owner</p> +</li> +</ol> +</li> +</ol> +<p>the editor shall execute the <i>ex</i> commands contained in that file.</p> +</li> +<li> +<p>If and only if all of the following are true:</p> +<ol type="a"> +<li> +<p>The current directory is not referred to by the <i>HOME</i> environment variable.</p> +</li> +<li> +<p>A command in the <i>EXINIT</i> environment variable or a command in the <b>.exrc</b> file in the directory referred to by the +<i>HOME</i> environment variable sets the editor option <b>exrc</b>.</p> +</li> +<li> +<p>The <b>.exrc</b> file in the current directory:</p> +<ol type="i"> +<li> +<p>Exists</p> +</li> +<li> +<p>Is owned by the same user ID as the real user ID of the process, or by one of a set of implementation-defined user IDs</p> +</li> +<li> +<p>Is not writable by anyone other than the owner</p> +</li> +</ol> +</li> +</ol> +<p>the editor shall attempt to execute the <i>ex</i> commands contained in that file.</p> +</li> +</ol> +<p>Lines in any <b>.exrc</b> file that are blank lines shall be ignored. If any <b>.exrc</b> file exists, but is not read for +ownership or permission reasons, it shall be an error.</p> +<p>After the <i>EXINIT</i> variable and any <b>.exrc</b> files are processed, the first file specified by the user shall be edited, +as follows:</p> +<ol> +<li> +<p>If the user specified the <b>-t</b> option, the effect shall be as if the <i>ex</i> <b>tag</b> command was entered with the +specified argument, with the exception that if tag processing does not result in a file to edit, the effect shall be as described +in step 3. below.</p> +</li> +<li> +<p>Otherwise, if the user specified any command line <i>file</i> arguments, the effect shall be as if the <i>ex</i> <b>edit</b> +command was entered with the first of those arguments as its <i>file</i> argument.</p> +</li> +<li> +<p>Otherwise, the effect shall be as if the <i>ex</i> <b>edit</b> command was entered with a nonexistent filename as its +<i>file</i> argument. It is unspecified whether this action shall set the current pathname. In an implementation where this action +does not set the current pathname, any editor command using the current pathname shall fail until an editor command sets the +current pathname.</p> +</li> +</ol> +<p>If the <b>-r</b> option was specified, the first time a file in the initial argument list or a file specified by the <b>-t</b> +option is edited, if recovery information has previously been saved about it, that information shall be recovered and the editor +shall behave as if the contents of the edit buffer have already been modified. If there are multiple instances of the file to be +recovered, the one most recently saved shall be recovered, and an informational message that there are previous versions of the +file that can be recovered shall be written. If no recovery information about a file is available, an informational message to this +effect shall be written, and the edit shall proceed as usual.</p> +<p>If the <b>-c</b> option was specified, the first time a file that already exists (including a file that might not exist but for +which recovery information is available, when the <b>-r</b> option is specified) replaces or initializes the contents of the edit +buffer, the current line shall be set to the last line of the edit buffer, the current column shall be set to non-<blank>, +and the <i>ex</i> commands specified with the <b>-c</b> option shall be executed. In this case, the current line and current column +shall not be set as described for the command associated with the replacement or initialization of the edit buffer contents. +However, if the <b>-t</b> option or a <b>tag</b> command is associated with this action, the <b>-c</b> option commands shall be +executed and then the movement to the tag shall be performed.</p> +<p>The current argument list shall initially be set to the filenames specified by the user on the command line. If no filenames are +specified by the user, the current argument list shall be empty. If the <b>-t</b> option was specified, it is unspecified whether +any filename resulting from tag processing shall be prepended to the current argument list. In the case where the filename is added +as a prefix to the current argument list, the current argument list reference shall be set to that filename. In the case where the +filename is not added as a prefix to the current argument list, the current argument list reference shall logically be located +before the first of the filenames specified on the command line (for example, a subsequent <i>ex</i> <b>next</b> command shall edit +the first filename from the command line). If the <b>-t</b> option was not specified, the current argument list reference shall be +to the first of the filenames on the command line.</p> +<h5><a name="tag_20_40_13_02" id="tag_20_40_13_02"></a>Addressing in ex</h5> +<p>Addressing in <i>ex</i> relates to the current line and the current column; the address of a line is its 1-based line number, +the address of a column is its 1-based count from the beginning of the line. Generally, the current line is the last line affected +by a command. The current line number is the address of the current line. In each command description, the effect of the command on +the current line number and the current column is described.</p> +<p>Addresses are constructed as follows:</p> +<ol> +<li> +<p>The character <tt>'.'</tt> (period) shall address the current line.</p> +</li> +<li> +<p>The character <tt>'$'</tt> shall address the last line of the edit buffer.</p> +</li> +<li> +<p>The positive decimal number <i>n</i> shall address the <i>n</i>th line of the edit buffer.</p> +</li> +<li> +<p>The address <tt>"'x"</tt> refers to the line marked with the mark name character <tt>'x'</tt>, which shall be a lowercase letter +from the portable character set, the backquote character, or the single-quote character. It shall be an error if the line that was +marked is not currently present in the edit buffer or the mark has not been set. Lines can be marked with the <i>ex</i> <b>mark</b> +or <b>k</b> commands, or the <a href="../utilities/vi.html"><i>vi</i></a> <b>m</b> command.</p> +</li> +<li> +<p>A regular expression enclosed by <slash> characters (<tt>'/'</tt>) shall address the first line found by searching +forwards from the line following the current line toward the end of the edit buffer and stopping at the first line for which the +line excluding the terminating <newline> matches the regular expression. As stated in <a href="#tag_20_40_13_58">Regular +Expressions in ex</a> , an address consisting of a null regular expression delimited by <slash> characters (<tt>"//"</tt>) +shall address the next line for which the line excluding the terminating <newline> matches the last regular expression +encountered. In addition, the second <slash> can be omitted at the end of a command line. If the <b>wrapscan</b> edit option +is set, the search shall wrap around to the beginning of the edit buffer and continue up to and including the current line, so that +the entire edit buffer is searched. Within the regular expression, the sequence <tt>"\/"</tt> shall represent a literal +<slash> instead of the regular expression delimiter.</p> +</li> +<li> +<p>A regular expression enclosed in <question-mark> characters (<tt>'?'</tt>) shall address the first line found by searching +backwards from the line preceding the current line toward the beginning of the edit buffer and stopping at the first line for which +the line excluding the terminating <newline> matches the regular expression. An address consisting of a null regular +expression delimited by <question-mark> characters (<tt>"??"</tt>) shall address the previous line for which the line +excluding the terminating <newline> matches the last regular expression encountered. In addition, the second +<question-mark> can be omitted at the end of a command line. If the <b>wrapscan</b> edit option is set, the search shall wrap +around from the beginning of the edit buffer to the end of the edit buffer and continue up to and including the current line, so +that the entire edit buffer is searched. Within the regular expression, the sequence <tt>"\?"</tt> shall represent a literal +<question-mark> instead of the RE delimiter.</p> +</li> +<li> +<p>A <plus-sign> (<tt>'+'</tt>) or a <hyphen-minus> (<tt>'-'</tt>) followed by a decimal number shall address the +current line plus or minus the number. A <tt>'+'</tt> or <tt>'-'</tt> not followed by a decimal number shall address the current +line plus or minus 1.</p> +</li> +</ol> +<p>Addresses can be followed by zero or more address offsets, optionally <blank>-separated. Address offsets are constructed +as follows:</p> +<ol> +<li> +<p>A <tt>'+'</tt> or <tt>'-'</tt> immediately followed by a decimal number shall add (subtract) the indicated number of lines to +(from) the address. A <tt>'+'</tt> or <tt>'-'</tt> not followed by a decimal number shall add (subtract) 1 to (from) the +address.</p> +</li> +<li> +<p>A decimal number shall add the indicated number of lines to the address.</p> +</li> +</ol> +<p>It shall not be an error for an intermediate address value to be less than zero or greater than the last line in the edit +buffer. It shall be an error for the final address value to be less than zero or greater than the last line in the edit buffer.</p> +<p>Commands take zero, one, or two addresses; see the descriptions of <i>1addr</i> and <i>2addr</i> in <a href= +"#tag_20_40_13_10">Command Descriptions in ex</a> . If more than the required number of addresses are provided to a command that +requires zero addresses, it shall be an error. Otherwise, if more than the required number of addresses are provided to a command, +the addresses specified first shall be evaluated and then discarded until the maximum number of valid addresses remain.</p> +<p>Addresses shall be separated from each other by a <comma> (<tt>','</tt>) or a <semicolon> (<tt>';'</tt>). If no +address is specified before or after a <comma> or <semicolon> separator, it shall be as if the address of the current +line was specified before or after the separator. In the case of a <semicolon> separator, the current line (<tt>'.'</tt>) +shall be set to the first address, and only then shall the next address be calculated. This feature can be used to determine the +starting line for forwards and backwards searches (see rules 5. and 6.).</p> +<p>A <percent-sign> (<tt>'%'</tt>) shall be equivalent to entering the two addresses <tt>"1,$"</tt>.</p> +<p>Any delimiting <blank> characters between addresses, address separators, or address offsets shall be discarded.</p> +<h5><a name="tag_20_40_13_03" id="tag_20_40_13_03"></a>Command Line Parsing in ex</h5> +<p>The following symbol is used in this and following sections to describe parsing behavior:</p> +<dl compact> +<dd></dd> +<dt><i>escape</i></dt> +<dd>If a character is referred to as "<backslash>-escaped" or "<control>-V-escaped", it shall mean that the +character acquired or lost a special meaning by virtue of being preceded, respectively, by a <backslash> or <control>-V +character. Unless otherwise specified, the escaping character shall be discarded at that time and shall not be further considered +for any purpose.</dd> +</dl> +<p>Command-line parsing shall be done in the following steps. For each step, characters already evaluated shall be ignored; that +is, the phrase "leading character" refers to the next character that has not yet been evaluated.</p> +<ol> +<li> +<p>Leading <colon> characters shall be skipped.</p> +</li> +<li> +<p>Leading <blank> characters shall be skipped.</p> +</li> +<li> +<p>If the leading character is a double-quote character, the characters up to and including the next non-<backslash>-escaped +<newline> shall be discarded, and any subsequent characters shall be parsed as a separate command.</p> +</li> +<li> +<p>Leading characters that can be interpreted as addresses shall be evaluated; see <a href="#tag_20_40_13_02">Addressing in ex</a> +.</p> +</li> +<li> +<p>Leading <blank> characters shall be skipped.</p> +</li> +<li> +<p>If the next character is a <vertical-line> character or a <newline>:</p> +<ol type="a"> +<li> +<p>If the next character is a <newline>:</p> +<ol type="i"> +<li> +<p>If <i>ex</i> is in open or visual mode, the current line shall be set to the last address specified, if any.</p> +</li> +<li> +<p>Otherwise, if the last command was terminated by a <vertical-line> character, no action shall be taken; for example, the +command <tt>"||<newline>"</tt> shall execute two implied commands, not three.</p> +</li> +<li> +<p>Otherwise, step 6.b. shall apply.</p> +</li> +</ol> +</li> +<li> +<p>Otherwise, the implied command shall be the <b>print</b> command. The last <b>#</b>, <b>p</b>, and <b>l</b> flags specified to +any <i>ex</i> command shall be remembered and shall apply to this implied command. Executing the <i>ex</i> <b>number</b>, +<b>print</b>, or <b>list</b> command shall set the remembered flags to <b>#</b>, nothing, and <b>l</b>, respectively, plus any +other flags specified for that execution of the <b>number</b>, <b>print</b>, or <b>list</b> command.</p> +<p>If <i>ex</i> is not currently performing a <b>global</b> or <b>v</b> command, and no address or count is specified, the current +line shall be incremented by 1 before the command is executed. If incrementing the current line would result in an address past the +last line in the edit buffer, the command shall fail, and the increment shall not happen.</p> +</li> +<li> +<p>The <newline> or <vertical-line> character shall be discarded and any subsequent characters shall be parsed as a +separate command.</p> +</li> +</ol> +</li> +<li> +<p>The command name shall be comprised of the next character (if the character is not alphabetic), or the next character and any +subsequent alphabetic characters (if the character is alphabetic), with the following exceptions:</p> +<ol type="a"> +<li> +<p>Commands that consist of any prefix of the characters in the command name <b>delete</b>, followed immediately by any of the +characters <tt>'l'</tt>, <tt>'p'</tt>, <tt>'+'</tt>, <tt>'-'</tt>, or <tt>'#'</tt> shall be interpreted as a <b>delete</b> command, +followed by a <blank>, followed by the characters that were not part of the prefix of the <b>delete</b> command. The maximum +number of characters shall be matched to the command name <b>delete</b>; for example, <tt>"del"</tt> shall not be treated as +<tt>"de"</tt> followed by the flag <b>l</b>.</p> +</li> +<li> +<p>Commands that consist of the character <tt>'k'</tt>, followed by a character that can be used as the name of a mark, shall be +equivalent to the mark command followed by a <blank>, followed by the character that followed the <tt>'k'</tt>.</p> +</li> +<li> +<p>Commands that consist of the character <tt>'s'</tt>, followed by characters that could be interpreted as valid options to the +<b>s</b> command, shall be the equivalent of the <b>s</b> command, without any pattern or replacement values, followed by a +<blank>, followed by the characters after the <tt>'s'</tt>.</p> +</li> +</ol> +</li> +<li> +<p>The command name shall be matched against the possible command names, and a command name that contains a prefix matching the +characters specified by the user shall be the executed command. In the case of commands where the characters specified by the user +could be ambiguous, the executed command shall be as follows:</p> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>a</b></p> +</td> +<td align="left"> +<p class="tent"><b>append</b></p> +</td> +<td align="left"> +<p class="tent">n</p> +</td> +<td align="left"> +<p class="tent"><b>next</b></p> +</td> +<td align="left"> +<p class="tent"><b>t</b></p> +</td> +<td align="left"> +<p class="tent">t</p> +</td> +<td align="left"> +<p class="tent"><b> </b></p> +</td> +<td align="left"> +<p class="tent"><b> </b></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>c</b></p> +</td> +<td align="left"> +<p class="tent"><b>change</b></p> +</td> +<td align="left"> +<p class="tent">p</p> +</td> +<td align="left"> +<p class="tent"><b>print</b></p> +</td> +<td align="left"> +<p class="tent"><b>u</b></p> +</td> +<td align="left"> +<p class="tent">undo</p> +</td> +<td align="left"> +<p class="tent"><b> </b></p> +</td> +<td align="left"> +<p class="tent"><b> </b></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>ch</b></p> +</td> +<td align="left"> +<p class="tent"><b>change</b></p> +</td> +<td align="left"> +<p class="tent">pr</p> +</td> +<td align="left"> +<p class="tent"><b>print</b></p> +</td> +<td align="left"> +<p class="tent"><b>un</b></p> +</td> +<td align="left"> +<p class="tent">undo</p> +</td> +<td align="left"> +<p class="tent"><b> </b></p> +</td> +<td align="left"> +<p class="tent"><b> </b></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>e</b></p> +</td> +<td align="left"> +<p class="tent"><b>edit</b></p> +</td> +<td align="left"> +<p class="tent">r</p> +</td> +<td align="left"> +<p class="tent"><b>read</b></p> +</td> +<td align="left"> +<p class="tent"><b>v</b></p> +</td> +<td align="left"> +<p class="tent">v</p> +</td> +<td align="left"> +<p class="tent"><b> </b></p> +</td> +<td align="left"> +<p class="tent"><b> </b></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>m</b></p> +</td> +<td align="left"> +<p class="tent"><b>move</b></p> +</td> +<td align="left"> +<p class="tent">re</p> +</td> +<td align="left"> +<p class="tent"><b>read</b></p> +</td> +<td align="left"> +<p class="tent"><b>w</b></p> +</td> +<td align="left"> +<p class="tent">write</p> +</td> +<td align="left"> +<p class="tent"><b> </b></p> +</td> +<td align="left"> +<p class="tent"><b> </b></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>ma</b></p> +</td> +<td align="left"> +<p class="tent"><b>mark</b></p> +</td> +<td align="left"> +<p class="tent">s</p> +</td> +<td align="left"> +<p class="tent"><b>s</b></p> +</td> +<td align="left"> +<p class="tent"><b> </b></p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent"><b> </b></p> +</td> +<td align="left"> +<p class="tent"><b> </b></p> +</td> +</tr> +</table> +</center> +<p class="tent">Implementation extensions with names causing similar ambiguities shall not be checked for a match until all +possible matches for commands specified by POSIX.1-2024 have been checked.</p> +</li> +<li class="tent">If the command is a <b>!</b> command, or if the command is a <b>read</b> command followed by zero or more +<blank> characters and a <b>!</b>, or if the command is a <b>write</b> command followed by one or more <blank> +characters and a <b>!</b>, the rest of the command shall include all characters up to a non-<backslash>-escaped +<newline>. The <newline> shall be discarded and any subsequent characters shall be parsed as a separate <i>ex</i> +command.</li> +<li class="tent">Otherwise, if the command is an <b>edit</b>, <b>ex</b>, or <b>next</b> command, or a <b>visual</b> command while +in open or visual mode, the next part of the command shall be parsed as follows: +<ol type="a"> +<li class="tent">Any <tt>'!'</tt> character immediately following the command shall be skipped and be part of the command.</li> +<li class="tent">Any leading <blank> characters shall be skipped and be part of the command.</li> +<li class="tent">If the next character is a <tt>'+'</tt>, characters up to the first non-<backslash>-escaped <newline> +or non-<backslash>-escaped <blank> shall be skipped and be part of the command.</li> +<li class="tent">The rest of the command shall be determined by the steps specified in paragraph 12.</li> +</ol> +</li> +<li class="tent">Otherwise, if the command is a <b>global</b>, <b>open</b>, <b>s</b>, or <b>v</b> command, the next part of the +command shall be parsed as follows: +<ol type="a"> +<li class="tent">Any leading <blank> characters shall be skipped and be part of the command.</li> +<li class="tent">If the next character is not an alphanumeric, double-quote, <newline>, <backslash>, or +<vertical-line> character: +<ol type="i"> +<li class="tent">The next character shall be used as a command delimiter.</li> +<li class="tent">If the command is a <b>global</b>, <b>open</b>, or <b>v</b> command, characters up to the first +non-<backslash>-escaped <newline>, or first non-<backslash>-escaped delimiter character, shall be skipped and be +part of the command.</li> +<li class="tent">If the command is an <b>s</b> command, characters up to the first non-<backslash>-escaped <newline>, +or second non-<backslash>-escaped delimiter character, shall be skipped and be part of the command.</li> +</ol> +</li> +<li class="tent">If the command is a <b>global</b> or <b>v</b> command, characters up to the first non-<backslash>-escaped +<newline> shall be skipped and be part of the command.</li> +<li class="tent">Otherwise, the rest of the command shall be determined by the steps specified in paragraph 12.</li> +</ol> +</li> +<li class="tent">Otherwise: +<ol type="a"> +<li class="tent">If the command was a <b>map</b>, <b>unmap</b>, <b>abbreviate</b>, or <b>unabbreviate</b> command, characters up to +the first non-<control>-V-escaped <newline>, <vertical-line>, or double-quote character shall be skipped and be +part of the command.</li> +<li class="tent">Otherwise, characters up to the first non-<backslash>-escaped <newline>, <vertical-line>, or +double-quote character shall be skipped and be part of the command.</li> +<li class="tent">If the command was an <b>append</b>, <b>change</b>, or <b>insert</b> command, and the step 12.b. ended at a +<vertical-line> character, any subsequent characters, up to the next non-<backslash>-escaped <newline> shall be +used as input text to the command.</li> +<li class="tent">If the command was ended by a double-quote character, all subsequent characters, up to the next +non-<backslash>-escaped <newline>, shall be discarded.</li> +<li class="tent">The terminating <newline> or <vertical-line> character shall be discarded and any subsequent +characters shall be parsed as a separate <i>ex</i> command.</li> +</ol> +</li> +</ol> +<p class="tent">Command arguments shall be parsed as described by the Synopsis and Description of each individual <i>ex</i> +command. This parsing shall not be <blank>-sensitive, except for the <b>!</b> argument, which has to follow the command name +without intervening <blank> characters, and where it would otherwise be ambiguous. For example, <i>count</i> and <i>flag</i> +arguments need not be <blank>-separated because <tt>"d22p"</tt> is not ambiguous, but <i>file</i> arguments to the <i>ex</i> +<b>next</b> command need to be separated by one or more <blank> characters. Any <blank> in command arguments for the +<b>abbreviate</b>, <b>unabbreviate</b>, <b>map</b>, and <b>unmap</b> commands can be <control>-V-escaped, in which case the +<blank> shall not be used as an argument delimiter. Any <blank> in the command argument for any other command can be +<backslash>-escaped, in which case that <blank> shall not be used as an argument delimiter.</p> +<p class="tent">Within command arguments for the <b>abbreviate</b>, <b>unabbreviate</b>, <b>map</b>, and <b>unmap</b> commands, any +character can be <control>-V-escaped. All such escaped characters shall be treated literally and shall have no special +meaning. Within command arguments for all other <i>ex</i> commands that are not regular expressions or replacement strings, any +character that would otherwise have a special meaning can be <backslash>-escaped. Escaped characters shall be treated +literally, without special meaning as shell expansion characters or <tt>'!'</tt>, <tt>'%'</tt>, and <tt>'#'</tt> expansion +characters. See <a href="#tag_20_40_13_58">Regular Expressions in ex</a> and <a href="#tag_20_40_13_59">Replacement Strings in +ex</a> for descriptions of command arguments that are regular expressions or replacement strings.</p> +<p class="tent">Non-<backslash>-escaped <tt>'%'</tt> characters appearing in <i>file</i> arguments to any <i>ex</i> command +shall be replaced by the current pathname; unescaped <tt>'#'</tt> characters shall be replaced by the alternate pathname. It shall +be an error if <tt>'%'</tt> or <tt>'#'</tt> characters appear unescaped in an argument and their corresponding values are not +set.</p> +<p class="tent">Non-<backslash>-escaped <tt>'!'</tt> characters in the arguments to either the <i>ex</i> <b>!</b> command or +the open and visual mode <b>!</b> command, or in the arguments to the <i>ex</i> <b>read</b> command, where the first +non-<blank> after the command name is a <tt>'!'</tt> character, or in the arguments to the <i>ex</i> <b>write</b> command +where the command name is followed by one or more <blank> characters and the first non-<blank> after the command name +is a <tt>'!'</tt> character, shall be replaced with the arguments to the last of those three commands as they appeared after all +unescaped <tt>'%'</tt>, <tt>'#'</tt>, and <tt>'!'</tt> characters were replaced. It shall be an error if <tt>'!'</tt> characters +appear unescaped in one of these commands and there has been no previous execution of one of these commands.</p> +<p class="tent">If an error occurs during the parsing or execution of an <i>ex</i> command:</p> +<ul> +<li class="tent">An informational message to this effect shall be written. Execution of the <i>ex</i> command shall stop, and the +cursor (for example, the current line and column) shall not be further modified.</li> +<li class="tent">If the <i>ex</i> command resulted from a map expansion, all characters from that map expansion shall be discarded, +except as otherwise specified by the <b>map</b> command.</li> +<li class="tent">Otherwise, if the <i>ex</i> command resulted from the processing of an <i>EXINIT</i> environment variable, a +<b>.exrc</b> file, a <b>:source</b> command, a <b>-c</b> option, or a <b>+</b><i>command</i> specified to an <i>ex</i> <b>edit</b>, +<b>ex</b>, <b>next</b>, or <b>visual</b> command, no further commands from the source of the commands shall be executed.</li> +<li class="tent">Otherwise, if the <i>ex</i> command resulted from the execution of a buffer or a <b>global</b> or <b>v</b> +command, no further commands caused by the execution of the buffer or the <b>global</b> or <b>v</b> command shall be executed.</li> +<li class="tent">Otherwise, if the <i>ex</i> command was not terminated by a <newline>, all characters up to and including +the next non-<backslash>-escaped <newline> shall be discarded.</li> +</ul> +<h5><a name="tag_20_40_13_04" id="tag_20_40_13_04"></a>Input Editing in ex</h5> +<p class="tent">The following symbol is used in this and the following sections to specify command actions:</p> +<dl compact> +<dd></dd> +<dt><i>word</i></dt> +<dd>In the POSIX locale, a word consists of a maximal sequence of letters, digits, and underscores, delimited at both ends by +characters other than letters, digits, or underscores, or by the beginning or end of a line or the edit buffer.</dd> +</dl> +<p class="tent">When accepting input characters from the user, in either <i>ex</i> command mode or <i>ex</i> text input mode, +<i>ex</i> shall enable canonical mode input processing, as defined in the System Interfaces volume of POSIX.1-2024.<br></p> +<p class="tent">If in <i>ex</i> text input mode:</p> +<ol> +<li class="tent">If the <b>number</b> edit option is set, <i>ex</i> shall prompt for input using the line number that would be +assigned to the line if it is entered, in the format specified for the <i>ex</i> <b>number</b> command.</li> +<li class="tent">If the <b>autoindent</b> edit option is set, <i>ex</i> shall prompt for input using <b>autoindent</b> characters, +as described by the <b>autoindent</b> edit option. <b>autoindent</b> characters shall follow the line number, if any.</li> +</ol> +<p class="tent">If in <i>ex</i> command mode:</p> +<ol> +<li class="tent">If the <b>prompt</b> edit option is set, input shall be prompted for using a single <tt>':'</tt> character; +otherwise, there shall be no prompt.</li> +</ol> +<p class="tent">The input characters in the following sections shall have the following effects on the input line.</p> +<h5><a name="tag_20_40_13_05" id="tag_20_40_13_05"></a>Scroll</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>eof +</tt></pre></dd> +</dl> +<p class="tent">See the description of the <a href="../utilities/stty.html"><i>stty</i></a> <i>eof</i> character in <a href= +"../utilities/stty.html#"><i>stty</i></a> .</p> +<p class="tent">If in <i>ex</i> command mode:</p> +<blockquote>If the <i>eof</i> character is the first character entered on the line, the line shall be evaluated as if it contained +two characters: a <control>-D and a <newline>. +<p class="tent">Otherwise, the <i>eof</i> character shall have no special meaning.</p> +</blockquote> +<br> +<p class="tent">If in <i>ex</i> text input mode:</p> +<blockquote>If the cursor follows an <b>autoindent</b> character, the <b>autoindent</b> characters in the line shall be modified so +that a part of the next text input character is displayed on the first column in the line after the previous <b>shiftwidth</b> edit +option column boundary, and the user shall be prompted again for input for the same line. +<p class="tent">Otherwise, if the cursor follows a <tt>'0'</tt>, which follows an <b>autoindent</b> character, and the <tt>'0'</tt> +was the previous text input character, the <tt>'0'</tt> and all <b>autoindent</b> characters in the line shall be discarded, and +the user shall be prompted again for input for the same line.</p> +<p class="tent">Otherwise, if the cursor follows a <tt>'^'</tt>, which follows an <b>autoindent</b> character, and the <tt>'^'</tt> +was the previous text input character, the <tt>'^'</tt> and all <b>autoindent</b> characters in the line shall be discarded, and +the user shall be prompted again for input for the same line. In addition, the <b>autoindent</b> level for the next input line +shall be derived from the same line from which the <b>autoindent</b> level for the current input line was derived.</p> +<p class="tent">Otherwise, if there are no <b>autoindent</b> or text input characters in the line, the <i>eof</i> character shall +be discarded.</p> +<p class="tent">Otherwise, the <i>eof</i> character shall have no special meaning.</p> +</blockquote> +<h5><a name="tag_20_40_13_06" id="tag_20_40_13_06"></a><newline></h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt><newline> +<br> +<control>-J +</tt></pre></dd> +</dl> +<p class="tent">If in <i>ex</i> command mode:</p> +<blockquote>Cause the command line to be parsed; <control>-J shall be mapped to the <newline> for this +purpose.</blockquote> +<br> +<p class="tent">If in <i>ex</i> text input mode:</p> +<blockquote>Terminate the current line. If there are no characters other than <b>autoindent</b> characters on the line, all +characters on the line shall be discarded. +<p class="tent">Prompt for text input on a new line after the current line. If the <b>autoindent</b> edit option is set, an +appropriate number of <b>autoindent</b> characters shall be added as a prefix to the line as described by the <i>ex</i> +<b>autoindent</b> edit option.</p> +</blockquote> +<h5><a name="tag_20_40_13_07" id="tag_20_40_13_07"></a><backslash></h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt><backslash> +</tt></pre></dd> +</dl> +<p class="tent">Allow the entry of a subsequent <newline> or <control>-J as a literal character, removing any special +meaning that it may have to the editor during text input mode. The <backslash> character shall be retained and evaluated when +the command line is parsed, or retained and included when the input text becomes part of the edit buffer.</p> +<h5><a name="tag_20_40_13_08" id="tag_20_40_13_08"></a><control>-V</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt><control>-V +</tt></pre></dd> +</dl> +<p class="tent">Allow the entry of any subsequent character as a literal character, removing any special meaning that it may have +to the editor during text input mode. The <control>-V character shall be discarded before the command line is parsed or the +input text becomes part of the edit buffer.</p> +<p class="tent">If the "literal next" functionality is performed by the underlying system, it is implementation-defined whether a +character other than <control>-V performs this function.</p> +<h5><a name="tag_20_40_13_09" id="tag_20_40_13_09"></a><control>-W</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt><control>-W +</tt></pre></dd> +</dl> +<p class="tent">Discard the <control>-W, and the word previous to it in the input line, including any <blank> +characters following the word and preceding the <control>-W. If the "word erase" functionality is performed by the +underlying system, it is implementation-defined whether a character other than <control>-W performs this function.</p> +<h5><a name="tag_20_40_13_10" id="tag_20_40_13_10"></a>Command Descriptions in ex</h5> +<p class="tent">The following symbols are used in this section to represent command modifiers. Some of these modifiers can be +omitted, in which case the specified defaults shall be used.</p> +<dl compact> +<dd></dd> +<dt><i>1addr</i></dt> +<dd>A single line address, given in any of the forms described in <a href="#tag_20_40_13_02">Addressing in ex</a> ; the default +shall be the current line (<tt>'.'</tt>), unless otherwise specified. +<p class="tent">If the line address is zero, it shall be an error, unless otherwise specified in the following command +descriptions.</p> +<p class="tent">If the edit buffer is empty, and the address is specified with a command other than <b>=</b>, <b>append</b>, +<b>insert</b>, <b>open</b>, <b>put</b>, <b>read</b>, or <b>visual</b>, or the address is not zero, it shall be an error.</p> +</dd> +<dt><i>2addr</i></dt> +<dd>Two addresses specifying an inclusive range of lines. If no addresses are specified, the default for <i>2addr</i> shall be the +current line only (<tt>".,."</tt>), unless otherwise specified in the following command descriptions. If one address is specified, +<i>2addr</i> shall specify that line only, unless otherwise specified in the following command descriptions. +<p class="tent">It shall be an error if the first address is greater than the second address.</p> +<p class="tent">If the edit buffer is empty, and the two addresses are specified with a command other than the <b>!</b>, +<b>write</b>, <b>wq</b>, or <b>xit</b> commands, or either address is not zero, it shall be an error.</p> +</dd> +<dt><i>count</i></dt> +<dd>A positive decimal number. If <i>count</i> is specified, it shall be equivalent to specifying an additional address to the +command, unless otherwise specified by the following command descriptions. The additional address shall be equal to the last +address specified to the command (either explicitly or by default) plus <i>count</i>-1. +<p class="tent">If this would result in an address greater than the last line of the edit buffer, it shall be corrected to equal +the last line of the edit buffer.</p> +</dd> +<dt><i>flags</i></dt> +<dd>One or more of the characters <tt>'+'</tt>, <tt>'-'</tt>, <tt>'#'</tt>, <tt>'p'</tt>, or <tt>'l'</tt> (ell). The flag +characters can be <blank>-separated, and in any order or combination. The characters <tt>'#'</tt>, <tt>'p'</tt>, and +<tt>'l'</tt> shall cause lines to be written in the format specified by the <b>print</b> command with the specified <i>flags</i>. +<p class="tent">The lines to be written are as follows:</p> +<ol> +<li class="tent">All edit buffer lines written during the execution of the <i>ex</i> <b>&</b>, <b>~</b>, <b>list</b>, +<b>number</b>, <b>open</b>, <b>print</b>, <b>s</b>, <b>visual</b>, and <b>z</b> commands shall be written as specified by +<i>flags</i>.</li> +<li class="tent">After the completion of an <i>ex</i> command with a flag as an argument, the current line shall be written as +specified by <i>flags</i>, unless the current line was the last line written by the command.</li> +</ol> +<p class="tent">The characters <tt>'+'</tt> and <tt>'-'</tt> cause the value of the current line after the execution of the +<i>ex</i> command to be adjusted by the offset address as described in <a href="#tag_20_40_13_02">Addressing in ex</a> . This +adjustment shall occur before the current line is written as described in 2. above.</p> +<p class="tent">The default for <i>flags</i> shall be none.</p> +</dd> +<dt><i>buffer</i></dt> +<dd>One of a number of named areas for holding text. The named buffers are specified by the alphanumeric characters of the POSIX +locale. There shall also be one "unnamed" buffer. When no buffer is specified for editor commands that use a buffer, the unnamed +buffer shall be used. Commands that store text into buffers shall store the text as it was before the command took effect, and +shall store text occurring earlier in the file before text occurring later in the file, regardless of how the text region was +specified. Commands that store text into buffers shall store the text into the unnamed buffer as well as any specified buffer. +<p class="tent">In <i>ex</i> commands, buffer names are specified as the name by itself. In open or visual mode commands the name +is preceded by a double-quote (<tt>'"'</tt> ) character.</p> +<p class="tent">If the specified buffer name is an uppercase character, and the buffer contents are to be modified, the buffer +shall be appended to rather than being overwritten. If the buffer is not being modified, specifying the buffer name in lowercase +and uppercase shall have identical results.</p> +<p class="tent">There shall also be buffers named by the numbers 1 through 9. In open and visual mode, if a region of text +including characters from more than a single line is being modified by the <a href="../utilities/vi.html"><i>vi</i></a> <b>c</b> or +<b>d</b> commands, the motion character associated with the <b>c</b> or <b>d</b> commands specifies that the buffer text shall be +in line mode, or the commands <b>%</b>, <b>`</b>, <b>/</b>, <b>?</b>, <b>(</b>, <b>)</b>, <b>N</b>, <b>n</b>, <b>{</b>, or <b>}</b> +are used to define a region of text for the <b>c</b> or <b>d</b> commands, the contents of buffers 1 through 8 shall be moved into +the buffer named by the next numerically greater value, the contents of buffer 9 shall be discarded, and the region of text shall +be copied into buffer 1. This shall be in addition to copying the text into a user-specified buffer or unnamed buffer, or both. +Numeric buffers can be specified as a source buffer for open and visual mode commands; however, specifying a numeric buffer as the +write target of an open or visual mode command shall have unspecified results.</p> +<p class="tent">The text of each buffer shall have the characteristic of being in either line or character mode. Appending text to +a non-empty buffer shall set the mode to match the characteristic of the text being appended. Appending text to a buffer shall +cause the creation of at least one additional line in the buffer. All text stored into buffers by <i>ex</i> commands shall be in +line mode. The <i>ex</i> commands that use buffers as the source of text specify individually how buffers of different modes are +handled. Each open or visual mode command that uses buffers for any purpose specifies individually the mode of the text stored into +the buffer and how buffers of different modes are handled.</p> +</dd> +<dt><i>file</i></dt> +<dd>Command text used to derive a pathname. The default shall be the current pathname, as defined previously, in which case, if no +current pathname has yet been established it shall be an error, except where specifically noted in the individual command +descriptions that follow. If the command text contains any of the characters <tt>'~'</tt>, <tt>'{'</tt>, <tt>'['</tt>, +<tt>'*'</tt>, <tt>'?'</tt>, <tt>'$'</tt>, <tt>'"'</tt>, backquote, single-quote, and <backslash>, it shall be subjected to +the process of "shell expansions", as described below; if more than a single pathname results and the command expects only one, +it shall be an error. +<p class="tent">The process of shell expansions in the editor shall be done as follows. The <i>ex</i> utility shall pass two +arguments to the program named by the shell edit option; the first shall be <b>-c</b>, and the second shall be the string +<tt>"echo"</tt> and the command text as a single argument. The standard output and standard error of that command shall replace the +command text.</p> +</dd> +<dt><b>!</b></dt> +<dd>A character that can be appended to the command name to modify its operation, as detailed in the individual command +descriptions. With the exception of the <i>ex</i> <b>read</b>, <b>write</b>, and <b>!</b> commands, the <tt>'!'</tt> character +shall only act as a modifier if there are no <blank> characters between it and the command name.</dd> +<dt><i>remembered search direction</i></dt> +<dd><br> +The <a href="../utilities/vi.html"><i>vi</i></a> commands <b>N</b> and <b>n</b> begin searching in a forwards or backwards +direction in the edit buffer based on a remembered search direction, which is initially unset, and is set by the <i>ex</i> +<b>global</b>, <b>v</b>, <b>s</b>, and <b>tag</b> commands, and the <a href="../utilities/vi.html"><i>vi</i></a> <b>/</b> and +<b>?</b> commands.</dd> +</dl> +<h5><a name="tag_20_40_13_11" id="tag_20_40_13_11"></a>Abbreviate</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>ab</tt><b>[</b><i>breviate</i><b>][</b><i>lhs rhs</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">If <i>lhs</i> and <i>rhs</i> are not specified, write the current list of abbreviations and do nothing more.</p> +<p class="tent">Implementations may restrict the set of characters accepted in <i>lhs</i> or <i>rhs</i>, except that printable +characters and <blank> characters shall not be restricted. Additional restrictions shall be implementation-defined.</p> +<p class="tent">In both <i>lhs</i> and <i>rhs</i>, any character may be escaped with a <control>-V, in which case the +character shall not be used to delimit <i>lhs</i> from <i>rhs</i>, and the escaping <control>-V shall be discarded.</p> +<p class="tent">In open and visual text input mode, if a non-word or <ESC> character that is not escaped by a +<control>-V character is entered after a word character, a check shall be made for a set of characters matching <i>lhs</i>, +in the text input entered during this command. If it is found, the effect shall be as if <i>rhs</i> was entered instead of +<i>lhs</i>.</p> +<p class="tent">The set of characters that are checked is defined as follows:</p> +<ol> +<li class="tent">If there are no characters inserted before the word and non-word or <ESC> characters that triggered the +check, the set of characters shall consist of the word character.</li> +<li class="tent">If the character inserted before the word and non-word or <ESC> characters that triggered the check is a +word character, the set of characters shall consist of the characters inserted immediately before the triggering characters that +are word characters, plus the triggering word character.</li> +<li class="tent">If the character inserted before the word and non-word or <ESC> characters that triggered the check is not a +word character, the set of characters shall consist of the characters that were inserted before the triggering characters that are +neither <blank> characters nor word characters, plus the triggering word character.</li> +</ol> +<p class="tent">It is unspecified whether the <i>lhs</i> argument entered for the <i>ex</i> <b>abbreviate</b> and +<b>unabbreviate</b> commands is replaced in this fashion. Regardless of whether or not the replacement occurs, the effect of the +command shall be as if the replacement had not occurred.</p> +<p class="tent"><i>Current line</i>: Unchanged.</p> +<p class="tent"><i>Current column</i>: Unchanged.</p> +<h5><a name="tag_20_40_13_12" id="tag_20_40_13_12"></a>Append</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<b>[</b><i>1addr</i><b>] </b><tt>a</tt><b>[</b><tt>ppend</tt><b>][</b><tt>!</tt><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">Enter <i>ex</i> text input mode; the input text shall be placed after the specified line. If line zero is +specified, the text shall be placed at the beginning of the edit buffer.</p> +<p class="tent">This command shall be affected by the <b>number</b> and <b>autoindent</b> edit options; following the command name +with <tt>'!'</tt> shall cause the <b>autoindent</b> edit option setting to be toggled for the duration of this command only.</p> +<p class="tent"><i>Current line</i>: Set to the last input line; if no lines were input, set to the specified line, or to the first +line of the edit buffer if a line of zero was specified, or zero if the edit buffer is empty.</p> +<p class="tent"><i>Current column</i>: Set to non-<blank>.</p> +<h5><a name="tag_20_40_13_13" id="tag_20_40_13_13"></a>Arguments</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>ar</tt><b>[</b><i>gs</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">Write the current argument list, with the current argument-list entry, if any, between <tt>'['</tt> and +<tt>']'</tt> characters.</p> +<p class="tent"><i>Current line</i>: Unchanged.</p> +<p class="tent"><i>Current column</i>: Unchanged.</p> +<h5><a name="tag_20_40_13_14" id="tag_20_40_13_14"></a>Change</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<b>[</b><i>2addr</i><b>] </b><tt>c</tt><b>[</b><tt>hange</tt><b>][</b><tt>!</tt><b>][</b><i>count</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">Enter <i>ex</i> text input mode; the input text shall replace the specified lines. The specified lines shall be +copied into the unnamed buffer, which shall become a line mode buffer.</p> +<p class="tent">This command shall be affected by the <b>number</b> and <b>autoindent</b> edit options; following the command name +with <tt>'!'</tt> shall cause the <b>autoindent</b> edit option setting to be toggled for the duration of this command only.</p> +<p class="tent"><i>Current line</i>: Set to the last input line; if no lines were input, set to the line before the first address, +or to the first line of the edit buffer if there are no lines preceding the first address, or to zero if the edit buffer is +empty.</p> +<p class="tent"><i>Current column</i>: Set to non-<blank>.</p> +<h5><a name="tag_20_40_13_15" id="tag_20_40_13_15"></a>Change Directory</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>chd</tt><b>[</b><tt>ir</tt><b>][</b><tt>!</tt><b>][</b><i>directory</i><b>]</b><tt> +cd</tt><b>[</b><tt>!</tt><b>][</b><i>directory</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">Change the current working directory to <i>directory</i>.</p> +<p class="tent">If no <i>directory</i> argument is specified, and the <i>HOME</i> environment variable is set to a non-null and +non-empty value, <i>directory</i> shall default to the value named in the <i>HOME</i> environment variable. If the <i>HOME</i> +environment variable is empty or is undefined, the default value of <i>directory</i> is implementation-defined.</p> +<p class="tent">If no <tt>'!'</tt> is appended to the command name, and the edit buffer has been modified since the last complete +write, and the current pathname does not begin with a <tt>'/'</tt>, it shall be an error.</p> +<p class="tent"><i>Current line</i>: Unchanged.</p> +<p class="tent"><i>Current column</i>: Unchanged.</p> +<h5><a name="tag_20_40_13_16" id="tag_20_40_13_16"></a>Copy</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<b>[</b><i>2addr</i><b>] </b><tt>co</tt><b>[</b><tt>py</tt><b>] </b><i>1addr </i><b>[</b><i>flags</i><b>] +[</b><i>2addr</i><b>] </b><tt>t </tt><i>1addr </i><b>[</b><i>flags</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">Copy the specified lines after the specified destination line; line zero specifies that the lines shall be placed +at the beginning of the edit buffer.</p> +<p class="tent"><i>Current line</i>: Set to the last line copied.</p> +<p class="tent"><i>Current column</i>: Set to non-<blank>.</p> +<h5><a name="tag_20_40_13_17" id="tag_20_40_13_17"></a>Delete</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<b>[</b><i>2addr</i><b>] </b><tt>d</tt><b>[</b><tt>elete</tt><b>][ </b><i>buffer</i><b>][</b><i>count</i><b>][</b><i>flags</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">Delete the specified lines into a buffer (defaulting to the unnamed buffer), which shall become a line-mode +buffer.</p> +<p class="tent">Flags can immediately follow the command name; see <a href="#tag_20_40_13_03">Command Line Parsing in ex</a> .</p> +<p class="tent"><i>Current line</i>: Set to the line following the deleted lines, or to the last line in the edit buffer if that +line is past the end of the edit buffer, or to zero if the edit buffer is empty.</p> +<p class="tent"><i>Current column</i>: Set to non-<blank>.</p> +<h5><a name="tag_20_40_13_18" id="tag_20_40_13_18"></a>Edit</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>e</tt><b>[</b><tt>dit</tt><b>][</b><tt>!</tt><b>][</b><tt>+</tt><i>command</i><b>][</b><i>file</i><b>]</b><tt> +ex</tt><b>[</b><tt>!</tt><b>][</b><tt>+</tt><i>command</i><b>][</b><i>file</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">If no <tt>'!'</tt> is appended to the command name, and the edit buffer has been modified since the last complete +write, it shall be an error.</p> +<p class="tent">If <i>file</i> is specified, replace the current contents of the edit buffer with the current contents of +<i>file</i>, and set the current pathname to <i>file</i>. If <i>file</i> is not specified, replace the current contents of the edit +buffer with the current contents of the file named by the current pathname. If for any reason the current contents of the file +cannot be accessed, the edit buffer shall be empty.</p> +<p class="tent">The <b>+</b><i>command</i> option shall be <blank>-delimited; <blank> characters within the +<b>+</b><i>command</i> can be escaped by preceding them with a <backslash> character. The <b>+</b><i>command</i> shall be +interpreted as an <i>ex</i> command immediately after the contents of the edit buffer have been replaced and the current line and +column have been set.</p> +<p class="tent">If the edit buffer is empty:</p> +<p class="tent"><i>Current line</i>: Set to 0.</p> +<p class="tent"><i>Current column</i>: Set to 1.</p> +<p class="tent">Otherwise, if executed while in <i>ex</i> command mode or if the <b>+</b><i>command</i> argument is specified:</p> +<p class="tent"><i>Current line</i>: Set to the last line of the edit buffer.</p> +<p class="tent"><i>Current column</i>: Set to non-<blank>.</p> +<p class="tent">Otherwise, if <i>file</i> is omitted or results in the current pathname:</p> +<p class="tent"><i>Current line</i>: Set to the first line of the edit buffer.</p> +<p class="tent"><i>Current column</i>: Set to non-<blank>.</p> +<p class="tent">Otherwise, if <i>file</i> is the same as the last file edited, the line and column shall be set as follows; if the +file was previously edited, the line and column may be set as follows:</p> +<p class="tent"><i>Current line</i>: Set to the last value held when that file was last edited. If this value is not a valid line +in the new edit buffer, set to the first line of the edit buffer.</p> +<p class="tent"><i>Current column</i>: If the current line was set to the last value held when the file was last edited, set to the +last value held when the file was last edited. Otherwise, or if the last value is not a valid column in the new edit buffer, set to +non-<blank>.<br></p> +<p class="tent">Otherwise:</p> +<p class="tent"><i>Current line</i>: Set to the first line of the edit buffer.</p> +<p class="tent"><i>Current column</i>: Set to non-<blank>.</p> +<h5><a name="tag_20_40_13_19" id="tag_20_40_13_19"></a>File</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>f</tt><b>[</b><tt>ile</tt><b>][</b><i>file</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">If a <i>file</i> argument is specified, the alternate pathname shall be set to the current pathname, and the +current pathname shall be set to <i>file</i>.</p> +<p class="tent">Write an informational message. If the file has a current pathname, it shall be included in this message; +otherwise, the message shall indicate that there is no current pathname. If the edit buffer contains lines, the current line number +and the number of lines in the edit buffer shall be included in this message; otherwise, the message shall indicate that the edit +buffer is empty. If the edit buffer has been modified since the last complete write, this fact shall be included in this message. +If the <b>readonly</b> edit option is set, this fact shall be included in this message. The message may contain other unspecified +information.</p> +<p class="tent"><i>Current line</i>: Unchanged.</p> +<p class="tent"><i>Current column</i>: Unchanged.</p> +<h5><a name="tag_20_40_13_20" id="tag_20_40_13_20"></a>Global</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<b>[</b><i>2addr</i><b>] </b><tt>g</tt><b>[</b><tt>lobal</tt><b>] </b><tt>/</tt><i>pattern</i><tt>/ </tt><b>[</b><i>commands</i><b>] +[</b><i>2addr</i><b>] </b><tt>v /</tt><i>pattern</i><tt>/ </tt><b>[</b><i>commands</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">The optional <tt>'!'</tt> character after the <b>global</b> command shall be the same as executing the <b>v</b> +command.</p> +<p class="tent">If <i>pattern</i> is empty (for example, <tt>"//"</tt>) or not specified, the last regular expression used in the +editor command shall be used as the <i>pattern</i>. The <i>pattern</i> can be delimited by <slash> characters (shown in the +Synopsis), as well as any non-alphanumeric or non-<blank> other than <backslash>, <vertical-line>, +<newline>, or double-quote. Within the pattern, in certain circumstances the delimiter can be used as a literal character; +see <a href="#tag_20_40_13_58">Regular Expressions in ex</a> .</p> +<p class="tent">If no lines are specified, the lines shall default to the entire file.</p> +<p class="tent">The <b>global</b> and <b>v</b> commands are logically two-pass operations. First, mark the lines within the +specified lines for which the line excluding the terminating <newline> matches (<b>global</b>) or does not match (<b>v</b> or +<b>global!</b>) the specified pattern. Second, execute the <i>ex</i> commands given by <i>commands</i>, with the current line +(<tt>'.'</tt>) set to each marked line. If an error occurs during this process, or the contents of the edit buffer are replaced +(for example, by the <i>ex</i> <b>:edit</b> command) an error message shall be written and no more commands resulting from the +execution of this command shall be processed.</p> +<p class="tent">Multiple <i>ex</i> commands can be specified by entering multiple commands on a single line using a +<vertical-line> to delimit them, or one per line, by escaping each <newline> with a <backslash>.</p> +<p class="tent">If no commands are specified:</p> +<ol> +<li class="tent">If in <i>ex</i> command mode, it shall be as if the <b>print</b> command were specified.</li> +<li class="tent">Otherwise, no command shall be executed.</li> +</ol> +<p class="tent">For the <b>append</b>, <b>change</b>, and <b>insert</b> commands, the input text shall be included as part of the +command, and the terminating <period> can be omitted if the command ends the list of commands. The <b>open</b> and +<b>visual</b> commands can be specified as one of the commands, in which case each marked line shall cause the editor to enter open +or visual mode. If open or visual mode is exited using the <a href="../utilities/vi.html"><i>vi</i></a> <b>Q</b> command, the +current line shall be set to the next marked line, and open or visual mode reentered, until the list of marked lines is +exhausted.</p> +<p class="tent">The <b>global</b>, <b>v</b>, and <b>undo</b> commands cannot be used in <i>commands</i>. Marked lines may be +deleted by commands executed for lines occurring earlier in the file than the marked lines. In this case, no commands shall be +executed for the deleted lines.</p> +<p class="tent">If the remembered search direction is not set, the <b>global</b> and <b>v</b> commands shall set it to forward.</p> +<p class="tent">The <b>autoprint</b> and <b>autoindent</b> edit options shall be inhibited for the duration of the <b>g</b> or +<b>v</b> command.</p> +<p class="tent"><i>Current line</i>: If no commands executed, set to the last marked line. Otherwise, as specified for the executed +<i>ex</i> commands.</p> +<p class="tent"><i>Current column</i>: If no commands are executed, set to non-<blank>; otherwise, as specified for the +individual <i>ex</i> commands.</p> +<h5><a name="tag_20_40_13_21" id="tag_20_40_13_21"></a>Insert</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<b>[</b><i>1addr</i><b>] </b><tt>i</tt><b>[</b><tt>nsert</tt><b>][</b><tt>!</tt><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">Enter <i>ex</i> text input mode; the input text shall be placed before the specified line. If the line is zero or +1, the text shall be placed at the beginning of the edit buffer.</p> +<p class="tent">This command shall be affected by the <b>number</b> and <b>autoindent</b> edit options; following the command name +with <tt>'!'</tt> shall cause the <b>autoindent</b> edit option setting to be toggled for the duration of this command only.</p> +<p class="tent"><i>Current line</i>: Set to the last input line; if no lines were input, set to the line before the specified line, +or to the first line of the edit buffer if there are no lines preceding the specified line, or zero if the edit buffer is +empty.</p> +<p class="tent"><i>Current column</i>: Set to non-<blank>.</p> +<h5><a name="tag_20_40_13_22" id="tag_20_40_13_22"></a>Join</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<b>[</b><i>2addr</i><b>] </b><tt>j</tt><b>[</b><tt>oin</tt><b>][</b><tt>!</tt><b>][</b><i>count</i><b>][</b><i>flags</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">If <i>count</i> is specified:</p> +<blockquote>If no address was specified, the <b>join</b> command shall behave as if <i>2addr</i> were the current line and the +current line plus <i>count</i> (.,. + <i>count</i>). +<p class="tent">If one address was specified, the <b>join</b> command shall behave as if <i>2addr</i> were the specified address +and the specified address plus <i>count</i> (<i>addr</i>,<i>addr</i> + <i>count</i>).</p> +<p class="tent">If two addresses were specified, the <b>join</b> command shall behave as if an additional address, equal to the +last address plus <i>count</i> -1 (<i>addr1</i>,<i>addr2</i>,<i>addr2</i> + <i>count</i> -1), was specified.</p> +<p class="tent">If this would result in a second address greater than the last line of the edit buffer, it shall be corrected to be +equal to the last line of the edit buffer.</p> +</blockquote> +<p class="tent">If no <i>count</i> is specified:</p> +<blockquote>If no address was specified, the <b>join</b> command shall behave as if <i>2addr</i> were the current line and the next +line (.,. +1). +<p class="tent">If one address was specified, the <b>join</b> command shall behave as if <i>2addr</i> were the specified address +and the next line (<i>addr</i>,<i>addr</i> +1).</p> +</blockquote> +<p class="tent">Join the text from the specified lines together into a single line, which shall replace the specified lines.</p> +<p class="tent">If a <tt>'!'</tt> character is appended to the command name, the <b>join</b> shall be without modification of any +line, independent of the current locale.</p> +<p class="tent">Otherwise, in the POSIX locale, set the current line to the first of the specified lines, and then, for each +subsequent line, proceed as follows:</p> +<ol> +<li class="tent">Discard leading <space> characters from the line to be joined.</li> +<li class="tent">If the line to be joined is now empty, delete it, and skip steps 3 through 5.</li> +<li class="tent">If the current line ends in a <blank>, or the first character of the line to be joined is a <tt>')'</tt> +character, join the lines without further modification.</li> +<li class="tent">If the last character of the current line is a <tt>'.'</tt>, join the lines with two <space> characters +between them.</li> +<li class="tent">Otherwise, join the lines with a single <space> between them.</li> +</ol> +<p class="tent"><i>Current line</i>: Set to the first line specified.</p> +<p class="tent"><i>Current column</i>: Set to non-<blank>.</p> +<h5><a name="tag_20_40_13_23" id="tag_20_40_13_23"></a>List</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<b>[</b><i>2addr</i><b>] </b><tt>l</tt><b>[</b><tt>ist</tt><b>][</b><i>count</i><b>][</b><i>flags</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">This command shall be equivalent to the <i>ex</i> command:</p> +<pre> +<b>[</b><i>2addr</i><b>] </b><tt>p</tt><b>[</b><tt>rint</tt><b>][</b><i>count</i><b>] </b><tt>l</tt><b>[</b><i>flags</i><b>]</b><tt> +</tt></pre> +<p class="tent">See <a href="#tag_20_40_13_31">Print</a> .</p> +<h5><a name="tag_20_40_13_24" id="tag_20_40_13_24"></a>Map</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>map</tt><b>[</b><tt>!</tt><b>][</b><i>lhs rhs</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">If <i>lhs</i> and <i>rhs</i> are not specified:</p> +<ol> +<li class="tent">If <tt>'!'</tt> is specified, write the current list of text input mode maps.</li> +<li class="tent">Otherwise, write the current list of command mode maps.</li> +<li class="tent">Do nothing more.</li> +</ol> +<p class="tent">Implementations may restrict the set of characters accepted in <i>lhs</i> or <i>rhs</i>, except that printable +characters and <blank> characters shall not be restricted. Additional restrictions shall be implementation-defined. In both +<i>lhs</i> and <i>rhs</i>, any character can be escaped with a <control>-V, in which case the character shall not be used to +delimit <i>lhs</i> from <i>rhs</i>, and the escaping <control>-V shall be discarded.</p> +<p class="tent">If the character <tt>'!'</tt> is appended to the <b>map</b> command name, the mapping shall be effective during +open or visual text input mode rather than <b>open</b> or <b>visual</b> command mode. This allows <i>lhs</i> to have two different +<b>map</b> definitions at the same time: one for command mode and one for text input mode.<br></p> +<p class="tent">For command mode mappings:</p> +<blockquote>When the <i>lhs</i> is entered as any part of a <a href="../utilities/vi.html"><i>vi</i></a> command in open or visual +mode (but not as part of the arguments to the command), the action shall be as if the corresponding <i>rhs</i> had been entered. +<p class="tent">If any character in the command, other than the first, is escaped using a <control>-V character, that +character shall not be part of a match to an <i>lhs</i>.</p> +<p class="tent">It is unspecified whether implementations shall support <b>map</b> commands where the <i>lhs</i> is more than a +single character in length, where the first character of the <i>lhs</i> is printable.</p> +</blockquote> +<p class="tent"></p> +<blockquote>If <i>lhs</i> contains more than one character and the first character is <tt>'#'</tt>, followed by a sequence of +digits corresponding to a numbered function key, then when this function key is typed it shall be mapped to <i>rhs</i>. Characters +other than digits following a <tt>'#'</tt> character also represent the function key named by the characters in the <i>lhs</i> +following the <tt>'#'</tt> and may be mapped to <i>rhs</i>. It is unspecified how function keys are named or what function keys are +supported.</blockquote> +<p class="tent">For text input mode mappings:</p> +<blockquote>When the <i>lhs</i> is entered as any part of text entered in open or visual text input modes, the action shall be as +if the corresponding <i>rhs</i> had been entered. +<p class="tent">If any character in the input text is escaped using a <control>-V character, that character shall not be part +of a match to an <i>lhs</i>.</p> +<p class="tent">It is unspecified whether the <i>lhs</i> text entered for subsequent <b>map</b> or <b>unmap</b> commands is +replaced with the <i>rhs</i> text for the purposes of the screen display; regardless of whether or not the display appears as if +the corresponding <i>rhs</i> text was entered, the effect of the command shall be as if the <i>lhs</i> text was entered.</p> +</blockquote> +<p class="tent">If only part of the <i>lhs</i> is entered, it is unspecified how long the editor will wait for additional, possibly +matching characters before treating the already entered characters as not matching the <i>lhs</i>.</p> +<p class="tent">The <i>rhs</i> characters shall themselves be subject to remapping, unless otherwise specified by the <b>remap</b> +edit option, except that if the characters in <i>lhs</i> occur as prefix characters in <i>rhs</i>, those characters shall not be +remapped.</p> +<p class="tent">On block-mode terminals, the mapping need not occur immediately (for example, it may occur after the terminal +transmits a group of characters to the system), but it shall achieve the same results as if it occurred immediately.</p> +<p class="tent"><i>Current line</i>: Unchanged.</p> +<p class="tent"><i>Current column</i>: Unchanged.</p> +<h5><a name="tag_20_40_13_25" id="tag_20_40_13_25"></a>Mark</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<b>[</b><i>1addr</i><b>] </b><tt>ma</tt><b>[</b><tt>rk</tt><b>] </b><i>character +</i><b>[</b><i>1addr</i><b>] </b><tt>k </tt><i>character</i><tt> +</tt></pre></dd> +</dl> +<p class="tent">Implementations shall support <i>character</i> values of a single lowercase letter of the POSIX locale and the +backquote and single-quote characters; support of other characters is implementation-defined.</p> +<p class="tent">If executing the <a href="../utilities/vi.html"><i>vi</i></a> <b>m</b> command, set the specified mark to the +current line and 1-based numbered character referenced by the current column, if any; otherwise, column position 1.</p> +<p class="tent">Otherwise, set the specified mark to the specified line and 1-based numbered first non-<blank> +non-<newline> in the line, if any; otherwise, the last non-<newline> in the line, if any; otherwise, column position +1.</p> +<p class="tent">The mark shall remain associated with the line until the mark is reset or the line is deleted. If a deleted line is +restored by a subsequent <b>undo</b> command, any marks previously associated with the line, which have not been reset, shall be +restored as well. Any use of a mark not associated with a current line in the edit buffer shall be an error.</p> +<p class="tent">The marks <b>`</b> and <b>'</b> shall be set as described previously, immediately before the following events occur +in the editor:</p> +<ol> +<li class="tent">The use of <tt>'$'</tt> as an <i>ex</i> address</li> +<li class="tent">The use of a positive decimal number as an <i>ex</i> address</li> +<li class="tent">The use of a search command as an <i>ex</i> address</li> +<li class="tent">The use of a mark reference as an <i>ex</i> address</li> +<li class="tent">The use of the following open and visual mode commands: <control>-], <b>%</b>, <b>(</b>, <b>)</b>, <b>[</b>, +<b>]</b>, <b>{</b>, <b>}</b></li> +<li class="tent">The use of the following open and visual mode commands: <b>'</b>, <b>G</b>, <b>H</b>, <b>L</b>, <b>M</b>, <b>z</b> +if the current line will change as a result of the command</li> +<li class="tent">The use of the open and visual mode commands: <b>/</b>, <b>?</b>, <b>N</b>, <b>`</b>, <b>n</b> if the current line +or column will change as a result of the command</li> +<li class="tent">The use of the <i>ex</i> mode commands: <b>z</b>, <b>undo</b>, <b>global</b>, <b>v</b></li> +</ol> +<p class="tent">For rules 1., 2., 3., and 4., the <b>`</b> and <b>'</b> marks shall not be set if the <i>ex</i> command is parsed +as specified by rule 6.a. in <a href="#tag_20_40_13_03">Command Line Parsing in ex</a> .</p> +<p class="tent">For rules 5., 6., and 7., the <b>`</b> and <b>'</b> marks shall not be set if the commands are used as motion +commands in open and visual mode.</p> +<p class="tent">For rules 1., 2., 3., 4., 5., 6., 7., and 8., the <b>`</b> and <b>'</b> marks shall not be set if the command +fails.</p> +<p class="tent">The <b>`</b> and <b>'</b> marks shall be set as described previously, each time the contents of the edit buffer are +replaced (including the editing of the initial buffer), if in open or visual mode, or if in <b>ex</b> mode and the edit buffer is +not empty, before any commands or movements (including commands or movements specified by the <b>-c</b> or <b>-t</b> options or the +<b>+</b><i>command</i> argument) are executed on the edit buffer. If in open or visual mode, the marks shall be set as if executing +the <a href="../utilities/vi.html"><i>vi</i></a> <b>m</b> command; otherwise, as if executing the <i>ex</i> <b>mark</b> +command.</p> +<p class="tent">When changing from <b>ex</b> mode to open or visual mode, if the <b>`</b> and <b>'</b> marks are not already set, +the <b>`</b> and <b>'</b> marks shall be set as described previously.</p> +<p class="tent"><i>Current line</i>: Unchanged.</p> +<p class="tent"><i>Current column</i>: Unchanged.</p> +<h5><a name="tag_20_40_13_26" id="tag_20_40_13_26"></a>Move</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<b>[</b><i>2addr</i><b>] </b><tt>m</tt><b>[</b><tt>ove</tt><b>] </b><i>1addr</i><tt> </tt><b>[</b><i>flags</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">Move the specified lines after the specified destination line. A destination of line zero specifies that the lines +shall be placed at the beginning of the edit buffer. It shall be an error if the destination line is within the range of lines to +be moved.</p> +<p class="tent"><i>Current line</i>: Set to the last of the moved lines.</p> +<p class="tent"><i>Current column</i>: Set to non-<blank>.</p> +<h5><a name="tag_20_40_13_27" id="tag_20_40_13_27"></a>Next</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>n</tt><b>[</b><tt>ext</tt><b>][</b><tt>!</tt><b>][</b><tt>+</tt><i>command</i><b>][</b><i>file </i><tt>...</tt><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">If no <tt>'!'</tt> is appended to the command name, and the edit buffer has been modified since the last complete +write, it shall be an error, unless the file is successfully written as specified by the <b>autowrite</b> option.<br></p> +<p class="tent">If one or more files is specified:</p> +<ol> +<li class="tent">Set the argument list to the specified filenames.</li> +<li class="tent">Set the current argument list reference to be the first entry in the argument list.</li> +<li class="tent">Set the current pathname to the first filename specified.</li> +</ol> +<p class="tent">Otherwise:</p> +<ol> +<li class="tent">It shall be an error if there are no more filenames in the argument list after the filename currently +referenced.</li> +<li class="tent">Set the current pathname and the current argument list reference to the filename after the filename currently +referenced in the argument list.</li> +</ol> +<p class="tent">Replace the contents of the edit buffer with the contents of the file named by the current pathname. If for any +reason the contents of the file cannot be accessed, the edit buffer shall be empty.</p> +<p class="tent">This command shall be affected by the <b>autowrite</b> and <b>writeany</b> edit options.</p> +<p class="tent">The <b>+</b><i>command</i> option shall be <blank>-delimited; <blank> characters can be escaped by +preceding them with a <backslash> character. The <b>+</b><i>command</i> shall be interpreted as an <i>ex</i> command +immediately after the contents of the edit buffer have been replaced and the current line and column have been set.</p> +<p class="tent"><i>Current line</i>: Set as described for the <b>edit</b> command.</p> +<p class="tent"><i>Current column</i>: Set as described for the <b>edit</b> command.</p> +<h5><a name="tag_20_40_13_28" id="tag_20_40_13_28"></a>Number</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<b>[</b><i>2addr</i><b>] </b><tt>nu</tt><b>[</b><tt>mber</tt><b>][</b><i>count</i><b>][</b><i>flags</i><b>] +[</b><i>2addr</i><b>] </b><tt>#</tt><b>[</b><i>count</i><b>][</b><i>flags</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">These commands shall be equivalent to the <i>ex</i> command:</p> +<pre> +<b>[</b><i>2addr</i><b>] </b><tt>p</tt><b>[</b><tt>rint</tt><b>][</b><i>count</i><b>] </b><tt>#</tt><b>[</b><i>flags</i><b>]</b><tt> +</tt></pre> +<p class="tent">See <a href="#tag_20_40_13_31">Print</a> .</p> +<h5><a name="tag_20_40_13_29" id="tag_20_40_13_29"></a>Open</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<b>[</b><i>1addr</i><b>] </b><tt>o</tt><b>[</b><tt>pen</tt><b>]</b><tt> /</tt><i>pattern</i><tt>/ </tt><b>[</b><i>flags</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">This command need not be supported on block-mode terminals or terminals with insufficient capabilities. If standard +input, standard output, or standard error are not terminal devices, the results are unspecified.</p> +<p class="tent">Enter open mode.</p> +<p class="tent">The trailing delimiter can be omitted from <i>pattern</i> at the end of the command line. If <i>pattern</i> is +empty (for example, <tt>"//"</tt>) or not specified, the last regular expression used in the editor shall be used as the pattern. +The pattern can be delimited by <slash> characters (shown in the Synopsis), as well as any alphanumeric, or non-<blank> +other than <backslash>, <vertical-line>, <newline>, or double-quote.</p> +<p class="tent"><i>Current line</i>: Set to the specified line.</p> +<p class="tent"><i>Current column</i>: Set to non-<blank>.</p> +<h5><a name="tag_20_40_13_30" id="tag_20_40_13_30"></a>Preserve</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>pre</tt><b>[</b><tt>serve</tt><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">Save the edit buffer in a form that can later be recovered by using the <b>-r</b> option or by using the <i>ex</i> +<b>recover</b> command. After the file has been preserved, a mail message shall be sent to the user. This message shall be readable +by invoking the <a href="../utilities/mailx.html"><i>mailx</i></a> utility. The message shall contain the name of the file, the +time of preservation, and an <i>ex</i> command that could be used to recover the file. Additional information may be included in +the mail message.</p> +<p class="tent"><i>Current line</i>: Unchanged.</p> +<p class="tent"><i>Current column</i>: Unchanged.</p> +<h5><a name="tag_20_40_13_31" id="tag_20_40_13_31"></a>Print</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<b>[</b><i>2addr</i><b>] </b><tt>p</tt><b>[</b><tt>rint</tt><b>][</b><i>count</i><b>][</b><i>flags</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">Write the addressed lines. The behavior is unspecified if the number of columns on the display is less than the +number of columns required to write any single character in the lines being written.</p> +<p class="tent">Non-printable characters, except for the <tab>, shall be written as implementation-defined multi-character +sequences.</p> +<p class="tent">If the <b>#</b> flag is specified or the <b>number</b> edit option is set, each line shall be preceded by its line +number in the following format:</p> +<pre> +<tt>"%6dΔΔ", <</tt><i>line number</i><tt>> +</tt></pre> +<p class="tent">If the <b>l</b> flag is specified or the <b>list</b> edit option is set:</p> +<ol> +<li class="tent">The characters listed in XBD <a href="../basedefs/V1_chap05.html#tagtcjh_2"><i>Escape Sequences and Associated +Actions</i></a> shall be written as the corresponding escape sequence.</li> +<li class="tent">Non-printable characters not in XBD <a href="../basedefs/V1_chap05.html#tagtcjh_2"><i>Escape Sequences and +Associated Actions</i></a> shall be written as one three-digit octal number (with a preceding <backslash>) for each byte in +the character (most significant byte first).</li> +<li class="tent">The end of each line shall be marked with a <tt>'$'</tt>, and literal <tt>'$'</tt> characters within the line +shall be written with a preceding <backslash>.</li> +</ol> +<p class="tent">Long lines shall be folded; the length at which folding occurs is unspecified, but should be appropriate for the +output terminal, considering the number of columns of the terminal.</p> +<p class="tent">If a line is folded, and the <b>l</b> flag is not specified and the <b>list</b> edit option is not set, it is +unspecified whether a multi-column character at the folding position is separated; it shall not be discarded.</p> +<p class="tent"><i>Current line</i>: Set to the last written line.</p> +<p class="tent"><i>Current column</i>: Unchanged if the current line is unchanged; otherwise, set to non-<blank>.</p> +<h5><a name="tag_20_40_13_32" id="tag_20_40_13_32"></a>Put</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<b>[</b><i>1addr</i><b>] </b><tt>pu</tt><b>[</b><tt>t</tt><b>][ </b><i>buffer</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">Append text from the specified buffer (by default, the unnamed buffer) to the specified line; line zero specifies +that the text shall be placed at the beginning of the edit buffer. Each portion of a line in the buffer shall become a new line in +the edit buffer, regardless of the mode of the buffer.</p> +<p class="tent"><i>Current line</i>: Set to the last line entered into the edit buffer.</p> +<p class="tent"><i>Current column</i>: Set to non-<blank>.</p> +<h5><a name="tag_20_40_13_33" id="tag_20_40_13_33"></a>Quit</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>q</tt><b>[</b><tt>uit</tt><b>][</b><tt>!</tt><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">If no <tt>'!'</tt> is appended to the command name:</p> +<ol> +<li class="tent">If the edit buffer has been modified since the last complete write, it shall be an error.</li> +<li class="tent">If there are filenames in the argument list after the filename currently referenced, and the last command was not +a <b>quit</b>, <b>wq</b>, <b>xit</b>, or <b>ZZ</b> (see <a href="../utilities/vi.html#tag_20_146_13_87"><i>Exit</i></a> ) command, +it shall be an error.</li> +</ol> +<p class="tent">Otherwise, terminate the editing session.</p> +<h5><a name="tag_20_40_13_34" id="tag_20_40_13_34"></a>Read</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<b>[</b><i>1addr</i><b>] </b><tt>r</tt><b>[</b><tt>ead</tt><b>][</b><tt>!</tt><b>][</b><i>file</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">If <tt>'!'</tt> is not the first non-<blank> to follow the command name, a copy of the specified file shall +be appended into the edit buffer after the specified line; line zero specifies that the copy shall be placed at the beginning of +the edit buffer. The number of lines and bytes read shall be written. If no <i>file</i> is named, the current pathname shall be the +default. If there is no current pathname, then <i>file</i> shall become the current pathname. If there is no current pathname or +<i>file</i> operand, it shall be an error. Specifying a <i>file</i> that is not of type regular shall have unspecified results.</p> +<p class="tent">Otherwise, if <i>file</i> is preceded by <tt>'!'</tt>, the rest of the line after the <tt>'!'</tt> shall have +<tt>'%'</tt>, <tt>'#'</tt>, and <tt>'!'</tt> characters expanded as described in <a href="#tag_20_40_13_03">Command Line Parsing in +ex</a> .</p> +<p class="tent">The <i>ex</i> utility shall then pass two arguments to the program named by the shell edit option; the first shall +be <b>-c</b> and the second shall be the expanded arguments to the <b>read</b> command as a single argument. The standard input of +the program shall be set to the standard input of the <i>ex</i> program when it was invoked. The standard error and standard output +of the program shall be appended into the edit buffer after the specified line.</p> +<p class="tent">Each line in the copied file or program output (as delimited by <newline> characters or the end of the file +or output if it is not immediately preceded by a <newline>), shall be a separate line in the edit buffer. Any occurrences of +<carriage-return> and <newline> pairs in the output shall be treated as single <newline> characters.</p> +<p class="tent">The special meaning of the <tt>'!'</tt> following the <b>read</b> command can be overridden by escaping it with a +<backslash> character.</p> +<p class="tent"><i>Current line</i>: If no lines are added to the edit buffer, unchanged. Otherwise, if in open or visual mode, set +to the first line entered into the edit buffer. Otherwise, set to the last line entered into the edit buffer.</p> +<p class="tent"><i>Current column</i>: Set to non-<blank>.</p> +<h5><a name="tag_20_40_13_35" id="tag_20_40_13_35"></a>Recover</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>rec</tt><b>[</b><tt>over</tt><b>][</b><tt>!</tt><b>] </b><i>file</i><tt> +</tt></pre></dd> +</dl> +<p class="tent">If no <tt>'!'</tt> is appended to the command name, and the edit buffer has been modified since the last complete +write, it shall be an error.</p> +<p class="tent">If no <i>file</i> operand is specified, then the current pathname shall be used. If there is no current pathname or +<i>file</i> operand, it shall be an error.</p> +<p class="tent">If no recovery information has previously been saved about <i>file</i>, the <b>recover</b> command shall behave +identically to the <b>edit</b> command, and an informational message to this effect shall be written.</p> +<p class="tent">Otherwise, set the current pathname to <i>file</i>, and replace the current contents of the edit buffer with the +recovered contents of <i>file</i>. If there are multiple instances of the file to be recovered, the one most recently saved shall +be recovered, and an informational message that there are previous versions of the file that can be recovered shall be written. The +editor shall behave as if the contents of the edit buffer have already been modified.</p> +<p class="tent"><i>Current file</i>: Set as described for the <b>edit</b> command.</p> +<p class="tent"><i>Current column</i>: Set as described for the <b>edit</b> command.</p> +<h5><a name="tag_20_40_13_36" id="tag_20_40_13_36"></a>Rewind</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>rew</tt><b>[</b><tt>ind</tt><b>][</b><tt>!</tt><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">If no <tt>'!'</tt> is appended to the command name, and the edit buffer has been modified since the last complete +write, it shall be an error, unless the file is successfully written as specified by the <b>autowrite</b> option.</p> +<p class="tent">If the argument list is empty, it shall be an error.</p> +<p class="tent">The current argument list reference and the current pathname shall be set to the first filename in the argument +list.</p> +<p class="tent">Replace the contents of the edit buffer with the contents of the file named by the current pathname. If for any +reason the contents of the file cannot be accessed, the edit buffer shall be empty.</p> +<p class="tent">This command shall be affected by the <b>autowrite</b> and <b>writeany</b> edit options.</p> +<p class="tent"><i>Current line</i>: Set as described for the <b>edit</b> command.</p> +<p class="tent"><i>Current column</i>: Set as described for the <b>edit</b> command.</p> +<h5><a name="tag_20_40_13_37" id="tag_20_40_13_37"></a>Set</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>se</tt><b>[</b><tt>t</tt><b>][ </b><i>option</i><b>[</b><tt>=</tt><b>[</b><i>value</i><b>]]</b><tt> ...</tt><b>][ </b><tt>no</tt><i>option</i><tt> ...</tt><b>][ </b><i>option</i><tt>? ...</tt><b>][ </b><tt>all</tt><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">When no arguments are specified, write the value of the <b>term</b> edit option and those options whose values have +been changed from the default settings; when the argument <i>all</i> is specified, write all of the option values.</p> +<p class="tent">Giving an option name followed by the character <tt>'?'</tt> shall cause the current value of that option to be +written. The <tt>'?'</tt> can be separated from the option name by zero or more <blank> characters. The <tt>'?'</tt> shall be +necessary only for Boolean valued options. Boolean options can be given values by the form <b>set</b> <i>option</i> to turn them on +or <b>set</b> <b>no</b><i>option</i> to turn them off; string and numeric options can be assigned by the form <b>set</b> +<i>option</i>=<i>value</i>. Any <blank> characters in strings can be included as is by preceding each <blank> with an +escaping <backslash>. More than one option can be set or listed by a single set command by specifying multiple arguments, +each separated from the next by one or more <blank> characters. Arguments can appear in any order and shall be processed in +the specified order.</p> +<p class="tent">See <a href="#tag_20_40_13_60">Edit Options in ex</a> for details about specific options.</p> +<p class="tent"><i>Current line</i>: Unchanged.</p> +<p class="tent"><i>Current column</i>: Unchanged.</p> +<h5><a name="tag_20_40_13_38" id="tag_20_40_13_38"></a>Shell</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>sh</tt><b>[</b><tt>ell</tt><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">Invoke the program named in the <b>shell</b> edit option with the single argument <b>-i</b> (interactive mode). +Editing shall be resumed when the program exits.</p> +<p class="tent"><i>Current line</i>: Unchanged.</p> +<p class="tent"><i>Current column</i>: Unchanged.</p> +<h5><a name="tag_20_40_13_39" id="tag_20_40_13_39"></a>Source</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>so</tt><b>[</b><tt>urce</tt><b>] </b><i>file</i><tt> +</tt></pre></dd> +</dl> +<p class="tent">Read and execute <i>ex</i> commands from <i>file</i>. Lines in the file that are blank lines shall be ignored.</p> +<p class="tent"><i>Current line</i>: As specified for the individual <i>ex</i> commands.</p> +<p class="tent"><i>Current column</i>: As specified for the individual <i>ex</i> commands.</p> +<h5><a name="tag_20_40_13_40" id="tag_20_40_13_40"></a>Substitute</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<b>[</b><i>2addr</i><b>] </b><tt>s</tt><b>[</b><tt>ubstitute</tt><b>][</b><tt>/</tt><i>pattern</i><tt>/</tt><i>repl</i><tt>/</tt><b>][</b><i>options</i><b>][</b><i>count</i><b>][</b><i>flags</i><b>]</b><tt> +<br> +</tt><b>[</b><i>2addr</i><b>] </b><tt>&</tt><b>[</b><i>options</i><b>][</b><i>count</i><b>][</b><i>flags</i><b>]</b><tt> +<br> +</tt><b>[</b><i>2addr</i><b>] </b><tt>~</tt><b>[</b><i>options</i><b>][</b><i>count</i><b>][</b><i>flags</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">Replace the first instance of the pattern <i>pattern</i> by the string <i>repl</i> on each specified line. (See +<a href="#tag_20_40_13_58">Regular Expressions in ex</a> and <a href="#tag_20_40_13_59">Replacement Strings in ex</a> .) Any +non-alphabetic, non-<blank> delimiter other than <backslash>, <tt>'|'</tt>, <newline>, or double-quote can be +used instead of <tt>'/'</tt>. Within the pattern, in certain circumstances the delimiter can be used as a literal character; see +<a href="#tag_20_40_13_58">Regular Expressions in ex</a> . Within the replacement, the delimiter shall not terminate the +replacement if it is the second character of an escape sequence (see XBD <a href="../basedefs/V1_chap09.html#tag_09_01"><i>9.1 +Regular Expression Definitions</i></a> ) and the escaped delimiter shall be treated as that literal character in the replacement +(losing any special meaning it would have had if it was not used as the delimiter and was not escaped). It shall be an error if the +substitution fails on every addressed line.</p> +<p class="tent">The trailing delimiter can be omitted from <i>pattern</i> or from <i>repl</i> at the end of the command line. If +both <i>pattern</i> and <i>repl</i> are not specified or are empty (for example, <tt>"//"</tt>), the last <b>s</b> command shall be +repeated. If only <i>pattern</i> is not specified or is empty, the last regular expression used in the editor shall be used as the +pattern. If only <i>repl</i> is not specified or is empty, the pattern shall be replaced by nothing. If the entire replacement +pattern is <tt>'%'</tt>, the last replacement pattern to an <b>s</b> command shall be used.</p> +<p class="tent">Entering a <carriage-return> in <i>repl</i> (which requires an escaping <backslash> in <i>ex</i> mode +and an escaping <control>-V in open or <a href="../utilities/vi.html"><i>vi</i></a> mode) shall split the line at that point, +creating a new line in the edit buffer. The <carriage-return> shall be discarded.</p> +<p class="tent">If <i>options</i> includes the letter <tt>'g'</tt> (<b>global</b>), all non-overlapping instances of the pattern in +the line shall be replaced.</p> +<p class="tent">If <i>options</i> includes the letter <tt>'c'</tt> (<b>confirm</b>), then before each substitution the line shall +be written; the written line shall reflect all previous substitutions. On the following line, <space> characters shall be +written beneath the characters from the line that are before the <i>pattern</i> to be replaced, and <tt>'^'</tt> characters written +beneath the characters included in the <i>pattern</i> to be replaced. The <i>ex</i> utility shall then wait for a response from the +user. An affirmative response shall cause the substitution to be done, while any other input shall not make the substitution. An +affirmative response shall consist of a line with the affirmative response (as defined by the current locale) at the beginning of +the line. This line shall be subject to editing in the same way as the <i>ex</i> command line.</p> +<p class="tent">If interrupted (see the ASYNCHRONOUS EVENTS section), any modifications confirmed by the user shall be preserved in +the edit buffer after the interrupt.</p> +<p class="tent">If the remembered search direction is not set, the <b>s</b> command shall set it to forward.</p> +<p class="tent">In the second Synopsis, the <b>&</b> command shall repeat the previous substitution, as if the <b>&</b> command +were replaced by:</p> +<pre> +<tt>s/</tt><i>pattern</i><tt>/</tt><i>repl</i><tt>/ +</tt></pre> +<p class="tent">where <i>pattern</i> and <i>repl</i> are as specified in the previous <b>s</b>, <b>&</b>, or <b>~</b> command.</p> +<p class="tent">In the third Synopsis, the <b>~</b> command shall repeat the previous substitution, as if the <tt>'~'</tt> were +replaced by:</p> +<pre> +<tt>s/</tt><i>pattern</i><tt>/</tt><i>repl</i><tt>/ +</tt></pre> +<p class="tent">where <i>pattern</i> shall be the last regular expression specified to the editor, and <i>repl</i> shall be from +the previous substitution (including <b>&</b> and <b>~</b>) command.</p> +<p class="tent">These commands shall be affected by the <i>LC_MESSAGES</i> environment variable.</p> +<p class="tent"><i>Current line</i>: Set to the last line in which a substitution occurred, or, unchanged if no substitution +occurred.</p> +<p class="tent"><i>Current column</i>: Set to non-<blank>.</p> +<h5><a name="tag_20_40_13_41" id="tag_20_40_13_41"></a>Suspend</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>su</tt><b>[</b><tt>spend</tt><b>][</b><tt>!</tt><b>]</b><tt> +st</tt><b>[</b><tt>op</tt><b>][</b><tt>!</tt><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">Allow control to return to the invoking process; <i>ex</i> shall suspend itself as if it had received the SIGTSTP +signal. The suspension shall occur only if job control is enabled in the invoking shell (see the description of <a href= +"../utilities/V3_chap02.html#set"><i>set</i></a> <b>-m</b>).</p> +<p class="tent">These commands shall be affected by the <b>autowrite</b> and <b>writeany</b> edit options.</p> +<p class="tent">The current <b>susp</b> character (see <a href="../utilities/stty.html#"><i>stty</i></a> ) shall be equivalent to +the <b>suspend</b> command.</p> +<h5><a name="tag_20_40_13_42" id="tag_20_40_13_42"></a>Tag</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>ta</tt><b>[</b><tt>g</tt><b>][</b><tt>!</tt><b>] </b><i>tagstring</i><tt> +</tt></pre></dd> +</dl> +<p class="tent">The results are unspecified if the format of a tags file is not as specified by the <a href= +"../utilities/ctags.html"><i>ctags</i></a> utility (see <a href="../utilities/ctags.html#"><i>ctags</i></a> ) description.</p> +<p class="tent">The <b>tag</b> command shall search for <i>tagstring</i> in the tag files referred to by the <b>tag</b> edit +option, in the order they are specified, until a reference to <i>tagstring</i> is found. Files shall be searched from beginning to +end. If no reference is found, it shall be an error and an error message to this effect shall be written. If the reference is not +found, or if an error occurs while processing a file referred to in the <b>tag</b> edit option, it shall be an error, and an error +message shall be written at the first occurrence of such an error.</p> +<p class="tent">Otherwise, if the tags file contained a pattern, the pattern shall be treated as a regular expression used in the +editor; for example, for the purposes of the <b>s</b> command.</p> +<p class="tent">If the <i>tagstring</i> is in a file with a different name than the current pathname, set the current pathname to +the name of that file, and replace the contents of the edit buffer with the contents of that file. In this case, if no <tt>'!'</tt> +is appended to the command name, and the edit buffer has been modified since the last complete write, it shall be an error, unless +the file is successfully written as specified by the <b>autowrite</b> option.</p> +<p class="tent">This command shall be affected by the <b>autowrite</b>, <b>tag</b>, <b>taglength</b>, and <b>writeany</b> edit +options.</p> +<p class="tent"><i>Current line</i>: If the tags file contained a line number, set to that line number. If the line number is +larger than the last line in the edit buffer, an error message shall be written and the current line shall be set as specified for +the <b>edit</b> command.</p> +<p class="tent">If the tags file contained a pattern, set to the first occurrence of the pattern in the file. If no matching +pattern is found, an error message shall be written and the current line shall be set as specified for the <b>edit</b> command.</p> +<p class="tent"><i>Current column</i>: If the tags file contained a line-number reference and that line-number was not larger than +the last line in the edit buffer, or if the tags file contained a pattern and that pattern was found, set to non-<blank>. +Otherwise, set as specified for the <b>edit</b> command.</p> +<h5><a name="tag_20_40_13_43" id="tag_20_40_13_43"></a>Unabbreviate</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>una</tt><b>[</b><tt>bbrev</tt><b>] </b><i>lhs</i><tt> +</tt></pre></dd> +</dl> +<p class="tent">If <i>lhs</i> is not an entry in the current list of abbreviations (see <a href="#tag_20_40_13_11">Abbreviate</a> +), it shall be an error. Otherwise, delete <i>lhs</i> from the list of abbreviations.</p> +<p class="tent"><i>Current line</i>: Unchanged.</p> +<p class="tent"><i>Current column</i>: Unchanged.</p> +<h5><a name="tag_20_40_13_44" id="tag_20_40_13_44"></a>Undo</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>u</tt><b>[</b><tt>ndo</tt><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">Reverse the changes made by the last command that modified the contents of the edit buffer, including <b>undo</b>. +For this purpose, the <b>global</b>, <b>v</b>, <b>open</b>, and <b>visual</b> commands, and commands resulting from buffer +executions and mapped character expansions, are considered single commands.</p> +<p class="tent">If no action that can be undone preceded the <b>undo</b> command, it shall be an error.</p> +<p class="tent">If the <b>undo</b> command restores lines that were marked, the mark shall also be restored unless it was reset +subsequent to the deletion of the lines.</p> +<p class="tent"><i>Current line</i>:</p> +<ol> +<li class="tent">If lines are added or changed in the file, set to the first line added or changed.</li> +<li class="tent">Set to the line before the first line deleted, if it exists.</li> +<li class="tent">Set to 1 if the edit buffer is not empty.</li> +<li class="tent">Set to zero.</li> +</ol> +<p class="tent"><i>Current column</i>: Set to non-<blank>.</p> +<h5><a name="tag_20_40_13_45" id="tag_20_40_13_45"></a>Unmap</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>unm</tt><b>[</b><tt>ap</tt><b>][</b><tt>!</tt><b>] </b><i>lhs</i><tt> +</tt></pre></dd> +</dl> +<p class="tent">If <tt>'!'</tt> is appended to the command name, and if <i>lhs</i> is not an entry in the list of text input mode +map definitions, it shall be an error. Otherwise, delete <i>lhs</i> from the list of text input mode map definitions.</p> +<p class="tent">If no <tt>'!'</tt> is appended to the command name, and if <i>lhs</i> is not an entry in the list of command mode +map definitions, it shall be an error. Otherwise, delete <i>lhs</i> from the list of command mode map definitions.</p> +<p class="tent"><i>Current line</i>: Unchanged.</p> +<p class="tent"><i>Current column</i>: Unchanged.</p> +<h5><a name="tag_20_40_13_46" id="tag_20_40_13_46"></a>Version</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>ve</tt><b>[</b><tt>rsion</tt><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">Write a message containing version information for the editor. The format of the message is unspecified.</p> +<p class="tent"><i>Current line</i>: Unchanged.</p> +<p class="tent"><i>Current column</i>: Unchanged.</p> +<h5><a name="tag_20_40_13_47" id="tag_20_40_13_47"></a>Visual</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<b>[</b><i>1addr</i><b>] </b><tt>vi</tt><b>[</b><tt>sual</tt><b>][</b><i>type</i><b>][</b><i>count</i><b>][</b><i>flags</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">If <i>ex</i> is currently in open or visual mode, the Synopsis and behavior of the visual command shall be the same +as the <b>edit</b> command, as specified by <a href="#tag_20_40_13_18">Edit</a> .</p> +<p class="tent">Otherwise, this command need not be supported on block-mode terminals or terminals with insufficient capabilities. +If standard input, standard output, or standard error are not terminal devices, the results are unspecified.</p> +<p class="tent">If <i>count</i> is specified, the value of the <b>window</b> edit option shall be set to <i>count</i> (as described +in <a href="#tag_20_40_13_93">window</a> ). If the <tt>'^'</tt> type character was also specified, the <b>window</b> edit option +shall be set before being used by the type character.</p> +<p class="tent">Enter visual mode. If <i>type</i> is not specified, it shall be as if a <i>type</i> of <tt>'+'</tt> was specified. +The <i>type</i> shall cause the following effects:</p> +<dl compact> +<dd></dd> +<dt><tt>+</tt></dt> +<dd>Place the beginning of the specified line at the top of the display.</dd> +<dt><tt>-</tt></dt> +<dd>Place the end of the specified line at the bottom of the display.</dd> +<dt><tt>.</tt></dt> +<dd>Place the beginning of the specified line in the middle of the display.</dd> +<dt><tt>^</tt></dt> +<dd>If the specified line is less than or equal to the value of the <b>window</b> edit option, set the line to 1; otherwise, +decrement the line by the value of the <b>window</b> edit option minus 1. Place the beginning of this line as close to the bottom +of the displayed lines as possible, while still displaying the value of the <b>window</b> edit option number of lines.</dd> +</dl> +<p class="tent"><i>Current line</i>: Set to the specified line.</p> +<p class="tent"><i>Current column</i>: Set to non-<blank>.</p> +<h5><a name="tag_20_40_13_48" id="tag_20_40_13_48"></a>Write</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<b>[</b><i>2addr</i><b>] </b><tt>w</tt><b>[</b><tt>rite</tt><b>][</b><tt>!</tt><b>][</b><tt>>></tt><b>][</b><i>file</i><b>] +[</b><i>2addr</i><b>] </b><tt>w</tt><b>[</b><tt>rite</tt><b>][</b><tt>!</tt><b>][</b><i>file</i><b>] +[</b><i>2addr</i><b>] </b><tt>wq</tt><b>[</b><tt>!</tt><b>][</b><tt>>></tt><b>][</b><i>file</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">If no lines are specified, the lines shall default to the entire file.</p> +<p class="tent">The command <b>wq</b> shall be equivalent to a <b>write</b> command followed by a <b>quit</b> command; <b>wq!</b> +shall be equivalent to <b>write!</b> followed by <b>quit</b>. In both cases, if the <b>write</b> command fails, the <b>quit</b> +shall not be attempted.</p> +<p class="tent">If the command name is not followed by one or more <blank> characters, or <i>file</i> is not preceded by a +<tt>'!'</tt> character, the <b>write</b> shall be to a file.</p> +<ol> +<li class="tent">If the <b>>></b> argument is specified, and the file already exists, the lines shall be appended to the file +instead of replacing its contents. If the <b>>></b> argument is specified, and the file does not already exist, it is +unspecified whether the write shall proceed as if the <b>>></b> argument had not been specified or if the write shall +fail.</li> +<li class="tent">If the <b>readonly</b> edit option is set (see <a href="#tag_20_40_13_76">readonly</a> ), the <b>write</b> shall +fail.</li> +<li class="tent">If <i>file</i> is specified, and is not the current pathname, and the file exists, the <b>write</b> shall +fail.</li> +<li class="tent">If <i>file</i> is not specified, the current pathname shall be used. If there is no current pathname, the +<b>write</b> command shall fail.</li> +<li class="tent">If the current pathname is used, and the current pathname has been changed by the <b>file</b> or <b>read</b> +commands, and the file exists, the <b>write</b> shall fail. If the <b>write</b> is successful, subsequent <b>write</b>s shall not +fail for this reason (unless the current pathname is changed again).</li> +<li class="tent">If the whole edit buffer is not being written, and the file to be written exists, the <b>write</b> shall +fail.</li> +</ol> +<p class="tent">For rules 1., 2., 3., and 5., the <b>write</b> can be forced by appending the character <tt>'!'</tt> to the command +name.</p> +<p class="tent">For rules 2., 3., and 5., the <b>write</b> can be forced by setting the <b>writeany</b> edit option.</p> +<p class="tent">Additional, implementation-defined tests may cause the <b>write</b> to fail.</p> +<p class="tent">If the edit buffer is empty, a file without any contents shall be written.</p> +<p class="tent">An informational message shall be written noting the number of lines and bytes written.</p> +<p class="tent">Otherwise, if the command is followed by one or more <blank> characters, and the file is preceded by +<tt>'!'</tt>, the rest of the line after the <tt>'!'</tt> shall have <tt>'%'</tt>, <tt>'#'</tt>, and <tt>'!'</tt> characters +expanded as described in <a href="#tag_20_40_13_03">Command Line Parsing in ex</a> .</p> +<p class="tent">The <i>ex</i> utility shall then pass two arguments to the program named by the <b>shell</b> edit option; the first +shall be <b>-c</b> and the second shall be the expanded arguments to the <b>write</b> command as a single argument. The specified +lines shall be written to the standard input of the command. The standard error and standard output of the program, if any, shall +be written as described for the <b>print</b> command. If the last character in that output is not a <newline>, a +<newline> shall be written at the end of the output.</p> +<p class="tent">The special meaning of the <tt>'!'</tt> following the <b>write</b> command can be overridden by escaping it with a +<backslash> character.</p> +<p class="tent"><i>Current line</i>: Unchanged.</p> +<p class="tent"><i>Current column</i>: Unchanged.</p> +<h5><a name="tag_20_40_13_49" id="tag_20_40_13_49"></a>Write and Exit</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<b>[</b><i>2addr</i><b>] </b><tt>x</tt><b>[</b><tt>it</tt><b>][</b><tt>!</tt><b>][</b><i>file</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">If the edit buffer has not been modified since the last complete <b>write</b>, <b>xit</b> shall be equivalent to +the <b>quit</b> command, or if a <tt>'!'</tt> is appended to the command name, to <b>quit!</b>.</p> +<p class="tent">Otherwise, <b>xit</b> shall be equivalent to the <b>wq</b> command, or if a <tt>'!'</tt> is appended to the command +name, to <b>wq!</b>.</p> +<p class="tent"><i>Current line</i>: Unchanged.</p> +<p class="tent"><i>Current column</i>: Unchanged.</p> +<h5><a name="tag_20_40_13_50" id="tag_20_40_13_50"></a>Yank</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<b>[</b><i>2addr</i><b>] </b><tt>ya</tt><b>[</b><tt>nk</tt><b>][ </b><i>buffer</i><b>][</b><i>count</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">Copy the specified lines to the specified buffer (by default, the unnamed buffer), which shall become a line-mode +buffer.</p> +<p class="tent"><i>Current line</i>: Unchanged.</p> +<p class="tent"><i>Current column</i>: Unchanged.</p> +<h5><a name="tag_20_40_13_51" id="tag_20_40_13_51"></a>Adjust Window</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<b>[</b><i>1addr</i><b>] </b><tt>z</tt><b>[</b><tt>!</tt><b>][</b><i>type </i><tt>...</tt><b>][</b><i>count</i><b>][</b><i>flags</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">If no line is specified, the current line shall be the default; if <i>type</i> is omitted as well, the current line +value shall first be incremented by 1. If incrementing the current line would cause it to be greater than the last line in the edit +buffer, it shall be an error.</p> +<p class="tent">If there are <blank> characters between the <i>type</i> argument and the preceding <b>z</b> command name or +optional <tt>'!'</tt> character, it shall be an error.</p> +<p class="tent">If <i>count</i> is specified, the value of the <b>window</b> edit option shall be set to <i>count</i> (as described +in <a href="#tag_20_40_13_93">window</a> ). If <i>count</i> is omitted, it shall default to 2 times the value of the <b>scroll</b> +edit option, or if <b>!</b> was specified, the number of lines in the display minus 1.</p> +<p class="tent">If <i>type</i> is omitted, then <i>count</i> lines starting with the specified line shall be written. Otherwise, +<i>count</i> lines starting with the line specified by the <i>type</i> argument shall be written.</p> +<p class="tent">The <i>type</i> argument shall change the lines to be written. The possible values of <i>type</i> are as +follows:</p> +<dl compact> +<dd></dd> +<dt><tt>-</tt></dt> +<dd>The specified line shall be decremented by the following value: +<pre> +<tt>(((number of '-' characters) x </tt><i>count</i><tt>) -1) +</tt></pre> +<p class="tent">If the calculation would result in a number less than 1, it shall be an error. Write lines from the edit buffer, +starting at the new value of line, until <i>count</i> lines or the last line in the edit buffer has been written.</p> +</dd> +<dt><tt>+</tt></dt> +<dd>The specified line shall be incremented by the following value: +<pre> +<tt>(((number of '+' characters) -1) x </tt><i>count</i><tt>) +1 +</tt></pre> +<p class="tent">If the calculation would result in a number greater than the last line in the edit buffer, it shall be an error. +Write lines from the edit buffer, starting at the new value of line, until <i>count</i> lines or the last line in the edit buffer +has been written.</p> +</dd> +<dt><tt>=</tt>,<tt>.</tt></dt> +<dd>If more than a single <tt>'.'</tt> or <tt>'='</tt> is specified, it shall be an error. The following steps shall be taken: +<ol> +<li class="tent">If <i>count</i> is zero, nothing shall be written.</li> +<li class="tent">Write as many of the <i>N</i> lines before the current line in the edit buffer as exist. If <i>count</i> or +<tt>'!'</tt> was specified, <i>N</i> shall be: +<pre> +<tt>(</tt><i>count</i><tt> -1) /2 +</tt></pre> +<p class="tent">Otherwise, <i>N</i> shall be:</p> +<pre> +<tt>(</tt><i>count</i><tt> -3) /2 +</tt></pre> +<p class="tent">If <i>N</i> is a number less than 3, no lines shall be written.</p> +</li> +<li class="tent">If <tt>'='</tt> was specified as the type character, write a line consisting of the smaller of the number of +columns in the display divided by two, or 40 <tt>'-'</tt> characters.</li> +<li class="tent">Write the current line.</li> +<li class="tent">Repeat step 3.</li> +<li class="tent">Write as many of the <i>N</i> lines after the current line in the edit buffer as exist. <i>N</i> shall be defined +as in step 2. If <i>N</i> is a number less than 3, no lines shall be written. If <i>count</i> is less than 3, no lines shall be +written.</li> +</ol> +</dd> +<dt><tt>^</tt></dt> +<dd>The specified line shall be decremented by the following value: +<pre> +<tt>(((number of '^' characters) +1) x </tt><i>count</i><tt>) -1 +</tt></pre> +<p class="tent">If the calculation would result in a number less than 1, it shall be an error. Write lines from the edit buffer, +starting at the new value of line, until <i>count</i> lines or the last line in the edit buffer has been written.</p> +</dd> +</dl> +<p class="tent"><i>Current line</i>: Set to the last line written, unless the type is <b>=</b>, in which case, set to the specified +line.</p> +<p class="tent"><i>Current column</i>: Set to non-<blank>.</p> +<h5><a name="tag_20_40_13_52" id="tag_20_40_13_52"></a>Escape</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt>!</tt><i>command +</i><b>[</b><i>2addr</i><b>]</b><tt> !</tt><i>command</i><tt> +</tt></pre></dd> +</dl> +<p class="tent">The contents of the line after the <tt>'!'</tt> shall have <tt>'%'</tt>, <tt>'#'</tt>, and <tt>'!'</tt> characters +expanded as described in <a href="#tag_20_40_13_03">Command Line Parsing in ex</a> . If the expansion causes the text of the line +to change, it shall be redisplayed, preceded by a single <tt>'!'</tt> character.</p> +<p class="tent">The <i>ex</i> utility shall execute the program named by the <b>shell</b> edit option. It shall pass two arguments +to the program; the first shall be <b>-c</b>, and the second shall be the expanded arguments to the <b>!</b> command as a single +argument.</p> +<p class="tent">If no lines are specified, the standard input, standard output, and standard error of the program shall be set to +the standard input, standard output, and standard error of the <i>ex</i> program when it was invoked. In addition, a warning +message shall be written if the edit buffer has been modified since the last complete write, and the <b>warn</b> edit option is +set.</p> +<p class="tent">If lines are specified, they shall be passed to the program as standard input, and the standard output and standard +error of the program shall replace those lines in the edit buffer. Each line in the program output (as delimited by <newline> +characters or the end of the output if it is not immediately preceded by a <newline>), shall be a separate line in the edit +buffer. Any occurrences of <carriage-return> and <newline> pairs in the output shall be treated as single +<newline> characters. The specified lines shall be copied into the unnamed buffer before they are replaced, and the unnamed +buffer shall become a line-mode buffer.</p> +<p class="tent">If in <i>ex</i> mode, a single <tt>'!'</tt> character shall be written when the program completes.</p> +<p class="tent">This command shall be affected by the <b>shell</b> and <b>warn</b> edit options. If no lines are specified, this +command shall be affected by the <b>autowrite</b> and <b>writeany</b> edit options. If lines are specified, this command shall be +affected by the <b>autoprint</b> edit option.<br></p> +<p class="tent"><i>Current line</i>:</p> +<ol> +<li class="tent">If no lines are specified, unchanged.</li> +<li class="tent">Otherwise, set to the last line read in, if any lines are read in.</li> +<li class="tent">Otherwise, set to the line before the first line of the lines specified, if that line exists.</li> +<li class="tent">Otherwise, set to the first line of the edit buffer if the edit buffer is not empty.</li> +<li class="tent">Otherwise, set to zero.</li> +</ol> +<p class="tent"><i>Current column</i>: If no lines are specified, unchanged. Otherwise, set to non-<blank>.</p> +<h5><a name="tag_20_40_13_53" id="tag_20_40_13_53"></a>Shift Left</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<b>[</b><i>2addr</i><b>]</b><tt> <</tt><b>[</b><tt>< ...</tt><b>][</b><i>count</i><b>][</b><i>flags</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">Shift the specified lines to the start of the line; the number of column positions to be shifted shall be the +number of command characters times the value of the <b>shiftwidth</b> edit option. Only leading <blank> characters shall be +deleted or changed into other <blank> characters in shifting; other characters shall not be affected.</p> +<p class="tent">Lines to be shifted shall be copied into the unnamed buffer, which shall become a line-mode buffer.</p> +<p class="tent">This command shall be affected by the <b>autoprint</b> edit option.</p> +<p class="tent"><i>Current line</i>: Set to the last line in the lines specified.</p> +<p class="tent"><i>Current column</i>: Set to non-<blank>.</p> +<h5><a name="tag_20_40_13_54" id="tag_20_40_13_54"></a>Shift Right</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<b>[</b><i>2addr</i><b>]</b><tt> ></tt><b>[</b><tt>> ...</tt><b>][</b><i>count</i><b>][</b><i>flags</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">Shift the specified lines away from the start of the line; the number of column positions to be shifted shall be +the number of command characters times the value of the <b>shiftwidth</b> edit option. The shift shall be accomplished by adding +<blank> characters as a prefix to the line or changing leading <blank> characters into other <blank> characters. +Empty lines shall not be changed.</p> +<p class="tent">Lines to be shifted shall be copied into the unnamed buffer, which shall become a line-mode buffer.</p> +<p class="tent">This command shall be affected by the <b>autoprint</b> edit option.</p> +<p class="tent"><i>Current line</i>: Set to the last line in the lines specified.</p> +<p class="tent"><i>Current column</i>: Set to non-<blank>.</p> +<h5><a name="tag_20_40_13_55" id="tag_20_40_13_55"></a><control>-D</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<tt><control>-D +</tt></pre></dd> +</dl> +<p class="tent">Write the next <i>n</i> lines, where <i>n</i> is the minimum of the values of the <b>scroll</b> edit option and the +number of lines after the current line in the edit buffer. If the current line is the last line of the edit buffer it shall be an +error.</p> +<p class="tent"><i>Current line</i>: Set to the last line written.</p> +<p class="tent"><i>Current column</i>: Set to non-<blank>.</p> +<h5><a name="tag_20_40_13_56" id="tag_20_40_13_56"></a>Write Line Number</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<b>[</b><i>1addr</i><b>] </b><tt>= </tt><b>[</b><i>flags</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p class="tent">If <i>line</i> is not specified, it shall default to the last line in the edit buffer. Write the line number of the +specified line.</p> +<p class="tent"><i>Current line</i>: Unchanged.</p> +<p class="tent"><i>Current column</i>: Unchanged.</p> +<h5><a name="tag_20_40_13_57" id="tag_20_40_13_57"></a>Execute</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<p class="tent"></p> +<pre> +<b>[</b><i>2addr</i><b>]</b><tt> @ </tt><i>buffer</i><tt> +</tt><b>[</b><i>2addr</i><b>]</b><tt> * </tt><i>buffer</i><tt> +</tt></pre></dd> +</dl> +<p class="tent">If no buffer is specified or is specified as <tt>'@'</tt> or <tt>'*'</tt>, the last buffer executed shall be used. +If no previous buffer has been executed, it shall be an error.</p> +<p class="tent">For each line specified by the addresses, set the current line (<tt>'.'</tt>) to the specified line, and execute +the contents of the named <i>buffer</i> (as they were at the time the <b>@</b> command was executed) as <i>ex</i> commands. For +each line of a line-mode buffer, and all but the last line of a character-mode buffer, the <i>ex</i> command parser shall behave as +if the line was terminated by a <newline>.</p> +<p class="tent">If an error occurs during this process, or a line specified by the addresses does not exist when the current line +would be set to it, or more than a single line was specified by the addresses, and the contents of the edit buffer are replaced +(for example, by the <i>ex</i> <b>:edit</b> command) an error message shall be written, and no more commands resulting from the +execution of this command shall be processed.</p> +<p class="tent"><i>Current line</i>: As specified for the individual <i>ex</i> commands.</p> +<p class="tent"><i>Current column</i>: As specified for the individual <i>ex</i> commands.</p> +<h5><a name="tag_20_40_13_58" id="tag_20_40_13_58"></a>Regular Expressions in ex</h5> +<p class="tent">The <i>ex</i> utility shall support regular expressions that are a superset of the basic regular expressions +described in XBD <a href="../basedefs/V1_chap09.html#tag_09_03"><i>9.3 Basic Regular Expressions</i></a> . A null regular +expression (<tt>"//"</tt>) shall be equivalent to the last regular expression encountered.</p> +<p class="tent">Regular expressions can be used in addresses to specify lines and, in some commands (for example, the +<b>substitute</b> command), to specify portions of a line to be substituted.</p> +<p class="tent">The start and end of a regular expression (RE) are marked by a delimiter character (although in some circumstances +the end delimiter can be omitted). In addresses, the delimiter is either <slash> or <question-mark>. In commands, other +characters can be used as the delimiter, as specified in the description of the command. Within the RE (as an <i>ex</i> extension +to the BRE syntax), the delimiter shall not terminate the RE if it is the second character of an escape sequence (see XBD <a href= +"../basedefs/V1_chap09.html#tag_09_01"><i>9.1 Regular Expression Definitions</i></a> ) and the escaped delimiter shall be treated +as that literal character in the RE (losing any special meaning it would have had if it was not used as the delimiter and was not +escaped). In addition, the delimiter character shall not terminate the RE when it appears within a bracket expression, and shall +have its normal meaning in the bracket expression. For example, the command <tt>"g%[%]%p"</tt> is equivalent to <tt>"g/[%]/p"</tt>, +and the command <tt>"s-[0-9]--g"</tt> is equivalent to <tt>"s/[0-9]//g"</tt>.</p> +<p class="tent">The following constructs can be used to enhance the basic regular expressions:</p> +<dl compact> +<dd></dd> +<dt><tt>\<</tt></dt> +<dd>Match the beginning of a <i>word</i>. (See the definition of <i>word</i> at the beginning of <a href="#tag_20_40_13_10">Command +Descriptions in ex</a> .)</dd> +<dt><tt>\></tt></dt> +<dd>Match the end of a <i>word</i>.</dd> +<dt><tt>~</tt></dt> +<dd>Match the replacement part of the last <b>substitute</b> command. The <tilde> (<tt>'~'</tt>) character can be escaped in +a regular expression to become a normal character with no special meaning. The <backslash> shall be discarded.</dd> +</dl> +<p class="tent">When the editor option <b>magic</b> is not set, the only characters with special meanings shall be <tt>'^'</tt> at +the beginning of a pattern, <tt>'$'</tt> at the end of a pattern, and <backslash>. The characters <tt>'.'</tt>, <tt>'*'</tt>, +<tt>'['</tt>, and <tt>'~'</tt> shall be treated as ordinary characters unless preceded by a <backslash>; when preceded by a +<backslash> they shall regain their special meaning, or in the case of <backslash>, be handled as a single +<backslash>. <backslash> characters used to escape other characters shall be discarded.</p> +<h5><a name="tag_20_40_13_59" id="tag_20_40_13_59"></a>Replacement Strings in ex</h5> +<p class="tent">Certain characters and strings have special meaning in replacement strings when the character, or the first +character of the string, is unescaped.</p> +<p class="tent">The character <tt>'&'</tt> (<tt>'\&'</tt> if the editor option <b>magic</b> is not set) in the replacement +string shall stand for the text matched by the pattern to be replaced. The character <tt>'~'</tt> (<tt>'\~'</tt> if <b>magic</b> is +not set) shall be replaced by the replacement part of the previous <b>substitute</b> command. The sequence <tt>'\n'</tt>, where +<i>n</i> is an integer, shall be replaced by the text matched by the corresponding back-reference expression. If the corresponding +back-reference expression does not match, then the characters <tt>'\n'</tt> shall be replaced by the empty string.</p> +<p class="tent">The strings <tt>'\l'</tt>, <tt>'\u'</tt>, <tt>'\L'</tt>, and <tt>'\U'</tt> can be used to modify the case of +elements in the replacement string (using the <tt>'\&'</tt> or <tt>"\"</tt>digit) notation. The string <tt>'\l'</tt> +(<tt>'\u'</tt>) shall cause the character that follows to be converted to lowercase (uppercase). The string <tt>'\L'</tt> +(<tt>'\U'</tt>) shall cause all characters subsequent to it to be converted to lowercase (uppercase) as they are inserted by the +substitution until the string <tt>'\e'</tt> or <tt>'\E'</tt>, or the end of the replacement string, is encountered.</p> +<p class="tent">Otherwise, any character following an unescaped <backslash> shall be treated as that literal character, and +the escaping <backslash> shall be discarded.</p> +<p class="tent">An example of case conversion with the <b>s</b> command is as follows:</p> +<pre> +<b>:</b><tt>p +</tt><b>The cat sat on the mat. +:</b><tt>s/\<.at\>/\u&/gp +</tt><b>The Cat Sat on the Mat. +:</b><tt>s/S\(.*\)M/S\U\1\eM/p +</tt><b>The Cat SAT ON THE Mat.</b><tt> +</tt></pre> +<h5><a name="tag_20_40_13_60" id="tag_20_40_13_60"></a>Edit Options in ex</h5> +<p class="tent">The <i>ex</i> utility has a number of options that modify its behavior. These options have default settings, which +can be changed using the <b>set</b> command.</p> +<p class="tent">Options are Boolean unless otherwise specified.</p> +<h5><a name="tag_20_40_13_61" id="tag_20_40_13_61"></a>autoindent, ai</h5> +<p class="tent">[Default <i>unset</i>]</p> +<p class="tent">If <b>autoindent</b> is set, each line in input mode shall be indented (using first as many <tab> characters +as possible, as determined by the editor option <b>tabstop</b>, and then using <space> characters) to align with another +line, as follows:</p> +<ol> +<li class="tent">If in open or visual mode and the text input is part of a line-oriented command (see the EXTENDED DESCRIPTION in +<a href="../utilities/vi.html#"><i>vi</i></a> ), align to the first column.</li> +<li class="tent">Otherwise, if in open or visual mode, indentation for each line shall be set as follows: +<ol type="a"> +<li class="tent">If a line was previously inserted as part of this command, it shall be set to the indentation of the last inserted +line by default, or as otherwise specified for the <control>-D character in <a href= +"../utilities/vi.html#tag_20_146_13_88"><i>Input Mode Commands in vi</i></a> .</li> +<li class="tent">Otherwise, it shall be set to the indentation of the previous current line, if any; otherwise, to the first +column.</li> +</ol> +</li> +<li class="tent">For the <i>ex</i> <b>a</b>, <b>i</b>, and <b>c</b> commands, indentation for each line shall be set as follows: +<ol type="a"> +<li class="tent">If a line was previously inserted as part of this command, it shall be set to the indentation of the last inserted +line by default, or as otherwise specified for the <i>eof</i> character in <a href="#tag_20_40_13_05">Scroll</a> .</li> +<li class="tent">Otherwise, if the command is the <i>ex</i> <b>a</b> command, it shall be set to the line appended after, if any; +otherwise to the first column.</li> +<li class="tent">Otherwise, if the command is the <i>ex</i> <b>i</b> command, it shall be set to the line inserted before, if any; +otherwise to the first column.</li> +<li class="tent">Otherwise, if the command is the <i>ex</i> <b>c</b> command, it shall be set to the indentation of the line +replaced.</li> +</ol> +</li> +</ol> +<h5><a name="tag_20_40_13_62" id="tag_20_40_13_62"></a>autoprint, ap</h5> +<p class="tent">[Default <i>set</i>]</p> +<p class="tent">If <b>autoprint</b> is set, the current line shall be written after each <i>ex</i> command that modifies the +contents of the current edit buffer, and after each <b>tag</b> command for which the tag search pattern was found or tag line +number was valid, unless:</p> +<ol> +<li class="tent">The command was executed while in open or visual mode.</li> +<li class="tent">The command was executed as part of a <b>global</b> or <b>v</b> command or <b>@</b> buffer execution.</li> +<li class="tent">The command was the form of the <b>read</b> command that reads a file into the edit buffer.</li> +<li class="tent">The command was the <b>append</b>, <b>change</b>, or <b>insert</b> command.</li> +<li class="tent">The command was not terminated by a <newline>.</li> +<li class="tent">The current line shall be written by a flag specified to the command; for example, <b>delete #</b> shall write the +current line as specified for the flag modifier to the <b>delete</b> command, and not as specified by the <b>autoprint</b> edit +option.</li> +</ol> +<h5><a name="tag_20_40_13_63" id="tag_20_40_13_63"></a>autowrite, aw</h5> +<p class="tent">[Default <i>unset</i>]</p> +<p class="tent">If <b>autowrite</b> is set, and the edit buffer has been modified since it was last completely written to any file, +the contents of the edit buffer shall be written as if the <i>ex</i> <b>write</b> command had been specified without arguments, +before each command affected by the <b>autowrite</b> edit option is executed. Appending the character <tt>'!'</tt> to the command +name of any of the <i>ex</i> commands except <tt>'!'</tt> shall prevent the write. If the write fails, it shall be an error and the +command shall not be executed.</p> +<h5><a name="tag_20_40_13_64" id="tag_20_40_13_64"></a>beautify, bf</h5> +<p class="tent"><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" +border="0"> [Default <i>unset</i>]</p> +<p class="tent">If <b>beautify</b> is set, all non-printable characters, other than <tab>, <newline>, and +<form-feed> characters, shall be discarded from text read in from files. <img src="../images/opt-end.gif" alt="[Option End]" +border="0"></p> +<h5><a name="tag_20_40_13_65" id="tag_20_40_13_65"></a>directory, dir</h5> +<p class="tent">[Default <i>implementation-defined</i>]</p> +<p class="tent">The value of this option specifies the directory in which the editor buffer is to be placed. If this directory is +not writable by the user, the editor shall quit.</p> +<h5><a name="tag_20_40_13_66" id="tag_20_40_13_66"></a>edcompatible, ed</h5> +<p class="tent">[Default <i>unset</i>]</p> +<p class="tent">Causes the presence of <b>g</b> and <b>c</b> suffixes on substitute commands to be remembered, and toggled by +repeating the suffixes.</p> +<h5><a name="tag_20_40_13_67" id="tag_20_40_13_67"></a>errorbells, eb</h5> +<p class="tent">[Default <i>unset</i>]</p> +<p class="tent">If the editor is in <i>ex</i> mode, and the terminal does not support a standout mode (such as inverse video), and +<b>errorbells</b> is set, error messages shall be preceded by alerting the terminal.</p> +<h5><a name="tag_20_40_13_68" id="tag_20_40_13_68"></a>exrc</h5> +<p class="tent">[Default <i>unset</i>]</p> +<p class="tent">If <b>exrc</b> is set, <i>ex</i> shall access any <b>.exrc</b> file in the current directory, as described in +<a href="#tag_20_40_13_01">Initialization in ex and vi</a> . If <b>exrc</b> is not set, <i>ex</i> shall ignore any <b>.exrc</b> +file in the current directory during initialization, unless the current directory is that named by the <i>HOME</i> environment +variable.</p> +<h5><a name="tag_20_40_13_69" id="tag_20_40_13_69"></a>ignorecase, ic</h5> +<p class="tent">[Default <i>unset</i>]</p> +<p class="tent">If <b>ignorecase</b> is set, characters that have uppercase and lowercase representations shall have those +representations considered as equivalent for purposes of regular expression comparison.</p> +<p class="tent">The <b>ignorecase</b> edit option shall affect all remembered regular expressions; for example, unsetting the +<b>ignorecase</b> edit option shall cause a subsequent <a href="../utilities/vi.html"><i>vi</i></a> <b>n</b> command to search for +the last basic regular expression in a case-sensitive fashion.</p> +<h5><a name="tag_20_40_13_70" id="tag_20_40_13_70"></a>list</h5> +<p class="tent">[Default <i>unset</i>]</p> +<p class="tent">If <b>list</b> is set, edit buffer lines written while in <i>ex</i> command mode shall be written as specified for +the <b>print</b> command with the <b>l</b> flag specified. In open or visual mode, each edit buffer line shall be displayed as +specified for the <i>ex</i> <b>print</b> command with the <b>l</b> flag specified. In open or visual text input mode, when the +cursor does not rest on any character in the line, it shall rest on the <tt>'$'</tt> marking the end of the line.</p> +<h5><a name="tag_20_40_13_71" id="tag_20_40_13_71"></a>magic</h5> +<p class="tent">[Default <i>set</i>]</p> +<p class="tent">If <b>magic</b> is set, modify the interpretation of characters in regular expressions and substitution replacement +strings (see <a href="#tag_20_40_13_58">Regular Expressions in ex</a> and <a href="#tag_20_40_13_59">Replacement Strings in ex</a> +).</p> +<h5><a name="tag_20_40_13_72" id="tag_20_40_13_72"></a>mesg</h5> +<p class="tent">[Default <i>set</i>]</p> +<p class="tent">If <b>mesg</b> is set, the permission for others to use the <b>write</b> or <b>talk</b> commands to write to the +terminal shall be turned on while in open or visual mode. The shell-level command <a href="../utilities/mesg.html"><i>mesg</i></a> +<b>n</b> shall take precedence over any setting of the <i>ex</i> <b>mesg</b> option; that is, if <b>mesg y</b> was issued before +the editor started (or in a shell escape), such as:</p> +<pre> +<tt>:!mesg y +</tt></pre> +<p class="tent">the <b>mesg</b> option in <i>ex</i> shall suppress incoming messages, but the <b>mesg</b> option shall not enable +incoming messages if <b>mesg n</b> was issued.</p> +<h5><a name="tag_20_40_13_73" id="tag_20_40_13_73"></a>number, nu</h5> +<p class="tent">[Default <i>unset</i>]</p> +<p class="tent">If <b>number</b> is set, edit buffer lines written while in <i>ex</i> command mode shall be written with line +numbers, in the format specified by the <b>print</b> command with the <b>#</b> flag specified. In <i>ex</i> text input mode, each +line shall be preceded by the line number it will have in the file.</p> +<p class="tent">In open or visual mode, each edit buffer line shall be displayed with a preceding line number, in the format +specified by the <i>ex</i> <b>print</b> command with the <b>#</b> flag specified. This line number shall not be considered part of +the line for the purposes of evaluating the current column; that is, column position 1 shall be the first column position after the +format specified by the <b>print</b> command.</p> +<h5><a name="tag_20_40_13_74" id="tag_20_40_13_74"></a>paragraphs, para</h5> +<p class="tent">[Default in the POSIX locale <tt>IPLPPPQPP LIpplpipbp</tt>]</p> +<p class="tent">The <b>paragraphs</b> edit option shall define additional paragraph boundaries for the open and visual mode +commands. The <b>paragraphs</b> edit option can be set to a character string consisting of zero or more character pairs. It shall +be an error to set it to an odd number of characters.</p> +<h5><a name="tag_20_40_13_75" id="tag_20_40_13_75"></a>prompt</h5> +<p class="tent">[Default <i>set</i>]</p> +<p class="tent">If <b>prompt</b> is set, <i>ex</i> command mode input shall be prompted for with a <colon> (<tt>':'</tt>); +when unset, no prompt shall be written.</p> +<h5><a name="tag_20_40_13_76" id="tag_20_40_13_76"></a>readonly</h5> +<p class="tent">[Default <i>see text</i>]</p> +<p class="tent">If the <b>readonly</b> edit option is set, read-only mode shall be enabled (see <a href= +"#tag_20_40_13_48">Write</a> ). The <b>readonly</b> edit option shall be initialized to set if either of the following conditions +are true:</p> +<ul> +<li class="tent">The command-line option -R was specified.</li> +<li class="tent">Performing actions equivalent to the <a href="../functions/access.html"><i>access</i>()</a> function called with +the following arguments indicates that the file lacks write permission: +<ol> +<li class="tent">The current pathname is used as the <i>path</i> argument.</li> +<li class="tent">The constant <b>W_OK</b> is used as the <i>amode</i> argument.</li> +</ol> +</li> +</ul> +<p class="tent">The <b>readonly</b> edit option may be initialized to set for other, implementation-defined reasons. The +<b>readonly</b> edit option shall not be initialized to unset based on any special privileges of the user or process. The +<b>readonly</b> edit option shall be reinitialized each time that the contents of the edit buffer are replaced (for example, by an +<b>edit</b> or <b>next</b> command) unless the user has explicitly set it, in which case it shall remain set until the user +explicitly unsets it. Once unset, it shall again be reinitialized each time that the contents of the edit buffer are replaced.</p> +<h5><a name="tag_20_40_13_77" id="tag_20_40_13_77"></a>redraw</h5> +<p class="tent">[Default <i>unset</i>]</p> +<p class="tent">If <b>redraw</b> is set and the terminal is a type incapable of supporting open or visual modes, the editor shall +redraw the screen when necessary in order to update its contents. (Since this is likely to require a large amount of output to the +terminal, it is useful only at high transmission speeds.)</p> +<h5><a name="tag_20_40_13_78" id="tag_20_40_13_78"></a>remap</h5> +<p class="tent">[Default <i>set</i>]</p> +<p class="tent">If <b>remap</b> is set, map translation shall allow for maps defined in terms of other maps; translation shall +continue until a final product is obtained. If unset, only a one-step translation shall be done.</p> +<h5><a name="tag_20_40_13_79" id="tag_20_40_13_79"></a>report</h5> +<p class="tent">[Default 5]</p> +<p class="tent">The value of this <b>report</b> edit option specifies what number of lines being added, copied, deleted, or +modified in the edit buffer will cause an informational message to be written to the user. The following conditions shall cause an +informational message. The message shall contain the number of lines added, copied, deleted, or modified, but is otherwise +unspecified.</p> +<ul> +<li class="tent">An <i>ex</i> or <a href="../utilities/vi.html"><i>vi</i></a> editor command, other than <b>open</b>, <b>undo</b>, +or <b>visual</b>, that modifies at least the value of the <b>report</b> edit option number of lines, and which is not part of an +<i>ex</i> <b>global</b> or <b>v</b> command, or <i>ex</i> or <a href="../utilities/vi.html"><i>vi</i></a> buffer execution, shall +cause an informational message to be written.</li> +<li class="tent">An <i>ex</i> <b>yank</b> or <a href="../utilities/vi.html"><i>vi</i></a> <b>y</b> or <b>Y</b> command, that copies +at least the value of the <b>report</b> edit option plus 1 number of lines, and which is not part of an <i>ex</i> <b>global</b> or +<b>v</b> command, or <i>ex</i> or <a href="../utilities/vi.html"><i>vi</i></a> buffer execution, shall cause an informational +message to be written.</li> +<li class="tent">An <i>ex</i> <b>global</b>, <b>v</b>, <b>open</b>, <b>undo</b>, or <b>visual</b> command or <i>ex</i> or <a href= +"../utilities/vi.html"><i>vi</i></a> buffer execution, that adds or deletes a total of at least the value of the <b>report</b> edit +option number of lines, and which is not part of an <i>ex</i> <b>global</b> or <b>v</b> command, or <i>ex</i> or <a href= +"../utilities/vi.html"><i>vi</i></a> buffer execution, shall cause an informational message to be written. (For example, if 3 lines +were added and 8 lines deleted during an <i>ex</i> <b>visual</b> command, 5 would be the number compared against the <b>report</b> +edit option after the command completed.)</li> +</ul> +<h5><a name="tag_20_40_13_80" id="tag_20_40_13_80"></a>scroll, scr</h5> +<p class="tent">[Default (number of lines in the display -1)/2]</p> +<p class="tent">The value of the <b>scroll</b> edit option shall determine the number of lines scrolled by the <i>ex</i> +<control>-D and <b>z</b> commands. For the <a href="../utilities/vi.html"><i>vi</i></a> <control>-D and +<control>-U commands, it shall be the initial number of lines to scroll when no previous <control>-D or +<control>-U command has been executed.</p> +<h5><a name="tag_20_40_13_81" id="tag_20_40_13_81"></a>sections</h5> +<p class="tent">[Default in the POSIX locale <tt>NHSHH HUnhsh</tt>]</p> +<p class="tent">The <b>sections</b> edit option shall define additional section boundaries for the open and visual mode commands. +The <b>sections</b> edit option can be set to a character string consisting of zero or more character pairs; it shall be an error +to set it to an odd number of characters.</p> +<h5><a name="tag_20_40_13_82" id="tag_20_40_13_82"></a>shell, sh</h5> +<p class="tent">[Default from the environment variable <i>SHELL ]</i></p> +<p class="tent">The value of this option shall be a string. The default shall be taken from the <i>SHELL</i> environment variable. +If the <i>SHELL</i> environment variable is null or empty, the <a href="../utilities/sh.html"><i>sh</i></a> (see <a href= +"../utilities/sh.html#"><i>sh</i></a> ) utility shall be the default.</p> +<h5><a name="tag_20_40_13_83" id="tag_20_40_13_83"></a>shiftwidth, sw</h5> +<p class="tent">[Default 8]</p> +<p class="tent">The value of this option shall give the width in columns of an indentation level used during autoindentation and by +the shift commands (<b><</b> and <b>></b>).</p> +<h5><a name="tag_20_40_13_84" id="tag_20_40_13_84"></a>showmatch, sm</h5> +<p class="tent">[Default <i>unset</i>]</p> +<p class="tent">The functionality described for the <b>showmatch</b> edit option need not be supported on block-mode terminals or +terminals with insufficient capabilities.</p> +<p class="tent">If <b>showmatch</b> is set, in open or visual mode, when a <tt>')'</tt> or <tt>'}'</tt> is typed, if the matching +<tt>'('</tt> or <tt>'{'</tt> is currently visible on the display, the matching <tt>'('</tt> or <tt>'{'</tt> shall be flagged moving +the cursor to its location for an unspecified amount of time.</p> +<h5><a name="tag_20_40_13_85" id="tag_20_40_13_85"></a>showmode</h5> +<p class="tent">[Default <i>unset</i>]</p> +<p class="tent">If <b>showmode</b> is set, in open or visual mode, the current mode that the editor is in shall be displayed on the +last line of the display. Command mode and text input mode shall be differentiated; other unspecified modes and +implementation-defined information may be displayed.</p> +<h5><a name="tag_20_40_13_86" id="tag_20_40_13_86"></a>slowopen</h5> +<p class="tent">[Default <i>unset</i>]</p> +<p class="tent">If <b>slowopen</b> is set during open and visual text input modes, the editor shall not update portions of the +display other than those display line columns that display the characters entered by the user (see <a href= +"../utilities/vi.html#tag_20_146_13_88"><i>Input Mode Commands in vi</i></a> ).</p> +<h5><a name="tag_20_40_13_87" id="tag_20_40_13_87"></a>tabstop, ts</h5> +<p class="tent">[Default 8]</p> +<p class="tent">The value of this edit option shall specify the column boundary used by a <tab> in the display (see <a href= +"#tag_20_40_13_62">autoprint, ap</a> and <a href="../utilities/vi.html#tag_20_146_13_88"><i>Input Mode Commands in vi</i></a> +).</p> +<h5><a name="tag_20_40_13_88" id="tag_20_40_13_88"></a>taglength, tl</h5> +<p class="tent">[Default zero]</p> +<p class="tent">The value of this edit option shall specify the maximum number of characters that are considered significant in the +user-specified tag name and in the tag name from the tags file. If the value is zero, all characters in both tag names shall be +significant.</p> +<h5><a name="tag_20_40_13_89" id="tag_20_40_13_89"></a>tags</h5> +<p class="tent">[Default <i>see text</i>]</p> +<p class="tent">The value of this edit option shall be a string of <blank>-delimited pathnames of files used by the +<b>tag</b> command. The default value is unspecified.</p> +<h5><a name="tag_20_40_13_90" id="tag_20_40_13_90"></a>term</h5> +<p class="tent">[Default from the environment variable <i>TERM ]</i></p> +<p class="tent">The value of this edit option shall be a string. The default shall be taken from the <i>TERM</i> variable in the +environment. If the <i>TERM</i> environment variable is empty or null, the default is unspecified. The editor shall use the value +of this edit option to determine the type of the display device.</p> +<p class="tent">The results are unspecified if the user changes the value of the term edit option after editor initialization.</p> +<h5><a name="tag_20_40_13_91" id="tag_20_40_13_91"></a>terse</h5> +<p class="tent">[Default <i>unset</i>]</p> +<p class="tent">If <b>terse</b> is set, error messages may be less verbose. However, except for this caveat, error messages are +unspecified. Furthermore, not all error messages need change for different settings of this option.</p> +<h5><a name="tag_20_40_13_92" id="tag_20_40_13_92"></a>warn</h5> +<p class="tent">[Default <i>set</i>]</p> +<p class="tent">If <b>warn</b> is set, and the contents of the edit buffer have been modified since they were last completely +written, the editor shall write a warning message before certain <b>!</b> commands (see <a href="#tag_20_40_13_52">Escape</a> +).</p> +<h5><a name="tag_20_40_13_93" id="tag_20_40_13_93"></a>window</h5> +<p class="tent">[Default <i>see text</i>]</p> +<p class="tent">A value used in open and visual mode, by the <control>-B and <control>-F commands, and, in visual mode, +to specify the number of lines displayed when the screen is repainted.</p> +<p class="tent">If the <b>-w</b> command-line option is not specified, the default value shall be set to the value of the +<i>LINES</i> environment variable. If the <i>LINES</i> environment variable is empty or null, the default shall be the number of +lines in the display minus 1.</p> +<p class="tent">Setting the <b>window</b> edit option to zero or to a value greater than the number of lines in the display minus 1 +(either explicitly or based on the <b>-w</b> option or the <i>LINES</i> environment variable) shall cause the <b>window</b> edit +option to be set to the number of lines in the display minus 1.</p> +<p class="tent">The baud rate of the terminal line may change the default in an implementation-defined manner.</p> +<h5><a name="tag_20_40_13_94" id="tag_20_40_13_94"></a>wrapmargin, wm</h5> +<p class="tent">[Default 0]</p> +<p class="tent">If the value of this edit option is zero, it shall have no effect.</p> +<p class="tent">If not in the POSIX locale, the effect of this edit option is implementation-defined.</p> +<p class="tent">Otherwise, it shall specify a number of columns from the ending margin of the terminal.</p> +<p class="tent">During open and visual text input modes, for each character for which any part of the character is displayed in a +column that is less than <b>wrapmargin</b> columns from the ending margin of the display line, the editor shall behave as +follows:</p> +<ol> +<li class="tent">If the character triggering this event is a <blank>, it, and all immediately preceding <blank> +characters on the current line entered during the execution of the current text input command, shall be discarded, and the editor +shall behave as if the user had entered a single <newline> instead. In addition, if the next user-entered character is a +<space>, it shall be discarded as well.</li> +<li class="tent">Otherwise, if there are one or more <blank> characters on the current line immediately preceding the last +group of inserted non-<blank> characters which was entered during the execution of the current text input command, the +<blank> characters shall be replaced as if the user had entered a single <newline> instead.</li> +</ol> +<p class="tent">If the <b>autoindent</b> edit option is set, and the events described in 1. or 2. are performed, any <blank> +characters at or after the cursor in the current line shall be discarded.</p> +<p class="tent">The ending margin shall be determined by the system or overridden by the user, as described for <i>COLUMNS</i> in +the ENVIRONMENT VARIABLES section and XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> .</p> +<h5><a name="tag_20_40_13_95" id="tag_20_40_13_95"></a>wrapscan, ws</h5> +<p class="tent">[Default <i>set</i>]</p> +<p class="tent">If <b>wrapscan</b> is set, searches (the <i>ex</i> <b>/</b> or <b>?</b> addresses, or open and visual mode +<b>/</b>, <b>?</b>, <b>N</b>, and <b>n</b> commands) shall wrap around the beginning or end of the edit buffer; when unset, +searches shall stop at the beginning or end of the edit buffer.</p> +<h5><a name="tag_20_40_13_96" id="tag_20_40_13_96"></a>writeany, wa</h5> +<p class="tent">[Default <i>unset</i>]</p> +<p class="tent">If <b>writeany</b> is set, some of the checks performed when executing the <i>ex</i> <b>write</b> commands shall be +inhibited, as described in editor option <b>autowrite</b>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_40_14" id="tag_20_40_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_40_15" id="tag_20_40_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>When any error is encountered and the standard input is not a terminal device file, in addition to the default requirements +described in <a href="../utilities/V3_chap01.html#tag_18_04"><i>1.4 Utility Description Defaults</i></a> , <i>ex</i> shall neither +write the file (if one has been opened) nor return to command or text input mode.</p> +<p class="tent">Otherwise, when an unrecoverable error is encountered, it shall be equivalent to a SIGHUP asynchronous event.</p> +<p class="tent">Otherwise, when an error is encountered, the editor shall behave as specified in <a href="#tag_20_40_13_03">Command +Line Parsing in ex</a> .</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_40_16" id="tag_20_40_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>If a SIGSEGV signal is received while <i>ex</i> is saving a file, the file might not be successfully saved.</p> +<p class="tent">The <b>next</b> command can accept more than one file, so usage such as:</p> +<pre> +<tt>next `ls [abc]*` +</tt></pre> +<p class="tent">is valid; it would not be valid for the <b>edit</b> or <b>read</b> commands, for example, because they expect only +one file and unspecified results occur.</p> +<p class="tent">Unlike the <a href="../functions/system.html#"><i>system</i></a> function, <i>ex</i> does not pass <tt>"--"</tt> +between the <tt>"-c"</tt> argument and the command string, so that programs for which <b>-c</b> takes an option-argument can be +used in the <b>shell</b> edit option. Users who want to use an <b>escape</b> command to execute a utility whose name starts with +<tt>'-'</tt> or <tt>'+'</tt> need to provide a pathname for that utility that does not start with either of those characters, or +precede the utility name with a <blank> character.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_40_17" id="tag_20_40_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_40_18" id="tag_20_40_18"></a>RATIONALE</h4> +<blockquote> +<p>The <i>ex</i>/<a href="../utilities/vi.html"><i>vi</i></a> specification is based on the historical practice found in the 4 BSD +and System V implementations of <i>ex</i> and <a href="../utilities/vi.html"><i>vi</i></a>.</p> +<p class="tent">A <i>restricted editor</i> (both the historical <i>red</i> utility and modifications to <i>ex</i>) were considered +and rejected for inclusion. Neither option provided the level of security that users might expect.</p> +<p class="tent">It is recognized that <i>ex</i> visual mode and related features would be difficult, if not impossible, to +implement satisfactorily on a block-mode terminal, or a terminal without any form of cursor addressing; thus, it is not a mandatory +requirement that such features should work on all terminals. It is the intention, however, that an <i>ex</i> implementation should +provide the full set of capabilities on all terminals capable of supporting them.</p> +<h5><a name="tag_20_40_18_01" id="tag_20_40_18_01"></a>Options</h5> +<p class="tent">The <b>-c</b> replacement for <b>+</b><i>command</i> was inspired by the <b>-e</b> option of <a href= +"../utilities/sed.html"><i>sed</i></a>. Historically, all such commands (see <b>edit</b> and <b>next</b> as well) were executed +from the last line of the edit buffer. This meant, for example, that <tt>"+/pattern"</tt> would fail unless the <b>wrapscan</b> +option was set. POSIX.1-2024 requires conformance to historical practice. The <b>+</b><i>command</i> option is no longer specified +by POSIX.1-2024 but may be present in some implementations. Historically, some implementations restricted the <i>ex</i> commands +that could be listed as part of the command line arguments. For consistency, POSIX.1-2024 does not permit these restrictions.</p> +<p class="tent">In historical implementations of the editor, the <b>-R</b> option (and the <b>readonly</b> edit option) only +prevented overwriting of files; appending to files was still permitted, mapping loosely into the <i>csh</i> <b>noclobber</b> +variable. Some implementations, however, have not followed this semantic, and <b>readonly</b> does not permit appending either. +POSIX.1-2024 follows the latter practice, believing that it is a more obvious and intuitive meaning of <b>readonly</b>.</p> +<p class="tent">The <b>-s</b> option suppresses all interactive user feedback and is useful for editing scripts in batch jobs. The +list of specific effects is historical practice. The terminal type "incapable of supporting open and visual modes" has +historically been named "dumb".</p> +<p class="tent">The <b>-t</b> option was required because the <a href="../utilities/ctags.html"><i>ctags</i></a> utility appears in +POSIX.1-2024 and the option is available in all historical implementations of <i>ex</i>.</p> +<p class="tent">Historically, the <i>ex</i> and <a href="../utilities/vi.html"><i>vi</i></a> utilities accepted a <b>-x</b> option, +which did encryption based on the algorithm found in the historical <i>crypt</i> utility. The <b>-x</b> option for encryption, and +the associated <i>crypt</i> utility, were omitted because the algorithm used was not specifiable and the export control laws of +some nations make it difficult to export cryptographic technology. In addition, it did not historically provide the level of +security that users might expect.</p> +<h5><a name="tag_20_40_18_02" id="tag_20_40_18_02"></a>Standard Input</h5> +<p class="tent">An end-of-file condition is not equivalent to an end-of-file character. A common end-of-file character, +<control>-D, is historically an <i>ex</i> command.</p> +<p class="tent">There was no maximum line length in historical implementations of <i>ex</i>. Specifically, as it was parsed in +chunks, the addresses had a different maximum length than the filenames. Further, the maximum line buffer size was declared as +BUFSIZ, which was different lengths on different systems. This version selected the value of {LINE_MAX} to impose a reasonable +restriction on portable usage of <i>ex</i> and to aid test suite writers in their development of realistic tests that exercise this +limit.</p> +<h5><a name="tag_20_40_18_03" id="tag_20_40_18_03"></a>Input Files</h5> +<p class="tent">It was an explicit decision by the standard developers that a <newline> be added to any file lacking one. It +was believed that this feature of <i>ex</i> and <a href="../utilities/vi.html"><i>vi</i></a> was relied on by users in order to +make text files lacking a trailing <newline> more portable. It is recognized that this will require a user-specified option +or extension for implementations that permit <i>ex</i> and <a href="../utilities/vi.html"><i>vi</i></a> to edit files of type other +than text if such files are not otherwise identified by the system. It was agreed that the ability to edit files of arbitrary type +can be useful, but it was not considered necessary to mandate that an <i>ex</i> or <a href="../utilities/vi.html"><i>vi</i></a> +implementation be required to handle files other than text files.</p> +<p class="tent">The paragraph in the INPUT FILES section, "By default, ...", is intended to close a long-standing security +problem in <i>ex</i> and <a href="../utilities/vi.html"><i>vi</i></a>; that of the "modeline" or "modelines" edit option. This +feature allows any line in the first or last five lines of the file containing the strings <tt>"ex:"</tt> or <tt>"vi:"</tt> (and, +apparently, <tt>"ei:"</tt> or <tt>"vx:"</tt>) to be a line containing editor commands, and <i>ex</i> interprets all the text up to +the next <tt>':'</tt> or <newline> as a command. Consider the consequences, for example, of an unsuspecting user using +<i>ex</i> or <a href="../utilities/vi.html"><i>vi</i></a> as the editor when replying to a mail message in which a line such +as:</p> +<pre> +<tt>ex:! rm -rf : +</tt></pre> +<p class="tent">appeared in the signature lines. The standard developers believed strongly that an editor should not by default +interpret any lines of a file. Vendors are strongly urged to delete this feature from their implementations of <i>ex</i> and +<a href="../utilities/vi.html"><i>vi</i></a>.</p> +<h5><a name="tag_20_40_18_04" id="tag_20_40_18_04"></a>Asynchronous Events</h5> +<p class="tent">The intention of the phrase "complete write" is that the entire edit buffer be written to stable storage. The +note regarding temporary files is intended for implementations that use temporary files to back edit buffers unnamed by the +user.</p> +<p class="tent">Historically, SIGQUIT was ignored by <i>ex</i>, but was the equivalent of the <b>Q</b> command in visual mode; that +is, it exited visual mode and entered <i>ex</i> mode. POSIX.1-2024 permits, but does not require, this behavior. Historically, +SIGINT was often used by <a href="../utilities/vi.html"><i>vi</i></a> users to terminate text input mode (<control>-C is +often easier to enter than <ESC>). Some implementations of <a href="../utilities/vi.html"><i>vi</i></a> alerted the terminal +on this event, and some did not. POSIX.1-2024 requires that SIGINT behave identically to <ESC>, and that the terminal not be +alerted.</p> +<p class="tent">Historically, suspending the <i>ex</i> editor during text input mode was similar to SIGINT, as completed lines were +retained, but any partial line discarded, and the editor returned to command mode. POSIX.1-2024 is silent on this issue; +implementations are encouraged to follow historical practice, where possible.</p> +<p class="tent">Historically, the <a href="../utilities/vi.html"><i>vi</i></a> editor did not treat SIGTSTP as an asynchronous +event, and it was therefore impossible to suspend the editor in visual text input mode. There are two major reasons for this. The +first is that SIGTSTP is a broadcast signal on UNIX systems, and the chain of events where the shell <a href= +"../utilities/V3_chap02.html#exec"><i>exec</i></a>s an application that then <a href= +"../utilities/V3_chap02.html#exec"><i>exec</i></a>s <a href="../utilities/vi.html"><i>vi</i></a> usually caused confusion for the +terminal state if SIGTSTP was delivered to the process group in the default manner. The second was that most implementations of the +UNIX <i>curses</i> package did not handle SIGTSTP safely, and the receipt of SIGTSTP at the wrong time would cause them to crash. +POSIX.1-2024 is silent on this issue; implementations are encouraged to treat suspension as an asynchronous event if possible.</p> +<p class="tent">Historically, modifications to the edit buffer made before SIGINT interrupted an operation were retained; that is, +anywhere from zero to all of the lines to be modified might have been modified by the time the SIGINT arrived. These changes were +not discarded by the arrival of SIGINT. POSIX.1-2024 permits this behavior, noting that the <b>undo</b> command is required to be +able to undo these partially completed commands.</p> +<p class="tent">The action taken for signals other than SIGINT, SIGCONT, SIGHUP, and SIGTERM is unspecified because some +implementations attempt to save the edit buffer in a useful state when other signals are received.</p> +<h5><a name="tag_20_40_18_05" id="tag_20_40_18_05"></a>Standard Error</h5> +<p class="tent">For <i>ex</i>/<a href="../utilities/vi.html"><i>vi</i></a>, diagnostic messages are those messages reported as a +result of a failed attempt to invoke <i>ex</i> or <a href="../utilities/vi.html"><i>vi</i></a>, such as invalid options or +insufficient resources, or an abnormal termination condition. Diagnostic messages should not be confused with the error messages +generated by inappropriate or illegal user commands.</p> +<h5><a name="tag_20_40_18_06" id="tag_20_40_18_06"></a>Initialization in ex and vi</h5> +<p class="tent">If an <i>ex</i> command (other than <b>cd</b>, <b>chdir</b>, or <b>source</b>) has a filename argument, one or both +of the alternate and current pathnames will be set. Informally, they are set as follows:</p> +<ol> +<li class="tent">If the <i>ex</i> command is one that replaces the contents of the edit buffer, and it succeeds, the current +pathname will be set to the filename argument (the first filename argument in the case of the <b>next</b> command) and the +alternate pathname will be set to the previous current pathname, if there was one.</li> +<li class="tent">In the case of the file read/write forms of the <b>read</b> and <b>write</b> commands, if there is no current +pathname, the current pathname will be set to the filename argument.</li> +<li class="tent">Otherwise, the alternate pathname will be set to the filename argument.</li> +</ol> +<p class="tent">For example, <b>:edit foo</b> and <b>:recover foo</b>, when successful, set the current pathname, and, if there was +a previous current pathname, the alternate pathname. The commands <b>:write</b>, <b>!command</b>, and <b>:edit</b> set neither the +current or alternate pathnames. If the <b>:edit foo</b> command were to fail for some reason, the alternate pathname would be set. +The <b>read</b> and <b>write</b> commands set the alternate pathname to their <i>file</i> argument, unless the current pathname is +not set, in which case they set the current pathname to their <i>file</i> arguments. The alternate pathname was not historically +set by the <b>:source</b> command. POSIX.1-2024 requires conformance to historical practice. Implementations adding commands that +take filenames as arguments are encouraged to set the alternate pathname as described here.</p> +<p class="tent">Historically, <i>ex</i> and <a href="../utilities/vi.html"><i>vi</i></a> read the <b>.exrc</b> file in the +<i>$HOME</i> directory twice, if the editor was executed in the <i>$HOME</i> directory. POSIX.1-2024 prohibits this behavior.</p> +<p class="tent">Historically, the 4 BSD <i>ex</i> and <a href="../utilities/vi.html"><i>vi</i></a> read the <i>$HOME</i> and local +<b>.exrc</b> files if they were owned by the real ID of the user, or the <b>sourceany</b> option was set, regardless of other +considerations. This was a security problem because it is possible to put normal UNIX system commands inside a <b>.exrc</b> file. +POSIX.1-2024 does not specify the <b>sourceany</b> option, and historical implementations are encouraged to delete it.</p> +<p class="tent">The <b>.exrc</b> files must be owned by the real ID of the user, and not writable by anyone other than the owner. +The appropriate privileges exception is intended to permit users to acquire special privileges, but continue to use the +<b>.exrc</b> files in their home directories.</p> +<p class="tent">System V Release 3.2 and later <a href="../utilities/vi.html"><i>vi</i></a> implementations added the option +<b>[no]exrc</b>. The behavior is that local <b>.exrc</b> files are read-only if the <b>exrc</b> option is set. The default for the +<b>exrc</b> option was off, so by default, local <b>.exrc</b> files were not read. The problem this was intended to solve was that +System V permitted users to give away files, so there is no possible ownership or writeability test to ensure that the file is +safe. This is still a security problem on systems where users can give away files, but there is nothing additional that +POSIX.1-2024 can do. The implementation-defined exception is intended to permit groups to have local <b>.exrc</b> files that are +shared by users, by creating pseudo-users to own the shared files.</p> +<p class="tent">POSIX.1-2024 does not mention system-wide <i>ex</i> and <a href="../utilities/vi.html"><i>vi</i></a> start-up +files. While they exist in several implementations of <i>ex</i> and <a href="../utilities/vi.html"><i>vi</i></a>, they are not +present in any implementations considered historical practice by POSIX.1-2024. Implementations that have such files should use them +only if they are owned by the real user ID or an appropriate user (for example, root on UNIX systems) and if they are not writable +by any user other than their owner. System-wide start-up files should be read before the <i>EXINIT</i> variable, +<b>$HOME/.exrc</b>, or local <b>.exrc</b> files are evaluated.</p> +<p class="tent">Historically, any <i>ex</i> command could be entered in the <i>EXINIT</i> variable or the <b>.exrc</b> file, +although ones requiring that the edit buffer already contain lines of text generally caused historical implementations of the +editor to drop <b>core</b>. POSIX.1-2024 requires that any <i>ex</i> command be permitted in the <i>EXINIT</i> variable and +<b>.exrc</b> files, for simplicity of specification and consistency, although many of them will obviously fail under many +circumstances.</p> +<p class="tent">The initialization of the contents of the edit buffer uses the phrase "the effect shall be" with regard to +various <i>ex</i> commands. The intent of this phrase is that edit buffer contents loaded during the initialization phase not be +lost; that is, loading the edit buffer should fail if the <b>.exrc</b> file read in the contents of a file and did not subsequently +write the edit buffer. An additional intent of this phrase is to specify that the initial current line and column is set as +specified for the individual <i>ex</i> commands.</p> +<p class="tent">Historically, the <b>-t</b> option behaved as if the tag search were a <b>+</b><i>command</i>; that is, it was +executed from the last line of the file specified by the tag. This resulted in the search failing if the pattern was a forward +search pattern and the <b>wrapscan</b> edit option was not set. POSIX.1-2024 does not permit this behavior, requiring that the +search for the tag pattern be performed on the entire file, and, if not found, that the current line be set to a more reasonable +location in the file.</p> +<p class="tent">Historically, the empty edit buffer presented for editing when a file was not specified by the user was unnamed. +This is permitted by POSIX.1-2024; however, implementations are encouraged to provide users a temporary filename for this buffer +because it permits them the use of <i>ex</i> commands that use the current pathname during temporary edit sessions.</p> +<p class="tent">Historically, the file specified using the <b>-t</b> option was not part of the current argument list. This +practice is permitted by POSIX.1-2024; however, implementations are encouraged to include its name in the current argument list for +consistency.</p> +<p class="tent">Historically, the <b>-c</b> command was generally not executed until a file that already exists was edited. +POSIX.1-2024 requires conformance to this historical practice. Commands that could cause the <b>-c</b> command to be executed +include the <i>ex</i> commands <b>edit</b>, <b>next</b>, <b>recover</b>, <b>rewind</b>, and <b>tag</b>, and the <a href= +"../utilities/vi.html"><i>vi</i></a> commands <control>-^ and <control>-]. Historically, reading a file into an edit +buffer did not cause the <b>-c</b> command to be executed (even though it might set the current pathname) with the exception that +it did cause the <b>-c</b> command to be executed if: the editor was in <i>ex</i> mode, the edit buffer had no current pathname, +the edit buffer was empty, and no read commands had yet been attempted. For consistency and simplicity of specification, +POSIX.1-2024 does not permit this behavior.</p> +<p class="tent">Historically, the <b>-r</b> option was the same as a normal edit session if there was no recovery information +available for the file. This allowed users to enter:</p> +<pre> +<tt>vi -r *.c +</tt></pre> +<p class="tent">and recover whatever files were recoverable. In some implementations, recovery was attempted only on the first file +named, and the file was not entered into the argument list; in others, recovery was attempted for each file named. In addition, +some historical implementations ignored <b>-r</b> if <b>-t</b> was specified or did not support command line <i>file</i> arguments +with the <b>-t</b> option. For consistency and simplicity of specification, POSIX.1-2024 disallows these special cases, and +requires that recovery be attempted the first time each file is edited.</p> +<p class="tent">Historically, <a href="../utilities/vi.html"><i>vi</i></a> initialized the <b>`</b> and <b>'</b> marks, but +<i>ex</i> did not. This meant that if the first command in <i>ex</i> mode was <b>visual</b> or if an <i>ex</i> command was executed +first (for example, <a href="../utilities/vi.html"><i>vi</i></a> +10 <i>file</i>), <a href="../utilities/vi.html"><i>vi</i></a> was +entered without the marks being initialized. Because the standard developers believed the marks to be generally useful, and for +consistency and simplicity of specification, POSIX.1-2024 requires that they always be initialized if in open or visual mode, or if +in <i>ex</i> mode and the edit buffer is not empty. Not initializing it in <i>ex</i> mode if the edit buffer is empty is historical +practice; however, it has always been possible to set (and use) marks in empty edit buffers in open and visual mode edit +sessions.</p> +<h5><a name="tag_20_40_18_07" id="tag_20_40_18_07"></a>Addressing</h5> +<p class="tent">Historically, <i>ex</i> and <a href="../utilities/vi.html"><i>vi</i></a> accepted the additional addressing forms +<tt>'\/'</tt> and <tt>'\?'</tt>. They were equivalent to <tt>"//"</tt> and <tt>"??"</tt>, respectively. They are not required by +POSIX.1-2024, mostly because nobody can remember whether they ever did anything different historically.</p> +<p class="tent">Historically, <i>ex</i> and <a href="../utilities/vi.html"><i>vi</i></a> permitted an address of zero for several +commands, and permitted the <b>%</b> address in empty files for others. For consistency, POSIX.1-2024 requires support for the +former in the few commands where it makes sense, and disallows it otherwise. In addition, because POSIX.1-2024 requires that +<b>%</b> be logically equivalent to <tt>"1,$"</tt>, it is also supported where it makes sense and disallowed otherwise.</p> +<p class="tent">Historically, the <b>%</b> address could not be followed by further addresses. For consistency and simplicity of +specification, POSIX.1-2024 requires that additional addresses be supported.</p> +<p class="tent">All of the following are valid <i>addresses</i>:</p> +<dl compact> +<dd></dd> +<dt><tt>+++</tt></dt> +<dd>Three lines after the current line.</dd> +<dt><tt>/</tt><i>re</i><tt>/-</tt></dt> +<dd>One line before the next occurrence of <i>re</i>.</dd> +<dt><tt>-2</tt></dt> +<dd>Two lines before the current line.</dd> +<dt><tt>3 ---- 2</tt></dt> +<dd>Line one (note intermediate negative address).</dd> +<dt><tt>1 2 3</tt></dt> +<dd>Line six.</dd> +</dl> +<p class="tent">Any number of addresses can be provided to commands taking addresses; for example, <tt>"1,2,3,4,5p"</tt> prints +lines 4 and 5, because two is the greatest valid number of addresses accepted by the <b>print</b> command. This, in combination +with the <semicolon> delimiter, permits users to create commands based on ordered patterns in the file. For example, the +command <b>3;/foo/;+2print</b> will display the first line after line 3 that contains the pattern <i>foo</i>, plus the next two +lines. Note that the address <b>3;</b> must be evaluated before being discarded because the search origin for the <b>/foo/</b> +command depends on this.</p> +<p class="tent">Historically, values could be added to addresses by including them after one or more <blank> characters; for +example, <b>3 - 5p</b> wrote the seventh line of the file, and <b>/foo/ 5</b> was the same as <b>/foo/+5</b>. +However, only absolute values could be added; for example, <b>5 /foo/</b> was an error. POSIX.1-2024 requires conformance to +historical practice. Address offsets are separately specified from addresses because they could historically be provided to visual +mode search commands.</p> +<p class="tent">Historically, any missing addresses defaulted to the current line. This was true for leading and trailing +<comma>-delimited addresses, and for trailing <semicolon>-delimited addresses. For consistency, POSIX.1-2024 requires +it for leading <semicolon> addresses as well.</p> +<p class="tent">Historically, <i>ex</i> and <a href="../utilities/vi.html"><i>vi</i></a> accepted the <tt>'^'</tt> character as +both an address and as a flag offset for commands. In both cases it was identical to the <tt>'-'</tt> character. POSIX.1-2024 does +not require or prohibit this behavior.</p> +<p class="tent">Historically, the enhancements to basic regular expressions could be used in addressing; for example, <tt>'~'</tt>, +<tt>'\<'</tt>, and <tt>'\>'</tt>. POSIX.1-2024 requires conformance to historical practice; that is, that regular expression +usage be consistent, and that regular expression enhancements be supported wherever regular expressions are used.</p> +<h5><a name="tag_20_40_18_08" id="tag_20_40_18_08"></a>Command Line Parsing in ex</h5> +<p class="tent">Historical <i>ex</i> command parsing was even more complex than that described here. POSIX.1-2024 requires the +subset of the command parsing that the standard developers believed was documented and that users could reasonably be expected to +use in a portable fashion, and that was historically consistent between implementations. (The discarded functionality is obscure, +at best.) Historical implementations will require changes in order to comply with POSIX.1-2024; however, users are not expected to +notice any of these changes. Most of the complexity in <i>ex</i> parsing is to handle three special termination cases:</p> +<ol> +<li class="tent">The <b>!</b>, <b>global</b>, <b>v</b>, and the filter versions of the <b>read</b> and <b>write</b> commands are +delimited by <newline> characters (they can contain <vertical-line> characters that are usually shell pipes).</li> +<li class="tent">The <b>ex</b>, <b>edit</b>, <b>next</b>, and <b>visual</b> in open and visual mode commands all take <i>ex</i> +commands, optionally containing <vertical-line> characters, as their first arguments.</li> +<li class="tent">The <b>s</b> command takes a regular expression as its first argument, and uses the delimiting characters to +delimit the command.</li> +</ol> +<p class="tent">Historically, <vertical-line> characters in the <b>+</b><i>command</i> argument of the <b>ex</b>, +<b>edit</b>, <b>next</b>, <b>vi</b>, and <b>visual</b> commands, and in the <i>pattern</i> and <i>replacement</i> parts of the +<b>s</b> command, did not delimit the command, and in the filter cases for <b>read</b> and <b>write</b>, and the <b>!</b>, +<b>global</b>, and <b>v</b> commands, they did not delimit the command at all. For example, the following commands are all +valid:</p> +<pre> +<b>:</b><tt>edit +25 | s/abc/ABC/ file.c +</tt><b>:</b><tt>s/ | /PIPE/ +</tt><b>:</b><tt>read !spell % | columnate +</tt><b>:</b><tt>global/pattern/p | l +</tt><b>:</b><tt>s/a/b/ | s/c/d | set +</tt></pre> +<p class="tent">Historically, empty or <blank> filled lines in <b>.exrc</b> files and <b>source</b>d files (as well as +<i>EXINIT</i> variables and <i>ex</i> command scripts) were treated as default commands; that is, <b>print</b> commands. +POSIX.1-2024 specifically requires that they be ignored when encountered in <b>.exrc</b> and <b>source</b>d files to eliminate a +common source of new user error.</p> +<p class="tent">Historically, <i>ex</i> commands with multiple adjacent (or <blank>-separated) vertical lines were handled +oddly when executed from <i>ex</i> mode. For example, the command <b>|||</b> <carriage-return>, when the cursor was on line +1, displayed lines 2, 3, and 5 of the file. In addition, the command <b>|</b> would only display the line after the next line, +instead of the next two lines. The former worked more logically when executed from <a href="../utilities/vi.html"><i>vi</i></a> +mode, and displayed lines 2, 3, and 4. POSIX.1-2024 requires the <a href="../utilities/vi.html"><i>vi</i></a> behavior; that is, a +single default command and line number increment for each command separator, and trailing <newline> characters after +<vertical-line> separators are discarded.</p> +<p class="tent">Historically, <i>ex</i> permitted a single extra <colon> as a leading command character; for example, +<b>:g/pattern/:p</b> was a valid command. POSIX.1-2024 generalizes this to require that any number of leading <colon> +characters be stripped.</p> +<p class="tent">Historically, any prefix of the <b>delete</b> command could be followed without intervening <blank> +characters by a flag character because in the command <b>d p</b>, <i>p</i> is interpreted as the buffer <i>p</i>. POSIX.1-2024 +requires conformance to historical practice.</p> +<p class="tent">Historically, the <b>k</b> command could be followed by the mark name without intervening <blank> characters. +POSIX.1-2024 requires conformance to historical practice.</p> +<p class="tent">Historically, the <b>s</b> command could be immediately followed by flag and option characters; for example, +<b>s/e/E/|s|sgc3p</b> was a valid command. However, flag characters could not stand alone; for example, the commands <b>sp</b> and +<b>s l</b> would fail, while the command <b>sgp</b> and <b>s gl</b> would succeed. (Obviously, the <tt>'#'</tt> flag +character was used as a delimiter character if it followed the command.) Another issue was that option characters had to precede +flag characters even when the command was fully specified; for example, the command <b>s/e/E/pg</b> would fail, while the command +<b>s/e/E/gp</b> would succeed. POSIX.1-2024 requires conformance to historical practice.</p> +<p class="tent">Historically, the first command name that had a prefix matching the input from the user was the executed command; +for example, <b>ve</b>, <b>ver</b>, and <b>vers</b> all executed the <b>version</b> command. Commands were in a specific order, +however, so that <b>a</b> matched <b>append</b>, not <b>abbreviate</b>. POSIX.1-2024 requires conformance to historical practice. +The restriction on command search order for implementations with extensions is to avoid the addition of commands such that the +historical prefixes would fail to work portably.</p> +<p class="tent">Historical implementations of <i>ex</i> and <a href="../utilities/vi.html"><i>vi</i></a> did not correctly handle +multiple <i>ex</i> commands, separated by <vertical-line> characters, that entered or exited visual mode or the editor. +Because implementations of <a href="../utilities/vi.html"><i>vi</i></a> exist that do not exhibit this failure mode, POSIX.1-2024 +does not permit it.</p> +<p class="tent">The requirement that alphabetic command names consist of all following alphabetic characters up to the next +non-alphabetic character means that alphabetic command names must be separated from their arguments by one or more non-alphabetic +characters, normally a <blank> or <tt>'!'</tt> character, except as specified for the exceptions, the <b>delete</b>, +<b>k</b>, and <b>s</b> commands.</p> +<p class="tent">Historically, the repeated execution of the <i>ex</i> default <b>print</b> commands (<control>-D, <i>eof</i>, +<newline>, <carriage-return>) erased any prompting character and displayed the next lines without scrolling the +terminal; that is, immediately below any previously displayed lines. This provided a cleaner presentation of the lines in the file +for the user. POSIX.1-2024 does not require this behavior because it may be impossible in some situations; however, implementations +are strongly encouraged to provide this semantic if possible.</p> +<p class="tent">Historically, it was possible to change files in the middle of a command, and have the rest of the command executed +in the new file; for example:</p> +<pre> +<tt>:edit +25 file.c | s/abc/ABC/ | 1 +</tt></pre> +<p class="tent">was a valid command, and the substitution was attempted in the newly edited file. POSIX.1-2024 requires conformance +to historical practice. The following commands are examples that exercise the <i>ex</i> parser:</p> +<pre> +<tt>echo 'foo | bar' > file1; echo 'foo/bar' > file2; +vi +:edit +1 | s/|/PIPE/ | w file1 | e file2 | 1 | s/\//SLASH/ | wq +</tt></pre> +<p class="tent">Historically, there was no protection in editor implementations to avoid <i>ex</i> <b>global</b>, <b>v</b>, +<b>@</b>, or <b>*</b> commands changing edit buffers during execution of their associated commands. Because this would almost +invariably result in catastrophic failure of the editor, and implementations exist that do exhibit these problems, POSIX.1-2024 +requires that changing the edit buffer during a <b>global</b> or <b>v</b> command, or during a <b>@</b> or <b>*</b> command for +which there will be more than a single execution, be an error. Implementations supporting multiple edit buffers simultaneously are +strongly encouraged to apply the same semantics to switching between buffers as well.</p> +<p class="tent">The <i>ex</i> command quoting required by POSIX.1-2024 is a superset of the quoting in historical implementations +of the editor. For example, it was not historically possible to escape a <blank> in a filename; for example, +<b>:edit foo\\\ bar</b> would report that too many filenames had been entered for the edit command, and there was no +method of escaping a <blank> in the first argument of an <b>edit</b>, <b>ex</b>, <b>next</b>, or <b>visual</b> command at +all. POSIX.1-2024 extends historical practice, requiring that quoting behavior be made consistent across all <i>ex</i> commands, +except for the <b>map</b>, <b>unmap</b>, <b>abbreviate</b>, and <b>unabbreviate</b> commands, which historically used +<control>-V instead of <backslash> characters for quoting. For those four commands, POSIX.1-2024 requires conformance +to historical practice.</p> +<p class="tent">Backslash quoting in <i>ex</i> is non-intuitive. <backslash>-escapes are ignored unless they escape a special +character; for example, when performing <i>file</i> argument expansion, the string <tt>"\\%"</tt> is equivalent to <tt>'\%'</tt>, +not <tt>"\<</tt><i>current pathname</i><tt>>"</tt>. This can be confusing for users because <backslash> is usually +one of the characters that causes shell expansion to be performed, and therefore shell quoting rules must be taken into +consideration. Generally, quoting characters are only considered if they escape a special character, and a quoting character must +be provided for each layer of parsing for which the character is special. As another example, only a single <backslash> is +necessary for the <tt>'\l'</tt> sequence in substitute replacement patterns, because the character <tt>'l'</tt> is not special to +any parsing layer above it.</p> +<p class="tent"><control>-V quoting in <i>ex</i> is slightly different from backslash quoting. In the four commands where +<control>-V quoting applies (<b>abbreviate</b>, <b>unabbreviate</b>, <b>map</b>, and <b>unmap</b>), any character may be +escaped by a <control>-V whether it would have a special meaning or not. POSIX.1-2024 requires conformance to historical +practice.</p> +<p class="tent">Historical implementations of the editor did not require delimiters within character classes to be escaped; for +example, the command <b>:s/[/]//</b> on the string <tt>"xxx/yyy"</tt> would delete the <tt>'/'</tt> from the string. POSIX.1-2024 +disallows this historical practice for consistency and because it places a large burden on implementations by requiring that +knowledge of regular expressions be built into the editor parser.</p> +<p class="tent">Historically, quoting <newline> characters in <i>ex</i> commands was handled inconsistently. In most cases, +the <newline> character always terminated the command, regardless of any preceding escape character, because +<backslash> characters did not escape <newline> characters for most <i>ex</i> commands. However, some <i>ex</i> +commands (for example, <b>s</b>, <b>map</b>, and <b>abbreviation</b>) permitted <newline> characters to be escaped (although +in the case of <b>map</b> and <b>abbreviation</b>, <control>-V characters escaped them instead of <backslash> +characters). This was true in not only the command line, but also <b>.exrc</b> and <b>source</b>d files. For example, the +command:</p> +<pre> +<tt>map = foo<control-V><newline>bar +</tt></pre> +<p class="tent">would succeed, although it was sometimes difficult to get the <control>-V and the inserted <newline> +passed to the <i>ex</i> parser. For consistency and simplicity of specification, POSIX.1-2024 requires that it be possible to +escape <newline> characters in <i>ex</i> commands at all times, using <backslash> characters for most <i>ex</i> +commands, and using <control>-V characters for the <b>map</b> and <b>abbreviation</b> commands. For example, the command +<b>print</b><newline><b>list</b> is required to be parsed as the single command <b>print</b><newline><b>list</b>. While +this differs from historical practice, POSIX.1-2024 developers believed it unlikely that any script or user depended on the +historical behavior.</p> +<p class="tent">Historically, an error in a command specified using the <b>-c</b> option did not cause the rest of the <b>-c</b> +commands to be discarded. POSIX.1-2024 disallows this for consistency with mapped keys, the <b>@</b>, <b>global</b>, <b>source</b>, +and <b>v</b> commands, the <i>EXINIT</i> environment variable, and the <b>.exrc</b> files.</p> +<h5><a name="tag_20_40_18_09" id="tag_20_40_18_09"></a>Input Editing in ex</h5> +<p class="tent">One of the common uses of the historical <i>ex</i> editor is over slow network connections. Editors that run in +canonical mode can require far less traffic to and from, and far less processing on, the host machine, as well as more easily +supporting block-mode terminals. For these reasons, POSIX.1-2024 requires that <i>ex</i> be implemented using canonical mode input +processing, as was done historically.</p> +<p class="tent">POSIX.1-2024 does not require the historical 4 BSD input editing characters "word erase" or "literal next". For +this reason, it is unspecified how they are handled by <i>ex</i>, although they must have the required effect. Implementations that +resolve them after the line has been ended using a <newline> or <control>-M character, and implementations that rely on +the underlying system terminal support for this processing, are both conforming. Implementations are strongly urged to use the +underlying system functionality, if at all possible, for compatibility with other system text input interfaces.</p> +<p class="tent">Historically, when the <i>eof</i> character was used to decrement the <b>autoindent</b> level, the cursor moved to +display the new end of the <b>autoindent</b> characters, but did not move the cursor to a new line, nor did it erase the +<control>-D character from the line. POSIX.1-2024 does not specify that the cursor remain on the same line or that the rest +of the line is erased; however, implementations are strongly encouraged to provide the best possible user interface; that is, the +cursor should remain on the same line, and any <control>-D character on the line should be erased.</p> +<p class="tent">POSIX.1-2024 does not require the historical 4 BSD input editing character "reprint", traditionally +<control>-R, which redisplayed the current input from the user. For this reason, and because the functionality cannot be +implemented after the line has been terminated by the user, POSIX.1-2024 makes no requirements about this functionality. +Implementations are strongly urged to make this historical functionality available, if possible.</p> +<p class="tent">Historically, <control>-Q did not perform a literal next function in <i>ex</i>, as it did in <a href= +"../utilities/vi.html"><i>vi</i></a>. POSIX.1-2024 requires conformance to historical practice to avoid breaking historical +<i>ex</i> scripts and <b>.exrc</b> files.</p> +<h5><a name="tag_20_40_18_10" id="tag_20_40_18_10"></a>eof</h5> +<p class="tent">Whether the <i>eof</i> character immediately modifies the <b>autoindent</b> characters in the prompt is left +unspecified so that implementations can conform in the presence of systems that do not support this functionality. Implementations +are encouraged to modify the line and redisplay it immediately, if possible.</p> +<p class="tent">The specification of the handling of the <i>eof</i> character differs from historical practice only in that +<i>eof</i> characters are not discarded if they follow normal characters in the text input. Historically, they were always +discarded.</p> +<h5><a name="tag_20_40_18_11" id="tag_20_40_18_11"></a>Command Descriptions in ex</h5> +<p class="tent">Historically, several commands (for example, <b>global</b>, <b>v</b>, <b>visual</b>, <b>s</b>, <b>write</b>, +<b>wq</b>, <b>yank</b>, <b>!</b>, <b><</b>, <b>></b>, <b>&</b>, and <b>~</b>) were executable in empty files (that is, the +default address(es) were 0), or permitted explicit addresses of 0 (for example, 0 was a valid address, or 0,0 was a valid range). +Addresses of 0, or command execution in an empty file, make sense only for commands that add new text to the edit buffer or write +commands (because users may wish to write empty files). POSIX.1-2024 requires this behavior for such commands and disallows it +otherwise, for consistency and simplicity of specification.</p> +<p class="tent">A count to an <i>ex</i> command has been historically corrected to be no greater than the last line in a file; for +example, in a five-line file, the command <b>1,6print</b> would fail, but the command <b>1print300</b> would succeed. POSIX.1-2024 +requires conformance to historical practice.</p> +<p class="tent">Historically, the use of flags in <i>ex</i> commands could be obscure. General historical practice was as described +by POSIX.1-2024, but there were some special cases. For instance, the <b>list</b>, <b>number</b>, and <b>print</b> commands ignored +trailing address offsets; for example, <b>3p +++#</b> would display line 3, and 3 would be the current line after the +execution of the command. The <b>open</b> and <b>visual</b> commands ignored both the trailing offsets and the trailing flags. +Also, flags specified to the <b>open</b> and <b>visual</b> commands interacted badly with the <b>list</b> edit option, and setting +and then unsetting it during the open/visual session would cause <a href="../utilities/vi.html"><i>vi</i></a> to stop displaying +lines in the specified format. For consistency and simplicity of specification, POSIX.1-2024 does not permit any of these +exceptions to the general rule.</p> +<p class="tent">POSIX.1-2024 uses the word <i>copy</i> in several places when discussing buffers. This is not intended to imply +implementation.</p> +<p class="tent">Historically, <i>ex</i> users could not specify numeric buffers because of the ambiguity this would cause; for +example, in the command <b>3 delete 2</b>, it is unclear whether 2 is a buffer name or a <i>count</i>. POSIX.1-2024 +requires conformance to historical practice by default, but does not preclude extensions.</p> +<p class="tent">Historically, the contents of the unnamed buffer were frequently discarded after commands that did not explicitly +affect it; for example, when using the <b>edit</b> command to switch files. For consistency and simplicity of specification, +POSIX.1-2024 does not permit this behavior.</p> +<p class="tent">The <i>ex</i> utility did not historically have access to the numeric buffers, and, furthermore, deleting lines in +<i>ex</i> did not modify their contents. For example, if, after doing a delete in <a href="../utilities/vi.html"><i>vi</i></a>, the +user switched to <i>ex</i>, did another delete, and then switched back to <a href="../utilities/vi.html"><i>vi</i></a>, the +contents of the numeric buffers would not have changed. POSIX.1-2024 requires conformance to historical practice. Numeric buffers +are described in the <i>ex</i> utility in order to confine the description of buffers to a single location in POSIX.1-2024.</p> +<p class="tent">The metacharacters that trigger shell expansion in <i>file</i> arguments match historical practice, as does the +method for doing shell expansion. Implementations wishing to provide users with the flexibility to alter the set of metacharacters +are encouraged to provide a <b>shellmeta</b> string edit option.</p> +<p class="tent">Historically, <i>ex</i> commands executed from <a href="../utilities/vi.html"><i>vi</i></a> refreshed the screen +when it did not strictly need to do so; for example, <b>:!date > /dev/null</b> does not require a screen refresh +because the output of the UNIX <a href="../utilities/date.html"><i>date</i></a> command requires only a single line of the screen. +POSIX.1-2024 requires that the screen be refreshed if it has been overwritten, but makes no requirements as to how an +implementation should make that determination. Implementations may prompt and refresh the screen regardless.</p> +<h5><a name="tag_20_40_18_12" id="tag_20_40_18_12"></a>Abbreviate</h5> +<p class="tent">Historical practice was that characters that were entered as part of an abbreviation replacement were subject to +<b>map</b> expansions, the <b>showmatch</b> edit option, further abbreviation expansions, and so on; that is, they were logically +pushed onto the terminal input queue, and were not a simple replacement. POSIX.1-2024 requires conformance to historical practice. +Historical practice was that whenever a non-word character (that had not been escaped by a <control>-V) was entered after a +word character, <a href="../utilities/vi.html"><i>vi</i></a> would check for abbreviations. The check was based on the type of the +character entered before the word character of the word/non-word pair that triggered the check. The word character of the +word/non-word pair that triggered the check and all characters entered before the trigger pair that were of that type were included +in the check, with the exception of <blank> characters, which always delimited the abbreviation.</p> +<p class="tent">This means that, for the abbreviation to work, the <i>lhs</i> must end with a word character, there can be no +transitions from word to non-word characters (or <i>vice versa</i>) other than between the last and next-to-last characters in the +<i>lhs</i>, and there can be no <blank> characters in the <i>lhs</i>. In addition, because of the historical quoting rules, +it was impossible to enter a literal <control>-V in the <i>lhs</i>. POSIX.1-2024 requires conformance to historical practice. +Historical implementations did not inform users when abbreviations that could never be used were entered; implementations are +strongly encouraged to do so.<br></p> +<p class="tent">For example, the following abbreviations will work:</p> +<pre> +<tt>:ab (p REPLACE +:ab p REPLACE +:ab ((p REPLACE +</tt></pre> +<p class="tent">The following abbreviations will not work:</p> +<pre> +<tt>:ab ( REPLACE +:ab (pp REPLACE +</tt></pre> +<p class="tent">Historical practice is that words on the <a href="../utilities/vi.html"><i>vi</i></a> colon command line were +subject to abbreviation expansion, including the arguments to the <b>abbrev</b> (and more interestingly) the <b>unabbrev</b> +command. Because there are implementations that do not do abbreviation expansion for the first argument to those commands, this is +permitted, but not required, by POSIX.1-2024. However, the following sequence:</p> +<pre> +<tt>:ab foo bar +:ab foo baz +</tt></pre> +<p class="tent">resulted in the addition of an abbreviation of <tt>"baz"</tt> for the string <tt>"bar"</tt> in historical +<i>ex</i>/<a href="../utilities/vi.html"><i>vi</i></a>, and the sequence:</p> +<pre> +<tt>:ab foo1 bar +:ab foo2 bar +:unabbreviate foo2 +</tt></pre> +<p class="tent">deleted the abbreviation <tt>"foo1"</tt>, not <tt>"foo2"</tt>. These behaviors are not permitted by POSIX.1-2024 +because they clearly violate the expectations of the user.</p> +<p class="tent">It was historical practice that <control>-V, not <backslash>, characters be interpreted as escaping +subsequent characters in the <b>abbreviate</b> command. POSIX.1-2024 requires conformance to historical practice; however, it +should be noted that an abbreviation containing a <blank> will never work.</p> +<h5><a name="tag_20_40_18_13" id="tag_20_40_18_13"></a>Append</h5> +<p class="tent">Historically, any text following a <vertical-line> command separator after an <b>append</b>, <b>change</b>, +or <b>insert</b> command became part of the insert text. For example, in the command:</p> +<pre> +<tt>:g/pattern/append|stuff1 +</tt></pre> +<p class="tent">a line containing the text <tt>"stuff1"</tt> would be appended to each line matching pattern. It was also +historically valid to enter:</p> +<pre> +<tt>:append|stuff1 +stuff2 +. +</tt></pre> +<p class="tent">and the text on the <i>ex</i> command line would be appended along with the text inserted after it. There was an +historical bug, however, that the user had to enter two terminating lines (the <tt>'.'</tt> lines) to terminate text input mode in +this case. POSIX.1-2024 requires conformance to historical practice, but disallows the historical need for multiple terminating +lines.</p> +<h5><a name="tag_20_40_18_14" id="tag_20_40_18_14"></a>Change</h5> +<p class="tent">See the RATIONALE for the <b>append</b> command. Historical practice for cursor positioning after the change +command when no text is input, is as described in POSIX.1-2024. However, one System V implementation is known to have been modified +such that the cursor is positioned on the first address specified, and not on the line before the first address. POSIX.1-2024 +disallows this modification for consistency.</p> +<p class="tent">Historically, the <b>change</b> command did not support buffer arguments, although some implementations allow the +specification of an optional buffer. This behavior is neither required nor disallowed by POSIX.1-2024.</p> +<h5><a name="tag_20_40_18_15" id="tag_20_40_18_15"></a>Change Directory</h5> +<p class="tent">A common extension in <i>ex</i> implementations is to use the elements of a <b>cdpath</b> edit option as prefix +directories for <i>path</i> arguments to <b>chdir</b> that are relative pathnames and that do not have <tt>'.'</tt> or +<tt>".."</tt> as their first component. Elements in the <b>cdpath</b> edit option are <colon>-separated. The initial value of +the <b>cdpath</b> edit option is the value of the shell <i>CDPATH</i> environment variable. This feature was not included in +POSIX.1-2024 because it does not exist in any of the implementations considered historical practice.</p> +<h5><a name="tag_20_40_18_16" id="tag_20_40_18_16"></a>Copy</h5> +<p class="tent">Historical implementations of <i>ex</i> permitted copies to lines inside of the specified range; for example, +<b>:2,5copy3</b> was a valid command. POSIX.1-2024 requires conformance to historical practice.</p> +<h5><a name="tag_20_40_18_17" id="tag_20_40_18_17"></a>Delete</h5> +<p class="tent">POSIX.1-2024 requires support for the historical parsing of a <b>delete</b> command followed by flags, without any +intervening <blank> characters. For example:</p> +<dl compact> +<dd></dd> +<dt><b>1dp</b></dt> +<dd>Deletes the first line and prints the line that was second.</dd> +<dt><b>1delep</b></dt> +<dd>As for <b>1dp</b>.</dd> +<dt><b>1d</b></dt> +<dd>Deletes the first line, saving it in buffer <i>p</i>.</dd> +<dt><b>1d p1l</b></dt> +<dd>(Pee-one-ell.) Deletes the first line, saving it in buffer <i>p</i>, and listing the line that was second.</dd> +</dl> +<h5><a name="tag_20_40_18_18" id="tag_20_40_18_18"></a>Edit</h5> +<p class="tent">Historically, any <i>ex</i> command could be entered as a <b>+</b><i>command</i> argument to the <b>edit</b> +command, although some (for example, <b>insert</b> and <b>append</b>) were known to confuse historical implementations. For +consistency and simplicity of specification, POSIX.1-2024 requires that any command be supported as an argument to the <b>edit</b> +command.</p> +<p class="tent">Historically, the command argument was executed with the current line set to the last line of the file, regardless +of whether the <b>edit</b> command was executed from visual mode or not. POSIX.1-2024 requires conformance to historical +practice.</p> +<p class="tent">Historically, the <b>+</b><i>command</i> specified to the <b>edit</b> and <b>next</b> commands was delimited by the +first <blank>, and there was no way to quote them. For consistency, POSIX.1-2024 requires that the usual <i>ex</i> backslash +quoting be provided.</p> +<p class="tent">Historically, specifying the <b>+</b><i>command</i> argument to the edit command required a filename to be +specified as well; for example, <b>:edit +100</b> would always fail. For consistency and simplicity of specification, +POSIX.1-2024 does not permit this usage to fail for that reason.</p> +<p class="tent">Historically, only the cursor position of the last file edited was remembered by the editor. POSIX.1-2024 requires +that this be supported; however, implementations are permitted to remember and restore the cursor position for any file previously +edited.</p> +<h5><a name="tag_20_40_18_19" id="tag_20_40_18_19"></a>File</h5> +<p class="tent">Historical versions of the <i>ex</i> editor <b>file</b> command displayed a current line and number of lines in the +edit buffer of 0 when the file was empty, while the <a href="../utilities/vi.html"><i>vi</i></a> <control>-G command +displayed a current line and number of lines in the edit buffer of 1 in the same situation. POSIX.1-2024 does not permit this +discrepancy, instead requiring that a message be displayed indicating that the file is empty.</p> +<h5><a name="tag_20_40_18_20" id="tag_20_40_18_20"></a>Global</h5> +<p class="tent">The two-pass operation of the <b>global</b> and <b>v</b> commands is not intended to imply implementation, only the +required result of the operation.</p> +<p class="tent">The current line and column are set as specified for the individual <i>ex</i> commands. This requirement is +cumulative; that is, the current line and column must track across all the commands executed by the <b>global</b> or <b>v</b> +commands.</p> +<h5><a name="tag_20_40_18_21" id="tag_20_40_18_21"></a>Insert</h5> +<p class="tent">See the RATIONALE for the <b>append</b> command.</p> +<p class="tent">Historically, <b>insert</b> could not be used with an address of zero; that is, not when the edit buffer was empty. +POSIX.1-2024 requires that this command behave consistently with the <b>append</b> command.</p> +<h5><a name="tag_20_40_18_22" id="tag_20_40_18_22"></a>Join</h5> +<p class="tent">The action of the <b>join</b> command in relation to the special characters is only defined for the POSIX locale +because the correct amount of white space after a period varies; in Japanese none is required, in French only a single space, and +so on.</p> +<h5><a name="tag_20_40_18_23" id="tag_20_40_18_23"></a>List</h5> +<p class="tent">The historical output of the <b>list</b> command was potentially ambiguous. The standard developers believed +correcting this to be more important than adhering to historical practice, and POSIX.1-2024 requires unambiguous output.</p> +<h5><a name="tag_20_40_18_24" id="tag_20_40_18_24"></a>Map</h5> +<p class="tent">Historically, command mode maps only applied to command names; for example, if the character <tt>'x'</tt> was +mapped to <tt>'y'</tt>, the command <b>fx</b> searched for the <tt>'x'</tt> character, not the <tt>'y'</tt> character. POSIX.1-2024 +requires this behavior. Historically, entering <control>-V as the first character of a <a href= +"../utilities/vi.html"><i>vi</i></a> command was an error. Several implementations have extended the semantics of <a href= +"../utilities/vi.html"><i>vi</i></a> such that <control>-V means that the subsequent command character is not mapped. This is +permitted, but not required, by POSIX.1-2024. Regardless, using <control>-V to escape the second or later character in a +sequence of characters that might match a <b>map</b> command, or any character in text input mode, is historical practice, and +stops the entered keys from matching a map. POSIX.1-2024 requires conformance to historical practice.</p> +<p class="tent">Historical implementations permitted digits to be used as a <b>map</b> command <i>lhs</i>, but then ignored the +map. POSIX.1-2024 requires that the mapped digits not be ignored.</p> +<p class="tent">The historical implementation of the <b>map</b> command did not permit <b>map</b> commands that were more than a +single character in length if the first character was printable. This behavior is permitted, but not required, by POSIX.1-2024.</p> +<p class="tent">Historically, mapped characters were remapped unless the <b>remap</b> edit option was not set, or the prefix of the +mapped characters matched the mapping characters; for example, in the <b>map</b>:</p> +<pre> +<tt>:map ab abcd +</tt></pre> +<p class="tent">the characters <tt>"ab"</tt> were used as is and were not remapped, but the characters <tt>"cd"</tt> were mapped if +appropriate. This can cause infinite loops in the <a href="../utilities/vi.html"><i>vi</i></a> mapping mechanisms. POSIX.1-2024 +requires conformance to historical practice, and that such loops be interruptible.</p> +<p class="tent">Text input maps had the same problems with expanding the <i>lhs</i> for the <i>ex</i> <b>map!</b> and <b>unmap!</b> +command as did the <i>ex</i> <b>abbreviate</b> and <b>unabbreviate</b> commands. See the RATIONALE for the <i>ex</i> +<b>abbreviate</b> command. POSIX.1-2024 requires similar modification of some historical practice for the <b>map</b> and +<b>unmap</b> commands, as described for the <b>abbreviate</b> and <b>unabbreviate</b> commands.</p> +<p class="tent">Historically, <b>map</b>s that were subsets of other <b>map</b>s behaved differently depending on the order in +which they were defined. For example:</p> +<pre> +<tt>:map! ab short +:map! abc long +</tt></pre> +<p class="tent">would always translate the characters <tt>"ab"</tt> to <tt>"short"</tt>, regardless of how fast the characters +<tt>"abc"</tt> were entered. If the entry order was reversed:</p> +<pre> +<tt>:map! abc long +:map! ab short +</tt></pre> +<p class="tent">the characters <tt>"ab"</tt> would cause the editor to pause, waiting for the completing <tt>'c'</tt> character, +and the characters might never be mapped to <tt>"short"</tt>. For consistency and simplicity of specification, POSIX.1-2024 +requires that the shortest match be used at all times.</p> +<p class="tent">The length of time the editor spends waiting for the characters to complete the <i>lhs</i> is unspecified because +the timing capabilities of systems are often inexact and variable, and it may depend on other factors such as the speed of the +connection. The time should be long enough for the user to be able to complete the sequence, but not long enough for the user to +have to wait. Some implementations of <a href="../utilities/vi.html"><i>vi</i></a> have added a <b>keytime</b> option, which +permits users to set the number of 0,1 seconds the editor waits for the completing characters. Because mapped terminal function and +cursor keys tend to start with an <ESC> character, and <ESC> is the key ending <a href= +"../utilities/vi.html"><i>vi</i></a> text input mode, <b>map</b>s starting with <ESC> characters are generally exempted from +this timeout period, or, at least timed out differently.</p> +<h5><a name="tag_20_40_18_25" id="tag_20_40_18_25"></a>Mark</h5> +<p class="tent">Historically, users were able to set the "previous context" marks explicitly. In addition, the <i>ex</i> commands +<tt>''</tt> and <tt>'`</tt> and the <a href="../utilities/vi.html"><i>vi</i></a> commands <tt>''</tt>, <tt>``</tt>, <tt>`'</tt>, +and <tt>'`</tt> all referred to the same mark. In addition, the previous context marks were not set if the command, with which the +address setting the mark was associated, failed. POSIX.1-2024 requires conformance to historical practice. Historically, if marked +lines were deleted, the mark was also deleted, but would reappear if the change was undone. POSIX.1-2024 requires conformance to +historical practice.</p> +<p class="tent">The description of the special events that set the <b>`</b> and <b>'</b> marks matches historical practice. For +example, historically the command <b>/a/,/b/</b> did not set the <b>`</b> and <b>'</b> marks, but the command <b>/a/,/b/delete</b> +did.</p> +<h5><a name="tag_20_40_18_26" id="tag_20_40_18_26"></a>Next</h5> +<p class="tent">Historically, any <i>ex</i> command could be entered as a <b>+</b><i>command</i> argument to the <b>next</b> +command, although some (for example, <b>insert</b> and <b>append</b>) were known to confuse historical implementations. +POSIX.1-2024 requires that any command be permitted and that it behave as specified. The <b>next</b> command can accept more than +one file, so usage such as:</p> +<pre> +<tt>next `ls [abc] ` +</tt></pre> +<p class="tent">is valid; it need not be valid for the <b>edit</b> or <b>read</b> commands, for example, because they expect only +one filename.</p> +<p class="tent">Historically, the <b>next</b> command behaved differently from the <b>:rewind</b> command in that it ignored the +force flag if the <b>autowrite</b> flag was set. For consistency, POSIX.1-2024 does not permit this behavior.</p> +<p class="tent">Historically, the <b>next</b> command positioned the cursor as if the file had never been edited before, +regardless. POSIX.1-2024 does not permit this behavior, for consistency with the <b>edit</b> command.</p> +<p class="tent">Implementations wanting to provide a counterpart to the <b>next</b> command that edited the previous file have used +the command <b>prev[ious],</b> which takes no <i>file</i> argument. POSIX.1-2024 does not require this command.</p> +<h5><a name="tag_20_40_18_27" id="tag_20_40_18_27"></a>Open</h5> +<p class="tent">Historically, the <b>open</b> command would fail if the <b>open</b> edit option was not set. POSIX.1-2024 does not +mention the <b>open</b> edit option and does not require this behavior. Some historical implementations do not permit entering open +mode from open or visual mode, only from <i>ex</i> mode. For consistency, POSIX.1-2024 does not permit this behavior.</p> +<p class="tent">Historically, entering open mode from the command line (that is, <a href="../utilities/vi.html"><i>vi</i></a> +<b>+open</b>) resulted in anomalous behaviors; for example, the <i>ex</i> file and <a href= +"../utilities/V3_chap02.html#set"><i>set</i></a> commands, and the <a href="../utilities/vi.html"><i>vi</i></a> command +<control>-G did not work. For consistency, POSIX.1-2024 does not permit this behavior.</p> +<p class="tent">Historically, the <b>open</b> command only permitted <tt>'/'</tt> characters to be used as the search pattern +delimiter. For consistency, POSIX.1-2024 requires that the search delimiters used by the <b>s</b>, <b>global</b>, and <b>v</b> +commands be accepted as well.</p> +<h5><a name="tag_20_40_18_28" id="tag_20_40_18_28"></a>Preserve</h5> +<p class="tent">The <b>preserve</b> command does not historically cause the file to be considered unmodified for the purposes of +future commands that may exit the editor. POSIX.1-2024 requires conformance to historical practice.</p> +<p class="tent">Historical documentation stated that mail was not sent to the user when preserve was executed; however, historical +implementations did send mail in this case. POSIX.1-2024 requires conformance to the historical implementations.</p> +<h5><a name="tag_20_40_18_29" id="tag_20_40_18_29"></a>Print</h5> +<p class="tent">The writing of NUL by the <b>print</b> command is not specified as a special case because the standard developers +did not want to require <i>ex</i> to support NUL characters. Historically, characters were displayed using the ARPA standard +mappings, which are as follows:</p> +<ol> +<li class="tent">Printable characters are left alone.</li> +<li class="tent">Control characters less than \177 are represented as <tt>'^'</tt> followed by the character offset from the +<tt>'@'</tt> character in the ASCII map; for example, \007 is represented as <tt>'^G'</tt>.</li> +<li class="tent">\177 is represented as <tt>'^'</tt> followed by <tt>'?'</tt>.</li> +</ol> +<p class="tent">The display of characters having their eighth bit set was less standard. Existing implementations use hex (0x00), +octal (\000), and a meta-bit display. (The latter displayed bytes that had their eighth bit set as the two characters <tt>"M-"</tt> +followed by the seven-bit display as described above.) The latter probably has the best claim to historical practice because it was +used for the <b>-v</b> option of 4 BSD and 4 BSD-derived versions of the <a href="../utilities/cat.html"><i>cat</i></a> utility +since 1980.</p> +<p class="tent">No specific display format is required by POSIX.1-2024.</p> +<p class="tent">Explicit dependence on the ASCII character set has been avoided where possible, hence the use of the phrase an +"implementation-defined multi-character sequence" for the display of non-printable characters in preference to the historical +usage of, for instance, <tt>"^I"</tt> for the <tab>. Implementations are encouraged to conform to historical practice in the +absence of any strong reason to diverge.</p> +<p class="tent">Historically, all <i>ex</i> commands beginning with the letter <tt>'p'</tt> could be entered using capitalized +versions of the commands; for example, <b>P[rint]</b>, <b>Pre[serve]</b>, and <b>Pu[t]</b> were all valid command names. +POSIX.1-2024 permits, but does not require, this historical practice because capital forms of the commands are used by some +implementations for other purposes.</p> +<h5><a name="tag_20_40_18_30" id="tag_20_40_18_30"></a>Put</h5> +<p class="tent">Historically, an <i>ex</i> <b>put</b> command, executed from open or visual mode, was the same as the open or +visual mode <b>P</b> command, if the buffer was named and was cut in character mode, and the same as the <b>p</b> command if the +buffer was named and cut in line mode. If the unnamed buffer was the source of the text, the entire line from which the text was +taken was usually <b>put</b>, and the buffer was handled as if in line mode, but it was possible to get extremely anomalous +behavior. In addition, using the <b>Q</b> command to switch into <i>ex</i> mode, and then doing a <b>put</b> often resulted in +errors as well, such as appending text that was unrelated to the (supposed) contents of the buffer. For consistency and simplicity +of specification, POSIX.1-2024 does not permit these behaviors. All <i>ex</i> <b>put</b> commands are required to operate in line +mode, and the contents of the buffers are not altered by changing the mode of the editor.</p> +<h5><a name="tag_20_40_18_31" id="tag_20_40_18_31"></a>Read</h5> +<p class="tent">Historically, an <i>ex</i> <b>read</b> command executed from open or visual mode, executed in an empty file, left +an empty line as the first line of the file. For consistency and simplicity of specification, POSIX.1-2024 does not permit this +behavior. Historically, a <b>read</b> in open or visual mode from a program left the cursor at the last line read in, not the +first. For consistency, POSIX.1-2024 does not permit this behavior.</p> +<p class="tent">Historical implementations of <i>ex</i> were unable to undo <b>read</b> commands that read from the output of a +program. For consistency, POSIX.1-2024 does not permit this behavior.</p> +<p class="tent">Historically, the <i>ex</i> and <a href="../utilities/vi.html"><i>vi</i></a> message after a successful <b>read</b> +or <b>write</b> command specified "characters", not "bytes". POSIX.1-2024 requires that the number of bytes be displayed, not +the number of characters, because it may be difficult in multi-byte implementations to determine the number of characters read. +Implementations are encouraged to clarify the message displayed to the user.</p> +<p class="tent">Historically, reads were not permitted on files other than type regular, except that FIFO files could be read +(probably only because they did not exist when <i>ex</i> and <a href="../utilities/vi.html"><i>vi</i></a> were originally written). +Because the historical <i>ex</i> evaluated <b>read!</b> and <b>read !</b> equivalently, there can be no optional way to force +the read. POSIX.1-2024 permits, but does not require, this behavior.</p> +<h5><a name="tag_20_40_18_32" id="tag_20_40_18_32"></a>Recover</h5> +<p class="tent">Some historical implementations of the editor permitted users to recover the edit buffer contents from a previous +edit session, and then exit without saving those contents (or explicitly discarding them). The intent of POSIX.1-2024 in requiring +that the edit buffer be treated as already modified is to prevent this user error.</p> +<h5><a name="tag_20_40_18_33" id="tag_20_40_18_33"></a>Rewind</h5> +<p class="tent">Historical implementations supported the <b>rewind</b> command when the user was editing the first file in the +list; that is, the file that the <b>rewind</b> command would edit. POSIX.1-2024 requires conformance to historical practice.</p> +<h5><a name="tag_20_40_18_34" id="tag_20_40_18_34"></a>Substitute</h5> +<p class="tent">Historically, <i>ex</i> accepted an <b>r</b> option to the <b>s</b> command. The effect of the <b>r</b> option was +to use the last regular expression used in any command as the pattern, the same as the <b>~</b> command. The <b>r</b> option is not +required by POSIX.1-2024. Historically, the <b>c</b> and <b>g</b> options were toggled; for example, the command <b>:s/abc/def/</b> +was the same as <b>s/abc/def/ccccgggg</b>. For simplicity of specification, POSIX.1-2024 does not permit this behavior.</p> +<p class="tent">The tilde command is often used to replace the last search RE. For example, in the sequence:</p> +<pre> +<tt>s/red/blue/ +/green +~ +</tt></pre> +<p class="tent">the <b>~</b> command is equivalent to:</p> +<pre> +<tt>s/green/blue/ +</tt></pre> +<p class="tent">Historically, <i>ex</i> accepted all of the following forms:</p> +<pre> +<tt>s/abc/def/ +s/abc/def +s/abc/ +s/abc +</tt></pre> +<p class="tent">POSIX.1-2024 requires conformance to this historical practice.</p> +<p class="tent">The <b>s</b> command presumes that the <tt>'^'</tt> character only occupies a single column in the display. Much of +the <i>ex</i> and <a href="../utilities/vi.html"><i>vi</i></a> specification presumes that the <space> only occupies a single +column in the display. There are no known character sets for which this is not true.</p> +<p class="tent">Historically, the final column position for the substitute commands was based on previous column movements; a +search for a pattern followed by a substitution would leave the column position unchanged, while a 0 command followed by a +substitution would change the column position to the first non-<blank>. For consistency and simplicity of specification, +POSIX.1-2024 requires that the final column position always be set to the first non-<blank>.</p> +<h5><a name="tag_20_40_18_35" id="tag_20_40_18_35"></a>Set</h5> +<p class="tent">Historical implementations redisplayed all of the options for each occurrence of the <b>all</b> keyword. +POSIX.1-2024 permits, but does not require, this behavior.</p> +<h5><a name="tag_20_40_18_36" id="tag_20_40_18_36"></a>Tag</h5> +<p class="tent">No requirement is made as to where <i>ex</i> and <a href="../utilities/vi.html"><i>vi</i></a> shall look for the +file referenced by the tag entry. Historical practice has been to look for the path found in the <b>tags</b> file, based on the +current directory. A useful extension found in some implementations is to look based on the directory containing the tags file that +held the entry, as well. No requirement is made as to which reference for the tag in the tags file is used. This is deliberate, in +order to permit extensions such as multiple entries in a tags file for a tag.</p> +<p class="tent">Because users often specify many different tags files, some of which need not be relevant or exist at any +particular time, POSIX.1-2024 requires that error messages about problem tags files be displayed only if the requested tag is not +found, and then, only once for each time that the <b>tag</b> edit option is changed.</p> +<p class="tent">The requirement that the current edit buffer be unmodified is only necessary if the file indicated by the tag entry +is not the same as the current file (as defined by the current pathname). Historically, the file would be reloaded if the filename +had changed, as well as if the filename was different from the current pathname. For consistency and simplicity of specification, +POSIX.1-2024 does not permit this behavior, requiring that the name be the only factor in the decision.</p> +<p class="tent">Historically, <a href="../utilities/vi.html"><i>vi</i></a> only searched for tags in the current file from the +current cursor to the end of the file, and therefore, if the <b>wrapscan</b> option was not set, tags occurring before the current +cursor were not found. POSIX.1-2024 considers this a bug, and implementations are required to search for the first occurrence in +the file, regardless.</p> +<h5><a name="tag_20_40_18_37" id="tag_20_40_18_37"></a>Undo</h5> +<p class="tent">The <b>undo</b> description deliberately uses the word "modified". The <b>undo</b> command is not intended to +undo commands that replace the contents of the edit buffer, such as <b>edit</b>, <b>next</b>, <b>tag</b>, or <b>recover</b>.</p> +<p class="tent">Cursor positioning after the <b>undo</b> command was inconsistent in the historical <a href= +"../utilities/vi.html"><i>vi</i></a>, sometimes attempting to restore the original cursor position (<b>global</b>, <b>undo</b>, and +<b>v</b> commands), and sometimes, in the presence of maps, placing the cursor on the last line added or changed instead of the +first. POSIX.1-2024 requires a simplified behavior for consistency and simplicity of specification.</p> +<h5><a name="tag_20_40_18_38" id="tag_20_40_18_38"></a>Version</h5> +<p class="tent">The <b>version</b> command cannot be exactly specified since there is no widely-accepted definition of what the +version information should contain. Implementations are encouraged to do something reasonably intelligent.</p> +<h5><a name="tag_20_40_18_39" id="tag_20_40_18_39"></a>Write</h5> +<p class="tent">Historically, the <i>ex</i> and <a href="../utilities/vi.html"><i>vi</i></a> message after a successful <b>read</b> +or <b>write</b> command specified "characters", not "bytes". POSIX.1-2024 requires that the number of bytes be displayed, not +the number of characters because it may be difficult in multi-byte implementations to determine the number of characters written. +Implementations are encouraged to clarify the message displayed to the user.</p> +<p class="tent">Implementation-defined tests are permitted so that implementations can make additional checks; for example, for +locks or file modification times.</p> +<p class="tent">Historically, attempting to append to a nonexistent file caused an error. It has been left unspecified in +POSIX.1-2024 to permit implementations to let the <b>write</b> succeed, so that the append semantics are similar to those of the +historical <i>csh</i>.</p> +<p class="tent">Historical <a href="../utilities/vi.html"><i>vi</i></a> permitted empty edit buffers to be written. However, since +the way <a href="../utilities/vi.html"><i>vi</i></a> got around dealing with "empty" files was to always have a line in the edit +buffer, no matter what, it wrote them as files of a single, empty line. POSIX.1-2024 does not permit this behavior.</p> +<p class="tent">Historically, <i>ex</i> restored standard output and standard error to their values as of when <i>ex</i> was +invoked, before writes to programs were performed. This could disturb the terminal configuration as well as be a security issue for +some terminals. POSIX.1-2024 does not permit this, requiring that the program output be captured and displayed as if by the +<i>ex</i> <b>print</b> command.</p> +<h5><a name="tag_20_40_18_40" id="tag_20_40_18_40"></a>Adjust Window</h5> +<p class="tent">Historically, the line count was set to the value of the <b>scroll</b> option if the type character was +end-of-file. This feature was broken on most historical implementations long ago, however, and is not documented anywhere. For this +reason, POSIX.1-2024 is resolutely silent.</p> +<p class="tent">Historically, the <b>z</b> command was <blank>-sensitive and <b>z +</b> and <b>z -</b> did +different things than <b>z+</b> and <b>z-</b> because the type could not be distinguished from a flag. (The commands +<b>z .</b> and <b>z =</b> were historically invalid.) POSIX.1-2024 requires conformance to this historical practice.</p> +<p class="tent">Historically, the <b>z</b> command was further <blank>-sensitive in that the <i>count</i> could not be +<blank>-delimited; for example, the commands <b>z= 5</b> and <b>z- 5</b> were also invalid. Because the +<i>count</i> is not ambiguous with respect to either the type character or the flags, this is not permitted by POSIX.1-2024.</p> +<h5><a name="tag_20_40_18_41" id="tag_20_40_18_41"></a>Escape</h5> +<p class="tent">Historically, <i>ex</i> filter commands only read the standard output of the commands, letting standard error +appear on the terminal as usual. The <a href="../utilities/vi.html"><i>vi</i></a> utility, however, read both standard output and +standard error. POSIX.1-2024 requires the latter behavior for both <i>ex</i> and <a href="../utilities/vi.html"><i>vi</i></a>, for +consistency.</p> +<p class="tent">In Issue 8 the <a href="../functions/system.html#"><i>system</i></a> function was changed to require that the POSIX +shell be invoked with <tt>"sh"</tt>, <tt>"-c"</tt>, <tt>"--"</tt>, and <i>command</i> arguments to make it easier to execute +programs with <hyphen-minus> (<tt>'-'</tt>) or <plus-sign> (<tt>'+'</tt>) as the first character of the program's +filename. A similar request to have the <i>ex</i> <b>escape</b> command do the same was not accepted. Unlike <a href= +"../functions/system.html"><i>system</i>()</a> (which always invokes a POSIX shell), <i>ex</i> invokes the program named by the +<b>shell</b> edit option. For example, the <i>csh</i> and <i>tcsh</i> shells that are frequently used as login shells do not +recognize <tt>"--"</tt> after <tt>"-c"</tt> as an end-of-options indicator. The program need not even be one that recognizes any +POSIX shell command line syntax. Some users invoke shell scripts to process lines that are being supplied to the specified utility. +These utilities know that they will be given <tt>"-c"</tt> as a first argument and just ignore it. Any utilities used in this +manner would have to be modified to skip over another argument (the <tt>"--"</tt>) to find the desired argument.</p> +<h5><a name="tag_20_40_18_42" id="tag_20_40_18_42"></a>Shift Left and Shift Right</h5> +<p class="tent">Historically, it was possible to add shift characters to increase the effect of the command; for example, +<b><<<</b> outdented (or <b>>>></b> indented) the lines 3 levels of indentation instead of the default 1. +POSIX.1-2024 requires conformance to historical practice.</p> +<h5><a name="tag_20_40_18_43" id="tag_20_40_18_43"></a><control>-D</h5> +<p class="tent">Historically, the <control>-D command erased the prompt, providing the user with an unbroken presentation of +lines from the edit buffer. This is not required by POSIX.1-2024; implementations are encouraged to provide it if possible. +Historically, the <control>-D command took, and then ignored, a <i>count</i>. POSIX.1-2024 does not permit this behavior.</p> +<h5><a name="tag_20_40_18_44" id="tag_20_40_18_44"></a>Write Line Number</h5> +<p class="tent">Historically, the <i>ex</i> <b>=</b> command, when executed in <i>ex</i> mode in an empty edit buffer, reported 0, +and from open or visual mode, reported 1. For consistency and simplicity of specification, POSIX.1-2024 does not permit this +behavior.</p> +<h5><a name="tag_20_40_18_45" id="tag_20_40_18_45"></a>Execute</h5> +<p class="tent">Historically, <i>ex</i> did not correctly handle the inclusion of text input commands (that is, <b>append</b>, +<b>insert</b>, and <b>change</b>) in executed buffers. POSIX.1-2024 does not permit this exclusion for consistency.</p> +<p class="tent">Historically, the logical contents of the buffer being executed did not change if the buffer itself were modified +by the commands being executed; that is, buffer execution did not support self-modifying code. POSIX.1-2024 requires conformance to +historical practice.</p> +<p class="tent">Historically, the <b>@</b> command took a range of lines, and the <b>@</b> buffer was executed once per line, with +the current line (<tt>'.'</tt>) set to each specified line. POSIX.1-2024 requires conformance to historical practice.</p> +<p class="tent">Some historical implementations did not notice if errors occurred during buffer execution. This, coupled with the +ability to specify a range of lines for the <i>ex</i> <b>@</b> command, makes it trivial to cause them to drop <b>core</b>. +POSIX.1-2024 requires that implementations stop buffer execution if any error occurs, if the specified line doesn't exist, or if +the contents of the edit buffer itself are replaced (for example, the buffer executes the <i>ex</i> <b>:edit</b> command).</p> +<h5><a name="tag_20_40_18_46" id="tag_20_40_18_46"></a>Regular Expressions in ex</h5> +<p class="tent">Historical practice is that the characters in the replacement part of the last <b>s</b> command—that is, those +matched by entering a <tt>'~'</tt> in the regular expression—were not further expanded by the regular expression engine. So, if the +characters contained the string <tt>"a.,"</tt> they would match <tt>'a'</tt> followed by <tt>".,"</tt> and not <tt>'a'</tt> +followed by any character. POSIX.1-2024 requires conformance to historical practice.</p> +<h5><a name="tag_20_40_18_47" id="tag_20_40_18_47"></a>Edit Options in ex</h5> +<p class="tent">The following paragraphs describe the historical behavior of some edit options that were not, for whatever reason, +included in POSIX.1-2024. Implementations are strongly encouraged to only use these names if the functionality described here is +fully supported.</p> +<dl compact> +<dd></dd> +<dt><b>extended</b></dt> +<dd>The <b>extended</b> edit option has been used in some implementations of <a href="../utilities/vi.html"><i>vi</i></a> to +provide extended regular expressions instead of basic regular expressions This option was omitted from POSIX.1-2024 because it is +not widespread historical practice.</dd> +<dt><b>flash</b></dt> +<dd>The <b>flash</b> edit option historically caused the screen to flash instead of beeping on error. This option was omitted from +POSIX.1-2024 because it is not found in some historical implementations.</dd> +<dt><b>hardtabs</b></dt> +<dd>The <b>hardtabs</b> edit option historically defined the number of columns between hardware tab settings. This option was +omitted from POSIX.1-2024 because it was believed to no longer be generally useful.</dd> +<dt><b>modeline</b></dt> +<dd>The <b>modeline</b> (sometimes named <b>modelines</b>) edit option historically caused <i>ex</i> or <a href= +"../utilities/vi.html"><i>vi</i></a> to read the five first and last lines of the file for editor commands. This option is a +security problem, and vendors are strongly encouraged to delete it from historical implementations.</dd> +<dt><b>open</b></dt> +<dd>The <b>open</b> edit option historically disallowed the <i>ex</i> <b>open</b> and <b>visual</b> commands. This edit option was +omitted because these commands are required by POSIX.1-2024.</dd> +<dt><b>optimize</b></dt> +<dd>The <b>optimize</b> edit option historically expedited text throughput by setting the terminal to not do automatic +<carriage-return> characters when printing more than one logical line of output. This option was omitted from POSIX.1-2024 +because it was intended for terminals without addressable cursors, which are rarely, if ever, still used.</dd> +<dt><b>ruler</b></dt> +<dd>The <b>ruler</b> edit option has been used in some implementations of <a href="../utilities/vi.html"><i>vi</i></a> to present a +current row/column ruler for the user. This option was omitted from POSIX.1-2024 because it is not widespread historical +practice.</dd> +<dt><b>sourceany</b></dt> +<dd>The <b>sourceany</b> edit option historically caused <i>ex</i> or <a href="../utilities/vi.html"><i>vi</i></a> to source +start-up files that were owned by users other than the user running the editor. This option is a security problem, and vendors are +strongly encouraged to remove it from their implementations.</dd> +<dt><b>timeout</b></dt> +<dd>The <b>timeout</b> edit option historically enabled the (now standard) feature of only waiting for a short period before +returning keys that could be part of a macro. This feature was omitted from POSIX.1-2024 because its behavior is now standard, it +is not widely useful, and it was rarely documented.</dd> +<dt><b>verbose</b></dt> +<dd>The <b>verbose</b> edit option has been used in some implementations of <a href="../utilities/vi.html"><i>vi</i></a> to cause +<a href="../utilities/vi.html"><i>vi</i></a> to output error messages for common errors; for example, attempting to move the cursor +past the beginning or end of the line instead of only alerting the screen. (The historical <a href= +"../utilities/vi.html"><i>vi</i></a> only alerted the terminal and presented no message for such errors. The historical editor +option <b>terse</b> did not select when to present error messages, it only made existing error messages more or less verbose.) This +option was omitted from POSIX.1-2024 because it is not widespread historical practice; however, implementors are encouraged to use +it if they wish to provide error messages for naive users.</dd> +<dt><b>wraplen</b></dt> +<dd>The <b>wraplen</b> edit option has been used in some implementations of <a href="../utilities/vi.html"><i>vi</i></a> to specify +an automatic margin measured from the left margin instead of from the right margin. This is useful when multiple screen sizes are +being used to edit a single file. This option was omitted from POSIX.1-2024 because it is not widespread historical practice; +however, implementors are encouraged to use it if they add this functionality.</dd> +</dl> +<h5><a name="tag_20_40_18_48" id="tag_20_40_18_48"></a>autoindent, ai</h5> +<p class="tent">Historically, the command <b>0a</b> did not do any autoindentation, regardless of the current indentation of line +1. POSIX.1-2024 requires that any indentation present in line 1 be used.</p> +<h5><a name="tag_20_40_18_49" id="tag_20_40_18_49"></a>autoprint, ap</h5> +<p class="tent">Historically, the <b>autoprint</b> edit option was not completely consistent or based solely on modifications to +the edit buffer. Exceptions were the <b>read</b> command (when reading from a file, but not from a filter), the <b>append</b>, +<b>change</b>, <b>insert</b>, <b>global</b>, and <b>v</b> commands, all of which were not affected by <b>autoprint</b>, and the +<b>tag</b> command, which was affected by <b>autoprint</b>. POSIX.1-2024 requires conformance to historical practice.</p> +<p class="tent">Historically, the <b>autoprint</b> option only applied to the last of multiple commands entered using +<vertical-line> delimiters; for example, <b>delete</b> <newline> was affected by <b>autoprint</b>, but +<b>delete|version</b> <newline> was not. POSIX.1-2024 requires conformance to historical practice.</p> +<h5><a name="tag_20_40_18_50" id="tag_20_40_18_50"></a>autowrite, aw</h5> +<p class="tent">Appending the <tt>'!'</tt> character to the <i>ex</i> <b>next</b> command to avoid performing an automatic write +was not supported in historical implementations. POSIX.1-2024 requires that the behavior match the other <i>ex</i> commands for +consistency.</p> +<h5><a name="tag_20_40_18_51" id="tag_20_40_18_51"></a>ignorecase, ic</h5> +<p class="tent">Historical implementations of case-insensitive matching (the <b>ignorecase</b> edit option) lead to +counter-intuitive situations when uppercase characters were used in range expressions. Historically, the process was as +follows:</p> +<ol> +<li class="tent">Take a line of text from the edit buffer.</li> +<li class="tent">Convert uppercase to lowercase in text line.</li> +<li class="tent">Convert uppercase to lowercase in regular expressions, except in character class specifications.</li> +<li class="tent">Match regular expressions against text.</li> +</ol> +<p class="tent">This would mean that, with <b>ignorecase</b> in effect, the text:</p> +<pre> +<tt>The cat sat on the mat +</tt></pre> +<p class="tent">would be matched by</p> +<pre> +<tt>/^the/ +</tt></pre> +<p class="tent">but not by:</p> +<pre> +<tt>/^[A-Z]he/ +</tt></pre> +<p class="tent">For consistency with other commands implementing regular expressions, POSIX.1-2024 does not permit this +behavior.</p> +<h5><a name="tag_20_40_18_52" id="tag_20_40_18_52"></a>paragraphs, para</h5> +<p class="tent">The ISO POSIX-2:1993 standard made the default <b>paragraphs</b> and <b>sections</b> edit options +implementation-defined, arguing they were historically oriented to the UNIX system <i>troff</i> text formatter, and a "portable +user" could use the <b>{</b>, <b>}</b>, <b>[[</b>, <b>]]</b>, <b>(</b>, and <b>)</b> commands in open or visual mode and have the +cursor stop in unexpected places. POSIX.1-2024 specifies their values in the POSIX locale because the unusual grouping (they only +work when grouped into two characters at a time) means that they cannot be used for general-purpose movement, regardless.</p> +<h5><a name="tag_20_40_18_53" id="tag_20_40_18_53"></a>readonly</h5> +<p class="tent">Implementations are encouraged to provide the best possible information to the user as to the read-only status of +the file, with the exception that they should not consider the current special privileges of the process. This provides users with +a safety net because they must force the overwrite of read-only files, even when running with additional privileges.</p> +<p class="tent">The <b>readonly</b> edit option specification largely conforms to historical practice. The only difference is that +historical implementations did not notice that the user had set the <b>readonly</b> edit option in cases where the file was already +marked read-only for some reason, and would therefore reinitialize the <b>readonly</b> edit option the next time the contents of +the edit buffer were replaced. This behavior is disallowed by POSIX.1-2024.</p> +<h5><a name="tag_20_40_18_54" id="tag_20_40_18_54"></a>report</h5> +<p class="tent">The requirement that lines copied to a buffer interact differently than deleted lines is historical practice. For +example, if the <b>report</b> edit option is set to 3, deleting 3 lines will cause a report to be written, but 4 lines must be +copied before a report is written.</p> +<p class="tent">The requirement that the <i>ex</i> <b>global</b>, <b>v</b>, <b>open</b>, <b>undo</b>, and <b>visual</b> commands +present reports based on the total number of lines added or deleted during the command execution, and that commands executed by the +<b>global</b> and <b>v</b> commands not present reports, is historical practice. POSIX.1-2024 extends historical practice by +requiring that buffer execution be treated similarly. The reasons for this are two-fold. Historically, only the report by the last +command executed from the buffer would be seen by the user, as each new report would overwrite the last. In addition, the standard +developers believed that buffer execution had more in common with <b>global</b> and <b>v</b> commands than it did with other +<i>ex</i> commands, and should behave similarly, for consistency and simplicity of specification.</p> +<h5><a name="tag_20_40_18_55" id="tag_20_40_18_55"></a>showmatch, sm</h5> +<p class="tent">The length of time the cursor spends on the matching character is unspecified because the timing capabilities of +systems are often inexact and variable. The time should be long enough for the user to notice, but not long enough for the user to +become annoyed. Some implementations of <a href="../utilities/vi.html"><i>vi</i></a> have added a <b>matchtime</b> option that +permits users to set the number of 0,1 second intervals the cursor pauses on the matching character.</p> +<h5><a name="tag_20_40_18_56" id="tag_20_40_18_56"></a>showmode</h5> +<p class="tent">The <b>showmode</b> option has been used in some historical implementations of <i>ex</i> and <a href= +"../utilities/vi.html"><i>vi</i></a> to display the current editing mode when in open or visual mode. The editing modes have +generally included "command" and "input", and sometimes other modes such as "replace" and "change". The string was usually +displayed on the bottom line of the screen at the far right-hand corner. In addition, a preceding <tt>'*'</tt> character often +denoted whether the contents of the edit buffer had been modified. The latter display has sometimes been part of the +<b>showmode</b> option, and sometimes based on another option. This option was not available in the 4 BSD historical implementation +of <a href="../utilities/vi.html"><i>vi</i></a>, but was viewed as generally useful, particularly to novice users, and is required +by POSIX.1-2024.</p> +<p class="tent">The <b>smd</b> shorthand for the <b>showmode</b> option was not present in all historical implementations of the +editor. POSIX.1-2024 requires it, for consistency.</p> +<p class="tent">Not all historical implementations of the editor displayed a mode string for command mode, differentiating command +mode from text input mode by the absence of a mode string. POSIX.1-2024 permits this behavior for consistency with historical +practice, but implementations are encouraged to provide a display string for both modes.</p> +<h5><a name="tag_20_40_18_57" id="tag_20_40_18_57"></a>slowopen</h5> +<p class="tent">Historically, the <b>slowopen</b> option was automatically set if the terminal baud rate was less than 1200 baud, +or if the baud rate was 1200 baud and the <b>redraw</b> option was not set. The <b>slowopen</b> option had two effects. First, when +inserting characters in the middle of a line, characters after the cursor would not be pushed ahead, but would appear to be +overwritten. Second, when creating a new line of text, lines after the current line would not be scrolled down, but would appear to +be overwritten. In both cases, ending text input mode would cause the screen to be refreshed to match the actual contents of the +edit buffer. Finally, terminals that were sufficiently intelligent caused the editor to ignore the <b>slowopen</b> option. +POSIX.1-2024 permits most historical behavior, extending historical practice to require <b>slowopen</b> behaviors if the edit +option is set by the user.</p> +<h5><a name="tag_20_40_18_58" id="tag_20_40_18_58"></a>tags</h5> +<p class="tent">The default path for tags files is left unspecified as implementations may have their own <b>tags</b> +implementations that do not correspond to the historical ones. The default <b>tags</b> option value should probably at least +include the file <b>./tags</b>.</p> +<h5><a name="tag_20_40_18_59" id="tag_20_40_18_59"></a>term</h5> +<p class="tent">Historical implementations of <i>ex</i> and <a href="../utilities/vi.html"><i>vi</i></a> ignored changes to the +<b>term</b> edit option after the initial terminal information was loaded. This is permitted by POSIX.1-2024; however, +implementations are encouraged to permit the user to modify their terminal type at any time.</p> +<h5><a name="tag_20_40_18_60" id="tag_20_40_18_60"></a>terse</h5> +<p class="tent">Historically, the <b>terse</b> edit option optionally provided a shorter, less descriptive error message, for some +error messages. This is permitted, but not required, by POSIX.1-2024. Historically, most common visual mode errors (for example, +trying to move the cursor past the end of a line) did not result in an error message, but simply alerted the terminal. +Implementations wishing to provide messages for novice users are urged to do so based on the <b>edit</b> option <b>verbose</b>, and +not <b>terse</b>.</p> +<h5><a name="tag_20_40_18_61" id="tag_20_40_18_61"></a>window</h5> +<p class="tent">In historical implementations, the default for the <b>window</b> edit option was based on the baud rate as +follows:</p> +<ol> +<li class="tent">If the baud rate was less than 1200, the <b>edit</b> option <b>w300</b> set the window value; for example, the +line: +<pre> +<tt>set w300=12 +</tt></pre> +<p class="tent">would set the window option to 12 if the baud rate was less than 1200.</p> +</li> +<li class="tent">If the baud rate was equal to 1200, the <b>edit</b> option <b>w1200</b> set the window value.</li> +<li class="tent">If the baud rate was greater than 1200, the <b>edit</b> option <b>w9600</b> set the window value.</li> +</ol> +<p class="tent">The <b>w300</b>, <b>w1200</b>, and <b>w9600</b> options do not appear in POSIX.1-2024 because of their dependence +on specific baud rates.</p> +<p class="tent">In historical implementations, the size of the window displayed by various commands was related to, but not +necessarily the same as, the <b>window</b> edit option. For example, the size of the window was set by the <i>ex</i> command +<b>visual 10</b>, but it did not change the value of the <b>window</b> edit option. However, changing the value of the +<b>window</b> edit option did change the number of lines that were displayed when the screen was repainted. POSIX.1-2024 does not +permit this behavior in the interests of consistency and simplicity of specification, and requires that all commands that change +the number of lines that are displayed do it by setting the value of the <b>window</b> edit option.</p> +<h5><a name="tag_20_40_18_62" id="tag_20_40_18_62"></a>wrapmargin, wm</h5> +<p class="tent">Historically, the <b>wrapmargin</b> option did not affect maps inserting characters that also had associated +<i>count</i>s; for example <b>:map K 5aABC DEF</b>. Unfortunately, there are widely used maps that depend on this +behavior. For consistency and simplicity of specification, POSIX.1-2024 does not permit this behavior.</p> +<p class="tent">Historically, <b>wrapmargin</b> was calculated using the column display width of all characters on the screen. For +example, an implementation using <tt>"^I"</tt> to represent <tab> characters when the <b>list</b> edit option was set, where +<tt>'^'</tt> and <tt>'I'</tt> each took up a single column on the screen, would calculate the <b>wrapmargin</b> based on a value of +2 for each <tab>. The <b>number</b> edit option similarly changed the effective length of the line as well. POSIX.1-2024 +requires conformance to historical practice.</p> +<p class="tent">Earlier versions of this standard allowed for implementations with bytes other than eight bits, but this has been +modified in this version.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_40_19" id="tag_20_40_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a +<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require +implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_40_20" id="tag_20_40_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19_09_01_04"><i>2.9.1.4 Command Search and Execution</i></a> , <a href= +"../utilities/ctags.html#"><i>ctags</i></a> , <a href="../utilities/ed.html#"><i>ed</i></a> , <a href= +"../utilities/sed.html#"><i>sed</i></a> , <a href="../utilities/sh.html#"><i>sh</i></a> , <a href= +"../utilities/stty.html#"><i>stty</i></a> , <a href="../utilities/vi.html#"><i>vi</i></a></p> +<p class="tent">XBD <a href="../basedefs/V1_chap05.html#tagtcjh_2"><i>Escape Sequences and Associated Actions</i></a> , <a href= +"../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href="../basedefs/V1_chap09.html#tag_09_03"><i>9.3 +Basic Regular Expressions</i></a> , <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p class="tent">XSH <a href="../functions/access.html#"><i>access</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_40_21" id="tag_20_40_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_40_22" id="tag_20_40_22"></a>Issue 5</h4> +<blockquote> +<p>The FUTURE DIRECTIONS section is added.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_40_23" id="tag_20_40_23"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +<p class="tent">The obsolescent SYNOPSIS is removed, removing the <b>+</b><i>command</i> and <b>-</b> options.<br></p> +<p class="tent">The following new requirements on POSIX implementations derive from alignment with the Single UNIX +Specification:</p> +<ul> +<li class="tent">In the <b>map</b> command description, the sequence <b>#</b><i>digit</i> is added.</li> +<li class="tent">The <b>directory</b>, <b>edcompatible</b>, <b>redraw</b>, and <b>slowopen</b> edit options are added.</li> +</ul> +<p class="tent">The <i>ex</i> utility is extensively changed for alignment with the IEEE P1003.2b draft standard. This +includes changes as a result of the IEEE PASC Interpretations 1003.2 #31, #38, #49, #50, #51, #52, #55, #56, #57, #61, #62, #63, +#64, #65, and #78.</p> +<p class="tent">The <b>-l</b> option is removed.</p> +<p class="tent">IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/23 is applied, correcting a URL.</p> +<p class="tent">IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/8 is applied, making an editorial correction in the +EXTENDED DESCRIPTION.</p> +<p class="tent">IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/9 is applied, removing text describing behavior on +systems with bytes consisting of more than eight bits.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_40_24" id="tag_20_40_24"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #027 is applied, clarifying the behavior if an operand is <tt>'-'</tt>.</p> +<p class="tent">Austin Group Interpretation 1003.1-2001 #036 is applied, clarifying the behavior for BREs.</p> +<p class="tent">Austin Group Interpretation 1003.1-2001 #121 is applied, clarifying the <i>ex</i> <b>write</b> command.</p> +<p class="tent">Austin Group Interpretation 1003.1-2001 #156 is applied.</p> +<p class="tent">SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p class="tent">POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0093 [584] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_40_25" id="tag_20_40_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to disallow the creation of filenames containing any bytes that +have the encoded value of a <newline> character.</p> +<p class="tent">Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p class="tent">Austin Group Defect 1185 is applied, changing the SIGCONT entry in ASYNCHRONOUS EVENTS and adding a SIGWINCH +entry.</p> +<p class="tent">Austin Group Defect 1251 is applied, clarifying the <b>set</b> command, changing "addr" to "2addr" in the +<b>!</b> command synopsis, and adding spaces in some synopsis lines.</p> +<p class="tent">Austin Group Defect 1281 is applied, changing the description of the <b>substitute</b> command to clarify that it +is an error if the substitution fails on every addressed line.</p> +<p class="tent">Austin Group Defect 1298 is applied, changing the CONSEQUENCES OF ERRORS section.</p> +<p class="tent">Austin Group Defect 1378 is applied, changing the description of the <i>LC_MESSAGES</i> environment variable.</p> +<p class="tent">Austin Group Defect 1529 is applied, changing the synopsis of the <b>escape</b> command and adding related +paragraphs to the APPLICATION USAGE and RATIONALE sections.</p> +<p class="tent">Austin Group Defect 1642 is applied, changing the description of the <b>redraw</b> edit option.</p> +<p class="tent">Austin Group Defect 1662 is applied, clarifying requirements relating to delimiters in addresses and in <b>s</b> +commands.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/env.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/expand.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/expand.html b/bdd/expand.html @@ -0,0 +1,221 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>expand</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/ex.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/expr.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="expand" id="expand"></a> <a name="tag_20_41" id="tag_20_41"></a><!-- expand --> +<h4 class="mansect"><a name="tag_20_41_01" id="tag_20_41_01"></a>NAME</h4> +<blockquote>expand — convert tabs to spaces</blockquote> +<h4 class="mansect"><a name="tag_20_41_02" id="tag_20_41_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>expand</tt> <b>[</b><tt>-t</tt> <i>tablist</i><b>] [</b><i>file</i><tt>...</tt><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_41_03" id="tag_20_41_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>expand</i> utility shall write files or the standard input to the standard output with <tab> characters replaced +with one or more <space> characters needed to pad to the next tab stop. Any <backspace> characters shall be copied to +the output and cause the column position count for tab stop calculations to be decremented; the column position count shall not be +decremented below zero.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_41_04" id="tag_20_41_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>expand</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following option shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-t </b><i>tablist</i></dt> +<dd>Specify the tab stops. The application shall ensure that the argument <i>tablist</i> consists of either a single positive +decimal integer or a list of tabstops. If a single number is given, tabs shall be set that number of column positions apart instead +of the default 8. +<p>If a list of tabstops is given, the application shall ensure that it consists of a list of two or more positive decimal +integers, separated by <blank> or <comma> characters, in ascending order. The <tab> characters shall be set at +those specific column positions. Each tab stop <i>N</i> shall be an integer value greater than zero, and the list is in strictly +ascending order. This is taken to mean that, from the start of a line of output, tabbing to position <i>N</i> shall cause the next +character output to be in the (<i>N</i>+1)th column position on that line.</p> +<p>In the event of <i>expand</i> having to process a <tab> at a position beyond the last of those specified in a multiple +tab-stop list, the <tab> shall be replaced by a single <space> in the output.</p> +</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_41_05" id="tag_20_41_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>The pathname of a text file to be used as input.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_41_06" id="tag_20_41_06"></a>STDIN</h4> +<blockquote> +<p>See the INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_41_07" id="tag_20_41_07"></a>INPUT FILES</h4> +<blockquote> +<p>Input files shall be text files.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_41_08" id="tag_20_41_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>expand</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files), the processing of <tab> and <space> characters, and for +the determination of the width in column positions each character would occupy on an output device.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_41_09" id="tag_20_41_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_41_10" id="tag_20_41_10"></a>STDOUT</h4> +<blockquote> +<p>The standard output shall be equivalent to the input files with <tab> characters converted into the appropriate number of +<space> characters.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_41_11" id="tag_20_41_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_41_12" id="tag_20_41_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_41_13" id="tag_20_41_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_41_14" id="tag_20_41_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_41_15" id="tag_20_41_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>The <i>expand</i> utility shall terminate with an error message and non-zero exit status upon encountering difficulties +accessing one of the <i>file</i> operands.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_41_16" id="tag_20_41_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_41_17" id="tag_20_41_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_41_18" id="tag_20_41_18"></a>RATIONALE</h4> +<blockquote> +<p>The <i>expand</i> utility is useful for preprocessing text files (before sorting, looking at specific columns, and so on) that +contain <tab> characters.</p> +<p>See XBD <a href="../basedefs/V1_chap03.html#tag_03_75"><i>3.75 Column Position</i></a> .</p> +<p>The <i>tablist</i> option-argument consists of integers in ascending order. Utility Syntax Guideline 8 mandates that +<i>expand</i> shall accept the integers (within the single argument) separated using either <comma> or <blank> +characters.</p> +<p>Earlier versions of this standard allowed the following form in the SYNOPSIS:</p> +<pre> +<tt>expand </tt><b>[</b><tt>-tabstop</tt><b>][</b><tt>-tab1,tab2,...,tabn</tt><b>][</b><i>file</i><tt> ...</tt><b>]</b><tt> +</tt></pre> +<p>This form is no longer specified by POSIX.1-2024 but may be present in some implementations.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_41_19" id="tag_20_41_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_41_20" id="tag_20_41_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/tabs.html#"><i>tabs</i></a> , <a href="../utilities/unexpand.html#"><i>unexpand</i></a></p> +<p>XBD <a href="../basedefs/V1_chap03.html#tag_03_75"><i>3.75 Column Position</i></a> , <a href= +"../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 +Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_41_21" id="tag_20_41_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_41_22" id="tag_20_41_22"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +<p>The APPLICATION USAGE section is added.</p> +<p>The obsolescent SYNOPSIS is removed.</p> +<p>The <i>LC_CTYPE</i> environment variable description is updated to align with the IEEE P1003.2b draft standard.</p> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_41_23" id="tag_20_41_23"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #027 is applied.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>The <i>expand</i> utility is moved from the User Portability Utilities option to the Base. User Portability Utilities is now an +option for interactive utilities.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_41_24" id="tag_20_41_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/ex.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/expr.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/expr.html b/bdd/expr.html @@ -0,0 +1,453 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>expr</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/expand.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/false.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="expr" id="expr"></a> <a name="tag_20_42" id="tag_20_42"></a><!-- expr --> +<h4 class="mansect"><a name="tag_20_42_01" id="tag_20_42_01"></a>NAME</h4> +<blockquote>expr — evaluate arguments as an expression</blockquote> +<h4 class="mansect"><a name="tag_20_42_02" id="tag_20_42_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>expr</tt> <i>operand</i><tt>...</tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_42_03" id="tag_20_42_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>expr</i> utility shall evaluate an expression and write the result to standard output.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_42_04" id="tag_20_42_04"></a>OPTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_42_05" id="tag_20_42_05"></a>OPERANDS</h4> +<blockquote> +<p>The single expression evaluated by <i>expr</i> shall be formed from the <i>operand</i> operands, as described in the EXTENDED +DESCRIPTION section. The application shall ensure that each of the expression operator symbols:</p> +<pre> +<tt>( ) | & = > >= < <= != + - * / % : +</tt></pre> +<p>and the symbols <i>integer</i> and <i>string</i> in the table are provided as separate arguments to <i>expr</i>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_42_06" id="tag_20_42_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_42_07" id="tag_20_42_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_42_08" id="tag_20_42_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>expr</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_COLLATE</i></dt> +<dd><br> +Determine the locale for the behavior of ranges, equivalence classes, and multi-character collating elements within regular +expressions and by the string comparison operators.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments) and the behavior of character classes within regular expressions.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_42_09" id="tag_20_42_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_42_10" id="tag_20_42_10"></a>STDOUT</h4> +<blockquote> +<p>The <i>expr</i> utility shall evaluate the expression and write the result, followed by a <newline>, to standard +output.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_42_11" id="tag_20_42_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_42_12" id="tag_20_42_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_42_13" id="tag_20_42_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>The formation of the expression to be evaluated is shown in the following table. The symbols <i>expr</i>, <i>expr1</i>, and +<i>expr2</i> represent expressions formed from <i>integer</i> and <i>string</i> symbols and the expression operator symbols (all +separate arguments) by recursive application of the constructs described in the table. The expressions are listed in order of +decreasing precedence, with equal-precedence operators grouped between horizontal lines. All of the operators shall be +left-associative.</p> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Expression</b></p> +</th> +<th align="center"> +<p class="tent"><b>Description</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>integer</i></p> +</td> +<td align="left"> +<p class="tent">An argument consisting only of an (optional) unary minus followed by digits.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>string</i></p> +</td> +<td align="left"> +<p class="tent">A string argument; see below.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">( <i>expr</i> )</p> +</td> +<td align="left"> +<p class="tent">Grouping symbols. Any expression can be placed within parentheses. Parentheses can be nested to a depth of +{EXPR_NEST_MAX}.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>expr1</i> : <i>expr2</i></p> +</td> +<td align="left"> +<p class="tent">Matching expression; see below.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><br> +<i>expr1</i> * <i>expr2</i><br> +<br> +<i>expr1</i> / <i>expr2</i><br> +<br> +<i>expr1</i> % <i>expr2</i><br></p> +</td> +<td align="left"> +<p class="tent"><br> +Multiplication of decimal integer-valued arguments.<br> +<br> +Integer division of decimal integer-valued arguments, producing an integer result.<br> +<br> +Remainder of integer division of decimal integer-valued arguments.<br></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><br> +<i>expr1</i> + <i>expr2</i><br> +<br> +<i>expr1</i> - <i>expr2</i><br></p> +</td> +<td align="left"> +<p class="tent"><br> +Addition of decimal integer-valued arguments.<br> +<br> +Subtraction of decimal integer-valued arguments.<br></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><br> +<br> +<br> +<br> +<br> +<i>expr1</i> = <i>expr2</i><br> +<i>expr1</i> > <i>expr2</i><br> +<i>expr1</i> >= <i>expr2</i><br> +<i>expr1</i> < <i>expr2</i><br> +<i>expr1</i> <= <i>expr2</i><br> +<i>expr1</i> != <i>expr2</i><br></p> +</td> +<td align="left"> +<p class="tent"><br> +Returns the result of a decimal integer comparison if both arguments are integers; otherwise, returns the result of a string +comparison using the locale-specific collation sequence. The result of each<br> +comparison is 1 if the specified relationship is true, or 0 if the relationship is false.<br> +<br> +Equal.<br> +Greater than.<br> +Greater than or equal.<br> +Less than.<br> +Less than or equal.<br> +Not equal.<br></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>expr1</i> & <i>expr2</i></p> +</td> +<td align="left"> +<p class="tent">Returns the evaluation of <i>expr1</i> if neither expression evaluates to null or zero; otherwise, returns +zero.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>expr1</i> | <i>expr2</i></p> +</td> +<td align="left"> +<p class="tent">Returns the evaluation of <i>expr1</i> if it is neither null nor zero; otherwise, returns the evaluation of +<i>expr2</i> if it is not null; otherwise, zero.</p> +</td> +</tr> +</table> +</center> +<h5><a name="tag_20_42_13_01" id="tag_20_42_13_01"></a>Matching Expression</h5> +<p class="tent">The <tt>':'</tt> matching operator shall compare the string resulting from the evaluation of <i>expr1</i> with the +regular expression pattern resulting from the evaluation of <i>expr2</i>. Regular expression syntax shall be that defined in XBD +<a href="../basedefs/V1_chap09.html#tag_09_03"><i>9.3 Basic Regular Expressions</i></a> , except that all patterns are anchored to +the beginning of the string (that is, only sequences starting at the first character of a string are matched by the regular +expression) and, therefore, it is unspecified whether <tt>'^'</tt> is a special character in that context. Usually, the matching +operator shall return a string representing the number of characters matched (<tt>'0'</tt> on failure). Alternatively, if the +pattern contains at least one regular expression subexpression <tt>"\(...\)"</tt>, the string matched by the back-reference +expression <tt>"\1"</tt> shall be returned. If the back-reference expression <tt>"\1"</tt> does not match, then the null string +shall be returned.</p> +<h5><a name="tag_20_42_13_02" id="tag_20_42_13_02"></a>Identification as Integer or String</h5> +<p class="tent">An argument or the value of a subexpression that consists only of an optional unary minus followed by digits is a +candidate for treatment as an integer if it is used as the left argument to the <tt>|</tt> operator or as either argument to any of +the following operators: <tt>& = > >= < <= != + - * / %</tt>. Otherwise, the argument or subexpression value shall be +treated as a string.</p> +<p class="tent">The use of string arguments <b>length</b>, <b>substr</b>, <b>index</b>, or <b>match</b> produces unspecified +results.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_42_14" id="tag_20_42_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>The <i>expression</i> evaluated to neither null nor zero, and the output specified in STDOUT was successfully written to +standard output.</dd> +<dt> 1</dt> +<dd>The <i>expression</i> evaluated to null or zero, and the output specified in STDOUT was successfully written to standard +output.</dd> +<dt> 2</dt> +<dd>Invalid <i>expression</i> error.</dd> +<dt>>2</dt> +<dd>Another error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_42_15" id="tag_20_42_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_42_16" id="tag_20_42_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The <i>expr</i> utility has a rather difficult syntax:</p> +<ul> +<li class="tent">Many of the operators are also shell control operators or reserved words, so they have to be escaped on the +command line.</li> +<li class="tent">Each part of the expression is composed of separate arguments, so liberal usage of <blank> characters is +required. For example: +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Invalid</b></p> +</th> +<th align="center"> +<p class="tent"><b>Valid</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>expr</i> <tt>1+2</tt></p> +</td> +<td align="left"> +<p class="tent"><i>expr</i> <tt>1 + 2</tt></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>expr</i> <tt>"1 + 2"</tt></p> +</td> +<td align="left"> +<p class="tent"><i>expr</i> <tt>1 + 2</tt></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>expr</i> <tt>1 + (2 * 3)</tt></p> +</td> +<td align="left"> +<p class="tent"><i>expr</i> <tt>1 + \( 2 \* 3 \)</tt></p> +</td> +</tr> +</table> +</center> +</li> +</ul> +<p class="tent">In many cases, the arithmetic and string features provided as part of the shell command language are easier to use +than their equivalents in <i>expr</i>. Newly written scripts should avoid <i>expr</i> in favor of the new features within the +shell; see <a href="../utilities/V3_chap02.html#tag_19_05"><i>2.5 Parameters and Variables</i></a> and <a href= +"../utilities/V3_chap02.html#tag_19_06_04"><i>2.6.4 Arithmetic Expansion</i></a> .</p> +<p class="tent">After argument processing by the shell, <i>expr</i> is not required to be able to tell the difference between an +operator and an operand except by the value. If <tt>"$a"</tt> is <tt>'='</tt>, the command:</p> +<pre> +<tt>expr "$a" = '=' +</tt></pre> +<p class="tent">looks like:</p> +<pre> +<tt>expr = = = +</tt></pre> +<p class="tent">as the arguments are passed to <i>expr</i> (and they all may be taken as the <tt>'='</tt> operator). The following +works reliably:</p> +<pre> +<tt>expr "X$a" = X= +</tt></pre> +<p class="tent">Also note that this volume of POSIX.1-2024 permits implementations to extend utilities. The <i>expr</i> utility +permits the integer arguments to be preceded with a unary minus. This means that an integer argument could look like an option. +Therefore, the conforming application must employ the <tt>"--"</tt> construct of Guideline 10 of XBD <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a> to protect its operands if there is any chance the +first operand might be a negative integer (or any string with a leading minus).</p> +<p class="tent">For testing string equality the <a href="../utilities/test.html"><i>test</i></a> utility is preferred over +<i>expr</i>, as it is usually implemented as a shell built-in. However, the functionality is not quite the same because the +<i>expr</i> <tt>=</tt> and <tt>!=</tt> operators check whether strings collate equally, whereas <a href= +"../utilities/test.html"><i>test</i></a> checks whether they are identical. Therefore, they can produce different results in +locales where the collation sequence does not have a total ordering of all characters (see XBD <a href= +"../basedefs/V1_chap07.html#tag_07_03_02"><i>7.3.2 LC_COLLATE</i></a> ).<br></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_42_17" id="tag_20_42_17"></a>EXAMPLES</h4> +<blockquote> +<p>The following command:</p> +<pre> +<tt>a=$(expr "$a" + 1) +</tt></pre> +<p class="tent">adds 1 to the variable <i>a</i>.</p> +<p class="tent">The following command, for <tt>"$a"</tt> equal to either <b>/usr/abc/file</b> or just <b>file</b>:</p> +<pre> +<tt>expr $a : '.*/\(.*\)' \| $a +</tt></pre> +<p class="tent">returns the last segment of a pathname (that is, <b>file</b>). Applications should avoid the character <tt>'/'</tt> +used alone as an argument; <i>expr</i> may interpret it as the division operator.</p> +<p class="tent">The following command:</p> +<pre> +<tt>expr "//$a" : '.*/\(.*\)' +</tt></pre> +<p class="tent">is a better representation of the previous example. The addition of the <tt>"//"</tt> characters eliminates any +ambiguity about the division operator and simplifies the whole expression. Also note that pathnames may contain characters +contained in the <i>IFS</i> variable and should be quoted to avoid having <tt>"$a"</tt> expand into multiple arguments.</p> +<p class="tent">The following command:</p> +<pre> +<tt>expr "X$VAR" : '.*' - 1 +</tt></pre> +<p class="tent">returns the number of characters in <i>VAR</i>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_42_18" id="tag_20_42_18"></a>RATIONALE</h4> +<blockquote> +<p>In an early proposal, EREs were used in the matching expression syntax. This was changed to BREs to avoid breaking historical +applications.</p> +<p class="tent">The use of a leading <circumflex> in the BRE is unspecified because many historical implementations have +treated it as a special character, despite their system documentation. For example:</p> +<pre> +<tt>expr foo : ^foo expr ^foo : ^foo +</tt></pre> +<p class="tent">return 3 and 0, respectively, on those systems; their documentation would imply the reverse. Thus, the anchoring +condition is left unspecified to avoid breaking historical scripts relying on this undocumented feature.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_42_19" id="tag_20_42_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_42_20" id="tag_20_42_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19_05"><i>2.5 Parameters and Variables</i></a> , <a href= +"../utilities/V3_chap02.html#tag_19_06_04"><i>2.6.4 Arithmetic Expansion</i></a></p> +<p class="tent">XBD <a href="../basedefs/V1_chap07.html#tag_07_03_02"><i>7.3.2 LC_COLLATE</i></a> , <a href= +"../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href="../basedefs/V1_chap09.html#tag_09_03"><i>9.3 +Basic Regular Expressions</i></a> , <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_42_21" id="tag_20_42_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_42_22" id="tag_20_42_22"></a>Issue 5</h4> +<blockquote> +<p>The FUTURE DIRECTIONS section is added.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_42_23" id="tag_20_42_23"></a>Issue 6</h4> +<blockquote> +<p>The <i>expr</i> utility is aligned with the IEEE P1003.2b draft standard, to include resolution of IEEE PASC Interpretation +1003.2 #104.</p> +<p class="tent">The normative text is reworded to avoid use of the term "must" for application requirements.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_42_24" id="tag_20_42_24"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #036 is applied, clarifying the behavior for BREs.</p> +<p class="tent">The SYNOPSIS and OPERANDS sections are revised to explicitly state that the name of each of the operands is +<i>operand</i>.</p> +<p class="tent">POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0094 [942], XCU/TC2-2008/0095 [709], XCU/TC2-2008/0096 [942], +XCU/TC2-2008/0097 [963], and XCU/TC2-2008/0098 [942] are applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_42_25" id="tag_20_42_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p class="tent">Austin Group Defect 1500 is applied, changing the EXIT STATUS section.</p> +<p class="tent">Austin Group Defect 1757 is applied, changing <tt>"[\(...\)]"</tt> to <tt>"\(...\)"</tt>.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/expand.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/false.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/false.html b/bdd/false.html @@ -0,0 +1,143 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>false</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/expr.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/fc.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="false" id="false"></a> <a name="tag_20_43" id="tag_20_43"></a><!-- false --> +<h4 class="mansect"><a name="tag_20_43_01" id="tag_20_43_01"></a>NAME</h4> +<blockquote>false — return false value</blockquote> +<h4 class="mansect"><a name="tag_20_43_02" id="tag_20_43_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>false</tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_43_03" id="tag_20_43_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>false</i> utility shall return with a non-zero exit code.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_43_04" id="tag_20_43_04"></a>OPTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_43_05" id="tag_20_43_05"></a>OPERANDS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_43_06" id="tag_20_43_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_43_07" id="tag_20_43_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_43_08" id="tag_20_43_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_43_09" id="tag_20_43_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_43_10" id="tag_20_43_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_43_11" id="tag_20_43_11"></a>STDERR</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_43_12" id="tag_20_43_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_43_13" id="tag_20_43_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_43_14" id="tag_20_43_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The <i>false</i> utility shall always exit with a value between 1 and 125, inclusive.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_43_15" id="tag_20_43_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_43_16" id="tag_20_43_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_43_17" id="tag_20_43_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_43_18" id="tag_20_43_18"></a>RATIONALE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_43_19" id="tag_20_43_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_43_20" id="tag_20_43_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/true.html#"><i>true</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_43_21" id="tag_20_43_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_43_22" id="tag_20_43_22"></a>Issue 6</h4> +<blockquote> +<p>IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/24 is applied, changing the STDERR section from "None." to +"Not used." for alignment with <a href="../utilities/V3_chap01.html#tag_18_04"><i>1.4 Utility Description Defaults</i></a> .</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_43_23" id="tag_20_43_23"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1321 is applied, changing the EXIT STATUS section.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/expr.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/fc.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/fc.html b/bdd/fc.html @@ -0,0 +1,378 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>fc</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/false.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/fg.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="fc" id="fc"></a> <a name="tag_20_44" id="tag_20_44"></a><!-- fc --> +<h4 class="mansect"><a name="tag_20_44_01" id="tag_20_44_01"></a>NAME</h4> +<blockquote>fc — process the command history list</blockquote> +<h4 class="mansect"><a name="tag_20_44_02" id="tag_20_44_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> fc</tt> <b>[</b><tt>-r</tt><b>] [</b><tt>-e</tt> <i>editor</i><b>] [</b><i>first</i> +<b>[</b><i>last</i><b>]]</b> <tt><br> +<br> +fc -l</tt> <b>[</b><tt>-nr</tt><b>] [</b><i>first</i> <b>[</b><i>last</i><b>]]</b> <tt><br> +<br> +fc -s</tt> <b>[</b><i>old</i><tt>=</tt><i>new</i><b>] [</b><i>first</i><b>]</b> <tt><img src="../images/opt-end.gif" alt= +"[Option End]" border="0"></tt></code></div> +<tt><br></tt></blockquote> +<h4 class="mansect"><a name="tag_20_44_03" id="tag_20_44_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>fc</i> utility shall list, or shall edit and re-execute, commands previously entered to an interactive <a href= +"../utilities/sh.html"><i>sh</i></a>.</p> +<p>The command history list shall reference commands by number. The first number in the list is selected arbitrarily. The +relationship of a number to its command shall not change except when the user logs in and no other process is accessing the list, +at which time the system may reset the numbering to start the oldest retained command at another number (usually 1). When the +number reaches an implementation-defined upper limit, which shall be no smaller than the value in <i>HISTSIZE</i> or 32767 +(whichever is greater), the shell may wrap the numbers, starting the next command with a lower number (usually 1). However, despite +this optional wrapping of numbers, <i>fc</i> shall maintain the time-ordering sequence of the commands. For example, if four +commands in sequence are given the numbers 32766, 32767, 1 (wrapped), and 2 as they are executed, command 32767 is considered the +command previous to 1, even though its number is higher.</p> +<p>When commands are edited (when the <b>-l</b> option is not specified), the resulting lines shall be entered at the end of the +history list and then re-executed by <a href="../utilities/sh.html"><i>sh</i></a>. The <i>fc</i> command that caused the editing +shall not be entered into the history list. If the editor returns a non-zero exit status, this shall suppress the entry into the +history list and the command re-execution. Any command line variable assignments or redirection operators used with <i>fc</i> shall +affect both the <i>fc</i> command itself as well as the command that results; for example:</p> +<pre> +<tt>fc -s -- -1 2>/dev/null +</tt></pre> +<p>reinvokes the previous command, suppressing standard error for both <i>fc</i> and the previous command.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_44_04" id="tag_20_44_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>fc</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-e </b><i>editor</i></dt> +<dd>Use the editor named by <i>editor</i> to edit the commands. The <i>editor</i> string is a utility name, subject to search via +the <i>PATH</i> variable (see XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> ). The value in +the <i>FCEDIT</i> variable shall be used as a default when <b>-e</b> is not specified. If <i>FCEDIT</i> is null or unset, <a href= +"../utilities/ed.html"><i>ed</i></a> shall be used as the editor.</dd> +<dt><b>-l</b></dt> +<dd>(The letter ell.) List the commands rather than invoking an editor on them. The commands shall be written in the sequence +indicated by the <i>first</i> and <i>last</i> operands, as affected by <b>-r</b>, with each command preceded by the command +number.</dd> +<dt><b>-n</b></dt> +<dd>Suppress command numbers when listing with <b>-l</b>.</dd> +<dt><b>-r</b></dt> +<dd>Reverse the order of the commands listed (with <b>-l</b>) or edited (with neither <b>-l</b> nor <b>-s</b>).</dd> +<dt><b>-s</b></dt> +<dd>Re-execute the command without invoking an editor.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_44_05" id="tag_20_44_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>first</i>, <i>last</i></dt> +<dd>Select the commands to list or edit. The number of previous commands that can be accessed shall be determined by the value of +the <i>HISTSIZE</i> variable. The value of <i>first</i> or <i>last</i> or both shall be one of the following: +<dl compact> +<dd></dd> +<dt><b>[+]</b><i>number</i></dt> +<dd>A positive number representing a command number; command numbers can be displayed with the <b>-l</b> option.</dd> +<dt><b>-</b><i>number</i></dt> +<dd>A negative decimal number representing the command that was executed <i>number</i> of commands previously. For example, -1 is +the immediately previous command.</dd> +<dt><i>string</i></dt> +<dd>A string indicating the most recently entered command that begins with that string. If the <i>old</i>=<i>new</i> operand is not +also specified with <b>-s</b>, the string form of the <i>first</i> operand cannot contain an embedded <equals-sign>.</dd> +</dl> +<p>When the synopsis form with <b>-s</b> is used:</p> +<ul> +<li> +<p>If <i>first</i> is omitted, the previous command shall be used.</p> +</li> +</ul> +<p>For the synopsis forms without <b>-s</b>:</p> +<ul> +<li> +<p>If <i>last</i> is omitted, <i>last</i> shall default to the previous command when <b>-l</b> is specified; otherwise, it shall +default to <i>first</i>.</p> +</li> +<li> +<p>If <i>first</i> and <i>last</i> are both omitted, the previous 16 commands shall be listed or the previous single command shall +be edited (based on the <b>-l</b> option).</p> +</li> +<li> +<p>If <i>first</i> and <i>last</i> are both present, all of the commands from <i>first</i> to <i>last</i> shall be edited (without +<b>-l</b>) or listed (with <b>-l</b>). Editing multiple commands shall be accomplished by presenting to the editor all of the +commands at one time, each command starting on a new line. If <i>first</i> represents a newer command than <i>last</i>, the +commands shall be listed or edited in reverse sequence, equivalent to using <b>-r</b>. For example, the following commands on the +first line are equivalent to the corresponding commands on the second:</p> +<pre> +<tt>fc -r 10 20 fc 30 40 +fc 20 10 fc -r 40 30 +</tt></pre></li> +<li> +<p>When a range of commands is used, it shall not be an error to specify <i>first</i> or <i>last</i> values that are not in the +history list; <i>fc</i> shall substitute the value representing the oldest or newest command in the list, as appropriate. For +example, if there are only ten commands in the history list, numbered 1 to 10:</p> +<pre> +<tt>fc -l +fc 1 99 +</tt></pre> +<p>shall list and edit, respectively, all ten commands.</p> +</li> +</ul> +</dd> +<dt><i>old</i>=<i>new</i></dt> +<dd>Replace the first occurrence of string <i>old</i> in the commands to be re-executed by the string <i>new</i>.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_44_06" id="tag_20_44_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_44_07" id="tag_20_44_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_44_08" id="tag_20_44_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>fc</i>:</p> +<dl compact> +<dd></dd> +<dt><i>FCEDIT</i></dt> +<dd>This variable, when expanded by the shell, shall determine the default value for the <b>-e</b> <i>editor</i> option's +<i>editor</i> option-argument. If <i>FCEDIT</i> is null or unset, <a href="../utilities/ed.html"><i>ed</i></a> shall be used as the +editor.</dd> +<dt><i>HISTFILE</i></dt> +<dd>Determine a pathname naming a command history file. If the <i>HISTFILE</i> variable is not set, the shell may attempt to access +or create a file <b>.sh_history</b> in the directory referred to by the <i>HOME</i> environment variable. If the shell cannot +obtain both read and write access to, or create, the history file, it shall use an unspecified mechanism that allows the history to +operate properly. (References to history "file" in this section shall be understood to mean this unspecified mechanism in such +cases.) An implementation may choose to access this variable only when initializing the history file; this initialization shall +occur when <i>fc</i> or <a href="../utilities/sh.html"><i>sh</i></a> first attempt to retrieve entries from, or add entries to, the +file, as the result of commands issued by the user, the file named by the <i>ENV</i> variable, or implementation-defined system +start-up files. In some historical shells, the history file is initialized just after the <i>ENV</i> file has been processed. +Therefore, it is implementation-defined whether changes made to <i>HISTFILE</i> after the history file has been initialized are +effective. Implementations may choose to disable the history list mechanism for users with appropriate privileges who do not set +<i>HISTFILE ;</i> the specific circumstances under which this occurs are implementation-defined. If more than one instance of the +shell is using the same history file, it is unspecified how updates to the history file from those shells interact. As entries are +deleted from the history file, they shall be deleted oldest first. It is unspecified when history file entries are physically +removed from the history file.</dd> +<dt><i>HISTSIZE</i></dt> +<dd>Determine a decimal number representing the limit to the number of previous commands that are accessible. If this variable is +unset, an unspecified default greater than or equal to 128 shall be used. The maximum number of commands in the history list is +unspecified, but shall be at least 128. An implementation may choose to access this variable only when initializing the history +file, as described under <i>HISTFILE .</i> Therefore, it is unspecified whether changes made to <i>HISTSIZE</i> after the history +file has been initialized are effective.</dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_44_09" id="tag_20_44_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_44_10" id="tag_20_44_10"></a>STDOUT</h4> +<blockquote> +<p>When the <b>-l</b> option is used to list commands, the format of each command in the list shall be as follows:</p> +<pre> +<tt>"%d\t%s\n", <</tt><i>line number</i><tt>>, <</tt><i>command</i><tt>> +</tt></pre> +<p>If both the <b>-l</b> and <b>-n</b> options are specified, the format of each command shall be:</p> +<pre> +<tt>"\t%s\n", <</tt><i>command</i><tt>> +</tt></pre> +<p>If the <<i>command</i>> consists of more than one line, the lines after the first shall be displayed as:</p> +<pre> +<tt>"\t%s\n", <</tt><i>continued-command</i><tt>> +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_44_11" id="tag_20_44_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_44_12" id="tag_20_44_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_44_13" id="tag_20_44_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_44_14" id="tag_20_44_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion of the listing.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +<p>Otherwise, the exit status shall be that of the commands executed by <i>fc</i>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_44_15" id="tag_20_44_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_44_16" id="tag_20_44_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>This utility is required to be intrinsic. See <a href="../utilities/V3_chap01.html#tag_18_07"><i>1.7 Intrinsic Utilities</i></a> +for details.</p> +<p>Since editors sometimes use file descriptors as integral parts of their editing, redirecting their file descriptors as part of +the <i>fc</i> command can produce unexpected results. For example, if <a href="../utilities/vi.html"><i>vi</i></a> is the +<i>FCEDIT</i> editor, the command:</p> +<pre> +<tt>fc -s | more +</tt></pre> +<p>does not work correctly on many systems.</p> +<p>Users on windowing systems may want to have separate history files for each window by setting <i>HISTFILE</i> as follows:</p> +<pre> +<tt>HISTFILE=$HOME/.sh_hist$$ +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_44_17" id="tag_20_44_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_44_18" id="tag_20_44_18"></a>RATIONALE</h4> +<blockquote> +<p>This utility is based on the <i>fc</i> built-in of the KornShell.</p> +<p>An early proposal specified the <b>-e</b> option as <b>[-e</b> <i>editor</i> <b>[</b><i>old</i>= <i>new</i> <b>]]</b>, which is +not historical practice. Historical practice in <i>fc</i> of either <b>[-e</b> <i>editor</i><b>]</b> or <b>[-e - [</b> <i>old</i>= +<i>new</i> <b>]]</b> is acceptable, but not both together. To clarify this, a new option <b>-s</b> was introduced replacing the +<b>[-e -]</b>. This resolves the conflict and makes <i>fc</i> conform to the Utility Syntax Guidelines.</p> +<dl compact> +<dd></dd> +<dt><i>HISTFILE</i></dt> +<dd>Some implementations of the KornShell check for the superuser and do not create a history file unless <i>HISTFILE</i> is set. +This is done primarily to avoid creating unlinked files in the root file system when logging in during single-user mode. +<i>HISTFILE</i> must be set for the superuser to have history.</dd> +<dt><i>HISTSIZE</i></dt> +<dd>Needed to limit the size of history files. It is the intent of the standard developers that when two shells share the same +history file, commands that are entered in one shell shall be accessible by the other shell. Because of the difficulties of +synchronization over a network, the exact nature of the interaction is unspecified.</dd> +</dl> +<p>The initialization process for the history file can be dependent on the system start-up files, in that they may contain commands +that effectively preempt the settings the user has for <i>HISTFILE</i> and <i>HISTSIZE .</i> For example, function definition +commands are recorded in the history file. If the system administrator includes function definitions in some system start-up file +called before the <i>ENV</i> file, the history file is initialized before the user can influence its characteristics. In some +historical shells, the history file is initialized just after the <i>ENV</i> file has been processed. Because of these situations, +the text requires the initialization process to be implementation-defined.</p> +<p>Consideration was given to omitting the <i>fc</i> utility in favor of the command line editing feature in <a href= +"../utilities/sh.html"><i>sh</i></a>. For example, in <a href="../utilities/vi.html"><i>vi</i></a> editing mode, typing +<tt>"<ESC> v"</tt> is equivalent to:</p> +<pre> +<tt>EDITOR=vi fc +</tt></pre> +<p>However, the <i>fc</i> utility allows the user the flexibility to edit multiple commands simultaneously (such as <i>fc</i> 10 +20) and to use editors other than those supported by <a href="../utilities/sh.html"><i>sh</i></a> for command line editing.</p> +<p>In the KornShell, the alias <b>r</b> ("re-do") is preset to <i>fc</i> <b>-e -</b> (equivalent to the POSIX <i>fc</i> +<b>-s</b>). This is probably an easier command name to remember than <i>fc</i> ("fix command"), but it does not meet the Utility +Syntax Guidelines. Renaming <i>fc</i> to <i>hist</i> or <i>redo</i> was considered, but since this description closely matches +historical KornShell practice already, such a renaming was seen as gratuitous. Users are free to create aliases whenever odd +historical names such as <i>fc</i>, <a href="../utilities/awk.html"><i>awk</i></a>, <a href="../utilities/cat.html"><i>cat</i></a>, +<a href="../utilities/grep.html"><i>grep</i></a>, or <a href="../utilities/yacc.html"><i>yacc</i></a> are standardized by +POSIX.</p> +<p>Command numbers have no ordering effects; they are like serial numbers. The <b>-r</b> option and -<i>number</i> operand address +the sequence of command execution, regardless of serial numbers. So, for example, if the command number wrapped back to 1 at some +arbitrary point, there would be no ambiguity associated with traversing the wrap point. For example, if the command history +were:</p> +<pre> +<tt>32766: echo 1 +32767: echo 2 +1: echo 3 +</tt></pre> +<p>the number -2 refers to command 32767 because it is the second previous command, regardless of serial number.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_44_19" id="tag_20_44_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_44_20" id="tag_20_44_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/sh.html#"><i>sh</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_44_21" id="tag_20_44_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_44_22" id="tag_20_44_22"></a>Issue 5</h4> +<blockquote> +<p>The FUTURE DIRECTIONS section is added.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_44_23" id="tag_20_44_23"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +<p>In the ENVIRONMENT VARIABLES section, the text "user's home directory" is updated to "directory referred to by the +<i>HOME</i> environment variable".</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_44_24" id="tag_20_44_24"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_44_25" id="tag_20_44_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 854 is applied, adding a note to the APPLICATION USAGE section that this utility is required to be +intrinsic.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/false.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/fg.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/fg.html b/bdd/fg.html @@ -0,0 +1,208 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>fg</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/fc.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/file.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="fg" id="fg"></a> <a name="tag_20_45" id="tag_20_45"></a><!-- fg --> +<h4 class="mansect"><a name="tag_20_45_01" id="tag_20_45_01"></a>NAME</h4> +<blockquote>fg — run jobs in the foreground</blockquote> +<h4 class="mansect"><a name="tag_20_45_02" id="tag_20_45_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> fg</tt> <b>[</b><i>job_id</i><b>]</b> <tt><img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></tt></code></div> +</blockquote> +<h4 class="mansect"><a name="tag_20_45_03" id="tag_20_45_03"></a>DESCRIPTION</h4> +<blockquote> +<p>If job control is enabled (see the description of <a href="../utilities/V3_chap02.html#set"><i>set</i></a> <b>-m</b>), the shell +is interactive, and the current shell execution environment (see <a href="../utilities/V3_chap02.html#tag_19_13"><i>2.13 Shell +Execution Environment</i></a> ) is not a subshell environment, the <i>fg</i> utility shall move a background job in the current +execution environment into the foreground, as described in <a href="../utilities/V3_chap02.html#tag_19_11"><i>2.11 Job +Control</i></a> ; it may also do so if the shell is non-interactive or the current shell execution environment is a subshell +environment.</p> +<p>Using <i>fg</i> to place a job into the foreground shall remove its process ID from the list of those "known in the current +shell execution environment"; see <a href="../utilities/V3_chap02.html#tag_19_09_03_02"><i>2.9.3.1 Asynchronous AND-OR +Lists</i></a> .</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_45_04" id="tag_20_45_04"></a>OPTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_45_05" id="tag_20_45_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>job_id</i></dt> +<dd>Specify the job to be run as a foreground job. If no <i>job_id</i> operand is given, the <i>job_id</i> for the job that was +most recently suspended, placed in the background, or run as a background job shall be used. The format of <i>job_id</i> is +described in XBD <a href="../basedefs/V1_chap03.html#tag_03_182"><i>3.182 Job ID</i></a> .</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_45_06" id="tag_20_45_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_45_07" id="tag_20_45_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_45_08" id="tag_20_45_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>fg</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_45_09" id="tag_20_45_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_45_10" id="tag_20_45_10"></a>STDOUT</h4> +<blockquote> +<p>The <i>fg</i> utility shall write the command line of the job to standard output in the following format:</p> +<pre> +<tt>"%s\n", <</tt><i>command</i><tt>> +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_45_11" id="tag_20_45_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_45_12" id="tag_20_45_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_45_13" id="tag_20_45_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_45_14" id="tag_20_45_14"></a>EXIT STATUS</h4> +<blockquote> +<p>If the <i>fg</i> utility succeeds, it does not return an exit status. Instead, the shell waits for the job that <i>fg</i> moved +into the foreground.</p> +<p>If <i>fg</i> does not move a job into the foreground, the following exit value shall be returned:</p> +<dl compact> +<dd></dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_45_15" id="tag_20_45_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>If job control is disabled, the <i>fg</i> utility shall exit with an error and no job shall be placed in the foreground.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_45_16" id="tag_20_45_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>This utility is required to be intrinsic. See <a href="../utilities/V3_chap01.html#tag_18_07"><i>1.7 Intrinsic Utilities</i></a> +for details.</p> +<p>The <i>fg</i> utility does not work as expected when it is operating in its own utility execution environment because that +environment has no applicable jobs to manipulate. See the APPLICATION USAGE section for <a href= +"../utilities/bg.html#"><i>bg</i></a> . For this reason, <i>fg</i> is generally implemented as a shell regular built-in.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_45_17" id="tag_20_45_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_45_18" id="tag_20_45_18"></a>RATIONALE</h4> +<blockquote> +<p>The extensions to the shell specified in this volume of POSIX.1-2024 have mostly been based on features provided by the +KornShell. The job control features provided by <a href="../utilities/bg.html"><i>bg</i></a>, <i>fg</i>, and <a href= +"../utilities/jobs.html"><i>jobs</i></a> are also based on the KornShell. The standard developers examined the characteristics of +the C shell versions of these utilities and found that differences exist. Despite widespread use of the C shell, the KornShell +versions were selected for this volume of POSIX.1-2024 to maintain a degree of uniformity with the rest of the KornShell features +selected (such as the very popular command line editing features).</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_45_19" id="tag_20_45_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_45_20" id="tag_20_45_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19_09_03_02"><i>2.9.3.1 Asynchronous AND-OR Lists</i></a> , <a href= +"../utilities/V3_chap02.html#tag_19_13"><i>2.13 Shell Execution Environment</i></a> , <a href="../utilities/bg.html#"><i>bg</i></a> +, <a href="../utilities/kill.html#tag_20_64"><i>kill</i></a> , <a href="../utilities/jobs.html#"><i>jobs</i></a> , <a href= +"../utilities/wait.html#tag_20_147"><i>wait</i></a></p> +<p>XBD <a href="../basedefs/V1_chap03.html#tag_03_182"><i>3.182 Job ID</i></a> , <a href="../basedefs/V1_chap08.html#tag_08"><i>8. +Environment Variables</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_45_21" id="tag_20_45_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_45_22" id="tag_20_45_22"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +<p>The APPLICATION USAGE section is added.</p> +<p>The JC marking is removed from the SYNOPSIS since job control is mandatory is this version.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_45_23" id="tag_20_45_23"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 854 is applied, adding a note to the APPLICATION USAGE section that this utility is required to be +intrinsic.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1254 is applied, updating the DESCRIPTION to account for the addition of <a href= +"../utilities/V3_chap02.html#tag_19_11"><i>2.11 Job Control</i></a> and changing the EXIT STATUS section.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/fc.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/file.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/file.html b/bdd/file.html @@ -0,0 +1,689 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>file</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/fg.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/find.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="file" id="file"></a> <a name="tag_20_46" id="tag_20_46"></a><!-- file --> +<h4 class="mansect"><a name="tag_20_46_01" id="tag_20_46_01"></a>NAME</h4> +<blockquote>file — determine file type</blockquote> +<h4 class="mansect"><a name="tag_20_46_02" id="tag_20_46_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>file</tt> <b>[</b><tt>-dh</tt><b>] [</b><tt>-M</tt> <i>file</i><b>] [</b><tt>-m</tt> <i>file</i><b>]</b> +<i>file</i><tt>...<br> +<br> +file -i</tt> <b>[</b><tt>-h</tt><b>]</b> <i>file</i><tt>...<br></tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_46_03" id="tag_20_46_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>file</i> utility shall perform a series of tests in sequence on each specified <i>file</i> in an attempt to classify +it:</p> +<ol> +<li> +<p>If <i>file</i> does not exist, cannot be read, or its file status could not be determined, the output shall indicate that the +file was processed, but that its type could not be determined.</p> +</li> +<li> +<p>If the file is not a regular file, its file type shall be identified. The file types directory, FIFO, socket, block special, and +character special shall be identified as such. Other implementation-defined file types may also be identified. If <i>file</i> is a +symbolic link, by default the link shall be resolved and <i>file</i> shall test the type of file referenced by the symbolic link. +(See the <b>-h</b> and <b>-i</b> options below.)</p> +</li> +<li> +<p>If the length of <i>file</i> is zero, it shall be identified as an empty file.</p> +</li> +<li> +<p>The <i>file</i> utility shall examine an initial segment of <i>file</i> and shall make a guess at identifying its contents based +on position-sensitive tests. (The answer is not guaranteed to be correct; see the <b>-d</b>, <b>-M</b>, and <b>-m</b> options +below.)</p> +</li> +<li> +<p>The <i>file</i> utility shall examine <i>file</i> and make a guess at identifying its contents based on context-sensitive +default system tests. (The answer is not guaranteed to be correct.)</p> +</li> +<li> +<p>The file shall be identified as a data file.</p> +</li> +</ol> +<p>If <i>file</i> does not exist, cannot be read, or its file status could not be determined, the output shall indicate that the +file was processed, but that its type could not be determined.</p> +<p>If <i>file</i> is a symbolic link, by default the link shall be resolved and <i>file</i> shall test the type of file referenced +by the symbolic link.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_46_04" id="tag_20_46_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>file</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> , except that the order of the <b>-m</b>, <b>-d</b>, and <b>-M</b> options shall be significant.</p> +<p>The following options shall be supported by the implementation:</p> +<dl compact> +<dd></dd> +<dt><b>-d</b></dt> +<dd>Apply any position-sensitive default system tests and context-sensitive default system tests to the file. This is the default +if no <b>-M</b> or <b>-m</b> option is specified.</dd> +<dt><b>-h</b></dt> +<dd>When a symbolic link is encountered, identify the file as a symbolic link. If <b>-h</b> is not specified and <i>file</i> is a +symbolic link that refers to a nonexistent file, <i>file</i> shall identify the file as a symbolic link, as if <b>-h</b> had been +specified.</dd> +<dt><b>-i</b></dt> +<dd>If a file is a regular file, do not attempt to classify the type of the file further, but identify the file as specified in the +STDOUT section.</dd> +<dt><b>-M </b><i>file</i></dt> +<dd>Specify the name of a file containing position-sensitive tests that shall be applied to a file in order to classify it (see the +EXTENDED DESCRIPTION). No position-sensitive default system tests nor context-sensitive default system tests shall be applied +unless the <b>-d</b> option is also specified.</dd> +<dt><b>-m </b><i>file</i></dt> +<dd>Specify the name of a file containing position-sensitive tests that shall be applied to a file in order to classify it (see the +EXTENDED DESCRIPTION).</dd> +</dl> +<p>If the <b>-m</b> option is specified without specifying the <b>-d</b> option or the <b>-M</b> option, position-sensitive default +system tests shall be applied after the position-sensitive tests specified by the <b>-m</b> option. If the <b>-M</b> option is +specified with the <b>-d</b> option, the <b>-m</b> option, or both, or the <b>-m</b> option is specified with the <b>-d</b> option, +the concatenation of the position-sensitive tests specified by these options shall be applied in the order specified by the +appearance of these options. If a <b>-M</b> or <b>-m</b> <i>file</i> option-argument is <b>-</b>, the results are unspecified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_46_05" id="tag_20_46_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of a file to be tested.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_46_06" id="tag_20_46_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be used if a <i>file</i> operand is <tt>'-'</tt> and the implementation treats the <tt>'-'</tt> as +meaning standard input. Otherwise, the standard input shall not be used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_46_07" id="tag_20_46_07"></a>INPUT FILES</h4> +<blockquote> +<p>The <i>file</i> can be any file type.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_46_08" id="tag_20_46_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>file</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error and +informative messages written to standard output.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_46_09" id="tag_20_46_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_46_10" id="tag_20_46_10"></a>STDOUT</h4> +<blockquote> +<p>In the POSIX locale, the following format shall be used to identify each operand, <i>file</i> specified:</p> +<pre> +<tt>"%s: %s\n", <</tt><i>file</i><tt>>, <</tt><i>type</i><tt>> +</tt></pre> +<p>The values for <<i>type</i>> are unspecified, except that in the POSIX locale, if <i>file</i> is identified as one of the +types listed in the following table, <<i>type</i>> shall contain (but is not limited to) the corresponding string, unless the +file is identified by a position-sensitive test specified by a <b>-M</b> or <b>-m</b> option. Each <space> shown in the +strings shall be exactly one <space>.<br></p> +<p class="caption"><a name="tagtcjh_20" id="tagtcjh_20"></a> Table: File Utility Output Strings</p> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>If <i>file</i> is:</b></p> +</th> +<th align="center"> +<p class="tent"><b><<i>type</i>> shall contain the string:</b></p> +</th> +<th align="center"> +<p class="tent"><b>Notes</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">Nonexistent</p> +</td> +<td align="left"> +<p class="tent">cannot open</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">Block special</p> +</td> +<td align="left"> +<p class="tent">block special</p> +</td> +<td align="left"> +<p class="tent">1</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">Character special</p> +</td> +<td align="left"> +<p class="tent">character special</p> +</td> +<td align="left"> +<p class="tent">1</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">Directory</p> +</td> +<td align="left"> +<p class="tent">directory</p> +</td> +<td align="left"> +<p class="tent">1</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">FIFO</p> +</td> +<td align="left"> +<p class="tent">fifo</p> +</td> +<td align="left"> +<p class="tent">1</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">Socket</p> +</td> +<td align="left"> +<p class="tent">socket</p> +</td> +<td align="left"> +<p class="tent">1</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">Symbolic link</p> +</td> +<td align="left"> +<p class="tent">symbolic link to</p> +</td> +<td align="left"> +<p class="tent">1</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">Regular file</p> +</td> +<td align="left"> +<p class="tent">regular file</p> +</td> +<td align="left"> +<p class="tent">1,2</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">Empty regular file</p> +</td> +<td align="left"> +<p class="tent">empty</p> +</td> +<td align="left"> +<p class="tent">3</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">Regular file that cannot be read</p> +</td> +<td align="left"> +<p class="tent">cannot open</p> +</td> +<td align="left"> +<p class="tent">3</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">Executable binary</p> +</td> +<td align="left"> +<p class="tent">executable</p> +</td> +<td align="left"> +<p class="tent">3,4,6</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>ar</i> archive library (see <i>ar</i>)</p> +</td> +<td align="left"> +<p class="tent">archive</p> +</td> +<td align="left"> +<p class="tent">3,4,6</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">Extended <i>cpio</i> format (see <i>pax</i>)</p> +</td> +<td align="left"> +<p class="tent">cpio archive</p> +</td> +<td align="left"> +<p class="tent">3,4,6</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">Extended <i>tar</i> format (see <b>ustar</b> in <i>pax</i>)</p> +</td> +<td align="left"> +<p class="tent">tar archive</p> +</td> +<td align="left"> +<p class="tent">3,4,6</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">Shell script</p> +</td> +<td align="left"> +<p class="tent">commands text</p> +</td> +<td align="left"> +<p class="tent">3,5,6</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">C-language source</p> +</td> +<td align="left"> +<p class="tent">c program text</p> +</td> +<td align="left"> +<p class="tent">3,5,6</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">FORTRAN source</p> +</td> +<td align="left"> +<p class="tent">fortran program text</p> +</td> +<td align="left"> +<p class="tent">3,5,6</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">Regular file whose type cannot be determined</p> +</td> +<td align="left"> +<p class="tent">data</p> +</td> +<td align="left"> +<p class="tent">3</p> +</td> +</tr> +</table> +</center> +<basefont size="2"> +<dl> +<dt><b>Notes:</b></dt> +<dd> +<ol> +<li class="tent">This is a file type test.</li> +<li class="tent">This test is applied only if the <b>-i</b> option is specified.</li> +<li class="tent">This test is applied only if the <b>-i</b> option is not specified.</li> +<li class="tent">This is a position-sensitive default system test.</li> +<li class="tent">This is a context-sensitive default system test.</li> +<li class="tent">Position-sensitive default system tests and context-sensitive default system tests are not applied if the +<b>-M</b> option is specified unless the <b>-d</b> option is also specified.</li> +</ol> +</dd> +</dl> +<basefont size="3"> +<p class="tent">In the POSIX locale, if <i>file</i> is identified as a symbolic link (see the <b>-h</b> option), the following +alternative output format shall be used:</p> +<pre> +<tt>"%s: %s %s\n", <</tt><i>file</i><tt>>, <</tt><i>type</i><tt>>, <</tt><i>contents of link</i><tt>>" +</tt></pre> +<p class="tent">If the file named by the <i>file</i> operand does not exist, cannot be read, or the type of the file named by the +<i>file</i> operand cannot be determined, this shall not be considered an error that affects the exit status.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_46_11" id="tag_20_46_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_46_12" id="tag_20_46_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_46_13" id="tag_20_46_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>A file specified as an option-argument to the <b>-m</b> or <b>-M</b> options shall contain one position-sensitive test per line, +which shall be applied to the file. If the test succeeds, the message field of the line shall be printed and no further tests shall +be applied, with the exception that tests on immediately following lines beginning with a single <tt>'>'</tt> character shall be +applied.</p> +<p class="tent">Each line shall be composed of the following four <tab>-separated fields. (Implementations may allow any +combination of one or more white-space characters other than <newline> to act as field separators.)</p> +<dl compact> +<dd></dd> +<dt><i>offset</i></dt> +<dd>An unsigned number (optionally preceded by a single <tt>'>'</tt> character) specifying the <i>offset</i>, in bytes, of the +value in the file that is to be compared against the <i>value</i> field of the line. If the file is shorter than the specified +offset, the test shall fail. +<p class="tent">If the <i>offset</i> begins with the character <tt>'>'</tt>, the test contained in the line shall not be applied +to the file unless the test on the last line for which the <i>offset</i> did not begin with a <tt>'>'</tt> was successful. By +default, the <i>offset</i> shall be interpreted as an unsigned decimal number. With a leading 0x or 0X, the <i>offset</i> shall be +interpreted as a hexadecimal number; otherwise, with a leading 0, the <i>offset</i> shall be interpreted as an octal number.</p> +</dd> +<dt><i>type</i></dt> +<dd>The type of the value in the file to be tested. The type shall consist of the type specification characters <tt>d</tt>, +<tt>s</tt>, and <tt>u</tt>, specifying signed decimal, string, and unsigned decimal, respectively. +<p class="tent">The <i>type</i> string shall be interpreted as the bytes from the file starting at the specified <i>offset</i> and +including the same number of bytes specified by the <i>value</i> field. If insufficient bytes remain in the file past the +<i>offset</i> to match the <i>value</i> field, the test shall fail.</p> +<p class="tent">The type specification characters <tt>d</tt> and <tt>u</tt> can be followed by an optional unsigned decimal integer +that specifies the number of bytes represented by the type. The type specification characters <tt>d</tt> and <tt>u</tt> can be +followed by an optional <tt>C</tt>, <tt>S</tt>, <tt>I</tt>, or <tt>L</tt>, indicating that the value is of type <b>char</b>, +<b>short</b>, <b>int</b>, or <b>long</b>, respectively.</p> +<p class="tent">The default number of bytes represented by the type specifiers <tt>d</tt>, <tt>f</tt>, and <tt>u</tt> shall +correspond to their respective C-language types as follows. If the system claims conformance to the C-Language Development +Utilities option, those specifiers shall correspond to the default sizes used in the <a href="../utilities/c17.html"><i>c17</i></a> +utility. Otherwise, the default sizes shall be implementation-defined.</p> +<p class="tent">For the type specifier characters <tt>d</tt> and <tt>u</tt>, the default number of bytes shall correspond to the +size of a basic integer type of the implementation. For these specifier characters, the implementation shall support values of the +optional number of bytes to be converted corresponding to the number of bytes in the C-language types <b>char</b>, <b>short</b>, +<b>int</b>, or <b>long</b>. These numbers can also be specified by an application as the characters <tt>C</tt>, <tt>S</tt>, +<tt>I</tt>, and <tt>L</tt>, respectively. The byte order used when interpreting numeric values is implementation-defined, but shall +correspond to the order in which a constant of the corresponding type is stored in memory on the system.</p> +<p class="tent">All type specifiers, except for <tt>s</tt>, can be followed by a mask specifier of the form &<i>number</i>. The +mask value shall be AND'ed with the value of the input file before the comparison with the <i>value</i> field of the line is made. +By default, the mask shall be interpreted as an unsigned decimal number. With a leading 0x or 0X, the mask shall be interpreted as +an unsigned hexadecimal number; otherwise, with a leading 0, the mask shall be interpreted as an unsigned octal number.</p> +<p class="tent">The strings <b>byte</b>, <b>short</b>, <b>long</b>, and <b>string</b> shall also be supported as type fields, being +interpreted as <tt>dC</tt>, <tt>dS</tt>, <tt>dL</tt>, and <tt>s</tt>, respectively.</p> +</dd> +<dt><i>value</i></dt> +<dd>The <i>value</i> to be compared with the value from the file. +<p class="tent">If the specifier from the type field is <tt>s</tt> or <b>string</b>, then interpret the value as a string. +Otherwise, interpret it as a number. If the value is a string, then the test shall succeed only when a string value exactly matches +the bytes from the file.</p> +<p class="tent">If the <i>value</i> is a string, it can contain the following sequences:</p> +<dl compact> +<dd></dd> +<dt>\<i>character</i></dt> +<dd>The <backslash>-escape sequences as specified in XBD <a href="../basedefs/V1_chap05.html#tagtcjh_2"><i>Escape Sequences +and Associated Actions</i></a> (<tt>'\\'</tt>, <tt>'\a'</tt>, <tt>'\b'</tt>, <tt>'\f'</tt>, <tt>'\n'</tt>, <tt>'\r'</tt>, +<tt>'\t'</tt>, <tt>'\v'</tt>). In addition, the escape sequence <tt>'\ '</tt> (the <backslash> character followed by a +<space> character) shall be recognized to represent a <space> character. The results of using any other character, +other than an octal digit, following the <backslash> are unspecified.</dd> +<dt>\<i>octal</i></dt> +<dd>Octal sequences that can be used to represent characters with specific coded values. An octal sequence shall consist of a +<backslash> followed by the longest sequence of one, two, or three octal-digit characters (01234567).</dd> +</dl> +<p class="tent">By default, any value that is not a string shall be interpreted as a signed decimal number. Any such value, with a +leading 0x or 0X, shall be interpreted as an unsigned hexadecimal number; otherwise, with a leading zero, the value shall be +interpreted as an unsigned octal number.</p> +<p class="tent">If the value is not a string, it can be preceded by a character indicating the comparison to be performed. +Permissible characters and the comparisons they specify are as follows:</p> +<dl compact> +<dd></dd> +<dt><tt>=</tt></dt> +<dd>The test shall succeed if the value from the file equals the <i>value</i> field.</dd> +<dt><tt><</tt></dt> +<dd>The test shall succeed if the value from the file is less than the <i>value</i> field.</dd> +<dt><tt>></tt></dt> +<dd>The test shall succeed if the value from the file is greater than the <i>value</i> field.</dd> +<dt><tt>&</tt></dt> +<dd>The test shall succeed if all of the set bits in the <i>value</i> field are set in the value from the file.</dd> +<dt><tt>^</tt></dt> +<dd>The test shall succeed if at least one of the set bits in the <i>value</i> field is not set in the value from the file.</dd> +<dt><tt>x</tt></dt> +<dd>The test shall succeed if the file is large enough to contain a value of the type specified starting at the offset +specified.</dd> +</dl> +</dd> +<dt><i>message</i></dt> +<dd>The <i>message</i> to be printed if the test succeeds. The <i>message</i> shall be interpreted using the notation for the +<a href="../utilities/printf.html"><i>printf</i></a> formatting specification; see <a href= +"../utilities/printf.html"><i>printf</i></a>. If the <i>value</i> field was a string, then the value from the file shall be the +argument for the <a href="../utilities/printf.html"><i>printf</i></a> formatting specification; otherwise, the value from the file +shall be the argument.</dd> +</dl> +<br></blockquote> +<h4 class="mansect"><a name="tag_20_46_14" id="tag_20_46_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_46_15" id="tag_20_46_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_46_16" id="tag_20_46_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The <i>file</i> utility can only be required to guess at many of the file types because only exhaustive testing can determine +some types with certainty. For example, binary data on some implementations might match the initial segment of an executable or a +<i>tar</i> archive.</p> +<p class="tent">Note that the table indicates that the output contains the stated string. Systems may add text before or after the +string. For executables, as an example, the machine architecture and various facts about how the file was link-edited may be +included. Note also that on systems that recognize shell script files starting with <tt>"#!"</tt> as executable files, these may be +identified as executable binary files rather than as shell scripts.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_46_17" id="tag_20_46_17"></a>EXAMPLES</h4> +<blockquote> +<p>Determine whether an argument is a binary executable file:</p> +<pre> +<tt>file -- "$1" | grep -q ':.*executable' && + printf "%s is executable.\n" "$1" +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_46_18" id="tag_20_46_18"></a>RATIONALE</h4> +<blockquote> +<p>The <b>-f</b> option was omitted because the same effect can (and should) be obtained using the <a href= +"../utilities/xargs.html"><i>xargs</i></a> utility.</p> +<p class="tent">Historical versions of the <i>file</i> utility attempt to identify the following types of files: symbolic link, +directory, character special, block special, socket, <i>tar</i> archive, <i>cpio</i> archive, SCCS archive, archive library, empty, +<a href="../utilities/compress.html"><i>compress</i></a> output, <i>pack</i> output, binary data, C source, FORTRAN source, +assembler source, <i>nroff</i>/<i>troff</i>/<i>eqn</i>/<i>tbl</i> source <i>troff</i> output, shell script, C shell script, English +text, ASCII text, various executables, APL workspace, compiled terminfo entries, and CURSES screen images. Only those types that +are reasonably well specified in POSIX or are directly related to POSIX utilities are listed in the table.</p> +<p class="tent">Historical systems have used a "magic file" named <b>/etc/magic</b> to help identify file types. Because it is +generally useful for users and scripts to be able to identify special file types, the <b>-m</b> flag and a portable format for +user-created magic files has been specified. No requirement is made that an implementation of <i>file</i> use this method of +identifying files, only that users be permitted to add their own classifying tests.</p> +<p class="tent">In addition, three options have been added to historical practice. The <b>-d</b> flag has been added to permit +users to cause their tests to follow any default system tests. The <b>-i</b> flag has been added to permit users to test portably +for regular files in shell scripts. The <b>-M</b> flag has been added to permit users to ignore any default system tests.</p> +<p class="tent">The POSIX.1-2024 description of default system tests and the interaction between the <b>-d</b>, <b>-M</b>, and +<b>-m</b> options did not clearly indicate that there were two types of "default system tests". The "position-sensitive tests" +determine file types by looking for certain string or binary values at specific offsets in the file being examined. These +position-sensitive tests were implemented in historical systems using the magic file described above. Some of these tests are now +built into the <i>file</i> utility itself on some implementations so the output can provide more detail than can be provided by +magic files. For example, a magic file can easily identify a file containing a core image on most implementations, but cannot name +the program file that dropped the core. A magic file could produce output such as:</p> +<pre> +<tt>/home/dwc/core: ELF 32-bit MSB core file SPARC Version 1 +</tt></pre> +<p class="tent">but by building the test into the <i>file</i> utility, you could get output such as:</p> +<pre> +<tt>/home/dwc/core: ELF 32-bit MSB core file SPARC Version 1, from 'testprog' +</tt></pre> +<p class="tent">These extended built-in tests are still to be treated as position-sensitive default system tests even if they are +not listed in <b>/etc/magic</b> or any other magic file.</p> +<p class="tent">The context-sensitive default system tests were always built into the <i>file</i> utility. These tests looked for +language constructs in text files trying to identify shell scripts, C, FORTRAN, and other computer language source files, and even +plain text files. With the addition of the <b>-m</b> and <b>-M</b> options the distinction between position-sensitive and +context-sensitive default system tests became important because the order of testing is important. The context-sensitive system +default tests should never be applied before any position-sensitive tests even if the <b>-d</b> option is specified before a +<b>-m</b> option or <b>-M</b> option due to the high probability that the context-sensitive system default tests will incorrectly +identify arbitrary text files as text files before position-sensitive tests specified by the <b>-m</b> or <b>-M</b> option would be +applied to give a more accurate identification.</p> +<p class="tent">Leaving the meaning of <b>-M -</b> and <b>-m -</b> unspecified allows an existing prototype of these options to +continue to work in a backwards-compatible manner. (In that implementation, <b>-M -</b> was roughly equivalent to <b>-d</b> in +POSIX.1-2024.)</p> +<p class="tent">The historical <b>-c</b> option was omitted as not particularly useful to users or portable shell scripts. In +addition, a reasonable implementation of the <i>file</i> utility would report any errors found each time the magic file is +read.</p> +<p class="tent">The historical format of the magic file was the same as that specified by the Rationale in the +ISO POSIX-2:1993 standard for the <i>offset</i>, <i>value</i>, and <i>message</i> fields; however, it used less precise type +fields than the format specified by the current normative text. The new type field values are a superset of the historical +ones.</p> +<p class="tent">The following is an example magic file:</p> +<pre> +<tt>0 short 070707 cpio archive +0 short 0143561 Byte-swapped cpio archive +0 string 070707 ASCII cpio archive +0 long 0177555 Very old archive +0 short 0177545 Old archive +0 short 017437 Old packed data +0 string \037\036 Packed data +0 string \377\037 Compacted data +0 string \037\235 Compressed data +>2 byte&0x80 >0 Block compressed +>2 byte&0x1f x %d bits +0 string \032\001 Compiled Terminfo Entry +0 short 0433 Curses screen image +0 short 0434 Curses screen image +0 string <ar> System V Release 1 archive +0 string !<arch>\n__.SYMDEF Archive random library +0 string !<arch> Archive +0 string ARF_BEGARF PHIGS clear text archive +0 long 0x137A2950 Scalable OpenFont binary +0 long 0x137A2951 Encrypted scalable OpenFont binary +</tt></pre> +<p class="tent">The use of a basic integer data type is intended to allow the implementation to choose a word size commonly used by +applications on that architecture.</p> +<p class="tent">Earlier versions of this standard allowed for implementations with bytes other than eight bits, but this has been +modified in this version.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_46_19" id="tag_20_46_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_46_20" id="tag_20_46_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/ar.html#"><i>ar</i></a> , <a href="../utilities/ls.html#"><i>ls</i></a> , <a href= +"../utilities/pax.html#"><i>pax</i></a> , <a href="../utilities/printf.html#tag_20_96"><i>printf</i></a></p> +<p class="tent">XBD <a href="../basedefs/V1_chap05.html#tagtcjh_2"><i>Escape Sequences and Associated Actions</i></a> , <a href= +"../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 +Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_46_21" id="tag_20_46_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_46_22" id="tag_20_46_22"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +<p class="tent">Options and an EXTENDED DESCRIPTION are added as specified in the IEEE P1003.2b draft standard.</p> +<p class="tent">IEEE PASC Interpretations 1003.2 #192 and #178 are applied.</p> +<p class="tent">IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/25 is applied, making major changes to address +ambiguities raised in defect reports.</p> +<p class="tent">IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/26 is applied, making it clear in the OPTIONS +section that the <b>-m</b>, <b>-d</b>, and <b>-M</b> options do not comply with Guideline 11 of the Utility Syntax Guidelines.</p> +<p class="tent">IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/10 is applied, clarifying the specification +characters.</p> +<p class="tent">IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/11 is applied, allowing application developers to +create portable magic files that can match characters in strings, and allowing common extensions found in existing +implementations.</p> +<p class="tent">IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/12 is applied, removing text describing behavior on +systems with bytes consisting of more than eight bits.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_46_23" id="tag_20_46_23"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #092 is applied.</p> +<p class="tent">SD5-XCU-ERN-4 is applied, adding further entries in the Notes column in <a href="#tagtcjh_20">File Utility Output +Strings</a> .</p> +<p class="tent">SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p class="tent">The <i>file</i> utility is moved from the User Portability Utilities option to the Base. User Portability Utilities +is now an option for interactive utilities.</p> +<p class="tent">The EXAMPLES section is revised to correct an error with the pathname <tt>"$1"</tt>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_46_24" id="tag_20_46_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to report an error if a utility is directed to display a +pathname that contains any bytes that have the encoded value of a <newline> character when <newline> is a terminator or +separator in the output format being used.</p> +<p class="tent">Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p class="tent">Austin Group Defect 1141 is applied, changing "core file" to "file containing a core image".</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/fg.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/find.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/find.html b/bdd/find.html @@ -0,0 +1,700 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>find</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/file.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/fold.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="find" id="find"></a> <a name="tag_20_47" id="tag_20_47"></a><!-- find --> +<h4 class="mansect"><a name="tag_20_47_01" id="tag_20_47_01"></a>NAME</h4> +<blockquote>find — find files</blockquote> +<h4 class="mansect"><a name="tag_20_47_02" id="tag_20_47_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>find</tt> <b>[</b><tt>-H|-L</tt><b>]</b> <i>path</i><tt>...</tt> <b>[</b><i>operand_expression</i><tt>...</tt><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_47_03" id="tag_20_47_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>find</i> utility shall recursively descend the directory hierarchy from each file specified by <i>path</i>, evaluating a +Boolean expression composed of the primaries described in the OPERANDS section for each file encountered. Each <i>path</i> operand +shall be evaluated unaltered as it was provided, including all trailing <slash> characters; all pathnames for other files +encountered in the hierarchy shall consist of the concatenation of the current <i>path</i> operand, a <slash> if the current +<i>path</i> operand did not end in one, and the filename relative to the <i>path</i> operand. The relative portion shall contain no +dot or dot-dot components, no trailing <slash> characters, and only single <slash> characters between pathname +components.</p> +<p>The <i>find</i> utility shall be able to descend to arbitrary depths in a file hierarchy and shall not fail due to path length +limitations (unless a <i>path</i> operand specified by the application exceeds {PATH_MAX} requirements).</p> +<p>The <i>find</i> utility shall detect infinite loops; that is, entering a previously visited directory that is an ancestor of the +last file encountered. When it detects an infinite loop, <i>find</i> shall write a diagnostic message to standard error and shall +either recover its position in the hierarchy or terminate. In either case, the final exit status shall be non-zero.</p> +<p>If a file is removed from or added to the directory hierarchy being searched it is unspecified whether or not <i>find</i> +includes that file in its search.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_47_04" id="tag_20_47_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>find</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported by the implementation:</p> +<dl compact> +<dd></dd> +<dt><b>-H</b></dt> +<dd>Cause the file information and file type evaluated for each symbolic link encountered as a <i>path</i> operand on the command +line to be those of the file referenced by the link, and not the link itself. If the referenced file does not exist, the file +information and type shall be for the link itself. File information and type for symbolic links encountered during the traversal of +a file hierarchy shall be that of the link itself.</dd> +<dt><b>-L</b></dt> +<dd>Cause the file information and file type evaluated for each symbolic link encountered as a <i>path</i> operand on the command +line or encountered during the traversal of a file hierarchy to be those of the file referenced by the link, and not the link +itself. If the referenced file does not exist, the file information and type shall be for the link itself.</dd> +</dl> +<p>Specifying more than one of the mutually-exclusive options <b>-H</b> and <b>-L</b> shall not be considered an error. The last +option specified shall determine the behavior of the utility. If neither the <b>-H</b> nor the <b>-L</b> option is specified, then +the file information and type for symbolic links encountered as a <i>path</i> operand on the command line or encountered during the +traversal of a file hierarchy shall be that of the link itself.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_47_05" id="tag_20_47_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<p>The first operand and subsequent operands up to but not including the first operand that starts with a <tt>'-'</tt>, or is a +<tt>'!'</tt> or a <tt>'('</tt>, shall be interpreted as <i>path</i> operands. If the first operand starts with a <tt>'-'</tt>, or +is a <tt>'!'</tt> or a <tt>'('</tt>, the behavior is unspecified. Each <i>path</i> operand is a pathname of a starting point in the +file hierarchy.</p> +<p>The first operand that starts with a <tt>'-'</tt>, or is a <tt>'!'</tt> or a <tt>'('</tt>, and all subsequent arguments shall be +interpreted as an <i>expression</i> made up of the following primaries and operators. In the descriptions, wherever <i>n</i> is +used as a primary argument, it shall be interpreted as a decimal integer optionally preceded by a <plus-sign> (<tt>'+'</tt>) +or <hyphen-minus> (<tt>'-'</tt>), as follows:</p> +<dl compact> +<dd></dd> +<dt>+<i>n</i></dt> +<dd>More than <i>n</i>.</dd> +<dt><i>n</i></dt> +<dd>Exactly <i>n</i>.</dd> +<dt>-<i>n</i></dt> +<dd>Less than <i>n</i>.</dd> +</dl> +<p>The following primaries shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-name </b><i>pattern</i></dt> +<dd><br> +The primary shall evaluate as true if the basename of the current pathname matches <i>pattern</i> using the pattern matching +notation described in <a href="../utilities/V3_chap02.html#tag_19_14"><i>2.14 Pattern Matching Notation</i></a> . The additional +rules in <a href="../utilities/V3_chap02.html#tag_19_14_03"><i>2.14.3 Patterns Used for Filename Expansion</i></a> do not apply as +this is a matching operation, not an expansion.</dd> +<dt><b>-iname </b><i>pattern</i></dt> +<dd><br> +The <b>-iname</b> primary shall be equivalent to <b>-name</b>, except that the match shall be case insensitive. See XBD <a href= +"../basedefs/V1_chap04.html#tag_04_01"><i>4.1 Case Insensitive Comparisons</i></a> .</dd> +<dt><b>-path </b><i>pattern</i></dt> +<dd><br> +The primary shall evaluate as true if the current pathname matches <i>pattern</i> using the pattern matching notation described in +<a href="../utilities/V3_chap02.html#tag_19_14"><i>2.14 Pattern Matching Notation</i></a> . The additional rules in <a href= +"../utilities/V3_chap02.html#tag_19_14_03"><i>2.14.3 Patterns Used for Filename Expansion</i></a> do not apply as this is a +matching operation, not an expansion.</dd> +<dt><b>-nouser</b></dt> +<dd>The primary shall evaluate as true if the file belongs to a user ID for which the <a href= +"../functions/getpwuid.html"><i>getpwuid</i>()</a> function defined in the System Interfaces volume of POSIX.1-2024 (or equivalent) +returns NULL.</dd> +<dt><b>-nogroup</b></dt> +<dd>The primary shall evaluate as true if the file belongs to a group ID for which the <a href= +"../functions/getgrgid.html"><i>getgrgid</i>()</a> function defined in the System Interfaces volume of POSIX.1-2024 (or equivalent) +returns NULL.</dd> +<dt><b>-mount</b></dt> +<dd>The primary shall always evaluate as true; it shall cause <i>find</i> to act only on files that have the same device ID +(<i>st_dev</i>, see XSH <a href="../functions/fstatat.html#"><i>fstatat</i></a> ) as the <i>path</i> operand below which they are +encountered and cause <i>find</i> not to descend below directories that have a different device ID than that <i>path</i> operand. +If any <b>-mount</b> primary is specified, it shall apply to the entire expression even if the <b>-mount</b> primary would not +normally be evaluated.</dd> +<dt><b>-xdev</b></dt> +<dd>The primary shall always evaluate as true; it shall cause <i>find</i> not to descend below directories that have a different +device ID (<i>st_dev</i>, see XSH <a href="../functions/fstatat.html#"><i>fstatat</i></a> ) than the <i>path</i> operand below +which they are encountered; that is, when a directory with a different device ID is encountered, <i>find</i> shall act on the +directory itself (unless <b>-mount</b> is specified) but shall not act on any files below the directory. If any <b>-xdev</b> +primary is specified, it shall apply to the entire expression even if the <b>-xdev</b> primary would not normally be +evaluated.</dd> +<dt><b>-prune</b></dt> +<dd>The primary shall always evaluate as true; it shall cause <i>find</i> not to descend the current pathname if it is a directory. +If the <b>-depth</b> primary is specified, the <b>-prune</b> primary shall have no effect.</dd> +<dt><b>-perm [-]</b><i>mode</i></dt> +<dd><br> +The <i>mode</i> argument is used to represent file mode bits. It shall be processed in an identical manner to the +<i>symbolic_mode</i> operand described in <a href="../utilities/chmod.html"><i>chmod</i></a>, except that: +<ol> +<li> +<p>The changes to file mode bits shall be applied to a template instead of to any files. The template shall initially have all file +mode bits cleared.</p> +</li> +<li> +<p>The <i>op</i> symbol <tt>'-'</tt> cannot be the first character of <i>mode</i>; this avoids ambiguity with the optional leading +<hyphen-minus>. Since the initial mode is all bits off, there are not any symbolic modes that need to use <tt>'-'</tt> as the +first character.</p> +</li> +</ol> +<p>If the <hyphen-minus> is omitted, the primary shall evaluate as true when the file permission bits exactly match the value +of the resulting template.</p> +<p>Otherwise, if <i>mode</i> is prefixed by a <hyphen-minus>, the primary shall evaluate as true if at least all the bits in +the resulting template are set in the file permission bits.</p> +</dd> +<dt><b>-perm [-]</b><i>onum</i></dt> +<dd><br> +If the <hyphen-minus> is omitted, the primary shall evaluate as true when the file mode bits exactly match the value of the +octal number <i>onum</i> (see the description of the octal <i>mode</i> in <a href="../utilities/chmod.html"><i>chmod</i></a>). +Otherwise, if <i>onum</i> is prefixed by a <hyphen-minus>, the primary shall evaluate as true if at least all of the bits +specified in <i>onum</i> are set. In both cases, the behavior is unspecified when <i>onum</i> exceeds 07777.</dd> +<dt><b>-type </b><i>c</i></dt> +<dd>The primary shall evaluate as true if the type of the file is <i>c</i>, where <i>c</i> is <tt>'b'</tt>, <tt>'c'</tt>, +<tt>'d'</tt>, <tt>'l'</tt>, <tt>'p'</tt>, <tt>'f'</tt>, or <tt>'s'</tt> for block special file, character special file, directory, +symbolic link, FIFO, regular file, or socket, respectively.</dd> +<dt><b>-links </b><i>n</i></dt> +<dd>The primary shall evaluate as true if the file has <i>n</i> links.</dd> +<dt><b>-user </b><i>uname</i></dt> +<dd>The primary shall evaluate as true if the file belongs to the user <i>uname.</i> If <i>uname</i> is a decimal integer and the +<a href="../functions/getpwnam.html"><i>getpwnam</i>()</a> (or equivalent) function does not return a valid user name, <i>uname</i> +shall be interpreted as a user ID.</dd> +<dt><b>-group </b><i>gname</i></dt> +<dd><br> +The primary shall evaluate as true if the file belongs to the group <i>gname</i>. If <i>gname</i> is a decimal integer and the +<a href="../functions/getgrnam.html"><i>getgrnam</i>()</a> (or equivalent) function does not return a valid group name, +<i>gname</i> shall be interpreted as a group ID.</dd> +<dt><b>-size </b><i>n</i><b>[c]</b></dt> +<dd>The primary shall evaluate as true if the file size in bytes, divided by 512 and rounded up to the next integer, is <i>n</i>. +If <i>n</i> is followed by the character <tt>'c'</tt>, the size shall be in bytes.</dd> +<dt><b>-atime </b><i>n</i></dt> +<dd>The primary shall evaluate as true if the file access time subtracted from the initialization time, divided by 86400 (with any +remainder discarded), is <i>n</i>.</dd> +<dt><b>-ctime </b><i>n</i></dt> +<dd>The primary shall evaluate as true if the time of last change of file status information subtracted from the initialization +time, divided by 86400 (with any remainder discarded), is <i>n</i>.</dd> +<dt><b>-mtime </b><i>n</i></dt> +<dd>The primary shall evaluate as true if the file modification time subtracted from the initialization time, divided by 86400 +(with any remainder discarded), is <i>n</i>.</dd> +<dt><b>-exec </b><i>utility_name </i><b>[</b><i>argument</i> ...<b>] ;</b></dt> +<dd></dd> +<dt><b>-exec </b><i>utility_name </i><b>[</b><i>argument</i> ...<b>] </b>{} +</dt> +<dd><br> +The end of the primary expression shall be punctuated by a <semicolon> or by a <plus-sign>. Only a <plus-sign> +that immediately follows an argument containing only the two characters <tt>"{}"</tt> shall punctuate the end of the primary +expression. Other uses of the <plus-sign> shall not be treated as special. +<p>If the primary expression is punctuated by a <semicolon>, the utility <i>utility_name</i> shall be invoked once for each +pathname and the primary shall evaluate as true if the utility returns a zero value as exit status. A <i>utility_name</i> or +<i>argument</i> containing only the two characters <tt>"{}"</tt> shall be replaced by the current pathname. If a +<i>utility_name</i> or <i>argument</i> string contains the two characters <tt>"{}"</tt>, but not just the two characters +<tt>"{}"</tt>, it is implementation-defined whether <i>find</i> replaces those two characters or uses the string without +change.</p> +<p>If the primary expression is punctuated by a <plus-sign>, the primary shall always evaluate as true, and the pathnames for +which the primary is evaluated shall be aggregated into sets. The utility <i>utility_name</i> shall be invoked once for each set of +aggregated pathnames. Each invocation shall begin after the last pathname in the set is aggregated, and shall be completed before +the <i>find</i> utility exits and before the first pathname in the next set (if any) is aggregated for this primary, but it is +otherwise unspecified whether the invocation occurs before, during, or after the evaluations of other primaries. If any invocation +returns a non-zero value as exit status, the <i>find</i> utility shall return a non-zero exit status. An argument containing only +the two characters <tt>"{}"</tt> shall be replaced by the set of aggregated pathnames, with each pathname passed as a separate +argument to the invoked utility in the same order that it was aggregated. The size of any set of two or more pathnames shall be +limited such that execution of the utility does not cause the system's {ARG_MAX} limit to be exceeded. If more than one argument +containing the two characters <tt>"{}"</tt> is present, the behavior is unspecified.</p> +<p>The current directory for the invocation of <i>utility_name</i> shall be the same as the current directory when the <i>find</i> +utility was started. If the <i>utility_name</i> names any of the special built-in utilities (see <a href= +"../utilities/V3_chap02.html#tag_19_15"><i>2.15 Special Built-In Utilities</i></a> ), the results are undefined.</p> +</dd> +<dt><b>-ok </b><i>utility_name </i><b>[</b><i>argument</i> ...<b>] ;</b></dt> +<dd><br> +The <b>-ok</b> primary shall be equivalent to <b>-exec</b>, except that the use of a <plus-sign> to punctuate the end of the +primary expression need not be supported, and <i>find</i> shall request affirmation of the invocation of <i>utility_name</i> using +the current file as an argument by writing to standard error as described in the STDERR section. If the response on standard input +is affirmative, the utility shall be invoked. Otherwise, the command shall not be invoked and the value of the <b>-ok</b> operand +shall be false.</dd> +<dt><b>-print</b></dt> +<dd>The primary shall always evaluate as true; it shall cause the current pathname to be written to standard output, followed by a +<newline>.</dd> +<dt><b>-print0</b></dt> +<dd>The primary shall always evaluate as true; it shall cause the current pathname to be written to standard output, followed by a +null byte.</dd> +<dt><b>-newer </b><i>file</i></dt> +<dd>The primary shall evaluate as true if the modification time of the current file is more recent than the modification time of +the file named by the pathname <i>file</i>. If <i>file</i> names a symbolic link, the modification time used shall be that of the +file referenced by the symbolic link if either the <b>-H</b> or <b>-L</b> option is specified; if neither <b>-H</b> nor <b>-L</b> +is specified, it is unspecified whether the modification time is that of the symbolic link itself or of the file referenced by the +symbolic link. In either case, if the referenced file does not exist, the modification time used shall be that of the link itself. +If <i>file</i> is a relative pathname, it shall be resolved relative to the current working directory that was inherited by +<i>find</i> when it was invoked.</dd> +<dt><b>-depth</b></dt> +<dd>The primary shall always evaluate as true; it shall cause descent of the directory hierarchy to be done so that all entries in +a directory are acted on before the directory itself. If a <b>-depth</b> primary is not specified, all entries in a directory shall +be acted on after the directory itself. If any <b>-depth</b> primary is specified, it shall apply to the entire expression even if +the <b>-depth</b> primary would not normally be evaluated.</dd> +</dl> +<p>The primaries can be combined using the following operators (in order of decreasing precedence):</p> +<dl compact> +<dd></dd> +<dt>( <i>expression</i> )</dt> +<dd>True if <i>expression</i> is true.</dd> +<dt><b>! </b><i>expression</i></dt> +<dd>Negation of a primary; the unary NOT operator.</dd> +<dt><i>expression </i><b>[-a] </b><i>expression</i></dt> +<dd><br> +Conjunction of primaries; the AND operator is implied by the juxtaposition of two primaries or made explicit by the optional +<b>-a</b> operator. The second expression shall not be evaluated if the first expression is false.</dd> +<dt><i>expression </i><b>-o </b><i>expression</i></dt> +<dd><br> +Alternation of primaries; the OR operator. The second expression shall not be evaluated if the first expression is true.</dd> +</dl> +<p>If no <i>expression</i> is present, <b>-print</b> shall be used as the expression. Otherwise, if the given expression does not +contain any of the primaries <b>-exec</b>, <b>-ok</b>, or <b>-print</b>, the given expression shall be effectively replaced by:</p> +<pre> +<tt>( </tt><i>given_expression</i><tt> ) -print +</tt></pre> +<p>The <b>-user</b>, <b>-group</b>, and <b>-newer</b> primaries each shall evaluate their respective arguments only once.</p> +<p>When the file type evaluated for the current file is a symbolic link, the results of evaluating the <b>-perm</b> primary are +implementation-defined.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_47_06" id="tag_20_47_06"></a>STDIN</h4> +<blockquote> +<p>If the <b>-ok</b> primary is used, the response shall be read from the standard input. An entire line shall be read as the +response. Otherwise, the standard input shall not be used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_47_07" id="tag_20_47_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_47_08" id="tag_20_47_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>find</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_COLLATE</i></dt> +<dd><br> +Determine the locale for the behavior of ranges, equivalence classes, and multi-character collating elements used in the pattern +matching notation for the <b>-name</b>, <b>-iname</b>, and <b>-path</b> primaries and in the extended regular expression defined +for the <b>yesexpr</b> locale keyword in the <i>LC_MESSAGES</i> category.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>This variable determines the locale for the interpretation of sequences of bytes of text data as characters (for example, +single-byte as opposed to multi-byte characters in arguments), the behavior of character classes within the pattern matching +notation used for the <b>-name</b>, <b>-iname</b>, and <b>-path</b> primaries, and the behavior of character classes within regular +expressions used in the extended regular expression defined for the <b>yesexpr</b> locale keyword in the <i>LC_MESSAGES</i> +category.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale used to process affirmative responses, and the locale used to affect the format and contents of diagnostic +messages and prompts written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>PATH</i></dt> +<dd>Determine the location of the <i>utility_name</i> for the <b>-exec</b> and <b>-ok</b> primaries, as described in XBD <a href= +"../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> .</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_47_09" id="tag_20_47_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_47_10" id="tag_20_47_10"></a>STDOUT</h4> +<blockquote> +<p>The <b>-print</b> primary shall cause the current pathname to be written to standard output. The format shall be:</p> +<pre> +<tt>"%s\n", <</tt><i>path</i><tt>> +</tt></pre> +<p>The <b>-print0</b> primary shall cause the current pathname to be written to standard output, followed by a null byte.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_47_11" id="tag_20_47_11"></a>STDERR</h4> +<blockquote> +<p>The <b>-ok</b> primary shall write a prompt to standard error containing at least the <i>utility_name</i> to be invoked and the +current pathname. In the POSIX locale, the last non-<blank> in the prompt shall be <tt>'?'</tt>. The exact format used is +unspecified.</p> +<p>Otherwise, the standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_47_12" id="tag_20_47_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_47_13" id="tag_20_47_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_47_14" id="tag_20_47_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>All <i>path</i> operands were traversed successfully, the output (if any) specified in STDOUT was successfully written to +standard output, and all commands (if any) executed using the <b>-exec</b> primary punctuated by a <plus-sign> exited with +exit status 0.</dd> +<dt>>0</dt> +<dd>A command executed using the <b>-exec</b> primary punctuated by a <plus-sign> exited with non-zero status, or an error +occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_47_15" id="tag_20_47_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_47_16" id="tag_20_47_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>When used in operands, pattern matching notation, <semicolon>, <left-parenthesis>, and <right-parenthesis> +characters are special to the shell and must be quoted (see <a href="../utilities/V3_chap02.html#tag_19_02"><i>2.2 Quoting</i></a> +).</p> +<p>When restricting the search to files on one file system, it can sometimes be desirable for the crossing points themselves to be +acted on and sometimes for them not to be acted on. (Crossing points are mount points and, if the <b>-L</b> option is specified, +symbolic links to directories on other file systems.) The <b>-xdev</b> primary acts on them and the <b>-mount</b> primary does not. +However, <b>-mount</b> also does not act on symbolic links to non-directory files on other file systems (if <b>-L</b> is +specified). If there is a need for an application to exclude crossing points but include symbolic links to non-directory files on +other file systems, this can be achieved by using two <i>find</i> commands as follows:</p> +<pre> +<tt>find -L dir -mount -type d -print +find -L dir -xdev ! -type d -print +</tt></pre> +<p>(in a subshell whose output is piped to <a href="../utilities/sort.html"><i>sort</i></a>, if the order matters).</p> +<p>If both <b>-mount</b> and <b>-xdev</b> are specified, <i>find</i> obeys both primaries but the end result is the same as if +<b>-xdev</b> were not specified.</p> +<p>The bit that is traditionally used for sticky (historically 01000) is specified in the <b>-perm</b> primary using the octal +number argument form. Since this bit is not defined by this volume of POSIX.1-2024, applications must not assume that it actually +refers to the traditional sticky bit.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_47_17" id="tag_20_47_17"></a>EXAMPLES</h4> +<blockquote> +<ol> +<li> +<p>The following commands are equivalent:</p> +<pre> +<tt>find . +find . -print +</tt></pre> +<p>They both write out the entire directory hierarchy from the current directory.</p> +<p>With this output format, if any pathnames include <newline> characters, it is not possible to tell where each pathname +begins and ends. This problem can be avoided by omitting such pathnames:</p> +<pre> +<tt>LC_ALL=POSIX find . -name $'*\n*' -prune -o -print +</tt></pre> +<p>or by using a sentinel in the pathname that <i>find</i> would never otherwise produce, such as:</p> +<pre> +<tt>find .//. -print +</tt></pre> +<p>or by using <b>-print0</b> instead of <b>-print</b> and processing the output with a utility that can accept null-terminated +pathnames as input, such as <a href="../utilities/xargs.html"><i>xargs</i></a> with the <b>-0</b> option or <a href= +"../utilities/read.html"><i>read</i></a> with <b>-d</b> <tt>""</tt>, for example:</p> +<pre> +<tt>find . -print0 | while IFS= read -rd "" file +do + # process "$file" +done +</tt></pre> +<p>It should be noted that using <i>find</i> with <b>-print0</b> to pipe input to <a href= +"../utilities/xargs.html"><i>xargs</i></a> <b>-r0</b> is less safe than using <i>find</i> with <b>-exec</b> because if <i>find</i> +<b>-print0</b> is terminated after it has written a partial pathname, the partial pathname may be processed as if it was a complete +pathname.</p> +</li> +<li> +<p>The following command:</p> +<pre> +<tt>find / \( -name tmp -o -name '*.xx' \) ! -type d -mtime +7 \ + -exec rm {} + +</tt></pre> +<p>removes all files named <b>tmp</b> or ending in <b>.xx</b> that have not been modified for more than seven (that is, eight or +more) 24-hour periods.</p> +</li> +<li> +<p>The following command:</p> +<pre> +<tt>find . -perm -o+w,+s +</tt></pre> +<p>prints (<b>-print</b> is assumed) the names of all files in or below the current directory, with all of the file permission bits +S_ISUID, S_ISGID, and S_IWOTH set, regardless of the value of the file creation mask. (Note that the file creation mask is only +specified for the file permission bits, and not S_ISUID, S_ISGID or S_ISVTX.)</p> +</li> +<li> +<p>The following command:</p> +<pre> +<tt>find . -perm -+w +</tt></pre> +<p>prints (<b>-print</b> is assumed) the names of all files in or below the current directory, with S_IWUSR set if the file +creation mask does not have S_IWUSR set (otherwise the S_IWUSR bit is ignored), S_IWGRP set if the file creation mask does not have +S_IWGRP set (otherwise S_IWGRP is ignored), and S_IWOTH set if the file creation mask does not have S_IWOTH set (otherwise S_IWOTH +is ignored).</p> +</li> +<li> +<p>The following command:</p> +<pre> +<tt>find . -name SCCS -prune -o -print +</tt></pre> +<p>recursively prints pathnames of all files in the current directory and below, but skips directories named SCCS and files in +them.</p> +</li> +<li> +<p>The following command:</p> +<pre> +<tt>find . -print -name SCCS -prune +</tt></pre> +<p>behaves as in the previous example, but prints the names of the SCCS directories.</p> +</li> +<li> +<p>The following command is roughly equivalent to the <b>-nt</b> extension to <a href="../utilities/test.html"><i>test</i></a>:</p> +<pre> +<tt>if [ -n "$(find file1 -prune -newer file2)" ]; then + printf %s\\n "file1 is newer than file2" +fi +</tt></pre></li> +<li> +<p>The descriptions of <b>-atime</b>, <b>-ctime</b>, and <b>-mtime</b> use the terminology <i>n</i> "86400 second periods +(days)". For example, a file accessed at 23:59 is selected by:</p> +<pre> +<tt>find . -atime -1 -print +</tt></pre> +<p>at 00:01 the next day (less than 24 hours later, not more than one day ago); the midnight boundary between days has no effect on +the 24-hour calculation.</p> +</li> +<li> +<p>The following command:</p> +<pre> +<tt>find . ! -name . -prune -name '*.old' -exec \ + sh -c 'mv "$@" ../old/' sh {} + +</tt></pre> +<p>performs the same task as:</p> +<pre> +<tt>mv ./*.old ./.old ./.*.old ../old/ +</tt></pre> +<p>while avoiding an "Argument list too long" error if there are a large number of files ending with <b>.old</b> and without +running <a href="../utilities/mv.html"><i>mv</i></a> if there are no such files (and avoiding "No such file or directory" errors +if <b>./.old</b> does not exist or no files match <b>./*.old</b> or <b>./.*.old</b>).</p> +<p>The alternative:</p> +<pre> +<tt>find . ! -name . -prune -name '*.old' -exec mv {} ../old/ \; +</tt></pre> +<p>is less efficient if there are many files to move because it executes one <a href="../utilities/mv.html"><i>mv</i></a> command +per file.</p> +</li> +<li> +<p>On systems configured to mount removable media on directories under <b>/media</b>, the following command searches the file +hierarchy for files of size larger than 100000 KiB without searching any mounted removable media:</p> +<pre> +<tt>find / -path /media -prune -o -size +200000 -print +</tt></pre></li> +<li> +<p>Except for the root directory, and <tt>"//"</tt> on implementations where <tt>"//"</tt> does not refer to the root directory, no +pattern given to <b>-name</b> will match a <slash>, because trailing <slash> characters are ignored when computing the +basename of the file under evaluation. Given two empty directories named <b>foo</b> and <b>bar</b>, the following command:</p> +<pre> +<tt>find foo/// bar/// -name foo -o -name 'bar?*' +</tt></pre> +<p>prints only the line <tt>"foo///"</tt>.</p> +</li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_47_18" id="tag_20_47_18"></a>RATIONALE</h4> +<blockquote> +<p>The <b>-a</b> operator was retained as an optional operator for compatibility with historical shell scripts, even though it is +redundant with expression concatenation.</p> +<p>The descriptions of the <tt>'-'</tt> modifier on the <i>mode</i> and <i>onum</i> arguments to the <b>-perm</b> primary agree +with historical practice on BSD and System V implementations. System V and BSD documentation both describe it in terms of checking +additional bits; in fact, it uses the same bits, but checks for having at least all of the matching bits set instead of having +exactly the matching bits set.</p> +<p>The exact format of the interactive prompts is unspecified. Only the general nature of the contents of prompts are specified +because:</p> +<ul> +<li> +<p>Implementations may desire more descriptive prompts than those used on historical implementations.</p> +</li> +<li> +<p>Since the historical prompt strings do not terminate with <newline> characters, there is no portable way for another +program to interact with the prompts of this utility via pipes.</p> +</li> +</ul> +<p>Therefore, an application using this prompting option relies on the system to provide the most suitable dialog directly with the +user, based on the general guidelines specified.</p> +<p>The <b>-size</b> operand refers to the size of a file, rather than the number of blocks it may occupy in the file system. The +intent is that the <i>st_size</i> field defined in the System Interfaces volume of POSIX.1-2024 should be used, not the +<i>st_blocks</i> found in historical implementations. There are at least two reasons for this:</p> +<ol> +<li> +<p>In both System V and BSD, <i>find</i> only uses <i>st_size</i> in size calculations for the operands specified by this volume of +POSIX.1-2024. (BSD uses <i>st_blocks</i> only when processing the <b>-ls</b> primary.)</p> +</li> +<li> +<p>Users usually think of file size in terms of bytes, which is also the unit used by the <a href= +"../utilities/ls.html"><i>ls</i></a> utility for the output from the <b>-l</b> option. (In both System V and BSD, <a href= +"../utilities/ls.html"><i>ls</i></a> uses <i>st_size</i> for the <b>-l</b> option size field and uses <i>st_blocks</i> for the +<a href="../utilities/ls.html"><i>ls</i></a> <b>-s</b> calculations. This volume of POSIX.1-2024 does not specify <a href= +"../utilities/ls.html"><i>ls</i></a> <b>-s</b>.)</p> +</li> +</ol> +<p>The descriptions of <b>-atime</b>, <b>-ctime</b>, and <b>-mtime</b> were changed from the SVID description of <i>n</i> "days" +to <i>n</i> being the result of the integer division of the time difference in seconds by 86400. The description is also different +in terms of the exact timeframe for the <i>n</i> case (<i>versus</i> the <i>+n</i> or <i>-n</i>), but it matches all known +historical implementations. It refers to one 86400 second period in the past, not any time from the beginning of that period to the +current time. For example, <b>-atime</b> 2 is true if the file was accessed any time in the period from 72 hours to 48 hours +ago.</p> +<p>Historical implementations do not modify <tt>"{}"</tt> when it appears as a substring of an <b>-exec</b> or <b>-ok</b> +<i>utility_name</i> or argument string. There have been numerous user requests for this extension, so this volume of POSIX.1-2024 +allows the desired behavior. At least one recent implementation does support this feature, but encountered several problems in +managing memory allocation and dealing with multiple occurrences of <tt>"{}"</tt> in a string while it was being developed, so it +is not yet required behavior.</p> +<p>Assuming the presence of <b>-print</b> was added to correct a historical pitfall that plagues novice users, it is entirely +upwards-compatible from the historical System V <i>find</i> utility. In its simplest form (<a href= +"../utilities/find.html"><i>find</i></a> <i>directory</i>), it could be confused with the historical BSD fast <i>find</i>. The BSD +developers agreed that adding <b>-print</b> as a default expression was the correct decision and have added the fast <i>find</i> +functionality within a new utility called <i>locate</i>.</p> +<p>Historically, the <b>-L</b> option was implemented using the primary <b>-follow</b>. The <b>-H</b> and <b>-L</b> options were +added for two reasons. First, they offer a finer granularity of control and consistency with other programs that walk file +hierarchies. Second, the <b>-follow</b> primary always evaluated to true. As they were historically really global variables that +took effect before the traversal began, some valid expressions had unexpected results. An example is the expression <b>-print</b> +<b>-o</b> <b>-follow</b>. Because <b>-print</b> always evaluates to true, the standard order of evaluation implies that +<b>-follow</b> would never be evaluated. This was never the case. Historical practice for the <b>-follow</b> primary, however, is +not consistent. Some implementations always follow symbolic links on the command line whether <b>-follow</b> is specified or not. +Others follow symbolic links on the command line only if <b>-follow</b> is specified. Both behaviors are provided by the <b>-H</b> +and <b>-L</b> options, but scripts using the current <b>-follow</b> primary would be broken if the <b>-follow</b> option is +specified to work either way.</p> +<p>Since the <b>-L</b> option resolves all symbolic links and the <b>-type</b> <i>l</i> primary is true for symbolic links that +still exist after symbolic links have been resolved, the command:</p> +<pre> +<tt>find -L . -type l +</tt></pre> +<p>prints a list of symbolic links reachable from the current directory that do not resolve to accessible files.</p> +<p>A feature of SVR4's <i>find</i> utility was the <b>-exec</b> primary's <b>+</b> terminator. This allowed filenames containing +special characters (especially <newline> characters) to be grouped together without the problems that occur if such filenames +are piped to <a href="../utilities/xargs.html"><i>xargs</i></a>.</p> +<p>The <tt>"-exec ... {} +"</tt> syntax adopted was a result of IEEE PASC Interpretation 1003.2 #210. It should be noted that this +is an incompatible change to IEEE Std 1003.2-1992. For example, the following command printed all files with a +<tt>'-'</tt> after their name if they are regular files, and a <tt>'+'</tt> otherwise:</p> +<pre> +<tt>find / -type f -exec echo {} - ';' -o -exec echo {} + ';' +</tt></pre> +<p>The change invalidates usage like this. Even though the previous standard stated that this usage would work, in practice many +did not support it and the standard developers felt it better to now state that this was not allowable.</p> +<p>Historically, many <i>find</i> implementations supported <b>-mount</b> and <b>-xdev</b> as synonymous primaries and earlier +versions of this standard only required support for <b>-xdev</b>. However, the behavior of <i>find</i> with <b>-xdev</b> differed +from that of the <a href="../functions/nftw.html"><i>nftw</i>()</a> function with FTW_MOUNT as regards whether the mount point +itself was included or excluded. Therefore the standard now requires support for both primaries with slightly differing behaviors: +<b>-mount</b> behaves in the manner of <a href="../functions/nftw.html"><i>nftw</i>()</a> with the traditional FTW_MOUNT flag, and +<b>-xdev</b> in the manner of <a href="../functions/nftw.html"><i>nftw</i>()</a> with a new FTW_XDEV flag.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_47_19" id="tag_20_47_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_47_20" id="tag_20_47_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19_02"><i>2.2 Quoting</i></a> , <a href="../utilities/V3_chap02.html#tag_19_14"><i>2.14 +Pattern Matching Notation</i></a> , <a href="../utilities/V3_chap02.html#tag_19_15"><i>2.15 Special Built-In Utilities</i></a> , +<a href="../utilities/chmod.html#tag_20_17"><i>chmod</i></a> , <a href="../utilities/mv.html#"><i>mv</i></a> , <a href= +"../utilities/pax.html#"><i>pax</i></a> , <a href="../utilities/sh.html#"><i>sh</i></a> , <a href= +"../utilities/test.html#"><i>test</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/fstatat.html#"><i>fstatat</i></a> , <a href="../functions/getgrgid.html#"><i>getgrgid</i></a> , +<a href="../functions/getpwuid.html#"><i>getpwuid</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_47_21" id="tag_20_47_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_47_22" id="tag_20_47_22"></a>Issue 5</h4> +<blockquote> +<p>The FUTURE DIRECTIONS section is added.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_47_23" id="tag_20_47_23"></a>Issue 6</h4> +<blockquote> +<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p> +<ul> +<li> +<p>The <b>-perm [-]</b><i>onum</i> primary is supported.</p> +</li> +</ul> +<p>The <i>find</i> utility is aligned with the IEEE P1003.2b draft standard, to include processing of symbolic links and +changes to the description of the <b>atime</b>, <b>ctime</b>, and <b>mtime</b> operands.</p> +<p>IEEE PASC Interpretation 1003.2 #210 is applied, extending the <b>-exec</b> operand.</p> +<p>IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/13 is applied, updating the RATIONALE section to be consistent +with the normative text.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_47_24" id="tag_20_47_24"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #126 is applied, changing the description of the <i>LC_MESSAGES</i> environment +variable.</p> +<p>Austin Group Interpretation 1003.1-2001 #127 is applied, rephrasing the description of the <b>-exec</b> primary to be +"immediately follows".</p> +<p>Austin Group Interpretation 1003.1-2001 #185 is applied, clarifying the requirements for the <b>-H</b> and <b>-L</b> +options.</p> +<p>Austin Group Interpretation 1003.1-2001 #186 is applied, clarifying the requirements for the evaluation of <i>path</i> +operands.</p> +<p>Austin Group Interpretation 1003.1-2001 #195 is applied, clarifying the interpretation of the first operand.</p> +<p>SD5-XCU-ERN-48 is applied, clarifying the <b>-L</b> option in the case that the referenced file does not exist.</p> +<p>SD5-XCU-ERN-89 is applied, updating the OPERANDS section.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>SD5-XCU-ERN-117 is applied, clarifying the <b>-perm</b> operand.</p> +<p>SD5-XCU-ERN-122 is applied, adding a new EXAMPLE.</p> +<p>The description of the <b>-name</b> primary is revised and the <b>-path</b> primary is added (with a new example).</p> +<p>POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0086 [365], XCU/TC1-2008/0087 [310], XCU/TC1-2008/0088 [309,310,430], +XCU/TC1-2008/0089 [235], and XCU/TC1-2008/0090 [445] are applied.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0099 [584], XCU/TC2-2008/0100 [584], and XCU/TC2-2008/0101 [584] are +applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_47_25" id="tag_20_47_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 243 is applied, adding the <b>-print0</b> primary.</p> +<p>Austin Group Defect 251 is applied, encouraging implementations to report an error if a utility is directed to display a +pathname that contains any bytes that have the encoded value of a <newline> character when <newline> is a terminator or +separator in the output format being used.</p> +<p>Austin Group Defect 1031 is applied, adding the <b>-iname</b> primary.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1133 is applied, adding the <b>-mount</b> primary.</p> +<p>Austin Group Defects 1259 and 1777 are applied, changing the EXAMPLES section.</p> +<p>Austin Group Defect 1392 is applied, changing the effect of the file creation mask on the <i>mode</i> argument for the +<b>-perm</b> primary to be consistent with <a href="../utilities/chmod.html"><i>chmod</i></a>.</p> +<p>Austin Group Defect 1501 is applied, changing the EXIT STATUS section.</p> +<p>Austin Group Defect 1553 is applied, changing the ENVIRONMENT VARIABLES section.</p> +<p>Austin Group Defect 1554 is applied, changing the RATIONALE section.</p> +<p>Austin Group Defect 1606 is applied, clarifying that if <i>find</i> detects an infinite loop and recovers its position, the +final exit status is non-zero.</p> +<p>Austin Group Defect 1776 is applied, clarifying how symbolic links are handled by the <b>-newer</b> <i>file</i> primary.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/file.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/fold.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/fold.html b/bdd/fold.html @@ -0,0 +1,248 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>fold</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/find.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/fuser.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="fold" id="fold"></a> <a name="tag_20_48" id="tag_20_48"></a><!-- fold --> +<h4 class="mansect"><a name="tag_20_48_01" id="tag_20_48_01"></a>NAME</h4> +<blockquote>fold — filter for folding lines</blockquote> +<h4 class="mansect"><a name="tag_20_48_02" id="tag_20_48_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>fold</tt> <b>[</b><tt>-bs</tt><b>] [</b><tt>-w</tt> <i>width</i><b>] [</b><i>file</i><tt>...</tt><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_48_03" id="tag_20_48_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>fold</i> utility is a filter that shall fold lines from its input files, breaking the lines to have a maximum of +<i>width</i> column positions (or bytes, if the <b>-b</b> option is specified). Lines shall be broken by the insertion of a +<newline> such that each output line (referred to later in this section as a <i>segment</i>) is the maximum width possible +that does not exceed the specified number of column positions (or bytes). A line shall not be broken in the middle of a character. +The behavior is undefined if <i>width</i> is less than the number of columns any single character in the input would occupy.</p> +<p>If the <carriage-return>, <backspace>, or <tab> characters are encountered in the input, and the <b>-b</b> +option is not specified, they shall be treated specially:</p> +<dl compact> +<dd></dd> +<dt><backspace></dt> +<dd>The current count of line width shall be decremented by one, although the count never shall become negative. The <i>fold</i> +utility shall not insert a <newline> immediately before or after any <backspace>, unless the following character has a +width greater than 1 and would cause the line width to exceed <i>width</i>.</dd> +<dt><carriage-return></dt> +<dd><br> +The current count of line width shall be set to zero. The <i>fold</i> utility shall not insert a <newline> immediately before +or after any <carriage-return>.</dd> +<dt><tab></dt> +<dd>Each <tab> encountered shall advance the column position pointer to the next tab stop. Tab stops shall be at each column +position <i>n</i> such that <i>n</i> modulo 8 equals 1.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_48_04" id="tag_20_48_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>fold</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-b</b></dt> +<dd>Count <i>width</i> in bytes rather than column positions.</dd> +<dt><b>-s</b></dt> +<dd>If a segment of a line contains a <blank> within the first <i>width</i> column positions (or bytes), break the line after +the last such <blank> meeting the width constraints. If there is no <blank> meeting the requirements, the <b>-s</b> +option shall have no effect for that output segment of the input line.</dd> +<dt><b>-w </b><i>width</i></dt> +<dd>Specify the maximum line length, in column positions (or bytes if <b>-b</b> is specified). The results are unspecified if +<i>width</i> is not a positive decimal number. The default value shall be 80.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_48_05" id="tag_20_48_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of a text file to be folded. If no <i>file</i> operands are specified, the standard input shall be used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_48_06" id="tag_20_48_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be used if no <i>file</i> operands are specified, and shall be used if a <i>file</i> operand is +<tt>'-'</tt> and the implementation treats the <tt>'-'</tt> as meaning standard input. Otherwise, the standard input shall not be +used. See the INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_48_07" id="tag_20_48_07"></a>INPUT FILES</h4> +<blockquote> +<p>If the <b>-b</b> option is specified, the input files shall be text files except that the lines are not limited to {LINE_MAX} +bytes in length. If the <b>-b</b> option is not specified, the input files shall be text files.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_48_08" id="tag_20_48_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>fold</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files), and for the determination of the width in column positions each +character would occupy on a constant-width font output device.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_48_09" id="tag_20_48_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_48_10" id="tag_20_48_10"></a>STDOUT</h4> +<blockquote> +<p>The standard output shall be a file containing a sequence of characters whose order shall be preserved from the input files, +possibly with inserted <newline> characters.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_48_11" id="tag_20_48_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_48_12" id="tag_20_48_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_48_13" id="tag_20_48_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_48_14" id="tag_20_48_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>All input files were processed successfully.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_48_15" id="tag_20_48_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_48_16" id="tag_20_48_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The <a href="../utilities/cut.html"><i>cut</i></a> and <i>fold</i> utilities can be used to create text files out of files with +arbitrary line lengths. The <a href="../utilities/cut.html"><i>cut</i></a> utility should be used when the number of lines (or +records) needs to remain constant. The <i>fold</i> utility should be used when the contents of long lines need to be kept +contiguous.</p> +<p>The <i>fold</i> utility is frequently used to send text files to printers that truncate, rather than fold, lines wider than the +printer is able to print (usually 80 or 132 column positions).</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_48_17" id="tag_20_48_17"></a>EXAMPLES</h4> +<blockquote> +<p>An example invocation that submits a file of possibly long lines to the printer (under the assumption that the user knows the +line width of the printer to be assigned by <a href="../utilities/lp.html"><i>lp</i></a>):</p> +<pre> +<tt>fold -w 132 bigfile | lp +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_48_18" id="tag_20_48_18"></a>RATIONALE</h4> +<blockquote> +<p>Although terminal input in canonical processing mode requires the erase character (frequently set to <backspace>) to erase +the previous character (not byte or column position), terminal output is not buffered and is extremely difficult, if not +impossible, to parse correctly; the interpretation depends entirely on the physical device that actually displays/prints/stores the +output. In all known internationalized implementations, the utilities producing output for mixed column-width output assume that a +<backspace> character backs up one column position and outputs enough <backspace> characters to return to the start of +the character when <backspace> is used to provide local line motions to support underlining and emboldening operations. Since +<i>fold</i> without the <b>-b</b> option is dealing with these same constraints, <backspace> is always treated as backing up +one column position rather than backing up one character.</p> +<p>Historical versions of the <i>fold</i> utility assumed 1 byte was one character and occupied one column position when written +out. This is no longer always true. Since the most common usage of <i>fold</i> is believed to be folding long lines for output to +limited-length output devices, this capability was preserved as the default case. The <b>-b</b> option was added so that +applications could <i>fold</i> files with arbitrary length lines into text files that could then be processed by the standard +utilities. Note that although the width for the <b>-b</b> option is in bytes, a line is never split in the middle of a character. +(It is unspecified what happens if a width is specified that is too small to hold a single character found in the input followed by +a <newline>.)</p> +<p>The tab stops are hardcoded to be every eighth column to meet historical practice. No new method of specifying other tab stops +was invented.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_48_19" id="tag_20_48_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_48_20" id="tag_20_48_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/cut.html#"><i>cut</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_48_21" id="tag_20_48_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_48_22" id="tag_20_48_22"></a>Issue 6</h4> +<blockquote> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_48_23" id="tag_20_48_23"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #092 is applied.<br></p> +<p>Austin Group Interpretation 1003.1-2001 #204 is applied, updating the DESCRIPTION to clarify when a <newline> can be +inserted before or after a <backspace>.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_48_24" id="tag_20_48_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/find.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/fuser.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/fuser.html b/bdd/fuser.html @@ -0,0 +1,277 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>fuser</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/fold.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/gencat.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="fuser" id="fuser"></a> <a name="tag_20_49" id="tag_20_49"></a><!-- fuser --> +<h4 class="mansect"><a name="tag_20_49_01" id="tag_20_49_01"></a>NAME</h4> +<blockquote>fuser — list process IDs of all processes that are using one or more named files</blockquote> +<h4 class="mansect"><a name="tag_20_49_02" id="tag_20_49_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> fuser</tt> <b>[</b><tt>-cfu</tt><b>]</b> <i>file</i><tt>... <img src="../images/opt-end.gif" alt= +"[Option End]" border="0"></tt></code></div> +</blockquote> +<h4 class="mansect"><a name="tag_20_49_03" id="tag_20_49_03"></a>DESCRIPTION</h4> +<blockquote> +<p>For each <i>file</i> operand, in order, <i>fuser</i> shall write one line of output, some of it to standard output, and the rest +to standard error, giving information about processes running on the local system that are using the file. A process shall be +considered to be using a file if it has at least one open file descriptor associated with the file or if the file is a directory +that is the current working directory or the root directory for the process, and may be considered to be using a file for other +implementation-dependent reasons. If <i>file</i> names a block special device that contains a mounted file system, and the +<b>-f</b> option is not specified, any processes using any file on that mounted file system and any processes that are using the +device file itself shall be listed.</p> +<p>Any output for processes running on remote systems that are using a named file is unspecified.</p> +<p>A user may need appropriate privileges to invoke the <i>fuser</i> utility.</p> +<p>When standard output and standard error are directed to the same file, the output for each <i>file</i> operand shall be +interleaved so that it is written to the file in the following order:</p> +<ul> +<li> +<p>On standard error, a pathname for the file, immediately followed by a <colon> and zero or more <blank> characters. +The pathname shall be either the file operand (unaltered) or the pathname that would result from a successful call to the <a href= +"../functions/realpath.html"><i>realpath</i>()</a> function, defined in the System Interfaces volume of POSIX.1-2024, with the +<i>file</i> operand as its <i>file_name</i> argument.</p> +</li> +<li> +<p>For each process using the file:</p> +<ul> +<li> +<p>On standard output, the process ID in the format:</p> +<pre> +<tt>" %1d", <</tt><i>process ID</i><tt>> +</tt></pre></li> +<li> +<p>On standard error, information about the file's use by the process, in the following format:</p> +<pre> +<tt>"%s", <</tt><i>use chars</i><tt>> +</tt></pre> +<p>if the <b>-u</b> option is not specified, or in the following format:</p> +<pre> +<tt>"%s(%s)", <</tt><i>use chars</i><tt>>, <</tt><i>user name</i><tt>> +</tt></pre> +<p>if the <b>-u</b> option is specified, where <<i>use chars</i>> is a string of zero or more characters indicating the use +of the file and <<i>user name</i>> is the user name corresponding to the real user ID of the process or, if the user name +cannot be resolved from the real user ID of the process, the real user ID of the process in decimal. The value of <<i>use +chars</i>> shall include the character <tt>'c'</tt> if the process is using the file as its current directory and the character +<tt>'r'</tt> if the process is using the file as its root directory; implementations may include other alphabetic characters to +indicate other uses of the file.</p> +</li> +</ul> +</li> +<li> +<p>On standard error, a <newline> character.</p> +</li> +</ul> +<p>When standard output and standard error are not directed to the same file, the data written to each shall be as described above +but the ordering of writes to standard output relative to writes to standard error is unspecified. For example, <i>fuser</i> might +first write the information for all file operands to standard error and then write all of the process IDs to standard output.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_49_04" id="tag_20_49_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>fuser</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-c</b></dt> +<dd>If a <i>file</i> operand names a directory that is the mount point of a mounted file system, all processes using any file on +that file system shall be listed as if they were using the named directory. The behavior for any <i>file</i> operand that names an +existing file that is not the mount point of a mounted file system is unspecified.</dd> +<dt><b>-f</b></dt> +<dd>The report shall be only for the named files.</dd> +<dt><b>-u</b></dt> +<dd>The user name, in parentheses, associated with each process ID written to standard output shall be written to standard +error.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_49_05" id="tag_20_49_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of a file for which the processes using the file are to be reported.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_49_06" id="tag_20_49_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_49_07" id="tag_20_49_07"></a>INPUT FILES</h4> +<blockquote> +<p>The user database.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_49_08" id="tag_20_49_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>fuser</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd>Determine the location of messages objects and message catalogs.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_49_09" id="tag_20_49_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_49_10" id="tag_20_49_10"></a>STDOUT</h4> +<blockquote> +<p>See DESCRIPTION.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_49_11" id="tag_20_49_11"></a>STDERR</h4> +<blockquote> +<p>The <i>fuser</i> utility shall write diagnostic messages to standard error.</p> +<p>The <i>fuser</i> utility also shall write information to standard error as specified in the DESCRIPTION section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_49_12" id="tag_20_49_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_49_13" id="tag_20_49_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_49_14" id="tag_20_49_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_49_15" id="tag_20_49_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_49_16" id="tag_20_49_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Things can change while <i>fuser</i> is running; the snapshot it gives is only true for an instant, and might not be accurate by +the time it is displayed.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_49_17" id="tag_20_49_17"></a>EXAMPLES</h4> +<blockquote> +<p>The command:</p> +<pre> +<tt>fuser -fu . +</tt></pre> +<p>writes to standard output the process IDs of processes that are using the current directory and writes to standard error an +indication of how those processes are using the directory and the user names associated with the processes that are using the +current directory.</p> +<pre> +<tt>fuser -c <</tt><i>mount point</i><tt>> +</tt></pre> +<p>writes to standard output the process IDs of processes that are using any file in the file system which is mounted on +<<i>mount point</i>> and writes to standard error an indication of how those processes are using the files.</p> +<pre> +<tt>fuser <</tt><i>mount point</i><tt>> +</tt></pre> +<p>writes to standard output the process IDs of processes that are using the file which is named by <<i>mount point</i>> and +writes to standard error an indication of how those processes are using the file.</p> +<pre> +<tt>fuser <</tt><i>mounted block device</i><tt>> +</tt></pre> +<p>writes to standard output the process IDs of processes that are using any file on the mounted file system contained by +<<i>mounted block device</i>> and of processes that are using the device file <<i>mounted block device</i>> itself, and +writes to standard error an indication of how those processes are using the files.</p> +<pre> +<tt>fuser -f <</tt><i>mounted block device</i><tt>> +</tt></pre> +<p>writes to standard output the process IDs of processes that are using the file <<i>mounted block device</i>> itself and +writes to standard error an indication of how those processes are using the file.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_49_18" id="tag_20_49_18"></a>RATIONALE</h4> +<blockquote> +<p>The definition of the <i>fuser</i> utility follows existing practice.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_49_19" id="tag_20_49_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_49_20" id="tag_20_49_20"></a>SEE ALSO</h4> +<blockquote> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_49_21" id="tag_20_49_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 5.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_49_22" id="tag_20_49_22"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-90 is applied, updating the EXAMPLES section.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_49_23" id="tag_20_49_23"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to report an error if a utility is directed to display a +pathname that contains any bytes that have the encoded value of a <newline> character when <newline> is a terminator or +separator in the output format being used.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1746 is applied, clarifying the output written to standard output and standard error.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/fold.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/gencat.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/gencat.html b/bdd/gencat.html @@ -0,0 +1,343 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>gencat</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/fuser.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/get.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="gencat" id="gencat"></a> <a name="tag_20_50" id="tag_20_50"></a><!-- gencat --> +<h4 class="mansect"><a name="tag_20_50_01" id="tag_20_50_01"></a>NAME</h4> +<blockquote>gencat — generate a formatted message catalog</blockquote> +<h4 class="mansect"><a name="tag_20_50_02" id="tag_20_50_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>gencat</tt> <i>catfile msgfile</i><tt>...</tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_50_03" id="tag_20_50_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>gencat</i> utility shall merge the message text source file <i>msgfile</i> into a formatted message catalog +<i>catfile</i>. The file <i>catfile</i> shall be created if it does not already exist. If <i>catfile</i> does exist, its messages +shall be included in the new <i>catfile</i>. If set and message numbers collide, the new message text defined in <i>msgfile</i> +shall replace the old message text currently contained in <i>catfile</i>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_50_04" id="tag_20_50_04"></a>OPTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_50_05" id="tag_20_50_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>catfile</i></dt> +<dd>A pathname of the formatted message catalog. If <tt>'-'</tt> is specified, standard output shall be used. The format of the +message catalog produced is unspecified.</dd> +<dt><i>msgfile</i></dt> +<dd>A pathname of a message text source file. If <tt>'-'</tt> is specified for an instance of <i>msgfile</i>, standard input shall +be used. The format of message text source files is defined in the EXTENDED DESCRIPTION section.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_50_06" id="tag_20_50_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall not be used unless a <i>msgfile</i> operand is specified as <tt>'-'</tt>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_50_07" id="tag_20_50_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files shall be text files.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_50_08" id="tag_20_50_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>gencat</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_50_09" id="tag_20_50_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_50_10" id="tag_20_50_10"></a>STDOUT</h4> +<blockquote> +<p>The standard output shall not be used unless the <i>catfile</i> operand is specified as <tt>'-'</tt>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_50_11" id="tag_20_50_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_50_12" id="tag_20_50_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_50_13" id="tag_20_50_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>The content of a message text file shall be in the format defined as follows. Note that the fields of a message text source line +are separated by a single <blank> character. Any other <blank> characters are considered to be part of the subsequent +field.</p> +<dl compact> +<dd></dd> +<dt><b>$set </b><i>n comment</i></dt> +<dd><br> +This line specifies the set identifier of the following messages until the next <b>$set</b> or end-of-file appears. The <i>n</i> +denotes the set identifier, which is defined as a number in the range [1, {NL_SETMAX}] (see the <a href= +"../basedefs/limits.h.html"><i><limits.h></i></a> header defined in the Base Definitions volume of POSIX.1-2024). The +application shall ensure that set identifiers are presented in ascending order within a single source file, but need not be +contiguous. Any string following the set identifier shall be treated as a comment. If no <b>$set</b> directive is specified in a +message text source file, all messages shall be located in an implementation-defined default message set NL_SETD (see the <a href= +"../basedefs/nl_types.h.html"><i><nl_types.h></i></a> header defined in the Base Definitions volume of POSIX.1-2024).</dd> +<dt><b>$delset </b><i>n comment</i></dt> +<dd><br> +This line deletes message set <i>n</i> from an existing message catalog. The <i>n</i> denotes the set number [1, {NL_SETMAX}]. Any +string following the set number shall be treated as a comment.</dd> +<dt><b>$ </b><i>comment</i></dt> +<dd>A line beginning with <tt>'$'</tt> followed by a <blank> shall be treated as a comment.</dd> +<dt><i>m message-text</i></dt> +<dd><br> +The <i>m</i> denotes the message identifier, which is defined as a number in the range [1, {NL_MSGMAX}] (see the <a href= +"../basedefs/limits.h.html"><i><limits.h></i></a> header). The <i>message-text</i> shall be stored in the message catalog +with the set identifier specified by the last <b>$set</b> directive, and with message identifier <i>m</i>. If the +<i>message-text</i> is empty, and a <blank> field separator is present, an empty string shall be stored in the message +catalog. If a message source line has a message number, but neither a field separator nor <i>message-text</i>, the existing message +with that number (if any) shall be deleted from the catalog. The application shall ensure that message identifiers are in ascending +order within a single set, but need not be contiguous. The application shall ensure that the length of <i>message-text</i> is in +the range [0, {NL_TEXTMAX}] (see the <a href="../basedefs/limits.h.html"><i><limits.h></i></a> header).</dd> +<dt><b>$quote </b><i>c</i></dt> +<dd>This line specifies an optional quote character <i>c</i>, which can be used to surround <i>message-text</i> so that trailing +<space> characters or null (empty) messages are visible in a message source line. By default, or if an empty <b>$quote</b> +directive is supplied, no quoting of <i>message-text</i> shall be recognized.</dd> +</dl> +<p>Empty lines in a message text source file shall be ignored. The effects of lines starting with any character other than those +defined above are implementation-defined.</p> +<p>Text strings can contain the special characters and escape sequences defined in the following table:</p> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Description</b></p> +</th> +<th align="center"> +<p class="tent"><b>Symbol</b></p> +</th> +<th align="center"> +<p class="tent"><b>Sequence</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><newline></p> +</td> +<td align="left"> +<p class="tent">NL(LF)</p> +</td> +<td align="left"> +<p class="tent">\n</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">Horizontal-tab</p> +</td> +<td align="left"> +<p class="tent">HT</p> +</td> +<td align="left"> +<p class="tent">\t</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><vertical-tab></p> +</td> +<td align="left"> +<p class="tent">VT</p> +</td> +<td align="left"> +<p class="tent">\v</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><backspace></p> +</td> +<td align="left"> +<p class="tent">BS</p> +</td> +<td align="left"> +<p class="tent">\b</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><carriage-return></p> +</td> +<td align="left"> +<p class="tent">CR</p> +</td> +<td align="left"> +<p class="tent">\r</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><form-feed></p> +</td> +<td align="left"> +<p class="tent">FF</p> +</td> +<td align="left"> +<p class="tent">\f</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">Backslash</p> +</td> +<td align="left"> +<p class="tent"><tt>\</tt></p> +</td> +<td align="left"> +<p class="tent">\\</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">Bit pattern</p> +</td> +<td align="left"> +<p class="tent"><tt>ddd</tt></p> +</td> +<td align="left"> +<p class="tent">\ddd</p> +</td> +</tr> +</table> +</center> +<p class="tent">The escape sequence <tt>"\ddd"</tt> consists of <backslash> followed by one, two, or three octal digits, +which shall be taken to specify the value of the desired character. If the character following a <backslash> is not one of +those specified, the <backslash> shall be ignored.</p> +<p class="tent">A <backslash> followed by a <newline> is also used to continue a string on the following line. Thus, +the following two lines describe a single message string:</p> +<pre> +<tt>1 This line continues \ +to the next line +</tt></pre> +<p class="tent">which shall be equivalent to:</p> +<pre> +<tt>1 This line continues to the next line +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_50_14" id="tag_20_50_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_50_15" id="tag_20_50_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_50_16" id="tag_20_50_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Message catalogs produced by <i>gencat</i> are binary encoded, meaning that their portability cannot be guaranteed between +different types of machine. Thus, just as C programs need to be recompiled for each type of machine, so message catalogs must be +recreated via <i>gencat</i>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_50_17" id="tag_20_50_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_50_18" id="tag_20_50_18"></a>RATIONALE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_50_19" id="tag_20_50_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_50_20" id="tag_20_50_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/iconv.html#tag_20_58"><i>iconv</i></a></p> +<p class="tent">XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/limits.h.html"><i><limits.h></i></a> , <a href="../basedefs/nl_types.h.html"><i><nl_types.h></i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_50_21" id="tag_20_50_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 3.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_50_22" id="tag_20_50_22"></a>Issue 6</h4> +<blockquote> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_50_23" id="tag_20_50_23"></a>Issue 7</h4> +<blockquote> +<p>The <i>gencat</i> utility is moved from the XSI option to the Base.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_50_24" id="tag_20_50_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p class="tent">Austin Group Defect 1463 is applied, changing <i>n</i> to <i>c</i> in the definition of <b>$quote</b>.</p> +<p class="tent">Austin Group Defect 1516 is applied, adding XSI shading to text relating to <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/fuser.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/get.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/get.html b/bdd/get.html @@ -0,0 +1,801 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>get</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/gencat.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/getconf.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="get" id="get"></a> <a name="tag_20_51" id="tag_20_51"></a><!-- get --> +<h4 class="mansect"><a name="tag_20_51_01" id="tag_20_51_01"></a>NAME</h4> +<blockquote>get — get a version of an SCCS file (<b>DEVELOPMENT</b>)</blockquote> +<h4 class="mansect"><a name="tag_20_51_02" id="tag_20_51_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> get</tt> <b>[</b><tt>-begkmnlLpst</tt><b>] [</b><tt>-c</tt> <i>cutoff</i><b>] [</b><tt>-i</tt> +<i>list</i><b>] [</b><tt>-r</tt> <i>SID</i><b>] [</b><tt>-x</tt> <i>list</i><b>]</b> <i>file</i><tt>... <img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div> +</blockquote> +<h4 class="mansect"><a name="tag_20_51_03" id="tag_20_51_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>get</i> utility shall generate a text file from each named SCCS <i>file</i> according to the specifications given by its +options.</p> +<p>The generated text shall normally be written into a file called the <b>g-file</b> whose name is derived from the SCCS filename +by simply removing the leading <tt>"s."</tt>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_51_04" id="tag_20_51_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>get</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-r </b><i>SID</i></dt> +<dd>Indicate the SCCS Identification String (SID) of the version (delta) of an SCCS file to be retrieved. The table shows, for the +most useful cases, what version of an SCCS file is retrieved (as well as the SID of the version to be eventually created by +<a href="../utilities/delta.html"><i>delta</i></a> if the <b>-e</b> option is also used), as a function of the SID specified.</dd> +<dt><b>-c </b><i>cutoff</i></dt> +<dd>Indicate the <i>cutoff</i> date-time, in the form: +<pre> +<i>YY</i><b>[</b><i>MM</i><b>[</b><i>DD</i><b>[</b><i>HH</i><b>[</b><i>MM</i><b>[</b><i>SS</i><b>]]]]]</b><tt> +</tt></pre> +<p>For the <i>YY</i> component, values in the range [69,99] shall refer to years 1969 to 1999 inclusive, and values in the range +[00,68] shall refer to years 2000 to 2068 inclusive. <basefont size="2"></p> +<dl> +<dt><b>Note:</b></dt> +<dd>It is expected that in a future version of this standard the default century inferred from a 2-digit year will change. (This +would apply to all commands accepting a 2-digit year as input.)</dd> +</dl> +<basefont size="3"> +<p>No changes (deltas) to the SCCS file that were created after the specified <i>cutoff</i> date-time shall be included in the +generated text file. Units omitted from the date-time default to their maximum possible values; for example, <b>-c</b> 7502 is +equivalent to <b>-c</b> 750228235959.</p> +<p>Any number of non-numeric characters may separate the various 2-digit pieces of the <i>cutoff</i> date-time. This feature allows +the user to specify a <i>cutoff</i> date in the form: <b>-c</b> "77/2/2 9:22:25".</p> +</dd> +<dt><b>-e</b></dt> +<dd>Indicate that the <i>get</i> is for the purpose of editing or making a change (delta) to the SCCS file via a subsequent use of +<a href="../utilities/delta.html"><i>delta</i></a>. The <b>-e</b> option used in a <i>get</i> for a particular version (SID) of the +SCCS file shall prevent further <i>get</i> commands from editing on the same SID until <a href= +"../utilities/delta.html"><i>delta</i></a> is executed or the <b>j</b> (joint edit) flag is set in the SCCS file. Concurrent use of +<i>get</i> <b>-e</b> for different SIDs is always allowed. +<p>If the <b>g-file</b> generated by <i>get</i> with a <b>-e</b> option is accidentally ruined in the process of editing, it may be +regenerated by re-executing the <i>get</i> command with the <b>-k</b> option in place of the <b>-e</b> option.</p> +<p>SCCS file protection specified via the ceiling, floor, and authorized user list stored in the SCCS file shall be enforced when +the <b>-e</b> option is used.</p> +</dd> +<dt><b>-b</b></dt> +<dd>Use with the <b>-e</b> option to indicate that the new delta should have an SID in a new branch as shown in the table below. +This option shall be ignored if the <b>b</b> flag is not present in the file or if the retrieved delta is not a leaf delta. (A leaf +delta is one that has no successors on the SCCS file tree.) <basefont size="2"> +<dl> +<dt><b>Note:</b></dt> +<dd>A branch delta may always be created from a non-leaf delta.</dd> +</dl> +<basefont size="3"></dd> +<dt><b>-i </b><i>list</i></dt> +<dd>Indicate a <i>list</i> of deltas to be included (forced to be applied) in the creation of the generated file. The <i>list</i> +has the following syntax: +<pre> +<tt><list> ::= <range> | <list> , <range> +<range> ::= SID | SID - SID +</tt></pre> +<p>SID, the SCCS Identification of a delta, may be in any form shown in the "SID Specified" column of the table in the EXTENDED +DESCRIPTION section, except that the result of supplying a partial SID is unspecified. A diagnostic message shall be written if the +first SID in the range is not an ancestor of the second SID in the range.</p> +</dd> +<dt><b>-x </b><i>list</i></dt> +<dd>Indicate a <i>list</i> of deltas to be excluded (forced not to be applied) in the creation of the generated file. See the +<b>-i</b> option for the <i>list</i> format.</dd> +<dt><b>-k</b></dt> +<dd>Suppress replacement of identification keywords (see below) in the retrieved text by their value. The <b>-k</b> option shall be +implied by the <b>-e</b> option.</dd> +<dt><b>-l</b></dt> +<dd>Write a delta summary into an <b>l-file</b>.</dd> +<dt><b>-L</b></dt> +<dd>Write a delta summary to standard output. All informative output that normally is written to standard output shall be written +to standard error instead, unless the <b>-s</b> option is used, in which case it shall be suppressed.</dd> +<dt><b>-p</b></dt> +<dd>Write the text retrieved from the SCCS file to the standard output. No <b>g-file</b> shall be created. All informative output +that normally goes to the standard output shall go to standard error instead, unless the <b>-s</b> option is used, in which case it +shall disappear.</dd> +<dt><b>-s</b></dt> +<dd>Suppress all informative output normally written to standard output. However, fatal error messages (which shall always be +written to the standard error) shall remain unaffected.</dd> +<dt><b>-m</b></dt> +<dd>Precede each text line retrieved from the SCCS file by the SID of the delta that inserted the text line in the SCCS file. The +format shall be: +<pre> +<tt>"%s\t%s", <</tt><i>SID</i><tt>>, <</tt><i>text line</i><tt>> +</tt></pre></dd> +<dt><b>-n</b></dt> +<dd>Precede each generated text line with the %<b>M</b>% identification keyword value (see below). The format shall be: +<pre> +<tt>"%s\t%s", <</tt><i>%M% value</i><tt>>, <</tt><i>text line</i><tt>> +</tt></pre> +<p>When both the <b>-m</b> and <b>-n</b> options are used, the <<i>text line</i>> shall be replaced by the <b>-m</b> +option-generated format.</p> +</dd> +<dt><b>-g</b></dt> +<dd>Suppress the actual retrieval of text from the SCCS file. It is primarily used to generate an <b>l-file</b>, or to verify the +existence of a particular SID.</dd> +<dt><b>-t</b></dt> +<dd>Use to access the most recently created (top) delta in a given release (for example, <b>-r 1</b>), or release and level (for +example, <b>-r 1.2</b>).</dd> +</dl> +<br></blockquote> +<h4 class="mansect"><a name="tag_20_51_05" id="tag_20_51_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of an existing SCCS file or a directory. If <i>file</i> is a directory, the <i>get</i> utility shall behave as +though each file in the directory were specified as a named file, except that non-SCCS files (last component of the pathname does +not begin with <b>s.</b>) and unreadable files shall be silently ignored. +<p>If exactly one <i>file</i> operand appears, and it is <tt>'-'</tt>, the standard input shall be read; each line of the standard +input is taken to be the name of an SCCS file to be processed. Non-SCCS files and unreadable files shall be silently ignored.</p> +</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_51_06" id="tag_20_51_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be a text file used only if the <i>file</i> operand is specified as <tt>'-'</tt>. Each line of the text +file shall be interpreted as an SCCS pathname.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_51_07" id="tag_20_51_07"></a>INPUT FILES</h4> +<blockquote> +<p>The SCCS files shall be files of an unspecified format.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_51_08" id="tag_20_51_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>get</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error, and +informative messages written to standard output (or standard error, if the <b>-p</b> option is used).</dd> +<dt><i>NLSPATH</i></dt> +<dd>Determine the location of messages objects and message catalogs.</dd> +<dt><i>TZ</i></dt> +<dd>Determine the timezone in which the times and dates written in the SCCS file are evaluated. If the <i>TZ</i> variable is unset +or NULL, an unspecified system default timezone is used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_51_09" id="tag_20_51_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_51_10" id="tag_20_51_10"></a>STDOUT</h4> +<blockquote> +<p>For each file processed, <i>get</i> shall write to standard output the SID being accessed and the number of lines retrieved from +the SCCS file, in the following format:</p> +<pre> +<tt>"%s\n%d lines\n", <</tt><i>SID</i><tt>>, <</tt><i>number of lines</i><tt>> +</tt></pre> +<p>If the <b>-e</b> option is used, the SID of the delta to be made shall appear after the SID accessed and before the number of +lines generated, in the POSIX locale:</p> +<pre> +<tt>"%s\nnew delta %s\n%d lines\n", <</tt><i>SID accessed</i><tt>>, + <</tt><i>SID to be made</i><tt>>, <</tt><i>number of lines</i><tt>> +</tt></pre> +<p>If there is more than one named file or if a directory or standard input is named, each pathname shall be written before each of +the lines shown in one of the preceding formats:</p> +<pre> +<tt>"\n%s:\n", <</tt><i>pathname</i><tt>> +</tt></pre> +<p>If the <b>-L</b> option is used, a delta summary shall be written following the format specified below for <b>l-files</b>.</p> +<p>If the <b>-i</b> option is used, included deltas shall be listed following the notation, in the POSIX locale:</p> +<pre> +<tt>"Included:\n" +</tt></pre> +<p>If the <b>-x</b> option is used, excluded deltas shall be listed following the notation, in the POSIX locale:</p> +<pre> +<tt>"Excluded:\n" +</tt></pre> +<p>If the <b>-p</b> or <b>-L</b> options are specified, the standard output shall consist of the text retrieved from the SCCS +file.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_51_11" id="tag_20_51_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages, except if the <b>-p</b> or <b>-L</b> options are specified, it +shall include all informative messages normally sent to standard output.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_51_12" id="tag_20_51_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>Several auxiliary files may be created by <i>get</i>. These files are known generically as the <b>g-file</b>, <b>l-file</b>, +<b>p-file</b>, and <b>z-file</b>. The letter before the <hyphen-minus> is called the <i>tag</i>. An auxiliary filename shall +be formed from the SCCS filename: the application shall ensure that the last component of all SCCS filenames is of the form +<b>s.</b><i>module-name</i>; the auxiliary files shall be named by replacing the leading <b>s</b> with the tag. The <b>g-file</b> +shall be an exception to this scheme: the <b>g-file</b> is named by removing the <b>s.</b> prefix. For example, for <b>s.xyz.c</b>, +the auxiliary filenames would be <b>xyz.c</b>, <b>l.xyz.c</b>, <b>p.xyz.c</b>, and <b>z.xyz.c</b>, respectively.</p> +<p>The <b>g-file</b>, which contains the generated text, shall be created in the current directory (unless the <b>-p</b> option is +used). A <b>g-file</b> shall be created in all cases, whether or not any lines of text were generated by the <i>get</i>. It shall +be owned by the real user. If the <b>-k</b> option is used or implied, the <b>g-file</b> shall be writable by the owner only +(read-only for everyone else); otherwise, it shall be read-only. Only the real user need have write permission in the current +directory.</p> +<p>The <b>l-file</b> shall contain a table showing which deltas were applied in generating the retrieved text. The <b>l-file</b> +shall be created in the current directory if the <b>-l</b> option is used; it shall be read-only and it is owned by the real user. +Only the real user need have write permission in the current directory.</p> +<p>Lines in the <b>l-file</b> shall have the following format:</p> +<pre> +<tt>"%c%c%cΔ%s\t%sΔ%s\n", <</tt><i>code1</i><tt>>, <</tt><i>code2</i><tt>>, <</tt><i>code3</i><tt>>, + <</tt><i>SID</i><tt>>, <</tt><i>date-time</i><tt>>, <</tt><i>login</i><tt>> +</tt></pre> +<p>where the entries are:</p> +<dl compact> +<dd></dd> +<dt><<i>code1</i>></dt> +<dd>A <space> if the delta was applied; <tt>'*'</tt> otherwise.</dd> +<dt><<i>code2</i>></dt> +<dd>A <space> if the delta was applied or was not applied and ignored; <tt>'*'</tt> if the delta was not applied and was not +ignored.</dd> +<dt><<i>code3</i>></dt> +<dd>A character indicating a special reason why the delta was or was not applied: +<dl compact> +<dd></dd> +<dt><b>I</b></dt> +<dd>Included.</dd> +<dt><b>X</b></dt> +<dd>Excluded.</dd> +<dt><b>C</b></dt> +<dd>Cut off (by a <b>-c</b> option).</dd> +</dl> +</dd> +<dt><<i>date-time</i>></dt> +<dd>Date and time (using the format of the <a href="../utilities/date.html"><i>date</i></a> utility's +<tt>%y</tt>/<tt>%m</tt>/<tt>%d</tt> <tt>%T</tt> conversion specification format) of creation.</dd> +<dt><<i>login</i>></dt> +<dd>Login name of person who created <a href="../utilities/delta.html"><i>delta</i></a>.</dd> +</dl> +<p>The comments and MR data shall follow on subsequent lines, indented one <tab>. A blank line shall terminate each +entry.</p> +<p>The <b>p-file</b> shall be used to pass information resulting from a <i>get</i> with a <b>-e</b> option along to <a href= +"../utilities/delta.html"><i>delta</i></a>. Its contents shall also be used to prevent a subsequent execution of <i>get</i> with a +<b>-e</b> option for the same SID until <a href="../utilities/delta.html"><i>delta</i></a> is executed or the joint edit flag, +<b>j</b>, is set in the SCCS file. The <b>p-file</b> shall be created in the directory containing the SCCS file and the application +shall ensure that the effective user has write permission in that directory. It shall be writable by owner only, and owned by the +effective user. Each line in the <b>p-file</b> shall have the following format:</p> +<pre> +<tt>"%sΔ%sΔ%sΔ%s%s%s\n", <</tt><i>g-file SID</i><tt>>, + <</tt><i>SID of new delta</i><tt>>, <</tt><i>login-name of real user</i><tt>>, + <</tt><i>date-time</i><tt>>, <</tt><i>i-value</i><tt>>, <</tt><i>x-value</i><tt>> +</tt></pre> +<p>where <<i>i-value</i>> uses the format <tt>""</tt> if no <b>-i</b> option was specified, and shall use the format:</p> +<pre> +<tt>"Δ-i%s", <-i option </tt><i>option-argument</i><tt>> +</tt></pre> +<p>if a <b>-i</b> option was specified and <<i>x-value</i>> uses the format <tt>""</tt> if no <b>-x</b> option was specified, +and shall use the format:</p> +<pre> +<tt>"Δ-x%s", <-x option </tt><i>option-argument</i><tt>> +</tt></pre> +<p>if a <b>-x</b> option was specified. There can be an arbitrary number of lines in the <b>p-file</b> at any time; no two lines +shall have the same new delta SID.</p> +<p>The <b>z-file</b> shall serve as a lock-out mechanism against simultaneous updates. Its contents shall be the binary process ID +of the command (that is, <i>get</i>) that created it. The <b>z-file</b> shall be created in the directory containing the SCCS file +for the duration of <i>get</i>. The same protection restrictions as those for the <b>p-file</b> shall apply for the <b>z-file</b>. +The <b>z-file</b> shall be created read-only.<br></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_51_13" id="tag_20_51_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th colspan="5" align="center"> +<p class="tent"><b>Determination of SCCS Identification String</b></p> +</th> +</tr> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>SID* Specified</b></p> +</th> +<th align="center"> +<p class="tent"><b>-b Keyletter Used†</b></p> +</th> +<th align="center"> +<p class="tent"><b>Other Conditions</b></p> +</th> +<th align="center"> +<p class="tent"><b>SID Retrieved</b></p> +</th> +<th align="center"> +<p class="tent"><b>SID of Delta to be Created</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">none‡</p> +</td> +<td align="center"> +<p class="tent">no</p> +</td> +<td align="left"> +<p class="tent">R defaults to mR</p> +</td> +<td align="left"> +<p class="tent">mR.mL</p> +</td> +<td align="left"> +<p class="tent">mR.(mL+1)</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">none‡</p> +</td> +<td align="center"> +<p class="tent">yes</p> +</td> +<td align="left"> +<p class="tent">R defaults to mR</p> +</td> +<td align="left"> +<p class="tent">mR.mL</p> +</td> +<td align="left"> +<p class="tent">mR.mL.(mB+1).1</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">R</p> +</td> +<td align="center"> +<p class="tent">no</p> +</td> +<td align="left"> +<p class="tent">R > mR</p> +</td> +<td align="left"> +<p class="tent">mR.mL</p> +</td> +<td align="left"> +<p class="tent">R.1***</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">R</p> +</td> +<td align="center"> +<p class="tent">no</p> +</td> +<td align="left"> +<p class="tent">R = mR</p> +</td> +<td align="left"> +<p class="tent">mR.mL</p> +</td> +<td align="left"> +<p class="tent">mR.(mL+1)</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">R</p> +</td> +<td align="center"> +<p class="tent">yes</p> +</td> +<td align="left"> +<p class="tent">R > mR</p> +</td> +<td align="left"> +<p class="tent">mR.mL</p> +</td> +<td align="left"> +<p class="tent">mR.mL.(mB+1).1</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">R</p> +</td> +<td align="center"> +<p class="tent">yes</p> +</td> +<td align="left"> +<p class="tent">R = mR</p> +</td> +<td align="left"> +<p class="tent">mR.mL</p> +</td> +<td align="left"> +<p class="tent">mR.mL.(mB+1).1</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">R</p> +</td> +<td align="center"> +<p class="tent">-</p> +</td> +<td align="left"> +<p class="tent">R < mR and R does not exist</p> +</td> +<td align="left"> +<p class="tent">hR.mL**</p> +</td> +<td align="left"> +<p class="tent">hR.mL.(mB+1).1</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">R</p> +</td> +<td align="center"> +<p class="tent">-</p> +</td> +<td align="left"> +<p class="tent">Trunk successor in release > R and R exists</p> +</td> +<td align="left"> +<p class="tent">R.mL</p> +</td> +<td align="left"> +<p class="tent">R.mL.(mB+1).1</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">R.L</p> +</td> +<td align="center"> +<p class="tent">no</p> +</td> +<td align="left"> +<p class="tent">No trunk successor</p> +</td> +<td align="left"> +<p class="tent">R.L</p> +</td> +<td align="left"> +<p class="tent">R.(L+1)</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">R.L</p> +</td> +<td align="center"> +<p class="tent">yes</p> +</td> +<td align="left"> +<p class="tent">No trunk successor</p> +</td> +<td align="left"> +<p class="tent">R.L</p> +</td> +<td align="left"> +<p class="tent">R.L.(mB+1).1</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">R.L</p> +</td> +<td align="center"> +<p class="tent">-</p> +</td> +<td align="left"> +<p class="tent">Trunk successor in release >= R</p> +</td> +<td align="left"> +<p class="tent">R.L</p> +</td> +<td align="left"> +<p class="tent">R.L.(mB+1).1</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">R.L.B</p> +</td> +<td align="center"> +<p class="tent">no</p> +</td> +<td align="left"> +<p class="tent">No branch successor</p> +</td> +<td align="left"> +<p class="tent">R.L.B.mS</p> +</td> +<td align="left"> +<p class="tent">R.L.B.(mS+1)</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">R.L.B</p> +</td> +<td align="center"> +<p class="tent">yes</p> +</td> +<td align="left"> +<p class="tent">No branch successor</p> +</td> +<td align="left"> +<p class="tent">R.L.B.mS</p> +</td> +<td align="left"> +<p class="tent">R.L.(mB+1).1</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">R.L.B.S</p> +</td> +<td align="center"> +<p class="tent">no</p> +</td> +<td align="left"> +<p class="tent">No branch successor</p> +</td> +<td align="left"> +<p class="tent">R.L.B.S</p> +</td> +<td align="left"> +<p class="tent">R.L.B.(S+1)</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">R.L.B.S</p> +</td> +<td align="center"> +<p class="tent">yes</p> +</td> +<td align="left"> +<p class="tent">No branch successor</p> +</td> +<td align="left"> +<p class="tent">R.L.B.S</p> +</td> +<td align="left"> +<p class="tent">R.L.(mB+1).1</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">R.L.B.S</p> +</td> +<td align="center"> +<p class="tent">-</p> +</td> +<td align="left"> +<p class="tent">Branch successor</p> +</td> +<td align="left"> +<p class="tent">R.L.B.S</p> +</td> +<td align="left"> +<p class="tent">R.L.(mB+1).1</p> +</td> +</tr> +</table> +</center> +<dl compact> +<dd></dd> +<dt>*</dt> +<dd>R, L, B, and S are the release, level, branch, and sequence components of the SID, respectively; m means maximum. Thus, for +example, R.mL means "the maximum level number within release R"; R.L.(mB+1).1 means "the first sequence number on the new branch +(that is, maximum branch number plus one) of level L within release R". Note that if the SID specified is of the form R.L, R.L.B, +or R.L.B.S, each of the specified components shall exist.</dd> +<dt>**</dt> +<dd>hR is the highest existing release that is lower than the specified, nonexistent, release R.</dd> +<dt>***</dt> +<dd>This is used to force creation of the first delta in a new release.</dd> +<dt>†</dt> +<dd>The <b>-b</b> option is effective only if the <b>b</b> flag is present in the file. An entry of <tt>'-'</tt> means +"irrelevant".</dd> +<dt>‡</dt> +<dd>This case applies if the <b>d</b> (default SID) flag is not present in the file. If the <b>d</b> flag is present in the file, +then the SID obtained from the <b>d</b> flag is interpreted as if it had been specified on the command line. Thus, one of the other +cases in this table applies.</dd> +</dl> +<h5><a name="tag_20_51_13_01" id="tag_20_51_13_01"></a>System Date and Time</h5> +<p class="tent">When a <b>g-file</b> is generated, the creation time of deltas in the SCCS file may be taken into account. If any +of these times are apparently in the future, the behavior is unspecified.</p> +<h5><a name="tag_20_51_13_02" id="tag_20_51_13_02"></a>Identification Keywords</h5> +<p class="tent">Identifying information shall be inserted into the text retrieved from the SCCS file by replacing identification +keywords with their value wherever they occur. The following keywords may be used in the text stored in an SCCS file:</p> +<dl compact> +<dd></dd> +<dt>%<b>M</b>%</dt> +<dd>Module name: either the value of the <b>m</b> flag in the file, or if absent, the name of the SCCS file with the leading +<b>s.</b> removed.</dd> +<dt>%<b>I</b>%</dt> +<dd>SCCS identification (SID) (%<b>R</b>%.%<b>L</b>% or %<b>R</b>%.%<b>L</b>%.%<b>B</b>%.%<b>S</b>%) of the retrieved text.</dd> +<dt>%<b>R</b>%</dt> +<dd>Release.</dd> +<dt>%<b>L</b>%</dt> +<dd>Level.</dd> +<dt>%<b>B</b>%</dt> +<dd>Branch.</dd> +<dt>%<b>S</b>%</dt> +<dd>Sequence.</dd> +<dt>%<b>D</b>%</dt> +<dd>Current date (<i>YY</i>/<i>MM</i>/<i>DD</i>).</dd> +<dt>%<b>H</b>%</dt> +<dd>Current date (<i>MM</i>/<i>DD</i>/<i>YY</i>).</dd> +<dt>%<b>T</b>%</dt> +<dd>Current time (<i>HH</i>:<i>MM</i>:<i>SS</i>).</dd> +<dt>%<b>E</b>%</dt> +<dd>Date newest applied delta was created (<i>YY</i>/<i>MM</i>/<i>DD</i>).</dd> +<dt>%<b>G</b>%</dt> +<dd>Date newest applied delta was created (<i>MM</i>/<i>DD</i>/<i>YY</i>).</dd> +<dt>%<b>U</b>%</dt> +<dd>Time newest applied delta was created (<i>HH</i>:<i>MM</i>:<i>SS</i>).</dd> +<dt>%<b>Y</b>%</dt> +<dd>Module type: value of the <b>t</b> flag in the SCCS file.</dd> +<dt>%<b>F</b>%</dt> +<dd>SCCS filename.</dd> +<dt>%<b>P</b>%</dt> +<dd>SCCS absolute pathname.</dd> +<dt>%<b>Q</b>%</dt> +<dd>The value of the <b>q</b> flag in the file.</dd> +<dt>%<b>C</b>%</dt> +<dd>Current line number. This keyword is intended for identifying messages output by the program, such as "this should not have +happened" type errors. It is not intended to be used on every line to provide sequence numbers.</dd> +<dt>%<b>Z</b>%</dt> +<dd>The four-character string <tt>"@(#)"</tt> recognizable by <a href="../utilities/what.html"><i>what</i></a>.</dd> +<dt>%<b>W</b>%</dt> +<dd>A shorthand notation for constructing <a href="../utilities/what.html"><i>what</i></a> strings: +<pre> +<tt>%W%=%Z%%M%<tab>%I% +</tt></pre></dd> +<dt>%<b>A</b>%</dt> +<dd>Another shorthand notation for constructing <a href="../utilities/what.html"><i>what</i></a> strings: +<pre> +<tt>%A%=%Z%%Y%%M%%I%%Z% +</tt></pre></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_51_14" id="tag_20_51_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_51_15" id="tag_20_51_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_51_16" id="tag_20_51_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Problems can arise if the system date and time have been modified (for example, put forward and then back again, or +unsynchronized clocks across a network) and can also arise when different values of the <i>TZ</i> environment variable are +used.</p> +<p class="tent">Problems of a similar nature can also arise for the operation of the <a href= +"../utilities/delta.html"><i>delta</i></a> utility, which compares the previous file body against the working file as part of its +normal operation.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_51_17" id="tag_20_51_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_51_18" id="tag_20_51_18"></a>RATIONALE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_51_19" id="tag_20_51_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +<p class="tent">If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of +a <newline> character, implementations are encouraged to treat this as an error. A future version of this standard may +require implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_51_20" id="tag_20_51_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/admin.html#"><i>admin</i></a> , <a href="../utilities/delta.html#"><i>delta</i></a> , <a href= +"../utilities/prs.html#"><i>prs</i></a> , <a href="../utilities/what.html#"><i>what</i></a></p> +<p class="tent">XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_51_21" id="tag_20_51_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_51_22" id="tag_20_51_22"></a>Issue 5</h4> +<blockquote> +<p>A correction is made to the first format string in STDOUT.</p> +<p class="tent">The interpretation of the <i>YY</i> component of the <b>-c</b> <i>cutoff</i> argument is noted.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_51_23" id="tag_20_51_23"></a>Issue 6</h4> +<blockquote> +<p>The obsolescent SYNOPSIS is removed, removing the <b>-lp</b> option.</p> +<p class="tent">The normative text is reworded to avoid use of the term "must" for application requirements.</p> +<p class="tent">The Open Group Corrigendum U025/5 is applied, correcting text in the OPTIONS section.</p> +<p class="tent">The Open Group Corrigendum U048/1 is applied.</p> +<p class="tent">The Open Group Interpretation PIN4C.00014 is applied.</p> +<p class="tent">The Open Group Base Resolution bwg2001-007 is applied as follows:</p> +<ul> +<li class="tent">The EXTENDED DESCRIPTION section is updated to make partial SID handling unspecified, reflecting common usage, and +to clarify SID ranges.</li> +<li class="tent">New text is added to the EXTENDED DESCRIPTION and APPLICATION USAGE sections regarding how the system date and +time may be taken into account.</li> +<li class="tent">The <i>TZ</i> environment variable is added to the ENVIRONMENT VARIABLES section.</li> +</ul> +</blockquote> +<h4 class="mansect"><a name="tag_20_51_24" id="tag_20_51_24"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p class="tent">POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0104 [584] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_51_25" id="tag_20_51_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to behave as follows:</p> +<ol type="a"> +<li class="tent">Report an error if a utility is directed to display a pathname that contains any bytes that have the encoded value +of a <newline> character when <newline> is a terminator or separator in the output format being used.</li> +<li class="tent">Disallow the creation of filenames containing any bytes that have the encoded value of a <newline> +character.</li> +</ol> +<p class="tent">Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/gencat.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/getconf.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/getconf.html b/bdd/getconf.html @@ -0,0 +1,365 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>getconf</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/get.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/getopts.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="getconf" id="getconf"></a> <a name="tag_20_52" id="tag_20_52"></a><!-- getconf --> +<h4 class="mansect"><a name="tag_20_52_01" id="tag_20_52_01"></a>NAME</h4> +<blockquote>getconf — get configuration values</blockquote> +<h4 class="mansect"><a name="tag_20_52_02" id="tag_20_52_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>getconf</tt> <b>[</b><tt>-v specification</tt><b>]</b> <i>system_var</i> <tt><br> +<br> +getconf</tt> <b>[</b><tt>-v specification</tt><b>]</b> <i>path_var pathname</i> <tt><br></tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_52_03" id="tag_20_52_03"></a>DESCRIPTION</h4> +<blockquote> +<p>In the first synopsis form, the <i>getconf</i> utility shall write to the standard output the value of the variable specified by +the <i>system_var</i> operand.</p> +<p>In the second synopsis form, the <i>getconf</i> utility shall write to the standard output the value of the variable specified +by the <i>path_var</i> operand for the path specified by the <i>pathname</i> operand.</p> +<p>The value of each configuration variable shall be determined as if it were obtained by calling the function from which it is +defined to be available by this volume of POSIX.1-2024 or by the System Interfaces volume of POSIX.1-2024 (see the OPERANDS +section). The value shall reflect conditions in the current operating environment.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_52_04" id="tag_20_52_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>getconf</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following option shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-v </b><i>specification</i></dt> +<dd><br> +Indicate a specific specification and version for which configuration variables shall be determined. If this option is not +specified, the values returned correspond to an implementation default conforming compilation environment. +<p>If the command:</p> +<pre> +<tt>getconf _POSIX_V8_ILP32_OFF32 +</tt></pre> +<p>does not write <tt>"-1\n"</tt> or <tt>"undefined\n"</tt> to standard output, then commands of the form:</p> +<pre> +<tt>getconf -v POSIX_V8_ILP32_OFF32 ... +</tt></pre> +<p>determine values for configuration variables corresponding to the POSIX_V8_ILP32_OFF32 compilation environment specified in +<a href="../utilities/c17.html#"><i>c17</i></a> , the EXTENDED DESCRIPTION.</p> +<p>If the command:</p> +<pre> +<tt>getconf _POSIX_V8_ILP32_OFFBIG +</tt></pre> +<p>does not write <tt>"-1\n"</tt> or <tt>"undefined\n"</tt> to standard output, then commands of the form:</p> +<pre> +<tt>getconf -v POSIX_V8_ILP32_OFFBIG ... +</tt></pre> +<p>determine values for configuration variables corresponding to the POSIX_V8_ILP32_OFFBIG compilation environment specified in +<a href="../utilities/c17.html#"><i>c17</i></a> , the EXTENDED DESCRIPTION.</p> +<p>If the command:</p> +<pre> +<tt>getconf _POSIX_V8_LP64_OFF64 +</tt></pre> +<p>does not write <tt>"-1\n"</tt> or <tt>"undefined\n"</tt> to standard output, then commands of the form:</p> +<pre> +<tt>getconf -v POSIX_V8_LP64_OFF64 ... +</tt></pre> +<p>determine values for configuration variables corresponding to the POSIX_V8_LP64_OFF64 compilation environment specified in +<a href="../utilities/c17.html#"><i>c17</i></a> , the EXTENDED DESCRIPTION.</p> +<p>If the command:</p> +<pre> +<tt>getconf _POSIX_V8_LPBIG_OFFBIG +</tt></pre> +<p>does not write <tt>"-1\n"</tt> or <tt>"undefined\n"</tt> to standard output, then commands of the form:</p> +<pre> +<tt>getconf -v POSIX_V8_LPBIG_OFFBIG ... +</tt></pre> +<p>determine values for configuration variables corresponding to the POSIX_V8_LPBIG_OFFBIG compilation environment specified in +<a href="../utilities/c17.html#"><i>c17</i></a> , the EXTENDED DESCRIPTION.</p> +</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_52_05" id="tag_20_52_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>path_var</i></dt> +<dd>A name of a configuration variable. All of the variables in the Variable column of the table in the DESCRIPTION of the <a href= +"../functions/fpathconf.html"><i>fpathconf</i>()</a> function defined in the System Interfaces volume of POSIX.1-2024, without the +enclosing braces, shall be supported. The implementation may add other local variables.</dd> +<dt><i>pathname</i></dt> +<dd>A pathname for which the variable specified by <i>path_var</i> is to be determined.</dd> +<dt><i>system_var</i></dt> +<dd>A name of a configuration variable. All of the following variables shall be supported: +<ul> +<li> +<p>The names, without the enclosing braces, in the Variable column of the table in the DESCRIPTION of the <a href= +"../functions/sysconf.html"><i>sysconf</i>()</a> function in the System Interfaces volume of POSIX.1-2024, except for the entries +corresponding to _SC_CLK_TCK, _SC_GETGR_R_SIZE_MAX, _SC_GETPW_R_SIZE_MAX, _SC_NPROCESSORS_CONF, _SC_NPROCESSORS_ONLN, and +_SC_NSIG.</p> +<p>For compatibility with earlier versions, the following variable names shall also be supported: POSIX2_C_BIND POSIX2_C_DEV +POSIX2_CHAR_TERM POSIX2_FORT_RUN POSIX2_LOCALEDEF POSIX2_SW_DEV POSIX2_UPE POSIX2_VERSION</p> +<p>and shall be equivalent to the same name prefixed with an <underscore>. This requirement may be removed in a future +version.</p> +</li> +<li> +<p>The names NPROCESSORS_CONF and NPROCESSORS_ONLN. The values of these configuration variables shall be determined as if they were +obtained by calling the function <a href="../functions/sysconf.html"><i>sysconf</i>()</a> with the argument _SC_NPROCESSORS_CONF or +_SC_NPROCESSORS_ONLN, respectively.</p> +</li> +<li> +<p>The names of the symbolic constants used as the <i>name</i> argument of the <a href= +"../functions/confstr.html"><i>confstr</i>()</a> function in the System Interfaces volume of POSIX.1-2024, without the _CS_ +prefix.</p> +</li> +<li> +<p>The names of the symbolic constants listed under the headings "Maximum Values" and "Minimum Values" in the description of +the <a href="../basedefs/limits.h.html"><i><limits.h></i></a> header in the Base Definitions volume of POSIX.1-2024, without +the enclosing braces.</p> +<p>For compatibility with earlier versions, the following variable names shall also be supported: POSIX2_BC_BASE_MAX +POSIX2_BC_DIM_MAX POSIX2_BC_SCALE_MAX POSIX2_BC_STRING_MAX POSIX2_COLL_WEIGHTS_MAX POSIX2_EXPR_NEST_MAX POSIX2_LINE_MAX +POSIX2_RE_DUP_MAX</p> +<p>and shall be equivalent to the same name prefixed with an <underscore>. This requirement may be removed in a future +version.</p> +</li> +</ul> +<p>The implementation may add other local values.</p> +</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_52_06" id="tag_20_52_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_52_07" id="tag_20_52_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_52_08" id="tag_20_52_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>getconf</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_52_09" id="tag_20_52_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_52_10" id="tag_20_52_10"></a>STDOUT</h4> +<blockquote> +<p>If the specified variable is defined on the system and its value is described to be available from the <a href= +"../functions/confstr.html"><i>confstr</i>()</a> function defined in the System Interfaces volume of POSIX.1-2024, its value shall +be written in the following format:</p> +<pre> +<tt>"%s\n", <</tt><i>value</i><tt>> +</tt></pre> +<p>Otherwise, if the specified variable is defined on the system, its value shall be written in the following format:</p> +<pre> +<tt>"%d\n", <</tt><i>value</i><tt>> +</tt></pre> +<p>If the specified variable is valid, but is undefined on the system, <i>getconf</i> shall write using the following format:</p> +<pre> +<tt>"undefined\n" +</tt></pre> +<p>If the variable name is invalid or an error occurs, nothing shall be written to standard output.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_52_11" id="tag_20_52_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_52_12" id="tag_20_52_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_52_13" id="tag_20_52_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_52_14" id="tag_20_52_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>The specified variable is valid and information about its current state was written successfully.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_52_15" id="tag_20_52_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_52_16" id="tag_20_52_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_52_17" id="tag_20_52_17"></a>EXAMPLES</h4> +<blockquote> +<p>The following example illustrates the value of {NGROUPS_MAX}:</p> +<pre> +<tt>getconf NGROUPS_MAX +</tt></pre> +<p>The following example illustrates the value of {NAME_MAX} for a specific directory:</p> +<pre> +<tt>getconf NAME_MAX /usr +</tt></pre> +<p>The following example shows how to deal more carefully with results that might be unspecified:</p> +<pre> +<tt>if value=$(getconf PATH_MAX /usr); then + if [ "$value" = "undefined" ]; then + echo PATH_MAX in /usr is indeterminate. + else + echo PATH_MAX in /usr is $value. + fi +else + echo Error in getconf. +fi +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_52_18" id="tag_20_52_18"></a>RATIONALE</h4> +<blockquote> +<p>The original need for this utility, and for the <a href="../functions/confstr.html"><i>confstr</i>()</a> function, was to +provide a way of finding the configuration-defined default value for the <i>PATH</i> environment variable. Since <i>PATH</i> can be +modified by the user to include directories that could contain utilities replacing the standard utilities, shell scripts need a way +to determine the system-supplied <i>PATH</i> environment variable value that contains the correct search path for the standard +utilities. It was later suggested that access to the other variables described in this volume of POSIX.1-2024 could also be useful +to applications.</p> +<p>This functionality of <i>getconf</i> would not be adequately subsumed by another command such as:</p> +<pre> +<tt>grep </tt><i>var</i><tt> /etc/conf +</tt></pre> +<p>because such a strategy would provide correct values for neither those variables that can vary at runtime, nor those that can +vary depending on the path.</p> +<p>Early proposal versions of <i>getconf</i> specified exit status 1 when the specified variable was valid, but not defined on the +system. The output string <tt>"undefined"</tt> is now used to specify this case with exit code 0 because so many things depend on +an exit code of zero when an invoked utility is successful.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_52_19" id="tag_20_52_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_52_20" id="tag_20_52_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/c17.html#"><i>c17</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a> , <a href= +"../basedefs/limits.h.html"><i><limits.h></i></a></p> +<p>XSH <a href="../functions/confstr.html#"><i>confstr</i></a> , <a href="../functions/fpathconf.html#"><i>fpathconf</i></a> , +<a href="../functions/sysconf.html#"><i>sysconf</i></a> , <a href="../functions/system.html#"><i>system</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_52_21" id="tag_20_52_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_52_22" id="tag_20_52_22"></a>Issue 5</h4> +<blockquote> +<p>In the OPERANDS section:</p> +<ul> +<li> +<p>{NL_MAX} is changed to {NL_NMAX}.</p> +</li> +<li> +<p>Entries beginning NL_ are deleted from the list of standard configuration variables.</p> +</li> +<li> +<p>The list of variables previously marked UX is merged with the list marked EX.</p> +</li> +<li> +<p>Operands are added to support new Option Groups.</p> +</li> +<li> +<p>Operands are added so that <i>getconf</i> can determine supported programming environments.</p> +</li> +</ul> +</blockquote> +<h4 class="mansect"><a name="tag_20_52_23" id="tag_20_52_23"></a>Issue 6</h4> +<blockquote> +<p>The Open Group Corrigendum U029/4 is applied, correcting the example command in the last paragraph of the OPTIONS section.</p> +<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p> +<ul> +<li> +<p>Operands are added to determine supported programming environments.</p> +</li> +</ul> +<p>This reference page is updated for alignment with the ISO/IEC 9899:1999 standard. Specifically, new macros for <i>c99</i> +programming environments are introduced.</p> +<p>XSI marked <i>system_var</i> (XBS5_*) values are marked LEGACY.</p> +<p>IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/27 is applied, correcting the descriptions of <i>path_var</i> +and <i>system_var</i> in the OPERANDS section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_52_24" id="tag_20_52_24"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>The EXAMPLES section is corrected.<br></p> +<p>POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0091 [125] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_52_25" id="tag_20_52_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 339 is applied, adding the <i>system_var</i> names NPROCESSORS_CONF and NPROCESSORS_ONLN.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1330 is applied, removing obsolescent interfaces and changing "_V7_" to "_V8_".</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/get.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/getopts.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/getopts.html b/bdd/getopts.html @@ -0,0 +1,351 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>getopts</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/getconf.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/gettext.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="getopts" id="getopts"></a> <a name="tag_20_53" id="tag_20_53"></a><!-- getopts --> +<h4 class="mansect"><a name="tag_20_53_01" id="tag_20_53_01"></a>NAME</h4> +<blockquote>getopts — parse utility options</blockquote> +<h4 class="mansect"><a name="tag_20_53_02" id="tag_20_53_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>getopts</tt> <i>optstring name</i> <b>[</b><i>param</i><tt>...</tt><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_53_03" id="tag_20_53_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>getopts</i> utility shall retrieve options and option-arguments from a list of parameters. It shall support the Utility +Syntax Guidelines 3 to 10, inclusive, described in XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>When the shell is first invoked, the shell variable <i>OPTIND</i> shall be initialized to 1. Each time <i>getopts</i> is +invoked, it shall place the value of the next option found in the parameter list in the shell variable specified by the <i>name</i> +operand and the shell variable <i>OPTIND</i> shall be set as follows:</p> +<ul> +<li> +<p>When <i>getopts</i> successfully parses an option that takes an option-argument (that is, a character followed by <colon> +in <i>optstring</i>, and exit status is 0), the value of <i>OPTIND</i> shall be the integer index of the next element of the +parameter list (if any; see OPERANDS below) to be searched for an option character. Index 1 identifies the first element of the +parameter list.</p> +</li> +<li> +<p>When <i>getopts</i> reports end of options (that is, when exit status is 1), the value of <i>OPTIND</i> shall be the integer +index of the next element of the parameter list (if any).</p> +</li> +<li> +<p>In all other cases, the value of <i>OPTIND</i> is unspecified, but shall encode the information needed for the next invocation +of <i>getopts</i> to resume parsing options after the option just parsed.</p> +</li> +</ul> +<p>When the option requires an option-argument, the <i>getopts</i> utility shall place it in the shell variable <i>OPTARG .</i> If +no option was found, or if the option that was found does not have an option-argument, <i>OPTARG</i> shall be unset.</p> +<p>If an option character not contained in the <i>optstring</i> operand is found where an option character is expected, the shell +variable specified by <i>name</i> shall be set to the <question-mark> (<tt>'?'</tt>) character. In this case, if the first +character in <i>optstring</i> is a <colon> (<tt>':'</tt>), the shell variable <i>OPTARG</i> shall be set to the option +character found, but no output shall be written to standard error; otherwise, the shell variable <i>OPTARG</i> shall be unset and a +diagnostic message shall be written to standard error. This condition shall be considered to be an error detected in the way +arguments were presented to the invoking application, but shall not be an error in <i>getopts</i> processing.</p> +<p>If an option-argument is missing:</p> +<ul> +<li> +<p>If the first character of <i>optstring</i> is a <colon>, the shell variable specified by <i>name</i> shall be set to the +<colon> character and the shell variable <i>OPTARG</i> shall be set to the option character found.</p> +</li> +<li> +<p>Otherwise, the shell variable specified by <i>name</i> shall be set to the <question-mark> character, the shell variable +<i>OPTARG</i> shall be unset, and a diagnostic message shall be written to standard error. This condition shall be considered to be +an error detected in the way arguments were presented to the invoking application, but shall not be an error in <i>getopts</i> +processing; a diagnostic message shall be written as stated, but the exit status shall be zero.</p> +</li> +</ul> +<p>When the end of options is encountered, the <i>getopts</i> utility shall exit with a return value of one; the shell variable +<i>OPTIND</i> shall be set to the index of the argument containing the first operand in the parameter list, or the value 1 plus the +number of elements in the parameter list if there are no operands in the parameter list; the <i>name</i> variable shall be set to +the <question-mark> character. Any of the following shall identify the end of options: the first <tt>"--"</tt> element of the +parameter list that is not an option-argument, finding an element of the parameter list that is not an option-argument and does not +begin with a <tt>'-'</tt>, or encountering an error.</p> +<p>The shell variables <i>OPTIND</i> and <i>OPTARG</i> shall not be exported by default. An error in setting any of these variables +(such as if <i>name</i> has previously been marked <i>readonly</i>) shall be considered an error of <i>getopts</i> processing, and +shall result in a return value greater than one.</p> +<p>The <i>getopts</i> utility can affect <i>OPTIND ,</i> <i>OPTARG ,</i> and the shell variable specified by the <i>name</i> +operand, within the current shell execution environment; see <a href="../utilities/V3_chap02.html#tag_19_13"><i>2.13 Shell +Execution Environment</i></a> .</p> +<p>If the application sets <i>OPTIND</i> to the value 1, a new set of parameters can be used: either the current positional +parameters or new <i>param</i> values. Any other attempt to invoke <i>getopts</i> multiple times in a single shell execution +environment with parameters (positional parameters or <i>param</i> operands) that are not the same in all invocations, or with an +<i>OPTIND</i> value modified by the application to be a value other than 1, produces unspecified results.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_53_04" id="tag_20_53_04"></a>OPTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_53_05" id="tag_20_53_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>optstring</i></dt> +<dd>A string containing the option characters recognized by the utility invoking <i>getopts</i>. If a character is followed by a +<colon>, the option shall be expected to have an argument, which should be supplied as a separate argument. Applications +should specify an option character and its option-argument as separate arguments, but <i>getopts</i> shall interpret the characters +following an option character requiring arguments as an argument whether or not this is done. An explicit null option-argument need +not be recognized if it is not supplied as a separate argument when <i>getopts</i> is invoked. (See also the <a href= +"../functions/getopt.html"><i>getopt</i>()</a> function defined in the System Interfaces volume of POSIX.1-2024.) The characters +<question-mark> and <colon> shall not be used as option characters by an application. The use of other option +characters that are not alphanumeric produces unspecified results. Whether or not the option-argument is supplied as a separate +argument from the option character, the value in <i>OPTARG</i> shall only be the characters of the option-argument. The first +character in <i>optstring</i> determines how <i>getopts</i> behaves if an option character is not known or an option-argument is +missing.</dd> +<dt><i>name</i></dt> +<dd>The name of a shell variable that shall be set by the <i>getopts</i> utility to the option character that was found.</dd> +</dl> +<p>By default, the list of parameters parsed by the <i>getopts</i> utility shall be the positional parameters currently set in the +invoking shell environment (<tt>"$@"</tt>). If <i>param</i> operands are given, they shall be parsed instead of the positional +parameters. Note that the next element of the parameter list need not exist; in this case, <i>OPTIND</i> will be set to +<tt>$#+1</tt> or the number of <i>param</i> operands plus 1.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_53_06" id="tag_20_53_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_53_07" id="tag_20_53_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_53_08" id="tag_20_53_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>getopts</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>OPTIND</i></dt> +<dd>This variable shall be used by the <i>getopts</i> utility as the index of the next argument to be processed.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_53_09" id="tag_20_53_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_53_10" id="tag_20_53_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_53_11" id="tag_20_53_11"></a>STDERR</h4> +<blockquote> +<p>Whenever an error is detected and the first character in the <i>optstring</i> operand is not a <colon> (<tt>':'</tt>), a +diagnostic message shall be written to standard error with the following information in an unspecified format:</p> +<ul> +<li> +<p>The invoking program name shall be identified in the message. The invoking program name shall be the value of the shell special +parameter 0 (see <a href="../utilities/V3_chap02.html#tag_19_05_02"><i>2.5.2 Special Parameters</i></a> ) at the time the +<i>getopts</i> utility is invoked. A name equivalent to:</p> +<pre> +<tt>basename "$0" +</tt></pre> +<p>may be used.</p> +</li> +<li> +<p>If an option is found that was not specified in <i>optstring</i>, this error is identified and the invalid option character +shall be identified in the message.</p> +</li> +<li> +<p>If an option requiring an option-argument is found, but an option-argument is not found, this error shall be identified and the +invalid option character shall be identified in the message.</p> +</li> +</ul> +</blockquote> +<h4 class="mansect"><a name="tag_20_53_12" id="tag_20_53_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_53_13" id="tag_20_53_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_53_14" id="tag_20_53_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>An option, specified or unspecified by <i>optstring</i>, was found.</dd> +<dt> 1</dt> +<dd>The end of options was encountered.</dd> +<dt>>1</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_53_15" id="tag_20_53_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_53_16" id="tag_20_53_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>This utility is required to be intrinsic. See <a href="../utilities/V3_chap01.html#tag_18_07"><i>1.7 Intrinsic Utilities</i></a> +for details.</p> +<p>Since <i>getopts</i> affects the current shell execution environment, it is generally provided as a shell regular built-in. If +it is called in a subshell or separate utility execution environment, such as one of the following:</p> +<pre> +<tt>(getopts abc value "$@") +nohup getopts ... +find . -exec getopts ... \; +</tt></pre> +<p>it does not affect the shell variables in the caller's environment.</p> +<p>Note that shell functions share <i>OPTIND</i> with the calling shell even though the positional parameters are changed. If the +calling shell and any of its functions uses <i>getopts</i> to parse arguments, the results are unspecified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_53_17" id="tag_20_53_17"></a>EXAMPLES</h4> +<blockquote> +<p>The following example script parses and displays its arguments:</p> +<pre> +<tt>aflag= +bflag= +while getopts ab: name +do + case $name in + a) aflag=1;; + b) bflag=1 + bval="$OPTARG";; + ?) printf "Usage: %s: [-a] [-b value] args\n" $0 + exit 2;; + esac +done +if [ -n "$aflag" ]; then + printf "Option -a specified\n" +fi +if [ -n "$bflag" ]; then + printf 'Option -b "%s" specified\n' "$bval" +fi +shift $(($OPTIND - 1)) +printf "Remaining arguments are: %s\n" "$*" +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_53_18" id="tag_20_53_18"></a>RATIONALE</h4> +<blockquote> +<p>The <i>getopts</i> utility was chosen in preference to the System V <i>getopt</i> utility because <i>getopts</i> handles +option-arguments containing <blank> characters.</p> +<p>The <i>OPTARG</i> variable is not mentioned in the ENVIRONMENT VARIABLES section because it does not affect the execution of +<i>getopts</i>; it is one of the few "output-only" variables used by the standard utilities.</p> +<p>The <colon> is not allowed as an option character because that is not historical behavior, and it violates the Utility +Syntax Guidelines. The <colon> is now specified to behave as in the KornShell version of the <i>getopts</i> utility; when +used as the first character in the <i>optstring</i> operand, it disables diagnostics concerning missing option-arguments and +unexpected option characters. This replaces the use of the <i>OPTERR</i> variable that was specified in an early proposal.</p> +<p>Although a leading <plus-sign> in <i>optstring</i> is required to have no effect on the behavior of <a href= +"../functions/getopt.html"><i>getopt</i>()</a>, this standard intentionally allows implementations of the <i>getopts</i> utility to +use a leading <plus-sign> as an extension that alters behavior. In fact, a <plus-sign> anywhere in the <i>optstring</i> +in the <i>getopts</i> utility produces unspecified behavior.</p> +<p>The formats of the diagnostic messages produced by the <i>getopts</i> utility and the <a href= +"../functions/getopt.html"><i>getopt</i>()</a> function are not fully specified because implementations with superior +("friendlier") formats objected to the formats used by some historical implementations. The standard developers considered it +important that the information in the messages used be uniform between <i>getopts</i> and <a href= +"../functions/getopt.html"><i>getopt</i>()</a>. Exact duplication of the messages might not be possible, particularly if a utility +is built on another system that has a different <a href="../functions/getopt.html"><i>getopt</i>()</a> function, but the messages +must have specific information included so that the program name, invalid option character, and type of error can be distinguished +by a user.</p> +<p>Only a rare application program intercepts a <i>getopts</i> standard error message and wants to parse it. Therefore, +implementations are free to choose the most usable messages they can devise. The following formats are used by many historical +implementations:</p> +<pre> +<tt>"%s: illegal option -- %c\n", <</tt><i>program name</i><tt>>, <</tt><i>option character</i><tt>> +<br> +"%s: option requires an argument -- %c\n", <</tt><i>program name</i><tt>>, \ + <</tt><i>option character</i><tt>> +</tt></pre> +<p>Historical shells with built-in versions of <a href="../functions/getopt.html"><i>getopt</i>()</a> or <i>getopts</i> have used +different formats, frequently not even indicating the option character found in error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_53_19" id="tag_20_53_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_53_20" id="tag_20_53_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19_05_02"><i>2.5.2 Special Parameters</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/getopt.html#"><i>getopt</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_53_21" id="tag_20_53_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_53_22" id="tag_20_53_22"></a>Issue 6</h4> +<blockquote> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_53_23" id="tag_20_53_23"></a>Issue 7</h4> +<blockquote> +<p>POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0092 [159] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_53_24" id="tag_20_53_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 191 is applied, adding a paragraph about leading <plus-sign> to the RATIONALE section.</p> +<p>Austin Group Defect 367 is applied, requiring that <i>getopts</i> distinguishes between encountering the end of options and an +error occurring, setting its exit status to one and greater than one, respectively.</p> +<p>Austin Group Defect 854 is applied, adding a note to the APPLICATION USAGE section that this utility is required to be +intrinsic.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1442 is applied, changing the EXAMPLES section.</p> +<p>Austin Group Defect 1784 is applied, clarifying several aspects of <i>getopts</i> behavior and changing the value of +<i>OPTIND</i> to be unspecified in some circumstances.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/getconf.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/gettext.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/gettext.html b/bdd/gettext.html @@ -0,0 +1,439 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>gettext</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/getopts.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/grep.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="gettext" id="gettext"></a> <a name="tag_20_54" id="tag_20_54"></a><!-- gettext --> +<h4 class="mansect"><a name="tag_20_54_01" id="tag_20_54_01"></a>NAME</h4> +<blockquote>gettext, ngettext — retrieve text string from messages object</blockquote> +<h4 class="mansect"><a name="tag_20_54_02" id="tag_20_54_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>gettext</tt> <b>[</b><tt>-e|-E</tt><b>] [</b><tt>-d textdomain</tt><b>] [</b><i>textdomain</i><b>]</b> <i>msgid</i> <tt><br> +<br> +gettext</tt> <b>[</b><tt>-e|-E</tt><b>] [</b><tt>-n</tt><b>]</b> <tt>-s</tt> <b>[</b><tt>-d</tt> <i>textdomain</i><b>]</b> +<i>msgid</i><tt>...<br> +<br> +ngettext</tt> <b>[</b><tt>-e|-E</tt><b>] [</b><tt>-d</tt> <i>textdomain</i><b>] [</b><i>textdomain</i><b>]</b> <i>msgid +msgid_plural n</i> <tt><br></tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_03" id="tag_20_54_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>gettext</i> and <i>ngettext</i> utilities shall write to standard output the message string(s) that would result from the +following calls to functions defined in the System Interfaces volume of POSIX.1-2024:</p> +<pre> +<tt>if (textdomainname == NULL || textdomainname[0] == '\0') + message_string = msgid; +else { + setlocale(LC_ALL, ""); + if (textdomaindir != NULL) + bindtextdomain(textdomainname, textdomaindir); + if (msgid_plural == NULL) + message_string = dgettext(textdomainname, msgid); + else + message_string = dngettext(textdomainname, msgid, msgid_plural, n); +} +</tt></pre> +<p>where:</p> +<ul> +<li> +<p>The <i>textdomaindir</i> variable is a string containing the value of the <i>TEXTDOMAINDIR</i> environment variable, if set and +not empty, or is NULL otherwise.</p> +</li> +<li> +<p>The <i>textdomainname</i> variable is a string containing the text domain name obtained from, in decreasing order of +precedence:</p> +<ul> +<li> +<p>The optional operand <i>textdomain,</i> if present</p> +</li> +<li> +<p>The <b>-d</b> <i>textdomain</i> option, if specified</p> +</li> +<li> +<p>The <i>TEXTDOMAIN</i> environment variable, if set and not empty</p> +</li> +</ul> +<p>If the text domain name cannot be obtained from these sources, the <i>textdomainname</i> variable is NULL.</p> +</li> +<li> +<p>If the <b>-s</b> option of <i>gettext</i> is not specified and for the <i>ngettext</i> utility, the <i>msgid</i> variable is a +string containing:</p> +<ul> +<li> +<p>The value of the <i>msgid</i> operand, if the <b>-E</b> option is specified</p> +</li> +<li> +<p>The value of the <i>msgid</i> operand with C-language escape sequences processed (see below), if the <b>-e</b> option is +specified</p> +</li> +<li> +<p>The value of the <i>msgid</i> operand with C-language escape sequences optionally processed (see below), otherwise</p> +</li> +</ul> +</li> +<li> +<p>If the <b>-s</b> option of <i>gettext</i> is specified, the <i>msgid</i> variable is a string containing:</p> +<ul> +<li> +<p>The value of each <i>msgid</i> operand in turn, if the <b>-E</b> option is specified or neither the <b>-e</b> nor the <b>-E</b> +option is specified</p> +</li> +<li> +<p>The value of each <i>msgid</i> operand in turn with C-language escape sequences processed (see below), if the <b>-e</b> option +is specified</p> +</li> +</ul> +</li> +<li> +<p>For the <i>gettext</i> utility, the <i>msgid_plural</i> variable is NULL. For the <i>ngettext</i> utility, the +<i>msgid_plural</i> variable is a string containing:</p> +<ul> +<li> +<p>The value of the <i>msgid_plural</i> operand, if the <b>-E</b> option is specified</p> +</li> +<li> +<p>The value of the <i>msgid_plural</i> operand with C-language escape sequences processed (see below), if the <b>-e</b> option is +specified</p> +</li> +<li> +<p>The value of the <i>msgid_plural</i> operand with C-language escape sequences optionally processed (see below), otherwise</p> +</li> +</ul> +</li> +<li> +<p>For the <i>gettext</i> utility, the <i>n</i> variable is 1 (one). For the <i>ngettext</i> utility the <i>n</i> variable is the +<i>n</i> operand, parsed as an integer as if by using the <a href="../functions/strtoul.html"><i>strtoul</i>()</a> function with a +<i>base</i> argument of 10.</p> +</li> +</ul> +<p>When C-language escape sequences are processed, they shall be processed as specified for character string literals in the +ISO C standard, except that <i>universal-character-name</i> escape sequences need not be supported. Implementations may also +support a <backslash> <tt>'c'</tt> escape sequence; if supported, the <tt>'\c'</tt> and all characters following it shall be +removed and, if the <b>-s</b> option is specified, the behavior shall be as if the <b>-n</b> option is also specified.</p> +<p>For the <i>ngettext</i> utility, and for the <i>gettext</i> utility if the <b>-s</b> option is not specified, the resulting +message string shall be written to standard output. If the <b>-s</b> option of <i>gettext</i> is specified, the resulting message +string for each <i>msgid</i> shall be written to standard output with consecutive message strings separated by a single +<space> character and, if the <b>-n</b> option is not specified, a <newline> shall be written after the last message +string. If the <b>-s</b> and <b>-n</b> options are specified, the trailing <newline> shall be omitted.</p> +<p>Under conditions where the <i>textdomainname</i> variable in the above code would be NULL, these utilities may write a +diagnostic message to standard error and exit with non-zero status.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_04" id="tag_20_54_04"></a>OPTIONS</h4> +<blockquote> +<p>These utilities shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a> +.</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-d </b><i>textdomain</i></dt> +<dd><br> +Retrieve the translated message from the domain <i>textdomain</i>, if <i>textdomain</i> is not specified as an operand.</dd> +<dt><b>-e</b></dt> +<dd>Process C-language escape sequences in <i>msgid</i> and <i>msgid_plural</i> operands.</dd> +<dt><b>-E</b></dt> +<dd>Do not process C-language escape sequences in <i>msgid</i> and <i>msgid_plural</i> operands.</dd> +</dl> +<p>The <i>gettext</i> utility shall also support the following options:</p> +<dl compact> +<dd></dd> +<dt><b>-n</b></dt> +<dd>Modify the behavior of the <b>-s</b> option such that a <newline> is not appended to the output.</dd> +<dt><b>-s</b></dt> +<dd>Separate the message strings obtained from each <i>msgid</i> operand with <space> characters in the output, and (if +<b>-n</b> is not also specified) append a <newline> to the output.</dd> +</dl> +<p>If neither of the mutually exclusive <b>-e</b> and <b>-E</b> options is specified, it is unspecified which is the default, +except that if the <b>-s</b> option of <i>gettext</i> is specified then <b>-E</b> shall be the default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_05" id="tag_20_54_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>textdomain</i></dt> +<dd>A text domain name used to retrieve the translated message. This shall override the specification by the <b>-d</b> option, if +present.</dd> +<dt><i>msgid</i></dt> +<dd>A key to retrieve the translated message.</dd> +<dt><i>msgid_plural</i></dt> +<dd>A default plural if no corresponding plural message can be found.</dd> +<dt><i>n</i></dt> +<dd>A non-negative decimal integer to be used as the <i>n</i> argument to <a href= +"../functions/dngettext.html"><i>dngettext</i>()</a> (see the DESCRIPTION).</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_06" id="tag_20_54_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_07" id="tag_20_54_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files are messages object files (see <a href="../utilities/msgfmt.html#"><i>msgfmt</i></a> ).</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_08" id="tag_20_54_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>gettext</i> and <i>ngettext</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LANGUAGE</i></dt> +<dd>Determine the location of messages objects <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src= +"../images/opt-start.gif" alt="[Option Start]" border="0"> if <i>NLSPATH</i> is not set or the evaluation of <i>NLSPATH</i> +did not lead to a suitable messages object being found. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale name used to locate messages objects, and the locale that should be used to affect the format and contents of +diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>TEXTDOMAIN</i></dt> +<dd><br> +Specify the text domain name. (See XBD <a href="../basedefs/V1_chap03.html#tag_03_386"><i>3.386 Text Domain</i></a> .)</dd> +<dt><i>TEXTDOMAINDIR</i></dt> +<dd><br> +Specify the pathname to the messages object hierarchy. <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src= +"../images/opt-start.gif" alt="[Option Start]" border="0"> <i>NLSPATH</i> shall have precedence over <i>TEXTDOMAINDIR .</i> +<img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_09" id="tag_20_54_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_10" id="tag_20_54_10"></a>STDOUT</h4> +<blockquote> +<p>See DESCRIPTION.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_11" id="tag_20_54_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_12" id="tag_20_54_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_13" id="tag_20_54_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_14" id="tag_20_54_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_15" id="tag_20_54_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_54_16" id="tag_20_54_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Since it is unspecified which of the <b>-e</b> or <b>-E</b> options is the default, except when the <b>-s</b> option of +<i>gettext</i> is specified, portable applications need to ensure that <b>-e</b>, <b>-E</b>, or (for <i>gettext</i>) <b>-s</b> is +specified whenever a <i>msgid</i> or <i>msgid_plural</i> operand contains, or might contain, a <backslash> character.</p> +<p>Note that, unless the <b>-s</b> option of <i>gettext</i> is specified without <b>-n</b>, the message(s) written to standard +output are not followed by a <newline>. (Therefore the output only ends with a <newline> if the last message ends with +one.)</p> +<p>Both <i>msgid</i> and <i>msgid_plural</i> should be properly quoted for the shell.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_17" id="tag_20_54_17"></a>EXAMPLES</h4> +<blockquote> +<p>The following examples assume that the following portable messages object source file (dot-po file) has been compiled to a valid +file <b>mail.mo</b> by the <a href="../utilities/msgfmt.html"><i>msgfmt</i></a> utility. See the EXTENDED DESCRIPTION section of +the <a href="../utilities/msgfmt.html"><i>msgfmt</i></a> utility for a description of the dot-po file format.</p> +<pre> +<tt>msgid "" +msgstr "" +"Content-Type: text/plain; charset=utf-8\n" +"Plural-Forms: nplurals=4; plural=n==1?0: (n>1&&n<=10)?1: (n==0)?2:3;\n" +<br> +msgid "recipient" +msgid_plural "recipients" +msgstr[0] "1 recipient" +msgstr[1] "2 to 10 recipients" +msgstr[2] "no recipients" +msgstr[3] "more than 10 recipients" +<br> +msgid "%d attachment\n" +msgid_plural "%d attachments\n" +msgstr[0] "1 (%d) attachment\n" +msgstr[1] "2 to 10 (%d) attachments\n" +msgstr[2] "no (%d) attachments\n" +msgstr[3] "more than 10 (%d) attachments\n" +</tt></pre> +<p>They also assume that <b>mail.mo</b> is installed in the directory that <i>gettext</i> and <i>ngettext</i> search for the +current locale. See the OPTIONS and ENVIRONMENT VARIABLES sections above and the description of <a href= +"../functions/gettext.html"><i>gettext</i>()</a> for details on how this search is performed.</p> +<p>The command</p> +<pre> +<tt>ngettext -d mail recipient recipients 0 +</tt></pre> +<p>will write <tt>"no recipients"</tt>.</p> +<p>The command</p> +<pre> +<tt>ngettext -d mail recipient recipients 1 +</tt></pre> +<p>will write <tt>"1 recipient"</tt>.</p> +<p>The command</p> +<pre> +<tt>ngettext -d mail recipient recipients 5 +</tt></pre> +<p>will write <tt>"2 to 10 recipients"</tt>.</p> +<p>The command</p> +<pre> +<tt>ngettext -d mail recipient recipients 11 +</tt></pre> +<p>will write <tt>"more than 10 recipients"</tt>.</p> +<p>The command</p> +<pre> +<tt>ngettext -d mail Call Calls 1 +</tt></pre> +<p>will write <tt>"Call"</tt>. Note that <tt>"Call"</tt> is not in the messages object.</p> +<p>The command</p> +<pre> +<tt>ngettext -d mail Call Calls 0 +</tt></pre> +<p>will write <tt>"Calls"</tt>.</p> +<p>The command</p> +<pre> +<tt>ngettext -d mail Call Calls 10 +</tt></pre> +<p>will write <tt>"Calls"</tt>.</p> +<p>The command</p> +<pre> +<tt>ngettext -ed mail "%d attachment\n" "%d attachments\n" 1 +</tt></pre> +<p>will write the same as</p> +<pre> +<tt>printf "1 (%%d) attachment\n" +</tt></pre> +<p>(i.e. <tt>"1 (%d) attachment"</tt> followed by a <newline> character). The output of <i>ngettext</i> can be used as a +format string for <a href="../utilities/printf.html"><i>printf</i></a>.</p> +<p>The command</p> +<pre> +<tt>printf "$(ngettext -ed mail "%d attachment\n" "%d attachments\n" 1)" 10 +</tt></pre> +<p>will write the same as</p> +<pre> +<tt>printf "1 (%d) attachment\n" 10 +</tt></pre> +<p>(i.e. <tt>"1 (10) attachment"</tt> followed by a <newline> character).</p> +<p>The command</p> +<pre> +<tt>ngettext -e -d mail "\tsubject\n" "\tsubjects\n" 0 +</tt></pre> +<p>will write the same as</p> +<pre> +<tt>printf "\tsubjects\n" +</tt></pre> +<p>(i.e. a <tab> character, followed by <tt>"subjects"</tt> followed by a <newline> character). Note that +<tt>"\tsubject\n"</tt> is not in the messages object.</p> +<p>The command</p> +<pre> +<tt>printf "%s\n" "$(ngettext -E -d mail "subject" "subjects" 0)" +</tt></pre> +<p>will write the same as</p> +<pre> +<tt>printf "subjects\n" +</tt></pre> +<p>(i.e. <tt>"subjects"</tt> followed by a <newline> character). Note that <tt>"subject"</tt> is not in the messages +object.</p> +<p>The command</p> +<pre> +<tt>gettext -s -d mail "recipient" +</tt></pre> +<p>will write <tt>"1 recipient"</tt> followed by a <newline> character.</p> +<p>The command</p> +<pre> +<tt>gettext -s -n -d mail "recipient" +</tt></pre> +<p>will write <tt>"1 recipient"</tt> without a <newline> character.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_18" id="tag_20_54_18"></a>RATIONALE</h4> +<blockquote> +<p>Historical implementations did not support the <tt>'\a'</tt> C-language escape sequence. This standard requires it to be +supported for consistency with other utilities that support the table in XBD <a href="../basedefs/V1_chap05.html#tag_05"><i>5. File +Format Notation</i></a> .</p> +<p>Unlike other standard utilities, the behavior of <i>gettext</i> and <i>ngettext</i> is not undefined when <i>NLSPATH</i> +overrides the system default path; see XBD <a href="../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization +Variables</i></a> . This is so that applications can use these utilities to obtain message strings from messages objects in other +locations. However, it also means that they need to be implemented in such a way that they do not do anything that would result in +undefined behavior when they need to write a diagnostic message. In particular, they should not use a string obtained from a +message catalog or a messages object as a format string (or should only do so after checking that the string contains the correct +conversions).</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_19" id="tag_20_54_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_20" id="tag_20_54_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/msgfmt.html#"><i>msgfmt</i></a> , <a href="../utilities/printf.html#tag_20_96"><i>printf</i></a></p> +<p>XBD <a href="../basedefs/V1_chap07.html#tag_07"><i>7. Locale</i></a> , <a href="../basedefs/V1_chap08.html#tag_08"><i>8. +Environment Variables</i></a> , <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/gettext.html#tag_17_238"><i>gettext</i></a> , <a href= +"../functions/iconv.html#tag_17_248"><i>iconv</i></a> , <a href="../functions/setlocale.html#"><i>setlocale</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_21" id="tag_20_54_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 8.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/getopts.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/grep.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/grep.html b/bdd/grep.html @@ -0,0 +1,371 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>grep</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/gettext.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/hash.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="grep" id="grep"></a> <a name="tag_20_55" id="tag_20_55"></a><!-- grep --> +<h4 class="mansect"><a name="tag_20_55_01" id="tag_20_55_01"></a>NAME</h4> +<blockquote>grep — search a file for a pattern</blockquote> +<h4 class="mansect"><a name="tag_20_55_02" id="tag_20_55_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>grep</tt> <b>[</b><tt>-E|-F</tt><b>] [</b><tt>-c|-l|-q</tt><b>] [</b><tt>-insvx</tt><b>]</b> <tt>-e</tt> +<i>pattern_list<br></i> <tt> </tt> <b>[</b><tt>-e</tt> <i>pattern_list</i><b>]</b><tt>...</tt> +<b>[</b><tt>-f</tt> <i>pattern_file</i><b>]</b><tt>...</tt> <b>[</b><i>file</i><tt>...</tt><b>]</b> <tt><br> +<br> +grep</tt> <b>[</b><tt>-E|-F</tt><b>] [</b><tt>-c|-l|-q</tt><b>] [</b><tt>-insvx</tt><b>] [</b><tt>-e</tt> +<i>pattern_list</i><b>]...<br></b> <tt> </tt> <tt>-f</tt> <i>pattern_file</i> +<b>[</b><tt>-f</tt> <i>pattern_file</i><b>]</b><tt>...</tt> <b>[</b><i>file</i><tt>...</tt><b>]</b> <tt><br> +<br> +grep</tt> <b>[</b><tt>-E|-F</tt><b>] [</b><tt>-c|-l|-q</tt><b>] [</b><tt>-insvx</tt><b>]</b> <i>pattern_list</i> +<b>[</b><i>file</i><tt>...</tt><b>]</b> <tt><br></tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_55_03" id="tag_20_55_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>grep</i> utility shall search the input files, selecting lines matching one or more patterns; the types of patterns are +controlled by the options specified. The patterns are specified by the <b>-e</b> option, <b>-f</b> option, or the +<i>pattern_list</i> operand. The <i>pattern_list</i>'s value shall consist of one or more patterns separated by <newline> +characters; the <i>pattern_file</i>'s contents shall consist of one or more patterns terminated by a <newline> character. By +default, an input line shall be selected if any pattern, treated as an entire basic regular expression (BRE) as described in XBD +<a href="../basedefs/V1_chap09.html#tag_09_03"><i>9.3 Basic Regular Expressions</i></a> , matches any part of the line excluding +the terminating <newline>; a null BRE shall match every line. By default, each selected input line shall be written to the +standard output.</p> +<p>Regular expression matching shall be based on text lines. Since a <newline> separates or terminates patterns (see the +<b>-e</b> and <b>-f</b> options below), regular expressions cannot contain a <newline>. Similarly, since patterns are matched +against individual lines (excluding the terminating <newline> characters) of the input, there is no way for a pattern to +match a <newline> found in the input.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_55_04" id="tag_20_55_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>grep</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-E</b></dt> +<dd>Match using extended regular expressions. Treat each pattern specified as an ERE, as described in XBD <a href= +"../basedefs/V1_chap09.html#tag_09_04"><i>9.4 Extended Regular Expressions</i></a> . If any entire ERE pattern matches some part of +an input line excluding the terminating <newline>, the line shall be matched. A null ERE shall match every line.</dd> +<dt><b>-F</b></dt> +<dd>Match using fixed strings. Treat each pattern specified as a string instead of a regular expression. If an input line contains +any of the patterns as a contiguous sequence of bytes, the line shall be matched. A null string shall match every line.</dd> +<dt><b>-c</b></dt> +<dd>Write only a count of selected lines to standard output.</dd> +<dt><b>-e </b><i>pattern_list</i></dt> +<dd><br> +Specify one or more patterns to be used during the search for input. The application shall ensure that patterns in +<i>pattern_list</i> are separated by a <newline>. A null pattern can be specified by two adjacent <newline> characters +in <i>pattern_list</i>. Unless the <b>-E</b> or <b>-F</b> option is also specified, each pattern shall be treated as a BRE, as +described in XBD <a href="../basedefs/V1_chap09.html#tag_09_03"><i>9.3 Basic Regular Expressions</i></a> . Multiple <b>-e</b> and +<b>-f</b> options shall be accepted by the <i>grep</i> utility. All of the specified patterns shall be used when matching lines, +but the order of evaluation is unspecified.</dd> +<dt><b>-f </b><i>pattern_file</i></dt> +<dd><br> +Read one or more patterns from the file named by the pathname <i>pattern_file</i>. Patterns in <i>pattern_file</i> shall be +terminated by a <newline>. A null pattern can be specified by an empty line in <i>pattern_file</i>. Unless the <b>-E</b> or +<b>-F</b> option is also specified, each pattern shall be treated as a BRE, as described in XBD <a href= +"../basedefs/V1_chap09.html#tag_09_03"><i>9.3 Basic Regular Expressions</i></a> .</dd> +<dt><b>-i</b></dt> +<dd>Perform pattern matching in a case-insensitive manner; see XBD <a href="../basedefs/V1_chap09.html#tag_09_02"><i>9.2 Regular +Expression General Requirements</i></a> .</dd> +<dt><b>-l</b></dt> +<dd>(The letter ell.) Write only the names of files containing selected lines to standard output. Pathnames shall be written once +per file searched. If the standard input is searched, a pathname of <tt>"(standard input)"</tt> shall be written, in the POSIX +locale. In other locales, <tt>"standard input"</tt> may be replaced by something more appropriate in those locales.</dd> +<dt><b>-n</b></dt> +<dd>Precede each output line by its relative line number in the file, each file starting at line 1. The line number counter shall +be reset for each file processed.</dd> +<dt><b>-q</b></dt> +<dd>Quiet. Nothing shall be written to the standard output, regardless of matching lines. Exit with zero status if an input line is +selected.</dd> +<dt><b>-s</b></dt> +<dd>Suppress the error messages ordinarily written for nonexistent or unreadable files. Other error messages shall not be +suppressed.</dd> +<dt><b>-v</b></dt> +<dd>Select lines not matching any of the specified patterns. If the <b>-v</b> option is not specified, selected lines shall be +those that match any of the specified patterns.</dd> +<dt><b>-x</b></dt> +<dd>Consider only input lines that use all characters in the line excluding the terminating <newline> to match an entire +fixed string or regular expression to be matching lines.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_55_05" id="tag_20_55_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>pattern_list</i></dt> +<dd>Specify one or more patterns to be used during the search for input. This operand shall be treated as if it were specified as +<b>-e</b> <i>pattern_list</i>.</dd> +<dt><i>file</i></dt> +<dd>A pathname of a file to be searched for the patterns. If no <i>file</i> operands are specified, the standard input shall be +used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_55_06" id="tag_20_55_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be used if no <i>file</i> operands are specified, and shall be used if a <i>file</i> operand is +<tt>'-'</tt> and the implementation treats the <tt>'-'</tt> as meaning standard input. Otherwise, the standard input shall not be +used. See the INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_55_07" id="tag_20_55_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files shall be text files.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_55_08" id="tag_20_55_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>grep</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_COLLATE</i></dt> +<dd><br> +Determine the locale for the behavior of ranges, equivalence classes, and multi-character collating elements within regular +expressions.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files) and the behavior of character classes within regular +expressions.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_55_09" id="tag_20_55_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_55_10" id="tag_20_55_10"></a>STDOUT</h4> +<blockquote> +<p>If the <b>-l</b> option is in effect, the following shall be written for each file containing at least one selected input +line:</p> +<pre> +<tt>"%s\n", <</tt><i>file</i><tt>> +</tt></pre> +<p>Otherwise, if more than one <i>file</i> argument appears, and <b>-q</b> is not specified, the <i>grep</i> utility shall prefix +each output line by:</p> +<pre> +<tt>"%s:", <</tt><i>file</i><tt>> +</tt></pre> +<p>The remainder of each output line shall depend on the other options specified:</p> +<ul> +<li> +<p>If the <b>-c</b> option is in effect, the remainder of each output line shall contain:</p> +<pre> +<tt>"%d\n", <</tt><i>count</i><tt>> +</tt></pre></li> +<li> +<p>Otherwise, if <b>-c</b> is not in effect and the <b>-n</b> option is in effect, the following shall be written to standard +output:</p> +<pre> +<tt>"%d:", <</tt><i>line number</i><tt>> +</tt></pre></li> +<li> +<p>Finally, the following shall be written to standard output:</p> +<pre> +<tt>"%s", <</tt><i>selected-line contents</i><tt>> +</tt></pre></li> +</ul> +</blockquote> +<h4 class="mansect"><a name="tag_20_55_11" id="tag_20_55_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_55_12" id="tag_20_55_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_55_13" id="tag_20_55_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_55_14" id="tag_20_55_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>One or more lines were selected and the output specified in STDOUT was successfully written to standard output.</dd> +<dt> 1</dt> +<dd>No lines were selected.</dd> +<dt>>1</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_55_15" id="tag_20_55_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>If the <b>-q</b> option is specified, the exit status shall be zero if an input line is selected, even if an error was detected. +Otherwise, default actions shall be performed.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_55_16" id="tag_20_55_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Care should be taken when using characters in <i>pattern_list</i> that may also be meaningful to the command interpreter. It is +safest to enclose the entire <i>pattern_list</i> argument in single-quotes:</p> +<pre> +<tt>'...' +</tt></pre> +<p>The <b>-e</b> <i>pattern_list</i> option has the same effect as the <i>pattern_list</i> operand, but is useful when +<i>pattern_list</i> begins with the <hyphen-minus> delimiter. It is also useful when it is more convenient to provide +multiple patterns as separate arguments.</p> +<p>Multiple <b>-e</b> and <b>-f</b> options are accepted and <i>grep</i> uses all of the patterns it is given while matching input +text lines. (Note that the order of evaluation is not specified. If an implementation finds a null string as a pattern, it is +allowed to use that pattern first, matching every line, and effectively ignore any other patterns.)</p> +<p>The <b>-q</b> option provides a means of easily determining whether or not a pattern (or string) exists in a group of files. +When searching several files, it provides a performance improvement (because it can quit as soon as it finds the first match) and +requires less care by the user in choosing the set of files to supply as arguments (because it exits zero if it finds a match even +if <i>grep</i> detected an access or read error on earlier <i>file</i> operands).</p> +<p>When using <i>grep</i> to process pathnames, it is recommended that LC_ALL, or at least LC_CTYPE and LC_COLLATE, are set to +POSIX or C in the environment, since pathnames can contain byte sequences that do not form valid characters in some locales, in +which case the utility's behavior would be undefined. In the POSIX locale each byte is a valid single-byte character, and therefore +this problem is avoided.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_55_17" id="tag_20_55_17"></a>EXAMPLES</h4> +<blockquote> +<ol> +<li> +<p>To find all uses of the word <tt>"Posix"</tt> (in any case) in file <b>text.mm</b> and write with line numbers:</p> +<pre> +<tt>grep -i -n posix text.mm +</tt></pre></li> +<li> +<p>To find all empty lines in the standard input:</p> +<pre> +<tt>grep ^$ +</tt></pre> +<p>or:</p> +<pre> +<tt>grep -v . +</tt></pre></li> +<li> +<p>Both of the following commands print all lines containing strings <tt>"abc"</tt> or <tt>"def"</tt> or both:</p> +<pre> +<tt>grep -E 'abc|def' +<br> +grep -F 'abc +def' +</tt></pre></li> +<li> +<p>Both of the following commands print all lines matching exactly <tt>"abc"</tt> or <tt>"def"</tt>:</p> +<pre> +<tt>grep -E '^abc$|^def$' +<br> +grep -F -x 'abc +def' +</tt></pre></li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_55_18" id="tag_20_55_18"></a>RATIONALE</h4> +<blockquote> +<p>This <i>grep</i> has been enhanced in an upwards-compatible way to provide the exact functionality of the historical +<i>egrep</i> and <i>fgrep</i> commands as well. It was the clear intention of the standard developers to consolidate the three +<i>grep</i>s into a single command.</p> +<p>The old <i>egrep</i> and <i>fgrep</i> commands are likely to be supported for many years to come as implementation extensions, +allowing historical applications to operate unmodified.</p> +<p>Historical implementations usually silently ignored all but one of multiply-specified <b>-e</b> and <b>-f</b> options, but were +not consistent as to which specification was actually used.</p> +<p>The <b>-b</b> option was omitted from the OPTIONS section because block numbers are implementation-defined.</p> +<p>The System V restriction on using <b>-</b> to mean standard input was omitted.</p> +<p>A definition of action taken when given a null BRE or ERE is specified. This is an error condition in some historical +implementations.</p> +<p>The <b>-l</b> option previously indicated that its use was undefined when no files were explicitly named. This behavior was +historical and placed an unnecessary restriction on future implementations. It has been removed.</p> +<p>The historical BSD <i>grep</i> <b>-s</b> option practice is easily duplicated by redirecting standard output to +<b>/dev/null</b>. The <b>-s</b> option required here is from System V.</p> +<p>The <b>-x</b> option, historically available only with <i>fgrep</i>, is available here for all of the non-obsolescent +versions.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_55_19" id="tag_20_55_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_55_20" id="tag_20_55_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/sed.html#"><i>sed</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap09.html#tag_09"><i>9. Regular Expressions</i></a> , <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 +Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_55_21" id="tag_20_55_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_55_22" id="tag_20_55_22"></a>Issue 6</h4> +<blockquote> +<p>The Open Group Corrigendum U029/5 is applied, correcting the SYNOPSIS.</p> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +<p>IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/28 is applied, correcting the examples using the <i>grep</i> +<b>-F</b> option which did not match the normative description of the <b>-F</b> option.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_55_23" id="tag_20_55_23"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #092 is applied.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>SD5-XCU-ERN-98 is applied, updating the STDOUT section.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0105 [584] and XCU/TC2-2008/0106 [663] are applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_55_24" id="tag_20_55_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to report an error if a utility is directed to display a +pathname that contains any bytes that have the encoded value of a <newline> character when <newline> is a terminator or +separator in the output format being used.</p> +<p>Austin Group Defect 1031 is applied, changing the description of the <b>-i</b> option.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1502 is applied, changing the EXIT STATUS section.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/gettext.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/hash.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/hash.html b/bdd/hash.html @@ -0,0 +1,228 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>hash</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/grep.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/head.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="hash" id="hash"></a> <a name="tag_20_56" id="tag_20_56"></a><!-- hash --> +<h4 class="mansect"><a name="tag_20_56_01" id="tag_20_56_01"></a>NAME</h4> +<blockquote>hash — remember or report utility locations</blockquote> +<h4 class="mansect"><a name="tag_20_56_02" id="tag_20_56_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>hash</tt> <b>[</b><i>utility</i><tt>...</tt><b>]</b> <tt><br> +<br> +hash -r<br></tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_56_03" id="tag_20_56_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>hash</i> utility shall affect the way the current shell environment remembers the locations of utilities found as +described in <a href="../utilities/V3_chap02.html#tag_19_09_01_04"><i>2.9.1.4 Command Search and Execution</i></a> . Depending on +the arguments specified, it shall add utility locations to its list of remembered locations or it shall purge the contents of the +list. When no arguments are specified, it shall report on the contents of the list.</p> +<p>Utilities provided as built-ins to the shell and functions shall not be reported by <i>hash</i>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_56_04" id="tag_20_56_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>hash</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following option shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-r</b></dt> +<dd>Forget all previously remembered utility locations.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_56_05" id="tag_20_56_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>utility</i></dt> +<dd>The name of a utility to be searched for and added to the list of remembered locations. If the search does not find +<i>utility</i>, it is unspecified whether or not this is treated as an error. If <i>utility</i> contains one or more <slash> +characters, the results are unspecified.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_56_06" id="tag_20_56_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_56_07" id="tag_20_56_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_56_08" id="tag_20_56_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>hash</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>PATH</i></dt> +<dd>Determine the location of <i>utility</i>, as described in XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment +Variables</i></a> .</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_56_09" id="tag_20_56_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_56_10" id="tag_20_56_10"></a>STDOUT</h4> +<blockquote> +<p>The standard output of <i>hash</i> shall be used when no arguments are specified. Its format is unspecified, but includes the +pathname of each utility in the list of remembered locations for the current shell environment. This list shall consist of those +utilities named in previous <i>hash</i> invocations that have been invoked, and may contain those invoked and found through the +normal command search process. This list shall be cleared when the contents of the <i>PATH</i> environment variable are +changed.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_56_11" id="tag_20_56_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_56_12" id="tag_20_56_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_56_13" id="tag_20_56_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_56_14" id="tag_20_56_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_56_15" id="tag_20_56_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_56_16" id="tag_20_56_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>This utility is required to be intrinsic. See <a href="../utilities/V3_chap01.html#tag_18_07"><i>1.7 Intrinsic Utilities</i></a> +for details.</p> +<p>Since <i>hash</i> affects the current shell execution environment, it is always provided as a shell regular built-in. If it is +called in a separate utility execution environment, such as one of the following:</p> +<pre> +<tt>nohup hash -r +find . -type f -exec hash {} + +</tt></pre> +<p>it does not affect the command search process of the caller's environment.</p> +<p>The <i>hash</i> utility may be implemented as an alias—for example, <a href="../utilities/alias.html"><i>alias</i></a> +<b>-t -</b>, in which case utilities found through normal command search are not listed by the <i>hash</i> command.</p> +<p>The effects of <i>hash</i> <b>-r</b> can also be achieved portably by resetting the value of <i>PATH ;</i> in the simplest form, +this can be:</p> +<pre> +<tt>PATH="$PATH" +</tt></pre> +<p>The use of <i>hash</i> with <i>utility</i> names is unnecessary for most applications, but may provide a performance improvement +on a few implementations; normally, the hashing process is included by default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_56_17" id="tag_20_56_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_56_18" id="tag_20_56_18"></a>RATIONALE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_56_19" id="tag_20_56_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_56_20" id="tag_20_56_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19_09_01_04"><i>2.9.1.4 Command Search and Execution</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_56_21" id="tag_20_56_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_56_22" id="tag_20_56_22"></a>Issue 7</h4> +<blockquote> +<p>The <i>hash</i> utility is moved from the XSI option to the Base.</p> +<p>POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0093 [241] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_56_23" id="tag_20_56_23"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 248 is applied, changing a command line in the APPLICATION USAGE section.</p> +<p>Austin Group Defect 251 is applied, encouraging implementations to report an error if a utility is directed to display a +pathname that contains any bytes that have the encoded value of a <newline> character when <newline> is a terminator or +separator in the output format being used.</p> +<p>Austin Group Defect 854 is applied, adding a note to the APPLICATION USAGE section that this utility is required to be +intrinsic.</p> +<p>Austin Group Defect 1063 is applied, clarifying that functions are not reported by <i>hash</i>, and that the list of remembered +locations is cleared when the contents of <i>PATH</i> are changed.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1460 is applied, making it explicitly unspecified whether or not <i>hash</i> reports an error if it cannot +find <i>utility</i>.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/grep.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/head.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/head.html b/bdd/head.html @@ -0,0 +1,242 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>head</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/hash.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/iconv.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="head" id="head"></a> <a name="tag_20_57" id="tag_20_57"></a><!-- head --> +<h4 class="mansect"><a name="tag_20_57_01" id="tag_20_57_01"></a>NAME</h4> +<blockquote>head — copy the first part of files</blockquote> +<h4 class="mansect"><a name="tag_20_57_02" id="tag_20_57_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>head</tt> <b>[</b><tt>-c</tt> <i>number</i><tt>|-n</tt> <i>number</i><b>] [</b><i>file</i><tt>...</tt><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_57_03" id="tag_20_57_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>head</i> utility shall copy its input files to the standard output, ending the output for each file at a designated +point.</p> +<p>Copying shall end at the point in the file indicated by the <b>-c</b> <i>number</i> or <b>-n</b> <i>number</i> options. The +option-argument <i>number</i> shall be counted in units of lines or bytes, according to the options <b>-n</b> and <b>-c</b>. Both +line and byte counts start from 1.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_57_04" id="tag_20_57_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>head</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-c </b><i>number</i></dt> +<dd>The first <i>number</i> bytes of each input file shall be copied to standard output. The application shall ensure that the +<i>number</i> option-argument is a positive decimal integer.</dd> +<dt><b>-n </b><i>number</i></dt> +<dd>This option shall be equivalent to <b>-c</b> <i>number</i>, except that the ending location in the file shall be measured in +lines instead of bytes.</dd> +</dl> +<p>When a file contains less than <i>number</i> bytes or lines, it shall be copied to standard output in its entirety. This shall +not be an error.</p> +<p>If no options are specified, <i>head</i> shall act as if <b>-n 10</b> had been specified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_57_05" id="tag_20_57_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of an input file. If no <i>file</i> operands are specified, the standard input shall be used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_57_06" id="tag_20_57_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be used if no <i>file</i> operands are specified, and shall be used if a <i>file</i> operand is +<tt>'-'</tt> and the implementation treats the <tt>'-'</tt> as meaning standard input. Otherwise, the standard input shall not be +used. See the INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_57_07" id="tag_20_57_07"></a>INPUT FILES</h4> +<blockquote> +<p>If the <b>-c</b> option is specified, the input files can contain arbitrary data; otherwise, the input files shall be text +files, but the line length shall not be restricted to {LINE_MAX} bytes.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_57_08" id="tag_20_57_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>head</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_57_09" id="tag_20_57_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_57_10" id="tag_20_57_10"></a>STDOUT</h4> +<blockquote> +<p>The standard output shall contain designated portions of the input files.</p> +<p>If multiple <i>file</i> operands are specified, <i>head</i> shall precede the output for each with the header:</p> +<pre> +<tt>"\n==> %s <==\n", <</tt><i>pathname</i><tt>> +</tt></pre> +<p>except that the first header written shall not include the initial <newline>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_57_11" id="tag_20_57_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_57_12" id="tag_20_57_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_57_13" id="tag_20_57_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_57_14" id="tag_20_57_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_57_15" id="tag_20_57_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_57_16" id="tag_20_57_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>When using <i>head</i> to process pathnames, it is recommended that LC_ALL, or at least LC_CTYPE and LC_COLLATE, are set to +POSIX or C in the environment, since pathnames can contain byte sequences that do not form valid characters in some locales, in +which case the utility's behavior would be undefined. In the POSIX locale each byte is a valid single-byte character, and therefore +this problem is avoided.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_57_17" id="tag_20_57_17"></a>EXAMPLES</h4> +<blockquote> +<p>To write the first ten lines of all files (except those with a leading period) in the directory:</p> +<pre> +<tt>head -- * +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_57_18" id="tag_20_57_18"></a>RATIONALE</h4> +<blockquote> +<p>Although it is possible to simulate <i>head</i> with <a href="../utilities/sed.html"><i>sed</i></a> 10q for a single file, the +standard developers decided that the popularity of <i>head</i> on historical BSD systems warranted its inclusion alongside <a href= +"../utilities/tail.html"><i>tail</i></a>.</p> +<p>POSIX.1-2024 version of <i>head</i> follows the Utility Syntax Guidelines. The <b>-n</b> option was added to this new interface +so that <i>head</i> and <a href="../utilities/tail.html"><i>tail</i></a> would be more logically related. Earlier versions of this +standard allowed a <b>-number</b> option. This form is no longer specified by POSIX.1-2024 but may be present in some +implementations.</p> +<p>The <i>head</i> and <a href="../utilities/tail.html"><i>tail</i></a> utilities have not historically been symmetric. For +example, this standard only requires <a href="../utilities/tail.html"><i>tail</i></a> to support at most one file operand, while +<i>head</i> must operate on multiple files. Conversely, this standard requires <a href="../utilities/tail.html"><i>tail</i></a> to +be able to start at a position relative to the start of a file, but <i>head</i> need not support stopping at a position relative to +the end of the file. Implementations may choose to make <i>head</i> and <a href="../utilities/tail.html"><i>tail</i></a> symmetric +as an extension, but applications should not rely on this.</p> +<p>Older implementations of <i>head</i> did not support <b>-c</b> <i>number</i>, but emulating this via <tt>dd ibs=1 +count=number</tt> is much less efficient and emulating via <tt>dd obs=pipe_buf | dd ibs=size count=number_of_blocks</tt> is +cumbersome, somewhat less efficient, and can only be used if the number of bytes to be copied is a multiple of a suitable block +size less than or equal to {PIPE_BUF}.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_57_19" id="tag_20_57_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_57_20" id="tag_20_57_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/dd.html#"><i>dd</i></a> , <a href="../utilities/sed.html#"><i>sed</i></a> , <a href= +"../utilities/tail.html#"><i>tail</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_57_21" id="tag_20_57_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_57_22" id="tag_20_57_22"></a>Issue 6</h4> +<blockquote> +<p>The obsolescent <b>-number</b> form is removed.</p> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +<p>The DESCRIPTION is updated to clarify that when a file contains less than the number of lines requested, the entire file is +copied to standard output.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_57_23" id="tag_20_57_23"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretations 1003.1-2001 #027 and #092 are applied.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>The APPLICATION USAGE section is removed and the EXAMPLES section is corrected.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0107 [663] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_57_24" id="tag_20_57_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to report an error if a utility is directed to display a +pathname that contains any bytes that have the encoded value of a <newline> character when <newline> is a terminator or +separator in the output format being used.</p> +<p>Austin Group Defect 407 is applied, adding the <b>-c</b> <i>number</i> option.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/hash.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/iconv.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/iconv.html b/bdd/iconv.html @@ -0,0 +1,264 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>iconv</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/head.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/id.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="iconv" id="iconv"></a> <a name="tag_20_58" id="tag_20_58"></a><!-- iconv --> +<h4 class="mansect"><a name="tag_20_58_01" id="tag_20_58_01"></a>NAME</h4> +<blockquote>iconv — codeset conversion</blockquote> +<h4 class="mansect"><a name="tag_20_58_02" id="tag_20_58_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>iconv</tt> <b>[</b><tt>-cs</tt><b>]</b> <tt>-f</tt> <i>frommap</i> <tt>-t</tt> <i>tomap</i> +<b>[</b><i>file</i><tt>...</tt><b>]</b> <tt><br> +<br> +iconv -f</tt> <i>fromcode</i> <b>[</b><tt>-cs</tt><b>] [</b><tt>-t</tt> <i>tocode</i><b>] [</b><i>file</i><tt>...</tt><b>]</b> +<tt><br> +<br> +iconv -t</tt> <i>tocode</i> <b>[</b><tt>-cs</tt><b>] [</b><tt>-f</tt> <i>fromcode</i><b>] [</b><i>file</i><tt>...</tt><b>]</b> +<tt><br> +<br> +iconv -l<br></tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_58_03" id="tag_20_58_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>iconv</i> utility shall convert the encoding of characters in <i>file</i> from one codeset to another and write the +results to standard output.</p> +<p>When the options indicate that charmap files are used to specify the codesets (see OPTIONS), the codeset conversion shall be +accomplished by performing a logical join on the symbolic character names in the two charmaps. The implementation need not support +the use of charmap files for codeset conversion unless the POSIX2_LOCALEDEF symbol is defined on the system.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_58_04" id="tag_20_58_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>iconv</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-c</b></dt> +<dd>Omit any characters that are invalid in the codeset of the input file from the output. When <b>-c</b> is not used, the results +of encountering invalid characters in the input stream (either those that are not characters in the codeset of the input file or +that have no corresponding character in the codeset of the output file) shall be specified in the system documentation. The +presence or absence of <b>-c</b> shall not affect the exit status of <i>iconv</i>.</dd> +<dt><b>-f </b><i>fromcodeset</i></dt> +<dd><br> +Identify the codeset of the input file. The implementation shall recognize the following two forms of the <i>fromcodeset</i> +option-argument: +<dl compact> +<dd></dd> +<dt><i>fromcode</i></dt> +<dd>The <i>fromcode</i> option-argument can not contain a <slash> character. It shall be interpreted as the name of one of +the codeset descriptions provided by the implementation in an unspecified format. Valid values of <i>fromcode</i> are +implementation-defined.</dd> +<dt><i>frommap</i></dt> +<dd>The <i>frommap</i> option-argument needs to contain a <slash> character. It shall be interpreted as the pathname of a +charmap file as defined in XBD <a href="../basedefs/V1_chap06.html#tag_06_04"><i>6.4 Character Set Description File</i></a> . If +the pathname does not represent a valid, readable charmap file, the results are undefined.</dd> +</dl> +<p>If this option is omitted, the codeset of the current locale shall be used.</p> +</dd> +<dt><b>-l</b></dt> +<dd>Write all supported <i>fromcode</i> and <i>tocode</i> values to standard output in an unspecified format.</dd> +<dt><b>-s</b></dt> +<dd>Suppress any messages written to standard error concerning invalid characters. When <b>-s</b> is not used, the results of +encountering invalid characters in the input stream (either those that are not valid characters in the codeset of the input file or +that have no corresponding character in the codeset of the output file) shall be specified in the system documentation. The +presence or absence of <b>-s</b> shall not affect the exit status of <i>iconv</i>.</dd> +<dt><b>-t </b><i>tocodeset</i></dt> +<dd>Identify the codeset to be used for the output file. The implementation shall recognize the following two forms of the +<i>tocodeset</i> option-argument: +<dl compact> +<dd></dd> +<dt><i>tocode</i></dt> +<dd>The semantics shall be equivalent to the <b>-f</b> <i>fromcode</i> option.</dd> +<dt><i>tomap</i></dt> +<dd>The semantics shall be equivalent to the <b>-f</b> <i>frommap</i> option.</dd> +</dl> +<p>If this option is omitted, the codeset of the current locale shall be used.</p> +</dd> +</dl> +<p>If either <b>-f</b> or <b>-t</b> represents a charmap file, but the other does not (or is omitted), or both <b>-f</b> and +<b>-t</b> are omitted, the results are undefined.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_58_05" id="tag_20_58_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of an input file. If no <i>file</i> operands are specified, or if a <i>file</i> operand is <tt>'-'</tt>, the +standard input shall be used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_58_06" id="tag_20_58_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be used only if no <i>file</i> operands are specified, or if a <i>file</i> operand is <tt>'-'</tt>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_58_07" id="tag_20_58_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input file shall be a text file.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_58_08" id="tag_20_58_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>iconv</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). During translation of the file, this variable is superseded by the use of the +<i>fromcode</i> option-argument.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_58_09" id="tag_20_58_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_58_10" id="tag_20_58_10"></a>STDOUT</h4> +<blockquote> +<p>When the <b>-l</b> option is used, the standard output shall contain all supported <i>fromcode</i> and <i>tocode</i> values, +written in an unspecified format.</p> +<p>When the <b>-l</b> option is not used, the standard output shall contain the sequence of characters read from the input files, +translated to the specified codeset. Nothing else shall be written to the standard output.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_58_11" id="tag_20_58_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_58_12" id="tag_20_58_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_58_13" id="tag_20_58_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_58_14" id="tag_20_58_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_58_15" id="tag_20_58_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_58_16" id="tag_20_58_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The user must ensure that both charmap files use the same symbolic names for characters the two codesets have in common.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_58_17" id="tag_20_58_17"></a>EXAMPLES</h4> +<blockquote> +<p>The following example converts the contents of file <b>mail.x400</b> from the ISO/IEC 6937:2001 standard codeset to the +ISO/IEC 8859-1:1998 standard codeset, and stores the results in file <b>mail.local</b>:</p> +<pre> +<tt>iconv -f IS6937 -t IS8859 mail.x400 > mail.local +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_58_18" id="tag_20_58_18"></a>RATIONALE</h4> +<blockquote> +<p>The <i>iconv</i> utility can be used portably only when the user provides two charmap files as option-arguments. This is because +a single charmap provided by the user cannot reliably be joined with the names in a system-provided character set description. The +valid values for <i>fromcode</i> and <i>tocode</i> are implementation-defined and do not have to have any relation to the charmap +mechanisms. As an aid to interactive users, the <b>-l</b> option was adopted from the Plan 9 operating system. It writes +information concerning these implementation-defined values. The format is unspecified because there are many possible useful +formats that could be chosen, such as a matrix of valid combinations of <i>fromcode</i> and <i>tocode</i>. The <b>-l</b> option is +not intended for shell script usage; conforming applications will have to use charmaps.</p> +<p>The <i>iconv</i> utility may support the conversion between ASCII and EBCDIC-based encodings, but is not required to do so. In +an XSI-compliant implementation, the <a href="../utilities/dd.html"><i>dd</i></a> utility is the only method guaranteed to support +conversion between these two character sets.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_58_19" id="tag_20_58_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_58_20" id="tag_20_58_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/dd.html#"><i>dd</i></a> , <a href="../utilities/gencat.html#"><i>gencat</i></a></p> +<p>XBD <a href="../basedefs/V1_chap06.html#tag_06_04"><i>6.4 Character Set Description File</i></a> , <a href= +"../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 +Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_58_21" id="tag_20_58_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 3.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_58_22" id="tag_20_58_22"></a>Issue 6</h4> +<blockquote> +<p>This utility has been rewritten to align with the IEEE P1003.2b draft standard. Specifically, the ability to use charmap +files for conversion has been added.</p> +<p>IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/29 is applied, making changes to address inconsistencies with +the <a href="../functions/iconv.html"><i>iconv</i>()</a> function in the System Interfaces volume of POSIX.1-2024.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_58_23" id="tag_20_58_23"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #206 is applied, correcting the <i>tomap</i> option.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0094 [291] and XCU/TC1-2008/0095 [291] are applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_58_24" id="tag_20_58_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/head.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/id.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/id.html b/bdd/id.html @@ -0,0 +1,276 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>id</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/iconv.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/ipcrm.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="id" id="id"></a> <a name="tag_20_59" id="tag_20_59"></a><!-- id --> +<h4 class="mansect"><a name="tag_20_59_01" id="tag_20_59_01"></a>NAME</h4> +<blockquote>id — return user identity</blockquote> +<h4 class="mansect"><a name="tag_20_59_02" id="tag_20_59_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>id</tt> <b>[</b><i>user</i><b>]</b> <tt><br> +<br> +id -G</tt> <b>[</b><tt>-n</tt><b>] [</b><i>user</i><b>]</b> <tt><br> +<br> +id -g</tt> <b>[</b><tt>-nr</tt><b>] [</b><i>user</i><b>]</b> <tt><br> +<br> +id -u</tt> <b>[</b><tt>-nr</tt><b>] [</b><i>user</i><b>]</b> <tt><br></tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_59_03" id="tag_20_59_03"></a>DESCRIPTION</h4> +<blockquote> +<p>If no <i>user</i> operand is provided, the <i>id</i> utility shall write the user and group IDs and the corresponding user and +group names of the invoking process to standard output. If the effective and real IDs do not match, both shall be written. If +multiple groups are supported by the underlying system (see the description of {NGROUPS_MAX} in the System Interfaces volume of +POSIX.1-2024), the supplementary group affiliations of the invoking process shall also be written.</p> +<p>If a <i>user</i> operand is provided and the process has appropriate privileges, the user and group IDs of the selected user +shall be written. In this case, effective IDs shall be assumed to be identical to real IDs. If the selected user has more than one +allowable group membership listed in the group database, these shall be written in the same manner as the supplementary groups +described in the preceding paragraph.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_59_04" id="tag_20_59_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>id</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-G</b></dt> +<dd>Output all different group IDs (effective, real, and supplementary) only, using the format <tt>"%u\n"</tt>. If there is more +than one distinct group affiliation, output each such affiliation, using the format <tt>" %u"</tt>, before the <newline> +is output.</dd> +<dt><b>-g</b></dt> +<dd>Output only the effective group ID, using the format <tt>"%u\n"</tt>.</dd> +<dt><b>-n</b></dt> +<dd>Output the name in the format <tt>"%s"</tt> instead of the numeric ID using the format <tt>"%u"</tt>.</dd> +<dt><b>-r</b></dt> +<dd>Output the real ID instead of the effective ID.</dd> +<dt><b>-u</b></dt> +<dd>Output only the effective user ID, using the format <tt>"%u\n"</tt>.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_59_05" id="tag_20_59_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>user</i></dt> +<dd>The login name for which information is to be written.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_59_06" id="tag_20_59_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_59_07" id="tag_20_59_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_59_08" id="tag_20_59_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>id</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error and +informative messages written to standard output.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_59_09" id="tag_20_59_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_59_10" id="tag_20_59_10"></a>STDOUT</h4> +<blockquote> +<p>The following formats shall be used when the <i>LC_MESSAGES</i> locale category specifies the POSIX locale. In other locales, +the strings <i>uid</i>, <i>gid</i>, <i>euid</i>, <i>egid</i>, and <i>groups</i> may be replaced with more appropriate strings +corresponding to the locale.</p> +<pre> +<tt>"uid=%u(%s) gid=%u(%s)\n", <</tt><i>real user ID</i><tt>>, <</tt><i>user-name</i><tt>>, + <</tt><i>real group ID</i><tt>>, <</tt><i>group-name</i><tt>> +</tt></pre> +<p>If the effective and real user IDs do not match, the following shall be inserted immediately before the <tt>'\n'</tt> character +in the previous format:</p> +<pre> +<tt>" euid=%u(%s)" +</tt></pre> +<p>with the following arguments added at the end of the argument list:</p> +<pre> +<tt><</tt><i>effective user ID</i><tt>>, <</tt><i>effective user-name</i><tt>> +</tt></pre> +<p>If the effective and real group IDs do not match, the following shall be inserted directly before the <tt>'\n'</tt> character in +the format string (and after any addition resulting from the effective and real user IDs not matching):</p> +<pre> +<tt>" egid=%u(%s)" +</tt></pre> +<p>with the following arguments added at the end of the argument list:</p> +<pre> +<tt><</tt><i>effective group-ID</i><tt>>, <</tt><i>effective group name</i><tt>> +</tt></pre> +<p>If the process has supplementary group affiliations or the selected user is allowed to belong to multiple groups, the first +shall be added directly before the <newline> in the format string:</p> +<pre> +<tt>" groups=%u(%s)" +</tt></pre> +<p>with the following arguments added at the end of the argument list:</p> +<pre> +<tt><</tt><i>supplementary group ID</i><tt>>, <</tt><i>supplementary group name</i><tt>> +</tt></pre> +<p>and the necessary number of the following added after that for any remaining supplementary group IDs:</p> +<pre> +<tt>",%u(%s)" +</tt></pre> +<p>and the necessary number of the following arguments added at the end of the argument list:</p> +<pre> +<tt><</tt><i>supplementary group ID</i><tt>>, <</tt><i>supplementary group name</i><tt>> +</tt></pre> +<p>If any of the user ID, group ID, effective user ID, effective group ID, or supplementary/multiple group IDs cannot be mapped by +the system into printable user or group names, the corresponding <tt>"(%s)"</tt> and <i>name</i> argument shall be omitted from the +corresponding format string.</p> +<p>When any of the options are specified, the output format shall be as described in the OPTIONS section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_59_11" id="tag_20_59_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_59_12" id="tag_20_59_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_59_13" id="tag_20_59_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_59_14" id="tag_20_59_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_59_15" id="tag_20_59_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_59_16" id="tag_20_59_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Output produced by the <b>-G</b> option and by the default case could potentially produce very long lines on systems that +support large numbers of supplementary groups. (On systems with user and group IDs that are 32-bit integers and with group names +with a maximum of 8 bytes per name, 93 supplementary groups plus distinct effective and real group and user IDs could theoretically +overflow the 2048-byte {LINE_MAX} text file line limit on the default output case. It would take about 186 supplementary groups to +overflow the 2048-byte barrier using <i>id</i> <b>-G</b>). This is not expected to be a problem in practice, but in cases where it +is a concern, applications should consider using <a href="../utilities/fold.html"><i>fold</i></a> <b>-s</b> before post-processing +the output of <i>id</i>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_59_17" id="tag_20_59_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_59_18" id="tag_20_59_18"></a>RATIONALE</h4> +<blockquote> +<p>The functionality provided by the 4 BSD <i>groups</i> utility can be simulated using:</p> +<pre> +<tt>id -Gn [ user ] +</tt></pre> +<p>The 4 BSD command <i>groups</i> was considered, but it was not included because it did not provide the functionality of the +<i>id</i> utility of the SVID. Also, it was thought that it would be easier to modify <i>id</i> to provide the additional +functionality necessary to systems with multiple groups than to invent another command.</p> +<p>The options <b>-u</b>, <b>-g</b>, <b>-n</b>, and <b>-r</b> were added to ease the use of <i>id</i> with shell commands +substitution. Without these options it is necessary to use some preprocessor such as <a href="../utilities/sed.html"><i>sed</i></a> +to select the desired piece of information. Since output such as that produced by:</p> +<pre> +<tt>id -u -n +</tt></pre> +<p>is frequently wanted, it seemed desirable to add the options.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_59_19" id="tag_20_59_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_59_20" id="tag_20_59_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/fold.html#"><i>fold</i></a> , <a href="../utilities/logname.html#"><i>logname</i></a> , <a href= +"../utilities/who.html#"><i>who</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/getgid.html#"><i>getgid</i></a> , <a href="../functions/getgroups.html#"><i>getgroups</i></a> , +<a href="../functions/getuid.html#"><i>getuid</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_59_21" id="tag_20_59_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_59_22" id="tag_20_59_22"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_59_23" id="tag_20_59_23"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/iconv.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/ipcrm.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/ipcrm.html b/bdd/ipcrm.html @@ -0,0 +1,201 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>ipcrm</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/id.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/ipcs.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="ipcrm" id="ipcrm"></a> <a name="tag_20_60" id="tag_20_60"></a><!-- ipcrm --> +<h4 class="mansect"><a name="tag_20_60_01" id="tag_20_60_01"></a>NAME</h4> +<blockquote>ipcrm — remove an XSI message queue, semaphore set, or shared memory segment identifier</blockquote> +<h4 class="mansect"><a name="tag_20_60_02" id="tag_20_60_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> ipcrm</tt> <b>[</b><tt>-q msgid|-Q msgkey|-s semid|-S semkey|-m shmid|-M shmkey</tt><b>]</b><tt>... +<img src="../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div> +</blockquote> +<h4 class="mansect"><a name="tag_20_60_03" id="tag_20_60_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>ipcrm</i> utility shall remove zero or more message queues, semaphore sets, or shared memory segments. The interprocess +communication facilities to be removed are specified by the options.</p> +<p>Only a user with appropriate privileges shall be allowed to remove an interprocess communication facility that was not created +by or owned by the user invoking <i>ipcrm</i>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_60_04" id="tag_20_60_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>ipcrm</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-q </b><i>msgid</i></dt> +<dd>Remove the message queue identifier <i>msgid</i> from the system and destroy the message queue and data structure associated +with it.</dd> +<dt><b>-m </b><i>shmid</i></dt> +<dd>Remove the shared memory identifier <i>shmid</i> from the system. The shared memory segment and data structure associated with +it shall be destroyed when all processes with the segment attached have either detached the segment or terminated. If the segment +is not attached to any process, it shall be destroyed immediately.</dd> +<dt><b>-s </b><i>semid</i></dt> +<dd>Remove the semaphore identifier <i>semid</i> from the system and destroy the set of semaphores and data structure associated +with it.</dd> +<dt><b>-Q </b><i>msgkey</i></dt> +<dd>Remove the message queue identifier, created with key <i>msgkey</i>, from the system and destroy the message queue and data +structure associated with it.</dd> +<dt><b>-M </b><i>shmkey</i></dt> +<dd>Remove the shared memory identifier, created with key <i>shmkey</i>, from the system. The shared memory segment and data +structure associated with it shall be destroyed after the last detach.</dd> +<dt><b>-S </b><i>semkey</i></dt> +<dd>Remove the semaphore identifier, created with key <i>semkey</i>, from the system and destroy the set of semaphores and data +structure associated with it.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_60_05" id="tag_20_60_05"></a>OPERANDS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_60_06" id="tag_20_60_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_60_07" id="tag_20_60_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_60_08" id="tag_20_60_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>ipcrm</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd>Determine the location of messages objects and message catalogs.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_60_09" id="tag_20_60_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_60_10" id="tag_20_60_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_60_11" id="tag_20_60_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_60_12" id="tag_20_60_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_60_13" id="tag_20_60_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_60_14" id="tag_20_60_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_60_15" id="tag_20_60_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_60_16" id="tag_20_60_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_60_17" id="tag_20_60_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_60_18" id="tag_20_60_18"></a>RATIONALE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_60_19" id="tag_20_60_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_60_20" id="tag_20_60_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/ipcs.html#"><i>ipcs</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/msgctl.html#"><i>msgctl</i></a> , <a href="../functions/semctl.html#"><i>semctl</i></a> , <a href= +"../functions/shmctl.html#"><i>shmctl</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_60_21" id="tag_20_60_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 5.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_60_22" id="tag_20_60_22"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_60_23" id="tag_20_60_23"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1240 is applied, clarifying the description of the <b>-m</b> option.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/id.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/ipcs.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/ipcs.html b/bdd/ipcs.html @@ -0,0 +1,448 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>ipcs</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/ipcrm.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/jobs.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="ipcs" id="ipcs"></a> <a name="tag_20_61" id="tag_20_61"></a><!-- ipcs --> +<h4 class="mansect"><a name="tag_20_61_01" id="tag_20_61_01"></a>NAME</h4> +<blockquote>ipcs — report XSI interprocess communication facilities status</blockquote> +<h4 class="mansect"><a name="tag_20_61_02" id="tag_20_61_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> ipcs</tt> <b>[</b><tt>-qms</tt><b>] [</b><tt>-a|-bcopt</tt><b>]</b> <tt><img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div> +</blockquote> +<h4 class="mansect"><a name="tag_20_61_03" id="tag_20_61_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>ipcs</i> utility shall write information about active interprocess communication facilities.</p> +<p>Without options, information shall be written in short format for message queues, shared memory segments, and semaphore sets +that are currently active in the system. Otherwise, the information that is displayed is controlled by the options specified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_61_04" id="tag_20_61_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>ipcs</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The <i>ipcs</i> utility accepts the following options:</p> +<dl compact> +<dd></dd> +<dt><b>-q</b></dt> +<dd>Write information about active message queues.</dd> +<dt><b>-m</b></dt> +<dd>Write information about active shared memory segments.</dd> +<dt><b>-s</b></dt> +<dd>Write information about active semaphore sets.</dd> +</dl> +<p>If <b>-q</b>, <b>-m</b>, or <b>-s</b> are specified, only information about those facilities shall be written. If none of these +three are specified, information about all three shall be written subject to the following options:</p> +<dl compact> +<dd></dd> +<dt><b>-a</b></dt> +<dd>Use all print options. (This is a shorthand notation for <b>-b</b>, <b>-c</b>, <b>-o</b>, <b>-p</b>, and <b>-t</b>.)</dd> +<dt><b>-b</b></dt> +<dd>Write information on maximum allowable size. (Maximum number of bytes in messages on queue for message queues, size of segments +for shared memory, and number of semaphores in each set for semaphores.)</dd> +<dt><b>-c</b></dt> +<dd>Write creator's user name and group name; see below.</dd> +<dt><b>-o</b></dt> +<dd>Write information on outstanding usage. (Number of messages on queue and total number of bytes in messages on queue for message +queues, and number of processes attached to shared memory segments.)</dd> +<dt><b>-p</b></dt> +<dd>Write process number information. (Process ID of the last process to send a message and process ID of the last process to +receive a message on message queues, process ID of the creating process, and process ID of the last process to attach or detach on +shared memory segments.)</dd> +<dt><b>-t</b></dt> +<dd>Write time information. (Time of the last control operation that changed the access permissions for all facilities, time of the +last <a href="../functions/msgsnd.html"><i>msgsnd</i>()</a> and <a href="../functions/msgrcv.html"><i>msgrcv</i>()</a> operations +on message queues, time of the last <a href="../functions/shmat.html"><i>shmat</i>()</a> and <a href= +"../functions/shmdt.html"><i>shmdt</i>()</a> operations on shared memory, and time of the last <a href= +"../functions/semop.html"><i>semop</i>()</a> operation on semaphores.)</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_61_05" id="tag_20_61_05"></a>OPERANDS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_61_06" id="tag_20_61_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_61_07" id="tag_20_61_07"></a>INPUT FILES</h4> +<blockquote> +<ul> +<li> +<p>The group database</p> +</li> +<li> +<p>The user database</p> +</li> +</ul> +</blockquote> +<h4 class="mansect"><a name="tag_20_61_08" id="tag_20_61_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>ipcs</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd>Determine the location of messages objects and message catalogs.</dd> +<dt><i>TZ</i></dt> +<dd>Determine the timezone for the date and time strings written by <i>ipcs</i>. If <i>TZ</i> is unset or null, an unspecified +default timezone shall be used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_61_09" id="tag_20_61_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_61_10" id="tag_20_61_10"></a>STDOUT</h4> +<blockquote> +<p>An introductory line shall be written with the format:</p> +<pre> +<tt>"IPC status from %s as of %s\n", <</tt><i>source</i><tt>>, <</tt><i>date</i><tt>> +</tt></pre> +<p>where <<i>source</i>> indicates the source used to gather the statistics and <<i>date</i>> is the information that +would be produced by the <a href="../utilities/date.html"><i>date</i></a> command when invoked in the POSIX locale.</p> +<p>The <i>ipcs</i> utility then shall create up to three reports depending upon the <b>-q</b>, <b>-m</b>, and <b>-s</b> options. +The first report shall indicate the status of message queues, the second report shall indicate the status of shared memory +segments, and the third report shall indicate the status of semaphore sets.</p> +<p>If the corresponding facility is not installed or has not been used since the last reboot, then the report shall be written out +in the format:</p> +<pre> +<tt>"%s facility not in system.\n", <</tt><i>facility</i><tt>> +</tt></pre> +<p>where <<i>facility</i>> is <i>Message Queue</i>, <i>Shared Memory</i>, or <i>Semaphore</i>, as appropriate. If the +facility has been installed and has been used since the last reboot, column headings separated by one or more <space> +characters and followed by a <newline> shall be written as indicated below followed by the facility name written out using +the format:</p> +<pre> +<tt>"%s:\n", <</tt><i>facility</i><tt>> +</tt></pre> +<p>where <<i>facility</i>> is <i>Message Queues</i>, <i>Shared Memory</i>, or <i>Semaphores</i>, as appropriate. On the +second and third reports the column headings need not be written if the last column headings written already provide column +headings for all information in that report.</p> +<p>The column headings provided in the first column below and the meaning of the information in those columns shall be given in +order below; the letters in parentheses indicate the options that shall cause the corresponding column to appear; "all" means +that the column shall always appear. Each column is separated by one or more <space> characters. Note that these options only +determine what information is provided for each report; they do not determine which reports are written.</p> +<dl compact> +<dd></dd> +<dt>T (all)</dt> +<dd>Type of facility: +<dl compact> +<dd></dd> +<dt><tt>q</tt></dt> +<dd>Message queue.</dd> +<dt><tt>m</tt></dt> +<dd>Shared memory segment.</dd> +<dt><tt>s</tt></dt> +<dd>Semaphore.</dd> +</dl> +<p>This field is a single character written using the format <tt>%c</tt>.</p> +</dd> +<dt>ID (all)</dt> +<dd>The identifier for the facility entry. This field shall be written using the format <tt>%d</tt>.</dd> +<dt>KEY (all)</dt> +<dd>The key used as an argument to <a href="../functions/msgget.html"><i>msgget</i>()</a>, <a href= +"../functions/semget.html"><i>semget</i>()</a>, or <a href="../functions/shmget.html"><i>shmget</i>()</a> to create the facility +entry. <basefont size="2"> +<dl> +<dt><b>Note:</b></dt> +<dd>The key of a shared memory segment is changed to IPC_PRIVATE when the segment has been removed until all processes attached to +the segment detach it.</dd> +</dl> +<basefont size="3"> This field shall be written using the format <tt>0x%x</tt>.</dd> +<dt>MODE (all)</dt> +<dd>The facility access modes and flags. The mode shall consist of 11 characters that are interpreted as follows. +<p>The first character shall be:</p> +<dl compact> +<dd></dd> +<dt><tt>S</tt></dt> +<dd>If a process is waiting on a <a href="../functions/msgsnd.html"><i>msgsnd</i>()</a> operation.</dd> +<dt><tt>-</tt></dt> +<dd>If the above is not true.</dd> +</dl> +<p>The second character shall be:</p> +<dl compact> +<dd></dd> +<dt><tt>R</tt></dt> +<dd>If a process is waiting on a <a href="../functions/msgrcv.html"><i>msgrcv</i>()</a> operation.</dd> +<dt><tt>C</tt> or <tt>-</tt></dt> +<dd>If the associated shared memory segment is to be cleared when the first attach operation is executed.</dd> +<dt><tt>-</tt></dt> +<dd>If none of the above is true.</dd> +</dl> +<p>The next nine characters shall be interpreted as three sets of three bits each. The first set refers to the owner's permissions; +the next to permissions of others in the usergroup of the facility entry; and the last to all others. Within each set, the first +character indicates permission to read, the second character indicates permission to write or alter the facility entry, and the +last character is a <hyphen-minus> (<tt>'-'</tt>).</p> +<p>The permissions shall be indicated as follows:</p> +<dl compact> +<dd></dd> +<dt><i>r</i></dt> +<dd>If read permission is granted.</dd> +<dt><i>w</i></dt> +<dd>If write permission is granted.</dd> +<dt><i>a</i></dt> +<dd>If alter permission is granted.</dd> +<dt><tt>-</tt></dt> +<dd>If the indicated permission is not granted.</dd> +</dl> +<p>The first character following the permissions specifies if there is an alternate or additional access control method associated +with the facility. If there is no alternate or additional access control method associated with the facility, a single +<space> shall be written; otherwise, another printable character is written.</p> +</dd> +<dt>OWNER (all)</dt> +<dd>The user name of the owner of the facility entry. If the user name of the owner is found in the user database, at least the +first eight column positions of the name shall be written using the format <tt>%s</tt>. Otherwise, the user ID of the owner shall +be written using the format <tt>%d</tt>.</dd> +<dt>GROUP (all)</dt> +<dd>The group name of the owner of the facility entry. If the group name of the owner is found in the group database, at least the +first eight column positions of the name shall be written using the format <tt>%s</tt>. Otherwise, the group ID of the owner shall +be written using the format <tt>%d</tt>.</dd> +</dl> +<p>The following nine columns shall be only written out for message queues:</p> +<dl compact> +<dd></dd> +<dt>CREATOR (<b>a</b>,<b>c</b>)</dt> +<dd>The user name of the creator of the facility entry. If the user name of the creator is found in the user database, at least the +first eight column positions of the name shall be written using the format <tt>%s</tt>. Otherwise, the user ID of the creator shall +be written using the format <tt>%d</tt>.</dd> +<dt>CGROUP (<b>a</b>,<b>c</b>)</dt> +<dd>The group name of the creator of the facility entry. If the group name of the creator is found in the group database, at least +the first eight column positions of the name shall be written using the format <tt>%s</tt>. Otherwise, the group ID of the creator +shall be written using the format <tt>%d</tt>.</dd> +<dt>CBYTES (<b>a</b>,<b>o</b>)</dt> +<dd>The number of bytes in messages currently outstanding on the associated message queue. This field shall be written using the +format <tt>%d</tt>.</dd> +<dt>QNUM (<b>a</b>,<b>o</b>)</dt> +<dd>The number of messages currently outstanding on the associated message queue. This field shall be written using the format +<tt>%d</tt>.</dd> +<dt>QBYTES (<b>a</b>,<b>b</b>)</dt> +<dd>The maximum number of bytes allowed in messages outstanding on the associated message queue. This field shall be written using +the format <tt>%d</tt>.</dd> +<dt>LSPID (<b>a</b>,<b>p</b>)</dt> +<dd>The process ID of the last process to send a message to the associated queue. This field shall be written using the format: +<pre> +<tt>"%d", <</tt><i>pid</i><tt>> +</tt></pre> +<p>where <<i>pid</i>> is 0 if no message has been sent to the corresponding message queue; otherwise, <<i>pid</i>> +shall be the process ID of the last process to send a message to the queue.</p> +</dd> +<dt>LRPID (<b>a</b>,<b>p</b>)</dt> +<dd>The process ID of the last process to receive a message from the associated queue. This field shall be written using the +format: +<pre> +<tt>"%d", <</tt><i>pid</i><tt>> +</tt></pre> +<p>where <<i>pid</i>> is 0 if no message has been received from the corresponding message queue; otherwise, +<<i>pid</i>> shall be the process ID of the last process to receive a message from the queue.</p> +</dd> +<dt>STIME (<b>a</b>,<b>t</b>)</dt> +<dd>The time the last message was sent to the associated queue. If a message has been sent to the corresponding message queue, the +hour, minute, and second of the last time a message was sent to the queue shall be written using the format +<tt>%d</tt>:<tt>%2.2d</tt>:<tt>%2.2d</tt>. Otherwise, the format <tt>" no-entry"</tt> shall be written.</dd> +<dt>RTIME (<b>a</b>,<b>t</b>)</dt> +<dd>The time the last message was received from the associated queue. If a message has been received from the corresponding message +queue, the hour, minute, and second of the last time a message was received from the queue shall be written using the format +<tt>%d</tt>:<tt>%2.2d</tt>:<tt>%2.2d</tt>. Otherwise, the format <tt>" no-entry"</tt> shall be written.</dd> +</dl> +<p>The following eight columns shall be only written out for shared memory segments.</p> +<dl compact> +<dd></dd> +<dt>CREATOR (<b>a</b>,<b>c</b>)</dt> +<dd>The user of the creator of the facility entry. If the user name of the creator is found in the user database, at least the +first eight column positions of the name shall be written using the format <tt>%s</tt>. Otherwise, the user ID of the creator shall +be written using the format <tt>%d</tt>.</dd> +<dt>CGROUP (<b>a</b>,<b>c</b>)</dt> +<dd>The group name of the creator of the facility entry. If the group name of the creator is found in the group database, at least +the first eight column positions of the name shall be written using the format <tt>%s</tt>. Otherwise, the group ID of the creator +shall be written using the format <tt>%d</tt>.</dd> +<dt>NATTCH (<b>a</b>,<b>o</b>)</dt> +<dd>The number of processes attached to the associated shared memory segment. This field shall be written using the format +<tt>%d</tt>.</dd> +<dt>SEGSZ (<b>a</b>,<b>b</b>)</dt> +<dd>The size of the associated shared memory segment. This field shall be written using the format <tt>%d</tt>.</dd> +<dt>CPID (<b>a</b>,<b>p</b>)</dt> +<dd>The process ID of the creator of the shared memory entry. This field shall be written using the format <tt>%d</tt>.</dd> +<dt>LPID (<b>a</b>,<b>p</b>)</dt> +<dd>The process ID of the last process to attach or detach the shared memory segment. This field shall be written using the format: +<pre> +<tt>"%d", <</tt><i>pid</i><tt>> +</tt></pre> +<p>where <<i>pid</i>> is 0 if no process has attached the corresponding shared memory segment; otherwise, <<i>pid</i>> +shall be the process ID of the last process to attach or detach the segment.</p> +</dd> +<dt>ATIME (<b>a</b>,<b>t</b>)</dt> +<dd>The time the last attach on the associated shared memory segment was completed. If the corresponding shared memory segment has +ever been attached, the hour, minute, and second of the last time the segment was attached shall be written using the format +<tt>%d</tt>:<tt>%2.2d</tt>:<tt>%2.2d</tt>. Otherwise, the format <tt>" no-entry"</tt> shall be written.</dd> +<dt>DTIME (<b>a</b>,<b>t</b>)</dt> +<dd>The time the last detach on the associated shared memory segment was completed. If the corresponding shared memory segment has +ever been detached, the hour, minute, and second of the last time the segment was detached shall be written using the format +<tt>%d</tt>:<tt>%2.2d</tt>:<tt>%2.2d</tt>. Otherwise, the format <tt>" no-entry"</tt> shall be written.</dd> +</dl> +<p>The following four columns shall be only written out for semaphore sets:</p> +<dl compact> +<dd></dd> +<dt>CREATOR (<b>a</b>,<b>c</b>)</dt> +<dd>The user of the creator of the facility entry. If the user name of the creator is found in the user database, at least the +first eight column positions of the name shall be written using the format <tt>%s</tt>. Otherwise, the user ID of the creator shall +be written using the format <tt>%d</tt>.</dd> +<dt>CGROUP (<b>a</b>,<b>c</b>)</dt> +<dd>The group name of the creator of the facility entry. If the group name of the creator is found in the group database, at least +the first eight column positions of the name shall be written using the format <tt>%s</tt>. Otherwise, the group ID of the creator +shall be written using the format <tt>%d</tt>.</dd> +<dt>NSEMS (<b>a</b>,<b>b</b>)</dt> +<dd>The number of semaphores in the set associated with the semaphore entry. This field shall be written using the format +<tt>%d</tt>.</dd> +<dt>OTIME (<b>a</b>,<b>t</b>)</dt> +<dd>The time the last semaphore operation on the set associated with the semaphore entry was completed. If a semaphore operation +has ever been performed on the corresponding semaphore set, the hour, minute, and second of the last semaphore operation on the +semaphore set shall be written using the format <tt>%d</tt>:<tt>%2.2d</tt>:<tt>%2.2d</tt>. Otherwise, the format +<tt>" no-entry"</tt> shall be written.</dd> +</dl> +<p>The following column shall be written for all three reports when it is requested:</p> +<dl compact> +<dd></dd> +<dt>CTIME (<b>a</b>,<b>t</b>)</dt> +<dd>The time the associated entry was created or changed. The hour, minute, and second of the time when the associated entry was +created shall be written using the format <tt>%d</tt>:<tt>%2.2d</tt>:<tt>%2.2d</tt>.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_61_11" id="tag_20_61_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_61_12" id="tag_20_61_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_61_13" id="tag_20_61_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_61_14" id="tag_20_61_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_61_15" id="tag_20_61_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_61_16" id="tag_20_61_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Things can change while <i>ipcs</i> is running; the information it gives is guaranteed to be accurate only when it was +retrieved.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_61_17" id="tag_20_61_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_61_18" id="tag_20_61_18"></a>RATIONALE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_61_19" id="tag_20_61_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_61_20" id="tag_20_61_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/ipcrm.html#"><i>ipcrm</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/msgrcv.html#"><i>msgrcv</i></a> , <a href="../functions/msgsnd.html#"><i>msgsnd</i></a> , <a href= +"../functions/semget.html#"><i>semget</i></a> , <a href="../functions/semop.html#"><i>semop</i></a> , <a href= +"../functions/shmat.html#"><i>shmat</i></a> , <a href="../functions/shmdt.html#"><i>shmdt</i></a> , <a href= +"../functions/shmget.html#"><i>shmget</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_61_21" id="tag_20_61_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 5.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_61_22" id="tag_20_61_22"></a>Issue 6</h4> +<blockquote> +<p>The Open Group Corrigendum U020/1 is applied, correcting the SYNOPSIS.</p> +<p>The Open Group Corrigenda U032/1 and U032/2 are applied, clarifying the output format.</p> +<p>The Open Group Base Resolution bwg98-004 is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_61_23" id="tag_20_61_23"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>SD5-XCU-ERN-139 is applied, adding the <a href="../utilities/ipcrm.html"><i>ipcrm</i></a> utility to the SEE ALSO section.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0108 [584] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_61_24" id="tag_20_61_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to report an error if a utility is directed to display a +pathname that contains any bytes that have the encoded value of a <newline> character when <newline> is a terminator or +separator in the output format being used.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/ipcrm.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/jobs.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/jobs.html b/bdd/jobs.html @@ -0,0 +1,326 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>jobs</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/ipcs.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/join.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="jobs" id="jobs"></a> <a name="tag_20_62" id="tag_20_62"></a><!-- jobs --> +<h4 class="mansect"><a name="tag_20_62_01" id="tag_20_62_01"></a>NAME</h4> +<blockquote>jobs — display status of jobs in the current shell execution environment</blockquote> +<h4 class="mansect"><a name="tag_20_62_02" id="tag_20_62_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> jobs</tt> <b>[</b><tt>-l|-p</tt><b>] [</b><i>job_id</i><tt>...</tt><b>]</b> <tt><img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div> +</blockquote> +<h4 class="mansect"><a name="tag_20_62_03" id="tag_20_62_03"></a>DESCRIPTION</h4> +<blockquote> +<p>If the current shell execution environment (see <a href="../utilities/V3_chap02.html#tag_19_13"><i>2.13 Shell Execution +Environment</i></a> ) is not a subshell environment, the <i>jobs</i> utility shall display the status of background jobs that were +created in the current shell execution environment; it may also do so if the current shell execution environment is a subshell +environment.</p> +<p>When <i>jobs</i> reports the termination status of a job, the shell shall remove the job from the background jobs list and the +associated process ID from the list of those "known in the current shell execution environment"; see <a href= +"../utilities/V3_chap02.html#tag_19_09_03_02"><i>2.9.3.1 Asynchronous AND-OR Lists</i></a> . If a write error occurs when +<i>jobs</i> writes to standard output, some process IDs might have been removed from the list but not successfully reported.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_62_04" id="tag_20_62_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>jobs</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-l</b></dt> +<dd>(The letter ell.) Provide more information about each job listed. See STDOUT for details.</dd> +<dt><b>-p</b></dt> +<dd>Display only the process IDs for the process group leaders of job-control background jobs and the process IDs associated with +non-job-control background jobs (if supported).</dd> +</dl> +<p>By default, the <i>jobs</i> utility shall display the status of all background jobs, both running and suspended, and all jobs +whose status has changed and have not been reported by the shell.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_62_05" id="tag_20_62_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>job_id</i></dt> +<dd>Specifies the jobs for which the status is to be displayed. If no <i>job_id</i> is given, the status information for all jobs +shall be displayed. The format of <i>job_id</i> is described in XBD <a href="../basedefs/V1_chap03.html#tag_03_182"><i>3.182 Job +ID</i></a> .</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_62_06" id="tag_20_62_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_62_07" id="tag_20_62_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_62_08" id="tag_20_62_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>jobs</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error and +informative messages written to standard output.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_62_09" id="tag_20_62_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_62_10" id="tag_20_62_10"></a>STDOUT</h4> +<blockquote> +<p>If the <b>-p</b> option is specified, the output shall consist of one line for each process ID:</p> +<pre> +<tt>"%d\n", <</tt><i>process ID</i><tt>> +</tt></pre> +<p>Otherwise, if the <b>-l</b> option is not specified, the output shall be a series of lines of the form:</p> +<pre> +<tt>"[%d] %c %s %s\n", <</tt><i>job-number</i><tt>>, <</tt><i>current</i><tt>>, <</tt><i>state</i><tt>>, <</tt><i>command</i><tt>> +</tt></pre> +<p>where the fields shall be as follows:</p> +<dl compact> +<dd></dd> +<dt><<i>current</i>></dt> +<dd>The character <tt>'+'</tt> identifies the job that would be used as a default for the <a href= +"../utilities/fg.html"><i>fg</i></a> or <a href="../utilities/bg.html"><i>bg</i></a> utilities; this job can also be specified +using the <i>job_id</i> %+ or <tt>"%%"</tt>. The character <tt>'-'</tt> identifies the job that would become the default if the +current default job were to exit; this job can also be specified using the <i>job_id</i> %-. For other jobs, this field is a +<space>. At most one job can be identified with <tt>'+'</tt> and at most one job can be identified with <tt>'-'</tt>. If +there is any suspended job, then the current job shall be a suspended job. If there are at least two suspended jobs, then the +previous job also shall be a suspended job.</dd> +<dt><<i>job-number</i>></dt> +<dd>A number that can be used to identify the job to the <a href="../utilities/wait.html"><i>wait</i></a>, <a href= +"../utilities/fg.html"><i>fg</i></a>, <a href="../utilities/bg.html"><i>bg</i></a>, and <a href= +"../utilities/kill.html"><i>kill</i></a> utilities. Using these utilities, the job can be identified by prefixing the job number +with <tt>'%'</tt>.</dd> +<dt><<i>state</i>></dt> +<dd>One of the following strings (in the POSIX locale): +<dl compact> +<dd></dd> +<dt><b>Running</b></dt> +<dd>Indicates that the job has not been suspended by a signal and has not exited.</dd> +<dt><b>Done</b></dt> +<dd>Indicates that the job completed and returned exit status zero.</dd> +<dt><b>Done</b>(<i>code</i>)</dt> +<dd>Indicates that the job completed normally and that it exited with the specified non-zero exit status, <i>code</i>, expressed as +a decimal number.</dd> +<dt><b>Stopped</b></dt> +<dd>Indicates that the job was suspended by the SIGTSTP signal.</dd> +<dt><b>Stopped</b> (<b>SIGTSTP</b>)</dt> +<dd><br> +Indicates that the job was suspended by the SIGTSTP signal.</dd> +<dt><b>Stopped</b> (<b>SIGSTOP</b>)</dt> +<dd><br> +Indicates that the job was suspended by the SIGSTOP signal.</dd> +<dt><b>Stopped</b> (<b>SIGTTIN</b>)</dt> +<dd><br> +Indicates that the job was suspended by the SIGTTIN signal.</dd> +<dt><b>Stopped</b> (<b>SIGTTOU</b>)</dt> +<dd><br> +Indicates that the job was suspended by the SIGTTOU signal.</dd> +</dl> +<p>The implementation may substitute the string <b>Suspended</b> in place of <b>Stopped</b>. If the job was terminated by a signal, +the format of <<i>state</i>> is unspecified, but it shall be visibly distinct from all of the other <<i>state</i>> +formats shown here and shall indicate the name or description of the signal causing the termination.</p> +</dd> +<dt><<i>command</i>></dt> +<dd>The associated command that was given to the shell.</dd> +</dl> +<p>If the <b>-l</b> option is specified:</p> +<ul> +<li> +<p>For job-control background jobs, a field containing the process group ID shall be inserted before the <<i>state</i>> +field. Also, more processes in a process group may be output on separate lines, using only the process ID and +<<i>command</i>> fields.</p> +</li> +<li> +<p>For non-job-control background jobs (if supported), a field containing the process ID associated with the job shall be inserted +before the <<i>state</i>> field. Also, more processes created to execute the job may be output on separate lines, using only +the process ID and <<i>command</i>> fields.</p> +</li> +</ul> +</blockquote> +<h4 class="mansect"><a name="tag_20_62_11" id="tag_20_62_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_62_12" id="tag_20_62_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_62_13" id="tag_20_62_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_62_14" id="tag_20_62_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>The output specified in STDOUT was successfully written to standard output.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_62_15" id="tag_20_62_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_62_16" id="tag_20_62_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>This utility is required to be intrinsic. See <a href="../utilities/V3_chap01.html#tag_18_07"><i>1.7 Intrinsic Utilities</i></a> +for details.</p> +<p>The <b>-p</b> option is the only portable way to find out the process group of a job-control background job because different +implementations have different strategies for defining the process group of the job. Usage such as $(<i>jobs</i> <b>-p</b>) +provides a way of referring to the process group of the job in an implementation-independent way.</p> +<p>The <i>jobs</i> utility does not work as expected when it is operating in its own utility execution environment because that +environment has no applicable jobs to manipulate. See the APPLICATION USAGE section for <a href= +"../utilities/bg.html#"><i>bg</i></a> . For this reason, <i>jobs</i> is generally implemented as a shell regular built-in.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_62_17" id="tag_20_62_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_62_18" id="tag_20_62_18"></a>RATIONALE</h4> +<blockquote> +<p>Both <tt>"%%"</tt> and <tt>"%+"</tt> are used to refer to the current job. Both forms are of equal validity—the <tt>"%%"</tt> +mirroring <tt>"$$"</tt> and <tt>"%+"</tt> mirroring the output of <i>jobs</i>. Both forms reflect historical practice of the +KornShell and the C shell with job control.</p> +<p>The job control features provided by <a href="../utilities/bg.html"><i>bg</i></a>, <a href="../utilities/fg.html"><i>fg</i></a>, +and <i>jobs</i> are based on the KornShell. The standard developers examined the characteristics of the C shell versions of these +utilities and found that differences exist. Despite widespread use of the C shell, the KornShell versions were selected for this +volume of POSIX.1-2024 to maintain a degree of uniformity with the rest of the KornShell features selected (such as the very +popular command line editing features).</p> +<p>The <i>jobs</i> utility is not dependent on job control being enabled, as are the seemingly related <a href= +"../utilities/bg.html"><i>bg</i></a> and <a href="../utilities/fg.html"><i>fg</i></a> utilities because <i>jobs</i> is useful for +examining background jobs, regardless of the current state of job control. When job control has been disabled using <a href= +"../utilities/V3_chap02.html#set"><i>set</i></a> <b>+m</b>, the <i>jobs</i> utility can still be used to examine the job-control +background jobs and (if supported) non-job-control background jobs that were created in the current shell execution environment. +See also the RATIONALE for <a href="../utilities/kill.html"><i>kill</i></a> and <a href= +"../utilities/wait.html"><i>wait</i></a>.</p> +<p>The output for terminated jobs is left unspecified to accommodate various historical systems. The following formats have been +witnessed:</p> +<ol> +<li> +<p><b>Killed</b>(<i>signal name</i>)</p> +</li> +<li> +<p><i>signal name</i></p> +</li> +<li> +<p><i>signal name</i>(<b>coredump</b>)</p> +</li> +<li> +<p><i>signal description</i>- <b>core dumped</b></p> +</li> +</ol> +<p>Most users should be able to understand these formats, although it means that applications have trouble parsing them.</p> +<p>The calculation of job IDs was not described since this would suggest an implementation, which may impose unnecessary +restrictions.</p> +<p>In an early proposal, a <b>-n</b> option was included to "Display the status of jobs that have changed, exited, or stopped +since the last status report". It was removed because the shell always writes any changed status of jobs before each prompt.</p> +<p>If <i>jobs</i> uses buffered writes to standard output, a write error could be detected when attempting to flush a buffer +containing multiple reports of terminated jobs, resulting in some unreported jobs having their process IDs removed from the list of +those known in the current shell execution environment (because they were removed when the report was added to the buffer).</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_62_19" id="tag_20_62_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_62_20" id="tag_20_62_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19_13"><i>2.13 Shell Execution Environment</i></a> , <a href= +"../utilities/bg.html#"><i>bg</i></a> , <a href="../utilities/fg.html#"><i>fg</i></a> , <a href= +"../utilities/kill.html#tag_20_64"><i>kill</i></a> , <a href="../utilities/wait.html#tag_20_147"><i>wait</i></a></p> +<p>XBD <a href="../basedefs/V1_chap03.html#tag_03_182"><i>3.182 Job ID</i></a> , <a href="../basedefs/V1_chap08.html#tag_08"><i>8. +Environment Variables</i></a> , <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_62_21" id="tag_20_62_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_62_22" id="tag_20_62_22"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +<p>The JC shading is removed as job control is mandatory in this version.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_62_23" id="tag_20_62_23"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_62_24" id="tag_20_62_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 854 is applied, adding a note to the APPLICATION USAGE section that this utility is required to be +intrinsic.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1254 is applied, updating various requirements for the <i>jobs</i> utility to account for the addition of +<a href="../utilities/V3_chap02.html#tag_19_11"><i>2.11 Job Control</i></a> .</p> +<p>Austin Group Defect 1492 is applied, clarifying the requirements when a write error to standard output occurs.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/ipcs.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/join.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/join.html b/bdd/join.html @@ -0,0 +1,351 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>join</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/jobs.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/kill.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="join" id="join"></a> <a name="tag_20_63" id="tag_20_63"></a><!-- join --> +<h4 class="mansect"><a name="tag_20_63_01" id="tag_20_63_01"></a>NAME</h4> +<blockquote>join — relational database operator</blockquote> +<h4 class="mansect"><a name="tag_20_63_02" id="tag_20_63_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>join</tt> <b>[</b><tt>-a</tt> <i>file_number</i><tt>|-v</tt> <i>file_number</i><b>] [</b><tt>-e</tt> <i>string</i><b>] +[</b><tt>-o</tt> <i>list</i><b>] [</b><tt>-t</tt> <i>char</i><b>]<br></b> <tt> </tt> +<b>[</b><tt>-1</tt> <i>field</i><b>] [</b><tt>-2</tt> <i>field</i><b>]</b> <i>file1 file2</i></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_63_03" id="tag_20_63_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>join</i> utility shall perform an equality join on the files <i>file1</i> and <i>file2</i>. The joined files shall be +written to the standard output.</p> +<p>The join field is a field in each file on which the files are compared. The <i>join</i> utility shall write one line in the +output for each pair of lines in <i>file1</i> and <i>file2</i> that have join fields that collate equally. The output line by +default shall consist of the join field, then the remaining fields from <i>file1</i>, then the remaining fields from <i>file2</i>. +This format can be changed by using the <b>-o</b> option (see below). The <b>-a</b> option can be used to add unmatched lines to +the output. The <b>-v</b> option can be used to output only unmatched lines.</p> +<p>The files <i>file1</i> and <i>file2</i> shall be ordered in the collating sequence of <a href= +"../utilities/sort.html"><i>sort</i></a> <b>-b</b> on the fields on which they shall be joined, by default the first in each line. +All selected output shall be written in the same collating sequence.</p> +<p>The default input field separators shall be <blank> characters. In this case, multiple separators shall count as one field +separator, and leading separators shall be ignored. The default output field separator shall be a <space>.</p> +<p>The field separator and collating sequence can be changed by using the <b>-t</b> option (see below).</p> +<p>If the same key appears more than once in either file, all combinations of the set of remaining fields in <i>file1</i> and the +set of remaining fields in <i>file2</i> are output in the order of the lines encountered.</p> +<p>If the input files are not in the appropriate collating sequence, the results are unspecified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_63_04" id="tag_20_63_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>join</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-a </b><i>file_number</i></dt> +<dd><br> +Produce a line for each unpairable line in file <i>file_number</i>, where <i>file_number</i> is 1 or 2, in addition to the default +output. If both <b>-a</b>1 and <b>-a</b>2 are specified, all unpairable lines shall be output.</dd> +<dt><b>-e </b><i>string</i></dt> +<dd>Replace empty output fields in the list selected by <b>-o</b> with the string <i>string</i>.</dd> +<dt><b>-o </b><i>list</i></dt> +<dd>Construct the output line to comprise the fields specified in <i>list</i>, each element of which shall have one of the +following two forms: +<ol> +<li> +<p><i>file_number.field</i>, where <i>file_number</i> is a file number and <i>field</i> is a decimal integer field number</p> +</li> +<li> +<p>0 (zero), representing the join field</p> +</li> +</ol> +<p>The elements of <i>list</i> shall be either <comma>-separated or <blank>-separated, as specified in Guideline 8 of +XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a> . The fields specified by <i>list</i> +shall be written for all selected output lines. Fields selected by <i>list</i> that do not appear in the input shall be treated as +empty output fields. (See the <b>-e</b> option.) Only specifically requested fields shall be written. The application shall ensure +that <i>list</i> is a single command line argument.</p> +</dd> +<dt><b>-t </b><i>char</i></dt> +<dd>Use character <i>char</i> as a separator, for both input and output. Every appearance of <i>char</i> in a line shall be +significant. When this option is specified, the collating sequence shall be the same as <a href= +"../utilities/sort.html"><i>sort</i></a> without the <b>-b</b> option.</dd> +<dt><b>-v </b><i>file_number</i></dt> +<dd><br> +Instead of the default output, produce a line only for each unpairable line in <i>file_number</i>, where <i>file_number</i> is 1 or +2. If both <b>-v</b>1 and <b>-v</b>2 are specified, all unpairable lines shall be output.</dd> +<dt><b>-1 </b><i>field</i></dt> +<dd>Join on the <i>field</i>th field of file 1. Fields are decimal integers starting with 1.</dd> +<dt><b>-2 </b><i>field</i></dt> +<dd>Join on the <i>field</i>th field of file 2. Fields are decimal integers starting with 1.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_63_05" id="tag_20_63_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file1</i>, <i>file2</i></dt> +<dd>A pathname of a file to be joined. If either of the <i>file1</i> or <i>file2</i> operands is <tt>'-'</tt>, the standard input +shall be used in its place.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_63_06" id="tag_20_63_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be used only if the <i>file1</i> or <i>file2</i> operand is <tt>'-'</tt>. See the INPUT FILES +section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_63_07" id="tag_20_63_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files shall be text files.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_63_08" id="tag_20_63_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>join</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_COLLATE</i></dt> +<dd><br> +Determine the locale of the collating sequence <i>join</i> expects to have been used when the input files were sorted.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_63_09" id="tag_20_63_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_63_10" id="tag_20_63_10"></a>STDOUT</h4> +<blockquote> +<p>The <i>join</i> utility output shall be a concatenation of selected character fields. When the <b>-o</b> option is not +specified, the output shall be:</p> +<pre> +<tt>"%s%s%s\n", <</tt><i>join field</i><tt>>, <</tt><i>other file1 fields</i><tt>>, + <</tt><i>other file2 fields</i><tt>> +</tt></pre> +<p>If the join field is not the first field in a file, the <<i>other file fields</i>> for that file shall be:</p> +<pre> +<tt><</tt><i>fields preceding join field</i><tt>>, <</tt><i>fields following join field</i><tt>> +</tt></pre> +<p>When the <b>-o</b> option is specified, the output format shall be:</p> +<pre> +<tt>"%s\n", <</tt><i>concatenation of fields</i><tt>> +</tt></pre> +<p>where the concatenation of fields is described by the <b>-o</b> option, above.</p> +<p>For either format, each field (except the last) shall be written with its trailing separator character. If the separator is the +default (<blank> characters), a single <space> shall be written after each field (except the last).</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_63_11" id="tag_20_63_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_63_12" id="tag_20_63_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_63_13" id="tag_20_63_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_63_14" id="tag_20_63_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>All input files were output successfully.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_63_15" id="tag_20_63_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_63_16" id="tag_20_63_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Pathnames consisting of numeric digits or of the form <i>string.string</i> should not be specified directly following the +<b>-o</b> list.</p> +<p>If the collating sequence of the current locale does not have a total ordering of all characters (see XBD <a href= +"../basedefs/V1_chap07.html#tag_07_03_02"><i>7.3.2 LC_COLLATE</i></a> ), <i>join</i> treats fields that collate equally but are not +identical as being the same. If this behavior is not desired, it can be avoided by forcing the use of the POSIX locale (although +this means re-sorting the input files into the POSIX locale collating sequence.)</p> +<p>When using <i>join</i> to process pathnames, it is recommended that LC_ALL, or at least LC_CTYPE and LC_COLLATE, are set to +POSIX or C in the environment, since pathnames can contain byte sequences that do not form valid characters in some locales, in +which case the utility's behavior would be undefined. In the POSIX locale each byte is a valid single-byte character, and therefore +this problem is avoided.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_63_17" id="tag_20_63_17"></a>EXAMPLES</h4> +<blockquote> +<p>The <b>-o</b> 0 field essentially selects the union of the join fields. For example, given file <b>phone</b>:</p> +<pre> +<tt>!Name Phone Number +Don +1 123-456-7890 +Hal +1 234-567-8901 +Yasushi +2 345-678-9012 +</tt></pre> +<p>and file <b>fax</b>:</p> +<pre> +<tt>!Name Fax Number +Don +1 123-456-7899 +Keith +1 456-789-0122 +Yasushi +2 345-678-9011 +</tt></pre> +<p>(where the large expanses of white space are meant to each represent a single <tab>), the command:</p> +<pre> +<tt>join -t "<tab>" -a 1 -a 2 -e '(unknown)' -o 0,1.2,2.2 phone fax +</tt></pre> +<p>(where <tt><tab></tt> is a literal <tab> character) would produce:</p> +<pre> +<tt>!Name Phone Number Fax Number +Don +1 123-456-7890 +1 123-456-7899 +Hal +1 234-567-8901 (unknown) +Keith (unknown) +1 456-789-0122 +Yasushi +2 345-678-9012 +2 345-678-9011 +</tt></pre> +<p>Multiple instances of the same key will produce combinatorial results. The following:</p> +<pre> +<tt>fa: + a x + a y + a z +fb: + a p +</tt></pre> +<p>will produce:</p> +<pre> +<tt>a x p +a y p +a z p +</tt></pre> +<p>And the following:</p> +<pre> +<tt>fa: + a b c + a d e +fb: + a w x + a y z + a o p +</tt></pre> +<p>will produce:</p> +<pre> +<tt>a b c w x +a b c y z +a b c o p +a d e w x +a d e y z +a d e o p +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_63_18" id="tag_20_63_18"></a>RATIONALE</h4> +<blockquote> +<p>The <b>-e</b> option is only effective when used with <b>-o</b> because, unless specific fields are identified using <b>-o</b>, +<i>join</i> is not aware of what fields might be empty. The exception to this is the join field, but identifying an empty join +field with the <b>-e</b> string is not historical practice and some scripts might break if this were changed.</p> +<p>The 0 field in the <b>-o</b> list was adopted from the Tenth Edition version of <i>join</i> to satisfy international objections +that the <i>join</i> in the base documents for IEEE Std 1003.2-1992 did not support the "full join" or "outer join" +described in relational database literature. Although it has been possible to include a join field in the output (by default, or by +field number using <b>-o</b>), the join field could not be included for an unpaired line selected by <b>-a</b>. The <b>-o</b> 0 +field essentially selects the union of the join fields.</p> +<p>This sort of outer join was not possible with the <i>join</i> commands in the base documents for IEEE Std 1003.2-1992. +The <b>-o</b> 0 field was chosen because it is an upwards-compatible change for applications. An alternative was considered: have +the join field represent the union of the fields in the files (where they are identical for matched lines, and one or both are null +for unmatched lines). This was not adopted because it would break some historical applications.</p> +<p>The ability to specify <i>file2</i> as <b>-</b> is not historical practice; it was added for completeness.</p> +<p>The <b>-v</b> option is not historical practice, but was considered necessary because it permitted the writing of <i>only</i> +those lines that do not match on the join field, as opposed to the <b>-a</b> option, which prints both lines that do and do not +match. This additional facility is parallel with the <b>-v</b> option of <a href="../utilities/grep.html"><i>grep</i></a>.</p> +<p>Some historical implementations have been encountered where a blank line in one of the input files was considered to be the end +of the file; the description in this volume of POSIX.1-2024 does not cite this as an allowable case.</p> +<p>Earlier versions of this standard allowed <b>-j</b>, <b>-j1</b>, <b>-j2</b> options, and a form of the <b>-o</b> option that +allowed the <i>list</i> option-argument to be multiple arguments. These forms are no longer specified by POSIX.1-2024 but may be +present in some implementations.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_63_19" id="tag_20_63_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_63_20" id="tag_20_63_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/awk.html#"><i>awk</i></a> , <a href="../utilities/comm.html#"><i>comm</i></a> , <a href= +"../utilities/sort.html#"><i>sort</i></a> , <a href="../utilities/uniq.html#"><i>uniq</i></a></p> +<p>XBD <a href="../basedefs/V1_chap07.html#tag_07_03_02"><i>7.3.2 LC_COLLATE</i></a> , <a href= +"../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 +Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_63_21" id="tag_20_63_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_63_22" id="tag_20_63_22"></a>Issue 6</h4> +<blockquote> +<p>The obsolescent <b>-j</b> options and the multi-argument <b>-o</b> option are removed in this version.</p> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_63_23" id="tag_20_63_23"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #027 is applied.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0109 [963], XCU/TC2-2008/0110 [663], XCU/TC2-2008/0111 [971], and +XCU/TC2-2008/0112 [885] are applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_63_24" id="tag_20_63_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/jobs.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/kill.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/kill.html b/bdd/kill.html @@ -0,0 +1,373 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>kill</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/join.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/lex.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="kill" id="kill"></a> <a name="tag_20_64" id="tag_20_64"></a><!-- kill --> +<h4 class="mansect"><a name="tag_20_64_01" id="tag_20_64_01"></a>NAME</h4> +<blockquote>kill — terminate or signal processes</blockquote> +<h4 class="mansect"><a name="tag_20_64_02" id="tag_20_64_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>kill</tt> <b>[</b><tt>-s</tt> <i>signal_name</i><b>]</b> <i>pid</i><tt>...<br> +<br> +kill -l</tt> <b>[</b><i>exit_status</i><b>]</b> <tt><br> +<br></tt></code></p> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> kill</tt> <b>[</b><tt>-</tt><i>signal_name</i><b>]</b> <i>pid</i><tt>...<br> +<br> +kill</tt> <b>[</b><tt>-</tt><i>signal_number</i><b>]</b> <i>pid</i><tt>... <img src="../images/opt-end.gif" alt="[Option End]" +border="0"></tt></code></div> +<tt><br></tt></blockquote> +<h4 class="mansect"><a name="tag_20_64_03" id="tag_20_64_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>kill</i> utility shall send a signal to the process or processes specified by each <i>pid</i> operand.</p> +<p>For each <i>pid</i> operand, the <i>kill</i> utility shall perform actions equivalent to the <a href= +"../functions/kill.html"><i>kill</i>()</a> function defined in the System Interfaces volume of POSIX.1-2024 called with the +following arguments:</p> +<ul> +<li> +<p>The value of the <i>pid</i> operand shall be used as the <i>pid</i> argument.</p> +</li> +<li> +<p>The <i>sig</i> argument is the value specified by the <b>-s</b> option, <b>-</b><i>signal_number</i> option, or the +<b>-</b><i>signal_name</i> option, or by SIGTERM, if none of these options is specified.</p> +</li> +</ul> +</blockquote> +<h4 class="mansect"><a name="tag_20_64_04" id="tag_20_64_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>kill</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> , <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> except that in the last two SYNOPSIS forms, the <b>-</b><i>signal_number</i> and +<b>-</b><i>signal_name</i> options are usually more than a single character. <img src="../images/opt-end.gif" alt="[Option End]" +border="0"></p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-l</b></dt> +<dd>(The letter ell.) Write all values of <i>signal_name</i> supported by the implementation, if no operand is given. If an +<i>exit_status</i> operand is given and it is a value of the <tt>'?'</tt> shell special parameter (see <a href= +"../utilities/V3_chap02.html#tag_19_05_02"><i>2.5.2 Special Parameters</i></a> and <a href= +"../utilities/wait.html"><i>wait</i></a>) corresponding to a process that was terminated or stopped by a signal, the +<i>signal_name</i> corresponding to the signal that terminated or stopped the process shall be written. If an <i>exit_status</i> +operand is given and it is the unsigned decimal integer value of a signal number, the <i>signal_name</i> (the symbolic constant +name without the <b>SIG</b> prefix defined in the Base Definitions volume of POSIX.1-2024) corresponding to that signal shall be +written. Otherwise, the results are unspecified.</dd> +<dt><b>-s </b><i>signal_name</i></dt> +<dd><br> +Specify the signal to send, using one of the symbolic names defined in the <a href= +"../basedefs/signal.h.html"><i><signal.h></i></a> header. Values of <i>signal_name</i> shall be recognized in a +case-independent fashion, without the <b>SIG</b> prefix. In addition, the symbolic name 0 shall be recognized, representing the +signal value zero. The corresponding signal shall be sent instead of SIGTERM.</dd> +<dt><b>-</b><i>signal_name</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border= +"0"><br> +Equivalent to <b>-s</b> <i>signal_name</i>. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-</b><i>signal_number</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border= +"0"><br> +Specify a non-negative decimal integer, <i>signal_number</i>, representing the signal to be used instead of SIGTERM, as the +<i>sig</i> argument in the effective call to <a href="../functions/kill.html"><i>kill</i>()</a>. The correspondence between integer +values and the <i>sig</i> value used is shown in the following list. +<p>The effects of specifying any <i>signal_number</i> other than those listed below are undefined.</p> +<dl compact> +<dd></dd> +<dt>0</dt> +<dd>0</dd> +<dt>1</dt> +<dd>SIGHUP</dd> +<dt>2</dt> +<dd>SIGINT</dd> +<dt>3</dt> +<dd>SIGQUIT</dd> +<dt>6</dt> +<dd>SIGABRT</dd> +<dt>9</dt> +<dd>SIGKILL</dd> +<dt>14</dt> +<dd>SIGALRM</dd> +<dt>15</dt> +<dd>SIGTERM</dd> +</dl> +<p>If the first argument is a negative integer, it shall be interpreted as a <b>-</b><i>signal_number</i> option, not as a negative +<i>pid</i> operand specifying a process group. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p> +</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_64_05" id="tag_20_64_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>pid</i></dt> +<dd>One of the following: +<ol> +<li> +<p>A decimal integer specifying a process or process group to be signaled. The process or processes selected by positive, negative, +and zero values of the <i>pid</i> operand shall be as described for the <a href="../functions/kill.html"><i>kill</i>()</a> +function. If process number 0 is specified, all processes in the current process group shall be signaled. For the effects of +negative <i>pid</i> numbers, see the <a href="../functions/kill.html"><i>kill</i>()</a> function defined in the System Interfaces +volume of POSIX.1-2024. If the first <i>pid</i> operand is negative, it should be preceded by <tt>"--"</tt> to keep it from being +interpreted as an option.</p> +</li> +<li> +<p>A job ID (see XBD <a href="../basedefs/V1_chap03.html#tag_03_182"><i>3.182 Job ID</i></a> ) that identifies a process group in +the case of a job-control background job, or a process ID in the case of a non-job-control background job (if supported), to be +signaled. The job ID notation is applicable only for invocations of <i>kill</i> in the current shell execution environment; see +<a href="../utilities/V3_chap02.html#tag_19_13"><i>2.13 Shell Execution Environment</i></a> . <basefont size="2"></p> +<dl> +<dt><b>Note:</b></dt> +<dd>The job ID type of <i>pid</i> is only available on systems supporting the User Portability Utilities option or supporting +non-job-control background jobs.</dd> +</dl> +<basefont size="3"></li> +</ol> +</dd> +<dt><i>exit_status</i></dt> +<dd>A decimal integer specifying a signal number or the exit status of a process terminated by a signal.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_64_06" id="tag_20_64_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_64_07" id="tag_20_64_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_64_08" id="tag_20_64_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>kill</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_64_09" id="tag_20_64_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_64_10" id="tag_20_64_10"></a>STDOUT</h4> +<blockquote> +<p>When the <b>-l</b> option is not specified, the standard output shall not be used.</p> +<p>When the <b>-l</b> option is specified, the symbolic name of each signal shall be written in the following format:</p> +<pre> +<tt>"%s%c", <</tt><i>signal_name</i><tt>>, <</tt><i>separator</i><tt>> +</tt></pre> +<p>where the <<i>signal_name</i>> is in uppercase, without the <b>SIG</b> prefix, and the <<i>separator</i>> shall be +either a <newline> or a <space>. For the last signal written, <<i>separator</i>> shall be a <newline>.</p> +<p>When both the <b>-l</b> option and <i>exit_status</i> operand are specified, the symbolic name of the corresponding signal shall +be written in the following format:</p> +<pre> +<tt>"%s\n", <</tt><i>signal_name</i><tt>> +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_64_11" id="tag_20_64_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_64_12" id="tag_20_64_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_64_13" id="tag_20_64_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_64_14" id="tag_20_64_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>The <b>-l</b> option was specified and the output specified in STDOUT was successfully written to standard output; or, the +<b>-l</b> option was not specified, at least one matching process was found for each <i>pid</i> operand, and the specified signal +was successfully processed for at least one matching process.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_64_15" id="tag_20_64_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_64_16" id="tag_20_64_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>This utility is required to be intrinsic. See <a href="../utilities/V3_chap01.html#tag_18_07"><i>1.7 Intrinsic Utilities</i></a> +for details.</p> +<p>Process numbers can be found by using <a href="../utilities/ps.html"><i>ps</i></a>.</p> +<p>The use of job ID notation is not dependent on job control being enabled. When job control has been disabled using <a href= +"../utilities/set.html"><i>set</i></a> <b>+m</b>, <i>kill</i> can still be used to signal the process group associated with a +job-control background job, or the process ID associated with a non-control background job (if supported), using</p> +<pre> +<tt>kill %<</tt><i>background job number</i><tt>> +</tt></pre> +<p>See also the RATIONALE for <a href="../utilities/jobs.html"><i>jobs</i></a> and <a href= +"../utilities/wait.html"><i>wait</i></a>.</p> +<p>The job ID notation is not required to work as expected when <i>kill</i> is operating in its own utility execution environment. +In either of the following examples:</p> +<pre> +<tt>nohup kill %1 & +system("kill %1"); +</tt></pre> +<p>the <i>kill</i> operates in a different environment and does not share the shell's understanding of job numbers.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_64_17" id="tag_20_64_17"></a>EXAMPLES</h4> +<blockquote> +<p>Any of the commands:</p> +<pre> +<tt>kill -9 100 -165 +kill -s kill 100 -165 +kill -s KILL 100 -165 +</tt></pre> +<p>sends the SIGKILL signal to the process whose process ID is 100 and to all processes whose process group ID is 165, assuming the +sending process has permission to send that signal to the specified processes, and that they exist.</p> +<p>The System Interfaces volume of POSIX.1-2024 and this volume of POSIX.1-2024 do not require specific signal numbers for any +<i>signal_names</i>. Even the <b>-</b><i>signal_number</i> option provides symbolic (although numeric) names for signals. If a +process is terminated by a signal, its exit status indicates the signal that killed it, but the exact values are not specified. The +<i>kill</i> <b>-l</b> option, however, can be used to map decimal signal numbers and exit status values into the name of a signal. +The following example reports the status of a terminated job:</p> +<pre> +<tt>job +stat=$? +if [ $stat -eq 0 ] +then + echo job completed successfully. +elif [ $stat -gt 128 ] +then + echo job terminated by signal SIG$(kill -l $stat). +else + echo job terminated with error code $stat. +fi +</tt></pre> +<p>To send the default signal to a process group (say 123), an application should use a command similar to one of the +following:</p> +<pre> +<tt>kill -s TERM -- -123 +kill -- -123 +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_64_18" id="tag_20_64_18"></a>RATIONALE</h4> +<blockquote> +<p>The <b>-l</b> option originated from the C shell, and is also implemented in the KornShell. The C shell output can consist of +multiple output lines because the signal names do not always fit on a single line on some terminal screens. The KornShell output +also included the implementation-defined signal numbers and was considered by the standard developers to be too difficult for +scripts to parse conveniently. The specified output format is intended not only to accommodate the historical C shell output, but +also to permit an entirely vertical or entirely horizontal listing on systems for which this is appropriate.</p> +<p>An early proposal invented the name SIGNULL as a <i>signal_name</i> for signal 0 (used by the System Interfaces volume of +POSIX.1-2024 to test for the existence of a process without sending it a signal). Since the <i>signal_name</i> 0 can be used in +this case unambiguously, SIGNULL has been removed.</p> +<p>An early proposal also required symbolic <i>signal_name</i>s to be recognized with or without the <b>SIG</b> prefix. Historical +versions of <i>kill</i> have not written the <b>SIG</b> prefix for the <b>-l</b> option and have not recognized the <b>SIG</b> +prefix on <i>signal_name</i>s. Since neither applications portability nor ease-of-use would be improved by requiring this +extension, it is no longer required.</p> +<p>To avoid an ambiguity of an initial negative number argument specifying either a signal number or a process group, POSIX.1-2024 +mandates that it is always considered the former by implementations that support the XSI option. It also requires that conforming +applications always use the <tt>"--"</tt> options terminator argument when specifying a process group.</p> +<p>The <b>-s</b> option was added in response to international interest in providing some form of <i>kill</i> that meets the +Utility Syntax Guidelines.</p> +<p>The job ID notation is not required to work as expected when <i>kill</i> is operating in its own utility execution environment. +In either of the following examples:</p> +<pre> +<tt>nohup kill %1 & +system("kill %1"); +</tt></pre> +<p>the <i>kill</i> operates in a different environment and does not understand how the shell has managed its job numbers.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_64_19" id="tag_20_64_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_64_20" id="tag_20_64_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19"><i>2. Shell Command Language</i></a> , <a href= +"../utilities/ps.html#"><i>ps</i></a> , <a href="../utilities/wait.html#tag_20_147"><i>wait</i></a></p> +<p>XBD <a href="../basedefs/V1_chap03.html#tag_03_182"><i>3.182 Job ID</i></a> , <a href="../basedefs/V1_chap08.html#tag_08"><i>8. +Environment Variables</i></a> , <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a> , <a href= +"../basedefs/signal.h.html"><i><signal.h></i></a></p> +<p>XSH <a href="../functions/kill.html#tag_17_296"><i>kill</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_64_21" id="tag_20_64_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_64_22" id="tag_20_64_22"></a>Issue 6</h4> +<blockquote> +<p>The obsolescent versions of the SYNOPSIS are turned into non-obsolescent features of the XSI option, corresponding to a similar +change in the <a href="../utilities/V3_chap02.html#trap"><i>trap</i></a> special built-in.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_64_23" id="tag_20_64_23"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_64_24" id="tag_20_64_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 854 is applied, adding a note to the APPLICATION USAGE section that this utility is required to be +intrinsic.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1254 is applied, clarifying the <b>-l</b> option with regard to an <i>exit_status</i> operand corresponding +to a stopped process, changing "job control job ID" to "job ID", and adding a paragraph to the RATIONALE section.</p> +<p>Austin Group Defect 1260 is applied, changing the SYNOPSIS and EXAMPLES sections in relation to the <b>-s</b> option, and the +RATIONALE section in relation to the use of <tt>"--"</tt> when specifying a process group.</p> +<p>Austin Group Defect 1504 is applied, changing the EXIT STATUS section.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/join.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/lex.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/lex.html b/bdd/lex.html @@ -0,0 +1,860 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>lex</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/kill.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/link.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="lex" id="lex"></a> <a name="tag_20_65" id="tag_20_65"></a><!-- lex --> +<h4 class="mansect"><a name="tag_20_65_01" id="tag_20_65_01"></a>NAME</h4> +<blockquote>lex — generate programs for lexical tasks (<b>DEVELOPMENT</b>)</blockquote> +<h4 class="mansect"><a name="tag_20_65_02" id="tag_20_65_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('CD')">CD</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> lex</tt> <b>[</b><tt>-t</tt><b>] [</b><tt>-n|-v</tt><b>] [</b><i>file</i><tt>...</tt><b>]</b> +<tt><img src="../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div> +</blockquote> +<h4 class="mansect"><a name="tag_20_65_03" id="tag_20_65_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>lex</i> utility shall generate C programs to be used in lexical processing of character input, and that can be used as an +interface to <a href="../utilities/yacc.html"><i>yacc</i></a>. The C programs shall be generated from <i>lex</i> source code and +conform to the ISO C standard, without depending on any undefined, unspecified, or implementation-defined behavior, except in +cases where the code is copied directly from the supplied source, or in cases that are documented by the implementation. Usually, +the <i>lex</i> utility shall write the program it generates to the file <b>lex.yy.c</b>; the state of this file is unspecified if +<i>lex</i> exits with a non-zero exit status. See the EXTENDED DESCRIPTION section for a complete description of the <i>lex</i> +input language.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_65_04" id="tag_20_65_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>lex</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> , except for Guideline 9.</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-n</b></dt> +<dd>Suppress the summary of statistics usually written with the <b>-v</b> option. If no table sizes are specified in the <i>lex</i> +source code and the <b>-v</b> option is not specified, then <b>-n</b> is implied.</dd> +<dt><b>-t</b></dt> +<dd>Write the resulting program to standard output instead of <b>lex.yy.c</b>.</dd> +<dt><b>-v</b></dt> +<dd>Write a summary of <i>lex</i> statistics to the standard output. (See the discussion of <i>lex</i> table sizes in <a href= +"#tag_20_65_13_01">Definitions in lex</a> .) If the <b>-t</b> option is specified and <b>-n</b> is not specified, this report shall +be written to standard error. If table sizes are specified in the <i>lex</i> source code, and if the <b>-n</b> option is not +specified, the <b>-v</b> option may be enabled.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_65_05" id="tag_20_65_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of an input file. If more than one such <i>file</i> is specified, all files shall be concatenated to produce a +single <i>lex</i> program. If no <i>file</i> operands are specified, or if a <i>file</i> operand is <tt>'-'</tt>, the standard +input shall be used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_65_06" id="tag_20_65_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be used if no <i>file</i> operands are specified, or if a <i>file</i> operand is <tt>'-'</tt>. See +INPUT FILES.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_65_07" id="tag_20_65_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files shall be text files containing <i>lex</i> source code, as described in the EXTENDED DESCRIPTION section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_65_08" id="tag_20_65_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>lex</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null.</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_COLLATE</i></dt> +<dd><br> +Determine the locale for the behavior of ranges, equivalence classes, and multi-character collating elements within regular +expressions.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files), and the behavior of character classes within regular +expressions.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +<p>If the values (if any) of the <i>LANG ,</i> <i>LC_COLLATE ,</i> <i>LC_CTYPE ,</i> and <i>LC_ALL</i> variables result in the +locale in effect for the <i>LC_CTYPE</i> or <i>LC_COLLATE</i> category not being the POSIX locale, the behavior is unspecified. +(See XBD <a href="../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of +internationalization variables used to determine the values of locale categories.)</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_65_09" id="tag_20_65_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_65_10" id="tag_20_65_10"></a>STDOUT</h4> +<blockquote> +<p>If the <b>-t</b> option is specified, the text file of C source code output of <i>lex</i> shall be written to standard +output.</p> +<p>If the <b>-t</b> option is not specified:</p> +<ul> +<li> +<p>Implementation-defined informational, error, and warning messages concerning the contents of <i>lex</i> source code input shall +be written to either the standard output or standard error.</p> +</li> +<li> +<p>If the <b>-v</b> option is specified and the <b>-n</b> option is not specified, <i>lex</i> statistics shall also be written to +either the standard output or standard error, in an implementation-defined format. These statistics may also be generated if table +sizes are specified with a <tt>'%'</tt> operator in the <i>Definitions</i> section, as long as the <b>-n</b> option is not +specified.</p> +</li> +</ul> +</blockquote> +<h4 class="mansect"><a name="tag_20_65_11" id="tag_20_65_11"></a>STDERR</h4> +<blockquote> +<p>If the <b>-t</b> option is specified, implementation-defined informational, error, and warning messages concerning the contents +of <i>lex</i> source code input shall be written to the standard error.</p> +<p>If the <b>-t</b> option is not specified:</p> +<ol> +<li> +<p>Implementation-defined informational, error, and warning messages concerning the contents of <i>lex</i> source code input shall +be written to either the standard output or standard error.</p> +</li> +<li> +<p>If the <b>-v</b> option is specified and the <b>-n</b> option is not specified, <i>lex</i> statistics shall also be written to +either the standard output or standard error, in an implementation-defined format. These statistics may also be generated if table +sizes are specified with a <tt>'%'</tt> operator in the <i>Definitions</i> section, as long as the <b>-n</b> option is not +specified.</p> +</li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_65_12" id="tag_20_65_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>A text file containing C source code shall be written to <b>lex.yy.c</b>, or to the standard output if the <b>-t</b> option is +present.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_65_13" id="tag_20_65_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>Each input file shall contain <i>lex</i> source code, which is a table of regular expressions with corresponding actions in the +form of C program fragments.</p> +<p>When <b>lex.yy.c</b> is compiled and linked with the <i>lex</i> library (using the <b>-l l</b> operand with <a href= +"../utilities/c17.html"><i>c17</i></a>), the resulting program shall read character input from the standard input and shall +partition it into strings that match the given expressions.<br></p> +<p>When an expression is matched, these actions shall occur:</p> +<ul> +<li> +<p>The input string that was matched shall be left in <i>yytext</i> as a null-terminated string; <i>yytext</i> shall either be an +external character array or a pointer to a character string. As explained in <a href="#tag_20_65_13_01">Definitions in lex</a> , +the type can be explicitly selected using the <b>%array</b> or <b>%pointer</b> declarations, but the default is +implementation-defined.</p> +</li> +<li> +<p>The external <b>int</b> <i>yyleng</i> shall be set to the length of the matching string.</p> +</li> +<li> +<p>The expression's corresponding program fragment, or action, shall be executed.</p> +</li> +</ul> +<p>During pattern matching, <i>lex</i> shall search the set of patterns for the single longest possible match. Among rules that +match the same number of characters, the rule given first shall be chosen.</p> +<p>The general format of <i>lex</i> source shall be:</p> +<blockquote> +<pre> +<i>Definitions</i> +<b>%%</b> +<i>Rules</i> +<b>%%</b> +<i>User</i>Subroutines +</pre></blockquote> +<p>The first <tt>"%%"</tt> is required to mark the beginning of the rules (regular expressions and actions); the second +<tt>"%%"</tt> is required only if user subroutines follow.</p> +<p>Any line in the <i>Definitions</i> section beginning with a <blank> shall be assumed to be a C program fragment and shall +be copied to the external definition area of the <b>lex.yy.c</b> file. Similarly, anything in the <i>Definitions</i> section +included between delimiter lines containing only <tt>"%{"</tt> and <tt>"%}"</tt> shall also be copied unchanged to the external +definition area of the <b>lex.yy.c</b> file.</p> +<p>Any such input (beginning with a <blank> or within <tt>"%{"</tt> and <tt>"%}"</tt> delimiter lines) appearing at the +beginning of the <i>Rules</i> section before any rules are specified shall be written to <b>lex.yy.c</b> after the declarations of +variables for the <i>yylex</i>() function and before the first line of code in <i>yylex</i>(). Thus, user variables local to +<i>yylex</i>() can be declared here, as well as application code to execute upon entry to <i>yylex</i>().</p> +<p>The action taken by <i>lex</i> when encountering any input beginning with a <blank> or within <tt>"%{"</tt> and +<tt>"%}"</tt> delimiter lines appearing in the <i>Rules</i> section but coming after one or more rules is undefined. The presence +of such input may result in an erroneous definition of the <i>yylex</i>() function.</p> +<p>C-language code in the input shall not contain C-language trigraphs. The C-language code within <tt>"%{"</tt> and <tt>"%}"</tt> +delimiter lines shall not contain any lines consisting only of <tt>"%}"</tt>, or only of <tt>"%%"</tt>.</p> +<h5><a name="tag_20_65_13_01" id="tag_20_65_13_01"></a>Definitions in lex</h5> +<p><i>Definitions</i> appear before the first <tt>"%%"</tt> delimiter. Any line in this section not contained between <tt>"%{"</tt> +and <tt>"%}"</tt> lines and not beginning with a <blank> shall be assumed to define a <i>lex</i> substitution string. The +format of these lines shall be:</p> +<pre> +<i>name substitute</i><tt> +</tt></pre> +<p>If a <i>name</i> does not meet the requirements for identifiers in the ISO C standard, the result is undefined. The string +<i>substitute</i> shall replace the string {<i>name</i>} when it is used in a rule. The <i>name</i> string shall be recognized in +this context only when the braces are provided and when it does not appear within a bracket expression or within double-quotes.</p> +<p>In the <i>Definitions</i> section, any line beginning with a <percent-sign> (<tt>'%'</tt>) character and followed by an +alphanumeric word beginning with either <tt>'s'</tt> or <tt>'S'</tt> shall define a set of start conditions. Any line beginning +with a <tt>'%'</tt> followed by a word beginning with either <tt>'x'</tt> or <tt>'X'</tt> shall define a set of exclusive start +conditions. When the generated scanner is in a <tt>%s</tt> state, patterns with no state specified shall be also active; in a +<tt>%x</tt> state, such patterns shall not be active. The rest of the line, after the first word, shall be considered to be one or +more <blank>-separated names of start conditions. Start condition names shall be constructed in the same way as definition +names. Start conditions can be used to restrict the matching of regular expressions to one or more states as described in <a href= +"#tag_20_65_13_04">Regular Expressions in lex</a> .</p> +<p>Implementations shall accept either of the following two mutually-exclusive declarations in the <i>Definitions</i> section:</p> +<dl compact> +<dd></dd> +<dt><b>%array</b></dt> +<dd>Declare the type of <i>yytext</i> to be a null-terminated character array.</dd> +<dt><b>%pointer</b></dt> +<dd>Declare the type of <i>yytext</i> to be a pointer to a null-terminated character string.</dd> +</dl> +<p>The default type of <i>yytext</i> is implementation-defined. If an application refers to <i>yytext</i> outside of the scanner +source file (that is, via an <b>extern</b>), the application shall include the appropriate <b>%array</b> or <b>%pointer</b> +declaration in the scanner source file.</p> +<p>Implementations shall accept declarations in the <i>Definitions</i> section for setting certain internal table sizes. The +declarations are shown in the following table.</p> +<p class="caption">Table: Table Size Declarations in <i>lex</i></p> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Declaration</b></p> +</th> +<th align="center"> +<p class="tent"><b>Description</b></p> +</th> +<th align="center"> +<p class="tent"><b>Minimum Value</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">%<b>p</b> <i>n</i></p> +</td> +<td align="left"> +<p class="tent">Number of positions</p> +</td> +<td align="left"> +<p class="tent">2500</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">%<b>n</b> <i>n</i></p> +</td> +<td align="left"> +<p class="tent">Number of states</p> +</td> +<td align="left"> +<p class="tent">500</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">%<b>a</b> <i>n</i></p> +</td> +<td align="left"> +<p class="tent">Number of transitions</p> +</td> +<td align="left"> +<p class="tent">2000</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">%<b>e</b> <i>n</i></p> +</td> +<td align="left"> +<p class="tent">Number of parse tree nodes</p> +</td> +<td align="left"> +<p class="tent">1000</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">%<b>k</b> <i>n</i></p> +</td> +<td align="left"> +<p class="tent">Number of packed character classes</p> +</td> +<td align="left"> +<p class="tent">1000</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">%<b>o</b> <i>n</i></p> +</td> +<td align="left"> +<p class="tent">Size of the output array</p> +</td> +<td align="left"> +<p class="tent">3000</p> +</td> +</tr> +</table> +</center> +<p class="tent">In the table, <i>n</i> represents a positive decimal integer, preceded by one or more <blank> characters. The +exact meaning of these table size numbers is implementation-defined. The implementation shall document how these numbers affect the +<i>lex</i> utility and how they are related to any output that may be generated by the implementation should limitations be +encountered during the execution of <i>lex</i>. It shall be possible to determine from this output which of the table size values +needs to be modified to permit <i>lex</i> to successfully generate tables for the input language. The values in the column Minimum +Value represent the lowest values conforming implementations shall provide.</p> +<h5><a name="tag_20_65_13_02" id="tag_20_65_13_02"></a>Rules in lex</h5> +<p class="tent">The rules in <i>lex</i> source files are a table in which the left column contains regular expressions and the +right column contains actions (C program fragments) to be executed when the expressions are recognized.</p> +<pre> +<i>ERE action +ERE action</i><tt> +... +</tt></pre> +<p class="tent">The extended regular expression (ERE) portion of a row shall be separated from <i>action</i> by one or more +<blank> characters. A regular expression containing <blank> characters shall be recognized under one of the following +conditions:</p> +<ul> +<li class="tent">The entire expression appears within double-quotes.</li> +<li class="tent">The <blank> characters appear within double-quotes or square brackets.</li> +<li class="tent">Each <blank> is preceded by a <backslash> character.</li> +</ul> +<h5><a name="tag_20_65_13_03" id="tag_20_65_13_03"></a>User Subroutines in lex</h5> +<p class="tent">Anything in the user subroutines section shall be copied to <b>lex.yy.c</b> following <i>yylex</i>().</p> +<h5><a name="tag_20_65_13_04" id="tag_20_65_13_04"></a>Regular Expressions in lex</h5> +<p class="tent">The <i>lex</i> utility shall support the set of extended regular expressions (see XBD <a href= +"../basedefs/V1_chap09.html#tag_09_04"><i>9.4 Extended Regular Expressions</i></a> ), with the following additions and exceptions +to the syntax:</p> +<dl compact> +<dd></dd> +<dt><tt>"..."</tt></dt> +<dd>Any string enclosed in double-quotes shall represent the characters within the double-quotes as themselves, except that +<backslash>-escapes (which appear in the following table) shall be recognized. Any <backslash>-escape sequence shall be +terminated by the closing quote. For example, <tt>"\01"</tt><tt>"1"</tt> represents a single string: the octal value 1 followed by +the character <tt>'1'</tt>.</dd> +<dt><<i>state</i>><i>r</i>, <<i>state1,state2,</i>...><i>r</i></dt> +<dd><br> +The regular expression <i>r</i> shall be matched only when the program is in one of the start conditions indicated by <i>state</i>, +<i>state1</i>, and so on; see <a href="#tag_20_65_13_05">Actions in lex</a> . (As an exception to the typographical conventions of +the rest of this volume of POSIX.1-2024, in this case <<i>state</i>> does not represent a metavariable, but the literal +angle-bracket characters surrounding a symbol.) The start condition shall be recognized as such only at the beginning of a regular +expression.</dd> +<dt><i>r</i>/<i>x</i></dt> +<dd>The regular expression <i>r</i> shall be matched only if it is followed by an occurrence of regular expression <i>x</i> +(<i>x</i> is the instance of trailing context, further defined below). The token returned in <i>yytext</i> shall only match +<i>r</i>. If the trailing portion of <i>r</i> matches the beginning of <i>x</i>, the result is unspecified. The <i>r</i> expression +cannot include further trailing context or the <tt>'$'</tt> (match-end-of-line) operator; <i>x</i> cannot include the <tt>'^'</tt> +(match-beginning-of-line) operator, nor trailing context, nor the <tt>'$'</tt> operator. That is, only one occurrence of trailing +context is allowed in a <i>lex</i> regular expression, and the <tt>'^'</tt> operator only can be used at the beginning of such an +expression.</dd> +<dt>{<i>name</i>}</dt> +<dd>When <i>name</i> is one of the substitution symbols from the <i>Definitions</i> section, the string, including the enclosing +braces, shall be replaced by the <i>substitute</i> value. The <i>substitute</i> value shall be treated in the extended regular +expression as if it were enclosed in parentheses. No substitution shall occur if {<i>name</i>} occurs within a bracket expression +or within double-quotes.</dd> +</dl> +<p class="tent">Within an ERE, a <backslash> character shall be considered to begin an escape sequence as specified in the +table in XBD <a href="../basedefs/V1_chap05.html#tag_05"><i>5. File Format Notation</i></a> (<tt>'\\'</tt>, <tt>'\a'</tt>, +<tt>'\b'</tt>, <tt>'\f'</tt>, <tt>'\n'</tt>, <tt>'\r'</tt>, <tt>'\t'</tt>, <tt>'\v'</tt>). In addition, the escape sequences in the +following table shall be recognized.</p> +<p class="tent">A literal <newline> cannot occur within an ERE; the escape sequence <tt>'\n'</tt> can be used to represent a +<newline>. A <newline> shall not be matched by a period operator.<br></p> +<p class="caption">Table: Escape Sequences in <i>lex</i></p> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Escape Sequence</b></p> +</th> +<th align="center"> +<p class="tent"><b>Description</b></p> +</th> +<th align="center"> +<p class="tent"><b>Meaning</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">\<i>digits</i></p> +</td> +<td align="left"> +<p class="tent">A <backslash> character followed by the longest sequence of one, two, or three octal-digit characters +(01234567). If all of the digits are 0 (that is, representation of the NUL character), the behavior is undefined.</p> +</td> +<td align="left"> +<p class="tent">The character whose encoding is represented by the one, two, or three-digit octal integer. Multi-byte characters +require multiple, concatenated escape sequences of this type, including the leading <backslash> for each byte.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">\x<i>digits</i></p> +</td> +<td align="left"> +<p class="tent">A <backslash> character followed by the longest sequence of hexadecimal-digit characters +(01234567abcdefABCDEF). If all of the digits are 0 (that is, representation of the NUL character), the behavior is undefined.</p> +</td> +<td align="left"> +<p class="tent">The character whose encoding is represented by the hexadecimal integer.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">\c</p> +</td> +<td align="left"> +<p class="tent">A <backslash> character followed by any character not described in this table or in the table in XBD <a href= +"../basedefs/V1_chap05.html#tag_05"><i>5. File Format Notation</i></a> (<tt>'\\'</tt>, <tt>'\a'</tt>, <tt>'\b'</tt>, <tt>'\f'</tt>, +<tt>'\n'</tt>, <tt>'\r'</tt>, <tt>'\t'</tt>, <tt>'\v'</tt>).</p> +</td> +<td align="left"> +<p class="tent">The character <tt>'c'</tt>, unchanged.</p> +</td> +</tr> +</table> +</center> +<basefont size="2"> +<dl> +<dt><b>Note:</b></dt> +<dd>If a <tt>'\x'</tt> sequence needs to be immediately followed by a hexadecimal digit character, a sequence such as +<tt>"\x1"</tt><tt>"1"</tt> can be used, which represents a character containing the value 1, followed by the character +<tt>'1'</tt>.</dd> +</dl> +<basefont size="3"> +<p class="tent">The order of precedence given to extended regular expressions for <i>lex</i> differs from that specified in XBD +<a href="../basedefs/V1_chap09.html#tag_09_04"><i>9.4 Extended Regular Expressions</i></a> . The order of precedence for <i>lex</i> +shall be as shown in the following table, from high to low. <basefont size="2"></p> +<dl> +<dt><b>Note:</b></dt> +<dd>The escaped characters entry is not meant to imply that these are operators, but they are included in the table to show their +relationships to the true operators. The start condition, trailing context, and anchoring notations have been omitted from the +table because of the placement restrictions described in this section; they can only appear at the beginning or ending of an +ERE.</dd> +</dl> +<basefont size="3"><br> +<p class="caption">Table: ERE Precedence in <i>lex</i></p> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Extended Regular Expression</b></p> +</th> +<th align="center"> +<p class="tent"><b>Precedence</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">collation-related bracket symbols</p> +</td> +<td align="left"> +<p class="tent">[= =] [: :] [. .]</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">escaped characters</p> +</td> +<td align="left"> +<p class="tent">\<<i>special character</i>></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">bracket expression</p> +</td> +<td align="left"> +<p class="tent">[ ]</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">quoting</p> +</td> +<td align="left"> +<p class="tent">"..."</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">grouping</p> +</td> +<td align="left"> +<p class="tent">( )</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">definition</p> +</td> +<td align="left"> +<p class="tent">{<i>name</i>}</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">single-character RE duplication</p> +</td> +<td align="left"> +<p class="tent">* + ?</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">concatenation</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">interval expression</p> +</td> +<td align="left"> +<p class="tent">{m,n}</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">alternation</p> +</td> +<td align="left"> +<p class="tent">|</p> +</td> +</tr> +</table> +</center> +<p class="tent">The ERE anchoring operators <tt>'^'</tt> and <tt>'$'</tt> do not appear in the table. With <i>lex</i> regular +expressions, these operators are restricted in their use: the <tt>'^'</tt> operator can only be used at the beginning of an entire +regular expression, and the <tt>'$'</tt> operator only at the end. The operators apply to the entire regular expression. Thus, for +example, the pattern <tt>"(^abc)|(def$)"</tt> is undefined; it can instead be written as two separate rules, one with the regular +expression <tt>"^abc"</tt> and one with <tt>"def$"</tt>, which share a common action via the special <tt>'|'</tt> action (see +below). If the pattern were written <tt>"^abc|def$"</tt>, it would match either <tt>"abc"</tt> or <tt>"def"</tt> on a line by +itself.</p> +<p class="tent">Unlike the general ERE rules, embedded anchoring is not allowed by most historical <i>lex</i> implementations. An +example of embedded anchoring would be for patterns such as <tt>"(^| )foo( |$)"</tt> to match <tt>"foo"</tt> when it +exists as a complete word. This functionality can be obtained using existing <i>lex</i> features:</p> +<pre> +<tt>^foo/[ \n] | +" foo"/[ \n] /* Found foo as a separate word. */ +</tt></pre> +<p class="tent">Note also that <tt>'$'</tt> is a form of trailing context (it is equivalent to <tt>"/\n"</tt>) and as such cannot +be used with regular expressions containing another instance of the operator (see the preceding discussion of trailing +context).</p> +<p class="tent">The additional regular expressions trailing-context operator <tt>'/'</tt> can be used as an ordinary character if +presented within double-quotes, <tt>"/"</tt>; preceded by a <backslash>, <tt>"\/"</tt>; or within a bracket expression, +<tt>"[/]"</tt>. The start-condition <tt>'<'</tt> and <tt>'>'</tt> operators shall be special only in a start condition at the +beginning of a regular expression; elsewhere in the regular expression they shall be treated as ordinary characters.</p> +<h5><a name="tag_20_65_13_05" id="tag_20_65_13_05"></a>Actions in lex</h5> +<p class="tent">The action to be taken when an ERE is matched can be a C program fragment or the special actions described below; +the program fragment can contain one or more C statements, and can also include special actions. The empty C statement <tt>';'</tt> +shall be a valid action; any string in the <b>lex.yy.c</b> input that matches the pattern portion of such a rule is effectively +ignored or skipped. However, the absence of an action shall not be valid, and the action <i>lex</i> takes in such a condition is +undefined.</p> +<p class="tent">The specification for an action, including C statements and special actions, can extend across several lines if +enclosed in braces:</p> +<pre> +<i>ERE</i><tt> <</tt><i>one or more blanks</i><tt>> { </tt><i>program statement + program statement</i><tt> } +</tt></pre> +<p class="tent">The program statements shall not contain unbalanced curly brace preprocessing tokens.</p> +<p class="tent">The default action when a string in the input to a <b>lex.yy.c</b> program is not matched by any expression shall +be to copy the string to the output. Because the default behavior of a program generated by <i>lex</i> is to read the input and +copy it to the output, a minimal <i>lex</i> source program that has just <tt>"%%"</tt> shall generate a C program that simply +copies the input to the output unchanged.</p> +<p class="tent">Four special actions shall be available:</p> +<pre> +<tt>| ECHO; REJECT; BEGIN +</tt></pre> +<dl compact> +<dd></dd> +<dt><tt>|</tt></dt> +<dd>The action <tt>'|'</tt> means that the action for the next rule is the action for this rule. Unlike the other three actions, +<tt>'|'</tt> cannot be enclosed in braces or be <semicolon>-terminated; the application shall ensure that it is specified +alone, with no other actions.</dd> +<dt><b>ECHO;</b></dt> +<dd>Write the contents of the string <i>yytext</i> on the output.</dd> +<dt><b>REJECT;</b></dt> +<dd>Usually only a single expression is matched by a given string in the input. <b>REJECT</b> means "continue to the next +expression that matches the current input", and shall cause whatever rule was the second choice after the current rule to be +executed for the same input. Thus, multiple rules can be matched and executed for one input string or overlapping input strings. +For example, given the regular expressions <tt>"xyz"</tt> and <tt>"xy"</tt> and the input <tt>"xyz"</tt>, usually only the regular +expression <tt>"xyz"</tt> would match. The next attempted match would start after <b>z.</b> If the last action in the +<tt>"xyz"</tt> rule is <b>REJECT</b>, both this rule and the <tt>"xy"</tt> rule would be executed. The <b>REJECT</b> action may be +implemented in such a fashion that flow of control does not continue after it, as if it were equivalent to a <b>goto</b> to another +part of <i>yylex</i>(). The use of <b>REJECT</b> may result in somewhat larger and slower scanners.</dd> +<dt><b>BEGIN</b></dt> +<dd>The action: +<pre> +<tt>BEGIN </tt><i>newstate</i><tt>; +</tt></pre> +<p class="tent">switches the state (start condition) to <i>newstate</i>. If the string <i>newstate</i> has not been declared +previously as a start condition in the <i>Definitions</i> section, the results are unspecified. The initial state is indicated by +the digit <tt>'0'</tt> or the token <b>INITIAL</b>.</p> +</dd> +</dl> +<p class="tent">The functions or macros described below are accessible to user code included in the <i>lex</i> input. It is +unspecified whether they appear in the C code output of <i>lex</i>, or are accessible only through the <b>-l l</b> operand to +<a href="../utilities/c17.html"><i>c17</i></a> (the <i>lex</i> library).</p> +<dl compact> +<dd></dd> +<dt><b>int </b><i>yylex</i>(<b>void</b>)</dt> +<dd><br> +Performs lexical analysis on the input; this is the primary function generated by the <i>lex</i> utility. The function shall return +zero when the end of input is reached; otherwise, it shall return non-zero values (tokens) determined by the actions that are +selected.</dd> +<dt><b>int </b><i>yymore</i>(<b>void</b>)</dt> +<dd><br> +When called, indicates that when the next input string is recognized, it is to be appended to the current value of <i>yytext</i> +rather than replacing it; the value in <i>yyleng</i> shall be adjusted accordingly.</dd> +<dt><b>int </b><i>yyless</i>(<b>int </b><i>n</i>)</dt> +<dd><br> +Retains <i>n</i> initial characters in <i>yytext</i>, NUL-terminated, and treats the remaining characters as if they had not been +read; the value in <i>yyleng</i> shall be adjusted accordingly.</dd> +<dt><b>int </b><i>input</i>(<b>void</b>)</dt> +<dd><br> +Returns the next character from the input, or zero on end-of-file. It shall obtain input from the stream pointer <i>yyin</i>, +although possibly via an intermediate buffer. Thus, once scanning has begun, the effect of altering the value of <i>yyin</i> is +undefined. The character read shall be removed from the input stream of the scanner without any processing by the scanner.</dd> +<dt><b>int </b><i>unput</i>(<b>int </b><i>c</i>)</dt> +<dd><br> +Returns the character <tt>'c'</tt> to the input; <i>yytext</i> and <i>yyleng</i> are undefined until the next expression is +matched. The result of using <i>unput</i>() for more characters than have been input is unspecified.</dd> +</dl> +<p class="tent">The following functions shall appear only in the <i>lex</i> library accessible through the <b>-l l</b> +operand; they can therefore be redefined by a conforming application:</p> +<dl compact> +<dd></dd> +<dt><b>int </b><i>yywrap</i>(<b>void</b>)</dt> +<dd><br> +Called by <i>yylex</i>() at end-of-file; the default <i>yywrap</i>() shall always return 1. If the application requires +<i>yylex</i>() to continue processing with another source of input, then the application can include a function <i>yywrap</i>(), +which associates another file with the external variable <b>FILE *</b> <i>yyin</i> and shall return a value of zero.</dd> +<dt><b>int </b><i>main</i>(<b>int </b><i>argc</i>, <b>char *</b><i>argv</i>[])</dt> +<dd><br> +Calls <i>yylex</i>() to perform lexical analysis, then exits. The user code can contain <i>main</i>() to perform +application-specific operations, calling <i>yylex</i>() as applicable.</dd> +</dl> +<p class="tent">Except for <i>input</i>(), <i>unput</i>(), and <i>main</i>(), all external and static names generated by <i>lex</i> +shall begin with the prefix <b>yy</b> or <b>YY</b>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_65_14" id="tag_20_65_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_65_15" id="tag_20_65_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_65_16" id="tag_20_65_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Conforming applications are warned that in the <i>Rules</i> section, an ERE without an action is not acceptable, but need not be +detected as erroneous by <i>lex</i>. This may result in compilation or runtime errors.</p> +<p class="tent">The purpose of <i>input</i>() is to take characters off the input stream and discard them as far as the lexical +analysis is concerned. A common use is to discard the body of a comment once the beginning of a comment is recognized.</p> +<p class="tent">The <i>lex</i> utility is not fully internationalized in its treatment of regular expressions in the <i>lex</i> +source code or generated lexical analyzer. It would seem desirable to have the lexical analyzer interpret the regular expressions +given in the <i>lex</i> source according to the environment specified when the lexical analyzer is executed, but this is not +possible with the current <i>lex</i> technology. Furthermore, the very nature of the lexical analyzers produced by <i>lex</i> must +be closely tied to the lexical requirements of the input language being described, which is frequently locale-specific anyway. (For +example, writing an analyzer that is used for French text is not automatically useful for processing other languages.)</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_65_17" id="tag_20_65_17"></a>EXAMPLES</h4> +<blockquote> +<p>The following is an example of a <i>lex</i> program that implements a rudimentary scanner for a Pascal-like syntax:</p> +<pre> +<tt>%{ +/* Need this for the call to atof() below. */ +#include <math.h> +/* Need this for printf(), fopen(), and stdin below. */ +#include <stdio.h> +%} +DIGIT [0-9] +ID [a-z][a-z0-9]* +%% +{DIGIT}+ { + printf("An integer: %s (%d)\n", yytext, + atoi(yytext)); + } +{DIGIT}+"."{DIGIT}* { + printf("A float: %s (%g)\n", yytext, + atof(yytext)); + } +if|then|begin|end|procedure|function { + printf("A keyword: %s\n", yytext); + } +{ID} printf("An identifier: %s\n", yytext); +"+"|"-"|"*"|"/" printf("An operator: %s\n", yytext); +"{"[^}\n]*"}" /* Eat up one-line comments. */ +[ \t\n]+ /* Eat up white space. */ +. printf("Unrecognized character: %s\n", yytext); +%% +int main(int argc, char *argv[]) +{ + ++argv, --argc; /* Skip over program name. */ + if (argc > 0) + yyin = fopen(argv[0], "r"); + else + yyin = stdin; + yylex(); +} +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_65_18" id="tag_20_65_18"></a>RATIONALE</h4> +<blockquote> +<p>Even though references to the C language are retained in this description, <i>lex</i> may be generalized to other languages, as +was done at one time for EFL, the Extended FORTRAN Language. Since the <i>lex</i> input specification is essentially +language-independent, versions of this utility could be written to produce Ada, Modula-2, or Pascal code, and there are known +historical implementations that do so.</p> +<p class="tent">The current description of <i>lex</i> bypasses the issue of dealing with internationalized EREs in the <i>lex</i> +source code or generated lexical analyzer. If it follows the model used by <a href="../utilities/awk.html"><i>awk</i></a> (the +source code is assumed to be presented in the POSIX locale, but input and output are in the locale specified by the environment +variables), then the tables in the lexical analyzer produced by <i>lex</i> would interpret EREs specified in the <i>lex</i> source +in terms of the environment variables specified when <i>lex</i> was executed. The desired effect would be to have the lexical +analyzer interpret the EREs given in the <i>lex</i> source according to the environment specified when the lexical analyzer is +executed, but this is not possible with the current <i>lex</i> technology.</p> +<p class="tent">The description of octal and hexadecimal-digit escape sequences agrees with the ISO C standard use of escape +sequences.</p> +<p class="tent">Earlier versions of this standard allowed for implementations with bytes other than eight bits, but this has been +modified in this version.</p> +<p class="tent">There is no detailed output format specification. The observed behavior of <i>lex</i> under four different +historical implementations was that none of these implementations consistently reported the line numbers for error and warning +messages. Furthermore, there was a desire that <i>lex</i> be allowed to output additional diagnostic messages. Leaving message +formats unspecified avoids these formatting questions and problems with internationalization.</p> +<p class="tent">Although the <tt>%x</tt> specifier for <i>exclusive</i> start conditions is not historical practice, it is believed +to be a minor change to historical implementations and greatly enhances the usability of <i>lex</i> programs since it permits an +application to obtain the expected functionality with fewer statements.</p> +<p class="tent">The <b>%array</b> and <b>%pointer</b> declarations were added as a compromise between historical systems. The +System V-based <i>lex</i> copies the matched text to a <i>yytext</i> array. The <i>flex</i> program, supported in BSD and GNU +systems, uses a pointer. In the latter case, significant performance improvements are available for some scanners. Most historical +programs should require no change in porting from one system to another because the string being referenced is null-terminated in +both cases. (The method used by <i>flex</i> in its case is to null-terminate the token in place by remembering the character that +used to come right after the token and replacing it before continuing on to the next scan.) Multi-file programs with external +references to <i>yytext</i> outside the scanner source file should continue to operate on their historical systems, but would +require one of the new declarations to be considered strictly portable.</p> +<p class="tent">The description of EREs avoids unnecessary duplication of ERE details because their meanings within a <i>lex</i> +ERE are the same as that for the ERE in this volume of POSIX.1-2024.</p> +<p class="tent">The reason for the undefined condition associated with text beginning with a <blank> or within <tt>"%{"</tt> +and <tt>"%}"</tt> delimiter lines appearing in the <i>Rules</i> section is historical practice. Both the BSD and System V +<i>lex</i> copy the indented (or enclosed) input in the <i>Rules</i> section (except at the beginning) to unreachable areas of the +<i>yylex</i>() function (the code is written directly after a <a href="../utilities/V3_chap02.html#break"><i>break</i></a> +statement). In some cases, the System V <i>lex</i> generates an error message or a syntax error, depending on the form of indented +input.</p> +<p class="tent">The intention in breaking the list of functions into those that may appear in <b>lex.yy.c</b> <i>versus</i> those +that only appear in <b>libl.a</b> is that only those functions in <b>libl.a</b> can be reliably redefined by a conforming +application.</p> +<p class="tent">The descriptions of standard output and standard error are somewhat complicated because historical <i>lex</i> +implementations chose to issue diagnostic messages to standard output (unless <b>-t</b> was given). POSIX.1-2024 allows this +behavior, but leaves an opening for the more expected behavior of using standard error for diagnostics. Also, the System V behavior +of writing the statistics when any table sizes are given is allowed, while BSD-derived systems can avoid it. The programmer can +always precisely obtain the desired results by using either the <b>-t</b> or <b>-n</b> options.</p> +<p class="tent">The OPERANDS section does not mention the use of <b>-</b> as a synonym for standard input; not all historical +implementations support such usage for any of the <i>file</i> operands.</p> +<p class="tent">A description of the <i>translation table</i> was deleted from early proposals because of its relatively low usage +in historical applications.</p> +<p class="tent">The change to the definition of the <i>input</i>() function that allows buffering of input presents the opportunity +for major performance gains in some applications.</p> +<p class="tent">The following examples clarify the differences between <i>lex</i> regular expressions and regular expressions +appearing elsewhere in this volume of POSIX.1-2024. For regular expressions of the form <tt>"r/x"</tt>, the string matching +<i>r</i> is always returned; confusion may arise when the beginning of <i>x</i> matches the trailing portion of <i>r</i>. For +example, given the regular expression <tt>"a*b/cc"</tt> and the input <tt>"aaabcc"</tt>, <i>yytext</i> would contain the string +<tt>"aaab"</tt> on this match. But given the regular expression <tt>"x*/xy"</tt> and the input <tt>"xxxy"</tt>, the token +<b>xxx</b>, not <b>xx</b>, is returned by some implementations because <b>xxx</b> matches <tt>"x*"</tt>.</p> +<p class="tent">In the rule <tt>"ab*/bc"</tt>, the <tt>"b*"</tt> at the end of <i>r</i> extends <i>r</i>'s match into the beginning +of the trailing context, so the result is unspecified. If this rule were <tt>"ab/bc"</tt>, however, the rule matches the text +<tt>"ab"</tt> when it is followed by the text <tt>"bc"</tt>. In this latter case, the matching of <i>r</i> cannot extend into the +beginning of <i>x</i>, so the result is specified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_65_19" id="tag_20_65_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_65_20" id="tag_20_65_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/c17.html#"><i>c17</i></a> , <a href="../utilities/ed.html#"><i>ed</i></a> , <a href= +"../utilities/yacc.html#"><i>yacc</i></a></p> +<p class="tent">XBD <a href="../basedefs/V1_chap05.html#tag_05"><i>5. File Format Notation</i></a> , <a href= +"../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href="../basedefs/V1_chap09.html#tag_09"><i>9. Regular +Expressions</i></a> , <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_65_21" id="tag_20_65_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_65_22" id="tag_20_65_22"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the C-Language Development Utilities option.</p> +<p class="tent">The obsolescent <b>-c</b> option is removed.</p> +<p class="tent">The normative text is reworded to avoid use of the term "must" for application requirements.</p> +<p class="tent">IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/14 is applied, removing text describing behavior on +systems with bytes consisting of more than eight bits.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_65_23" id="tag_20_65_23"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #190 is applied, clarifying the requirements for generated code to conform to the +ISO C standard.</p> +<p class="tent">Austin Group Interpretation 1003.1-2001 #191 is applied, clarifying the handling of C-language trigraphs and curly +brace preprocessing tokens.</p> +<p class="tent">SD5-XCU-ERN-6 is applied, clarifying that Guideline 9 of the Utility Syntax Guidelines does not apply.</p> +<p class="tent">SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_65_24" id="tag_20_65_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p class="tent">Austin Group Defect 1453 is applied, changing the ENVIRONMENT VARIABLES section.</p> +<p class="tent">Austin Group Defect 1517 is applied, removing a reference to the <b>-c</b> option from the RATIONALE section.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/kill.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/link.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/link.html b/bdd/link.html @@ -0,0 +1,182 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>link</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/lex.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/ln.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="link" id="link"></a> <a name="tag_20_66" id="tag_20_66"></a><!-- link --> +<h4 class="mansect"><a name="tag_20_66_01" id="tag_20_66_01"></a>NAME</h4> +<blockquote>link — call link function</blockquote> +<h4 class="mansect"><a name="tag_20_66_02" id="tag_20_66_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> link</tt> <i>file1 file2</i> <tt><img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></tt></code></div> +</blockquote> +<h4 class="mansect"><a name="tag_20_66_03" id="tag_20_66_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>link</i> utility shall perform the function call:</p> +<pre> +<tt>link(</tt><i>file1</i><tt>, </tt><i>file2</i><tt>); +</tt></pre> +<p>A user may need appropriate privileges to invoke the <i>link</i> utility.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_66_04" id="tag_20_66_04"></a>OPTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_66_05" id="tag_20_66_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file1</i></dt> +<dd>The pathname of an existing file.</dd> +<dt><i>file2</i></dt> +<dd>The pathname of the new directory entry to be created.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_66_06" id="tag_20_66_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_66_07" id="tag_20_66_07"></a>INPUT FILES</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_66_08" id="tag_20_66_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>link</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd>Determine the location of messages objects and message catalogs.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_66_09" id="tag_20_66_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_66_10" id="tag_20_66_10"></a>STDOUT</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_66_11" id="tag_20_66_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_66_12" id="tag_20_66_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_66_13" id="tag_20_66_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_66_14" id="tag_20_66_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_66_15" id="tag_20_66_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_66_16" id="tag_20_66_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_66_17" id="tag_20_66_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_66_18" id="tag_20_66_18"></a>RATIONALE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_66_19" id="tag_20_66_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a +<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require +implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_66_20" id="tag_20_66_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/ln.html#"><i>ln</i></a> , <a href="../utilities/unlink.html#tag_20_139"><i>unlink</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a></p> +<p>XSH <a href="../functions/link.html#tag_17_304"><i>link</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_66_21" id="tag_20_66_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 5.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_66_22" id="tag_20_66_22"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to disallow the creation of filenames containing any bytes that +have the encoded value of a <newline> character.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/lex.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/ln.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/ln.html b/bdd/ln.html @@ -0,0 +1,343 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>ln</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/link.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/locale.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="ln" id="ln"></a> <a name="tag_20_67" id="tag_20_67"></a><!-- ln --> +<h4 class="mansect"><a name="tag_20_67_01" id="tag_20_67_01"></a>NAME</h4> +<blockquote>ln — link files</blockquote> +<h4 class="mansect"><a name="tag_20_67_02" id="tag_20_67_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>ln</tt> <b>[</b><tt>-fs</tt><b>] [</b><tt>-L|-P</tt><b>]</b> <i>source_file target_file</i> <tt><br> +<br> +ln</tt> <b>[</b><tt>-fs</tt><b>] [</b><tt>-L|-P</tt><b>]</b> <i>source_file</i><tt>...</tt> <i>target_dir</i> <tt><br></tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_67_03" id="tag_20_67_03"></a>DESCRIPTION</h4> +<blockquote> +<p>In the first synopsis form, the <i>ln</i> utility shall create a new directory entry at the destination path specified by the +<i>target_file</i> operand. If the <b>-s</b> option is specified, a symbolic link shall be created with the contents specified by +the <i>source_file</i> operand (which need not name an existing file); otherwise, a hard link shall be created to the file named by +the <i>source_file</i> operand. This first synopsis form shall be assumed when the final operand does not name an existing +directory; if more than two operands are specified and the final is not an existing directory, an error shall result.</p> +<p>In the second synopsis form, the <i>ln</i> utility shall create a new directory entry for each <i>source_file</i> operand, at a +destination path in the existing directory named by <i>target_dir</i>. If the <b>-s</b> option is specified, a symbolic link shall +be created with the contents specified by each <i>source_file</i> operand (which need not name an existing file); otherwise, a hard +link shall be created to each file named by a <i>source_file</i> operand.</p> +<p>If the last operand specifies an existing file of a type not specified by the System Interfaces volume of POSIX.1-2024, the +behavior is implementation-defined.</p> +<p>The corresponding destination path for each <i>source_file</i> shall be the concatenation of the target directory pathname, a +<slash> character if the target directory pathname did not end in a <slash>, and the last pathname component of the +<i>source_file</i>. The second synopsis form shall be assumed when the final operand names an existing directory.</p> +<p>For each <i>source_file</i>:</p> +<ol> +<li> +<p>If the destination path exists and was created by a previous step, it is unspecified whether <i>ln</i> writes a diagnostic +message to standard error, does nothing more with the current <i>source_file</i>, and goes on to any remaining <i>source_file</i>s; +or continues processing the current <i>source_file</i>. If the destination path exists:</p> +<ol type="a"> +<li> +<p>If the <b>-f</b> option is not specified, <i>ln</i> shall write a diagnostic message to standard error, do nothing more with the +current <i>source_file</i>, and go on to any remaining <i>source_file</i>s.</p> +</li> +<li> +<p>If the destination path names the same directory entry as the current <i>source_file</i> <i>ln</i> shall write a diagnostic +message to standard error, do nothing more with the current <i>source_file</i>, and go on to any remaining +<i>source_file</i>s<i>.</i></p> +</li> +<li> +<p>Actions shall be performed equivalent to the <a href="../functions/unlink.html"><i>unlink</i>()</a> function defined in the +System Interfaces volume of POSIX.1-2024, called using the destination path as the <i>path</i> argument. If this fails for any +reason, <i>ln</i> shall write a diagnostic message to standard error, do nothing more with the current <i>source_file</i>, and go +on to any remaining <i>source_file</i>s.</p> +</li> +</ol> +</li> +<li> +<p>If the <b>-s</b> option is specified, actions shall be performed equivalent to the <a href= +"../functions/symlink.html"><i>symlink</i>()</a> function with <i>source_file</i> as the <i>path1</i> argument and the destination +path as the <i>path2</i> argument. The <i>ln</i> utility shall do nothing more with <i>source_file</i> and shall go on to any +remaining files.</p> +</li> +<li> +<p>If <i>source_file</i> is a symbolic link:</p> +<ol type="a"> +<li> +<p>If the <b>-P</b> option is in effect, actions shall be performed equivalent to the <a href= +"../functions/linkat.html"><i>linkat</i>()</a> function with <i>source_file</i> as the <i>path1</i> argument, the destination path +as the <i>path2</i> argument, AT_FDCWD as the <i>fd1</i> and <i>fd2</i> arguments, and zero as the <i>flag</i> argument.</p> +</li> +<li> +<p>If the <b>-L</b> option is in effect, actions shall be performed equivalent to the <a href= +"../functions/linkat.html"><i>linkat</i>()</a> function with <i>source_file</i> as the <i>path1</i> argument, the destination path +as the <i>path2</i> argument, AT_FDCWD as the <i>fd1</i> and <i>fd2</i> arguments, and AT_SYMLINK_FOLLOW as the <i>flag</i> +argument.</p> +</li> +</ol> +<p>The <i>ln</i> utility shall do nothing more with <i>source_file</i> and shall go on to any remaining files.</p> +</li> +<li> +<p>Actions shall be performed equivalent to the <a href="../functions/link.html"><i>link</i>()</a> function defined in the System +Interfaces volume of POSIX.1-2024 using <i>source_file</i> as the <i>path1</i> argument, and the destination path as the +<i>path2</i> argument.</p> +</li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_67_04" id="tag_20_67_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>ln</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-f</b></dt> +<dd>Force existing destination pathnames to be removed to allow the link.</dd> +<dt><b>-L</b></dt> +<dd>For each <i>source_file</i> operand that names a file of type symbolic link, create a hard link to the file referenced by the +symbolic link.</dd> +<dt><b>-P</b></dt> +<dd>For each <i>source_file</i> operand that names a file of type symbolic link, create a hard link to the symbolic link +itself.</dd> +<dt><b>-s</b></dt> +<dd>Create symbolic links instead of hard links. If the <b>-s</b> option is specified, the <b>-L</b> and <b>-P</b> options shall be +silently ignored.</dd> +</dl> +<p>Specifying more than one of the mutually-exclusive options <b>-L</b> and <b>-P</b> shall not be considered an error. The last +option specified shall determine the behavior of the utility (unless the <b>-s</b> option causes it to be ignored).</p> +<p>If the <b>-s</b> option is not specified and neither a <b>-L</b> nor a <b>-P</b> option is specified, it is +implementation-defined which of the <b>-L</b> and <b>-P</b> options is used as the default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_67_05" id="tag_20_67_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>source_file</i></dt> +<dd>A pathname of a file to be linked. If the <b>-s</b> option is specified, no restrictions on the type of file or on its +existence shall be made. If the <b>-s</b> option is not specified, whether a directory can be linked is +implementation-defined.</dd> +<dt><i>target_file</i></dt> +<dd>The pathname of the new directory entry to be created.</dd> +<dt><i>target_dir</i></dt> +<dd>A pathname of an existing directory in which the new directory entries are created.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_67_06" id="tag_20_67_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_67_07" id="tag_20_67_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_67_08" id="tag_20_67_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>ln</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_67_09" id="tag_20_67_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_67_10" id="tag_20_67_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_67_11" id="tag_20_67_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_67_12" id="tag_20_67_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_67_13" id="tag_20_67_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_67_14" id="tag_20_67_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_67_15" id="tag_20_67_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_67_16" id="tag_20_67_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_67_17" id="tag_20_67_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_67_18" id="tag_20_67_18"></a>RATIONALE</h4> +<blockquote> +<p>The CONSEQUENCES OF ERRORS section does not require <i>ln</i> <b>-f</b> <i>a b</i> to remove <i>b</i> if a subsequent link +operation would fail.</p> +<p>Some historic versions of <i>ln</i> (including the one specified by the SVID) unlink the destination file, if it exists, by +default. If the mode does not permit writing, these versions prompt for confirmation before attempting the unlink. In these +versions the <b>-f</b> option causes <i>ln</i> not to attempt to prompt for confirmation.</p> +<p>This allows <i>ln</i> to succeed in creating links when the target file already exists, even if the file itself is not writable +(although the directory must be). Early proposals specified this functionality.</p> +<p>This volume of POSIX.1-2024 does not allow the <i>ln</i> utility to unlink existing destination paths by default for the +following reasons:</p> +<ul> +<li> +<p>The <i>ln</i> utility has historically been used to provide locking for shell applications, a usage that is incompatible with +<i>ln</i> unlinking the destination path by default. There was no corresponding technical advantage to adding this +functionality.</p> +</li> +<li> +<p>This functionality gave <i>ln</i> the ability to destroy the link structure of files, which changes the historical behavior of +<i>ln</i>.</p> +</li> +<li> +<p>This functionality is easily replicated with a combination of <a href="../utilities/rm.html"><i>rm</i></a> and <i>ln</i>.</p> +</li> +<li> +<p>It is not historical practice in many systems; BSD and BSD-derived systems do not support this behavior. Unfortunately, +whichever behavior is selected can cause scripts written expecting the other behavior to fail.</p> +</li> +<li> +<p>It is preferable that <i>ln</i> perform in the same manner as the <a href="../functions/link.html"><i>link</i>()</a> function, +which does not permit the target to exist already.</p> +</li> +</ul> +<p>This volume of POSIX.1-2024 retains the <b>-f</b> option to provide support for shell scripts depending on the SVID semantics. +It seems likely that shell scripts would not be written to handle prompting by <i>ln</i> and would therefore have specified the +<b>-f</b> option.</p> +<p>The <b>-f</b> option is an undocumented feature of many historical versions of the <i>ln</i> utility, allowing linking to +directories. These versions require modification.</p> +<p>Early proposals of this volume of POSIX.1-2024 also required a <b>-i</b> option, which behaved like the <b>-i</b> options in +<a href="../utilities/cp.html"><i>cp</i></a> and <a href="../utilities/mv.html"><i>mv</i></a>, prompting for confirmation before +unlinking existing files. This was not historical practice for the <i>ln</i> utility and has been omitted.</p> +<p>The <b>-L</b> and <b>-P</b> options allow for implementing both common behaviors of the <i>ln</i> utility. Earlier versions of +this standard did not specify these options and required the behavior now described for the <b>-L</b> option. Many systems by +default or as an alternative provided a non-conforming <i>ln</i> utility with the behavior now described for the <b>-P</b> option. +Since applications could not rely on <i>ln</i> following links in practice, the <b>-L</b> and <b>-P</b> options were added to +specify the desired behavior for the application.</p> +<p>The <b>-L</b> and <b>-P</b> options are ignored when <b>-s</b> is specified in order to allow an alias to be created to alter +the default behavior when creating hard links (for example, <a href="../utilities/alias.html"><i>alias</i></a> <i>ln</i>='<a href= +"../utilities/ln.html"><i>ln</i></a> <b>-L</b>'). They serve no purpose when <b>-s</b> is specified, since <i>source_file</i> is +then just a string to be used as the contents of the created symbolic link and need not exist as a file.</p> +<p>The specification ensures that <i>ln</i> <b>a</b> <b>a</b> with or without the <b>-f</b> option will not unlink the file +<b>a</b>. Earlier versions of this standard were unclear in this case.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_67_19" id="tag_20_67_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a +<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require +implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_67_20" id="tag_20_67_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/chmod.html#tag_20_17"><i>chmod</i></a> , <a href="../utilities/find.html#"><i>find</i></a> , <a href= +"../utilities/pax.html#"><i>pax</i></a> , <a href="../utilities/readlink.html#tag_20_101"><i>readlink</i></a> , <a href= +"../utilities/realpath.html#tag_20_102"><i>realpath</i></a> , <a href="../utilities/rm.html#"><i>rm</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/link.html#tag_17_304"><i>link</i></a> , <a href= +"../functions/unlink.html#tag_17_649"><i>unlink</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_67_21" id="tag_20_67_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_67_22" id="tag_20_67_22"></a>Issue 6</h4> +<blockquote> +<p>The <i>ln</i> utility is updated to include symbolic link processing as defined in the IEEE P1003.2b draft standard.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_67_23" id="tag_20_67_23"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretations 1003.1-2001 #164, #168, and #169 are applied.</p> +<p>SD5-XCU-ERN-27 is applied, adding a new paragraph to the RATIONALE.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>The <b>-L</b> and <b>-P</b> options are added to make it implementation-defined whether the <i>ln</i> utility follows symbolic +links.</p> +<p>POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0096 [136] is applied.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0113 [930] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_67_24" id="tag_20_67_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to disallow the creation of filenames containing any bytes that +have the encoded value of a <newline> character.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1380 is applied, changing text using the term "link" in line with its updated definition.</p> +<p>Austin Group Defect 1457 is applied, adding <a href="../utilities/readlink.html"><i>readlink</i></a> and <a href= +"../utilities/realpath.html"><i>realpath</i></a> to the SEE ALSO section.</p> +<p>Austin Group Defect 1506 is applied, changing the EXIT STATUS section.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/link.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/locale.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/locale.html b/bdd/locale.html @@ -0,0 +1,388 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>locale</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/ln.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/localedef.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="locale" id="locale"></a> <a name="tag_20_68" id="tag_20_68"></a><!-- locale --> +<h4 class="mansect"><a name="tag_20_68_01" id="tag_20_68_01"></a>NAME</h4> +<blockquote>locale — get locale-specific information</blockquote> +<h4 class="mansect"><a name="tag_20_68_02" id="tag_20_68_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>locale</tt> <b>[</b><tt>-a|-m</tt><b>]</b> <tt><br> +<br> +locale</tt> <b>[</b><tt>-ck</tt><b>]</b> <i>name</i><tt>...<br></tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_68_03" id="tag_20_68_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>locale</i> utility shall write information about the current locale environment, or all public locales, to the standard +output. For the purposes of this section, a <i>public locale</i> is one provided by the implementation that is accessible to the +application.</p> +<p>When <i>locale</i> is invoked without any arguments, it shall summarize the current locale environment for each locale category +as determined by the settings of the environment variables defined in XBD <a href="../basedefs/V1_chap07.html#tag_07"><i>7. +Locale</i></a> .</p> +<p>When invoked with operands, it shall write values that have been assigned to the keywords in the locale categories, as +follows:</p> +<ul> +<li> +<p>Specifying a keyword name shall select the named keyword and the category containing that keyword.</p> +</li> +<li> +<p>Specifying a category name shall select the named category and all keywords in that category.</p> +</li> +</ul> +</blockquote> +<h4 class="mansect"><a name="tag_20_68_04" id="tag_20_68_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>locale</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-a</b></dt> +<dd>Write information about all available public locales. The available locales shall include <b>POSIX</b>, representing the POSIX +locale. The manner in which the implementation determines what other locales are available is implementation-defined.</dd> +<dt><b>-c</b></dt> +<dd>Write the names of selected locale categories; see the STDOUT section. The <b>-c</b> option increases readability when more +than one category is selected (for example, via more than one keyword name or via a category name). It is valid both with and +without the <b>-k</b> option.</dd> +<dt><b>-k</b></dt> +<dd>Write the names and values of selected keywords. The implementation may omit values for some keywords; see the OPERANDS +section.</dd> +<dt><b>-m</b></dt> +<dd>Write names of available charmaps; see XBD <a href="../basedefs/V1_chap06.html#tag_06_01"><i>6.1 Portable Character Set</i></a> +.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_68_05" id="tag_20_68_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>name</i></dt> +<dd>The name of a locale category as defined in XBD <a href="../basedefs/V1_chap07.html#tag_07"><i>7. Locale</i></a> , the name of +a keyword in a locale category, or the reserved name <b>charmap</b>. The named category or keyword shall be selected for output. If +a single <i>name</i> represents both a locale category name and a keyword name in the current locale, the results are unspecified. +Otherwise, both category and keyword names can be specified as <i>name</i> operands, in any sequence. It is implementation-defined +whether any keyword values are written for the categories <i>LC_CTYPE</i> and <i>LC_COLLATE .</i></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_68_06" id="tag_20_68_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_68_07" id="tag_20_68_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_68_08" id="tag_20_68_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>locale</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +<p>The application shall ensure that the <i>LANG ,</i> <i>LC_* ,</i> and <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> +<img src="../images/opt-start.gif" alt="[Option Start]" border="0"> <i>NLSPATH</i> <img src="../images/opt-end.gif" alt= +"[Option End]" border="0"> environment variables specify the current locale environment to be written out; they shall be used +if the <b>-a</b> option is not specified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_68_09" id="tag_20_68_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_68_10" id="tag_20_68_10"></a>STDOUT</h4> +<blockquote> +<p>The <i>LANG</i> variable shall be written first using the format:</p> +<pre> +<tt>"LANG=%s\n", <</tt><i>value</i><tt>> +</tt></pre> +<p>If <i>LANG</i> is not set or is an empty string, the value is the empty string.</p> +<p>If <i>locale</i> is invoked without any options or operands, the names and values of the <i>LC_*</i> environment variables +described in this volume of POSIX.1-2024 shall be written to the standard output, one variable per line, and each line using the +following format. Only those variables set in the environment and not overridden by <i>LC_ALL</i> shall be written using this +format:</p> +<pre> +<tt>"%s=%s\n", <</tt><i>variable_name</i><tt>>, <</tt><i>value</i><tt>> +</tt></pre> +<p>The names of those <i>LC_*</i> variables associated with locale categories defined in this volume of POSIX.1-2024 that are not +set in the environment or are overridden by <i>LC_ALL</i> shall be written in the following format:</p> +<pre> +<tt>"%s=\"%s\"\n", <</tt><i>variable_name</i><tt>>, <</tt><i>implied value</i><tt>> +</tt></pre> +<p>The <<i>implied value</i>> shall be the name of the locale that has been selected for that category by the +implementation, based on the values in <i>LANG</i> and <i>LC_ALL ,</i> as described in XBD <a href= +"../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> .</p> +<p>The <<i>value</i>> and <<i>implied value</i>> shown above shall be properly quoted for possible later reentry +to the shell. The <<i>value</i>> shall not be quoted using double-quotes (so that it can be distinguished by the user from +the <<i>implied value</i>> case, which always requires double-quotes).</p> +<p>The <i>LC_ALL</i> variable shall be written last, using the first format shown above. If it is not set, it shall be written +as:</p> +<pre> +<tt>"LC_ALL=\n" +</tt></pre> +<p>If any arguments are specified:</p> +<ol> +<li> +<p>If the <b>-a</b> option is specified, the names of all the public locales shall be written, each in the following format:</p> +<pre> +<tt>"%s\n", <</tt><i>locale name</i><tt>> +</tt></pre></li> +<li> +<p>If the <b>-c</b> option is specified, the names of all selected categories shall be written, each in the following format:</p> +<pre> +<tt>"%s\n", <</tt><i>category name</i><tt>> +</tt></pre> +<p>If keywords are also selected for writing (see following items), the category name output shall precede the keyword output for +that category.</p> +<p>If the <b>-c</b> option is not specified, the names of the categories shall not be written; only the keywords, as selected by +the <<i>name</i>> operand, shall be written.</p> +</li> +<li> +<p>If the <b>-k</b> option is specified, the names and values of selected keywords shall be written. If a value is non-numeric and +is not a compound keyword value, it shall be written in the following format:</p> +<pre> +<tt>"%s=\"%s\"\n", <</tt><i>keyword name</i><tt>>, <</tt><i>keyword value</i><tt>> +</tt></pre> +<p>If a value is a non-numeric compound keyword value, it shall either be written in the format:</p> +<pre> +<tt>"%s=\"%s\"\n", <</tt><i>keyword name</i><tt>>, <</tt><i>keyword value</i><tt>> +</tt></pre> +<p>where the <<i>keyword value</i>> is a single string of values separated by <semicolon> characters, or it shall be +written in the format:</p> +<pre> +<tt>"%s=%s\n", <</tt><i>keyword name</i><tt>>, <</tt><i>keyword value</i><tt>> +</tt></pre> +<p>where the <<i>keyword value</i>> is encoded as a set of strings, each enclosed in double-quotation-marks, separated by +<semicolon> characters.</p> +<p>If the keyword was <b>charmap</b>, the name of the charmap (if any) that was specified via the <a href= +"../utilities/localedef.html"><i>localedef</i></a> <b>-f</b> option when the locale was created shall be written, with the word +<b>charmap</b> as <<i>keyword name</i>>.</p> +<p>If a value is numeric, it shall be written in one of the following formats:</p> +<pre> +<tt>"%s=%d\n", <</tt><i>keyword name</i><tt>>, <</tt><i>keyword value</i><tt>> +<br> +"%s=%c%o\n", <</tt><i>keyword name</i><tt>>, <</tt><i>escape character</i><tt>>, <</tt><i>keyword value</i><tt>> +<br> +"%s=%cx%x\n", <</tt><i>keyword name</i><tt>>, <</tt><i>escape character</i><tt>>, <</tt><i>keyword value</i><tt>> +</tt></pre> +<p>where the <<i>escape character</i>> is that identified by the <b>escape_char</b> keyword in the current locale; see +XBD <a href="../basedefs/V1_chap07.html#tag_07_03"><i>7.3 Locale Definition</i></a> .</p> +<p>Compound keyword values (list entries) shall be separated in the output by <semicolon> characters. When included in +keyword values, the <semicolon>, <backslash>, double-quote, and any control character shall be preceded (escaped) with +the escape character.</p> +</li> +<li> +<p>If the <b>-k</b> option is not specified, selected keyword values shall be written, each in the following format:</p> +<pre> +<tt>"%s\n", <</tt><i>keyword value</i><tt>> +</tt></pre> +<p>If the keyword was <b>charmap</b>, the name of the charmap (if any) that was specified via the <a href= +"../utilities/localedef.html"><i>localedef</i></a> <b>-f</b> option when the locale was created shall be written.</p> +</li> +<li> +<p>If the <b>-m</b> option is specified, then a list of all available charmaps shall be written, each in the format:</p> +<pre> +<tt>"%s\n", <</tt><i>charmap</i><tt>> +</tt></pre> +<p>where <<i>charmap</i>> is in a format suitable for use as the option-argument to the <a href= +"../utilities/localedef.html"><i>localedef</i></a> <b>-f</b> option.</p> +</li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_68_11" id="tag_20_68_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_68_12" id="tag_20_68_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_68_13" id="tag_20_68_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_68_14" id="tag_20_68_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>All the requested information was found and output successfully.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_68_15" id="tag_20_68_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_68_16" id="tag_20_68_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>If the <i>LANG</i> environment variable is not set or set to an empty value, or one of the <i>LC_*</i> environment variables is +set to an unrecognized value, the actual locales assumed (if any) are implementation-defined as described in XBD <a href= +"../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> .</p> +<p>Implementations are not required to write out the actual values for keywords in the categories <i>LC_CTYPE</i> and <i>LC_COLLATE +;</i> however, they must write out the categories (allowing an application to determine, for example, which character classes are +available).</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_68_17" id="tag_20_68_17"></a>EXAMPLES</h4> +<blockquote> +<p>In the following examples, the assumption is that locale environment variables are set as follows:</p> +<pre> +<tt>LANG=locale_x +LC_COLLATE=locale_y +</tt></pre> +<p>The command <i>locale</i> would result in the following output:</p> +<pre> +<tt>LANG=locale_x +LC_CTYPE="locale_x" +LC_COLLATE=locale_y +LC_TIME="locale_x" +LC_NUMERIC="locale_x" +LC_MONETARY="locale_x" +LC_MESSAGES="locale_x" +LC_ALL= +</tt></pre> +<p>The order of presentation of the categories is not specified by this volume of POSIX.1-2024.</p> +<p>The command:</p> +<pre> +<tt>LC_ALL=POSIX locale -ck decimal_point +</tt></pre> +<p>would produce:</p> +<pre> +<tt>LC_NUMERIC +decimal_point="." +</tt></pre> +<p>The following command shows an application of <i>locale</i> to determine whether a user-supplied response is affirmative:</p> +<pre> +<tt>printf 'Prompt for response: ' +read response +if printf "%s\n" "$response" | grep -Eq -- "$(locale yesexpr)" +then + affirmative processing goes here +else + non-affirmative processing goes here +fi +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_68_18" id="tag_20_68_18"></a>RATIONALE</h4> +<blockquote> +<p>The output for categories <i>LC_CTYPE</i> and <i>LC_COLLATE</i> has been made implementation-defined because there is a +questionable value in having a shell script receive an entire array of characters. It is also difficult to return a logical +collation description, short of returning a complete <a href="../utilities/localedef.html"><i>localedef</i></a> source.</p> +<p>The <b>-m</b> option was included to allow applications to query for the existence of charmaps. The output is a list of the +charmaps (implementation-supplied and user-supplied, if any) on the system.</p> +<p>The <b>-c</b> option was included for readability when more than one category is selected (for example, via more than one +keyword name or via a category name). It is valid both with and without the <b>-k</b> option.</p> +<p>The <b>charmap</b> keyword, which returns the name of the charmap (if any) that was used when the current locale was created, +was included to allow applications needing the information to retrieve it.</p> +<p>According to XBD <a href="../basedefs/V1_chap06.html#tag_06_01"><i>6.1 Portable Character Set</i></a> , the standard requires +that all supported locales must have the same encoding for <period> and <slash>, because these two characters are used +within the locale-independent pathname resolution sequence. Therefore, it would be an error if <i>locale</i> <b>-a</b> listed both +ASCII and EBCDIC-based locales, since those two encodings do not share the same representation for either <period> or +<slash>. Any system that supports both environments would be expected to provide two POSIX locales, one in either codeset, +where only the locales appropriate to the current environment can be visible at a time. In an XSI-compliant implementation, the +<a href="../utilities/dd.html"><i>dd</i></a> utility is the only portable means for performing conversions between the two +character sets.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_68_19" id="tag_20_68_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_68_20" id="tag_20_68_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/localedef.html#"><i>localedef</i></a></p> +<p>XBD <a href="../basedefs/V1_chap06.html#tag_06_01"><i>6.1 Portable Character Set</i></a> , <a href= +"../basedefs/V1_chap07.html#tag_07"><i>7. Locale</i></a> , <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment +Variables</i></a> , <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_68_21" id="tag_20_68_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_68_22" id="tag_20_68_22"></a>Issue 5</h4> +<blockquote> +<p>The FUTURE DIRECTIONS section is added.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_68_23" id="tag_20_68_23"></a>Issue 6</h4> +<blockquote> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +<p>IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/30 is applied, correcting an editorial error in the STDOUT +section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_68_24" id="tag_20_68_24"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretations 1003.1-2001 #017, #021, and #088 are applied, clarifying the standard output for the <b>-k</b> +option when <i>LANG</i> is not set or is an empty string.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0097 [291] is applied.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0114 [941] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_68_25" id="tag_20_68_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1262 is applied, changing the EXAMPLES section.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/ln.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/localedef.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/localedef.html b/bdd/localedef.html @@ -0,0 +1,316 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>localedef</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/locale.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/logger.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="localedef" id="localedef"></a> <a name="tag_20_69" id="tag_20_69"></a><!-- localedef --> +<h4 class="mansect"><a name="tag_20_69_01" id="tag_20_69_01"></a>NAME</h4> +<blockquote>localedef — define locale environment</blockquote> +<h4 class="mansect"><a name="tag_20_69_02" id="tag_20_69_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>localedef</tt> <b>[</b><tt>-c</tt><b>] [</b><tt>-f</tt> <i>charmap</i><b>] [</b><tt>-i</tt> <i>sourcefile</i><b>] +[</b><tt>-u</tt> <i>code_set_name</i><b>]</b> <i>name</i></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_69_03" id="tag_20_69_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>localedef</i> utility shall convert source definitions for locale categories into a format usable by the functions and +utilities whose operational behavior is determined by the setting of the locale environment variables defined in XBD <a href= +"../basedefs/V1_chap07.html#tag_07"><i>7. Locale</i></a> . It is implementation-defined whether users have the capability to create +new locales, in addition to those supplied by the implementation. If the symbolic constant POSIX2_LOCALEDEF is defined, the system +supports the creation of new locales. <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" +alt="[Option Start]" border="0"> On XSI-conformant systems, the symbolic constant POSIX2_LOCALEDEF shall be defined. +<img src="../images/opt-end.gif" alt="[Option End]" border="0"></p> +<p>The utility shall read source definitions for one or more locale categories belonging to the same locale from the file named in +the <b>-i</b> option (if specified) or from standard input.</p> +<p>The <i>name</i> operand identifies the target locale. The utility shall support the creation of <i>public</i>, or generally +accessible locales, as well as <i>private</i>, or restricted-access locales. Implementations may restrict the capability to create +or modify public locales to users with appropriate privileges.</p> +<p>Each category source definition shall be identified by the corresponding environment variable name and terminated by an +<b>END</b> <i>category-name</i> statement. The following categories shall be supported. In addition, the input may contain source +for implementation-defined categories.</p> +<dl compact> +<dd></dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Defines character classification and case conversion.</dd> +<dt><i>LC_COLLATE</i></dt> +<dd><br> +Defines collation rules.</dd> +<dt><i>LC_MONETARY</i></dt> +<dd><br> +Defines the format and symbols used in formatting of monetary information.</dd> +<dt><i>LC_NUMERIC</i></dt> +<dd><br> +Defines the decimal delimiter, grouping, and grouping symbol for non-monetary numeric editing.</dd> +<dt><i>LC_TIME</i></dt> +<dd>Defines the format and content of date and time information.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Defines the format and values of affirmative and negative responses.</dd> +</dl> +<p>If the <i>LC_COLLATE</i> category defines a collation sequence that does not have a total ordering of all characters, +<i>localedef</i> shall write a warning message to standard error and, if the exit status would otherwise have been zero, shall exit +with status 1.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_69_04" id="tag_20_69_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>localedef</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-c</b></dt> +<dd>Create permanent output even if warning messages have been issued.</dd> +<dt><b>-f </b><i>charmap</i></dt> +<dd>Specify the pathname of a file containing a mapping of character symbols and collating element symbols to actual character +encodings. The format of the <i>charmap</i> is described in XBD <a href="../basedefs/V1_chap06.html#tag_06_04"><i>6.4 Character Set +Description File</i></a> . The application shall ensure that this option is specified if symbolic names (other than collating +symbols defined in a <b>collating-symbol</b> keyword) are used. If the <b>-f</b> option is not present, an implementation-defined +character mapping shall be used.</dd> +<dt><b>-i </b><i>inputfile</i></dt> +<dd>The pathname of a file containing the source definitions. If this option is not present, source definitions shall be read from +standard input. The format of the <i>inputfile</i> is described in XBD <a href="../basedefs/V1_chap07.html#tag_07_03"><i>7.3 Locale +Definition</i></a> .</dd> +<dt><b>-u </b><i>code_set_name</i></dt> +<dd><br> +Specify the name of a codeset used as the target mapping of character symbols and collating element symbols whose encoding values +are defined in terms of the ISO/IEC 10646-1:2020 standard position constant values.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_69_05" id="tag_20_69_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>name</i></dt> +<dd>Identifies the locale; see XBD <a href="../basedefs/V1_chap07.html#tag_07"><i>7. Locale</i></a> for a description of the use of +this name. If the name contains one or more <slash> characters, <i>name</i> shall be interpreted as a pathname where the +created locale definitions shall be stored. If <i>name</i> does not contain any <slash> characters, the interpretation of the +name is implementation-defined and the locale shall be public. The ability to create public locales in this way may be restricted +to users with appropriate privileges. (As a consequence of specifying one <i>name</i>, although several categories can be processed +in one execution, only categories belonging to the same locale can be processed.)</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_69_06" id="tag_20_69_06"></a>STDIN</h4> +<blockquote> +<p>Unless the <b>-i</b> option is specified, the standard input shall be a text file containing one or more locale category source +definitions, as described in XBD <a href="../basedefs/V1_chap07.html#tag_07_03"><i>7.3 Locale Definition</i></a> . When lines are +continued using the escape character mechanism, there is no limit to the length of the accumulated continued line.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_69_07" id="tag_20_69_07"></a>INPUT FILES</h4> +<blockquote> +<p>The character set mapping file specified as the <i>charmap</i> option-argument is described in XBD <a href= +"../basedefs/V1_chap06.html#tag_06_04"><i>6.4 Character Set Description File</i></a> . If a locale category source definition +contains a <b>copy</b> statement, as defined in XBD <a href="../basedefs/V1_chap07.html#tag_07"><i>7. Locale</i></a> , and the +<b>copy</b> statement names a valid, existing locale, then <i>localedef</i> shall behave as if the source definition had contained +a valid category source definition for the named locale.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_69_08" id="tag_20_69_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>localedef</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_COLLATE</i></dt> +<dd><br> +(This variable has no affect on <i>localedef</i>; the POSIX locale is used for this category.)</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). This variable has no affect on the processing of <i>localedef</i> +input data; the POSIX locale is used for this purpose, regardless of the value of this variable.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_69_09" id="tag_20_69_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_69_10" id="tag_20_69_10"></a>STDOUT</h4> +<blockquote> +<p>The utility shall report all categories successfully processed, in an unspecified format.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_69_11" id="tag_20_69_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_69_12" id="tag_20_69_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>The format of the created output is unspecified. If the <i>name</i> operand does not contain a <slash>, the existence of +an output file for the locale is unspecified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_69_13" id="tag_20_69_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>When the <b>-u</b> option is used, the <i>code_set_name</i> option-argument shall be interpreted as an implementation-defined +name of a codeset to which the ISO/IEC 10646-1:2020 standard position constant values shall be converted via an +implementation-defined method. Both the ISO/IEC 10646-1:2020 standard position constant values and other formats (decimal, +hexadecimal, or octal) shall be valid as encoding values within the <i>charmap</i> file. The codeset represented by the +implementation-defined name can be any codeset that is supported by the implementation.</p> +<p>When conflicts occur between the <i>charmap</i> specification of <<i>code_set_name</i>>, <<i>mb_cur_max</i>>, or +<<i>mb_cur_min</i>> and the implementation-defined interpretation of these respective items for the codeset represented by +the <b>-u</b> option-argument <i>code_set_name</i>, the result is unspecified.</p> +<p>When conflicts (including omissions) occur between the <i>charmap</i> encoding values specified for symbolic names of characters +of the portable character set and the implementation-defined assignment of character encoding values, the result is unspecified. If +the result is that <i>localedef</i> creates the specified locale, any attempted use of that locale by an application or utility +results in undefined behavior.</p> +<p>If a non-printable character in the <i>charmap</i> has a width specified that is not <b>-1</b>, the result is undefined.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_69_14" id="tag_20_69_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>No errors occurred and the locales were successfully created.</dd> +<dt> 1</dt> +<dd>Warnings occurred and the locales were successfully created.</dd> +<dt> 2</dt> +<dd>The locale specification exceeded implementation limits or the coded character set or sets used were not supported by the +implementation, and no locale was created.</dd> +<dt> 3</dt> +<dd>The capability to create new locales is not supported by the implementation.</dd> +<dt>>3</dt> +<dd>Warnings or errors occurred and no output was created.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_69_15" id="tag_20_69_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>If an error is detected, no permanent output shall be created.</p> +<p>If warnings occur, permanent output shall be created if the <b>-c</b> option was specified. The following conditions shall cause +warning messages to be issued:</p> +<ul> +<li> +<p>If a symbolic name not found in the <i>charmap</i> file is used for the descriptions of the <i>LC_CTYPE</i> or <i>LC_COLLATE</i> +categories (for other categories, this shall be an error condition).</p> +</li> +<li> +<p>If the number of operands to the <b>order</b> keyword exceeds the {COLL_WEIGHTS_MAX} limit.</p> +</li> +<li> +<p>If optional keywords not supported by the implementation are present in the source.</p> +</li> +</ul> +<p>Other implementation-defined conditions may also cause warnings.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_69_16" id="tag_20_69_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The <i>charmap</i> definition is optional, and is contained outside the locale definition. This allows both completely +self-defined source files, and generic sources (applicable to more than one codeset). To aid portability, all <i>charmap</i> +definitions must use the same symbolic names for the portable character set. As explained in XBD <a href= +"../basedefs/V1_chap06.html#tag_06_04"><i>6.4 Character Set Description File</i></a> , it is implementation-defined whether or not +users or applications can provide additional character set description files. Therefore, the <b>-f</b> option might be operable +only when an implementation-defined <i>charmap</i> is named.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_69_17" id="tag_20_69_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_69_18" id="tag_20_69_18"></a>RATIONALE</h4> +<blockquote> +<p>The output produced by the <i>localedef</i> utility is implementation-defined. The <i>name</i> operand is used to identify the +specific locale. (As a consequence, although several categories can be processed in one execution, only categories belonging to the +same locale can be processed.)</p> +<p>When conflicts (including omissions) occur between the <i>charmap</i> encoding values specified for symbolic names of characters +of the portable character set and the implementation-defined assignment of character encoding values, it is recommended that +<i>localedef</i> treats this as an error in order to prevent the undefined behavior that results if <i>localedef</i> creates the +specified locale and an application or utility attempts to use it.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_69_19" id="tag_20_69_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a +<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require +implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_69_20" id="tag_20_69_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/locale.html#"><i>locale</i></a></p> +<p>XBD <a href="../basedefs/V1_chap06.html#tag_06_04"><i>6.4 Character Set Description File</i></a> , <a href= +"../basedefs/V1_chap07.html#tag_07"><i>7. Locale</i></a> , <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment +Variables</i></a> , <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_69_21" id="tag_20_69_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_69_22" id="tag_20_69_22"></a>Issue 6</h4> +<blockquote> +<p>The <b>-u</b> option is added, as specified in the IEEE P1003.2b draft standard.</p> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +<p>IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/15 is applied, rewording text in the OPERANDS section describing +the ability to create public locales.</p> +<p>IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/16 is applied, making the text consistent with the descriptions +of <b>WIDTH</b> and <b>WIDTH_DEFAULT</b> in the Base Definitions volume of POSIX.1-2024.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_69_23" id="tag_20_69_23"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_69_24" id="tag_20_69_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to disallow the creation of filenames containing any bytes that +have the encoded value of a <newline> character.</p> +<p>Austin Group Defect 1070 is applied, requiring that <i>localedef</i> issues a warning if the <i>LC_COLLATE</i> category defines +a collation sequence that does not have a total ordering of all characters.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1609 is applied, clarifying the behavior when conflicts (including omissions) occur between the +<i>charmap</i> encoding values specified for symbolic names of characters of the portable character set and the +implementation-defined assignment of character encoding values.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/locale.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/logger.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/logger.html b/bdd/logger.html @@ -0,0 +1,266 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>logger</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/localedef.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/logname.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="logger" id="logger"></a> <a name="tag_20_70" id="tag_20_70"></a><!-- logger --> +<h4 class="mansect"><a name="tag_20_70_01" id="tag_20_70_01"></a>NAME</h4> +<blockquote>logger — log messages</blockquote> +<h4 class="mansect"><a name="tag_20_70_02" id="tag_20_70_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>logger</tt> <b>[</b><tt>-i</tt><b>] [</b><tt>-f</tt> <i>file</i><b>] [</b><tt>-p</tt> <i>priority</i><b>] [</b><tt>-t</tt> +<i>tag</i><b>] [</b><tt>string...</tt><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_70_03" id="tag_20_70_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>logger</i> utility shall send messages to an implementation-defined logging facility, which may log them in an +implementation-defined system log, write them to the system console, forward them to a list of users, or forward them to the +logging facility on another host over the network. Each logged message shall include a message header and a message body. The +message header shall contain at least a timestamp and a tag string.</p> +<p>If one or more <i>string</i> operands are specified, they shall be logged; otherwise, the message bodies to be logged shall be +read from standard input if no <b>-f</b> option is specified, or from the specified file if the <b>-f</b> option is present.</p> +<p>It is implementation-defined whether messages written in locales other than the POSIX locale are effective.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_70_04" id="tag_20_70_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>logger</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-f </b><i>file</i></dt> +<dd>Read the log message bodies from <i>file</i> instead of standard input.</dd> +<dt><b>-i</b></dt> +<dd>Log the process ID of the <i>logger</i> process with each message.</dd> +<dt><b>-p </b><i>priority</i></dt> +<dd>Log the message with priority set to <i>priority</i>. The priority is specified as a <i>facility</i>.<i>level</i> pair. The +following values for <i>facility</i> shall be supported: +<dl compact> +<dd></dd> +<dt>user</dt> +<dd>Messages generated by arbitrary processes.</dd> +<dt>local0</dt> +<dd>Reserved for local use.</dd> +<dt>local1</dt> +<dd>Reserved for local use.</dd> +<dt>local2</dt> +<dd>Reserved for local use.</dd> +<dt>local3</dt> +<dd>Reserved for local use.</dd> +<dt>local4</dt> +<dd>Reserved for local use.</dd> +<dt>local5</dt> +<dd>Reserved for local use.</dd> +<dt>local6</dt> +<dd>Reserved for local use.</dd> +<dt>local7</dt> +<dd>Reserved for local use.</dd> +</dl> +<p>The following values for <i>level</i> shall be supported:</p> +<dl compact> +<dd></dd> +<dt>emerg</dt> +<dd>A panic condition.</dd> +<dt>alert</dt> +<dd>A condition that should be corrected immediately, such as a corrupted system database.</dd> +<dt>crit</dt> +<dd>Critical conditions, such as hard device errors.</dd> +<dt>err</dt> +<dd>Errors.</dd> +<dt>warning</dt> +<dd>Warning messages.</dd> +<dt>notice</dt> +<dd>Conditions that are not error conditions, but that may require special handling.</dd> +<dt>info</dt> +<dd>Informational messages.</dd> +<dt>debug</dt> +<dd>Messages that contain information normally of use only when debugging a program.</dd> +</dl> +<p>If the <b>-p</b> option is not specified, the priority shall be <tt>user.notice</tt>.</p> +</dd> +<dt><b>-t </b><i>tag</i></dt> +<dd>Use the string <i>tag</i> as the tag string in the message header. The default tag is unspecified.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_70_05" id="tag_20_70_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>string</i></dt> +<dd>One of the string arguments whose contents are concatenated together, in the order specified, separated by single <space> +characters.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_70_06" id="tag_20_70_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be used if no <i>string</i> operands are specified and either the <b>-f</b> option is not specified or +the <b>-f</b> option is specified with a <i>file</i> option-argument of <tt>'-'</tt> and the implementation treats the <tt>'-'</tt> +as meaning standard input. Otherwise, the standard input shall not be used. See the INPUT FILES section.</p> +<p>Each non-empty line shall be logged as a separate message. It is unspecified whether an empty line is also logged as a separate +message.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_70_07" id="tag_20_70_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files shall be text files.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_70_08" id="tag_20_70_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>logger</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error. (This +means diagnostics from <i>logger</i> to the user or application, not diagnostic messages that the user is sending to the system +administrator.)</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_70_09" id="tag_20_70_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_70_10" id="tag_20_70_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_70_11" id="tag_20_70_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_70_12" id="tag_20_70_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>Unspecified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_70_13" id="tag_20_70_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_70_14" id="tag_20_70_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_70_15" id="tag_20_70_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_70_16" id="tag_20_70_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>This utility allows logging of information for later use by a system administrator or programmer in determining why +non-interactive utilities have failed. The locations of the saved messages, their format, and retention period are all unspecified. +There is no method for a conforming application to read messages, once written.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_70_17" id="tag_20_70_17"></a>EXAMPLES</h4> +<blockquote> +<p>A batch application, running non-interactively, tries to read a configuration file and fails; it may attempt to notify the +system administrator with:</p> +<pre> +<tt>logger myname: unable to read file foo. [timestamp] +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_70_18" id="tag_20_70_18"></a>RATIONALE</h4> +<blockquote> +<p>The standard developers believed strongly that some method of alerting administrators to errors was necessary. The obvious +example is a batch utility, running non-interactively, that is unable to read its configuration files or that is unable to create +or write its results file. However, the standard developers did not wish to define the format or delivery mechanisms as they have +historically been (and will probably continue to be) very system-specific, as well as involving functionality clearly outside the +scope of this volume of POSIX.1-2024.</p> +<p>The text with <i>LC_MESSAGES</i> about diagnostic messages means diagnostics from <i>logger</i> to the user or application, not +diagnostic messages that the user is sending to the system administrator.</p> +<p>Multiple <i>string</i> arguments are allowed, similar to <a href="../utilities/echo.html"><i>echo</i></a>, for ease-of-use.</p> +<p>Like the utilities <a href="../utilities/mailx.html"><i>mailx</i></a> and <a href="../utilities/lp.html"><i>lp</i></a>, +<i>logger</i> is admittedly difficult to test. This was not deemed sufficient justification to exclude these utilities from this +volume of POSIX.1-2024. It is also arguable that they are, in fact, testable, but that the tests themselves are not portable.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_70_19" id="tag_20_70_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_70_20" id="tag_20_70_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/lp.html#"><i>lp</i></a> , <a href="../utilities/mailx.html#"><i>mailx</i></a> , <a href= +"../utilities/write.html#tag_20_151"><i>write</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_70_21" id="tag_20_70_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_70_22" id="tag_20_70_22"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_70_23" id="tag_20_70_23"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 917 is applied, adding the <b>-f</b>, <b>-i</b>, <b>-p</b>, and <b>-t</b> options, and specifying the +behavior when <i>logger</i> is executed with no operands.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/localedef.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/logname.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/logname.html b/bdd/logname.html @@ -0,0 +1,173 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>logname</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/logger.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/lp.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="logname" id="logname"></a> <a name="tag_20_71" id="tag_20_71"></a><!-- logname --> +<h4 class="mansect"><a name="tag_20_71_01" id="tag_20_71_01"></a>NAME</h4> +<blockquote>logname — return the user's login name</blockquote> +<h4 class="mansect"><a name="tag_20_71_02" id="tag_20_71_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>logname</tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_71_03" id="tag_20_71_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>logname</i> utility shall write the user's login name to standard output. The login name shall be the string that would +be returned by the <a href="../functions/getlogin.html"><i>getlogin</i>()</a> function defined in the System Interfaces volume of +POSIX.1-2024. Under the conditions where the <a href="../functions/getlogin.html"><i>getlogin</i>()</a> function would fail, the +<i>logname</i> utility shall write a diagnostic message to standard error and exit with a non-zero exit status.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_71_04" id="tag_20_71_04"></a>OPTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_71_05" id="tag_20_71_05"></a>OPERANDS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_71_06" id="tag_20_71_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_71_07" id="tag_20_71_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_71_08" id="tag_20_71_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>logname</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_71_09" id="tag_20_71_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_71_10" id="tag_20_71_10"></a>STDOUT</h4> +<blockquote> +<p>The <i>logname</i> utility output shall be a single line consisting of the user's login name:</p> +<pre> +<tt>"%s\n", <</tt><i>login name</i><tt>> +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_71_11" id="tag_20_71_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_71_12" id="tag_20_71_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_71_13" id="tag_20_71_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_71_14" id="tag_20_71_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_71_15" id="tag_20_71_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_71_16" id="tag_20_71_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The <i>logname</i> utility explicitly ignores the <i>LOGNAME</i> environment variable because environment changes could produce +erroneous results.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_71_17" id="tag_20_71_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_71_18" id="tag_20_71_18"></a>RATIONALE</h4> +<blockquote> +<p>The <b>passwd</b> file is not listed as required because the implementation may have other means of mapping login names.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_71_19" id="tag_20_71_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_71_20" id="tag_20_71_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/id.html#"><i>id</i></a> , <a href="../utilities/who.html#"><i>who</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a></p> +<p>XSH <a href="../functions/getlogin.html#"><i>getlogin</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_71_21" id="tag_20_71_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_71_22" id="tag_20_71_22"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/logger.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/lp.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/lp.html b/bdd/lp.html @@ -0,0 +1,355 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>lp</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/logname.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/ls.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="lp" id="lp"></a> <a name="tag_20_72" id="tag_20_72"></a><!-- lp --> +<h4 class="mansect"><a name="tag_20_72_01" id="tag_20_72_01"></a>NAME</h4> +<blockquote>lp — send files to a printer</blockquote> +<h4 class="mansect"><a name="tag_20_72_02" id="tag_20_72_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>lp</tt> <b>[</b><tt>-c</tt><b>] [</b><tt>-d</tt> <i>dest</i><b>] [</b><tt>-n</tt> <i>copies</i><b>] [</b><tt>-msw</tt><b>] +[</b><tt>-o</tt> <i>option</i><b>]</b><tt>...</tt> <b>[</b><tt>-t</tt> <i>title</i><b>] [</b><i>file</i><tt>...</tt><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_72_03" id="tag_20_72_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>lp</i> utility shall copy the input files to an output destination in an unspecified manner. The default output +destination should be to a hardcopy device, such as a printer or microfilm recorder, that produces non-volatile, human-readable +documents. If such a device is not available to the application, or if the system provides no such device, the <i>lp</i> utility +shall exit with a non-zero exit status.</p> +<p>The actual writing to the output device may occur some time after the <i>lp</i> utility successfully exits. During the portion +of the writing that corresponds to each input file, the implementation shall guarantee exclusive access to the device.</p> +<p>The <i>lp</i> utility shall associate a unique <i>request ID</i> with each request.</p> +<p>Normally, a banner page is produced to separate and identify each print job. This page may be suppressed by +implementation-defined conditions, such as an operator command or one of the <b>-o</b> <i>option</i> values.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_72_04" id="tag_20_72_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>lp</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-c</b></dt> +<dd>Exit only after further access to any of the input files is no longer required. The application can then safely delete or +modify the files without affecting the output operation. Normally, files are not copied, but are linked whenever possible. If the +<b>-c</b> option is not given, then the user should be careful not to remove any of the files before the request has been printed +in its entirety. It should also be noted that in the absence of the <b>-c</b> option, any changes made to the named files after the +request is made but before it is printed may be reflected in the printed output. On some implementations, <b>-c</b> may be on by +default.</dd> +<dt><b>-d </b><i>dest</i></dt> +<dd>Specify a string that names the destination (<i>dest</i>). If <i>dest</i> is a printer, the request shall be printed only on +that specific printer. If <i>dest</i> is a class of printers, the request shall be printed on the first available printer that is a +member of the class. Under certain conditions (printer unavailability, file space limitation, and so on), requests for specific +destinations need not be accepted. Destination names vary between systems. +<p>If <b>-d</b> is not specified, and neither the <i>LPDEST</i> nor <i>PRINTER</i> environment variable is set, an unspecified +destination is used. The <b>-d</b> <i>dest</i> option shall take precedence over <i>LPDEST ,</i> which in turn shall take +precedence over <i>PRINTER .</i> Results are undefined when <i>dest</i> contains a value that is not a valid destination name.</p> +</dd> +<dt><b>-m</b></dt> +<dd>Send mail (see <a href="../utilities/mailx.html#"><i>mailx</i></a> ) after the files have been printed. By default, no mail is +sent upon normal completion of the print request.</dd> +<dt><b>-n </b><i>copies</i></dt> +<dd>Write <i>copies</i> number of copies of the files, where <i>copies</i> is a positive decimal integer. The methods for producing +multiple copies and for arranging the multiple copies when multiple <i>file</i> operands are used are unspecified, except that each +file shall be output as an integral whole, not interleaved with portions of other files.</dd> +<dt><b>-o </b><i>option</i></dt> +<dd>Specify printer-dependent or class-dependent <i>option</i>s. Several such <i>option</i>s may be collected by specifying the +<b>-o</b> option more than once.</dd> +<dt><b>-s</b></dt> +<dd>Suppress messages from <i>lp</i>.</dd> +<dt><b>-t </b><i>title</i></dt> +<dd>Write <i>title</i> on the banner page of the output.</dd> +<dt><b>-w</b></dt> +<dd>Write a message on the user's terminal after the files have been printed. If the user is not logged in, then mail shall be sent +instead.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_72_05" id="tag_20_72_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of a file to be output. If no <i>file</i> operands are specified, or if a <i>file</i> operand is <tt>'-'</tt>, the +standard input shall be used. If a <i>file</i> operand is used, but the <b>-c</b> option is not specified, the process performing +the writing to the output device may have user and group permissions that differ from that of the process invoking <i>lp</i>.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_72_06" id="tag_20_72_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be used only if no <i>file</i> operands are specified, or if a <i>file</i> operand is <tt>'-'</tt>. See +the INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_72_07" id="tag_20_72_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files shall be text files.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_72_08" id="tag_20_72_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>lp</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error and +informative messages written to standard output.</dd> +<dt><i>LC_TIME</i></dt> +<dd>Determine the format and contents of date and time strings displayed in the <i>lp</i> banner page, if any.</dd> +<dt><i>LPDEST</i></dt> +<dd>Determine the destination. If the <i>LPDEST</i> environment variable is not set, the <i>PRINTER</i> environment variable shall +be used. The <b>-d</b> <i>dest</i> option takes precedence over <i>LPDEST .</i> Results are undefined when <b>-d</b> is not +specified and <i>LPDEST</i> contains a value that is not a valid destination name.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>PRINTER</i></dt> +<dd>Determine the output device or destination. If the <i>LPDEST</i> and <i>PRINTER</i> environment variables are not set, an +unspecified output device is used. The <b>-d</b> <i>dest</i> option and the <i>LPDEST</i> environment variable shall take +precedence over <i>PRINTER .</i> Results are undefined when <b>-d</b> is not specified, <i>LPDEST</i> is unset, and <i>PRINTER</i> +contains a value that is not a valid device or destination name.</dd> +<dt><i>TZ</i></dt> +<dd>Determine the timezone used to calculate date and time strings displayed in the <i>lp</i> banner page, if any. If <i>TZ</i> is +unset or null, an unspecified default timezone shall be used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_72_09" id="tag_20_72_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_72_10" id="tag_20_72_10"></a>STDOUT</h4> +<blockquote> +<p>The <i>lp</i> utility shall write a <i>request ID</i> to the standard output, unless <b>-s</b> is specified. The format of the +message is unspecified. The request ID can be used on systems supporting the historical <i>cancel</i> and <i>lpstat</i> +utilities.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_72_11" id="tag_20_72_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_72_12" id="tag_20_72_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_72_13" id="tag_20_72_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_72_14" id="tag_20_72_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>All input files were processed successfully.</dd> +<dt>>0</dt> +<dd>No output device was available, or an error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_72_15" id="tag_20_72_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_72_16" id="tag_20_72_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The <a href="../utilities/pr.html"><i>pr</i></a> and <a href="../utilities/fold.html"><i>fold</i></a> utilities can be used to +achieve reasonable formatting for the implementation's default page size.</p> +<p>A conforming application can use one of the <i>file</i> operands only with the <b>-c</b> option or if the file is publicly +readable and guaranteed to be available at the time of printing. This is because POSIX.1-2024 gives the implementation the freedom +to queue up the request for printing at some later time by a different process that might not be able to access the file.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_72_17" id="tag_20_72_17"></a>EXAMPLES</h4> +<blockquote> +<ol> +<li> +<p>To print file <i>file</i>:</p> +<pre> +<tt>lp -c </tt><i>file</i><tt> +</tt></pre></li> +<li> +<p>To print multiple files with headers:</p> +<pre> +<tt>pr </tt><i>file1 file2</i><tt> | lp +</tt></pre></li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_72_18" id="tag_20_72_18"></a>RATIONALE</h4> +<blockquote> +<p>The <i>lp</i> utility was designed to be a basic version of a utility that is already available in many historical +implementations. The standard developers considered that it should be implementable simply as:</p> +<pre> +<tt>cat "$@" > /dev/lp +</tt></pre> +<p>after appropriate processing of options, if that is how the implementation chose to do it and if exclusive access could be +granted (so that two users did not write to the device simultaneously). Although in the future the standard developers may add +other options to this utility, it should always be able to execute with no options or operands and send the standard input to an +unspecified output device.</p> +<p>This volume of POSIX.1-2024 makes no representations concerning the format of the printed output, except that it must be +"human-readable" and "non-volatile". Thus, writing by default to a disk or tape drive or a display terminal would not qualify. +(Such destinations are not prohibited when <b>-d</b> <i>dest</i>, <i>LPDEST ,</i> or <i>PRINTER</i> are used, however.)</p> +<p>This volume of POSIX.1-2024 is worded such that a "print job" consisting of multiple input files, possibly in multiple copies, +is guaranteed to print so that any one file is not intermixed with another, but there is no statement that all the files or copies +have to print out together.</p> +<p>The <b>-c</b> option may imply a spooling operation, but this is not required. The utility can be implemented to wait until the +printer is ready and then wait until it is finished. Because of that, there is no attempt to define a queuing mechanism +(priorities, classes of output, and so on).</p> +<p>On some historical systems, the request ID reported on the STDOUT can be used to later cancel or find the status of a request +using utilities not defined in this volume of POSIX.1-2024.</p> +<p>Although the historical System V <i>lp</i> and BSD <i>lpr</i> utilities have provided similar functionality, they used different +names for the environment variable specifying the destination printer. Since the name of the utility here is <i>lp</i>, +<i>LPDEST</i> (used by the System V <i>lp</i> utility) was given precedence over <i>PRINTER</i> (used by the BSD <i>lpr</i> +utility). Since environments of users frequently contain one or the other environment variable, the <i>lp</i> utility is required +to recognize both. If this was not done, many applications would send output to unexpected output devices when users moved from +system to system.</p> +<p>Some have commented that <i>lp</i> has far too little functionality to make it worthwhile. Requests have proposed additional +options or operands or both that added functionality. The requests included:</p> +<ul> +<li> +<p>Wording <i>requiring</i> the output to be "hardcopy"</p> +</li> +<li> +<p>A requirement for multiple printers</p> +</li> +<li> +<p>Options for supporting various page-description languages</p> +</li> +</ul> +<p>Given that a compliant system is not required to even have a printer, placing further restrictions upon the behavior of the +printer is not useful. Since hardcopy format is so application-dependent, it is difficult, if not impossible, to select a +reasonable subset of functionality that should be required on all compliant systems.</p> +<p>The term <i>unspecified</i> is used in this section in lieu of <i>implementation-defined</i> as most known implementations would +not be able to make definitive statements in their conformance documents; the existence and usage of printers is very dependent on +how the system administrator configures each individual system.</p> +<p>Since the default destination, device type, queuing mechanisms, and acceptable forms of input are all unspecified, usage +guidelines for what a conforming application can do are as follows:</p> +<ul> +<li> +<p>Use the command in a pipeline, or with <b>-c</b>, so that there are no permission problems and the files can be safely deleted +or modified.</p> +</li> +<li> +<p>Limit output to text files of reasonable line lengths and printable characters and include no device-specific formatting +information, such as a page description language. The meaning of "reasonable" in this context can only be answered as a +quality-of-implementation issue, but it should be apparent from historical usage patterns in the industry and the locale. The +<a href="../utilities/pr.html"><i>pr</i></a> and <a href="../utilities/fold.html"><i>fold</i></a> utilities can be used to achieve +reasonable formatting for the default page size of the implementation.</p> +</li> +</ul> +<p>Alternatively, the application can arrange its installation in such a way that it requires the system administrator or operator +to provide the appropriate information on <i>lp</i> options and environment variable values.</p> +<p>At a minimum, having this utility in this volume of POSIX.1-2024 tells the industry that conforming applications require a means +to print output and provides at least a command name and <i>LPDEST</i> routing mechanism that can be used for discussions between +vendors, application developers, and users. The use of "should" in the DESCRIPTION of <i>lp</i> clearly shows the intent of the +standard developers, even if they cannot mandate that all systems (such as laptops) have printers.</p> +<p>This volume of POSIX.1-2024 does not specify what the ownership of the process performing the writing to the output device may +be. If <b>-c</b> is not used, it is unspecified whether the process performing the writing to the output device has permission to +read <i>file</i> if there are any restrictions in place on who may read <i>file</i> until after it is printed. Also, if <b>-c</b> +is not used, the results of deleting <i>file</i> before it is printed are unspecified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_72_19" id="tag_20_72_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_72_20" id="tag_20_72_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/mailx.html#"><i>mailx</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_72_21" id="tag_20_72_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_72_22" id="tag_20_72_22"></a>Issue 6</h4> +<blockquote> +<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p> +<ul> +<li> +<p>In the DESCRIPTION, the requirement to associate a unique request ID, and the normal generation of a banner page is added.</p> +</li> +<li> +<p>In the OPTIONS section:</p> +<ul> +<li> +<p>The <b>-d</b> <i>dest</i> description is expanded, but references to <i>lpstat</i> are removed.</p> +</li> +<li> +<p>The <b>-m</b>, <b>-o</b>, <b>-s</b>, <b>-t</b>, and <b>-w</b> options are added.</p> +</li> +</ul> +</li> +<li> +<p>In the ENVIRONMENT VARIABLES section, <i>LC_TIME</i> may now affect the execution.</p> +</li> +<li> +<p>The STDOUT section is added.</p> +</li> +</ul> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +<p>The <i>TZ</i> entry is added to the ENVIRONMENT VARIABLES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_72_23" id="tag_20_72_23"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_72_24" id="tag_20_72_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/logname.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/ls.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/ls.html b/bdd/ls.html @@ -0,0 +1,700 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>ls</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/lp.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/m4.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="ls" id="ls"></a> <a name="tag_20_73" id="tag_20_73"></a><!-- ls --> +<h4 class="mansect"><a name="tag_20_73_01" id="tag_20_73_01"></a>NAME</h4> +<blockquote>ls — list directory contents</blockquote> +<h4 class="mansect"><a name="tag_20_73_02" id="tag_20_73_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> ls</tt> <b>[</b><tt>-ikqrs</tt><b>] [</b><tt>-<img src= +"../images/opt-start.gif" border="0">g<img src="../images/opt-end.gif" border="0">ln<img src="../images/opt-start.gif" border= +"0">o<img src="../images/opt-end.gif" border="0"></tt><b>] [</b><tt>-A|-a</tt><b>] [</b><tt>-C|-m|-x|-1</tt><b>]</b> <tt>\<br> + </tt> <b>[</b><tt>-F|-p</tt><b>] [</b><tt>-H|-L</tt><b>] [</b><tt>-R|-d</tt><b>] +[</b><tt>-S|-f|-t</tt><b>] [</b><tt>-c|-u</tt><b>] [</b><i>file</i><tt>...</tt><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_73_03" id="tag_20_73_03"></a>DESCRIPTION</h4> +<blockquote> +<p>For each operand that names a file of a type other than directory or symbolic link to a directory, <i>ls</i> shall write the +name of the file as well as any requested, associated information. For each operand that names a file of type directory, <i>ls</i> +shall write the names of files contained within the directory as well as any requested, associated information. Filenames beginning +with a <period> (<tt>'.'</tt>) and any associated information shall not be written out unless explicitly referenced, the +<b>-A</b> or <b>-a</b> option is supplied, or an implementation-defined condition causes them to be written. If one or more of the +<b>-d</b>, <b>-F</b>, or <b>-l</b> options are specified, and neither the <b>-H</b> nor the <b>-L</b> option is specified, for each +operand that names a file of type symbolic link to a directory, <i>ls</i> shall write the name of the file as well as any +requested, associated information. If none of the <b>-d</b>, <b>-F</b>, or <b>-l</b> options are specified, or the <b>-H</b> or +<b>-L</b> options are specified, for each operand that names a file of type symbolic link to a directory, <i>ls</i> shall write the +names of files contained within the directory as well as any requested, associated information. In each case where the names of +files contained within a directory are written, if the directory contains any symbolic links then <i>ls</i> shall evaluate the file +information and file type to be those of the symbolic link itself, unless the <b>-L</b> option is specified.</p> +<p>If no operands are specified, <i>ls</i> shall behave as if a single operand of dot (<tt>'.'</tt>) had been specified. If more +than one operand is specified, <i>ls</i> shall write non-directory operands first; it shall sort directory and non-directory +operands separately according to the collating sequence in the current locale.</p> +<p>Whenever <i>ls</i> sorts filenames or pathnames according to the collating sequence in the current locale, if this collating +sequence does not have a total ordering of all characters (see XBD <a href="../basedefs/V1_chap07.html#tag_07_03_02"><i>7.3.2 +LC_COLLATE</i></a> ), then any filenames or pathnames that collate equally shall be further compared byte-by-byte using the +collating sequence for the POSIX locale.</p> +<p>The <i>ls</i> utility shall detect infinite loops; that is, entering a previously visited directory that is an ancestor of the +last file encountered. When it detects an infinite loop, <i>ls</i> shall write a diagnostic message to standard error and shall +either recover its position in the hierarchy or terminate.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_73_04" id="tag_20_73_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>ls</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-A</b></dt> +<dd>Write out all directory entries, including those whose names begin with a <period> (<tt>'.'</tt>) but excluding the +entries dot and dot-dot (if they exist).</dd> +<dt><b>-C</b></dt> +<dd>Write multi-text-column output with entries sorted down the columns, according to the collating sequence. The number of text +columns and the column separator characters are unspecified, but should be adapted to the nature of the output device. This option +disables long format output. <basefont size="2"> +<dl> +<dt><b>Note:</b></dt> +<dd>Since the output from this option may use separator characters that include characters that might appear in filenames (in +addition to the problems related to <newline>s in filenames), <b>-C</b> should not be used when filenames might be extracted +from the output by a script.</dd> +</dl> +<basefont size="3"></dd> +<dt><b>-F</b></dt> +<dd>Do not follow symbolic links named as operands unless the <b>-H</b> or <b>-L</b> options are specified. Write a <slash> +(<tt>'/'</tt>) immediately after each pathname that is a directory, an <asterisk> (<tt>'*'</tt>) after each that is +executable, a <vertical-line> (<tt>'|'</tt>) after each that is a FIFO, an <equals-sign> (<tt>'='</tt>) after each that +is a socket, and a <commercial-at> (<tt>'@'</tt>) after each that is a symbolic link. For other file types, other symbols may +be written.</dd> +<dt><b>-H</b></dt> +<dd>Evaluate the file information and file type for symbolic links specified on the command line to be those of the file referenced +by the link, and not the link itself; however, <i>ls</i> shall write the name of the link itself and not the file referenced by the +link.</dd> +<dt><b>-L</b></dt> +<dd>Evaluate the file information and file type for all symbolic links (whether named on the command line or encountered in a file +hierarchy) to be those of the file referenced by the link, and not the link itself; however, <i>ls</i> shall write the name of the +link itself and not the file referenced by the link. When <b>-L</b> is used with <b>-l</b>, write the contents of symbolic links in +the long format (see the STDOUT section).</dd> +<dt><b>-R</b></dt> +<dd>Recursively list subdirectories encountered. Subdirectories with filenames beginning with a <period> (<tt>'.'</tt>) shall +be recursively listed if and only if the subdirectory name was included in the filenames listed for the containing directory. When +a symbolic link to a directory is encountered, the directory shall not be recursively listed unless the <b>-L</b> option is +specified. The use of <b>-R</b> with <b>-d</b> or <b>-f</b> produces unspecified results.</dd> +<dt><b>-S</b></dt> +<dd>Sort with the primary key being file size (in decreasing order) and the secondary key being filename in the collating sequence +(in increasing order). For a symbolic link, the size used as the sort key is that of the symbolic link itself, unless <i>ls</i> is +evaluating its file information to be that of the file referenced by the link (see the <b>-H</b> and <b>-L</b> options).</dd> +<dt><b>-a</b></dt> +<dd>Write out all directory entries, including those whose names begin with a <period> (<tt>'.'</tt>).</dd> +<dt><b>-c</b></dt> +<dd>Use time of last modification of the file status information (see XBD <a href= +"../basedefs/sys_stat.h.html"><i><sys/stat.h></i></a> ) instead of last modification of the file itself for sorting +(<b>-t</b>) or writing (<b>-l</b>).</dd> +<dt><b>-d</b></dt> +<dd>Do not follow symbolic links named as operands unless the <b>-H</b> or <b>-L</b> options are specified. Do not treat +directories differently than other types of files. The use of <b>-d</b> with <b>-R</b> or <b>-f</b> produces unspecified +results.</dd> +<dt><b>-f</b></dt> +<dd>List the entries in directory operands in the order they appear in the directory. The behavior for non-directory operands is +unspecified. This option shall turn on <b>-a</b>. When <b>-f</b> is specified, any occurrences of the <b>-r</b>, <b>-S</b>, and +<b>-t</b> options shall be ignored and any occurrences of the <b>-A</b>, <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> +<img src="../images/opt-start.gif" alt="[Option Start]" border="0"> <b>-g</b>, <img src="../images/opt-end.gif" alt="[Option End]" +border="0"> <b>-l</b>, <b>-n</b>, <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" +alt="[Option Start]" border="0"> <b>-o</b>, <img src="../images/opt-end.gif" alt="[Option End]" border="0"> and <b>-s</b> options +may be ignored. The use of <b>-f</b> with <b>-R</b> or <b>-d</b> produces unspecified results.</dd> +<dt><b>-g</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Turn on the <b>-l</b> (ell) option, but disable writing the file's owner name or number. Disable the <b>-C</b>, <b>-m</b>, and +<b>-x</b> options. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-i</b></dt> +<dd>For each file, write the file's file serial number (see <a href="../functions/stat.html"><i>stat</i>()</a> in the System +Interfaces volume of POSIX.1-2024).</dd> +<dt><b>-k</b></dt> +<dd>Set the block size for the <b>-s</b> option and the per-directory block count written for the <b>-l</b>, <b>-n</b>, <b>-s</b>, +<sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +<b>-g</b>, and <b>-o</b> <img src="../images/opt-end.gif" alt="[Option End]" border="0"> options (see the STDOUT section) to 1024 +bytes.</dd> +<dt><b>-l</b></dt> +<dd>(The letter ell.) Do not follow symbolic links named as operands unless the <b>-H</b> or <b>-L</b> options are specified. Write +out in long format (see the STDOUT section). Disable the <b>-C</b>, <b>-m</b>, and <b>-x</b> options.</dd> +<dt><b>-m</b></dt> +<dd>Stream output format; list pathnames across the page, separated by a <comma> character followed by a <space> +character. Use a <newline> character as the list terminator and after the separator sequence when there is not room on a line +for the next list entry. This option disables long format output.</dd> +<dt><b>-n</b></dt> +<dd>Turn on the <b>-l</b> (ell) option, but when writing the file's owner or group, write the file's numeric UID or GID rather than +the user or group name, respectively. Disable the <b>-C</b>, <b>-m</b>, and <b>-x</b> options.</dd> +<dt><b>-o</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Turn on the <b>-l</b> (ell) option, but disable writing the file's group name or number. Disable the <b>-C</b>, <b>-m</b>, and +<b>-x</b> options. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-p</b></dt> +<dd>Write a <slash> (<tt>'/'</tt>) after each pathname if that file is a directory.</dd> +<dt><b>-q</b></dt> +<dd>Force each instance of non-printable filename characters (including <newline>, <tab>, and other control characters) +to be written as the <question-mark> (<tt>'?'</tt>) character. Implementations may provide this option by default if the +output is to a terminal device.</dd> +<dt><b>-r</b></dt> +<dd>Reverse the order of the sort to get reverse collating sequence, oldest first, or smallest file size first depending on the +other options given.</dd> +<dt><b>-s</b></dt> +<dd>Indicate the total number of file system blocks consumed by each file displayed. If the <b>-k</b> option is also specified, the +block size shall be 1024 bytes; otherwise, the block size is implementation-defined.</dd> +<dt><b>-t</b></dt> +<dd>Sort with the primary key being time modified (most recently modified first) and the secondary key being filename in the +collating sequence. For a symbolic link, the time used as the sort key is that of the symbolic link itself, unless <i>ls</i> is +evaluating its file information to be that of the file referenced by the link (see the <b>-H</b> and <b>-L</b> options).</dd> +<dt><b>-u</b></dt> +<dd>Use time of last access (see XBD <a href="../basedefs/sys_stat.h.html"><i><sys/stat.h></i></a> ) instead of last +modification of the file for sorting (<b>-t</b>) or writing (<b>-l</b>).</dd> +<dt><b>-x</b></dt> +<dd>The same as <b>-C</b>, except that the multi-text-column output is produced with entries sorted across, rather than down, the +columns. This option disables long format output.</dd> +<dt><b>-1</b></dt> +<dd>(The numeric digit one.) Force output to be one entry per line. This option does not disable long format output. (Long format +output is enabled by <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> <b>-g</b>, <img src="../images/opt-end.gif" alt="[Option End]" border="0"> <b>-l</b> (ell), <b>-n</b>, +and <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +<b>-o</b>; <img src="../images/opt-end.gif" alt="[Option End]" border="0"> and disabled by <b>-C</b>, <b>-m</b>, and +<b>-x</b>.)</dd> +</dl> +<p>If an option that enables long format output (<sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src= +"../images/opt-start.gif" alt="[Option Start]" border="0"> <b>-g</b>, <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"> <b>-l</b> (ell), <b>-n</b>, and <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" +alt="[Option Start]" border="0"> <b>-o</b><img src="../images/opt-end.gif" alt="[Option End]" border="0"> ) is given with an option +that disables long format output (<b>-C</b>, <b>-m</b>, and <b>-x</b>), this shall not be considered an error. The last of these +options specified shall determine whether long format output is written.</p> +<p>If <b>-R</b>, <b>-d</b>, or <b>-f</b> are specified, the results of specifying these mutually-exclusive options are specified by +the descriptions of these options above. If more than one of any of the other options shown in the SYNOPSIS section in +mutually-exclusive sets are given, this shall not be considered an error; the last option specified in each set shall determine the +output.</p> +<p>Note that if <b>-t</b> is specified, <b>-c</b> and <b>-u</b> are not only mutually-exclusive with each other, they are also +mutually-exclusive with <b>-S</b> when determining sort order. But even if <b>-S</b> is specified after all occurrences of +<b>-c</b>, <b>-t</b>, and <b>-u</b>, the last use of <b>-c</b> or <b>-u</b> determines the timestamp printed when producing long +format output.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_73_05" id="tag_20_73_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of a file to be written. If the file specified is not found, a diagnostic message shall be output on standard +error.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_73_06" id="tag_20_73_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_73_07" id="tag_20_73_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.<br></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_73_08" id="tag_20_73_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>ls</i>:</p> +<dl compact> +<dd></dd> +<dt><i>COLUMNS</i></dt> +<dd>Override the system-selected horizontal display line size, used to determine the column position width for writing multiple +text-column output. See XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> for valid values and +results when it is unset or null. The <i>ls</i> utility shall use this value to calculate how many pathname text columns to write +(see <b>-C</b>). The column width chosen to write the names of files in any given directory shall be constant. Filenames shall not +be truncated to fit into the multiple text-column output.</dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_COLLATE</i></dt> +<dd><br> +Determine the locale for character collation information in determining the pathname collation sequence.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments) and which characters are defined as printable (character class <b>print</b>).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>LC_TIME</i></dt> +<dd>Determine the format and contents for date and time strings written by <i>ls</i>.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>TZ</i></dt> +<dd>Determine the timezone for date and time strings written by <i>ls</i>. If <i>TZ</i> is unset or null, an unspecified default +timezone shall be used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_73_09" id="tag_20_73_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_73_10" id="tag_20_73_10"></a>STDOUT</h4> +<blockquote> +<p>The default format shall be to list one entry per line to standard output; the exceptions are to terminals or when one of the +<b>-C</b>, <b>-m</b>, or <b>-x</b> options is specified. If the output is to a terminal, the format is implementation-defined.</p> +<p>In the formats specified below, except where specified otherwise the <<i>pathname</i>> field shall consist of the file's +pathname and, if the <b>-F</b> or <b>-p</b> option is specified, any indicator character written after the pathname as described +for those options.</p> +<p>When <b>-m</b> is specified, the format used for the last element of the list shall be:</p> +<pre> +<tt>"%s\n", <</tt><i>pathname</i><tt>> +</tt></pre> +<p>The format used for each other element of the list shall be:</p> +<pre> +<tt>"%s,%s", <</tt><i>pathname</i><tt>>, <</tt><i>separator</i><tt>> +</tt></pre> +<p>where, if there is not room for the next element of the list to fit within the current line length, <<i>separator</i>> is +a string containing an optional <space> character and a mandatory <newline> character; otherwise it is a single +<space> character.</p> +<p>If the <b>-i</b> option is specified, the file's file serial number (see XBD <a href= +"../basedefs/sys_stat.h.html"><i><sys/stat.h></i></a> ) shall be written in the following format before any other output for +the corresponding entry:</p> +<pre> +<tt>%u ", <</tt><i>file serial number</i><tt>> +</tt></pre> +<p>If the <b>-l</b> option is specified, the following information shall be written for files other than character special and +block special files:</p> +<pre> +<tt>"%s %u %s %s %u %s %s\n", <</tt><i>file mode</i><tt>>, <</tt><i>number of links</i><tt>>, + <</tt><i>owner name</i><tt>>, <</tt><i>group name</i><tt>>, <</tt><i>size</i><tt>>, <</tt><i>date and time</i><tt>>, + <</tt><i>pathname</i><tt>> +</tt></pre> +<p>If the <b>-l</b> option is specified, the following information shall be written for character special and block special +files:</p> +<pre> +<tt>"%s %u %s %s %s %s %s\n", <</tt><i>file mode</i><tt>>, <</tt><i>number of links</i><tt>>, + <</tt><i>owner name</i><tt>>, <</tt><i>group name</i><tt>>, <</tt><i>device info</i><tt>>, <</tt><i>date and time</i><tt>>, + <</tt><i>pathname</i><tt>> +</tt></pre> +<p>In both cases if the file is a symbolic link and the <b>-L</b> option is also specified, this information shall be for the file +resolved from the symbolic link, except that the <<i>pathname</i>> field shall contain the pathname of the symbolic link +itself. If the file is a symbolic link and the <b>-L</b> option is not specified, this information shall be about the link itself +and the <<i>pathname</i>> field shall be one of the following forms:</p> +<ul> +<li> +<p><tt>"%s%sΔ->Δ%s", <</tt><i>pathname of link</i><tt>>, <</tt><i>link type indicator</i><tt>>, <</tt><i>contents +of link</i><tt>></tt></p> +</li> +<li> +<p><tt>"%sΔ->Δ%s%s", <</tt><i>pathname of link</i><tt>>, <</tt><i>contents of link</i><tt>>, <</tt><i>file type +indicator</i><tt>></tt></p> +</li> +<li> +<p><tt>"%s%sΔ->Δ%s%s", <</tt><i>pathname of link</i><tt>>, <</tt><i>link type indicator</i><tt>>, +<</tt><i>contents of link</i><tt>>, <</tt><i>file type indicator</i><tt>></tt></p> +</li> +</ul> +<p>where <<i>link type indicator</i>> is a <commercial-at> (<tt>'@'</tt>) if the <b>-F</b> option is specified, or an +empty string otherwise and <<i>file type indicator</i>> is the required indicator character, if any, for the file resolved +from the symbolic link if the <b>-F</b> or <b>-p</b> option is specified, or an empty string otherwise. If pathname resolution +fails when following the symbolic link, this shall not be treated as an error and the <<i>file type indicator</i>> field +shall be an empty string.</p> +<p>The <b>-n</b>, <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> <b>-g</b>, and <b>-o</b> <img src="../images/opt-end.gif" alt="[Option End]" border="0"> options use +the same format as <b>-l</b>, but with omitted items and their associated <blank> characters. See the OPTIONS section.</p> +<p>In both the preceding <b>-l</b> forms, if <<i>owner name</i>> or <<i>group name</i>> cannot be determined, or if +<b>-n</b> is given, they shall be replaced with their associated numeric values using the format <tt>%u</tt>.</p> +<p>The <<i>size</i>> field shall contain the value that would be returned for the file in the <i>st_size</i> field of +<b>struct stat</b> (see XBD <a href="../basedefs/sys_stat.h.html"><i><sys/stat.h></i></a> ). Note that for some file types +this value is unspecified.</p> +<p>The <<i>device info</i>> field shall contain implementation-defined information associated with the device in +question.</p> +<p>The <<i>date and time</i>> field shall contain the appropriate date and timestamp of when the file was last +modified. In the POSIX locale, the field shall be the equivalent of the output of the following <a href= +"../utilities/date.html"><i>date</i></a> command:</p> +<pre> +<tt>date "+%b %e %H:%M" +</tt></pre> +<p>if the file has been modified in the last six months, or:</p> +<pre> +<tt>date "+%b %e %Y" +</tt></pre> +<p>(where two <space> characters are used between <tt>%e</tt> and <tt>%Y</tt>) if the file has not been modified in the last +six months or if the modification date is in the future, except that, in both cases, the final <newline> produced by <a href= +"../utilities/date.html"><i>date</i></a> shall not be included and the output shall be as if the <a href= +"../utilities/date.html"><i>date</i></a> command were executed at the time of the last modification date of the file rather than +the current time. When the <i>LC_TIME</i> locale category is not set to the POSIX locale, a different format and order of +presentation of this field may be used.</p> +<p>If the pathname was specified as a <i>file</i> operand, it shall be written as specified.</p> +<p>The file mode written under the <b>-l</b>, <b>-n</b>, <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src= +"../images/opt-start.gif" alt="[Option Start]" border="0"> <b>-g</b>, and <b>-o</b> <img src="../images/opt-end.gif" alt= +"[Option End]" border="0"> options shall consist of the following format:</p> +<pre> +<tt>"%c%s%s%s%s", <</tt><i>entry type</i><tt>>, <</tt><i>owner permissions</i><tt>>, + <</tt><i>group permissions</i><tt>>, <</tt><i>other permissions</i><tt>>, + <</tt><i>optional alternate access method flag</i><tt>> +</tt></pre> +<p>The <<i>optional alternate access method flag</i>> shall be the empty string if there is no alternate +or additional access control method associated with the file; otherwise, it shall be a string containing a single printable +character that is not a <blank>.</p> +<p>The <<i>entry type</i>> character shall describe the type of file, as follows:</p> +<dl compact> +<dd></dd> +<dt><tt>d</tt></dt> +<dd>Directory.</dd> +<dt><tt>b</tt></dt> +<dd>Block special file.</dd> +<dt><tt>c</tt></dt> +<dd>Character special file.</dd> +<dt><tt>l</tt> (ell)</dt> +<dd>Symbolic link.</dd> +<dt><tt>p</tt></dt> +<dd>FIFO.</dd> +<dt><tt>s</tt></dt> +<dd>Socket.</dd> +<dt><tt>-</tt></dt> +<dd>Regular file.</dd> +</dl> +<p>Implementations may add other characters to this list to represent other implementation-defined file types.</p> +<p>The next three fields shall be three characters each:</p> +<dl compact> +<dd></dd> +<dt><<i>owner permissions</i>></dt> +<dd><br> +Permissions for the file owner class (see XBD <a href="../basedefs/V1_chap04.html#tag_04_07"><i>4.7 File Access Permissions</i></a> +).</dd> +<dt><<i>group permissions</i>></dt> +<dd><br> +Permissions for the file group class.</dd> +<dt><<i>other permissions</i>></dt> +<dd><br> +Permissions for the file other class.</dd> +</dl> +<p>Each field shall have three character positions:</p> +<ol> +<li> +<p>If <tt>'r'</tt>, the file is readable; if <tt>'-'</tt>, the file is not readable.</p> +</li> +<li> +<p>If <tt>'w'</tt>, the file is writable; if <tt>'-'</tt>, the file is not writable.</p> +</li> +<li> +<p>The first of the following that applies:</p> +<dl compact> +<dd></dd> +<dt><tt>S</tt></dt> +<dd>If in <<i>owner permissions</i>>, the file is not executable and set-user-ID mode is set. If in +<<i>group permissions</i>>, the file is not executable and set-group-ID mode is set.</dd> +<dt><tt>s</tt></dt> +<dd>If in <<i>owner permissions</i>>, the file is executable and set-user-ID mode is set. If in +<<i>group permissions</i>>, the file is executable and set-group-ID mode is set.</dd> +<dt><tt>T</tt></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +If in <<i>other permissions</i>> and the file is a directory, search permission is not granted to others, and the +restricted deletion flag is set. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><tt>t</tt></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +If in <<i>other permissions</i>> and the file is a directory, search permission is granted to others, and the restricted +deletion flag is set. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><tt>x</tt></dt> +<dd>The file is executable or the directory is searchable.</dd> +<dt><tt>-</tt></dt> +<dd>None of the attributes of <tt>'S'</tt>, <tt>'s'</tt>, <tt>'T'</tt>, <tt>'t'</tt>, or <tt>'x'</tt> applies.</dd> +</dl> +<p>Implementations may add other characters to this list for the third character position. Such additions shall, however, be +written in lowercase if the file is executable or searchable, and in uppercase if it is not.</p> +</li> +</ol> +<p>If any of the <b>-l</b>, <b>-n</b>, <b>-s</b>, <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src= +"../images/opt-start.gif" alt="[Option Start]" border="0"> <b>-g</b>, or <b>-o</b> <img src="../images/opt-end.gif" alt= +"[Option End]" border="0"> options is specified, each list of files within a directory shall be preceded by a status line +indicating the number of file system blocks occupied by the listed files for that directory in 512-byte units if the <b>-k</b> +option is not specified, or 1024-byte units if the <b>-k</b> option is specified, rounded up to the next integral number of units, +if necessary. In the POSIX locale, the format shall be:</p> +<pre> +<tt>"total %u\n", <</tt><i>number of units in the directory</i><tt>> +</tt></pre> +<p>If more than one directory, or a combination of non-directory files and directories are written, either as a result of +specifying multiple operands, or the <b>-R</b> option, each list of files within a directory shall be preceded by:</p> +<pre> +<tt>"\n%s:\n", <</tt><i>directory name</i><tt>> +</tt></pre> +<p>The above string may be omitted for the directory named by the operand if only one operand is present. It may also be omitted +for dot (<tt>'.'</tt>) if no operands are present. If this string is the first thing to be written, the first <newline> shall +not be written. This output shall precede the number of units in the directory.</p> +<p>If the <b>-s</b> option is given, each file shall be written with the number of blocks used by the file. Along with <b>-C</b>, +<b>-1</b>, <b>-m</b>, or <b>-x</b>, the number and a <space> shall precede the filename; with <b>-l</b>, <b>-n</b>, +<sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +<b>-g</b>, or <b>-o</b>, <img src="../images/opt-end.gif" alt="[Option End]" border="0"> they shall precede each line describing a +file.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_73_11" id="tag_20_73_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_73_12" id="tag_20_73_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_73_13" id="tag_20_73_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_73_14" id="tag_20_73_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_73_15" id="tag_20_73_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_73_16" id="tag_20_73_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>It is difficult for an application to use every part of the file modes field of <i>ls</i> <b>-l</b> in a portable manner. +Certain file types and executable bits are not guaranteed to be exactly as shown, as implementations may have extensions. +Applications can use this field to pass directly to a user printout or prompt, but actions based on its contents should generally +be deferred, instead, to the <a href="../utilities/test.html"><i>test</i></a> utility.</p> +<p>The output of <i>ls</i> (with the <b>-l</b> and related options) contains information that logically could be used by utilities +such as <a href="../utilities/chmod.html"><i>chmod</i></a> and <a href="../utilities/touch.html"><i>touch</i></a> to restore files +to a known state. However, this information is presented in a format that cannot be used directly by those utilities or be easily +translated into a format that can be used. A character has been added to the end of the permissions string so that applications at +least have an indication that they may be working in an area they do not understand instead of assuming that they can translate the +permissions string into something that can be used. Future versions or related documents may define one or more specific characters +to be used based on different standard additional or alternative access control mechanisms.</p> +<p>As with many of the utilities that deal with filenames, the output of <i>ls</i> for multiple files or in one of the long listing +formats must be used carefully on systems where filenames can contain embedded white space. Systems and system administrators +should institute policies and user training to limit the use of such filenames.</p> +<p>The number of disk blocks occupied by the file that it reports varies depending on underlying file system type, block size units +reported, and the method of calculating the number of blocks. On some file system types, the number is the actual number of blocks +occupied by the file (counting indirect blocks and ignoring holes in the file); on others it is calculated based on the file size +(usually making an allowance for indirect blocks, but ignoring holes).</p> +<p>The <tt>total</tt> number provided when using <i>ls</i> <b>-l</b> does not necessarily correspond to the space that would be +reclaimed if all the listed files were removed, because of hard links (and symbolic links if <b>-L</b> is present). The space for +each listed file is counted in the total regardless of any relationship between the files.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_73_17" id="tag_20_73_17"></a>EXAMPLES</h4> +<blockquote> +<p>An example of a small directory tree being fully listed with <i>ls</i> <b>-laRF a</b> in the POSIX locale:</p> +<pre> +<tt>a: +total 11 +drwxr-xr-x 3 fox prog 64 Jul 4 12:07 ./ +drwxrwxrwx 4 fox prog 3264 Jul 4 12:09 ../ +drwxr-xr-x 2 fox prog 48 Jul 4 12:07 b/ +-rwxr--r-- 1 fox prog 572 Jul 4 12:07 foo* +<br> +a/b: +total 4 +drwxr-xr-x 2 fox prog 48 Jul 4 12:07 ./ +drwxr-xr-x 3 fox prog 64 Jul 4 12:07 ../ +-rw-r--r-- 1 fox prog 700 Jul 4 12:07 bar +</tt></pre> +<p>where the <tt>"a:"</tt> line may be omitted by some implementations.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_73_18" id="tag_20_73_18"></a>RATIONALE</h4> +<blockquote> +<p>Some historical implementations of the <i>ls</i> utility show all entries in a directory except dot and dot-dot when a superuser +invokes <i>ls</i> without specifying the <b>-a</b> option. When "normal" users invoke <i>ls</i> without specifying <b>-a</b>, +they should not see information about any files with names beginning with a <period> unless they were named as <i>file</i> +operands.</p> +<p>Implementations are expected to traverse arbitrary depths when processing the <b>-R</b> option. The only limitation on depth +should be based on running out of physical storage for keeping track of untraversed directories.</p> +<p>The <b>-1</b> (one) option was historically found in BSD and BSD-derived implementations only. It is required in this volume of +POSIX.1-2024 so that conforming applications might ensure that output is one entry per line, even if the output is to a +terminal.</p> +<p>The <b>-S</b> option was added in Issue 7, but had been provided by several implementations for many years. The description +given in the standard documents historic practice, but does not match much of the documentation that described its behavior. +Historical documentation typically described it as something like:</p> +<dl compact> +<dd></dd> +<dt><b>-S</b></dt> +<dd>Sort by size (largest size first) instead of by name. Special character devices (listed last) are sorted by name.</dd> +</dl> +<p>even though the file type was never considered when sorting the output. Character special files do typically sort close to the +end of the list because their file size on most implementations is zero. But they are sorted alphabetically with any other files +that happen to have the same file size (zero), not sorted separately and added to the end.</p> +<p>This volume of POSIX.1-2024 is frequently silent about what happens when mutually-exclusive options are specified. Except for +<b>-R</b>, <b>-d</b>, and <b>-f</b>, the <i>ls</i> utility is required to accept multiple options from each mutually-exclusive +option set without treating them as errors and to use the behavior specified by the last option given in each mutually-exclusive +set. Since <i>ls</i> is one of the most aliased commands, it is important that the implementation perform intuitively. For example, +if the alias were:</p> +<pre> +<tt>alias ls="ls -C" +</tt></pre> +<p>and the user typed <i>ls</i> <b>-1</b> (one), single-text-column output should result, not an error.</p> +<p>The <b>-g</b>, <b>-l</b> (ell), <b>-n</b>, and <b>-o</b> options are not mutually-exclusive options. They all enable long format +output. They work together to determine whether the file's owner is written (no if <b>-g</b> is present), file's group is written +(no if <b>-o</b> is present), and if the file's group or owner is written whether it is written as the name (default) or a string +representation of the UID or GID number (if <b>-n</b> is present). The <b>-C</b>, <b>-m</b>, <b>-x</b>, and <b>-1</b> (one) are +mutually-exclusive options and the first three of these disable long format output. The <b>-1</b> (one) option does not directly +change whether or not long format output is enabled, but by overriding <b>-C</b>, <b>-m</b>, and <b>-x</b>, it can re-enable long +format output that had been disabled by one of these options.</p> +<p>Earlier versions of this standard did not describe the BSD <b>-A</b> option (like <b>-a</b>, but dot and dot-dot are not written +out). It has been added due to widespread implementation.</p> +<p>Implementations may make <b>-q</b> the default for terminals to prevent trojan horse attacks on terminals with special escape +sequences. This is not required because:</p> +<ul> +<li> +<p>Some control characters may be useful on some terminals; for example, a system might write them as <tt>"\001"</tt> or +<tt>"^A"</tt>.</p> +</li> +<li> +<p>Special behavior for terminals is not relevant to applications portability.</p> +</li> +</ul> +<p>An early proposal specified that the <<i>optional alternate access method flag</i>> had to be +<tt>'+'</tt> if there was an alternate access method used on the file or <space> if there was not. This was changed to be +<space> if there is not and a single printable character if there is. This was done for three reasons:</p> +<ol> +<li> +<p>There are historical implementations using characters other than <tt>'+'</tt>.</p> +</li> +<li> +<p>There are implementations that vary this character used in that position to distinguish between various alternate access methods +in use.</p> +</li> +<li> +<p>The standard developers did not want to preclude future specifications that might need a way to specify more than one alternate +access method.</p> +</li> +</ol> +<p>Nonetheless, implementations providing a single alternate access method are encouraged to use <tt>'+'</tt>.</p> +<p>Earlier versions of this standard did not have the <b>-k</b> option, which meant that the <b>-s</b> option could not be used +portably as its block size was implementation-defined, and the units used to specify the number of blocks occupied by files in a +directory in an <i>ls</i> <b>-l</b> listing were fixed as 512-byte units. The <b>-k</b> option has been added to provide a way for +the <b>-s</b> option to be used portably, and for consistency it also changes the aforementioned units from 512-byte to +1024-byte.</p> +<p>The <<i>date and time</i>> field in the <b>-l</b> format is specified only for the POSIX locale. As noted, the +format can be different in other locales. No mechanism for defining this is present in this volume of POSIX.1-2024, as the +appropriate vehicle is a messaging system; that is, the format should be specified as a "message".</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_73_19" id="tag_20_73_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +<p>Allowing <b>-f</b> to ignore the <b>-A</b>, <b>-g</b>, <b>-l</b>, <b>-n</b>, <b>-o</b>, and <b>-s</b> options may be removed in +a future version.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_73_20" id="tag_20_73_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/chmod.html#tag_20_17"><i>chmod</i></a> , <a href="../utilities/find.html#"><i>find</i></a> , <a href= +"../utilities/readlink.html#tag_20_101"><i>readlink</i></a></p> +<p>XBD <a href="../basedefs/V1_chap07.html#tag_07_03_02"><i>7.3.2 LC_COLLATE</i></a> , <a href= +"../basedefs/V1_chap04.html#tag_04_07"><i>4.7 File Access Permissions</i></a> , <a href="../basedefs/V1_chap08.html#tag_08"><i>8. +Environment Variables</i></a> , <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a> , <a href= +"../basedefs/sys_stat.h.html"><i><sys/stat.h></i></a></p> +<p>XSH <a href="../functions/fstatat.html#"><i>fstatat</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_73_21" id="tag_20_73_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_73_22" id="tag_20_73_22"></a>Issue 5</h4> +<blockquote> +<p>A second FUTURE DIRECTION is added.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_73_23" id="tag_20_73_23"></a>Issue 6</h4> +<blockquote> +<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p> +<ul> +<li> +<p>In the <b>-F</b> option, other symbols are allowed for other file types.</p> +</li> +</ul> +<p>Treatment of symbolic links is added, as defined in the IEEE P1003.2b draft standard.</p> +<p>The Open Group Base Resolution bwg2001-010 is applied, adding the <tt>T</tt> and <tt>t</tt> fields as part of the XSI +option.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_73_24" id="tag_20_73_24"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #101 is applied, clarifying the optional alternate access method flag in the STDOUT +section.</p> +<p>Austin Group Interpretation 1003.1-2001 #128 is applied, clarifying the DESCRIPTION and the definition of the <b>-R</b> +option.</p> +<p>Austin Group Interpretation 1003.1-2001 #129 is applied, clarifying the behavior of <i>ls</i> when no operands are +specified.</p> +<p>Austin Group Interpretation 1003.1-2001 #198 is applied, clarifying the requirements for the <b>-H</b> option.</p> +<p>SD5-XCU-ERN-50 is applied, adding the <b>-A</b> option.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>The <b>-S</b> option is added from The Open Group Technical Standard, 2006, Extended API Set Part 1.</p> +<p>The <b>-f</b>, <b>-m</b>, <b>-n</b>, <b>-p</b>, <b>-s</b>, and <b>-x</b> options are moved from the XSI option to the Base.</p> +<p>The description of the <b>-f</b>, <b>-s</b>, and <b>-t</b> options are revised and the <b>-k</b> option is added.</p> +<p>POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0098 [424], XCU/TC1-2008/0099 [424], XCU/TC1-2008/0100 [424], +XCU/TC1-2008/0101 [424], XCU/TC1-2008/0102 [424], XCU/TC1-2008/0103 [424], XCU/TC1-2008/0104 [424], XCU/TC1-2008/0105 [423,424], +XCU/TC1-2008/0106 [424], XCU/TC1-2008/0107 [424], XCU/TC1-2008/0108 [424], XCU/TC1-2008/0109 [424], XCU/TC1-2008/0110 [424], +XCU/TC1-2008/0111 [423], XCU/TC1-2008/0112 [117], XCU/TC1-2008/0113 [117], XCU/TC1-2008/0114 [117], XCU/TC1-2008/0115 [424], and +XCU/TC1-2008/0116 [424] are applied.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0115 [963] and XCU/TC2-2008/0116 [963] are applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_73_25" id="tag_20_73_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to report an error if a utility is directed to display a +pathname that contains any bytes that have the encoded value of a <newline> character when <newline> is a terminator or +separator in the output format being used.</p> +<p>Austin Group Defect 1023 is applied, clarifying the <b>-R</b> option with respect to subdirectory filenames beginning with a +<period>.</p> +<p>Austin Group Defect 1070 is applied, requiring that any filenames or pathnames that collate equally are further compared +byte-by-byte using the collating sequence for the POSIX locale.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1146 is applied, clarifying the requirements for the status line written by <i>ls</i> <b>-l</b>.</p> +<p>Austin Group Defect 1147 is applied, clarifying the requirements for trailing file type indicators (such as <tt>'/'</tt> for a +directory).</p> +<p>Austin Group Defect 1148 is applied, clarifying the behavior of the <b>-S</b> option for symbolic links.</p> +<p>Austin Group Defect 1149 is applied, inserting a comma in the description of the <b>-r</b> option.</p> +<p>Austin Group Defect 1185 is applied, changing the <i>COLUMNS</i> entry in ENVIRONMENT VARIABLES.</p> +<p>Austin Group Defect 1217 is applied, adding file type indicators for sockets.</p> +<p>Austin Group Defect 1261 is applied, changing the STDOUT and EXAMPLES sections in relation to the <tt><</tt><i>directory +name</i><tt>></tt> output.</p> +<p>Austin Group Defect 1457 is applied, adding <a href="../utilities/readlink.html"><i>readlink</i></a> to the SEE ALSO +section.</p> +<p>Austin Group Defect 1703 is applied, changing "at-sign" to "<commercial-at>".</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/lp.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/m4.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/m4.html b/bdd/m4.html @@ -0,0 +1,635 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>m4</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/ls.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/mailx.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="m4" id="m4"></a> <a name="tag_20_74" id="tag_20_74"></a><!-- m4 --> +<h4 class="mansect"><a name="tag_20_74_01" id="tag_20_74_01"></a>NAME</h4> +<blockquote>m4 — macro processor</blockquote> +<h4 class="mansect"><a name="tag_20_74_02" id="tag_20_74_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>m4</tt> <b>[</b><tt>-s</tt><b>] [</b><tt>-D</tt> <i>name</i><b>[</b><tt>=</tt><i>val</i><b>]]</b><tt>...</tt> +<b>[</b><tt>-U</tt> <i>name</i><b>]</b><tt>...</tt> <b>[</b><i>file</i><tt>...</tt><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_74_03" id="tag_20_74_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>m4</i> utility is a macro processor that shall read one or more text files, process them according to their included +macro statements, and write the results to standard output.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_74_04" id="tag_20_74_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>m4</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> , except that the order of the <b>-D</b> and <b>-U</b> options shall be significant, and options can be +interspersed with operands.</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-s</b></dt> +<dd>Enable line synchronization output for the <a href="../utilities/c17.html"><i>c17</i></a> preprocessor phase (that is, +<b>#line</b> directives).</dd> +<dt><b>-D </b><i>name</i><b>[</b>=<i>val</i><b>]</b></dt> +<dd><br> +Define <i>name</i> to <i>val</i> or to null if =<i>val</i> is omitted.</dd> +<dt><b>-U </b><i>name</i></dt> +<dd>Undefine <i>name</i>.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_74_05" id="tag_20_74_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of a text file to be processed. If no <i>file</i> is given, or if it is <tt>'-'</tt>, the standard input shall be +read.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_74_06" id="tag_20_74_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be a text file that is used if no <i>file</i> operand is given, or if it is <tt>'-'</tt>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_74_07" id="tag_20_74_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input file named by the <i>file</i> operand shall be a text file.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_74_08" id="tag_20_74_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>m4</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_74_09" id="tag_20_74_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_74_10" id="tag_20_74_10"></a>STDOUT</h4> +<blockquote> +<p>The standard output shall be the same as the input files, after being processed for macro expansion.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_74_11" id="tag_20_74_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used to display strings with the <b>errprint</b> macro, macro tracing enabled by the <b>traceon</b> +macro, the defined text for macros written by the <b>dumpdef</b> macro, or for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_74_12" id="tag_20_74_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_74_13" id="tag_20_74_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>The <i>m4</i> utility shall compare each token from the input against the set of built-in and user-defined macros. If the token +matches the name of a macro, then the token shall be replaced by the macro's defining text, if any, then scanning for tokens shall +resume at the start of the macro's defining text concatenated with the subsequent input. If a token does not match the name of a +macro, it shall be written to standard output. Macros may have arguments, in which case the arguments shall be substituted into the +defining text before it is rescanned.</p> +<p>No special meaning shall be given to characters enclosed between matching left and right quoting strings, other than identifying +nested quoting while finding the matching right quoting string, but the outermost quoting strings shall themselves be discarded. By +default, the left quoting string consists of a grave accent (backquote) and the right quoting string consists of an acute accent +(single-quote); see also the <b>changequote</b> macro.</p> +<p>Comments are written but not scanned for matching macro names; by default, the begin-comment string consists of the +<number-sign> character and the end-comment string consists of a <newline>. See also the <b>changecom</b> and +<b>dnl</b> macros.</p> +<p>Name tokens shall consist of the longest possible sequence of letters, digits, and underscores, where the first character is not +a digit. Tokens not of this form shall not be treated as name tokens. A macro call is a name token that matches the name of a +built-in or user-defined macro. Macro calls can have either of the following forms, which shall be distinguished by whether or not +the macro name is immediately followed by a <left-parenthesis>:</p> +<pre> +<i>name</i><tt> +<br> +</tt><i>name</i><tt>(</tt><i>arg1</i><tt>, </tt><i>arg2</i><tt>, ..., </tt><i>argn</i><tt>) +</tt></pre> +<p>The application shall ensure that the <left-parenthesis> immediately follows the name of the macro. If a token matching +the name of a macro is not followed by a <left-parenthesis>, it shall be handled as a use of that macro without +arguments.</p> +<p>If a macro name is followed by a <left-parenthesis>, the subsequent text shall be tokenized and expanded until a token is +encountered that is not a quoted string and whose expansion includes a matching unquoted <right-parenthesis>. The expanded +text between the <left-parenthesis> and the matching unquoted <right-parenthesis> is the macro's argument text. An +unquoted <comma> character within the macro's argument text shall mark the end of one argument and the beginning of the next +argument unless the unquoted <comma> is enclosed within a nested unquoted <left-parenthesis>, <right-parenthesis> +pair. The unquoted <comma> characters that separate the arguments, and any unquoted white-space characters at the beginning +of each argument, shall be discarded. All other characters in the macro's argument text, including any white-space characters at +the end of an argument and any nested parenthesized text, shall be retained. The input text containing the macro name, the +following <left-parenthesis>, and all tokens up to and including the token whose expansion contained the matching unquoted +<right-parenthesis> shall be replaced, and tokenization shall resume on the result of performing argument substition on the +macro's defining text followed by any expanded text that followed the matching unquoted <right-parenthesis>. Otherwise, the +macro name was not followed by a <left-parenthesis>, and tokenization shall resume on the result of performing argument +substitution with zero arguments on the macro's defining text.</p> +<p>During argument substitution, arguments shall be positionally defined and referenced. The string <tt>"$1"</tt> in the defining +text shall be replaced by the first argument. Systems shall support at least nine arguments; only the first nine can be referenced, +using the strings <tt>"$1"</tt> to <tt>"$9"</tt>, inclusive. The string <tt>"$0"</tt> shall be replaced with the name of the macro. +The string <tt>"$#"</tt> shall be replaced by the number of arguments as a minimal string of decimal digits (<tt>'0'</tt> if the +macro was invoked without being followed by a <left-parenthesis>, otherwise 1 more than the number of unquoted <comma> +characters that divided arguments in the macro's argument text). The string <tt>"$*"</tt> shall be replaced by a list of all of the +arguments, separated by <comma> characters. The string <tt>"$@"</tt> shall be replaced by a list of all of the arguments +separated by <comma> characters, and each argument shall be quoted using the current left and right quoting strings. The +string <tt>"${"</tt> produces unspecified behavior.</p> +<p>If fewer arguments are supplied than are in the macro definition, the omitted arguments are taken to be null. It is not an error +if more arguments are supplied than are in the macro definition.</p> +<p>The <i>m4</i> utility shall make available the following built-in macros. They can be redefined, but once this is done the +original meaning is lost. Their values shall be null unless otherwise stated. In the descriptions below, the term <i>defining +text</i> refers to the value of the macro: the second argument to the <b>define</b> macro, among other things. Except for the first +argument to the <b>eval</b> macro, all numeric arguments to built-in macros shall be interpreted as decimal values. The string +values produced as the defining text of the <b>decr</b>, <b>divnum</b>, <b>incr</b>, <b>index</b>, <b>len</b>, and <b>sysval</b> +built-in macros shall be in the form of a decimal-constant as defined in the C language.</p> +<dl compact> +<dd></dd> +<dt><b>changecom</b></dt> +<dd>The <b>changecom</b> macro shall set the begin-comment and end-comment strings. With no arguments, the comment mechanism shall +be disabled. With a single non-null argument, that argument shall become the begin-comment and the <newline> shall become the +end-comment string. With two non-null arguments, the first argument shall become the begin-comment string and the second argument +shall become the end-comment string. The behavior is unspecified if either argument is provided but null, or if either argument +includes letters, digits, underscore, or <left-parenthesis>. Systems shall support comment strings of at least five +characters.</dd> +<dt><b>changequote</b></dt> +<dd>The <b>changequote</b> macro shall set the begin-quote and end-quote strings. With no arguments, the quote strings shall be set +to the default values (that is, <tt>`'</tt>). The behavior is unspecified if there is a single argument, or if either argument is +null or includes letters, digits, underscore, or <left-parenthesis>. With two non-null arguments, the first argument shall +become the begin-quote string and the second argument shall become the end-quote string. Systems shall support quote strings of at +least five characters.</dd> +<dt><b>decr</b></dt> +<dd>The defining text of the <b>decr</b> macro shall be its first argument decremented by 1. It shall be an error to specify an +argument containing any non-numeric characters. The behavior is unspecified if <b>decr</b> is not immediately followed by a +<left-parenthesis>.</dd> +<dt><b>define</b></dt> +<dd>The second argument shall become the defining text of the macro whose name is the first argument. It is unspecified whether the +<b>define</b> macro deletes all prior definitions of the macro named by its first argument or preserves all but the current +definition of the macro. The behavior is unspecified if <b>define</b> is not immediately followed by a +<left-parenthesis>.</dd> +<dt><b>defn</b></dt> +<dd>The defining text of the <b>defn</b> macro shall be the quoted definition (using the current quoting strings) of its arguments. +The behavior is unspecified if <b>defn</b> is not immediately followed by a <left-parenthesis>.</dd> +<dt><b>divert</b></dt> +<dd>The <i>m4</i> utility maintains nine temporary buffers, numbered 1 to 9, inclusive. When the last of the input has been +processed, any output that has been placed in these buffers shall be written to standard output in buffer-numerical order. The +<b>divert</b> macro shall divert future output to the buffer specified by its argument. Specifying no argument or an argument of 0 +shall resume the normal output process. Output diverted to a stream with a negative number shall be discarded. Behavior is +implementation-defined if a stream number larger than 9 is specified. It shall be an error to specify an argument containing any +non-numeric characters.</dd> +<dt><b>divnum</b></dt> +<dd>The defining text of the <b>divnum</b> macro shall be the number of the current output stream as a string.</dd> +<dt><b>dnl</b></dt> +<dd>The <b>dnl</b> macro shall cause <i>m4</i> to discard all input characters up to and including the next <newline>.</dd> +<dt><b>dumpdef</b></dt> +<dd>The <b>dumpdef</b> macro shall write the defined text to standard error for each of the macros specified as arguments, or, if +no arguments are specified, for all macros.</dd> +<dt><b>errprint</b></dt> +<dd>The <b>errprint</b> macro shall write its arguments to standard error. The behavior is unspecified if <b>errprint</b> is not +immediately followed by a <left-parenthesis>.</dd> +<dt><b>eval</b></dt> +<dd>The <b>eval</b> macro shall evaluate its first argument as an arithmetic expression, using signed integer arithmetic with at +least 32-bit precision. At least the following C-language operators shall be supported, with precedence, associativity, and +behavior as described in <a href="../utilities/V3_chap01.html#tag_18_01_02_01"><i>1.1.2.1 Arithmetic Precision and +Operations</i></a> : +<pre> +<tt>() +unary + +unary - +~ +<br> +! +binary * +/ +% +binary + +binary - +<< +>> +< +<= +> +>= +== +!= +binary & +^ +| +&& +|| +</tt></pre> +<p>Systems shall support octal and hexadecimal numbers as in the ISO C standard. The second argument, if specified, shall set +the radix for the result; if the argument is blank or unspecified, the default is 10. Behavior is unspecified if the radix falls +outside the range 2 to 36, inclusive. The third argument, if specified, sets the minimum number of digits in the result. Behavior +is unspecified if the third argument is less than zero. It shall be an error to specify the second or third argument containing any +non-numeric characters. The behavior is unspecified if <b>eval</b> is not immediately followed by a <left-parenthesis>.</p> +</dd> +<dt><b>ifdef</b></dt> +<dd>If the first argument to the <b>ifdef</b> macro is defined, the defining text shall be the second argument. Otherwise, the +defining text shall be the third argument, if specified, or the null string, if not. The behavior is unspecified if <b>ifdef</b> is +not immediately followed by a <left-parenthesis>.</dd> +<dt><b>ifelse</b></dt> +<dd>The <b>ifelse</b> macro takes three or more arguments. If the first two arguments compare as equal strings, the defining text +shall be the third argument. If the first two arguments do not compare as equal strings and there are three arguments, the defining +text shall be null. If the first two arguments do not compare as equal strings and there are four or five arguments, the defining +text shall be the fourth argument. If the first two arguments do not compare as equal strings and there are six or more arguments, +the first three arguments shall be discarded and processing shall restart with the remaining arguments. The behavior is unspecified +if <b>ifelse</b> is not immediately followed by a <left-parenthesis>.</dd> +<dt><b>include</b></dt> +<dd>The defining text for the <b>include</b> macro shall be the contents of the file named by the first argument. It shall be an +error if the file cannot be read. The behavior is unspecified if <b>include</b> is not immediately followed by a +<left-parenthesis>.</dd> +<dt><b>incr</b></dt> +<dd>The defining text of the <b>incr</b> macro shall be its first argument incremented by 1. It shall be an error to specify an +argument containing any non-numeric characters. The behavior is unspecified if <b>incr</b> is not immediately followed by a +<left-parenthesis>.</dd> +<dt><b>index</b></dt> +<dd>The defining text of the <b>index</b> macro shall be the first character position (as a string) in the first argument where a +string matching the second argument begins (zero origin), or -1 if the second argument does not occur. The behavior is unspecified +if <b>index</b> is not immediately followed by a <left-parenthesis>.</dd> +<dt><b>len</b></dt> +<dd>The defining text of the <b>len</b> macro shall be the length (as a string) of the first argument. The behavior is unspecified +if <b>len</b> is not immediately followed by a <left-parenthesis>.</dd> +<dt><b>m4exit</b></dt> +<dd>Exit from the <i>m4</i> utility. If the first argument is specified, it shall be the exit code. If no argument is specified, +the exit code shall be zero. It shall be an error to specify an argument containing any non-numeric characters. If the first +argument is zero or no argument is specified, and an error has previously occurred (for example, a <i>file</i> operand that could +not be opened), the exit status shall be non-zero.</dd> +<dt><b>m4wrap</b></dt> +<dd>The first argument shall be processed when EOF is reached. If the <b>m4wrap</b> macro is used multiple times, the arguments +specified shall be processed in the order in which the <b>m4wrap</b> macros were processed. The behavior is unspecified if +<b>m4wrap</b> is not immediately followed by a <left-parenthesis>.</dd> +<dt><b>mkstemp</b></dt> +<dd>The defining text shall be as if it were the resulting pathname after a successful call to the <a href= +"../functions/mkstemp.html"><i>mkstemp</i>()</a> function defined in the System Interfaces volume of POSIX.1-2024 called with the +first argument to the macro invocation. If a file is created, that file shall be closed. If a file could not be created, the +<i>m4</i> utility shall write a diagnostic message to standard error and shall continue processing input but its final exit status +shall be non-zero; the defining text of the macro shall be the empty string. The behavior is unspecified if <b>mkstemp</b> is not +immediately followed by a <left-parenthesis>.</dd> +<dt><b>popdef</b></dt> +<dd>The <b>popdef</b> macro shall delete the current definition of its arguments, replacing that definition with the previous one. +If there is no previous definition, the macro is undefined. The behavior is unspecified if <b>popdef</b> is not immediately +followed by a <left-parenthesis>.</dd> +<dt><b>pushdef</b></dt> +<dd>The <b>pushdef</b> macro shall be equivalent to the <b>define</b> macro with the exception that it shall preserve any current +definition for future retrieval using the <b>popdef</b> macro. The behavior is unspecified if <b>pushdef</b> is not immediately +followed by a <left-parenthesis>.</dd> +<dt><b>shift</b></dt> +<dd>The defining text for the <b>shift</b> macro shall be a comma-separated list of its arguments except the first one. Each +argument shall be quoted using the current quoting strings. The behavior is unspecified if <b>shift</b> is not immediately followed +by a <left-parenthesis>.</dd> +<dt><b>sinclude</b></dt> +<dd>The <b>sinclude</b> macro shall be equivalent to the <b>include</b> macro, except that it shall not be an error if the file is +inaccessible. The behavior is unspecified if <b>sinclude</b> is not immediately followed by a <left-parenthesis>.</dd> +<dt><b>substr</b></dt> +<dd>The defining text for the <b>substr</b> macro shall be the substring of the first argument beginning at the zero-offset +character position specified by the second argument. The third argument, if specified, shall be the number of characters to select; +if not specified, the characters from the starting point to the end of the first argument shall become the defining text. It shall +not be an error to specify a starting point beyond the end of the first argument and the defining text shall be null. It shall be +an error to specify an argument containing any non-numeric characters. The behavior is unspecified if <b>substr</b> is not +immediately followed by a <left-parenthesis>.</dd> +<dt><b>syscmd</b></dt> +<dd>The <b>syscmd</b> macro shall interpret its first argument as a shell command line. The defining text shall be the string +result of that command. The string result shall not be rescanned for macros while setting the defining text. No output redirection +shall be performed by the <i>m4</i> utility. The exit status value from the command can be retrieved using the <b>sysval</b> macro. +The behavior is unspecified if <b>syscmd</b> is not immediately followed by a <left-parenthesis>.</dd> +<dt><b>sysval</b></dt> +<dd>The defining text of the <b>sysval</b> macro shall be the exit value of the utility last invoked by the <b>syscmd</b> macro (as +a string).</dd> +<dt><b>traceon</b></dt> +<dd>The <b>traceon</b> macro shall enable tracing for the macros specified as arguments, or, if no arguments are specified, for all +macros. The trace output shall be written to standard error in an unspecified format.</dd> +<dt><b>traceoff</b></dt> +<dd>The <b>traceoff</b> macro shall disable tracing for the macros specified as arguments, or, if no arguments are specified, for +all macros.</dd> +<dt><b>translit</b></dt> +<dd>The defining text of the <b>translit</b> macro shall be the first argument with every character that occurs in the second +argument replaced with the corresponding character from the third argument. If no replacement character is specified for some +source character because the second argument is longer than the third argument, that character shall be deleted from the first +argument in <b>translit</b>'s defining text. The behavior is unspecified if the <tt>'-'</tt> character appears within the second or +third argument anywhere besides the first or last character. The behavior is unspecified if the same character appears more than +once in the second argument. The behavior is unspecified if <b>translit</b> is not immediately followed by a +<left-parenthesis>.</dd> +<dt><b>undefine</b></dt> +<dd>The <b>undefine</b> macro shall delete all definitions (including those preserved using the <b>pushdef</b> macro) of the macros +named by its arguments. The behavior is unspecified if <b>undefine</b> is not immediately followed by a +<left-parenthesis>.</dd> +<dt><b>undivert</b></dt> +<dd>The <b>undivert</b> macro shall cause immediate output of any text in temporary buffers named as arguments, or all temporary +buffers if no arguments are specified. Buffers can be undiverted into other temporary buffers. Undiverting shall discard the +contents of the temporary buffer. The behavior is unspecified if an argument contains any non-numeric characters.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_74_14" id="tag_20_74_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred</dd> +</dl> +<p>If the <b>m4exit</b> macro is used, the exit value can be specified by the input file.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_74_15" id="tag_20_74_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_74_16" id="tag_20_74_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The <b>defn</b> macro is useful for renaming macros, especially built-ins.</p> +<p>Since <b>eval</b> defers to the ISO C standard, some operations have undefined behavior. In some implementations, division +or remainder by zero cause a fatal signal, even if the division occurs on the short-circuited branch of <tt>"&&"</tt> or +<tt>"||"</tt>. Any operation that overflows in signed arithmetic produces undefined behavior. Likewise, using the <b>shift</b> +operators with a shift amount that is not positive and smaller than the precision is undefined, as is shifting a negative number to +the right. Historically, not all implementations obeyed C-language precedence rules: <tt>'~'</tt> and <tt>'!'</tt> were lower than +<tt>'=='</tt>; <tt>'=='</tt> and <tt>'!='</tt> were not lower than <tt>'<'</tt>; and <tt>'|'</tt> was not lower than +<tt>'^'</tt>; the liberal use of <tt>"()"</tt> can force the desired precedence even with these non-compliant implementations. +Furthermore, some traditional implementations treated <tt>'^'</tt> as an exponentiation operator, although most implementations now +use <tt>"**"</tt> as an extension for this purpose.</p> +<p>When a macro has been multiply defined via the <b>pushdef</b> macro, it is unspecified whether the <b>define</b> macro will +alter only the most recent definition (as though by <b>popdef</b> and <b>pushdef</b>), or replace the entire stack of definitions +with a single definition (as though by <b>undefine</b> and <b>pushdef</b>). An application desiring particular behavior for the +<b>define</b> macro in this case can redefine it accordingly.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_74_17" id="tag_20_74_17"></a>EXAMPLES</h4> +<blockquote> +<p>If the file <b>m4src</b> contains the lines:</p> +<pre> +<tt>The value of `VER' is "VER". +ifdef(`VER', ``VER'' is defined to be VER., VER is not defined.) +ifelse(VER, 1, ``VER'' is `VER'.) +ifelse(VER, 2, ``VER'' is `VER'., ``VER'' is not 2.) +end +</tt></pre> +<p>then the command</p> +<pre> +<tt>m4 m4src +</tt></pre> +<p>or the command:</p> +<pre> +<tt>m4 -U VER m4src +</tt></pre> +<p>produces the output:</p> +<pre> +<tt>The value of VER is "VER". +VER is not defined. +<br> +VER is not 2. +end +</tt></pre> +<p>The command:</p> +<pre> +<tt>m4 -D VER m4src +</tt></pre> +<p>produces the output:</p> +<pre> +<tt>The value of VER is "". +VER is defined to be . +<br> +VER is not 2. +end +</tt></pre> +<p>The command:</p> +<pre> +<tt>m4 -D VER=1 m4src +</tt></pre> +<p>produces the output:</p> +<pre> +<tt>The value of VER is "1". +VER is defined to be 1. +VER is 1. +VER is not 2. +end +</tt></pre> +<p>The command:</p> +<pre> +<tt>m4 -D VER=2 m4src +</tt></pre> +<p>produces the output:</p> +<pre> +<tt>The value of VER is "2". +VER is defined to be 2. +<br> +VER is 2. +end +</tt></pre> +<p>In the following six examples, an additional line is evaluated after this prologue of three definitions:</p> +<pre> +<tt>define(`macro', `argument 2 is :`$2':, called with $# arguments')dnl +define(`argumentsa', `Arguments')dnl +define(`a', `.')dnl +</tt></pre> +<ol> +<li> +<p>The additional line:</p> +<pre> +<tt>macro`'a +</tt></pre> +produces: +<pre> +<tt>argument 2 is ::, called with 0 arguments. +</tt></pre> +Explanation: <i>macro</i> is called with 0 arguments (as shown by the <tt>$#</tt> substitution), the substitution of <tt>$2</tt> is +the empty string, and the empty quoted string after the expansion text prevents concatenation with the subsequent <tt>'a'</tt>, +which in turn lets macro <i>a</i> expand to the final <tt>'.'</tt>.</li> +<li> +<p>The additional line:</p> +<pre> +<tt>macro()a +</tt></pre> +produces: +<pre> +<tt>argument 2 is ::, called with 1 Arguments +</tt></pre> +Explanation: <i>macro</i> is called with one (empty string) argument; then the defining text ending in <tt>"arguments"</tt> is +concatenated with the subsequent <tt>'a'</tt> to form the next macro name <i>argumentsa</i> which is expanded into +<tt>Arguments</tt> before the final output.</li> +<li> +<p>The additional line:</p> +<pre> +<tt>macro( 1, ( ,2,) , `3') +</tt></pre> +produces: +<pre> +<tt>argument 2 is :( ,2,) :, called with 3 arguments +</tt></pre> +Explanation: Leading (but not internal or trailing) space is removed before the argument substituted for <tt>$2</tt>, and the +unquoted commas embedded in parentheses do not delineate arguments.</li> +<li> +<p>The additional line:</p> +<pre> +<tt>macro( `1', `mac2(,`2',)', `3') +</tt></pre> +produces: +<pre> +<tt>argument 2 is :mac2(,`2',):, called with 3 arguments +</tt></pre> +Explanation: Regardless of whether <i>mac2</i> is a defined macro, quoting in the macro call prevents interpretation of +<tt>"mac2"</tt> during argument collection, and the quoting in the defining text of <i>macro</i> prevents interpretation of +<tt>"mac2"</tt> in the substitution of <tt>$2</tt> during rescan of the output of <i>macro</i>.</li> +<li> +<p>The additional line:</p> +<pre> +<tt>undefine(`mac2')macro( 1, mac2(,2,), 3) +</tt></pre> +produces: +<pre> +<tt>argument 2 is :mac2(,2,):, called with 3 arguments +</tt></pre> +Explanation: <i>mac2</i> is not a macro name when scanned during argument collection, so it and the subsequent parenthesized text +are used literally.</li> +<li> +<p>The additional line:</p> +<pre> +<tt>define(`mac2', `hi $@')macro( 1, mac2( ,2,), 3) +</tt></pre> +produces: +<pre> +<tt>argument 2 is :hi :, called with 5 arguments +</tt></pre> +Explanation: <i>mac2</i> is a macro name, so collecting the arguments to <i>macro</i> requires scanning the output of +<i>mac2(,2,)</i> (the text <tt>hi `',`2',`'</tt> after substitution of <tt>$@</tt>); this output contains unquoted commas causing +additional arguments to be visible to <i>macro</i>.</li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_74_18" id="tag_20_74_18"></a>RATIONALE</h4> +<blockquote> +<p>Historic System V-based behavior treated <tt>"${"</tt> in a macro definition as two literal characters. However, this sequence +is left unspecified so that implementations may offer extensions such as <tt>"${11}"</tt> meaning the eleventh argument. Macros can +still be defined with appropriate uses of nested quoting to result in a literal <tt>"${"</tt> in the output after rescanning +removes the nested quotes.</p> +<p>In the <b>translit</b> built-in, historic System V-based behavior treated <tt>'-'</tt> as a literal; GNU behavior treats it as a +range. This version of the standard allows either behavior.</p> +<p>Earlier versions of this standard allowed the exit status to be either zero or non-zero when <tt>m4exit(0)</tt> is called after +an error has occurred. Exiting with zero status is now disallowed as this hides the fact that an error occurred from shell scripts +that check the exit status of <i>m4</i>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_74_19" id="tag_20_74_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_74_20" id="tag_20_74_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/c17.html#"><i>c17</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_74_21" id="tag_20_74_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_74_22" id="tag_20_74_22"></a>Issue 5</h4> +<blockquote> +<p>The phrase "the defined text for macros written by the <b>dumpdef</b> macro" is added to the description of STDERR, and the +description of <b>dumpdef</b> is updated to indicate that output is written to standard error. The description of <b>eval</b> is +updated to indicate that the list of excluded C operators excludes unary <tt>'&'</tt> and <tt>'.'</tt>. In the description of +<b>ifdef</b>, the phrase "and it is not defined to be zero" is deleted.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_74_23" id="tag_20_74_23"></a>Issue 6</h4> +<blockquote> +<p>In the EXTENDED DESCRIPTION, the <b>eval</b> text is updated to include a <tt>'&'</tt> character in the excepted list.</p> +<p>The EXTENDED DESCRIPTION of <b>divert</b> is updated to clarify that there are only nine diversion buffers.</p> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +<p>The Open Group Base Resolution bwg2000-006 is applied.</p> +<p>IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/31 is applied, replacing the EXAMPLES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_74_24" id="tag_20_74_24"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #117 is applied, marking the <b>maketemp</b> macro obsolescent and adding a new +<b>mkstemp</b> macro.</p> +<p>Austin Group Interpretation 1003.1-2001 #207 is applied, clarifying the handling of white-space characters that precede or trail +any macro arguments.</p> +<p>SD5-XCU-ERN-6 is applied, clarifying that Guideline 9 of the Utility Syntax Guidelines does not apply (options can be +interspersed with operands).</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>SD5-XCU-ERN-99 is applied, clarifying the definition of the <b>divert</b> macro in the EXTENDED DESCRIPTION.</p> +<p>SD5-XCU-ERN-100 is applied, clarifying the definition of the <b>syscmd</b> macro in the EXTENDED DESCRIPTION.</p> +<p>SD5-XCU-ERN-101 is applied, clarifying the definition of the <b>undivert</b> macro in the EXTENDED DESCRIPTION.</p> +<p>SD5-XCU-ERN-111 is applied to the EXTENDED DESCRIPTION, clarifying that the string <tt>"${"</tt> produces unspecified +behavior.</p> +<p>SD5-XCU-ERN-112 is applied, updating the <b>changequote</b> macro.</p> +<p>SD5-XCU-ERN-118 is applied, clarifying the definition of the <b>define</b> macro in the EXTENDED DESCRIPTION and APPLICATION +USAGE sections.</p> +<p>SD5-XCU-ERN-119 is applied, clarifying the definition of the <b>translit</b> macro in the EXTENDED DESCRIPTION and RATIONALE +sections.</p> +<p>SD5-XCU-ERN-130, SD5-XCU-ERN-131, and SD5-XCU-ERN-137 are applied.</p> +<p>The <i>m4</i> utility is moved from the XSI option to the Base.<br></p> +<p>POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0117 [241], XCU/TC1-2008/0118 [242,431], XCU/TC1-2008/0119 [242,431], and +XCU/TC1-2008/0120 [325,430] are applied.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0117 [964], XCU/TC2-2008/0118 [970], and XCU/TC2-2008/0119 [964] are +applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_74_25" id="tag_20_74_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to report an error if a utility is directed to display a +pathname that contains any bytes that have the encoded value of a <newline> character when <newline> is a terminator or +separator in the output format being used.</p> +<p>Austin Group Defect 984 is applied, requiring that the exit status of <i>m4</i> is non-zero when <b>m4exit</b> is called with a +first argument of zero or with no arguments after an error has occurred.</p> +<p>Austin Group Defect 1072 is applied, clarifying the handling of macro arguments.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1330 is applied, removing the obsolescent <b>maketemp</b> macro.</p> +<p>Austin Group Defect 1514 is applied, changing the RATIONALE section to use the same terminology as the normative text to which +it refers.</p> +<p>Austin Group Defect 1570 is applied, removing extra spacing in <tt>"=="</tt>.</p> +<p>Austin Group Defect 1658 is applied, changing "whitespace characters" to "white-space characters".</p> +<p>Austin Group Defect 1730 is applied, adding square brackets around <i>file</i><tt>...</tt> in the SYNOPSIS.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/ls.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/mailx.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/mailx.html b/bdd/mailx.html @@ -0,0 +1,1654 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>mailx</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/m4.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/make.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="mailx" id="mailx"></a> <a name="tag_20_75" id="tag_20_75"></a><!-- mailx --> +<h4 class="mansect"><a name="tag_20_75_01" id="tag_20_75_01"></a>NAME</h4> +<blockquote>mailx — process messages</blockquote> +<h4 class="mansect"><a name="tag_20_75_02" id="tag_20_75_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<h5><a name="tag_20_75_02_01" id="tag_20_75_02_01"></a>Send Mode</h5> +<p><code><tt>mailx</tt> <b>[</b><tt>-E</tt><b>] [</b><tt>-s</tt> <i>subject</i><b>]</b> <i>address</i><tt>...</tt></code></p> +<h5><a name="tag_20_75_02_02" id="tag_20_75_02_02"></a>Receive Mode</h5> +<pre> +<tt><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup><img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +mailx -e +mailx </tt><b>[</b><tt>-HiNn</tt><b>] [</b><tt>-F</tt><b>] [</b><tt>-u </tt><i>user</i><b>]</b><tt> +mailx -f </tt><b>[</b><tt>-HiNn</tt><b>] [</b><tt>-F</tt><b>] [</b><i>file</i><b>]</b><tt> +<img src="../images/opt-end.gif" alt="[Option End]" border="0"> +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_75_03" id="tag_20_75_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>mailx</i> utility provides a message sending and receiving facility. It has two major modes, selected by the options +used: Send Mode and Receive Mode.</p> +<p>On systems that do not support the User Portability Utilities option, an application using <i>mailx</i> shall have the ability +to send messages in an unspecified manner (Send Mode). Unless the first character of one or more lines is <tilde> +(<tt>'~'</tt>), all characters in the input message shall appear in the delivered message, but additional characters may be +inserted in the message before it is retrieved.</p> +<p><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> On +systems supporting the User Portability Utilities option, mail-receiving capabilities and other interactive features, Receive Mode, +described below, also shall be enabled. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p> +<h5><a name="tag_20_75_03_01" id="tag_20_75_03_01"></a>Send Mode</h5> +<p>Send Mode can be used by applications or users to send messages from the text in standard input. The message shall be passed to +the mail delivery software. The mail delivery software shall process passed messages according to the rules of IETF RFC 5322.</p> +<h5><a name="tag_20_75_03_02" id="tag_20_75_03_02"></a>Receive Mode</h5> +<sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +<p>Receive Mode is more oriented towards interactive users. Mail can be read and sent in this interactive mode.</p> +<p>When reading mail, <i>mailx</i> provides commands to facilitate saving, deleting, and responding to messages. When sending mail, +<i>mailx</i> allows editing, reviewing, and other modification of the message as it is entered.</p> +<p>Incoming mail shall be stored in one or more unspecified locations for each user, collectively called the system <i>mailbox</i> +for that user. When <i>mailx</i> is invoked in Receive Mode, the system mailbox shall be the default place to find new mail. As +messages are read, they shall be marked to be moved to a secondary file for storage, unless specific action is taken. This +secondary file is called the <b>mbox</b> and is normally located in the directory referred to by the <i>HOME</i> environment +variable (see <i>MBOX</i> in the ENVIRONMENT VARIABLES section for a description of this file). Messages shall remain in this file +until explicitly removed. When the <b>-f</b> option is used to read mail messages from secondary files, messages shall be retained +in those files unless specifically removed. All three of these locations—system mailbox, <b>mbox</b>, and secondary file—are +referred to in this section as simply "mailboxes", unless more specific identification is required. <img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_75_04" id="tag_20_75_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>mailx</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported. (Only the <b>-E</b> and <b>-s</b> <i>subject</i> options are required on all systems. +The other options are required only on systems supporting the User Portability Utilities option.)</p> +<dl compact> +<dd></dd> +<dt><b>-E</b></dt> +<dd>Discard messages with an empty message body.</dd> +<dt><b>-e</b></dt> +<dd><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Test for the presence of mail in the system mailbox. The <i>mailx</i> utility shall write nothing and exit with a successful return +code if there is mail to read. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-f</b></dt> +<dd><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Read messages from the file named by the <i>file</i> operand instead of the system mailbox. (See also <b>folder</b>.) If no +<i>file</i> operand is specified, read messages from <b>mbox</b> instead of the system mailbox. <img src="../images/opt-end.gif" +alt="[Option End]" border="0"></dd> +<dt><b>-F</b></dt> +<dd><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Record the message in a file named after the first recipient. The name is the login-name portion of the address found first in the +<b>To</b> field in the message header. Overrides the <b>record</b> variable, if set (see <a href="#tag_20_75_13_02">Internal +Variables in mailx</a> ). <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-H</b></dt> +<dd><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Write a header summary only. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-i</b></dt> +<dd><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Ignore interrupts. (See also <b>ignore</b>.) <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-n</b></dt> +<dd><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> Do +not initialize from the system default start-up file. See the EXTENDED DESCRIPTION section. <img src="../images/opt-end.gif" alt= +"[Option End]" border="0"></dd> +<dt><b>-N</b></dt> +<dd><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> Do +not write an initial header summary. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-s </b><i>subject</i></dt> +<dd>Set the <b>Subject</b> header field to <i>subject</i>. All characters in the <i>subject</i> string shall appear in the +delivered message. The results are unspecified if <i>subject</i> is longer than {LINE_MAX} - 10 bytes or contains a +<newline>.</dd> +<dt><b>-u </b><i>user</i></dt> +<dd><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Read the system mailbox of the login name <i>user</i>. This shall only be successful if the invoking user has appropriate +privileges to read the system mailbox of that user. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_75_05" id="tag_20_75_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>address</i></dt> +<dd>Addressee of message. When <b>-n</b> is specified and no user start-up files are accessed (see the EXTENDED DESCRIPTION +section), the user or application shall ensure this is an address to pass to the mail delivery system. Any system or user start-up +files may enable aliases (see <b>alias</b> under <a href="#tag_20_75_13_03">Commands in mailx</a> ) that may modify the form of +<i>address</i> before it is passed to the mail delivery system.</dd> +<dt><i>file</i></dt> +<dd><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> A +pathname of a file to be read instead of the system mailbox when <b>-f</b> is specified. The meaning of the <i>file</i> operand +shall be affected by the contents of the <b>folder</b> internal variable; see <a href="#tag_20_75_13_02">Internal Variables in +mailx</a> . <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_75_06" id="tag_20_75_06"></a>STDIN</h4> +<blockquote> +<p>When <i>mailx</i> is invoked in Send Mode (the first synopsis line), standard input shall be the message to be delivered to the +specified addresses. <sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> When in Receive Mode, user commands shall be accepted from <i>stdin</i>. <img src= +"../images/opt-end.gif" alt="[Option End]" border="0"> If the User Portability Utilities option is not supported, standard +input lines beginning with a <tilde> (<tt>'~'</tt>) character produce unspecified results.</p> +<p><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> If +the User Portability Utilities option is supported, then in both Send and Receive Modes, standard input lines beginning with the +escape character (usually <tilde> (<tt>'~'</tt>)) shall affect processing as described in <a href="#tag_20_75_13_48">Command +Escapes in mailx</a> . <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_75_07" id="tag_20_75_07"></a>INPUT FILES</h4> +<blockquote> +<p>When <i>mailx</i> is used as described by this volume of POSIX.1-2024, the <i>file</i> operand (see the <b>-f</b> option) and +the <b>mbox</b> shall be text files containing mail messages, formatted as described in the OUTPUT FILES section. The nature of the +system mailbox is unspecified; it need not be a file.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_75_08" id="tag_20_75_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Some of the functionality described in this section shall be provided on implementations that support the User Portability +Utilities option as described in the text, and is not further shaded for this option. <img src="../images/opt-end.gif" alt= +"[Option End]" border="0"></p> +<p>The following environment variables shall affect the execution of <i>mailx</i>:</p> +<dl compact> +<dd></dd> +<dt><i>DEAD</i></dt> +<dd>Determine the pathname of the file in which to save partial messages in case of interrupts or delivery errors. The default +shall be <b>dead.letter</b> in the directory named by the <i>HOME</i> variable. The behavior of <i>mailx</i> in saving partial +messages is unspecified if the User Portability Utilities option is not supported and <i>DEAD</i> is not defined with the value +<b>/dev/null</b>.</dd> +<dt><i>EDITOR</i></dt> +<dd>Determine the name of a utility to invoke when the <b>edit</b> (see <a href="#tag_20_75_13_03">Commands in mailx</a> ) or +<b>~e</b> (see <a href="#tag_20_75_13_48">Command Escapes in mailx</a> ) command is used. The default editor is unspecified. +<sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> + On XSI-conformant systems it is <a href="../utilities/ed.html"><i>ed</i></a>. <img src="../images/opt-end.gif" alt= +"[Option End]" border="0"> The effects of this variable are unspecified if the User Portability Utilities option is not +supported.</dd> +<dt><i>HOME</i></dt> +<dd>Determine the pathname of the user's home directory.</dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files) and the handling of case-insensitive address and header field name +comparisons.</dd> +<dt><i>LC_TIME</i></dt> +<dd>This variable may determine the format and contents of the date and time strings written by <i>mailx</i>. This volume of +POSIX.1-2024 specifies the effects of this variable only for systems supporting the User Portability Utilities option.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error and +informative messages written to standard output.</dd> +<dt><i>LISTER</i></dt> +<dd>Determine a string representing the command for writing the contents of the <b>folder</b> directory to standard output when the +<b>folders</b> command is given (see <b>folders</b> in <a href="#tag_20_75_13_03">Commands in mailx</a> ). Any string acceptable as +a <i>command_string</i> operand to the <a href="../utilities/sh.html"><i>sh</i></a> <b>-c</b> command shall be valid. If this +variable is null or not set, the output command shall be <a href="../utilities/ls.html"><i>ls</i></a>. The effects of this variable +are unspecified if the User Portability Utilities option is not supported.</dd> +<dt><i>MAILRC</i></dt> +<dd>Determine the pathname of the user start-up file. The default shall be <b>.mailrc</b> in the directory referred to by the +<i>HOME</i> environment variable. The behavior of <i>mailx</i> is unspecified if the User Portability Utilities option is not +supported and <i>MAILRC</i> is not defined with the value <b>/dev/null</b>.</dd> +<dt><i>MBOX</i></dt> +<dd>Determine a pathname of the file to save messages from the system mailbox that have been read. The <b>exit</b> command shall +override this function, as shall saving the message explicitly in another file. The default shall be <b>mbox</b> in the directory +named by the <i>HOME</i> variable. The effects of this variable are unspecified if the User Portability Utilities option is not +supported.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>PAGER</i></dt> +<dd>Determine a string representing an output filtering or pagination command for writing the output to the terminal. Any string +acceptable as a <i>command_string</i> operand to the <a href="../utilities/sh.html"><i>sh</i></a> <b>-c</b> command shall be valid. +When standard output is a terminal device, the message output shall be piped through the command if the <i>mailx</i> internal +variable <b>crt</b> is set to a value less than the total number of lines in the message; see <a href="#tag_20_75_13_02">Internal +Variables in mailx</a> . When standard output is not a terminal device, it is unspecified whether the message output is written +directly to standard output or is subject to pagination. If the <i>PAGER</i> variable is null or not set, the paginator shall be +either <a href="../utilities/more.html"><i>more</i></a> or another paginator utility documented in the system documentation. The +effects of this variable are unspecified if the User Portability Utilities option is not supported.</dd> +<dt><i>SHELL</i></dt> +<dd>Determine the name of a preferred command interpreter. The default shall be <a href="../utilities/sh.html"><i>sh</i></a>. The +effects of this variable are unspecified if the User Portability Utilities option is not supported.</dd> +<dt><i>TERM</i></dt> +<dd>If the internal variable <b>screen</b> is not specified, determine the name of the terminal type to indicate in an unspecified +manner the number of lines in a screenful of header summaries. If <i>TERM</i> is not set or is set to null, an unspecified default +terminal type shall be used and the value of a screenful is unspecified. The effects of this variable are unspecified if the User +Portability Utilities option is not supported.</dd> +<dt><i>TZ</i></dt> +<dd>This variable may determine the timezone used to calculate date and time strings written by <i>mailx</i>. If <i>TZ</i> is unset +or null, an unspecified default timezone shall be used.</dd> +<dt><i>VISUAL</i></dt> +<dd>Determine a pathname of a utility to invoke when the <b>visual</b> command (see <a href="#tag_20_75_13_03">Commands in +mailx</a> ) or <b>~v</b> command-escape (see <a href="#tag_20_75_13_48">Command Escapes in mailx</a> ) is used. If this variable is +null or not set, the full-screen editor shall be <a href="../utilities/vi.html"><i>vi</i></a>. The effects of this variable are +unspecified if the User Portability Utilities option is not supported.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_75_09" id="tag_20_75_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>When <i>mailx</i> is in Send Mode and standard input is not a terminal, it shall take the standard action for all signals.</p> +<p>In <sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> + Receive Mode, or in <img src="../images/opt-end.gif" alt="[Option End]" border="0"> Send Mode when standard input is a +terminal, if a SIGINT signal is received:</p> +<ol> +<li> +<p><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> If +in command mode, the current command, if there is one, shall be aborted, and a command-mode prompt shall be written. <img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></p> +</li> +<li> +<p>If in input mode:</p> +<ol type="a"> +<li> +<p><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> If +<b>ignore</b> is set, <i>mailx</i> shall write <tt>"@\n"</tt>, discard the current input line, and continue processing, bypassing +the message-abort mechanism described in item 2b. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p> +</li> +<li> +<p>If the interrupt was received while sending mail, either when in <sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> +<img src="../images/opt-start.gif" alt="[Option Start]" border="0"> Receive Mode or in <img src="../images/opt-end.gif" alt= +"[Option End]" border="0"> Send Mode, a message shall be written, and another subsequent interrupt, with no other intervening +characters typed, shall be required to abort the mail message. <sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src= +"../images/opt-start.gif" alt="[Option Start]" border="0"> If in Receive Mode and another interrupt is received, a +command-mode prompt shall be written. <img src="../images/opt-end.gif" alt="[Option End]" border="0"> If in Send Mode and +another interrupt is received, <i>mailx</i> shall terminate with a non-zero status.</p> +<p>In both cases listed in item b, if the message is not empty:</p> +<ol type="i"> +<li> +<p><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> If +<b>save</b> is enabled and the file named by <i>DEAD</i> can be created, the message shall be written to the file named by <i>DEAD +.</i> If the file exists, the message shall be written to replace the contents of the file. <img src="../images/opt-end.gif" alt= +"[Option End]" border="0"></p> +</li> +<li> +<p>If <sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +<b>save</b> is not enabled, or <img src="../images/opt-end.gif" alt="[Option End]" border="0"> the file named by <i>DEAD</i> +cannot be created, the message shall not be saved.</p> +</li> +</ol> +</li> +</ol> +</li> +</ol> +<p>The <i>mailx</i> utility shall take the standard action for all other signals.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_75_10" id="tag_20_75_10"></a>STDOUT</h4> +<blockquote> +<p>In command and input modes, all output, including prompts and messages, shall be written to standard output.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_75_11" id="tag_20_75_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_75_12" id="tag_20_75_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>Various <i>mailx</i> commands and command escapes can create or add to files, including the <b>mbox</b>, the dead-letter file, +and secondary mailboxes. When <i>mailx</i> is used as described in this volume of POSIX.1-2024, these files shall be text files, +formatted as follows:</p> +<blockquote><tt>line beginning with</tt> <b>From<space><br> +[</b><tt>one or more</tt> <i>header fields</i>; see <a href="#tag_20_75_13_03">Commands in mailx</a> ]<br> +<i>empty line<br></i> <b>[</b><tt>zero or more</tt> <i>body lines<br> +empty line]<br></i> <b>[</b><tt>line beginning with</tt> <b>From<space>...]</b></blockquote> +<p>where each message begins with the <b>From <space></b> line shown, preceded by the beginning of the file or an empty +line. (The <b>From <space></b> line is considered to be part of the message header, but not one of the header fields referred +to in <a href="#tag_20_75_13_03">Commands in mailx</a> ; thus, it shall not be affected by the <b>discard</b>, <b>ignore</b>, or +<b>retain</b> commands.) The formats of the remainder of the <b>From <space></b> line and any additional header lines are +unspecified, except that none shall be empty. The format of a message body line is also unspecified, except that no line following +an empty line shall start with <b>From <space></b>; <i>mailx</i> shall modify any such user-entered message body lines +(following an empty line and beginning with <b>From <space></b>) by adding one or more characters to precede the +<tt>'F'</tt>; it may add these characters to <b>From <space></b> lines that are not preceded by an empty line.</p> +<p>When a message from the system mailbox or entered by the user is not a text file, it is implementation-defined how such a +message is stored in files written by <i>mailx</i>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_75_13" id="tag_20_75_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> The +functionality in the entire EXTENDED DESCRIPTION section shall be provided on implementations supporting the User Portability +Utilities option. The functionality described in this section shall be provided on implementations that support the User +Portability Utilities option (and the rest of this section is not further shaded for this option). <img src="../images/opt-end.gif" +alt="[Option End]" border="0"></p> +<p>The <i>mailx</i> utility need not support for all character encodings in all circumstances. For example, inter-system mail may +be restricted to 7-bit data by the underlying network, 8-bit data need not be portable to non-internationalized systems, and so on. +Under these circumstances, it is recommended that only characters defined in the ISO/IEC 646:1991 standard International +Reference Version (equivalent to ASCII) 7-bit range of characters be used.</p> +<p>When <i>mailx</i> is invoked using one of the Receive Mode synopsis forms, it shall write a page of header-summary lines (if +<b>-N</b> was not specified and there are messages, see below), followed by a prompt indicating that <i>mailx</i> can accept +regular commands (see <a href="#tag_20_75_13_03">Commands in mailx</a> ); this is termed <i>command mode</i>. The page of +header-summary lines shall contain the first new message if there are new messages, or the first unread message if there are unread +messages, or the first message. When <i>mailx</i> is invoked using the Send Mode synopsis and standard input is a terminal, if no +subject is specified on the command line and the <b>asksub</b> variable is set, a prompt for the subject shall be written. At this +point, <i>mailx</i> shall be in input mode. This input mode shall also be entered when using one of the Receive Mode synopsis forms +and a reply or new message is composed using the <b>reply</b>, <b>Reply</b>, <b>followup</b>, <b>Followup</b>, or <b>mail</b> +commands and standard input is a terminal. When the message is typed and the end of the message is encountered, the message shall +be passed to the mail delivery software. Commands can be entered by beginning a line with the escape character (by default, +<tilde> (<tt>'~'</tt>)) followed by a single command letter and optional arguments. See <a href="#tag_20_75_13_03">Commands +in mailx</a> for a summary of these commands. It is unspecified what effect these commands will have if standard input is not a +terminal when a message is entered using either the Send Mode synopsis, or the Read Mode commands <b>reply</b>, <b>Reply</b>, +<b>followup</b>, <b>Followup</b>, or <b>mail</b>. <basefont size="2"></p> +<dl> +<dt><b>Note:</b></dt> +<dd>For notational convenience, this section uses the default escape character, <tilde>, in all references and examples.</dd> +</dl> +<basefont size="3"> +<p>At any time, the behavior of <i>mailx</i> shall be governed by a set of environmental and internal variables. These are flags +and valued parameters that can be set and cleared via the <i>mailx</i> <b>set</b> and <b>unset</b> commands.</p> +<p>Regular commands are of the form:</p> +<pre> +<b>[</b><i>command</i><b>] [</b><i>msglist</i><b>] [</b><i>argument </i><tt>...</tt><b>] +</b></pre> +<p>If no <i>command</i> is specified in command mode, <b>next</b> shall be assumed. In input mode, commands shall be recognized by +the escape character, and lines not treated as commands shall be taken as input for the message.</p> +<p>In command mode, each message shall be assigned a sequential number, starting with 1.</p> +<p>All messages have a state that shall affect how they are displayed in the header summary and how they are retained or deleted +upon termination of <i>mailx</i>. There is at any time the notion of a <i>current</i> message, which shall be marked by a +<tt>'>'</tt> at the beginning of a line in the header summary. When <i>mailx</i> is invoked using one of the Receive Mode +synopsis forms, the current message shall be the first new message, if there is a new message, or the first unread message if there +is an unread message, or the first message if there are any messages, or unspecified if there are no messages in the mailbox. Each +command that takes an optional list of messages (<i>msglist</i>) or an optional single message (<i>message</i>) on which to operate +shall leave the current message set to the highest-numbered message of the messages specified, unless the command deletes messages, +in which case the current message shall be set to the first undeleted message (that is, a message not in the deleted state) after +the highest-numbered message deleted by the command, if one exists, or the first undeleted message before the highest-numbered +message deleted by the command, if one exists, or to an unspecified value if there are no remaining undeleted messages. All +messages shall be in one of the following states:</p> +<dl compact> +<dd></dd> +<dt><i>new</i></dt> +<dd>The message is present in the system mailbox and has not been viewed by the user or moved to any other state. Messages in state +<i>new</i> when <i>mailx</i> quits shall be retained in the system mailbox.</dd> +<dt><i>unread</i></dt> +<dd>The message has been present in the system mailbox for more than one invocation of <i>mailx</i> and has not been viewed by the +user or moved to any other state. Messages in state <i>unread</i> when <i>mailx</i> quits shall be retained in the system +mailbox.</dd> +<dt><i>read</i></dt> +<dd>The message has been processed by one of the following commands: <b>~f</b>, <b>~m</b>, <b>~F</b>, <b>~M</b>, <b>copy</b>, +<b>mbox</b>, <b>next</b>, <b>pipe</b>, <b>print</b>, <b>Print</b>, <b>top</b>, <b>type</b>, <b>Type</b>, <b>undelete</b>. The +<b>dp</b> and <b>dt</b> commands shall also cause the message they write, if any, to be marked as <i>read</i>. If the +<b>autoprint</b> variable is set, the <b>delete</b> command shall also cause the message it writes, if any, to be marked as +<i>read</i>. Messages that are in the system mailbox and in state <i>read</i> when <i>mailx</i> quits shall be saved in the +<b>mbox</b>, unless the internal variable <b>hold</b> was set. Messages that are in the <b>mbox</b> or in a secondary mailbox and +in state <i>read</i> when <i>mailx</i> quits shall be retained in their current location.</dd> +<dt><i>deleted</i></dt> +<dd>The message has been processed by one of the following commands: <b>delete</b>, <b>dp</b>, <b>dt</b>. Messages in state +<i>deleted</i> when <i>mailx</i> quits shall be deleted. Deleted messages shall be ignored until <i>mailx</i> quits or changes +mailboxes or they are specified to the undelete command; for example, the message specification /<i>string</i> shall only search +the <b>Subject</b> header fields of messages that have not yet been deleted, unless the command operating on the list of messages +is <b>undelete</b>. No deleted message or deleted message header shall be displayed by any <i>mailx</i> command other than +<b>undelete</b>.</dd> +<dt><i>preserved</i></dt> +<dd>The message has been processed by a <b>preserve</b> command. When <i>mailx</i> quits, the message shall be retained in its +current location.</dd> +<dt><i>saved</i></dt> +<dd>The message has been processed by one of the following commands: <b>save</b> or <b>write</b>. If the current mailbox is the +system mailbox, and the internal variable <b>keepsave</b> is set, messages in the state saved shall be saved to the file designated +by the <i>MBOX</i> variable (see the ENVIRONMENT VARIABLES section). If the current mailbox is the system mailbox, messages in the +state <i>saved</i> shall be deleted from the current mailbox, when the <b>quit</b> or <b>file</b> command is used to exit the +current mailbox.</dd> +</dl> +<p>The header-summary line for each message shall indicate the state of the message.</p> +<p>Many commands take an optional list of messages (<i>msglist</i>) on which to operate, which defaults to the current message. A +<i>msglist</i> is a list of message specifications separated by <blank> characters, which can include:</p> +<dl compact> +<dd></dd> +<dt><tt>n</tt></dt> +<dd>Message number <i>n</i>.</dd> +<dt><tt>+</tt></dt> +<dd>The next undeleted message, or the next deleted message for the <b>undelete</b> command.</dd> +<dt><tt>-</tt></dt> +<dd>The next previous undeleted message, or the next previous deleted message for the <b>undelete</b> command.</dd> +<dt><tt>.</tt></dt> +<dd>The current message.</dd> +<dt><tt>^</tt></dt> +<dd>The first undeleted message, or the first deleted message for the <b>undelete</b> command.</dd> +<dt><tt>$</tt></dt> +<dd>The last message.</dd> +<dt><tt>*</tt></dt> +<dd>All messages.</dd> +<dt><tt>n-m</tt></dt> +<dd>An inclusive range of message numbers.</dd> +<dt><i>address</i></dt> +<dd>All messages from <i>address</i>; any address as shown in a header summary shall be matchable in this form.</dd> +<dt>/<i>string</i></dt> +<dd>All messages with <i>string</i> in the <b>Subject</b> header field (case ignored).</dd> +<dt><tt>:c</tt></dt> +<dd>All messages of type <i>c</i>, where <i>c</i> shall be one of: +<dl compact> +<dd></dd> +<dt><tt>d</tt></dt> +<dd>Deleted messages.</dd> +<dt><tt>n</tt></dt> +<dd>New messages.</dd> +<dt><tt>o</tt></dt> +<dd>Old messages (any not in state <i>read</i> or <i>new</i>).</dd> +<dt><tt>r</tt></dt> +<dd>Read messages.</dd> +<dt><tt>u</tt></dt> +<dd>Unread messages.</dd> +</dl> +</dd> +</dl> +<p>Other commands take an optional message (<i>message</i>) on which to operate, which defaults to the current message. All of the +forms allowed for <i>msglist</i> are also allowed for <i>message</i>, but if more than one message is specified, only the first +shall be operated on.</p> +<p>Other arguments are usually arbitrary strings whose usage depends on the command involved.</p> +<h5><a name="tag_20_75_13_01" id="tag_20_75_13_01"></a>Start-Up in mailx</h5> +<p>At start-up time, <i>mailx</i> shall take the following steps in sequence:</p> +<ol> +<li> +<p>Establish all variables at their stated default values.</p> +</li> +<li> +<p>Process command line options, overriding corresponding default values.</p> +</li> +<li> +<p>Import any of the <i>DEAD ,</i> <i>EDITOR ,</i> <i>MBOX ,</i> <i>LISTER ,</i> <i>PAGER ,</i> <i>SHELL ,</i> or <i>VISUAL</i> +variables that are present in the environment, overriding the corresponding default values.</p> +</li> +<li> +<p>Read <i>mailx</i> commands from an unspecified system start-up file, unless the <b>-n</b> option is given, to initialize any +internal <i>mailx</i> variables and aliases.</p> +</li> +<li> +<p>Process the user start-up file of <i>mailx</i> commands named in the user <i>MAILRC</i> variable.</p> +</li> +</ol> +<p>Most regular <i>mailx</i> commands are valid inside start-up files, the most common use being to set up initial display options +and alias lists. The following commands shall be invalid in a start-up file: <b>!</b>, <b>edit</b>, <b>hold</b>, <b>mail</b>, +<b>preserve</b>, <b>reply</b>, <b>Reply</b>, <b>Save</b>, <b>shell</b>, <b>visual</b>, <b>Copy</b>, <b>followup</b>, and +<b>Followup</b>. Any errors in a start-up file shall either cause <i>mailx</i> to terminate with a diagnostic message and a +non-zero status or to continue after writing a diagnostic message, ignoring the remainder of the lines in the file.</p> +<p>A blank line in a start-up file shall be ignored.</p> +<h5><a name="tag_20_75_13_02" id="tag_20_75_13_02"></a>Internal Variables in mailx</h5> +<p>The following variables are internal <i>mailx</i> variables. Each internal variable can be set via the <i>mailx</i> <b>set</b> +command at any time. The <b>unset</b> and <b>set no</b><i>name</i> commands can be used to erase variables.</p> +<p>In the following list, variables shown as:</p> +<pre> +<tt>variable +</tt></pre> +<p>represent Boolean values. Variables shown as:</p> +<pre> +<tt>variable=</tt><i>value</i><tt> +</tt></pre> +<p>shall be assigned string or numeric values. For string values, the rules in <a href="#tag_20_75_13_03">Commands in mailx</a> +concerning filenames and quoting shall also apply.</p> +<p>The defaults specified here may be changed by the unspecified system start-up file unless the user specifies the <b>-n</b> +option.</p> +<dl compact> +<dd></dd> +<dt><b>allnet</b></dt> +<dd>All network names whose login name components match shall be treated as identical. This shall cause the <i>msglist</i> message +specifications to behave similarly. The default shall be <b>noallnet</b>. See also the <b>alternates</b> command and the +<b>metoo</b> variable.</dd> +<dt><b>append</b></dt> +<dd>Append messages to the end of the <b>mbox</b> file upon termination instead of placing them at the beginning. The default shall +be <b>noappend</b>. This variable shall not affect the <b>save</b> command when saving to <b>mbox</b>.</dd> +<dt><b>ask</b>, <b>asksub</b></dt> +<dd>Prompt for a value for the <b>Subject</b> header field on outgoing mail if one is not specified on the command line with the +<b>-s</b> option. The <b>ask</b> and <b>asksub</b> forms are synonyms; the system shall refer to <b>asksub</b> and <b>noasksub</b> +in its messages, but shall accept <b>ask</b> and <b>noask</b> as user input to mean <b>asksub</b> and <b>noasksub</b>. It shall not +be possible to set both <b>ask</b> and <b>noasksub</b>, or <b>noask</b> and <b>asksub</b>. The default shall be <b>asksub</b>, but +no prompting shall be done if standard input is not a terminal.</dd> +<dt><b>askbcc</b></dt> +<dd>Prompt for the blind copy list. The default shall be <b>noaskbcc</b>.</dd> +<dt><b>askcc</b></dt> +<dd>Prompt for the copy list. The default shall be <b>noaskcc</b>.</dd> +<dt><b>autoprint</b></dt> +<dd>Enable automatic writing of messages after <b>delete</b> and <b>undelete</b> commands. The default shall be +<b>noautoprint</b>.</dd> +<dt><b>bang</b></dt> +<dd>Enable the special-case treatment of <exclamation-mark> characters (<tt>'!'</tt>) in <b>!</b> commands and +<b>~!</b><i>command</i> escapes; see the <b>Invoke Shell Command</b> command and <a href="#tag_20_75_13_48">Command Escapes in +mailx</a> . The default shall be <b>nobang</b>, disabling the expansion of <tt>'!'</tt> in the <i>command</i> argument to the +<b>!</b> command and the <b>~!</b><i>command</i> escape.</dd> +<dt><b>cmd</b>=<i>command</i></dt> +<dd><br> +Set the default command to be invoked by the <b>pipe</b> command. The default shall be <b>nocmd</b>.</dd> +<dt><b>crt</b>=<i>number</i></dt> +<dd>Paginate message output as described for the <i>PAGER</i> variable. The default shall be <b>nocrt</b>, disabling this +pagination. If it is set to null, the value used is implementation-defined.</dd> +<dt><b>debug</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Enable verbose diagnostics for debugging. Messages are not delivered. The default shall be <b>nodebug</b>. <img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>dot</b></dt> +<dd>When <b>dot</b> is set, a <period> on a line by itself during message input from a terminal shall also signify +end-of-file (in addition to normal end-of-file). The default shall be <b>nodot</b>. If <b>ignoreeof</b> is set (see below), a +setting of <b>nodot</b> shall be ignored and <period> and the <b>~.</b> command escape are the only methods to terminate +input mode.</dd> +<dt><b>escape</b>=<i>c</i></dt> +<dd>Set the command escape character to be the character <tt>'c'</tt>. By default, the command escape character shall be +<tilde>. If <b>escape</b> is unset, <tilde> shall be used; if it is set to null, command escaping shall be +disabled.</dd> +<dt><b>flipr</b></dt> +<dd>Reverse the meanings of the <b>R</b> and <b>r</b> commands. The default shall be <b>noflipr</b>.</dd> +<dt><b>folder</b>=<i>directory</i></dt> +<dd><br> +The default directory for saving mail files. User-specified filenames beginning with a <plus-sign> (<tt>'+'</tt>) shall be +expanded by preceding the filename with this directory name to obtain the real pathname. If <i>directory</i> does not start with a +<slash> (<tt>'/'</tt>), the contents of <i>HOME</i> shall be prefixed to it. The default shall be <b>nofolder</b>. If +<b>folder</b> is unset, user-specified filenames beginning with <tt>'+'</tt> shall refer to files in the current directory that +begin with the literal <tt>'+'</tt> character. See also <b>outfolder</b> below. The <b>folder</b> value need not affect the +processing of the files named in <i>MBOX</i> and <i>DEAD .</i></dd> +<dt><b>header</b></dt> +<dd>Enable writing of the header summary when entering <i>mailx</i> in Receive Mode. The default shall be <b>header</b>.</dd> +<dt><b>hold</b></dt> +<dd>Disable message moving of read messages from the system mailbox to the <b>mbox</b> save file upon normal program termination or +folder change. This automatic mail management is complemented with the commands <b>hold</b> (and <b>preserve</b>), <b>mbox</b>, and +<b>touch</b>, which partially override the <b>hold</b> variable. The default shall be <b>nohold</b>.</dd> +<dt><b>ignore</b></dt> +<dd>Ignore interrupts while entering messages. The default shall be <b>noignore</b>.</dd> +<dt><b>ignoreeof</b></dt> +<dd>Ignore normal end-of-file during message input. Input can be terminated only by entering a <period> (<tt>'.'</tt>) on a +line by itself or by the <b>~.</b> command escape. The default shall be <b>noignoreeof</b>. See also <b>dot</b> above.</dd> +<dt><b>indentprefix</b>=<i>string</i></dt> +<dd><br> +A string that shall be added as a prefix to each line that is inserted into the message by the <b>~m</b> command escape. This +variable shall default to one <tab>.</dd> +<dt><b>keep</b></dt> +<dd>When a system mailbox, secondary mailbox, or <b>mbox</b> is empty, truncate it to zero length instead of removing it. The +default shall be <b>nokeep</b>.</dd> +<dt><b>keepsave</b></dt> +<dd>Keep the messages that have been saved from the system mailbox into other files in the file designated by the variable <i>MBOX +,</i> instead of deleting them. The default shall be <b>nokeepsave</b>.</dd> +<dt><b>metoo</b></dt> +<dd>Suppress the deletion of the user's login name from the recipient list when replying to a message or sending to a group. The +default shall be <b>nometoo</b>.</dd> +<dt><b>onehop</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +When responding to a message that was originally sent to several recipients, the other recipient addresses are normally forced to +be relative to the originating author's machine for the response. This flag disables alteration of the recipients' addresses, +improving efficiency in a network where all machines can send directly to all other machines (that is, one hop away). The default +shall be <b>noonehop</b>. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>outfolder</b></dt> +<dd>Cause the files used to record outgoing messages to be located in the directory specified by the <b>folder</b> variable unless +the pathname is absolute. The default shall be <b>nooutfolder</b>. See the <b>record</b> variable.</dd> +<dt><b>page</b></dt> +<dd>Insert a <form-feed> after each message sent through the pipe created by the <b>pipe</b> command. The default shall be +<b>nopage</b>.</dd> +<dt><b>prompt</b>=<i>string</i></dt> +<dd><br> +Set the command-mode prompt to <i>string</i>. If <i>string</i> is null or if <b>noprompt</b> is set, no prompting shall occur. The +default shall be to prompt with the string <tt>"? "</tt>.</dd> +<dt><b>quiet</b></dt> +<dd>Refrain from writing the opening message and version when entering <i>mailx</i>. The default shall be <b>noquiet</b>.</dd> +<dt><b>record</b>=<i>file</i></dt> +<dd>Record all outgoing mail in the file with the pathname <i>file</i>. The default shall be <b>norecord</b>. See also +<b>outfolder</b> above.</dd> +<dt><b>save</b></dt> +<dd>Enable saving of messages in the dead-letter file on interrupt or delivery error. See the variable <i>DEAD</i> for the location +of the dead-letter file. The default shall be <b>save</b>.</dd> +<dt><b>screen</b>=<i>number</i></dt> +<dd><br> +Set the number of lines in a screenful of headers for the <b>headers</b> and <b>z</b> commands. If <b>screen</b> is not specified, +a value based on the terminal type identified by the <i>TERM</i> environment variable, the window size, the baud rate, or some +combination of these shall be used. The default shall be <b>noscreen</b>.</dd> +<dt><b>sendwait</b></dt> +<dd>Wait for the background mailer to finish before returning. The default shall be <b>nosendwait</b>.</dd> +<dt><b>showto</b></dt> +<dd>When the sender of the message was the user who is invoking <i>mailx</i>, write the information from the <b>To</b> field +instead of the <b>From</b> field in the header summary. The default shall be <b>noshowto</b>.</dd> +<dt><b>sign</b>=<i>string</i></dt> +<dd>Set the variable inserted into the text of a message when the <b>~a</b> command escape is given. The default shall be +<b>nosign</b>. The character sequences <tt>'\t'</tt> and <tt>'\n'</tt> shall be recognized in the variable as <tab> and +<newline> characters, respectively. (See also <b>~i</b> in <a href="#tag_20_75_13_48">Command Escapes in mailx</a> .)</dd> +<dt><b>Sign</b>=<i>string</i></dt> +<dd>Set the variable inserted into the text of a message when the <b>~A</b> command escape is given. The default shall be +<b>noSign</b>. The character sequences <tt>'\t'</tt> and <tt>'\n'</tt> shall be recognized in the variable as <tab> and +<newline> characters, respectively.</dd> +<dt><b>toplines</b>=<i>number</i></dt> +<dd><br> +Set the number of lines of the message to write with the <b>top</b> command. The default shall be 5.</dd> +</dl> +<h5><a name="tag_20_75_13_03" id="tag_20_75_13_03"></a>Commands in mailx</h5> +<p>The following <i>mailx</i> commands shall be provided. In the following list, <i>header</i> refers to lines from the message +header, as shown in the OUTPUT FILES section. <i>Header field</i> refers to a line or set of lines within the header that begins +with one or more non-white-space characters immediately followed by a <colon> and white space, and continuing up to and +including a <newline> that immediately precedes either the next line beginning with a non-white-space character or an empty +line. <i>Field name</i> refers to the portion of a header field prior to the first <colon>.</p> +<p>For each of the commands listed below, the command can be entered as the abbreviation (those characters in the Synopsis command +word preceding the <tt>'['</tt>), the full command (all characters shown for the command word, omitting the <tt>'['</tt> and +<tt>']'</tt>), or any truncation of the full command down to the abbreviation. For example, the <b>exit</b> command (shown as +<b>ex[it]</b> in the Synopsis) can be entered as <b>ex</b>, <b>exi</b>, or <b>exit</b>.</p> +<p>The arguments to commands can be quoted, using the following methods:</p> +<ul> +<li> +<p>An argument can be enclosed between paired double-quotes (<tt>""</tt>) or single-quotes (<tt>''</tt>); any white space, shell +word expansion, or <backslash> characters within the quotes shall be treated literally as part of the argument. A +double-quote shall be treated literally within single-quotes and <i>vice versa</i>. These special properties of the +<quotation-mark> characters shall occur only when they are paired at the beginning and end of the argument.</p> +</li> +<li> +<p>A <backslash> outside of the enclosing quotes shall be discarded and the following character treated literally as part of +the argument.</p> +</li> +<li> +<p>An unquoted <backslash> at the end of a command line shall be discarded and the next line shall continue the command.</p> +</li> +</ul> +<br> +<p>Filenames, where expected, shall be subjected to the following transformations, in sequence:</p> +<ul> +<li> +<p>If the filename begins with an unquoted <plus-sign>, and the <b>folder</b> variable is defined (see the <b>folder</b> +variable), the <plus-sign> shall be replaced by the value of the <b>folder</b> variable followed by a <slash>. If the +<b>folder</b> variable is unset or is set to null, the filename shall be unchanged.</p> +</li> +<li> +<p>Shell word expansions shall be applied to the filename (see <a href="../utilities/V3_chap02.html#tag_19_06"><i>2.6 Word +Expansions</i></a> ). If more than a single pathname results from this expansion and the command is expecting one file, the effects +are unspecified.</p> +</li> +</ul> +<h5><a name="tag_20_75_13_04" id="tag_20_75_13_04"></a>Declare Aliases</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>a</tt><b>[</b><tt>lias</tt><b>] [</b><i>alias </i><b>[</b><i>address</i><tt>...</tt><b>]]</b><tt> +g</tt><b>[</b><tt>roup</tt><b>] [</b><i>alias </i><b>[</b><i>address</i><tt>...</tt><b>]]</b><tt> +</tt></pre></dd> +</dl> +<p>Add the given addresses to the alias specified by <i>alias</i>. The names shall be substituted when <i>alias</i> is used as a +recipient address specified by the user in an outgoing message (that is, other recipients addressed indirectly through the +<b>reply</b> command shall not be substituted in this manner). Mail address alias substitution shall apply only when the alias +string is used as a full address; for example, when <b>hlj</b> is an alias, <i>hlj@posix.com</i> does not trigger the alias +substitution. Recursive expansion of an alias group member can be prevented by prefixing it with an unquoted <backslash>. If +no arguments are given, write a listing of the current aliases to standard output. If only an <i>alias</i> argument is given, write +a listing of the specified alias to standard output. These listings need not reflect the same order of addresses that were +entered.</p> +<h5><a name="tag_20_75_13_05" id="tag_20_75_13_05"></a>Declare Alternatives</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>alt</tt><b>[</b><tt>ernates</tt><b>] </b><i>name</i><tt>... +</tt></pre></dd> +</dl> +<p>Declare a list of alternative addresses for the address consisting of the user's login name. When responding to a message, these +alternative addresses shall be removed from the list of recipients. The comparison of addresses shall be performed in a +case-insensitive manner. With no arguments, <b>alternates</b> shall write the current list of alternative addresses.</p> +<h5><a name="tag_20_75_13_06" id="tag_20_75_13_06"></a>Change Current Directory</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>cd </tt><b>[</b><i>directory</i><b>]</b><tt> +ch</tt><b>[</b><tt>dir</tt><b>] [</b><i>directory</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p>Change directory. If <i>directory</i> is not specified, the contents of <i>HOME</i> shall be used.</p> +<h5><a name="tag_20_75_13_07" id="tag_20_75_13_07"></a>Copy Messages</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>c</tt><b>[</b><tt>opy</tt><b>] [</b><i>file</i><b>]</b><tt> +c</tt><b>[</b><tt>opy</tt><b>] [</b><i>msglist</i><b>] </b><i>file</i><tt> +C</tt><b>[</b><tt>opy</tt><b>] [</b><i>msglist</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p>Copy messages to the file named by the pathname <i>file</i> without marking the messages as saved. Otherwise, it shall be +equivalent to the <b>save</b> command.</p> +<p>In the capitalized form, save the specified messages in a file whose name is derived from the author of the message to be saved, +without marking the messages as saved. Otherwise, it shall be equivalent to the <b>Save</b> command.</p> +<h5><a name="tag_20_75_13_08" id="tag_20_75_13_08"></a>Delete Messages</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>d</tt><b>[</b><tt>elete</tt><b>] [</b><i>msglist</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p>Mark messages for deletion from the mailbox. The deletions shall not occur until <i>mailx</i> quits (see the <b>quit</b> +command) or changes mailboxes (see the <b>folder</b> command). If <b>autoprint</b> is set and there are messages remaining after +the <b>delete</b> command, the current message shall be written as described for the <b>print</b> command (see the <b>print</b> +command); otherwise, the <i>mailx</i> prompt shall be written.</p> +<h5><a name="tag_20_75_13_09" id="tag_20_75_13_09"></a>Discard Header Fields</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>di</tt><b>[</b><tt>scard</tt><b>] [</b><i>field-name</i><tt>...</tt><b>]</b><tt> +ig</tt><b>[</b><tt>nore</tt><b>] [</b><i>field-name</i><tt>...</tt><b>]</b><tt> +</tt></pre></dd> +</dl> +<p>Suppress header fields with the specified field names when writing messages. Specified <i>field-name</i> arguments shall be +added to the list of suppressed field names. Examples of field names to ignore are <b>status</b> and <b>cc</b>. The header fields +shall be included when the message is saved. The <b>Print</b> and <b>Type</b> commands shall override this command. The comparison +of field names shall be performed in a case-insensitive manner. If no arguments are specified, write a list of the currently +suppressed field names to standard output; the listing need not reflect the same order of field names that were entered.</p> +<p>If both <b>retain</b> and <b>discard</b> commands are given, <b>discard</b> commands shall be ignored.</p> +<h5><a name="tag_20_75_13_10" id="tag_20_75_13_10"></a>Delete Messages and Display</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>dp </tt><b>[</b><i>msglist</i><b>]</b><tt> +dt </tt><b>[</b><i>msglist</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p>Delete the specified messages as described for the <b>delete</b> command, except that the <b>autoprint</b> variable shall have +no effect, and the current message shall be written only if it was set to a message after the last message deleted by the command. +Otherwise, an informational message to the effect that there are no further messages in the mailbox shall be written, followed by +the <i>mailx</i> prompt.</p> +<h5><a name="tag_20_75_13_11" id="tag_20_75_13_11"></a>Echo a String</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>ec</tt><b>[</b><tt>ho</tt><b>] </b><i>string</i><tt> ... +</tt></pre></dd> +</dl> +<p>Echo the given strings, equivalent to the shell <a href="../utilities/echo.html"><i>echo</i></a> utility.</p> +<h5><a name="tag_20_75_13_12" id="tag_20_75_13_12"></a>Edit Messages</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>e</tt><b>[</b><tt>dit</tt><b>] [</b><i>msglist</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p>Edit the given messages. The messages shall be placed in a temporary file and the utility named by the <i>EDITOR</i> variable is +invoked to edit each file in sequence. The default <i>EDITOR</i> is unspecified.</p> +<p>The <b>edit</b> command does not modify the contents of those messages in the mailbox.</p> +<h5><a name="tag_20_75_13_13" id="tag_20_75_13_13"></a>Exit</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>ex</tt><b>[</b><tt>it</tt><b>]</b><tt> +x</tt><b>[</b><tt>it</tt><b>]</b><tt> +</tt></pre></dd> +</dl> +<p>Exit from <i>mailx</i> without performing automatic message moving, or any other management tasks. See also <b>quit</b>.</p> +<h5><a name="tag_20_75_13_14" id="tag_20_75_13_14"></a>Change Folder</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>fi</tt><b>[</b><tt>le</tt><b>] [</b><i>file</i><b>]</b><tt> +fold</tt><b>[</b><tt>er</tt><b>] [</b><i>file</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p>If no argument is given, write the name and status of the current mailbox. Otherwise, close the current file of messages after +performing actions as specified for the <b>quit</b> command (except for terminating <i>mailx</i>) and then read in the file named +by the pathname <i>file</i>. The behavior is unspecified if <i>file</i> is not a valid <b>mbox</b>.</p> +<p>Several unquoted special characters shall be recognized when used as <i>file</i> names, with the following substitutions:</p> +<dl compact> +<dd></dd> +<dt><tt>%</tt></dt> +<dd>The system mailbox for the invoking user.</dd> +<dt><tt>%</tt><i>user</i></dt> +<dd>The system mailbox for <i>user</i>.</dd> +<dt><tt>#</tt></dt> +<dd>The previous file.</dd> +<dt><tt>&</tt></dt> +<dd>The current <b>mbox</b>.</dd> +<dt><tt>+</tt><i>file</i></dt> +<dd>The named file in the <b>folder</b> directory. (See the <b>folder</b> variable.)</dd> +</dl> +<p>The default file shall be the current mailbox.</p> +<h5><a name="tag_20_75_13_15" id="tag_20_75_13_15"></a>Display List of Folders</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>folders</tt> +</pre></dd> +</dl> +<p>Write the names of the files in the directory set by the <b>folder</b> variable. The command specified by the <i>LISTER</i> +environment variable shall be used (see the ENVIRONMENT VARIABLES section).</p> +<h5><a name="tag_20_75_13_16" id="tag_20_75_13_16"></a>Follow Up Specified Messages</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>fo</tt><b>[</b><tt>llowup</tt><b>] [</b><i>message</i><b>]</b><tt> +F</tt><b>[</b><tt>ollowup</tt><b>] [</b><i>msglist</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p>The <b>followup</b> and <b>Followup</b> commands shall be equivalent to <b>reply</b> and <b>Reply</b>, respectively, except +that:</p> +<ul> +<li> +<p>They shall ignore the <b>record</b> variable.</p> +</li> +<li> +<p>The <b>followup</b> command shall record the response in a file whose name is derived from the author of the <i>message</i>.</p> +</li> +<li> +<p>The <b>Followup</b> command shall record the response in a file whose name is derived from the author of the first message in +the <i>msglist</i>.</p> +</li> +</ul> +<p>See also the <b>save</b> and <b>copy</b> commands and <b>outfolder</b>.</p> +<h5><a name="tag_20_75_13_17" id="tag_20_75_13_17"></a>Display Header Summary for Specified Messages</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>f</tt><b>[</b><tt>rom</tt><b>] [</b><i>msglist</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p>Write the header summary for the specified messages.</p> +<h5><a name="tag_20_75_13_18" id="tag_20_75_13_18"></a>Display Header Summaries</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>h</tt><b>[</b><tt>eaders</tt><b>] [</b><i>message</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p>Write the page of header summaries that includes the message specified. If the <i>message</i> argument is not specified, the +current message shall not change. However, if the <i>message</i> argument is specified, the current message shall become the +message that appears at the top of the page of header summaries that includes the message specified. The <b>screen</b> variable +sets the number of header summaries per page. See also the <b>z</b> command.</p> +<h5><a name="tag_20_75_13_19" id="tag_20_75_13_19"></a>Help</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>hel</tt><b>[</b><tt>p</tt><b>]</b><tt> +? +</tt></pre></dd> +</dl> +<p>Write a summary of commands.</p> +<h5><a name="tag_20_75_13_20" id="tag_20_75_13_20"></a>Hold Messages</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>ho</tt><b>[</b><tt>ld</tt><b>] [</b><i>msglist</i><b>]</b><tt> +pre</tt><b>[</b><tt>serve</tt><b>] [</b><i>msglist</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p>Allowed only in the system mailbox. Mark the messages in <i>msglist</i> to be preserved, as if the <b>hold</b> variable were +set, upon normal termination or when the folder is changed. This shall override any commands that might previously have marked the +messages to be deleted, and only the <b>delete</b>, <b>dp</b>, or <b>dt</b>, as well as the <b>mbox</b> and <b>touch</b> commands, +shall remove the <i>preserve</i> mark of a message.</p> +<h5><a name="tag_20_75_13_21" id="tag_20_75_13_21"></a>Execute Commands Conditionally</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>i</tt><b>[</b><tt>f</tt><b>]</b><tt> s|r +</tt><i>mail-command</i><tt>s +el</tt><b>[</b><tt>se</tt><b>] +</b><i>mail-command</i><tt>s +en</tt><b>[</b><tt>dif</tt><b>]</b><tt> +</tt></pre></dd> +</dl> +<p>Execute commands conditionally, where <b>if s</b> executes the following <i>mail-command</i>s, up to an <b>else</b> or +<b>endif</b>, if the program is in Send Mode, and <b>if r</b> shall cause the <i>mail-command</i>s to be executed only in +Receive Mode.</p> +<h5><a name="tag_20_75_13_22" id="tag_20_75_13_22"></a>List Available Commands</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>l</tt><b>[</b><tt>ist</tt><b>]</b><tt> +</tt></pre></dd> +</dl> +<p>Write a list of all commands available. No explanation shall be given.</p> +<h5><a name="tag_20_75_13_23" id="tag_20_75_13_23"></a>Mail a Message</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>m</tt><b>[</b><tt>ail</tt><b>] </b><i>address</i><tt>... +</tt></pre></dd> +</dl> +<p>Mail a message to the specified addresses or aliases.</p> +<h5><a name="tag_20_75_13_24" id="tag_20_75_13_24"></a>Direct Messages to mbox</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>mb</tt><b>[</b><tt>ox</tt><b>] [</b><i>msglist</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p>Allowed only in the system mailbox. Arrange for the given messages to end up in the secondary mailbox, overriding a possibly set +<b>hold</b> variable, upon normal termination or when the folder is changed. Overrides a former <b>hold</b> or <b>preserve</b> +request. See <i>MBOX</i> in the ENVIRONMENT VARIABLES section. See also the <b>exit</b> and <b>quit</b> commands.</p> +<h5><a name="tag_20_75_13_25" id="tag_20_75_13_25"></a>Process Next Specified Message</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>n</tt><b>[</b><tt>ext</tt><b>] [</b><i>message</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p>If the current message has not been written (for example, by the <b>print</b> command) since <i>mailx</i> started or since any +other message was the current message, behave as if the <b>print</b> command was entered. Otherwise, if there is an undeleted +message after the current message, make it the current message and behave as if the <b>print</b> command was entered. Otherwise, an +informational message to the effect that there are no further messages in the mailbox shall be written, followed by the +<i>mailx</i> prompt. Should the current message location be the result of an immediately preceding <b>hold</b>, <b>mbox</b>, +<b>preserve</b>, or <b>touch</b> command, <b>next</b> shall act as if the current message has already been written.</p> +<h5><a name="tag_20_75_13_26" id="tag_20_75_13_26"></a>Pipe Message</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>pi</tt><b>[</b><tt>pe</tt><b>] [[</b><i>msglist</i><b>] </b><i>command</i><b>]</b><tt> +| </tt><b>[[</b><i>msglist</i><b>] </b><i>command</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p>Pipe the messages through the given <i>command</i> by invoking the command interpreter specified by <i>SHELL</i> with three +arguments: <tt>"-c"</tt>, <tt>"--"</tt>, and <i>command</i>. (See also <a href="../utilities/sh.html"><i>sh</i></a> <b>-c</b>.) The +application shall ensure that the command is given as a single argument. Quoting, described previously, can be used to accomplish +this. If no arguments are given, the current message shall be piped through the command specified by the value of the <b>cmd</b> +variable. If the <b>page</b> variable is set, a <form-feed> shall be inserted after each message.</p> +<h5><a name="tag_20_75_13_27" id="tag_20_75_13_27"></a>Display Message with Header</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>P</tt><b>[</b><tt>rint</tt><b>] [</b><i>msglist</i><b>]</b><tt> +T</tt><b>[</b><tt>ype</tt><b>] [</b><i>msglist</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p>Write the specified messages, including all header fields, to standard output. This command shall override suppression of header +fields by the <b>discard</b>, <b>ignore</b>, and <b>retain</b> commands. If <b>crt</b> is set, the output shall be paginated as +described for the <i>PAGER</i> variable.</p> +<h5><a name="tag_20_75_13_28" id="tag_20_75_13_28"></a>Display Message</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>p</tt><b>[</b><tt>rint</tt><b>] [</b><i>msglist</i><b>]</b><tt> +t</tt><b>[</b><tt>ype</tt><b>] [</b><i>msglist</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p>Write the specified messages to standard output. If <b>crt</b> is set, the output shall be paginated as described for the +<i>PAGER</i> variable.</p> +<h5><a name="tag_20_75_13_29" id="tag_20_75_13_29"></a>Quit</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>q</tt><b>[</b><tt>uit</tt><b>] +</b><i>end-of-file</i><tt> +</tt></pre></dd> +</dl> +<p>Terminate <i>mailx</i> normally, performing automatic message moving as specified in the description of the variable +<b>hold</b>, deleting messages that have been explicitly saved (unless <b>keepsave</b> is set), discarding messages that have been +deleted, and saving all remaining messages in the mailbox.</p> +<h5><a name="tag_20_75_13_30" id="tag_20_75_13_30"></a>Reply to a Message or a Message List</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>r</tt><b>[</b><tt>eply</tt><b>] [</b><i>message</i><b>]</b><tt> +r</tt><b>[</b><tt>espond</tt><b>] [</b><i>message</i><b>]</b><tt> +R</tt><b>[</b><tt>eply</tt><b>] [</b><i>msglist</i><b>]</b><tt> +R</tt><b>[</b><tt>espond</tt><b>] [</b><i>msglist</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p>Mail a reply message to one or more addresses taken from certain header fields in the specified message or message list. If the +<b>flipr</b> variable is unset, these commands shall behave as described below. If the <b>flipr</b> variable is set, commands in +the lowercase form shall behave as described below for commands in the capitalized form, and <i>vice versa</i>; the synopsis forms +shown above shall also be swapped accordingly.</p> +<p>The recipients of the reply message shall be determined by first constructing an initial list of recipients and then modifying +it to form the list that is in effect when <i>mailx</i> enters input mode.</p> +<p>In the capitalized form, the initial list of recipients shall be taken from the header of each message in the <i>msglist</i> as +follows:</p> +<ul> +<li> +<p>If the header contains a <b>Reply-To</b> field, the address or addresses in that field shall be added to the list.</p> +</li> +<li> +<p>Otherwise, the address or addresses in the <b>From</b> field of the header shall be added to the list.</p> +</li> +</ul> +<p>In the lowercase form, the initial list of recipients shall be taken from the header of the <i>message</i> as follows:</p> +<ul> +<li> +<p>If the header does not contain a <b>Reply-To</b> field, all of the addresses in the <b>From</b>, <b>To</b>, and <b>Cc</b> fields +shall be included in the list.</p> +</li> +<li> +<p>Otherwise, it is implementation-defined whether all of the addresses in the <b>Reply-To</b>, <b>To</b>, and <b>Cc</b> fields are +included in the list or only the address or addresses in the <b>Reply-To</b> field.</p> +</li> +</ul> +<p>The initial list of recipients shall be marked for placement in the header fields of the reply message as follows. Recipient +addresses taken from a <b>From</b> or <b>Reply-To</b> header field shall be marked for placement in the <b>To</b> field of the +reply message. Recipient addresses taken from a <b>Cc</b> header field shall be marked for placement in the <b>Cc</b> field of the +reply message. Recipient addresses taken from a <b>To</b> header field shall be marked for placement in either the <b>To</b> or the +<b>Cc</b> field of the reply message. Implementations shall provide a way to place them in the <b>To</b> field. Implementations +may, but need not, provide an implementation-defined way to place them in the <b>Cc</b> field.</p> +<p>The modifications applied to the initial list of recipients shall be as follows:</p> +<ul> +<li> +<p>If the <b>metoo</b> variable is unset, addresses consisting of the login name of the user and any alternative addresses declared +using the <b>alternates</b> command shall be removed from the list.</p> +</li> +<li> +<p>The set of recipients marked for placement in the <b>To</b> header field of the reply message shall have duplicates within that +set removed.</p> +</li> +<li> +<p>The set of recipients marked for placement in the <b>Cc</b> header field of the reply message shall have duplicates within that +set removed and may have recipients that are also marked for placement in the <b>To</b> field removed.</p> +</li> +</ul> +<p>The values for the <b>To</b> and <b>Cc</b> header fields of the reply message shall be constructed from the addresses in the +modified list of recipients that are marked for placement in each of those fields.</p> +<p>The value for the <b>Subject</b> header field of the reply message shall be formed from the value of the <b>Subject</b> header +field of the <i>message</i> or the first message in <i>msglist</i> by prefixing it with <b>Re:</b><space>, unless it already +begins with that string.</p> +<p>The values of the <b>To</b>, <b>Cc</b>, and <b>Subject</b> header fields set as described above can be modified by the user +after <i>mailx</i> enters input mode through the use of the <b>~t</b>, <b>~c</b>, <b>~s</b>, and <b>~h</b> command escapes.</p> +<p>If <b>record</b> is set to a pathname, the response shall be saved at the end of that file.</p> +<h5><a name="tag_20_75_13_31" id="tag_20_75_13_31"></a>Retain Header Fields</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>ret</tt><b>[</b><tt>ain</tt><b>] [</b><i>field-name</i><tt>...</tt><b>]</b><tt> +</tt></pre></dd> +</dl> +<p>Retain header fields with the specified field names when writing messages. This command shall override all <b>discard</b> and +<b>ignore</b> commands. The comparison of field names shall be performed in a case-insensitive manner. If no arguments are +specified, write a list of the currently retained field names to standard output; the listing need not reflect the same order of +field names that were entered.</p> +<h5><a name="tag_20_75_13_32" id="tag_20_75_13_32"></a>Save Messages</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>s</tt><b>[</b><tt>ave</tt><b>] [</b><i>file</i><b>]</b><tt> +s</tt><b>[</b><tt>ave</tt><b>] [</b><i>msglist</i><b>] </b><i>file</i><tt> +S</tt><b>[</b><tt>ave</tt><b>] [</b><i>msglist</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p>Save the specified messages in the file named by the pathname <i>file</i>, or the <b>mbox</b> if the <i>file</i> argument is +omitted. The file shall be created if it does not exist; otherwise, the messages shall be appended to the file. The message shall +be put in the state <i>saved</i>, and shall behave as specified in the description of the <i>saved</i> state when the current +mailbox is exited by the <b>quit</b> or <b>file</b> command.</p> +<p>In the capitalized form, save the specified messages in a file whose name is derived from the author of the first message. The +name of the file shall be taken to be the author's name with all network addressing stripped off. See also the <b>Copy</b>, +<b>followup</b>, and <b>Followup</b> commands and <b>outfolder</b> variable.</p> +<h5><a name="tag_20_75_13_33" id="tag_20_75_13_33"></a>Set Variables</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>se</tt><b>[</b><tt>t</tt><b>] [</b><i>name</i><b>[</b><tt>=</tt><b>[</b><i>string</i><b>]] </b><tt>...</tt><b>] [</b><i>name</i><tt>=</tt><i>number </i><tt>...</tt><b>] [</b><tt>no</tt><i>name </i><tt>...</tt><b>]</b><tt> +</tt></pre></dd> +</dl> +<p>Define one or more variables called <i>name</i>. The variable can be given a null, string, or numeric value. Quoting and +<backslash>-escapes can occur anywhere in <i>string</i>, as described previously, as if the <i>string</i> portion of the +argument were the entire argument. The forms <i>name</i> and <i>name</i>= shall be equivalent to <i>name</i>="" for variables that +take string values. The <b>set</b> command without arguments shall write a list of all defined variables and their values. The +<b>no</b> <i>name</i> form shall be equivalent to <b>unset</b> <i>name</i>.</p> +<h5><a name="tag_20_75_13_34" id="tag_20_75_13_34"></a>Invoke a Shell</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>sh</tt><b>[</b><tt>ell</tt><b>]</b><tt> +</tt></pre></dd> +</dl> +<p>Invoke an interactive command interpreter (see also <i>SHELL ).</i></p> +<h5><a name="tag_20_75_13_35" id="tag_20_75_13_35"></a>Display Message Size</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>si</tt><b>[</b><tt>ze</tt><b>] [</b><i>msglist</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p>Write the size in bytes of each of the specified messages.</p> +<h5><a name="tag_20_75_13_36" id="tag_20_75_13_36"></a>Read mailx Commands From a File</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>so</tt><b>[</b><tt>urce</tt><b>] </b><i>file</i><tt> +</tt></pre></dd> +</dl> +<p>Read and execute commands from the file named by the pathname <i>file</i> and return to command mode.</p> +<h5><a name="tag_20_75_13_37" id="tag_20_75_13_37"></a>Display Beginning of Messages</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>to</tt><b>[</b><tt>p</tt><b>] [</b><i>msglist</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p>Write the top few lines of each of the specified messages. If the <b>toplines</b> variable is set, it is taken as the number of +lines to write. The default shall be 5.</p> +<h5><a name="tag_20_75_13_38" id="tag_20_75_13_38"></a>Touch Messages</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>tou</tt><b>[</b><tt>ch</tt><b>] [</b><i>msglist</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p>Allowed only in the system mailbox. Touch the specified messages. Unless overridden by the <b>hold</b> variable, any message in +<i>msglist</i> that is not specifically deleted nor saved in a file shall be placed in the <b>mbox</b> upon normal termination or +when the folder is changed. Overrides a former <b>hold</b> or <b>preserve</b> request.</p> +<h5><a name="tag_20_75_13_39" id="tag_20_75_13_39"></a>Delete Aliases</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>una</tt><b>[</b><tt>lias</tt><b>] [</b><i>alias</i><b>]</b><tt>... +</tt></pre></dd> +</dl> +<p>Delete the specified alias names. If a specified alias does not exist, the results are unspecified.</p> +<h5><a name="tag_20_75_13_40" id="tag_20_75_13_40"></a>Undelete Messages</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>u</tt><b>[</b><tt>ndelete</tt><b>] [</b><i>msglist</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p>Change the state of the specified messages from deleted to read. If <b>autoprint</b> is set, the last message of those restored +shall be written. If <i>msglist</i> is not specified, the message shall be selected as follows:</p> +<ul> +<li> +<p>If there are any deleted messages that follow the current message, the first of these shall be chosen.</p> +</li> +<li> +<p>Otherwise, the last deleted message that also precedes the current message shall be chosen.</p> +</li> +</ul> +<h5><a name="tag_20_75_13_41" id="tag_20_75_13_41"></a>Unset Variables</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>uns</tt><b>[</b><tt>et</tt><b>] </b><i>name</i><tt>... +</tt></pre></dd> +</dl> +<p>Cause the specified variables to be erased.</p> +<h5><a name="tag_20_75_13_42" id="tag_20_75_13_42"></a>Edit Message with Full-Screen Editor</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>v</tt><b>[</b><tt>isual</tt><b>] [</b><i>msglist</i><b>]</b><tt> +</tt></pre></dd> +</dl> +<p>Edit the given messages with a screen editor. Each message shall be placed in a temporary file, and the utility named by the +<i>VISUAL</i> variable shall be invoked to edit each file in sequence. The default editor shall be <a href= +"../utilities/vi.html"><i>vi</i></a>.</p> +<p>The <b>visual</b> command does not modify the contents of those messages in the mailbox.</p> +<h5><a name="tag_20_75_13_43" id="tag_20_75_13_43"></a>Write Messages to a File</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>w</tt><b>[</b><tt>rite</tt><b>] [</b><i>msglist</i><b>] </b><i>file</i><tt> +</tt></pre></dd> +</dl> +<p>Write the given messages to the file specified by the pathname <i>file</i>, minus the message header. Otherwise, it shall be +equivalent to the <b>save</b> command.</p> +<h5><a name="tag_20_75_13_44" id="tag_20_75_13_44"></a>Scroll Header Display</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>z</tt><b>[</b><tt>+|-</tt><b>]</b><tt> +</tt></pre></dd> +</dl> +<p>Scroll the header display forward (if <tt>'+'</tt> is specified or if no option is specified) or backward (if <tt>'-'</tt> is +specified) one screenful. The number of header summaries written shall be set by the <b>screen</b> variable.</p> +<h5><a name="tag_20_75_13_45" id="tag_20_75_13_45"></a>Invoke Shell Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>!</tt><i>command</i><tt> +</tt></pre></dd> +</dl> +<p>Invoke the command interpreter specified by <i>SHELL</i> with three arguments: <tt>"-c"</tt>, <tt>"--"</tt>, and <i>command</i>. +(See also <a href="../utilities/sh.html"><i>sh</i></a> <b>-c</b>.) If the <b>bang</b> variable is set, each unescaped occurrence of +<tt>'!'</tt> in <i>command</i> shall be replaced with the command executed by the previous <b>!</b> command or <b>~!</b> command +escape.</p> +<h5><a name="tag_20_75_13_46" id="tag_20_75_13_46"></a>Null Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt># </tt><i>comment</i><tt> +</tt></pre></dd> +</dl> +<p>This null command (comment) shall be ignored by <i>mailx</i>.</p> +<h5><a name="tag_20_75_13_47" id="tag_20_75_13_47"></a>Display Current Message Number</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>= +</tt></pre></dd> +</dl> +<p>Write the current message number.</p> +<h5><a name="tag_20_75_13_48" id="tag_20_75_13_48"></a>Command Escapes in mailx</h5> +<p>The following commands can be entered only from input mode, by beginning a line with the escape character (by default, +<tilde> (<tt>'~'</tt>)). See the <b>escape</b> variable description for changing this special character. The format for the +commands shall be:</p> +<pre> +<tt><</tt><i>escape-character</i><tt>><</tt><i>command-char</i><tt>><</tt><i>separator</i><tt>></tt><b>[</b><tt><</tt><i>arguments</i><tt>></tt><b>]</b><tt> +</tt></pre> +<p>where the <<i>separator</i>> can be zero or more <blank> characters.</p> +<p>In the following descriptions, the application shall ensure that the argument <i>command</i> (but not <i>mailx-command)</i> is a +shell command string. Any string acceptable to the command interpreter specified by the <i>SHELL</i> variable when it is invoked as +<i>SHELL</i> <b>-c</b> <i>command_string</i> shall be valid. The command can be presented as multiple arguments (that is, quoting +is not required).</p> +<p>Command escapes that are listed with <i>msglist</i> or <i>mailx-command</i> arguments are invalid in Send Mode and produce +unspecified results.</p> +<dl compact> +<dd></dd> +<dt><b>~! </b><i>command</i></dt> +<dd>Invoke the command interpreter specified by <i>SHELL</i> with three arguments: <tt>"-c"</tt>, <tt>"--"</tt>, and +<i>command</i>; and then return to input mode. If the <b>bang</b> variable is set, each unescaped occurrence of <tt>'!'</tt> in +<i>command</i> shall be replaced with the command executed by the previous <b>!</b> command or <b>~!</b> command escape.</dd> +<dt><b>~.</b></dt> +<dd>Simulate end-of-file (terminate message input).</dd> +<dt><b>~: </b><i>mailx-command</i>, <b>~_ </b><i>mailx-command</i></dt> +<dd><br> +Perform the command-level request.</dd> +<dt><b>~?</b></dt> +<dd>Write a summary of command escapes.</dd> +<dt><b>~A</b></dt> +<dd>This shall be equivalent to <b>~i Sign</b>.</dd> +<dt><b>~a</b></dt> +<dd>This shall be equivalent to <b>~i sign</b>.</dd> +<dt><b>~b </b><i>name</i>...</dt> +<dd>Add the <i>name</i>s to the blind carbon copy (<b>Bcc</b>) list.</dd> +<dt><b>~c </b><i>name</i>...</dt> +<dd>Add the <i>name</i>s to the carbon copy (<b>Cc</b>) list.</dd> +<dt><b>~d</b></dt> +<dd>Read in the dead-letter file. See <i>DEAD</i> for a description of this file.</dd> +<dt><b>~e</b></dt> +<dd>Invoke the editor, as specified by the <i>EDITOR</i> environment variable, on the partial message.</dd> +<dt><b>~f [</b><i>msglist</i><b>]</b></dt> +<dd>Forward the specified messages. The specified messages, including their headers, shall be inserted into the current message +without alteration. The header fields included in each header shall be affected by the <b>discard</b>, <b>ignore</b>, and +<b>retain</b> commands.</dd> +<dt><b>~F [</b><i>msglist</i><b>]</b></dt> +<dd>This shall be the equivalent of the <b>~f</b> command escape, except that all header fields shall be included in the message +headers, regardless of previous <b>discard</b>, <b>ignore</b>, and <b>retain</b> commands.</dd> +<dt><b>~h</b></dt> +<dd>If standard input is a terminal, prompt for values for the <b>Subject</b>, <b>To</b>, <b>Cc</b>, and <b>Bcc</b> header fields. +Other implementation-defined header fields may also be presented for editing. If the header field is written with an initial value, +it can be edited as if it had just been typed.</dd> +<dt><b>~i </b><i>string</i></dt> +<dd>Insert the value of the named variable, followed by a <newline>, into the text of the message. If the string is unset or +null, the message shall not be changed.</dd> +<dt><b>~m [</b><i>msglist</i><b>]</b></dt> +<dd>Insert the specified messages, including their headers, into the current message, prefixing non-empty lines with the string in +the <b>indentprefix</b> variable. The header fields included in each header shall be affected by the <b>discard</b>, <b>ignore</b>, +and <b>retain</b> commands.</dd> +<dt><b>~M [</b><i>msglist</i><b>]</b></dt> +<dd>This shall be the equivalent of the <b>~m</b> command escape, except that all header fields shall be included in the message +headers, regardless of previous <b>discard</b>, <b>ignore</b>, and <b>retain</b> commands.</dd> +<dt><b>~p</b></dt> +<dd>Write the message being entered. If the message is longer than <b>crt</b> lines (see <a href="#tag_20_75_13_02">Internal +Variables in mailx</a> ), the output shall be paginated as described for the <i>PAGER</i> variable.</dd> +<dt><b>~q</b></dt> +<dd>Quit (see the <b>quit</b> command) from input mode by simulating an interrupt. If the body of the message is not empty, the +partial message shall be saved in the dead-letter file. See <i>DEAD</i> for a description of this file.</dd> +<dt> +<b>~r </b><i>file</i>, <b>~< </b><i>file</i>, <b>~r !</b><i>command</i>, <b>~< !</b><i>command</i></dt> +<dd><br> +Read in the file specified by the pathname <i>file</i>. If the argument begins with an <exclamation-mark> (<tt>'!'</tt>), the +rest of the string shall be taken as an arbitrary system command; the command interpreter specified by <i>SHELL</i> shall be +invoked with three arguments: <tt>"-c"</tt>, <tt>"--"</tt>, and <i>command</i>. The standard output of <i>command</i> shall be +inserted into the message.</dd> +<dt><b>~s </b><i>string</i></dt> +<dd>Set the value for the <b>Subject</b> header field to <i>string</i>.</dd> +<dt><b>~t </b><i>name</i>...</dt> +<dd>Add the given <i>name</i>s to the <b>To</b> list.</dd> +<dt><b>~v</b></dt> +<dd>Invoke the full-screen editor, as specified by the <i>VISUAL</i> environment variable, on the partial message.</dd> +<dt><b>~w </b><i>file</i></dt> +<dd>Write the partial message, without the header, onto the file named by the pathname <i>file</i>. The file shall be created or +the message shall be appended to it if the file exists.</dd> +<dt><b>~x</b></dt> +<dd>Exit as with <b>~q</b>, except the message shall not be saved in the dead-letter file.</dd> +<dt><b>~| </b><i>command</i></dt> +<dd>Pipe the body of the message through the given <i>command</i> by invoking the command interpreter specified by <i>SHELL</i> +with three arguments: <tt>"-c"</tt>, <tt>"--"</tt>, and <i>command</i>. If the <i>command</i> returns a successful exit status, the +standard output of the command shall replace the message. Otherwise, the message shall remain unchanged. If the <i>command</i> +fails, an error message giving the exit status shall be written.</dd> +</dl> +<br></blockquote> +<h4 class="mansect"><a name="tag_20_75_14" id="tag_20_75_14"></a>EXIT STATUS</h4> +<blockquote> +<p><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +When the <b>-e</b> option is specified, the following exit values are returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Mail was found.</dd> +<dt>>0</dt> +<dd>Mail was not found or an error occurred.</dd> +</dl> +<img src="../images/opt-end.gif" alt="[Option End]" border="0"> +<p>Otherwise, the following exit values are returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion; note that this status implies that any messages that <i>mailx</i> was instructed to send were all +successfully either <i>sent</i> or discarded (see <b>-E</b>), but it gives no assurances that any of them were actually +<i>delivered</i>.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_75_15" id="tag_20_75_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>When in <sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border= +"0"> input mode (Receive Mode) <img src="../images/opt-end.gif" alt="[Option End]" border="0"> or Send Mode:</p> +<ul> +<li> +<p>If an error is encountered processing an input line beginning with a <tilde> (<tt>'~'</tt>) character, <sup>[<a href= +"javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> (see <a href= +"#tag_20_75_13_48">Command Escapes in mailx</a> ), <img src="../images/opt-end.gif" alt="[Option End]" border="0"> a +diagnostic message shall be written to standard error, and the message being composed may be modified, but this condition shall not +prevent the message from being sent.</p> +</li> +<li> +<p>Other errors shall prevent the sending of the message.</p> +</li> +</ul> +<p><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +When in command mode:</p> +<ul> +<li> +<p>Default.</p> +</li> +</ul> +<img src="../images/opt-end.gif" alt="[Option End]" border="0"></blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_75_16" id="tag_20_75_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Delivery of messages to remote systems requires the existence of communication paths to such systems. These need not exist.</p> +<p>Input lines are limited to {LINE_MAX} bytes, but mailers between systems may impose more severe line-length restrictions. This +volume of POSIX.1-2024 does not place any restrictions on the length of messages handled by <i>mailx</i>, and for delivery of local +messages the only limitations should be the normal problems of available disk space for the target mail file. When sending messages +to external machines, applications are advised to limit messages to less than 100000 bytes because some mail gateways impose +message-length restrictions.</p> +<p>The format of the system mailbox is intentionally unspecified. Not all systems implement system mailboxes as flat files, +particularly with the advent of multimedia mail messages. Some system mailboxes may be multiple files, others records in a +database. The internal format of the messages themselves is specified with the historical format from Version 7, but only +after the messages have been saved in some file other than the system mailbox. This was done so that many historical applications +expecting text-file mailboxes are not broken.</p> +<p>Some new formats for messages can be expected in the future, probably including binary data, bit maps, and various multimedia +objects. As described here, <i>mailx</i> is not prohibited from handling such messages, but it must store them as text files in +secondary mailboxes (unless some extension, such as a variable or command line option, is used to change the stored format). Its +method of doing so is implementation-defined and might include translating the data into text file-compatible or readable form or +omitting certain portions of the message from the stored output.</p> +<p>The <b>discard</b> and <b>ignore</b> commands are not inverses of the <b>retain</b> command. The <b>retain</b> command discards +all header fields except those explicitly retained. The <b>discard</b> command keeps all header fields except those explicitly +discarded. If field names exist on the retained field names list, <b>discard</b> and <b>ignore</b> commands are ignored.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_75_17" id="tag_20_75_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_75_18" id="tag_20_75_18"></a>RATIONALE</h4> +<blockquote> +<p>The standard developers felt strongly that a method for applications to send messages to specific users was necessary. The +obvious example is a batch utility, running non-interactively, that wishes to communicate errors or results to a user. However, the +actual format, delivery mechanism, and method of reading the message are clearly beyond the scope of this volume of +POSIX.1-2024.</p> +<p>The intent of this command is to provide a simple, portable interface for sending messages non-interactively. It merely defines +a "front-end" to the historical mail system. It is suggested that implementations explicitly denote the sender and recipient in +the body of the delivered message. Further specification of formats for either the message envelope or the message itself were +deliberately not made, as the industry is in the midst of changing from the current standards to a more internationalized standard +and it is probably incorrect, at this time, to require either one.</p> +<p>Implementations are encouraged to conform to the various delivery mechanisms described in the CCITT X.400 standards or to the +equivalent Internet standards, described in Internet Request for Comment (RFC) documents RFC 819, RFC 920, RFC 921, +RFC 1123, and RFC 5322.</p> +<p>Many historical systems modified each body line that started with <b>From </b> by prefixing the <tt>'F'</tt> with +<tt>'>'</tt>. It is unnecessary, but allowed, to do that when the string does not follow a blank line because it cannot be +confused with the next header.</p> +<p>The <b>edit</b> and <b>visual</b> commands merely edit the specified messages in a temporary file. They do not modify the +contents of those messages in the mailbox; such a capability could be added as an extension, such as by using different command +names.</p> +<p>The restriction on the value for a <b>Subject</b> header field being {LINE_MAX}-10 bytes is based on the historical format that +consumes 10 bytes for <b>Subject: </b> and the trailing <newline>. Many historical mailers that a message may encounter +on other systems are not able to handle lines that long, however.</p> +<p>Like the utilities <a href="../utilities/logger.html"><i>logger</i></a> and <a href="../utilities/lp.html"><i>lp</i></a>, +<i>mailx</i> admittedly is difficult to test. This was not deemed sufficient justification to exclude this utility from this volume +of POSIX.1-2024. It is also arguable that it is, in fact, testable, but that the tests themselves are not portable.</p> +<p>When <i>mailx</i> is being used by an application that wishes to receive the results as if none of the User Portability +Utilities option features were supported, the <i>DEAD</i> environment variable must be set to <b>/dev/null</b>. Otherwise, it may +be subject to the file creations described in <i>mailx</i> ASYNCHRONOUS EVENTS. Similarly, if the <i>MAILRC</i> environment +variable is not set to <b>/dev/null</b>, historical versions of <i>mailx</i> and <i>Mail</i> read initialization commands from a +file before processing begins. Since the initialization that a user specifies could alter the contents of messages an application +is trying to send, such applications must set <i>MAILRC</i> to <b>/dev/null</b>.</p> +<p>The description of <i>LC_TIME</i> uses "may affect" because many historical implementations do not or cannot manipulate the +date and time strings in the incoming mail headers. Some header fields found in incoming mail do not have enough information to +determine the timezone in which the mail originated, and, therefore, <i>mailx</i> cannot convert the date and time strings into the +internal form that then is parsed by routines like <a href="../functions/strftime.html"><i>strftime</i>()</a> that can take +<i>LC_TIME</i> settings into account. Changing all these times to a user-specified format is allowed, but not required.</p> +<p>The paginator selected when <i>PAGER</i> is null or unset is partially unspecified to allow the System V historical practice of +using <i>pg</i> as the default. Bypassing the pagination function, such as by declaring that <a href= +"../utilities/cat.html"><i>cat</i></a> is the paginator, would not meet with the intended meaning of this description. However, any +"portable user" would have to set <i>PAGER</i> explicitly to get his or her preferred paginator on all systems. The paginator +choice was made partially unspecified, unlike the <i>VISUAL</i> editor choice (mandated to be <a href= +"../utilities/vi.html"><i>vi</i></a>) because most historical pagers follow a common theme of user input, whereas editors differ +dramatically.</p> +<p>Options to specify addresses as <b>cc</b> (carbon copy) or <b>bcc</b> (blind carbon copy) were considered to be format details +and were omitted.</p> +<p>A zero exit status implies that all messages were <i>sent</i>, but it gives no assurances that any of them were actually +<i>delivered</i>. The reliability of the delivery mechanism is unspecified and is an appropriate marketing distinction between +systems.</p> +<p>In order to conform to the Utility Syntax Guidelines, a solution was required to the optional <i>file</i> option-argument to +<b>-f</b>. By making <i>file</i> an operand, the guidelines are satisfied and users remain portable. However, it does force +implementations to support usage such as:</p> +<pre> +<tt>mailx -fin mymail.box +</tt></pre> +<p>The <b>no</b> <i>name</i> method of unsetting variables is not present in all historical systems, but it is in System V and +provides a logical set of commands corresponding to the format of the display of options from the <i>mailx</i> <a href= +"../utilities/V3_chap02.html#set"><i>set</i></a> command without arguments.</p> +<p>The <b>ask</b> and <b>asksub</b> variables are the names selected by BSD and System V, respectively, for the same feature. They +are synonyms in this volume of POSIX.1-2024.</p> +<p>The <i>mailx</i> <a href="../utilities/echo.html"><i>echo</i></a> command was not documented in the BSD version and has been +omitted here because it is not obviously useful for interactive users.</p> +<p>The default prompt on the System V <i>mailx</i> is a <question-mark>, on BSD <i>Mail</i> an <ampersand>. Since this +volume of POSIX.1-2024 chose the <i>mailx</i> name, it kept the System V default, assuming that BSD users would not have difficulty +with this minor incompatibility (that they can override).</p> +<p>The meanings of <b>r</b> and <b>R</b> are reversed between System V <i>mailx</i> and SunOS <i>Mail</i>. Once again, since this +volume of POSIX.1-2024 chose the <i>mailx</i> name, it kept the System V default, but allows the SunOS user to achieve the desired +results using <b>flipr</b>, an internal variable in System V <i>mailx</i>, although it has not been documented in the SVID.</p> +<p>The <b>indentprefix</b> variable, the <b>retain</b> and <b>unalias</b> commands, and the <b>~F</b> and <b>~M</b> command escapes +were adopted from 4.3 BSD <i>Mail</i>.</p> +<p>The <b>version</b> command was not included because no sufficiently general specification of the version information could be +devised that would still be useful to a portable user. This command name should be used by suppliers who wish to provide version +information about the <i>mailx</i> command.</p> +<p>The "implementation-specific (unspecified) system start-up file" historically has been named <b>/etc/mailx.rc</b>, but this +specific name and location are not required.</p> +<p>The intent of the wording for the <b>next</b> command is that if any command has already displayed the current message it should +display a following message, but, otherwise, it should display the current message. Consider the command sequence:</p> +<pre> +<tt>next 3 +delete 3 +next +</tt></pre> +<p>where the <b>autoprint</b> option was not set. The normative text specifies that the second <b>next</b> command should display a +message following the third message, because even though the current message has not been displayed since it was set by the +<b>delete</b> command, it has been displayed since the current message was anything other than message number 3. This does not +always match historical practice in some implementations, where the command file address followed by <b>next</b> (or the default +command) would skip the message for which the user had searched.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_75_19" id="tag_20_75_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a +<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require +implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_75_20" id="tag_20_75_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19"><i>2. Shell Command Language</i></a> , <a href= +"../utilities/ed.html#"><i>ed</i></a> , <a href="../utilities/ls.html#"><i>ls</i></a> , <a href= +"../utilities/more.html#"><i>more</i></a> , <a href="../utilities/vi.html#"><i>vi</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_75_21" id="tag_20_75_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_75_22" id="tag_20_75_22"></a>Issue 5</h4> +<blockquote> +<p>The description of the <i>EDITOR</i> environment variable is changed to indicate that <a href= +"../utilities/ed.html"><i>ed</i></a> is the default editor if this variable is not set. In previous issues, this default was not +stated explicitly at this point but was implied further down in the text.</p> +<p>The FUTURE DIRECTIONS section is added.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_75_23" id="tag_20_75_23"></a>Issue 6</h4> +<blockquote> +<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p> +<ul> +<li> +<p>The <b>-F</b> option is added.</p> +</li> +<li> +<p>The <b>allnet</b>, <b>debug</b>, and <b>sendwait</b> internal variables are added.</p> +</li> +<li> +<p>The <b>C</b>, <b>ec</b>, <b>fo</b>, <b>F</b>, and <b>S</b> <i>mailx</i> commands are added.</p> +</li> +</ul> +<p>In the DESCRIPTION and ENVIRONMENT VARIABLES sections, text stating "<i>HOME</i> directory" is replaced by "directory +referred to by the <i>HOME</i> environment variable".</p> +<p>The <i>mailx</i> utility is aligned with the IEEE P1003.2b draft standard, which includes various clarifications to resolve +IEEE PASC Interpretations submitted for the ISO POSIX-2:1993 standard. In particular, the changes here address IEEE PASC +Interpretations 1003.2 #10, #11, #103, #106, #108, #114, #115, #122, and #129.</p> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +<p>The <i>TZ</i> entry is added to the ENVIRONMENT VARIABLES section.</p> +<p>IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/32 is applied, applying a change to the EXTENDED DESCRIPTION, +raised by IEEE PASC Interpretation 1003.2 #122, which was overlooked in the first version of this standard.</p> +<p>IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/17 is applied, updating the EXTENDED DESCRIPTION (Internal +Variables in <i>mailx</i>). The system start-up file is changed from "implementation-defined" to "unspecified" for consistency +with other text in the EXTENDED DESCRIPTION.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_75_24" id="tag_20_75_24"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #089 is applied, clarifying the effect of the <i>LC_TIME</i> environment variable.</p> +<p>Austin Group Interpretation 1003.1-2001 #090 is applied, updating the description of the <b>next</b> command.</p> +<p>SD5-XCU-ERN-69 is applied.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>Shading to indicate support for the User Portability Utilities option is added.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0120 [855] and XCU/TC2-2008/0121 [619] are applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_75_25" id="tag_20_75_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to disallow the creation of filenames containing any bytes that +have the encoded value of a <newline> character.</p> +<p>Austin Group Defect 956 is applied, clarifying how the <i>PAGER</i> environment variable and the <b>crt</b> internal variable +affect pagination.</p> +<p>Austin Group Defects 990 and 991 are applied, changing the description of the <b>mbox</b> command.</p> +<p>Austin Group Defect 999 is applied, adding <b>Save</b> to the list of commands that are invalid in a start-up file.</p> +<p>Austin Group Defect 1034 is applied, clarifying that <b>~.</b> can be used to terminate input mode when <b>ignoreeof</b> is +set.</p> +<p>Austin Group Defect 1109 is applied, changing the description of the <b>bang</b> internal variable.</p> +<p>Austin Group Defect 1113 is applied, changing the description of the <i>read</i> state.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1176 is applied, changing "option-argument" to "operand".</p> +<p>Austin Group Defect 1306 is applied, changing the description of the <b>folder</b> internal variable.</p> +<p>Austin Group Defect 1367 is applied, adding the <b>-E</b> option.</p> +<p>Austin Group Defect 1401 is applied, changing the requirements for the <b>reply</b>, <b>Reply</b>, <b>followup</b>, and +<b>Followup</b> commands.</p> +<p>Austin Group Defect 1405 is applied, changing the terminology related to mail messages to match IETF RFC 5322.</p> +<p>Austin Group Defect 1408 is applied, changing the description of Send Mode.</p> +<p>Austin Group Defect 1507 is applied, changing the EXIT STATUS section.</p> +<p>Austin Group Defect 1528 is applied, adding a <tt>"--"</tt> argument to be passed between <tt>"-c"</tt> and <i>command</i> when +executing shell commands.</p> +<p>Austin Group Defect 1634 is applied, clarifying handling of the system mailbox.</p> +<p>Austin Group Defect 1685 is applied, updating RFC references.</p> +<p>Austin Group Defect 1725 is applied, clarifying that the default for the <b>screen</b> internal variable is <b>noscreen</b>.</p> +<p>Austin Group Defect 1743 is applied, changing the descriptions of the <b>metoo</b> internal variable and the <b>alternates</b> +command.</p> +<p>Austin Group Defect 1747 is applied, changing the description of the <b>alias</b> command.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/m4.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/make.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/make.html b/bdd/make.html @@ -0,0 +1,1806 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>make</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/mailx.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/man.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="make" id="make"></a> <a name="tag_20_76" id="tag_20_76"></a><!-- make --> +<h4 class="mansect"><a name="tag_20_76_01" id="tag_20_76_01"></a>NAME</h4> +<blockquote>make — maintain, update, and regenerate files (<b>DEVELOPMENT</b>)</blockquote> +<h4 class="mansect"><a name="tag_20_76_02" id="tag_20_76_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('SD')">SD</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> make</tt> <b>[</b><tt>-einpqrst</tt><b>] [</b><tt>-f</tt> <i>makefile</i><b>]</b><tt>...</tt> +<b>[</b><tt>-j</tt> <i>maxjobs</i><b>] [</b><tt>-k|-S</tt><b>]<br></b> <tt> </tt> +<b>[</b><i>macro</i><b>[</b><tt>::</tt><b>[</b><tt>:</tt><b>]]</b><tt>=</tt><i>value</i><tt>...</tt><b>] +[</b><i>target_name</i><tt>...</tt><b>]</b> <tt><img src="../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div> +</blockquote> +<h4 class="mansect"><a name="tag_20_76_03" id="tag_20_76_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>make</i> utility shall update files that are derived from other files. A typical case is one where object files are +derived from the corresponding source files. The <i>make</i> utility examines time relationships and shall update those derived +files (called targets) that have modified times earlier than the modified times of the files (called prerequisites) from which they +are derived. A description file (makefile) contains a description of the relationships between files, and the commands that need to +be executed to update the targets to reflect changes in their prerequisites. Each specification, or rule, shall consist of a +target, optional prerequisites, and optional commands to be executed when a prerequisite is newer than the target. There are two +kinds of rule:</p> +<ol> +<li> +<p><i>Inference rules</i>, which have one target name with at least one <period> (<tt>'.'</tt>) and no <slash> +(<tt>'/'</tt>)</p> +</li> +<li> +<p><i>Target rules</i>, which can have more than one target name</p> +</li> +</ol> +<p>In addition, <i>make</i> shall have a collection of built-in macros and inference rules that infer prerequisite relationships to +simplify maintenance of programs.</p> +<p>To receive exactly the behavior described in this section, a portable makefile shall:</p> +<ul> +<li> +<p>Include the special target <b>.POSIX</b></p> +</li> +<li> +<p>Omit any special target reserved for implementations (a leading period followed by uppercase letters) that has not been +specified by this section</p> +</li> +</ul> +<p>The behavior of <i>make</i> is unspecified if either or both of these conditions are not met.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_76_04" id="tag_20_76_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>make</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> , except for Guideline 9.</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-e</b></dt> +<dd>Cause environment variables, including those with null values, to override macro assignments within makefiles.</dd> +<dt><b>-f </b><i>makefile</i></dt> +<dd>Specify a different makefile. The argument <i>makefile</i> is a pathname of a description file, which is also referred to as +the <i>makefile</i>. A pathname of <tt>'-'</tt> shall denote the standard input. There can be multiple instances of this option, +and they shall be processed in the order specified. The effect of specifying the same option-argument more than once is +unspecified.</dd> +<dt><b>-i</b></dt> +<dd>Ignore error codes returned by invoked commands. This mode shall be the same as if the special target <b>.IGNORE</b> were +specified without prerequisites.</dd> +<dt><b>-j </b><i>maxjobs</i></dt> +<dd>Set the maximum number of targets that can be updated concurrently. If this option is specified multiple times, the last value +of <i>maxjobs</i> specified shall take precedence. If this option is not specified, or if <i>maxjobs</i> is 1, only one target +shall be updated at a time (no parallelization). If the value of <i>maxjobs</i> is non-positive, the behavior is unspecified. When +<i>maxjobs</i> is greater than 1, <i>make</i> shall create a pool of up to <i>maxjobs</i> - 1 tokens. (Note that implementations +are not required to create a pool of exactly <i>maxjobs</i> - 1 tokens. For example, an implementation could limit the pool size +based on the number of processors available.) If the size of the token pool would be 0, <i>make</i> need not implement a token +pool. +<p>When all of the following are true:</p> +<ul> +<li> +<p>There is a target with commands that is not up-to-date</p> +</li> +<li> +<p>The target's prerequisites (if any) are up-to-date</p> +</li> +<li> +<p><i>make</i> is not waiting to bring the target up-to-date (see <b>.WAIT</b>)</p> +</li> +<li> +<p><i>make</i> is currently bringing a different target with commands up-to-date</p> +</li> +<li> +<p><i>make</i> is not currently bringing <i>maxjobs</i> targets up-to-date in parallel</p> +</li> +<li> +<p>The special target <b>.NOTPARALLEL</b> is not specified</p> +</li> +<li> +<p>The token pool is not empty</p> +</li> +</ul> +<p>then <i>make</i> may attempt to remove one token from the pool. If a token is successfully removed, it shall attempt to bring +this target up-to-date in parallel, and after this processing completes shall return the token to the pool. When <i>make</i> is +bringing a target without commands up-to-date, it need not remove a token from the pool.</p> +<p>If a rule invokes a sub-<i>make</i> either via the <i>MAKE</i> macro or via a command line that begins with <tt>'+'</tt>, the +sub-<i>make</i> is the same implementation as the <i>make</i> that invoked the sub-<i>make</i>, and the <b>-j</b> option is passed +to the sub-<i>make</i> via the <i>MAKEFLAGS</i> environment variable with the same <i>maxjobs</i> value and is not overridden by a +<i>maxjobs</i> value from another source (even if it has the same value), the sub-<i>make</i> shall use the same token pool as its +invoking <i>make</i> rather than create a new token pool. Otherwise, it is unspecified whether the sub-<i>make</i> uses the same +token pool as its invoking <i>make</i> or creates a new token pool. If a rule executes multiple sub-<i>make</i> processes +asynchronously the behavior is unspecified.</p> +</dd> +<dt><b>-k</b></dt> +<dd>Continue to update other targets that do not depend on the current target if a non-ignored error occurs while executing the +commands to bring a target up-to-date.</dd> +<dt><b>-n</b></dt> +<dd>Write commands that would be executed on standard output, but do not execute them. However, lines with a <plus-sign> +(<tt>'+'</tt>) prefix, lines that expand the <i>MAKE</i> macro, and lines being processed in order to create an include file or to +bring it up-to-date (see <b>Include Lines</b> in the EXTENDED DESCRIPTION section) shall be executed. In this mode, lines with a +<commercial-at> (<tt>'@'</tt>) character prefix shall be written to standard output.</dd> +<dt><b>-p</b></dt> +<dd>Write to standard output the complete set of macro definitions and target descriptions. The output format is unspecified.</dd> +<dt><b>-q</b></dt> +<dd>Return a zero exit value if the target file is up-to-date; otherwise, return an exit value of 1. Targets shall not be updated +if this option is specified. However, a makefile command line (associated with the targets) with a <plus-sign> (<tt>'+'</tt>) +prefix shall be executed and it is unspecified whether command lines that do not have a <plus-sign> prefix and either expand +the <i>MAKE</i> macro or are being processed in order to create an include file or to bring it up-to-date (see <b>Include Lines</b> +in the EXTENDED DESCRIPTION section) are executed.</dd> +<dt><b>-r</b></dt> +<dd>Clear the suffix list and do not use the built-in rules.</dd> +<dt><b>-S</b></dt> +<dd>Terminate <i>make</i> if an error occurs while executing the commands to bring a target up-to-date. This shall be the default +and the opposite of <b>-k</b>.</dd> +<dt><b>-s</b></dt> +<dd>Do not write makefile <i>execution lines</i> (see <a href="#tag_20_76_13_03">Makefile Execution</a> ) or touch messages (see +<b>-t</b>) to standard output before executing. This mode shall be the same as if the special target <b>.SILENT</b> were specified +without prerequisites.</dd> +<dt><b>-t</b></dt> +<dd>Update the modification time of each target as though a <a href="../utilities/touch.html"><i>touch</i></a> <i>target</i> had +been executed. Targets that have prerequisites but no commands (see <a href="#tag_20_76_13_04">Target Rules</a> ), or that are +already up-to-date, shall not be touched in this manner. Write messages to standard output for each target file indicating the name +of the file and that it was touched. Normally, the <i>makefile</i> command lines associated with each target are not executed. +However, a command line with a <plus-sign> (<tt>'+'</tt>) prefix shall be executed and it is unspecified whether command +lines that do not have a <plus-sign> prefix and either expand the <i>MAKE</i> macro or are being processed in order to create +an include file or to bring it up-to-date (see <b>Include Lines</b> in the EXTENDED DESCRIPTION section) are executed.</dd> +</dl> +<p>Any options specified in the <i>MAKEFLAGS</i> environment variable shall be evaluated before any options specified on the +<i>make</i> utility command line. If the <b>-k</b> and <b>-S</b> options are both specified on the <i>make</i> utility command line +or by the <i>MAKEFLAGS</i> environment variable, the last option specified shall take precedence. If the <b>-f</b> or <b>-p</b> +options appear in the <i>MAKEFLAGS</i> environment variable, the result is undefined.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_76_05" id="tag_20_76_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>target_name</i></dt> +<dd>Target names, as defined in the EXTENDED DESCRIPTION section. If no target is specified, while <i>make</i> is processing the +makefiles, the first target that <i>make</i> encounters that is not a special target or an inference rule shall be used.</dd> +<dt><i>macro</i>=<i>value</i></dt> +<dd></dd> +<dt><i>macro</i>::=<i>value</i></dt> +<dd></dd> +<dt><i>macro</i>:::=<i>value</i></dt> +<dd>Delayed and immediate expansion macro definitions, as defined in <a href="#tag_20_76_13_05">Macros</a> .</dd> +</dl> +<p>Delayed and immediate expansion macro definitions can be intermixed, and shall be processed in the order specified. If any macro +definition appears after a <i>target_name</i> operand on the <i>make</i> utility command line, the results are unspecified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_76_06" id="tag_20_76_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be used only if the <i>makefile</i> option-argument is <tt>'-'</tt>. See the INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_76_07" id="tag_20_76_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input file, otherwise known as the makefile, is a text file containing rules, macro definitions, include lines, and +comments. See the EXTENDED DESCRIPTION section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_76_08" id="tag_20_76_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>make</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>MAKEFLAGS</i></dt> +<dd><br> +This variable shall be interpreted as a character string representing a series of option characters to be used as the default +options. The implementation shall accept both of the following formats (but need not accept them when intermixed): +<ul> +<li> +<p>The characters are option letters without the leading <hyphen-minus> characters or <blank> separation used on a +<i>make</i> utility command line.</p> +</li> +<li> +<p>The characters are formatted in a manner similar to the use of the <i>make</i> utility in shell commands: options are preceded +by <hyphen-minus> characters and <blank>-separated as described in XBD <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a> . The <i>macro</i>=<i>value</i> macro definition +operands can also be included. The difference between the contents of <i>MAKEFLAGS</i> and the use of the <i>make</i> utility in +shell commands is that the contents of the variable shall not be subjected to the word expansions (see <a href= +"../utilities/V3_chap02.html#tag_19_06"><i>2.6 Word Expansions</i></a> ) associated with parsing shell command lines.</p> +</li> +</ul> +</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>PROJECTDIR</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border= +"0"><br> +Provide a directory to be used to search for SCCS files not found in the current directory. In all of the following cases, the +search for SCCS files is made in the directory <b>SCCS</b> in the identified directory. If the value of <i>PROJECTDIR</i> begins +with a <slash>, it shall be considered an absolute pathname; otherwise, the value of <i>PROJECTDIR</i> is treated as a user +name and that user's initial working directory shall be examined for a subdirectory <b>src</b> or <b>source</b>. If such a +directory is found, it shall be used. Otherwise, the value is used as a relative pathname. +<p>If <i>PROJECTDIR</i> is not set or has a null value, the search for SCCS files shall be made in the directory <b>SCCS</b> in the +current directory.</p> +<p>The setting of <i>PROJECTDIR</i> affects all files listed in the remainder of this utility description for files with a +component named <b>SCCS</b>. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p> +</dd> +</dl> +<p>The value of the <i>SHELL</i> environment variable shall not be used as a macro and shall not be modified by defining the +<i>SHELL</i> macro in a makefile or on the command line. All other environment variables, including those with null values, shall +be used as macros, as defined in <a href="#tag_20_76_13_05">Macros</a> .</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_76_09" id="tag_20_76_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>For SIGHUP, SIGINT, SIGQUIT, and SIGTERM signals, if the signal was not inherited as ignored, none of the <b>-n</b>, <b>-p</b>, +or <b>-q</b> options was specified, <i>make</i> is currently processing a target or inference rule, and the current target is +neither a directory nor a prerequisite of the special targets <b>.PHONY</b> or <b>.PRECIOUS</b>:</p> +<ul> +<li> +<p>The <i>make</i> utility shall catch the signal and, if the time of last data modification of the current target has changed +since make began processing the rule to bring that target up to date, remove that target; it may also remove that target if the +time of last data modification has not changed. Any targets removed in this manner shall be reported in diagnostic or informational +messages of unspecified format, written to standard error.</p> +</li> +<li> +<p>If <i>make</i> writes a diagnostic message to standard error, it shall exit with a status that indicates an error occurred; +otherwise, it shall set the signal to default and re-signal itself.</p> +</li> +</ul> +<p>In all other circumstances, <i>make</i> shall take the standard action for all signals; see <a href= +"../utilities/V3_chap01.html#tag_18_04"><i>1.4 Utility Description Defaults</i></a> .</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_76_10" id="tag_20_76_10"></a>STDOUT</h4> +<blockquote> +<p>If <i>make</i> is invoked without any work needing to be done, it may write a message to standard output indicating that no +action was taken. Otherwise, the <i>make</i> utility shall write all commands to be executed (and the filenames of files touched +for the <b>-t</b> option in a message of unspecified format) to standard output unless the <b>-s</b> option was specified, the +command is prefixed with a <commercial-at> (<tt>'@'</tt>), or the special target <b>.SILENT</b> has either the current target +as a prerequisite or has no prerequisites.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_76_11" id="tag_20_76_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used for diagnostic messages and may be used for informational messages about target removals (see +ASYNCHRONOUS EVENTS).</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_76_12" id="tag_20_76_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>Files can be created when the <b>-t</b> option is present. Additional files can also be created by the utilities invoked by +<i>make</i>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_76_13" id="tag_20_76_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>The <i>make</i> utility attempts to perform the actions, specified in one or more makefiles, required to ensure that specified +targets are up-to-date. By default, the following files shall be tried in sequence: <b>./makefile</b> and <b>./Makefile</b>. If +neither <b>./makefile</b> nor <b>./Makefile</b> is found, other implementation-defined files may also be tried. <sup>[<a href= +"javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> On +XSI-conformant systems, the additional files <b>./s.makefile</b>, <b>SCCS/s.makefile</b>, <b>./s.Makefile</b>, and +<b>SCCS/s.Makefile</b> shall also be tried. <img src="../images/opt-end.gif" alt="[Option End]" border="0"> The <b>-f</b> +option shall direct <i>make</i> to ignore any of these default files and use the specified option-argument as a makefile instead. +If this option-argument is <tt>'-'</tt>, standard input shall be used.</p> +<p>The term <i>makefile</i> is used to refer to any makefile contents provided by the user, whether in <b>./makefile</b> or its +variants, or specified by the <b>-f</b> option.</p> +<p>A target shall be considered up-to-date if it exists and is newer than all of its prerequisites, or if it has already been made +up-to-date by the current invocation of <i>make</i> (regardless of the target's existence or age), except that targets that are +made up-to-date in order for them to be processed as include line pathnames (see <b>Include Lines</b> below) need not be considered +up-to-date during later processing. A target may also be considered up-to-date if it exists, is the same age as one or more of its +prerequisites, and is newer than the remaining prerequisites (if any). The <i>make</i> utility shall treat all prerequisites as +targets themselves and recursively ensure that they are up-to-date, processing them in the order in which they appear in the rule. +The <i>make</i> utility shall use the modification times of files to determine whether the corresponding targets are +out-of-date.</p> +<p>To ensure that a target is up-to-date, <i>make</i> shall ensure that all of the prerequisites of the target are up-to-date, then +check to see if the target itself is up-to-date. If the target is not up-to-date, the target shall be made up-to-date by executing +the rule's commands (if any). If the target does not exist after the target has been successfully made up-to-date, the target shall +be treated as being newer than any target for which it is a prerequisite.</p> +<p>If a target exists and there is neither a target rule nor an inference rule for the target, the target shall be considered +up-to-date. It shall be an error if <i>make</i> attempts to ensure that a target is up-to-date but the target does not exist and +there is neither a target rule nor an inference rule for the target.</p> +<h5><a name="tag_20_76_13_01" id="tag_20_76_13_01"></a>Makefile Syntax</h5> +<p>A makefile can contain rules, macro definitions (see <a href="#tag_20_76_13_05">Macros</a> ), include lines, and comments. There +are two kinds of rules: <i>target rules</i>, including special targets (see <a href="#tag_20_76_13_04">Target Rules</a> ), and +<i>inference rules</i> (see <a href="#tag_20_76_13_06">Inference Rules</a> ). The <i>make</i> utility shall contain a set of +built-in inference rules. If the <b>-r</b> option is present, the built-in rules shall not be used and the suffix list shall be +cleared. Additional rules of both kinds can be specified in a makefile. If a rule is defined more than once, the value of the rule +shall be that of the last one specified. Macros can also be defined more than once, and the value of the macro is specified in +<a href="#tag_20_76_13_05">Macros</a> . There are three kinds of comments: blank lines, empty lines, and a <number-sign> +(<tt>'#'</tt>) and all following characters up to the first unescaped <newline> character. Blank lines, empty lines, and +lines with <number-sign> (<tt>'#'</tt>) as the first character on the line are also known as comment lines.</p> +<p>Target and inference rules can contain <i>command lines</i>. Command lines can have a prefix that shall be removed before +execution (see <a href="#tag_20_76_13_03">Makefile Execution</a> ).</p> +<p>When an escaped <newline> (one preceded by a <backslash>) is found anywhere in the makefile except in a command line +after macro expansion, an include line, or a line immediately preceding an include line, it shall be replaced, along with any +leading white space on the next line, with a single <space>. After all macro expansion is complete, when an escaped +<newline> is found in a command line in a makefile, the command line that is executed shall contain the <backslash>, +the <newline>, and the next line, except that the first character of the next line shall not be included if it is a +<tab>. When an escaped <newline> is found in an include line or in a line immediately preceding an include line, the +behavior is unspecified.</p> +<h5><a name="tag_20_76_13_02" id="tag_20_76_13_02"></a>Include Lines</h5> +<p>If the word <b>include</b>, optionally prefixed with a <hyphen-minus> character, appears at the beginning of a line and is +followed by one or more <blank> characters, the string formed by the remainder of the line shall be processed as follows to +produce one or more pathnames:</p> +<ul> +<li> +<p>The trailing <newline>, any <blank> characters immediately preceding a comment, and any comment shall be discarded. +If the resulting string contains any double-quote characters (<tt>'"'</tt> ) the behavior is unspecified.</p> +</li> +<li> +<p>The resulting string shall be processed for macro expansion (see <a href="#tag_20_76_13_05">Macros</a> ).</p> +</li> +<li> +<p>Any <blank> characters that appear after the first non-<blank> shall be used as separators to divide the +macro-expanded string into fields. It is unspecified whether pathname expansion (see <a href= +"../utilities/V3_chap02.html#tag_19_14"><i>2.14 Pattern Matching Notation</i></a> ) is also performed.</p> +</li> +<li> +<p>If the processing of separators and optional pathname expansion results in zero non-empty fields, the behavior is unspecified. +If it results in at least one non-empty field, these fields are taken as pathnames.</p> +</li> +</ul> +<p>For each pathname so identified, in the order specified:</p> +<ul> +<li> +<p>If the pathname does not begin with a <tt>'/'</tt>, it shall be treated as relative to the current working directory of the +process, not relative to the directory containing the makefile.</p> +</li> +<li> +<p>The <i>make</i> utility shall use one of the following two methods to attempt to create the file or bring it up-to-date:</p> +<ol> +<li> +<p>The "immediate remaking" method</p> +<p>If <i>make</i> uses this method, any target rules or inference rules for the pathname that were parsed before the include line +was parsed shall be used to attempt to create the file or to bring it up-to-date before opening the file.</p> +</li> +<li> +<p>The "delayed remaking" method</p> +<p>If <i>make</i> uses this method, no attempt shall be made to create the file or bring it up-to-date until after the makefile(s) +have been read. During processing of the include line, <i>make</i> shall read the current contents of the file, if it exists, or +treat it as an empty file if it does not exist. Once the makefile(s) have been read, <i>make</i> shall use any applicable target +rule or inference rule for the pathname, regardless of whether it is parsed before or after the include line, when creating the +file or bringing it up-to-date. Additionally in this case, the new contents of the file, if it is successfully created or updated, +shall be used when processing rules for the following targets after the makefile(s) have been read:</p> +<ul> +<li> +<p>The <i>target_name</i> operands, if any.</p> +</li> +<li> +<p>The first target <i>make</i> encounters that is not a special target or an inference rule, if no <i>target_name</i> operands are +specified.</p> +</li> +<li> +<p>All targets that are prerequisites, directly or recursively, of the above targets.</p> +</li> +</ul> +</li> +</ol> +<p>If the pathname is relative, the file does not exist, and an attempt to create it using a rule has not been made and will not be +made, it is unspecified whether additional directories are searched for an existing file of the same relative pathname.</p> +<p>If, after proceeding as described above, the file still cannot be opened:</p> +<ul> +<li> +<p>If the word <b>include</b> was prefixed with a <hyphen-minus> character, the file shall be ignored.</p> +</li> +<li> +<p>Otherwise, an error shall occur.</p> +</li> +</ul> +</li> +<li> +<p>The contents of the file specified by the pathname shall be read and processed as if they appeared in the makefile in place of +the include line. If the file ends with an escaped <newline> the behavior is unspecified.</p> +</li> +<li> +<p>The file may itself contain further include lines. Implementations shall support nesting of include files up to a depth of at +least 16.</p> +</li> +</ul> +<h5><a name="tag_20_76_13_03" id="tag_20_76_13_03"></a>Makefile Execution</h5> +<p>Makefile command lines shall be processed one at a time.</p> +<p>Makefile command lines can have one or more of the following prefixes: a <hyphen-minus> (<tt>'-'</tt>), a +<commercial-at> (<tt>'@'</tt>), or a <plus-sign> (<tt>'+'</tt>). These shall modify the way in which <i>make</i> +processes the command.</p> +<dl compact> +<dd></dd> +<dt><tt>-</tt></dt> +<dd>If the command prefix contains a <hyphen-minus>, or the <b>-i</b> option is present, or the special target <b>.IGNORE</b> +has either the current target as a prerequisite or has no prerequisites, any error found while executing the command shall be +ignored.</dd> +<dt><tt>@</tt></dt> +<dd>If the command prefix contains a <commercial-at> and the <i>make</i> utility command line <b>-n</b> option is not +specified, or the <b>-s</b> option is present, or the special target <b>.SILENT</b> has either the current target as a prerequisite +or has no prerequisites, the command shall not be written to standard output before it is executed.</dd> +<dt><tt>+</tt></dt> +<dd>If the command prefix contains a <plus-sign>, the command shall be executed even if <b>-n</b>, <b>-q</b>, or <b>-t</b> is +specified.</dd> +</dl> +<p>An <i>execution line</i> is built from the command line by removing any prefix characters. Except as described under the +<commercial-at> (<tt>'@'</tt>) prefix, the execution line shall be written to the standard output, optionally preceded by a +<tab>. The execution line shall then be executed by a shell as if it were passed as the argument to the <a href= +"../functions/system.html"><i>system</i>()</a> interface, except that if errors are not being ignored then the shell <b>-e</b> +option shall also be in effect. If errors are being ignored for the command (as a result of the <b>-i</b> option, a <tt>'-'</tt> +command prefix, or a <b>.IGNORE</b> special target), the shell <b>-e</b> option shall not be in effect. The environment for the +command being executed shall contain all of the variables in the environment of <i>make</i>.</p> +<p>By default, when <i>make</i> receives a non-zero status from the execution of a command, it shall terminate with an error +message to standard error.</p> +<h5><a name="tag_20_76_13_04" id="tag_20_76_13_04"></a>Target Rules</h5> +<p>Target rules are formatted as follows:</p> +<pre> +<i>target </i><b>[</b><i>target</i><tt>...</tt><b>]</b><tt>: </tt><b>[</b><i>prerequisite</i><tt>...</tt><b>][;</b><i>command</i><b>] +[</b><tt><tab></tt><i>command</i><tt> +<tab></tt><i>command</i><tt> +...</tt><b>]</b><tt> +</tt></pre> +<p>Target entries are specified by a <blank>-separated, non-null list of targets, then a <colon>, then a +<blank>-separated, possibly empty list of prerequisites. Text following a <semicolon>, if any, and all following lines +that begin with a <tab>, are makefile command lines to be executed to update the target. The first non-empty line that does +not begin with a <tab> or <tt>'#'</tt> shall begin a new entry. Any comment line may begin a new entry.</p> +<p>Applications shall select target names from the set of characters consisting solely of slashes, hyphens, periods, underscores, +digits, and alphabetics from the portable character set (see XBD <a href="../basedefs/V1_chap06.html#tag_06_01"><i>6.1 Portable +Character Set</i></a> ). Implementations may allow other characters in target names as extensions. The interpretation of targets +containing the characters <tt>'%'</tt> and <tt>'"'</tt> is implementation-defined.</p> +<p>A target that has prerequisites, but does not have any commands, can be used to add to the prerequisite list for that target. +Only one target rule for any given target can contain commands.</p> +<p>Lines that begin with one of the following are called <i>special targets</i> and control the operation of <i>make</i>:</p> +<dl compact> +<dd></dd> +<dt><b>.DEFAULT</b></dt> +<dd>If the makefile contains this special target, the application shall ensure that it is specified with commands, but without +prerequisites. The commands shall be used by <i>make</i> if there are no other rules available to build a target.</dd> +<dt><b>.IGNORE</b></dt> +<dd>Prerequisites of this special target are targets themselves; this shall cause errors from commands associated with them to be +ignored in the same manner as specified by the <b>-i</b> option. Subsequent occurrences of <b>.IGNORE</b> shall add to the list of +targets ignoring command errors. If no prerequisites are specified, <i>make</i> shall behave as if the <b>-i</b> option had been +specified and errors from all commands associated with all targets shall be ignored.</dd> +<dt><b>.NOTPARALLEL</b></dt> +<dd><br> +The application shall ensure that this special target is specified without prerequisites or commands. When specified, <i>make</i> +shall update one target at a time, regardless of whether the <b>-j</b> <i>maxjobs</i> option is specified. If the <b>-j</b> +<i>maxjobs</i> option is specified, the option shall continue to be passed unchanged to sub-<i>make</i> invocations via +<i>MAKEFLAGS .</i></dd> +<dt><b>.PHONY</b></dt> +<dd>Prerequisites of this special target are targets themselves; these targets (known as <i>phony targets</i>) shall be considered +always out-of-date when the <i>make</i> utility begins executing. If a phony target's commands are executed, that phony target +shall then be considered up-to-date until the execution of <i>make</i> completes. Subsequent occurrences of <b>.PHONY</b> shall add +to the list of phony targets. A <b>.PHONY</b> special target with no prerequisites shall be ignored. If the <b>-t</b> option is +specified, phony targets shall not be touched. Phony targets shall not be removed if <i>make</i> receives one of the asynchronous +events explicitly described in the ASYNCHRONOUS EVENTS section.</dd> +<dt><b>.POSIX</b></dt> +<dd>The application shall ensure that this special target is specified without prerequisites or commands. If it appears as the +first non-comment line in the makefile, <i>make</i> shall process the makefile as specified by this section; otherwise, the +behavior of <i>make</i> is unspecified.</dd> +<dt><b>.PRECIOUS</b></dt> +<dd>Prerequisites of this special target shall not be removed if <i>make</i> receives one of the asynchronous events explicitly +described in the ASYNCHRONOUS EVENTS section. Subsequent occurrences of <b>.PRECIOUS</b> shall add to the list of precious files. +If no prerequisites are specified, all targets in the makefile shall be treated as if specified with <b>.PRECIOUS</b>.</dd> +<dt><b>.SCCS_GET</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +The application shall ensure that this special target is specified without prerequisites. If this special target is included in a +makefile, the commands specified with this target shall replace the default commands associated with this special target (see +<a href="#tag_20_76_13_09">Default Rules</a> ). The commands specified with this target are used to get all SCCS files that are not +found in the current directory. +<p>When source files are named in a list of prerequisites, <i>make</i> shall treat them just like any other target. Because the +source file is presumed to be present in the directory, there is no need to add an entry for it to the makefile. When a target has +no prerequisites, but is present in the directory, <i>make</i> shall assume that that file is up-to-date. If, however, an SCCS file +named <b>SCCS/s.</b><i>source_file</i> is found for a target <i>source_file</i>, <i>make</i> compares the timestamp of the target +file with that of the <b>SCCS/s.source_file</b> to ensure the target is up-to-date. If the target is missing, or if the SCCS file +is newer, <i>make</i> shall automatically issue the commands specified for the <b>.SCCS_GET</b> special target to retrieve the most +recent version. However, if the target is writable by anyone, <i>make</i> shall not retrieve a new version. <img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></p> +</dd> +<dt><b>.SILENT</b></dt> +<dd>Prerequisites of this special target are targets themselves; this shall cause commands associated with them not to be written +to the standard output before they are executed. Subsequent occurrences of <b>.SILENT</b> shall add to the list of targets with +silent commands. If no prerequisites are specified, <i>make</i> shall behave as if the <b>-s</b> option had been specified and no +commands or touch messages associated with any target shall be written to standard output.</dd> +<dt><b>.SUFFIXES</b></dt> +<dd>Prerequisites of <b>.SUFFIXES</b> shall be appended to the list of known suffixes and are used in conjunction with the +inference rules (see <a href="#tag_20_76_13_06">Inference Rules</a> ). If <b>.SUFFIXES</b> does not have any prerequisites, the +list of known suffixes shall be cleared.</dd> +<dt><b>.WAIT</b></dt> +<dd>The application shall ensure that this special target, if specified as a target, is specified without prerequisites or +commands. When <b>.WAIT</b> appears as a target, it shall have no effect. When <b>.WAIT</b> appears in a target rule as a +prerequisite, it shall not itself be treated as a prerequisite; however, <i>make</i> shall not recursively process the +prerequisites (if any) to the right of the <b>.WAIT</b> until the prerequisites (if any) to the left of it have been brought +up-to-date. Implementations may also enforce the same ordering between the affected prerequisites while processing other target +rules that have some or all of the same affected prerequisites.</dd> +</dl> +<p>The special targets <b>.IGNORE</b>, <b>.NOTPARALLEL</b>, <b>.PHONY</b>, <b>.POSIX</b>, <b>.PRECIOUS</b>, <b>.SILENT</b>, +<b>.SUFFIXES</b>, and <b>.WAIT</b> shall be specified without commands.</p> +<p>Targets and prerequisites consisting of a leading <period> followed by the uppercase letters <tt>"POSIX"</tt> and then any +other characters are reserved for future standardization. Targets and prerequisites consisting of a leading <period> followed +by one or more uppercase letters, that are not described above, are reserved for implementation extensions.</p> +<h5><a name="tag_20_76_13_05" id="tag_20_76_13_05"></a>Macros</h5> +<p>A macro can be one of two flavors, <i>delayed-expansion</i> or <i>immediate-expansion</i>.</p> +<p>The following form defines a delayed-expansion macro (replacing any previous definition of the macro named by +<i>string1</i>):</p> +<pre> +<i>string1</i><tt> = </tt><b>[</b><i>string2</i><b>]</b><tt> +</tt></pre> +<p>The following form defines an immediate-expansion macro (replacing any previous definition of the macro named by +<i>string1</i>):</p> +<pre> +<i>string1</i><tt> ::= </tt><b>[</b><i>string2</i><b>]</b><tt> +</tt></pre> +<p>The following form defines a delayed-expansion macro (replacing any previous definition of the macro named by +<i>string1</i>):</p> +<pre> +<i>string1</i><tt> :::= </tt><b>[</b><i>string2</i><b>]</b><tt> +</tt></pre> +<p>by immediately expanding macros in <i>string2</i>, if any, before assigning the value.</p> +<p>The following form defines a delayed-expansion macro (replacing any previous definition of the macro named by +<i>string1</i>):</p> +<pre> +<i>string1</i><tt> != </tt><b>[</b><i>string2</i><b>]</b><tt> +</tt></pre> +<p>by immediately expanding macros in <i>string2</i>, if any, and then executing the result as a shell command as if it were passed +as the argument to the <a href="../functions/system.html"><i>system</i>()</a> interface. The <i>make</i> utility shall capture the +standard output from the shell execution and shall remove all white space at the beginning, remove a single trailing +<newline> character (if there is one), and then replace all remaining <newline> characters with <space> +characters to produce the value assigned to the macro named by <i>string1</i>. It shall not be an error if the shell command has +non-zero exit status.</p> +<p>The following form defines a delayed-expansion macro, but only if the macro named by <i>string1</i> is not already defined:</p> +<pre> +<i>string1</i><tt> ?= </tt><b>[</b><i>string2</i><b>]</b><tt> +</tt></pre> +<p>The following form (the <i>append</i> form) appends additional text to the value of a macro:</p> +<pre> +<i>string1</i><tt> += </tt><b>[</b><i>string2</i><b>]</b><tt> +</tt></pre> +<p>When using the append form:</p> +<ul> +<li> +<p>If the macro named by <i>string1</i> does not exist, this form shall be equivalent to the delayed-expansion form</p> +<pre> +<i>string1</i><tt> = </tt><b>[</b><i>string2</i><b>]</b><tt> +</tt></pre></li> +<li> +<p>If the macro named by <i>string1</i> exists and is an immediate-expansion macro, then a <space> or <tab> character +followed by the evaluation of <i>string2</i> shall be appended to the value currently assigned to the macro named by +<i>string1</i>.</p> +</li> +<li> +<p>If the macro named by <i>string1</i> exists and is a delayed-expansion macro, then a <space> or <tab> character +followed by the unevaluated <i>string2</i> shall be appended to the value currently assigned to the macro named by +<i>string1</i>.</p> +</li> +</ul> +<p>In all cases the value of <i>string1</i> is defined as all characters from the first non-<blank> character to the last +non-<blank> character, inclusive, before the <tt>=</tt>, <tt>::=</tt>, <tt>:::=</tt>, <tt>!=</tt>, <tt>?=</tt>, or +<tt>+=</tt>. Portable applications shall ensure that a <blank> precedes the <tt>::=</tt>, <tt>:::=</tt>, <tt>!=</tt>, +<tt>?=</tt>, or <tt>+=</tt> in those forms to avoid any parsing ambiguity with implementations that permit <colon>, +<exclamation-mark>, <question-mark>, or <plus-sign> in macro names as extensions. The value of <i>string2</i> is +defined as all characters from the first non-<blank> character, if any, after the <equals-sign>, up to but not +including a comment character (<tt>'#'</tt>) or an unescaped <newline>.</p> +<p>Portable applications shall select macro names from the set of characters consisting solely of characters from the portable +filename character set. Implementations may allow other characters in macro names as extensions; however, a macro name shall not +contain an <equals-sign>, <blank>, or control character.</p> +<p>Macro expansions in <i>string1</i> of macro definition lines shall be evaluated when read. Macro expansions in <i>string2</i> of +macro definition lines shall be performed according to the form of macro definition used. In immediate-expansion forms (including +appending to an existing immediate-expansion macro), they shall be expanded in the macro definition line and the result of the +expansion shall not be scanned for further macros when the macro identified by <i>string1</i> is expanded. In delayed-expansion +forms (including appending to an existing delayed-expansion macro, and conditional assignment to a macro not previously existing), +they shall not be expanded in the macro definition line; they shall be expanded when the macro identified by <i>string1</i> is +expanded, and the result of the expansion shall be scanned for further macros. Implementations shall support at least 100 levels of +indirection.</p> +<p>Macros can appear anywhere in the makefile. Macro expansions using the forms $(<i>string1</i>) or ${<i>string1</i>} shall be +replaced by <i>string2</i>, as follows:</p> +<ul> +<li> +<p>Macros in target lines shall be evaluated when the target line is read.</p> +</li> +<li> +<p>Macros in makefile command lines shall be evaluated when the command is executed.</p> +</li> +<li> +<p>Macros in the string before the <equals-sign> in a macro definition shall be evaluated when the macro assignment is +made.</p> +</li> +<li> +<p>Immediate-expansion macros shall be evaluated immediately when the macro assignment is made, and this value shall be used as the +replacement until the immediate-expansion macro is redefined.</p> +</li> +<li> +<p>Delayed-expansion macros after the <equals-sign> in macro definitions other than the <tt>:::=</tt>, <tt>!=</tt>, and +<tt>+=</tt> forms, and after the <equals-sign> in <tt>+=</tt> form macro definitions where the macro named by <i>string1</i> +exists and is a delayed-expansion macro, shall only be evaluated when the defined macro is expanded.</p> +</li> +</ul> +<p>The parentheses or braces are optional if <i>string1</i> is a single character. The string <tt>"$$"</tt> shall be replaced by +the single character <tt>'$'</tt>, except during the immediate expansion performed for the <tt>:::=</tt> operator, where it shall +be left unmodified. If <i>string1</i> in a macro expansion contains a macro expansion, that inner macro expansion shall be +performed first and the result substituted into <i>string1</i> to produce the macro name used for the outer macro expansion.</p> +<p>Macro expansions using the forms $(<i>string1</i><b>:</b><i>subst1</i><b>=[</b><i>subst2</i><b>]</b>) or +${<i>string1</i><b>:</b><i>subst1</i><b>=[</b><i>subst2</i><b>]</b>} can be used to replace all occurrences of <i>subst1</i> with +<i>subst2</i> when the macro substitution is performed. The <i>subst1</i> to be replaced shall be recognized when it is a suffix at +the end of a word in <i>string1</i> (where a <i>word</i>, in this context, is defined to be a string delimited by the beginning of +the value, a <blank>, or a <newline>). If <i>string1</i> in a macro expansion contains a macro expansion, that inner +macro expansion shall be performed as described above and the result substituted into <i>string1</i> to produce the macro name used +for the outer macro expansion.</p> +<p>Macro expansions using the forms +$(<i>string1</i><b>:[</b><i>op</i><b>]%[</b><i>os</i><b>]=[</b><i>np</i><b>][%][</b><i>ns</i><b>]</b>) or +${<i>string1</i><b>:[</b><i>op</i><b>]%[</b><i>os</i><b>]=[</b><i>np</i><b>][%][</b><i>ns</i><b>]</b>} are called pattern macro +expansions, where <i>op</i> is the old prefix, <i>os</i> is the old suffix, <i>np</i> is the new prefix and <i>ns</i> is the new +suffix. Any item inside square brackets is optional. With this form, when the macro <i>string1</i> is expanded each +white-space-separated word that completely matches the <b>[</b><i>op</i><b>]%[</b><i>os</i><b>]</b> pattern on the left-hand side +of the <equals-sign> (<tt>'='</tt>), where the <percent> (<tt>'%'</tt>) character matches zero or more characters, +shall be replaced by the right-hand side of the <equals-sign> and shall then be further modified according to the use of +<percent> characters as described below. Any words that do not match shall be unmodified in the expansion.</p> +<p>If more than one <percent> character appears on the left-hand side of the <equals-sign> (<tt>'='</tt>), the second +and subsequent <percent> characters shall be treated as literal characters in <i>os</i>.</p> +<p>If no <percent> character appears on the right-hand side of the <equals-sign>, no further modification of the word +shall be performed. If a single <percent> character appears on the right-hand side, the <percent> character in the word +shall be replaced with the characters matched by the <percent> on the left-hand side. If more than one <percent> +character appears on the right-hand side, it is unspecified whether the first <percent> character in the word is replaced +with the characters matched by the <percent> on the left-hand side and all remaining <percent> characters are left +unchanged, or each <percent> character is replaced with the characters matched by the <percent> on the left-hand +side.</p> +<p>In both macro expansion forms, any macro expansions on the right-hand side of the <colon> shall be recursively expanded +before further examination. If this results in more than one <equals-sign> after the <colon>, the first one shall be +the separator.</p> +<p>In all forms of macro expansion, if the value of the macro named by <i>string1</i> is an empty string, or if the macro named by +<i>string1</i> does not exist, the final result shall be an empty string. <basefont size="2"></p> +<dl> +<dt><b>Note:</b></dt> +<dd>It is not safe to assume that a macro which has not intentionally been set to a specific value will not exist. See APPLICATION +USAGE for more information.</dd> +</dl> +<basefont size="3"> +<p>Macro definitions shall be taken from the following sources, in the following logical order, before the makefile(s) are +read.</p> +<ol> +<li> +<p>Macros specified on the <i>make</i> utility command line, in the order specified on the command line. It is unspecified whether +the internal macros defined in <a href="#tag_20_76_13_08">Internal Macros</a> are accepted from this source.</p> +</li> +<li> +<p>Macros defined by the <i>MAKEFLAGS</i> environment variable, in the order specified in the environment variable. It is +unspecified whether the internal macros defined in <a href="#tag_20_76_13_08">Internal Macros</a> are accepted from this +source.</p> +</li> +<li> +<p>The contents of the environment, excluding the <i>MAKEFLAGS</i> and <i>SHELL</i> variables and including the variables with null +values.</p> +</li> +<li> +<p>Macros defined in the inference rules built into <i>make</i>.</p> +</li> +</ol> +<p>Macro definitions from these sources shall not override macro definitions from a lower-numbered source. Macro definitions from a +single source (for example, the <i>make</i> utility command line, the <i>MAKEFLAGS</i> environment variable, or the other +environment variables) shall override previous macro definitions from the same source.</p> +<p>Macros defined in the makefile(s) shall override macro definitions that occur before them in the makefile(s) and macro +definitions from source 4. If the <b>-e</b> option is not specified, macros defined in the makefile(s) shall override macro +definitions from source 3. Macros defined in the makefile(s) shall not override macro definitions from source 1 or source 2.</p> +<p>Before the makefile(s) are read, all of the <i>make</i> utility command line options (except <b>-f</b> and <b>-p</b>) and +<i>make</i> utility command line macro definitions (except any for the <i>MAKEFLAGS</i> macro), not already included in the +<i>MAKEFLAGS</i> macro, shall be added to the <i>MAKEFLAGS</i> macro, quoted in an implementation-defined manner such that when +<i>MAKEFLAGS</i> is read by another instance of the <i>make</i> command, the original macro's value is recovered. Other +implementation-defined options and macros, with the exception of the <i>CURDIR</i> macro, may also be added to the <i>MAKEFLAGS</i> +macro. If this modifies the value of the <i>MAKEFLAGS</i> macro, or, if the <i>MAKEFLAGS</i> macro is modified at any subsequent +time, the <i>MAKEFLAGS</i> environment variable shall be modified to match the new value of the <i>MAKEFLAGS</i> macro. The result +of setting <i>MAKEFLAGS</i> in the Makefile is unspecified.</p> +<p>Before the makefile(s) are read, all of the <i>make</i> utility command line macro definitions (except the <i>MAKEFLAGS</i> +macro or the <i>SHELL</i> macro) shall be added to the environment of <i>make</i>. Other implementation-defined variables may also +be added to the environment of <i>make</i>. Macros defined by the <i>MAKEFLAGS</i> environment variable and macros defined in the +makefile(s) shall not be added to the environment of <i>make</i> if they are not already in its environment. With the exception of +<i>SHELL</i> (see below), it is unspecified whether macros defined in these ways update the value of an environment variable that +already exists in the environment of <i>make</i>.</p> +<p>The <i>MAKE</i> macro shall be treated specially. If <i>MAKE</i> is not defined in the environment, the <i>MAKE</i> macro shall +be provided by <i>make</i> and set to the value of <i>argv</i>[0] passed to <i>main</i>() (or equivalent, if <i>make</i> is not a C +program). If this value contains at least one <slash> and is a relative pathname, <i>make</i> shall convert it to an absolute +pathname. If <i>MAKE</i> is defined in the makefile or is specified on the command line, it shall replace the original value of the +<i>MAKE</i> macro.</p> +<p>The <i>SHELL</i> macro shall be treated specially. It shall be provided by <i>make</i> and set to the pathname of the shell +command language interpreter (see <a href="../utilities/sh.html#"><i>sh</i></a> ). The <i>SHELL</i> environment variable shall not +affect the value of the <i>SHELL</i> macro. If <i>SHELL</i> is defined in the makefile or is specified on the command line, it +shall replace the original value of the <i>SHELL</i> macro, but shall not affect the <i>SHELL</i> environment variable. Other +effects of defining <i>SHELL</i> in the makefile or on the command line are implementation-defined.</p> +<p>The <i>CURDIR</i> macro shall be treated specially. It shall be provided by <i>make</i> and set to an absolute pathname of the +current working directory when <i>make</i> is executed. The value shall be the same as the pathname that would be output by the +<a href="../utilities/pwd.html"><i>pwd</i></a> utility with either the <b>-L</b> or <b>-P</b> option; if they differ, it is +unspecified which value is used. The <i>CURDIR</i> environment variable shall not affect the value of the <i>CURDIR</i> macro +unless the <b>-e</b> option is specified. If the <b>-e</b> option is not specified, there is a <i>CURDIR</i> environment variable +set, and its value is different from the <i>CURDIR</i> macro value, the environment variable value shall be set to the macro value. +If <i>CURDIR</i> is defined in the makefile, present in the <i>MAKEFLAGS</i> environment variable, or specified on the command +line, it shall replace the original value of the <i>CURDIR</i> macro in accordance with the logical order described above, but +shall not cause <i>make</i> to change its current working directory.</p> +<h5><a name="tag_20_76_13_06" id="tag_20_76_13_06"></a>Inference Rules</h5> +<p>Inference rules are formatted as follows:</p> +<pre> +<i>target</i><tt>: +<tab></tt><i>command +</i><b>[</b><tt><tab></tt><i>command</i><b>]</b><tt> +... +<br> +</tt><i>line that does not begin with </i><tt><tab></tt><i> or </i><tt># +</tt></pre> +<p>The application shall ensure that the <i>target</i> portion is a valid target name (see <a href="#tag_20_76_13_04">Target +Rules</a> ) of the form <b>.s2</b> or <b>.s1.s2</b> (where <b>.s1</b> and <b>.s2</b> are suffixes that have been given as +prerequisites of the <b>.SUFFIXES</b> special target and s1 and s2 do not contain any <slash> or <period> characters.) +If there is only one <period> in the target, it is a single-suffix inference rule. Targets with two periods are double-suffix +inference rules. Inference rules can have only one target before the <colon>.</p> +<p>The application shall ensure that the makefile does not specify prerequisites for inference rules; no characters other than +white space shall follow the <colon> in the first line, except when creating the <i>empty rule,</i> described below. +Prerequisites are inferred, as described below.</p> +<p>Inference rules can be redefined. A target that matches an existing inference rule shall overwrite the old inference rule. An +empty rule can be created with a command consisting of simply a <semicolon> (that is, the rule still exists and is found +during inference rule search, but since it is empty, execution has no effect). The empty rule can also be formatted as follows:</p> +<pre> +<i>rule</i><tt>: ; +</tt></pre> +<p>where zero or more <blank> characters separate the <colon> and <semicolon>.</p> +<p>The <i>make</i> utility uses the suffixes of targets and their prerequisites to infer how a target can be made up-to-date. A +list of inference rules defines the commands to be executed. By default, <i>make</i> contains a built-in set of inference rules. +Additional rules can be specified in the makefile.</p> +<p>The special target <b>.SUFFIXES</b> contains as its prerequisites a list of suffixes that shall be used by the inference rules. +The order in which the suffixes are specified defines the order in which the inference rules for the suffixes are used. New +suffixes shall be appended to the current list by specifying a <b>.SUFFIXES</b> special target in the makefile. A <b>.SUFFIXES</b> +target with no prerequisites shall clear the list of suffixes. An empty <b>.SUFFIXES</b> target followed by a new <b>.SUFFIXES</b> +list is required to change the order of the suffixes.</p> +<p>Normally, the user would provide an inference rule for each suffix. The inference rule to update a target with a suffix +<b>.s1</b> from a prerequisite with a suffix <b>.s2</b> is specified as a target <b>.s2.s1</b>. The internal macros provide the +means to specify general inference rules (see <a href="#tag_20_76_13_08">Internal Macros</a> ).</p> +<p>When no target rule with commands is found to update a target, the inference rules shall be checked. The suffix of the target +(<b>.s1</b>) to be built shall be compared to the list of suffixes specified by the <b>.SUFFIXES</b> special targets. If the +<b>.s1</b> suffix is found in <b>.SUFFIXES</b>, the inference rules shall be searched in the order defined for the first +<b>.s2.s1</b> rule whose prerequisite file (<b>$*.s2</b>) exists. If the target is out-of-date with respect to this prerequisite, +the commands for that inference rule shall be executed. Prerequisites added by target rules without commands shall not affect the +selection of the applicable inference rule.</p> +<p>If the target to be built does not contain a suffix and there is no rule for the target, the single-suffix inference rules shall +be checked. The single-suffix inference rules define how to build a target if a file is found with a name that matches the target +name with one of the single suffixes appended. A rule with one suffix <b>.s2</b> is the definition of how to build target from +<b>target.s2</b>. The other suffix (<b>.s1</b>) is treated as null.</p> +<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> A +<tilde> (<tt>'~'</tt>) in the above rules refers to an SCCS file in the current directory. Thus, the rule <b>.c~.o</b> would +transform an SCCS C-language source file into an object file (<b>.o</b>). Because the <b>s.</b> of the SCCS files is a prefix, it +is incompatible with <i>make</i>'s suffix point of view. Hence, the <tt>'~'</tt> is a way of changing any file reference into an +SCCS file reference. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p> +<h5><a name="tag_20_76_13_07" id="tag_20_76_13_07"></a>Libraries</h5> +<p>If a target or prerequisite contains parentheses, it shall be treated as a member of an archive library. For the +<i>lib</i>(<i>member</i><b>.o</b>) expression <i>lib</i> refers to the name of the archive library and <i>member</i><b>.o</b> to +the member name. The application shall ensure that the member is an object file with the <b>.o</b> suffix. The modification time of +the expression is the modification time for the member as kept in the archive library; see <a href= +"../utilities/ar.html#"><i>ar</i></a> . The <b>.a</b> suffix shall refer to an archive library. The <b>.s2.a</b> rule shall be used +to update a member in the library from a file with a suffix <b>.s2</b>.</p> +<h5><a name="tag_20_76_13_08" id="tag_20_76_13_08"></a>Internal Macros</h5> +<p>The <i>make</i> utility shall maintain a set of internal macros that can be used in the commands of target and inference rules, +as described below. In order to clearly define the meaning of these macros, some clarification of the terms <i>target rule</i>, +<i>inference rule</i>, <i>target</i>, and <i>prerequisite</i> is necessary.</p> +<p>Target rules are specified by the user in a makefile for a particular target. Inference rules are user-specified or +<i>make</i>-specified rules for a particular class of target name. Explicit prerequisites are those prerequisites specified in a +makefile on target lines. Implicit prerequisites are those prerequisites that are generated when inference rules are used. +Inference rules are applied to implicit prerequisites or to explicit prerequisites that do not have target rules defined for them +in the makefile. Target rules are applied to targets specified in the makefile.</p> +<p>Before any target in the makefile is updated, each of its prerequisites (both explicit and implicit) shall be updated. This +shall be accomplished by recursively processing each prerequisite. Upon recursion, each prerequisite shall become a target itself. +Its prerequisites in turn shall be processed recursively until a target is found that has no prerequisites, or further recursion +would require applying two inference rules one immediately after the other, at which point the recursion shall stop. As an +extension, implementations may continue recursion when two or more successive inference rules need to be applied; however, if there +are multiple different chains of such rules that could be used to create the target, it is unspecified which chain is used. The +recursion shall then back up, updating each target as it goes.</p> +<p>In the definitions that follow, the word <i>target</i> refers to one of:</p> +<ul> +<li> +<p>A target specified in the makefile</p> +</li> +<li> +<p>An explicit prerequisite specified in the makefile that becomes the target when <i>make</i> processes it during recursion</p> +</li> +<li> +<p>An implicit prerequisite that becomes a target when <i>make</i> processes it during recursion</p> +</li> +</ul> +<p>In the definitions that follow, the word <i>prerequisite</i> refers to one of:</p> +<ul> +<li> +<p>An explicit prerequisite specified in the makefile for a particular target</p> +</li> +<li> +<p>An implicit prerequisite generated as a result of locating an appropriate inference rule and corresponding file that matches the +suffix of the target</p> +</li> +</ul> +<p>The internal macros are:</p> +<dl compact> +<dd></dd> +<dt>$@</dt> +<dd>The $@ macro shall evaluate to the full target name of the current target, or the archive filename part of a library archive +target. It shall be evaluated for both target and inference rules. +<p>For example, in the <b>.c.a</b> inference rule, $@ represents the out-of-date <b>.a</b> file to be built. Similarly, in a +makefile target rule to build <b>lib.a</b> from <b>file.c</b>, $@ represents the out-of-date <b>lib.a</b>.</p> +</dd> +<dt>$%</dt> +<dd>The $% macro shall be evaluated only when the current target is an archive library member of the form +<i>libname</i>(<i>member</i><b>.o</b>). In these cases, $@ shall evaluate to <i>libname</i> and $% shall evaluate to +<i>member</i><b>.o</b>. The $% macro shall be evaluated for both target and inference rules. +<p>For example, in a makefile target rule to build <b>lib.a</b>(<b>file.o</b>), $% represents <b>file.o</b>, as opposed to $@, +which represents <b>lib.a</b>.</p> +</dd> +<dt>$^</dt> +<dd>The $^ macro shall evaluate to the list of prerequisites for the current target, with any duplicates (except the first) +removed. It shall be evaluated for both target and inference rules. If the list of prerequisites of the target contains any +<b>.WAIT</b> special targets, the results of expanding $^ are unspecified. +<p>For example, in a makefile target rule to build <i>prog</i> from <b>file1.o</b>, <b>file2.o</b>, and <b>file3.o</b>, and +regardless of which prerequisites <i>prog</i> is out-of-date with respect to, $^ represents <b>file1.o</b>, <b>file2.o</b>, and +<b>file3.o</b>.</p> +</dd> +<dt>$+</dt> +<dd>The $+ macro shall be equivalent to $^, except that duplicates shall not be removed; all prerequisites shall appear in the +order they were listed in the makefile.</dd> +<dt>$?</dt> +<dd>The $? macro shall evaluate to the list of prerequisites that are newer than the current target. It shall be evaluated for both +target and inference rules. +<p>For example, in a makefile target rule to build <i>prog</i> from <b>file1.o</b>, <b>file2.o</b>, and <b>file3.o</b>, and where +<i>prog</i> is not out-of-date with respect to <b>file1.o</b>, but is out-of-date with respect to <b>file2.o</b> and +<b>file3.o</b>, $? represents <b>file2.o</b> and <b>file3.o</b>.</p> +</dd> +<dt>$<</dt> +<dd>In an inference rule, the $< macro shall evaluate to the filename whose existence allowed the inference rule to be chosen +for the target. In the <b>.DEFAULT</b> rule, the $< macro shall evaluate to the current target name. The meaning of the $< +macro is otherwise unspecified. +<p>For example, in the <b>.c.a</b> inference rule, $< represents the prerequisite <b>.c</b> file.</p> +</dd> +<dt>$*</dt> +<dd>The $* macro shall evaluate to the current target name with its suffix deleted. It shall be evaluated at least for inference +rules. +<p>For example, in the <b>.c.a</b> inference rule, $*.o represents the out-of-date <b>.o</b> file that corresponds to the +prerequisite <b>.c</b> file.</p> +</dd> +</dl> +<p>Each of the internal macros has an alternative form. When an uppercase <tt>'D'</tt> or <tt>'F'</tt> is appended to any of the +macros, the meaning shall be changed to the <i>directory part</i> for <tt>'D'</tt> and <i>filename part</i> for <tt>'F'</tt>. The +directory part is the path prefix of the file without a trailing <slash>; for the current directory, the directory part is +<tt>'.'</tt>. When the $? macro contains more than one prerequisite filename, the $(?D) and $(?F) (or ${?D} and ${?F}) macros +expand to a list of directory name parts and filename parts respectively.</p> +<p>For the target <i>lib</i>(<i>member</i><b>.o</b>) and the <b>.s2.a</b> rule, the internal macros shall be defined as:</p> +<dl compact> +<dd></dd> +<dt>$<</dt> +<dd><i>member</i><b>.s2</b></dd> +<dt>$*</dt> +<dd><i>member</i></dd> +<dt>$@</dt> +<dd><i>lib</i></dd> +<dt>$^</dt> +<dd><i>member</i><b>.s2</b></dd> +<dt>$?</dt> +<dd><i>member</i><b>.s2</b></dd> +<dt>$%</dt> +<dd><i>member</i><b>.o</b></dd> +</dl> +<h5><a name="tag_20_76_13_09" id="tag_20_76_13_09"></a>Default Rules</h5> +<p>The default rules and macro values for <i>make</i> shall achieve results that are the same as if the following were used, except +that where a result includes the literal value of a macro, this value may differ. Implementations that do not support the +C-Language Development Utilities option may omit <b>CC</b>, <b>CFLAGS</b>, <b>YACC</b>, <b>YFLAGS</b>, <b>LEX</b>, <b>LFLAGS</b>, +<b>LDFLAGS</b>, and the <b>.c</b>, <b>.y</b>, and <b>.l</b> inference rules. Implementations may provide additional macros and +rules.</p> +<pre> +<i>SPECIAL TARGETS</i><tt> +<br> +<sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup><img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +.SCCS_GET: + sccs $(SCCSFLAGS) get $(SCCSGETFLAGS) $@ +<img src="../images/opt-end.gif" alt="[Option End]" border="0"> +<br> +<sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> +.SUFFIXES: .o .c .y .l .a .sh <img src="../images/opt-start.gif" border="0">.c~ .y~ .l~ .sh~<img src="../images/opt-end.gif" +border="0"> +<br> +</tt><i>MACROS</i><tt> +<br> +AR=ar +ARFLAGS=-rv +YACC=yacc +YFLAGS= +LEX=lex +LFLAGS= +LDFLAGS= +CC=c17 +CFLAGS=-O 1 +<sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup><img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +GET=get +GFLAGS= +SCCSFLAGS= +SCCSGETFLAGS=-s +<img src="../images/opt-end.gif" alt="[Option End]" border="0"> +<br> +</tt><i>SINGLE-SUFFIX RULES</i><tt> +<br> +.c: + $(CC) $(CFLAGS) $(LDFLAGS) -o $@ $< +<br> +.sh: + cp $< $@ + chmod a+x $@ +<br> +<sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup><img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +.c~: + $(GET) $(GFLAGS) -p $< > $*.c + $(CC) $(CFLAGS) $(LDFLAGS) -o $@ $*.c +<br> +.sh~: + $(GET) $(GFLAGS) -p $< > $*.sh + cp $*.sh $@ + chmod a+x $@ +<img src="../images/opt-end.gif" alt="[Option End]" border="0"> +<br> +</tt><i>DOUBLE-SUFFIX RULES</i><tt> +<br> +.c.o: + $(CC) $(CFLAGS) -c $< +<br> +.y.o: + $(YACC) $(YFLAGS) $< + $(CC) $(CFLAGS) -c y.tab.c + rm -f y.tab.c + mv y.tab.o $@ +<br> +.l.o: + $(LEX) $(LFLAGS) $< + $(CC) $(CFLAGS) -c lex.yy.c + rm -f lex.yy.c + mv lex.yy.o $@ +<br> +.y.c: + $(YACC) $(YFLAGS) $< + mv y.tab.c $@ +<br> +.l.c: + $(LEX) $(LFLAGS) $< + mv lex.yy.c $@ +<br> +<sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup><img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +.c~.o: + $(GET) $(GFLAGS) -p $< > $*.c + $(CC) $(CFLAGS) -c $*.c +<br> +.y~.o: + $(GET) $(GFLAGS) -p $< > $*.y + $(YACC) $(YFLAGS) $*.y + $(CC) $(CFLAGS) -c y.tab.c + rm -f y.tab.c + mv y.tab.o $@ +<br> +.l~.o: + $(GET) $(GFLAGS) -p $< > $*.l + $(LEX) $(LFLAGS) $*.l + $(CC) $(CFLAGS) -c lex.yy.c + rm -f lex.yy.c + mv lex.yy.o $@ +<br> +.y~.c: + $(GET) $(GFLAGS) -p $< > $*.y + $(YACC) $(YFLAGS) $*.y + mv y.tab.c $@ +<br> +.l~.c: + $(GET) $(GFLAGS) -p $< > $*.l + $(LEX) $(LFLAGS) $*.l + mv lex.yy.c $@ +<img src="../images/opt-end.gif" alt="[Option End]" border="0"> +<br> +.c.a: + $(CC) -c $(CFLAGS) $< + $(AR) $(ARFLAGS) $@ $*.o + rm -f $*.o +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_76_14" id="tag_20_76_14"></a>EXIT STATUS</h4> +<blockquote> +<p>When the <b>-q</b> option is specified, the <i>make</i> utility shall exit with one of the following values:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>All specified targets were already up-to-date.</dd> +<dt> 1</dt> +<dd>One or more targets were not up-to-date.</dd> +<dt>>1</dt> +<dd>An error occurred.</dd> +</dl> +<p>When the <b>-q</b> option is not specified, the <i>make</i> utility shall exit with one of the following values:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>All specified targets were already up-to-date, or all commands executed to bring targets up-to-date either exited with status 0 +or had a non-zero exit status that was specified (via the <b>-i</b> option, the special target <b>.IGNORE</b>, or a <tt>'-'</tt> +command prefix) to be ignored.</dd> +<dt>>0</dt> +<dd>An error occurred, or at least one command executed to bring a target up-to-date exited with a non-zero exit status that was +not specified to be ignored.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_76_15" id="tag_20_76_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_76_16" id="tag_20_76_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>If there is a source file (such as <b>./source.c</b>) and there are two SCCS files corresponding to it (<b>./s.source.c</b> and +<b>./SCCS/s.source.c</b>), on XSI-conformant systems <i>make</i> uses the SCCS file in the current directory. However, users are +advised to use the underlying SCCS utilities (<a href="../utilities/admin.html"><i>admin</i></a>, <a href= +"../utilities/delta.html"><i>delta</i></a>, <a href="../utilities/get.html"><i>get</i></a>, and so on) or the <a href= +"../utilities/sccs.html"><i>sccs</i></a> utility for all source files in a given directory. If both forms are used for a given +source file, future developers are very likely to be confused.</p> +<p>It is incumbent upon portable makefiles to specify the <b>.POSIX</b> special target in order to guarantee that they are not +affected by local extensions.</p> +<p>The <b>-k</b> and <b>-S</b> options are both present so that the relationship between the command line, the <i>MAKEFLAGS</i> +variable, and the makefile can be controlled precisely. If the <b>k</b> flag is passed in <i>MAKEFLAGS</i> and a command is of the +form:</p> +<pre> +<tt>$(MAKE) -S foo +</tt></pre> +<p>then the default behavior is restored for the child <i>make</i>.</p> +<p>When the <b>-n</b> option is specified, it is always added to <i>MAKEFLAGS .</i> This allows a recursive <i>make</i> <b>-n</b> +<i>target</i> to be used to see all of the actions that would be taken to update <i>target</i>.</p> +<p>Because of widespread historical practice, interpreting a <number-sign> (<tt>'#'</tt>) inside a variable as the start of a +comment has the unfortunate side-effect of making it impossible to place a <number-sign> in a variable, thus forbidding +something like:</p> +<pre> +<tt>CFLAGS = -D "COMMENT_CHAR='#'" +</tt></pre> +<p>Many historical <i>make</i> utilities stop chaining together inference rules when an intermediate target is nonexistent. For +example, it might be possible for a <i>make</i> to determine that both <b>.y.c</b> and <b>.c.o</b> could be used to convert a +<b>.y</b> to a <b>.o</b>. Instead, in this case, <i>make</i> requires the use of a <b>.y.o</b> rule.</p> +<p>The standard set of default rules uses only features provided by other parts of this volume of POSIX.1-2024. They include rules +for optional utilities in this volume of POSIX.1-2024, but only rules pertaining to utilities that are provided are needed in an +implementation's default set.</p> +<p>Although <i>make</i> expands macros that do not exist to an empty string, it is not safe to assume that a macro which has not +intentionally been set to a specific value will expand to an empty string for everyone who uses the makefile. There are two reasons +for this:</p> +<ol> +<li> +<p>When another user executes <i>make</i>, they might happen to have an environment variable of the same name (which they have set +for some unrelated purpose) with a non-empty value.</p> +</li> +<li> +<p>A different implementation of <i>make</i> (or a later version of the same implementation) might have a non-empty value for the +macro in its default set.</p> +</li> +</ol> +<p>This is one aspect of a more general problem, which is that any macro that is not one for which this standard requires a default +value, and is not explicitly set either in the makefile or on the <i>make</i> command line, can have an unexpected value (or +unexpectedly not exist) when the makefile is used by a different user or with a different <i>make</i> implementation.</p> +<p>For this reason, it is recommended that makefile authors do not design makefile schemes in which values for non-standard macros +are obtained from the user's environment variables. Safer methods of allowing users to configure macro values include:</p> +<ul> +<li> +<p>Setting the macros to default values in a <i>make</i> include file where the user can edit the values.</p> +</li> +<li> +<p>Executing <i>make</i> from one or more wrapper scripts which set macro values on the command line (and which do not obtain those +values from environment variables).</p> +</li> +</ul> +<p>Makefile authors who follow this recommendation may wish to check for any macros they have overlooked by using a <i>make</i> +implementation that provides, as an extension, a command-line option that causes <i>make</i> to report attempts to expand (or +append to) macros that do not exist. Users of makefiles written by others can also benefit from the use of such an option to detect +the opposite problem (where the author had a macro being set from an environment variable but the user does not have the variable +set). This can avoid misbehaviors that would otherwise be hard to debug, such as a file-processing utility reading from standard +input because it was not given any pathnames to process.</p> +<p>Makefile authors who choose not to follow the recommendation can minimize the risk of misbehavior by ensuring all non-standard +macros have names that begin with a suitable project-specific prefix.</p> +<p>Use of the <b>-e</b> option is strongly discouraged, as it makes the problem discussed above even more likely by introducing the +possibility of unexpected values occurring even for macros set in the makefile. If a specific macro needs a value from the +environment to override a value set in the makefile, it is safer to set just that macro on the command line, using for example +<tt>make MYPROJ_FOO="$MYPROJ_FOO"</tt>. Alternatively, the makefile can be modified to use the <tt>?=</tt> assignment operator +for that macro.</p> +<p>Delayed-expansion macros are evaluated when they are used rather than when they are defined. Therefore:</p> +<pre> +<tt>MACRO = </tt><i>value1</i><tt> +Immed ::= $(MACRO) +DELAY = $(MACRO) +MACRO = </tt><i>value2</i><tt> +<br> +target: + echo $(Immed) $(DELAY) +</tt></pre> +<p>would produce <tt>"value1 value2"</tt>, since <b>Immed</b> was expanded while <b>MACRO</b> was <i>value1</i>, but <b>DELAY</b> +was not expanded until it was needed in the <a href="../utilities/echo.html"><i>echo</i></a> command line when <b>MACRO</b> was +<i>value2</i>.</p> +<p>Because the behavior of the <tt>+=</tt> assignment differs depending on whether the macro being appended to is a +delayed-expansion macro or an immediate-expansion macro, it is recommended that when both macro types are used in a set of multiple +makefiles and include files, a naming convention is adopted to distinguish the two macro types. This avoids any confusion about +whether <tt>+=</tt> will append the expanded or unexpanded value. A suitable convention might be to name delayed-expansion macros +using uppercase and underscore characters and immediate-expansion macros using a name that contains at least one lowercase +character.</p> +<p>Some historical applications have been known to intermix <i>target_name</i> and <i>macro=name</i> operands on the command line, +expecting that all of the macros are processed before any of the targets are dealt with. Conforming applications do not do this, +although some backwards-compatibility support may be included in some implementations.</p> +<p>The following characters in filenames may give trouble: <tt>'='</tt>, <tt>':'</tt>, <tt>'`'</tt>, single-quote, and +<tt>'@'</tt>. In include filenames, pattern matching characters and <tt>'"'</tt> should also be avoided, as they may be treated as +special by some implementations.</p> +<p>For inference rules, the descriptions of $< and $? seem similar. However, an example shows the minor difference. In a +makefile containing:</p> +<pre> +<tt>foo.o: foo.h +</tt></pre> +<p>if <b>foo.h</b> is newer than <b>foo.o</b>, yet <b>foo.c</b> is older than <b>foo.o</b>, the built-in rule to make <b>foo.o</b> +from <b>foo.c</b> is used, with $< equal to <b>foo.c</b> and $? equal to <b>foo.h</b>. If <b>foo.c</b> is also newer than +<b>foo.o</b>, $< is equal to <b>foo.c</b> and $? is equal to <b>foo.h foo.c</b>.</p> +<p>As a consequence of the general rules for target updating, a useful special case is that if a target has no prerequisites and no +commands, and the target of the rule is a nonexistent file, then <i>make</i> acts as if this target has been updated whenever its +rule is run. <basefont size="2"></p> +<dl> +<dt><b>Note:</b></dt> +<dd>This implies that all targets depending on this one will always have their commands run.</dd> +</dl> +<basefont size="3"> +<p>Shell command sequences like <tt>make; cp original copy; make</tt> may have problems on filesystems where +the timestamp resolution is the minimum (1 second) required by the standard and where <i>make</i> considers identical timestamps to +be up-to-date. Conversely, rules like <tt>copy: original; cp -p original copy</tt> will result in +redundant work on <i>make</i> implementations that consider identical timestamps to be out-of-date.</p> +<p>The requirements relating to dynamic include files (ones that have rules to create or update them) allow two different methods +of implementing them, as explained in RATIONALE below. In order to write a set of makefiles and include files (both dynamic and +static) that work with both methods, applications need to ensure the following:</p> +<ul> +<li> +<p>Rules containing commands for creating dynamic include files (and any prerequisites) precede the include line that will cause +the file to be read.</p> +</li> +<li> +<p>Include lines and rules for creating dynamic include files do not depend on the contents of any earlier dynamic include file. +For example, defining a macro in a dynamic include file and using that macro in a later include line should be avoided (unless the +later include line is itself inside the dynamic include file).</p> +</li> +<li> +<p>One of the rules used in creating a dynamic include file, or a dynamic prerequisite of an include file, contains commands to +create its target and does not ignore creation failure.</p> +</li> +</ul> +<p>Note that although the first point above appears at first sight to preclude a dynamic include file that defines its own +prerequisites, this can be achieved by having two include lines that name the same file (provided the rules in the file do not +contain command lines), as shown in EXAMPLES.</p> +<p>This standard does not specify precedence between macro definition and include directives. Thus, the behavior of:</p> +<pre> +<tt>include =foo.mk +</tt></pre> +<p>is unspecified. To define a variable named include, either the white space before the <equal-sign> should be removed, or +another macro should be used, as in:</p> +<pre> +<tt>INCLUDE_NAME = include +$(INCLUDE_NAME) =foo.mk +</tt></pre> +<p>On the other hand, if the intent is to include a file which starts with an <equal-sign>, either the filename should be +changed to <tt>./=foo.mk</tt>, or the makefile should be written as:</p> +<pre> +<tt>INCLUDE_FILE = =foo.mk +include $(INCLUDE_FILE) +</tt></pre> +<p>It is important to be careful when using parallel execution (the <b>-j</b> option) and archives. If multiple <tt>$(AR)</tt> +commands run at the same time on the same archive file, they will not know about each other and can corrupt the file. If the +<b>-j</b> option is used, it is necessary to use <b>.WAIT</b> in between archive member prerequisites to prevent this (see +EXAMPLES).</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_76_17" id="tag_20_76_17"></a>EXAMPLES</h4> +<blockquote> +<ol> +<li> +<p>The following command:</p> +<pre> +<tt>make +</tt></pre> +<p>makes the first target found in the makefile.</p> +</li> +<li> +<p>The following command:</p> +<pre> +<tt>make junk +</tt></pre> +<p>makes the target <b>junk</b>.</p> +</li> +<li> +<p>The following makefile says that <b>pgm</b> depends on two files, <b>a.o</b> and <b>b.o</b>, and that they in turn depend on +their corresponding source files (<b>a.c</b> and <b>b.c</b>), and a common file <b>incl.h</b>:</p> +<pre> +<tt>.POSIX: +pgm: a.o b.o + c17 a.o b.o -o pgm +a.o: incl.h a.c + c17 -c a.c +b.o: incl.h b.c + c17 -c b.c +</tt></pre></li> +<li> +<p>The following is an extended version of the previous example that generates <i>make</i> include files containing the +prerequisites for each object file. The include file also defines its own prerequisites, and the makefile arranges that these are +used by including the file twice. With implementations of <i>make</i> that create include files during parsing, the first time +<i>make</i> is run the file does not exist but the use of the <hyphen-minus> prefix on the first include line means it is +ignored and is then generated by the rule preceding the second include line. On subsequent runs, if any of the source or header +files previously identified has changed, the include file will be updated. There are other ways of updating the include file when +headers change, but they involve recursive execution of <i>make</i>.</p> +<pre> +<tt>.POSIX: +.SUFFIXES: .c .d + +OFILES = a.o b.o + +pgm: $(OFILES) + c17 $(OFILES) -o pgm +a.o: + c17 -c a.c +b.o: + c17 -c b.c + +-include $(OFILES:.o=.d) +.c.d: + +{ \ + set -o pipefail; cfile=$<; ofile=$${cfile%.c}.o; \ + printf '%s %s: %s ' "$$ofile" $@ $<; \ + c17 -E $< | LC_ALL=C sed -n \ + '/^#[[:blank:]]*[[:digit:]]/s/.*"\([^"]*\.h\)".*/\1/p' | \ + LC_ALL=C sort -u | tr '\n' ' '; \ + echo; \ + } > $@ +include $(OFILES:.o=.d) +</tt></pre> +<p>This example does not cope with a header file being removed (<a href="../utilities/make.html"><i>make</i></a> will complain that +it does not know how to make it), necessitating that <b>*.d</b> be removed and the <i>make</i> run again. Alternatively, this can +be handled by updating the commands which generate the <b>.d</b> file so that they add an empty target rule for each of its +prerequisites.</p> +</li> +<li> +<p>An example for making optimized <b>.o</b> files from <b>.c</b> files is:</p> +<pre> +<tt>.c.o: + c17 -c -O 1 $*.c +</tt></pre> +<p>or:</p> +<pre> +<tt>.c.o: + c17 -c -O 1 $< +</tt></pre></li> +<li> +<p>The most common use of the archive interface follows. Here, it is assumed that the source files are all C-language source:</p> +<pre> +<tt>lib.a: lib.a(file1.o) .WAIT lib.a(file2.o) .WAIT lib.a(file3.o) + @echo lib.a is now up-to-date +</tt></pre> +<p>The <b>.c.a</b> rule is used to make <b>file1.o</b>, <b>file2.o</b>, and <b>file3.o</b> and insert them into <b>lib.a</b>.</p> +</li> +<li> +<p>The treatment of escaped <newline> characters throughout the makefile is historical practice. For example, the inference +rule:</p> +<pre> +<tt>.c.o\ +: +</tt></pre> +<p>works, and the macro:</p> +<pre> +<tt>f= bar baz\ + biz +a: + echo ==$f== +</tt></pre> +<p>echoes <tt>"==bar baz biz=="</tt>.</p> +<p>If $? were:</p> +<pre> +<tt>/usr/include/stdio.h /usr/include/unistd.h foo.h +</tt></pre> +<p>then $(?D) would be:</p> +<pre> +<tt>/usr/include /usr/include . +</tt></pre> +<p>and $(?F) would be:</p> +<pre> +<tt>stdio.h unistd.h foo.h +</tt></pre></li> +<li> +<p>The contents of the built-in rules can be viewed by running:</p> +<pre> +<tt>make -p -f /dev/null 2>/dev/null +</tt></pre></li> +<li> +<p>With the following makefile, <tt>make -j 10 all</tt> may bring <tt>one</tt> and <tt>two</tt> up-to-date in parallel despite the +<b>.WAIT</b> in the prerequisite list for <tt>foo</tt>. This is because the <b>.WAIT</b> does not stop <i>make</i> from recursively +processing <tt>bar</tt> and its prerequisites in parallel. However, if only <tt>foo</tt> is specified (<tt>make -j 10 foo</tt>), +<i>make</i> will wait for <tt>one</tt> to be brought up-to-date before bringing <tt>two</tt> up-to-date. Note also that the +<b>.WAIT</b> does not create a prerequisite relationship between <tt>one</tt> and <tt>two</tt>, so <tt>make -j 10 two</tt> will not +build <tt>one</tt>.</p> +<pre> +<tt>all: foo bar +foo: one .WAIT two +bar: one two +foo bar one two: ; @echo $@ +</tt></pre></li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_76_18" id="tag_20_76_18"></a>RATIONALE</h4> +<blockquote> +<p>The <i>make</i> utility described in this volume of POSIX.1-2024 is intended to provide the means for changing portable source +code into executables that can be run on a POSIX.1-2024-conforming system. It reflects the most common features present in System V +and BSD <i>make</i>s.</p> +<p>Historically, the <i>make</i> utility has been an especially fertile ground for vendor and research organization-specific syntax +modifications and extensions. Examples include:</p> +<ul> +<li> +<p>Syntax supporting parallel execution (such as from various multi-processor vendors, GNU, and others)</p> +</li> +<li> +<p>Additional "operators" separating targets and their prerequisites (System V, BSD, and others)</p> +</li> +<li> +<p>Modifications of the meaning of internal macros when referencing libraries (BSD and others)</p> +</li> +<li> +<p>Using a single instance of the shell for all of the command lines of the target (BSD and others)</p> +</li> +<li> +<p>Allowing <space> characters as well as <tab> characters to delimit command lines (BSD)</p> +</li> +<li> +<p>Adding C preprocessor-style "include" and "ifdef" constructs (System V, GNU, BSD, and others)</p> +</li> +<li> +<p>Remote execution of command lines (Sprite and others)</p> +</li> +<li> +<p>Specifying additional special targets (BSD, System V, and most others)</p> +</li> +<li> +<p>Specifying an alternate shell to use to process commands.</p> +</li> +</ul> +<p>Additionally, many vendors and research organizations have rethought the basic concepts of <i>make</i>, creating vastly +extended, as well as completely new, syntaxes. Each of these versions of <i>make</i> fulfills the needs of a different community of +users; it is unreasonable for this volume of POSIX.1-2024 to require behavior that would be incompatible (and probably inferior) to +historical practice for such a community.</p> +<p>In similar circumstances, when the industry has enough sufficiently incompatible formats as to make them irreconcilable, this +volume of POSIX.1-2024 has followed one or both of two courses of action. Commands have been renamed (<a href= +"../utilities/cksum.html"><i>cksum</i></a>, <a href="../utilities/echo.html"><i>echo</i></a>, and <a href= +"../utilities/pax.html"><i>pax</i></a>) and/or command line options have been provided to select the desired behavior (<a href= +"../utilities/grep.html"><i>grep</i></a>, <a href="../utilities/od.html"><i>od</i></a>, and <a href= +"../utilities/pax.html"><i>pax</i></a>).</p> +<p>Because the syntax specified for the <i>make</i> utility was, by and large, a subset of the syntaxes accepted by almost all +versions of <i>make</i> when the original IEEE Std 1003.2-1992 shell and utilities standard was being developed, it was +decided that it would be counter-productive to change the name. And since the makefile itself is a basic unit of portability, it +would not be completely effective to reserve a new option letter, such as <i>make</i> <b>-P</b>, to achieve the portable behavior. +Therefore, the special target <b>.POSIX</b> was added to the makefile, allowing users to specify "standard" behavior. This +special target does not preclude extensions in the <i>make</i> utility, nor does it preclude such extensions being used by the +makefile specifying the target; it does, however, preclude any extensions from being applied that could alter the behavior of +previously valid syntax; such extensions must be controlled via command line options or new special targets. It is incumbent upon +portable makefiles to specify the <b>.POSIX</b> special target in order to guarantee that they are not affected by local +extensions.</p> +<p>The portable version of <i>make</i> described in this reference page is not intended to be the state-of-the-art software +generation tool and, as such, some newer and more leading-edge features have not been included. An attempt has been made to +describe the portable makefile in a manner that does not preclude such extensions as long as they do not disturb the portable +behavior described here.</p> +<p>When the <b>-n</b> option is specified, it is always added to <i>MAKEFLAGS .</i> This allows a recursive <i>make</i> <b>-n</b> +<i>target</i> to be used to see all of the actions that would be taken to update <i>target</i>.</p> +<p>The definition of <i>MAKEFLAGS</i> allows both the System V letter string and the BSD command line formats. The two formats are +sufficiently different to allow implementations to support both without ambiguity.</p> +<p>Early proposals stated that an "unquoted" <number-sign> was treated as the start of a comment. The <i>make</i> utility +does not pay any attention to quotes. A <number-sign> starts a comment regardless of its surroundings.</p> +<p>The text about "other implementation-defined pathnames may also be tried" in addition to <b>./makefile</b> and +<b>./Makefile</b> is to allow such extensions as <b>SCCS/s.Makefile</b> and other variations. It was made an implementation-defined +requirement (as opposed to unspecified behavior) to highlight surprising implementations that might select something unexpected +like <b>/etc/Makefile</b>. XSI-conformant systems also try <b>./s.makefile</b>, <b>SCCS/s.makefile</b>, <b>./s.Makefile</b>, and +<b>SCCS/s.Makefile</b>.</p> +<p>The default rules are based on System V. The default <b>CC=</b> value is <a href="../utilities/c17.html"><i>c17</i></a> instead +of <i>cc</i> because this volume of POSIX.1-2024 does not standardize the utility named <i>cc</i>. Thus, every conforming +application would be required to define <b>CC=</b><a href="../utilities/c17.html"><i>c17</i></a> to expect to run. There is no +advantage conferred by the hope that the makefile might hit the "preferred" compiler because this cannot be guaranteed to work. +Also, since the portable makescript can only use the <a href="../utilities/c17.html"><i>c17</i></a> options, no advantage is +conferred in terms of what the script can do. It is a quality-of-implementation issue as to whether <a href= +"../utilities/c17.html"><i>c17</i></a> is as valuable as <i>cc</i>.</p> +<p>Implementations are permitted to include any macro of their choosing in the default set. However, they are encouraged to keep +such additions to a minimum in order to reduce the risk of name clashes with user macros.</p> +<p>Implementations are encouraged to provide, as an extension, a command-line option that causes <i>make</i> to report attempts to +expand (or append to) macros that do not exist. See APPLICATION USAGE for the intended use cases of such an option.</p> +<p>The <b>-d</b> option to <i>make</i> is frequently used to produce debugging information, but is too implementation-defined to +add to this volume of POSIX.1-2024.</p> +<p>The <b>-p</b> option is not passed in <i>MAKEFLAGS</i> on most historical implementations and to change this would cause many +implementations to break without sufficiently increased portability.</p> +<p>Commands that begin with a <plus-sign> (<tt>'+'</tt>) are executed even if the <b>-n</b> option is present. Based on the +GNU version of <i>make</i>, the behavior of <b>-n</b> when the <plus-sign> prefix is encountered has been extended to apply +to <b>-q</b> and <b>-t</b> as well. The System V convention of forcing command execution with <b>-n</b> when the command line of a +target expands the <i>MAKE</i> macro was not adopted in earlier versions of this standard, but it is now required because it has +become widespread existing practice.</p> +<p>The double <colon> in the target rule format is supported in BSD systems to allow more than one target line containing the +same target name to have commands associated with it. Since this is not functionality described in the SVID or XPG3 it has been +allowed as an extension, but not mandated.</p> +<p>The default rules are provided with text specifying that the built-in rules shall be the same as if the listed set were used. +The intent is that implementations should be able to use the rules without change, but will be allowed to alter them in ways that +do not affect the primary behavior.</p> +<p>One point of discussion was whether to drop the default rules list from this volume of POSIX.1-2024. They provide convenience, +but do not enhance portability of applications. The prime benefit is in portability of users who wish to type <i>make</i> +<i>command</i> and have the command build from a <b>command.c</b> file.</p> +<p>The historical <i>MAKESHELL</i> feature, and related features provided by other <i>make</i> implementations, were omitted. In +some implementations it is used to let a user override the shell to be used to run <i>make</i> commands. This was confusing; for a +portable <i>make</i>, the shell should be chosen by the makefile writer. Further, a makefile writer cannot require an alternate +shell to be used and still consider the makefile portable. While it would be possible to standardize a mechanism for specifying an +alternate shell, existing implementations do not agree on such a mechanism, and makefile writers can already invoke an alternate +shell by specifying the shell name in the rule for a target; for example:</p> +<pre> +<tt>python -c "foo" +</tt></pre> +<p>The <i>make</i> utilities in most historical implementations process the prerequisites of a target in left-to-right order, and +the makefile format requires this. It supports the standard idiom used in many makefiles that produce <a href= +"../utilities/yacc.html"><i>yacc</i></a> programs; for example:</p> +<pre> +<tt>foo: y.tab.o lex.o main.o + $(CC) $(CFLAGS) -o $</tt>@<tt> y.tab.o lex.o main.o +</tt></pre> +<p>In this example, if <i>make</i> chose any arbitrary order, the <b>lex.o</b> might not be made with the correct <b>y.tab.h</b>. +Although there may be better ways to express this relationship, it is widely used historically. Implementations that desire to +update prerequisites in parallel should require an explicit extension to <i>make</i> or the makefile format to accomplish it, as +described previously.</p> +<p>The algorithm for determining a new entry for target rules is partially unspecified. Some historical <i>make</i>s allow comment +lines (including blank and empty lines) within the collection of commands marked by leading <tab> characters. A conforming +makefile must ensure that each command starts with a <tab>, but implementations are free to ignore comments without +triggering the start of a new entry.</p> +<p>The ASYNCHRONOUS EVENTS section includes having SIGTERM and SIGHUP, along with the more traditional SIGINT and SIGQUIT, remove +the current target unless directed not to do so. SIGTERM and SIGHUP were added to parallel other utilities that have historically +cleaned up their work as a result of these signals. When <i>make</i> receives any signal other than SIGQUIT, it is required to +resend itself the signal it received so that it exits with a status that reflects the signal. The results from SIGQUIT are +partially unspecified because, on systems that create a file named <b>core</b> upon receipt of SIGQUIT, the <b>core</b> file from +<i>make</i> would conflict with a <b>core</b> file from the command that was running when the SIGQUIT arrived. The main concern was +to prevent damaged files from appearing up-to-date when <i>make</i> is rerun.</p> +<p>The <b>.PRECIOUS</b> special target was extended to affect all targets globally (by specifying no prerequisites). The +<b>.IGNORE</b> and <b>.SILENT</b> special targets were extended to allow prerequisites; it was judged to be more useful in some +cases to be able to turn off errors or echoing for a list of targets than for the entire makefile. These extensions to <i>make</i> +in System V were made to match historical practice from the BSD <i>make</i>.</p> +<p>Macros are not exported to the environment of commands to be run. This was never the case in any historical <i>make</i> and +would have serious consequences. The environment is the same as the environment to <i>make</i> except that <i>MAKEFLAGS</i> and +macros defined on the <i>make</i> command line are added, and except that macros defined by the <i>MAKEFLAGS</i> environment +variable and macros defined in the makefile(s) may update the value of an existing environment variable (other than <i>SHELL +).</i></p> +<p>Some implementations do not use <a href="../functions/system.html"><i>system</i>()</a> for all command lines, as required by the +portable makefile format; as a performance enhancement, they select lines without shell metacharacters for direct execution by +<a href="../functions/execve.html"><i>execve</i>()</a>. There is no requirement that <a href= +"../functions/system.html"><i>system</i>()</a> be used specifically, but merely that the same results be achieved. The +metacharacters typically used to bypass the direct <a href="../functions/execve.html"><i>execve</i>()</a> execution have been any +of:</p> +<pre> +<tt>= | ^ ( ) ; & < > * ? [ ] : $ ` ' " \ \n +</tt></pre> +<p>The default in some advanced versions of <i>make</i> is to group all the command lines for a target and execute them using a +single shell invocation; the System V method is to pass each line individually to a separate shell. The single-shell method has the +advantages in performance and the lack of a requirement for many continued lines. However, converting to this newer method has +caused portability problems with many historical makefiles, so the behavior with the POSIX makefile is specified to be the same as +that of System V. It is suggested that the special target <b>.ONESHELL</b> be used as an implementation extension to achieve the +single-shell grouping for a target or group of targets.</p> +<p>Novice users of <i>make</i> have had difficulty with the historical need to start commands with a <tab>. Since it is often +difficult to discern differences between <tab> and <space> characters on terminals or printed listings, confusing bugs +can arise. In early proposals, an attempt was made to correct this problem by allowing leading <blank> characters instead of +<tab> characters. However, implementors reported many makefiles that failed in subtle ways following this change, and it is +difficult to implement a <i>make</i> that unambiguously can differentiate between macro and command lines. There is extensive +historical practice of allowing leading <space> characters before macro definitions. Forcing macro lines into column 1 would +be a significant backwards-compatibility problem for some makefiles. Therefore, historical practice was restored.</p> +<p>There is substantial variation in the handling of include lines by different implementations. However, there is enough +commonality for the standard to be able to specify a minimum set of requirements that allow the feature to be used portably. Known +variations have been explicitly called out as unspecified behavior in the description.</p> +<p>The System V dynamic dependency feature was not included. It would support:</p> +<pre> +<tt>cat: $$@.c +</tt></pre> +<p>that would expand to;</p> +<pre> +<tt>cat: cat.c +</tt></pre> +<p>This feature exists only in the new version of System V <i>make</i> and, while useful, is not in wide usage. This means that +macros are expanded twice for prerequisites: once at makefile parse time and once at target update time.</p> +<p>Consideration was given to adding metarules to the POSIX <i>make</i>. This would make <b>%.o: %.c</b> the same as +<b>.c.o:</b>. This is quite useful and available from some vendors, but it would cause too many changes to this <i>make</i> to +support. It would have introduced rule chaining and new substitution rules. However, the rules for target names have been set to +reserve the <tt>'%'</tt> and <tt>'"'</tt> characters. These are traditionally used to implement metarules and quoting of target +names, respectively. Implementors are strongly encouraged to use these characters only for these purposes.</p> +<p>A request was made to extend the suffix delimiter character from a <period> to any character. The metarules feature in +newer <i>make</i>s solves this problem in a more general way. This volume of POSIX.1-2024 is staying with the more conservative +historical definition.</p> +<p>The standard output format for the <b>-p</b> option is not described because it is primarily a debugging option and because the +format is not generally useful to programs. In historical implementations the output is not suitable for use in generating +makefiles. The <b>-p</b> format has been variable across historical implementations. Therefore, the definition of <b>-p</b> was +only to provide a consistently named option for obtaining <i>make</i> script debugging information.</p> +<p>Some historical implementations have not cleared the suffix list with <b>-r</b>.</p> +<p>Implementations should be aware that some historical applications have intermixed <i>target_name</i> and +<i>macro</i>=<i>value</i> operands on the command line, expecting that all of the macros are processed before any of the targets +are dealt with. Conforming applications do not do this, but some backwards-compatibility support may be warranted.</p> +<p>Empty inference rules are specified with a <semicolon> command rather than omitting all commands, as described in an early +proposal. The latter case has no traditional meaning and is reserved for implementation extensions, such as in GNU <i>make</i>.</p> +<p>Earlier versions of this standard defined comment lines only as lines with <tt>'#'</tt> as the first character. Many places then +talked about comments, blank lines, and empty lines; but some places inadvertently only mentioned comments when blank lines and +empty lines had also been accepted in all known implementations. The standard now defines comment lines to be blank lines, empty +lines, and lines starting with a <tt>'#'</tt> character and explicitly lists cases where blank lines and empty lines are not +acceptable.</p> +<p>On most historic systems, the <i>make</i> utility considered a target with a prerequisite that had an identical timestamp as +up-to-date. One implementation of <i>make</i> treated it as out-of-date. Note that up-to-date and out-of-date are antonyms. The +standard now allows either behavior, but implementations are encouraged to treat such targets as out-of-date. This is especially +important on file systems where the timestamp resolution is the minimum (1 second) required by the standard. All implementations of +<i>make</i> should make full use of the finest timestamp resolution available on the file systems holding targets and prerequisites +to ensure that targets are up-to-date even for prerequisite files with timestamps that were updated within the same second. +However, if the timestamp resolutions of the file systems containing a target and a prerequisite are different, the timestamp with +the more precise resolution should be rounded down to the resolution of the less precise timestamp for the comparison.</p> +<p>The traditional semantics of delayed-expansion macros have often been the source of subtle bugs for makefile writers not aware +of those semantics. Furthermore, in implementations that support an extension of assigning the output of an arbitrary command to a +macro definition, the use of delayed-expansion macros could result in an undesirable growth in execution time, as each use of the +macro would re-run the arbitrary command. Historically, several implementations independently developed a form of immediate +expansion, usually via the operator <tt>":="</tt>, so that execution of an arbitrary command happens once at the definition of the +macro rather than each use of the macro; however, there are subtle differences in the expansion rules of those various +implementations when the expanded value of <i>string2</i> contained a <tt>'$'</tt>. Other implementations used the operator +<tt>":="</tt> for conditional expansion, altogether unrelated to immediate-expansion macro definition.</p> +<p>The standard developers felt that immediate-expansion semantics were useful enough to standardize, but requiring the semantics +of any one implementation of <tt>":="</tt> would cause confusion in makefiles written for other implementation semantics, +necessitating a reader to determine if <tt>.POSIX:</tt> had been specified at the beginning of the file (or worse, at the beginning +of some other file that then includes the fragment in question) to know which semantics would be in use. Therefore, the standard +developers opted to require two new operators, <tt>"::="</tt> and <tt>":::="</tt>, with specific semantics; the <tt>"::="</tt> +operator has semantics closest to the GNU <i>make</i> implementation of <tt>":="</tt>, where <tt>'$'</tt> characters occurring in +the immediate expansion of <i>string2</i> are not further expanded in subsequent use of the macro, and the <tt>":::="</tt> operator +has semantics closest to the BSD <i>make</i> and <i>smake</i> implementations of <tt>":="</tt>, where immediate expansion is +performed when assigning to a delayed-expansion macro and <tt>"$$"</tt> is preserved. It was felt that other implementations could +easily support the required semantics.</p> +<p>Implementations that previously provided <tt>":="</tt> as an extension are encouraged to leave this extension intact, with no +change in the implementation's particular semantics, to avoid breaking non-portable makefiles that had been targeting that +particular implementation. A portable makefile, with <tt>.POSIX:</tt> specified at the beginning, should not use the <tt>":="</tt> +operator.</p> +<p>Traditionally, constructs such as</p> +<pre> +<tt>DIR: FORCE + (commands) +FORCE: +</tt></pre> +<p>were used to allow <tt>make DIR</tt> to always run <tt>(commands)</tt>; however, this depended on the user never creating a file +named <b>FORCE</b>. The addition of the .B~.PHONY special target provides a more efficient manner of providing a target whose +commands are always run, and where the user cannot create a file that influences the behavior in an unexpected manner.</p> +<p>This standard allows two different methods of creating include files or bringing them up-to-date, reflecting established +practice in SunPro <i>make</i> and GNU <i>make</i>. The former performs this action during parsing, before the include file is +opened. The latter delays performing the action until after all makefiles have been read. Implementors who opt for the "delayed +remaking" method should be aware of the following potential issues:</p> +<ul> +<li> +<p>Diagnostic messages about missing include files must be deferred until the final exit status is known. Note that this is a +conformance issue, not just a quality of implementation issue.</p> +</li> +<li> +<p>If the way <i>make</i> handles using updated include file contents is to start over after include files have been made +up-to-date, it is possible for a poorly written makefile to cause <i>make</i> to enter a sequence of restarts where nothing changes +each time, resulting in the sequence continuing indefinitely unless the situation is detected. Implementors are encouraged to +include a mechanism for detecting and reporting this, rather than allowing <i>make</i> to consume an arbitrary amount of system +resource until it is forcibly terminated.</p> +</li> +<li> +<p>If <i>make</i> uses this start-over method, makefile contents read from a pipe on standard input or from a FIFO must be copied +to a temporary file, and when <i>make</i> starts over it must use this file instead.</p> +</li> +<li> +<p>If <i>make</i> starts over by executing itself using the <i>exec</i> family of functions, the need to replace <tt>'-'</tt> or +the pathnames of FIFOs with the pathnames of temporary files can lead to the <i>exec</i> call failing with an [E2BIG] error if the +original execution was close to the {ARG_MAX} limit. Although this is a quality of implementation issue, not a conformance issue +(since the general rules for utility errors allow utilities to fail when they encounter a variety of internal errors - see <a href= +"../utilities/V3_chap01.html#tag_18_04"><i>1.4 Utility Description Defaults</i></a> ), implementors are encouraged to explore ways +to prevent it, such as passing information via a temporary file instead of on the command line when an [E2BIG] error has occurred. +Another solution might be to jump (e.g. using <a href="../functions/siglongjmp.html"><i>siglongjmp</i>()</a>) back to the start of +<i>main</i>() as the way to start over. Making a recursive call to <i>main</i>() is not recommended, as that would run into the +stack limit if sufficiently many restarts are needed.</p> +</li> +</ul> +<p>This standard specifies that a non-existent include file is first created if possible, and only if not possible can other +directories be searched. Historical versions of GNU <i>make</i> first searched the include directories, then attempted to create +the include file. This behavior was not considered suitable for standardization as it means writers of portable applications have +to use absolute pathnames for all include files that need to be created via a rule (because they can never be sure what relative +pathnames are safe to use, since a file with the same relative pathname might happen to exist in one of the searched directories +when installing the application on a new system). Note, however, that this only applies to directories searched by default. If an +application uses an extension to specify that one or more directories are searched, this standard does not place any constraints on +when the specified directories are searched.</p> +<p>This standard specifies a way for portable applications to request parallel updating of targets with commands by using the +<b>-j</b> <i>maxjobs</i> option. This feature is described in terms of a token pool initially containing up to <i>maxjobs</i> - 1 +tokens. Note that this is not intended to prescribe a particular implementation design; the usual "as if" rule applies.</p> +<p>Implementations are permitted to silently limit the pool size for a few reasons, including:</p> +<ul> +<li> +<p>Implementations that do not support parallelism can support the <b>-j</b> option by simply ignoring the option (other than +passing it to sub-<i>make</i> invocations via the <i>MAKEFLAGS</i> environment variable). In effect, such an implementation +silently restricts the size of the token pool to zero (and therefore need not create a token pool).</p> +</li> +<li> +<p>Some historical implementations dynamically limit the token pool size based on the current system load to avoid overloading the +system.</p> +</li> +<li> +<p>Implementations may want to limit the token pool size based on the number of processors available.</p> +</li> +<li> +<p>Implementations may want to limit the token pool size based on resource limits.</p> +</li> +</ul> +<p>Limiting the pool size does not change the value of <i>maxjobs</i> that is passed to sub-<i>make</i> invocations via the +<i>MAKEFLAGS</i> environment variable.</p> +<p>When a different <i>maxjobs</i> value is passed to a sub-<i>make</i>, some historical <i>make</i> implementations created a +separate pool of tokens while other historical <i>make</i> implementations continued to obtain tokens from the invoking <i>make</i> +but limited the number of tokens held at a time to the new value of <i>maxjobs</i> - 1. Both behaviors are believed to have merit +in different situations: the former gives a sub-<i>make</i> complete control the amount of parallelism, while the latter allows the +user to control the overall system load. This standard permits either behavior.</p> +<p>This standard calls for a token pool of size <i>maxjobs</i> - 1, and for removal from that pool only for the second and +subsequent tasks in a set of parallel tasks. This design was chosen because this is effectively what existing implementations do, +and also because the token consumed by a parallel task that invokes a sub-<i>make</i> is effectively lent to the sub-<i>make</i>. +Lending the token to the sub-<i>make</i> has the following advantages:</p> +<ul> +<li> +<p>It prevents the sub-<i>make</i> from being completely idle due to token starvation, allowing it to always make some progress +regardless of how many tokens other sub-<i>make</i> invocations have consumed.</p> +</li> +<li> +<p>It prevents token pool exhaustion caused by a long chain of sub-<i>make</i> invocations. If the token consumed by the invoking +rule was not effectively lent to the sub-<i>make</i>, then the pool would be exhausted by a chain of sub-<i>make</i> invocations +that is <i>maxjobs</i> long. Such a chain would never accomplish any work, and would thus never complete.</p> +</li> +</ul> +<p>When a rule invokes multiple sub-<i>make</i> processes asynchronously (for example by using an asynchronous list in the shell), +some implementations allow each sub-<i>make</i> to execute at least one rule even though this would cause the total number of +parallel rule executions across all <i>make</i> instances to exceed <i>maxjobs</i> (after discounting the rules that execute +sub-<i>make</i> processes). This behavior may not be ideal, but it is easier to implement and is unlikely to cause problems in +practice because applications typically do not have any rules that invoke multiple sub-<i>make</i> processes asynchronously. For +this reason the behavior is unspecified if a rule executes multiple sub-<i>make</i> processes asynchronously.</p> +<p>When multiple sub-<i>make</i> processes are running in parallel there is no requirement placed on the ordering of output from +these processes. Some implementations of <i>make</i> attempt to serialize output from each sub-<i>make</i>; others make no such +attempt. If diagnostic messages from failed commands are intermixed, the usual way to deal with this is to repeat the <i>make</i> +without <b>-j</b> (or with <b>-j</b> 1) so that intermixing will not occur.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_76_19" id="tag_20_76_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a +<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require +implementations to treat this as an error.</p> +<p>Some implementations of <i>make</i> include an <i>export</i> directive to add specified <i>make</i> variables to the +environment. This may be considered for standardization in a future version.</p> +<p>A future version of this standard may add a command-line option that causes <i>make</i> to report attempts to expand (or append +to) macros that do not exist.</p> +<p>A future version of this standard may require that a target with a prerequisite with an identical timestamp is considered +out-of-date.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_76_20" id="tag_20_76_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19"><i>2. Shell Command Language</i></a> , <a href= +"../utilities/ar.html#"><i>ar</i></a> , <a href="../utilities/c17.html#"><i>c17</i></a> , <a href= +"../utilities/get.html#"><i>get</i></a> , <a href="../utilities/lex.html#"><i>lex</i></a> , <a href= +"../utilities/sccs.html#"><i>sccs</i></a> , <a href="../utilities/sh.html#"><i>sh</i></a> , <a href= +"../utilities/yacc.html#"><i>yacc</i></a></p> +<p>XBD <a href="../basedefs/V1_chap06.html#tag_06_01"><i>6.1 Portable Character Set</i></a> , <a href= +"../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 +Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/exec.html#tag_17_129"><i>exec</i></a> , <a href="../functions/system.html#"><i>system</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_76_21" id="tag_20_76_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_76_22" id="tag_20_76_22"></a>Issue 5</h4> +<blockquote> +<p>The FUTURE DIRECTIONS section is added.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_76_23" id="tag_20_76_23"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the Software Development Utilities option.</p> +<p>The Open Group Corrigendum U029/1 is applied, correcting a typographical error in the SPECIAL TARGETS section.</p> +<p>In the ENVIRONMENT VARIABLES section, the <i>PROJECTDIR</i> description is updated from "otherwise, the home directory of a +user of that name is examined" to "otherwise, the value of <i>PROJECTDIR</i> is treated as a user name and that user's initial +working directory is examined".</p> +<p>It is specified whether the command line is related to the makefile or to the <i>make</i> command, and the macro processing +rules are updated to align with the IEEE P1003.2b draft standard.</p> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +<p>PASC Interpretation 1003.2 #193 is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_76_24" id="tag_20_76_24"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-6 is applied, clarifying that Guideline 9 of the Utility Syntax Guidelines does not apply.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>Include lines in makefiles are introduced.</p> +<p>Austin Group Interpretation 1003.1-2001 #131 is applied, changing the <b>Makefile Execution</b> section.</p> +<p>POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0121 [257] is applied.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0122 [509], XCU/TC2-2008/0123 [584], XCU/TC2-2008/0124 [857], +XCU/TC2-2008/0125 [505], XCU/TC2-2008/0126 [584], XCU/TC2-2008/0127 [505], XCU/TC2-2008/0128 [865], XCU/TC2-2008/0129 [693], +XCU/TC2-2008/0130 [602], XCU/TC2-2008/0131 [848], XCU/TC2-2008/0132 [763], XCU/TC2-2008/0133 [857], XCU/TC2-2008/0134 [866], +XCU/TC2-2008/0135 [525], XCU/TC2-2008/0136 [848], XCU/TC2-2008/0137 [769], XCU/TC2-2008/0138 [525], XCU/TC2-2008/0139 [769], +XCU/TC2-2008/0140 [505], XCU/TC2-2008/0141 [693], XCU/TC2-2008/0142 [505], XCU/TC2-2008/0143 [857], and XCU/TC2-2008/0144 [693,865] +are applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_76_25" id="tag_20_76_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to disallow the creation of filenames containing any bytes that +have the encoded value of a <newline> character.</p> +<p>Austin Group Defects 330, 1417, 1422, 1709, and 1710 are applied, adding new forms of macro assignment using the <tt>"::="</tt>, +<tt>"?="</tt>, and <tt>"+="</tt> operators.</p> +<p>Austin Group Defect 333 is applied, adding support for "silent includes" using <b>-include</b>.</p> +<p>Austin Group Defects 336 and 1711 are applied, specifying the behavior when <i>string1</i> in a macro expansion contains a macro +expansion.</p> +<p>Austin Group Defect 337 is applied, adding a new form of macro assignment using the <tt>"!="</tt> operator.</p> +<p>Austin Group Defects 373 and 1417 are applied, changing the set of characters that portable applications can use in macro names +to the entire portable filename character set (thus adding <hyphen-minus> to the set that could previously be used).</p> +<p>Austin Group Defects 514 and 1520 are applied, adding the $+ and $^ internal macros.</p> +<p>Austin Group Defect 518 is applied, allowing multiple files to be specified on an <b>include</b> line.</p> +<p>Austin Group Defects 519, 1712, and 1715 are applied, adding support for pattern macro expansions.</p> +<p>Austin Group Defects 523, 1708, and 1749 are applied, adding the .B~.PHONY special target.</p> +<p>Austin Group Defect 875 is applied, clarifying the requirements for inference rules.</p> +<p>Austin Group Defect 1104 is applied, changing "<b>s2.a</b>" to "<b>.s2.a</b>".</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1141 is applied, changing "core files" to "a file named core".</p> +<p>Austin Group Defect 1155 is applied, clarifying the handling of the <i>MAKE</i> macro.</p> +<p>Austin Group Defect 1325 is applied, adding requirements relating to the creation of include files.</p> +<p>Austin Group Defect 1330 is applied, removing obsolescent interfaces.</p> +<p>Austin Group Defect 1419 is applied, updating the <b>.SCCS_GET</b> default rule.</p> +<p>Austin Group Defect 1420 is applied, clarifying where internal macros can be used.</p> +<p>Austin Group Defect 1421 is applied, changing the APPLICATION USAGE section.</p> +<p>Austin Group Defects 1424, 1658, 1690, 1701, 1702, 1703, 1704, 1707, 1719, 1720, 1721, 1722, and 1750 are applied, making +various minor editorial wording changes.</p> +<p>Austin Group Defects 1436, 1437, 1652, 1660, 1661, and 1733 are applied, adding the <b>-j</b> <i>maxjobs</i> option and the +<b>.NOTPARALLEL</b> and <b>.WAIT</b> special targets, and changing the <b>-n</b> option.</p> +<p>Austin Group Defects 1471 and 1513 are applied, adding a new form of macro assignment using the <tt>":::="</tt> operator.</p> +<p>Austin Group Defect 1479 is applied, clarifying the requirements for default rules and macro values.</p> +<p>Austin Group Defect 1492 is applied, changing the EXIT STATUS section.</p> +<p>Austin Group Defect 1505 is applied, clarifying the requirements for expansion of macros that do not exist.</p> +<p>Austin Group Defect 1510 is applied, correcting a typographic error in the RATIONALE section.</p> +<p>Austin Group Defect 1549 is applied, clarifying the requirements for an escaped <newline> in a command line.</p> +<p>Austin Group Defect 1615 is applied, allowing target names to contain slashes and hyphens.</p> +<p>Austin Group Defect 1626 is applied, adding the <i>CURDIR</i> macro.</p> +<p>Austin Group Defect 1631 is applied, adding information about use of the <b>-j</b> option with the <b>.c.a</b> default rule to +the APPLICATION USAGE and EXAMPLES sections.</p> +<p>Austin Group Defect 1650 is applied, changing the few occurrences of "dependencies" to use the more common +"prerequisites".</p> +<p>Austin Group Defect 1653 is applied, clarifying the difference between how <i>MAKEFLAGS</i> is parsed compared to shell commands +that use the <i>make</i> utility.</p> +<p>Austin Group Defects 1654 and 1655 are applied, changing the APPLICATION USAGE section.</p> +<p>Austin Group Defect 1656 is applied, changing the NAME section.</p> +<p>Austin Group Defect 1657 is applied, moving some requirements unrelated to makefile syntax from the Makefile Syntax subsection +to the beginning of the EXTENDED DESCRIPTION section.</p> +<p>Austin Group Defect 1689 is applied, removing some redundant wording from the DESCRIPTION section.</p> +<p>Austin Group Defect 1692 is applied, allowing <i>make</i>, when invoked with the <b>-q</b> or <b>-t</b> option, to execute +command lines (without a <plus-sign> prefix) that expand the <i>MAKE</i> macro.</p> +<p>Austin Group Defect 1693 is applied, changing "command lines" to "execution lines" in the description of the <b>-s</b> +option.</p> +<p>Austin Group Defect 1694 is applied, changing "in the order they appear" to "in the order specified" in the OPERANDS +section.</p> +<p>Austin Group Defect 1696 is applied, changing the STDOUT section.</p> +<p>Austin Group Defect 1697 is applied, changing the RATIONALE and FUTURE DIRECTIONS sections.</p> +<p>Austin Group Defect 1698 is applied, changing "of a target" to "of the target" in the EXTENDED DESCRIPTION section.</p> +<p>Austin Group Defect 1699 is applied, addressing some inconsistencies in the use of the term "rules".</p> +<p>Austin Group Defect 1706 is applied, removing a line from the format specified for target rules.</p> +<p>Austin Group Defect 1714 is applied, changing "beginning of the line" to "beginning of the value".</p> +<p>Austin Group Defect 1716 is applied, changing the typographic convention used for variable elements within target names, in +particular the inference rule suffixes s1 and s2.</p> +<p>Austin Group Defect 1723 is applied, adding historical context to a paragraph in the RATIONALE section.</p> +<p>Austin Group Defect 1772 is applied, clarifying the ASYNCHRONOUS EVENTS section.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/mailx.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/man.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/man.html b/bdd/man.html @@ -0,0 +1,266 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>man</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/make.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/mesg.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="man" id="man"></a> <a name="tag_20_77" id="tag_20_77"></a><!-- man --> +<h4 class="mansect"><a name="tag_20_77_01" id="tag_20_77_01"></a>NAME</h4> +<blockquote>man — display system documentation</blockquote> +<h4 class="mansect"><a name="tag_20_77_02" id="tag_20_77_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> man</tt> <b>[</b><tt>-k</tt><b>]</b> <i>name</i><tt>... <img src="../images/opt-end.gif" alt= +"[Option End]" border="0"></tt></code></div> +</blockquote> +<h4 class="mansect"><a name="tag_20_77_03" id="tag_20_77_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>man</i> utility shall write information about each of the <i>name</i> operands. If <i>name</i> is the name of a standard +utility, <i>man</i> at a minimum shall write a message describing the syntax used by the standard utility, its options, operands, +environment variables affecting its execution, and its list of exit status codes. If more information is available, the <i>man</i> +utility shall provide it in an implementation-defined manner.</p> +<p>An implementation may provide information for values of <i>name</i> other than the standard utilities. Standard utilities that +are listed as optional and that are not supported by the implementation either shall cause a brief message indicating that fact to +be displayed or shall cause a full display of information as described previously.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_77_04" id="tag_20_77_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>man</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following option shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-k</b></dt> +<dd>Interpret <i>name</i> operands as keywords to be used in searching a utilities summary database that contains a brief purpose +entry for each standard utility and write lines from the summary database that match any of the keywords. The keyword search shall +produce results that are the equivalent of the output of the following command: +<pre> +<tt>grep -Ei ' +</tt><i>name +name</i><tt> +... +' </tt><i>summary-database</i><tt> +</tt></pre> +<p>This assumes that the <i>summary-database</i> is a text file with a single entry per line; this organization is not required and +the example using <a href="../utilities/grep.html"><i>grep</i></a> <b>-Ei</b> is merely illustrative of the type of search +intended. The purpose entry to be included in the database shall consist of a terse description of the purpose of the utility.</p> +</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_77_05" id="tag_20_77_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>name</i></dt> +<dd>A keyword or the name of a standard utility. When <b>-k</b> is not specified and <i>name</i> does not represent one of the +standard utilities, the results are unspecified.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_77_06" id="tag_20_77_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_77_07" id="tag_20_77_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_77_08" id="tag_20_77_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>man</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and in the summary database). The value of <i>LC_CTYPE</i> need not affect the format +of the information written about the <i>name</i> operands.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error and +informative messages written to standard output.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>PAGER</i></dt> +<dd>Determine an output filtering command for writing the output to a terminal. Any string acceptable as a <i>command_string</i> +operand to the <a href="../utilities/sh.html"><i>sh</i></a> <b>-c</b> command shall be valid. When standard output is a terminal +device, the reference page output shall be piped through the command. If the <i>PAGER</i> variable is null or not set, the command +shall be either <a href="../utilities/more.html"><i>more</i></a> or another paginator utility documented in the system +documentation.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_77_09" id="tag_20_77_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_77_10" id="tag_20_77_10"></a>STDOUT</h4> +<blockquote> +<p>The <i>man</i> utility shall write text describing the syntax of the utility <i>name</i>, its options and its operands, or, when +<b>-k</b> is specified, lines from the summary database. The format of this text is implementation-defined.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_77_11" id="tag_20_77_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used for diagnostic messages, and may also be used for informational messages of unspecified +format.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_77_12" id="tag_20_77_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_77_13" id="tag_20_77_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_77_14" id="tag_20_77_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_77_15" id="tag_20_77_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_77_16" id="tag_20_77_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_77_17" id="tag_20_77_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_77_18" id="tag_20_77_18"></a>RATIONALE</h4> +<blockquote> +<p>It is recognized that the <i>man</i> utility is only of minimal usefulness as specified. The opinion of the standard developers +was strongly divided as to how much or how little information <i>man</i> should be required to provide. They considered, however, +that the provision of some portable way of accessing documentation would aid user portability. The arguments against a fuller +specification were:</p> +<ul> +<li> +<p>Large quantities of documentation should not be required on a system that does not have excess disk space.</p> +</li> +<li> +<p>The current manual system does not present information in a manner that greatly aids user portability.</p> +</li> +<li> +<p>A "better help system" is currently an area in which vendors feel that they can add value to their POSIX implementations.</p> +</li> +</ul> +<p>The <b>-f</b> option was considered, but due to implementation differences, it was not included in this volume of +POSIX.1-2024.</p> +<p>The description was changed to be more specific about what has to be displayed for a utility. The standard developers considered +it insufficient to allow a display of only the synopsis without giving a short description of what each option and operand +does.</p> +<p>The "purpose" entry to be included in the database can be similar to the section title (less the numeric prefix) from this +volume of POSIX.1-2024 for each utility. These titles are similar to those used in historical systems for this purpose.</p> +<p>See <a href="../utilities/mailx.html"><i>mailx</i></a> for rationale concerning the default paginator.</p> +<p>The caveat in the <i>LC_CTYPE</i> description was added because it is not a requirement that an implementation provide reference +pages for all of its supported locales on each system; changing <i>LC_CTYPE</i> does not necessarily translate the reference page +into another language. This is equivalent to the current state of <i>LC_MESSAGES</i> in POSIX.1-2024—locale-specific messages are +not yet a requirement.</p> +<p>The historical <i>MANPATH</i> variable is not included in POSIX because no attempt is made to specify naming conventions for +reference page files, nor even to mandate that they are files at all. On some implementations they could be a true database, a +hypertext file, or even fixed strings within the <i>man</i> executable. The standard developers considered the portability of +reference pages to be outside their scope of work. However, users should be aware that <i>MANPATH</i> is implemented on a number of +historical systems and that it can be used to tailor the search pattern for reference pages from the various categories (utilities, +functions, file formats, and so on) when the system administrator reveals the location and conventions for reference pages on the +system.</p> +<p>The keyword search can rely on at least the text of the section titles from these utility descriptions, and the implementation +may add more keywords. The term "section titles" refers to the strings such as:</p> +<pre> +<tt>man — Display system documentation +ps — Report process status +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_77_19" id="tag_20_77_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_77_20" id="tag_20_77_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/more.html#"><i>more</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_77_21" id="tag_20_77_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_77_22" id="tag_20_77_22"></a>Issue 5</h4> +<blockquote> +<p>The FUTURE DIRECTIONS section is added.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_77_23" id="tag_20_77_23"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #108 is applied, clarifying that informational messages may appear on standard +error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_77_24" id="tag_20_77_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 190 is applied, marking the <i>man</i> utility as part of the User Portability Utilities option, and adding +a requirement for the message it writes for a standard utility to include the environment variables affecting its execution and its +list of exit status codes.</p> +<p>Austin Group Defect 251 is applied, encouraging implementations to report an error if a utility is directed to display a +pathname that contains any bytes that have the encoded value of a <newline> character when <newline> is a terminator or +separator in the output format being used.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/make.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/mesg.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/mesg.html b/bdd/mesg.html @@ -0,0 +1,207 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>mesg</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/man.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/mkdir.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="mesg" id="mesg"></a> <a name="tag_20_78" id="tag_20_78"></a><!-- mesg --> +<h4 class="mansect"><a name="tag_20_78_01" id="tag_20_78_01"></a>NAME</h4> +<blockquote>mesg — permit or deny messages</blockquote> +<h4 class="mansect"><a name="tag_20_78_02" id="tag_20_78_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>mesg</tt> <b>[</b><tt>y|n</tt><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_78_03" id="tag_20_78_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>mesg</i> utility shall control whether other users are allowed to send messages via <a href= +"../utilities/write.html"><i>write</i></a>, <a href="../utilities/talk.html"><i>talk</i></a>, or other utilities to a terminal +device. The terminal device affected shall be determined by searching for the first terminal in the sequence of devices associated +with standard input, standard output, and standard error, respectively. With no arguments, <i>mesg</i> shall report the current +state without changing it. Processes with appropriate privileges may be able to send messages to the terminal independent of the +current state.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_78_04" id="tag_20_78_04"></a>OPTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_78_05" id="tag_20_78_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported in the POSIX locale:</p> +<dl compact> +<dd></dd> +<dt><i>y</i></dt> +<dd>Grant permission to other users to send messages to the terminal device.</dd> +<dt><i>n</i></dt> +<dd>Deny permission to other users to send messages to the terminal device.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_78_06" id="tag_20_78_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_78_07" id="tag_20_78_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_78_08" id="tag_20_78_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>mesg</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written (by <i>mesg</i>) to +standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_78_09" id="tag_20_78_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_78_10" id="tag_20_78_10"></a>STDOUT</h4> +<blockquote> +<p>If no operand is specified, <i>mesg</i> shall display the current terminal state in an unspecified format.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_78_11" id="tag_20_78_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_78_12" id="tag_20_78_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_78_13" id="tag_20_78_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_78_14" id="tag_20_78_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Receiving messages is allowed.</dd> +<dt> 1</dt> +<dd>Receiving messages is not allowed.</dd> +<dt>>1</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_78_15" id="tag_20_78_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_78_16" id="tag_20_78_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The mechanism by which the message status of the terminal is changed is unspecified. Therefore, unspecified actions may cause +the status of the terminal to change after <i>mesg</i> has successfully completed. These actions may include, but are not limited +to: another invocation of the <i>mesg</i> utility, login procedures; invocation of the <a href= +"../utilities/stty.html"><i>stty</i></a> utility, invocation of the <a href="../utilities/chmod.html"><i>chmod</i></a> utility or +<a href="../functions/chmod.html"><i>chmod</i>()</a> function, and so on.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_78_17" id="tag_20_78_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_78_18" id="tag_20_78_18"></a>RATIONALE</h4> +<blockquote> +<p>The terminal changed by <i>mesg</i> is that associated with the standard input, output, or error, rather than the controlling +terminal for the session. This is because users logged in more than once should be able to change any of their login terminals +without having to stop the job running in those sessions. This is not a security problem involving the terminals of other users +because appropriate privileges would be required to affect the terminal of another user.</p> +<p>The method of checking each of the first three file descriptors in sequence until a terminal is found was adopted from System +V.</p> +<p>The file <b>/dev/tty</b> is not specified for the terminal device because it was thought to be too restrictive. Typical +environment changes for the <i>n</i> operand are that write permissions are removed for <i>others</i> and <i>group</i> from the +appropriate device. It was decided to leave the actual description of what is done as unspecified because of potential differences +between implementations.</p> +<p>The format for standard output is unspecified because of differences between historical implementations. This output is +generally not useful to shell scripts (they can use the exit status), so exact parsing of the output is unnecessary.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_78_19" id="tag_20_78_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_78_20" id="tag_20_78_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/talk.html#"><i>talk</i></a> , <a href="../utilities/write.html#tag_20_151"><i>write</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_78_21" id="tag_20_78_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_78_22" id="tag_20_78_22"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_78_23" id="tag_20_78_23"></a>Issue 7</h4> +<blockquote> +<p>The <i>mesg</i> utility is moved from the User Portability Utilities option to the Base. User Portability Utilities is now an +option for interactive utilities.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_78_24" id="tag_20_78_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/man.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/mkdir.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/mkdir.html b/bdd/mkdir.html @@ -0,0 +1,258 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>mkdir</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/mesg.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/mkfifo.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="mkdir" id="mkdir"></a> <a name="tag_20_79" id="tag_20_79"></a><!-- mkdir --> +<h4 class="mansect"><a name="tag_20_79_01" id="tag_20_79_01"></a>NAME</h4> +<blockquote>mkdir — make directories</blockquote> +<h4 class="mansect"><a name="tag_20_79_02" id="tag_20_79_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>mkdir</tt> <b>[</b><tt>-p</tt><b>] [</b><tt>-m</tt> <i>mode</i><b>]</b> <i>dir</i><tt>...</tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_79_03" id="tag_20_79_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>mkdir</i> utility shall create the directories specified by the operands, in the order specified.</p> +<p>For each <i>dir</i> operand, the <i>mkdir</i> utility shall perform actions equivalent to the <a href= +"../functions/mkdir.html"><i>mkdir</i>()</a> function defined in the System Interfaces volume of POSIX.1-2024, called with the +following arguments:</p> +<ol> +<li> +<p>The <i>dir</i> operand is used as the <i>path</i> argument.</p> +</li> +<li> +<p>The value of the bitwise-inclusive OR of S_IRWXU, S_IRWXG, and S_IRWXO is used as the <i>mode</i> argument. (If the <b>-m</b> +option is specified, the value of the <a href="../functions/mkdir.html"><i>mkdir</i>()</a> <i>mode</i> argument is unspecified, but +the directory shall at no time have permissions less restrictive than the <b>-m</b> <i>mode</i> option-argument.)</p> +</li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_79_04" id="tag_20_79_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>mkdir</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-m </b><i>mode</i></dt> +<dd>Set the file permission bits of the newly-created directory to the specified <i>mode</i> value. The <i>mode</i> option-argument +shall be the same as the <i>mode</i> operand defined for the <a href="../utilities/chmod.html"><i>chmod</i></a> utility. In the +<i>symbolic_mode</i> strings, the <i>op</i> characters <tt>'+'</tt> and <tt>'-'</tt> shall be interpreted relative to an assumed +initial mode of <i>a</i>=<i>rwx</i>; <tt>'+'</tt> shall add permissions to the default mode, <tt>'-'</tt> shall delete permissions +from the default mode.</dd> +<dt><b>-p</b></dt> +<dd>Create any missing intermediate pathname components. +<p>For each <i>dir</i> operand that does not name an existing directory, before performing the actions described in the DESCRIPTION +above, the <i>mkdir</i> utility shall create any pathname components of the path prefix of <i>dir</i> that do not name an existing +directory by performing actions equivalent to first calling the <a href="../functions/mkdir.html"><i>mkdir</i>()</a> function with +the following arguments:</p> +<ol> +<li> +<p>A pathname naming the missing pathname component, ending with a trailing <slash> character, as the <i>path</i> +argument</p> +</li> +<li> +<p>The value zero as the <i>mode</i> argument</p> +</li> +</ol> +<p>and then calling the <a href="../functions/chmod.html"><i>chmod</i>()</a> function with the following arguments:</p> +<ol> +<li> +<p>The same <i>path</i> argument as in the <a href="../functions/mkdir.html"><i>mkdir</i>()</a> call</p> +</li> +<li> +<p>The value <tt>(S_IWUSR|S_IXUSR|~<i>filemask</i>)&0777</tt> as the <i>mode</i> argument, where <i>filemask</i> is the file +mode creation mask of the process (see XSH <a href="../functions/umask.html#tag_17_645"><i>umask</i></a> )</p> +</li> +</ol> +<p>Each <i>dir</i> operand that names an existing directory shall be ignored without error.</p> +</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_79_05" id="tag_20_79_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>dir</i></dt> +<dd>A pathname of a directory to be created.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_79_06" id="tag_20_79_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_79_07" id="tag_20_79_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_79_08" id="tag_20_79_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>mkdir</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_79_09" id="tag_20_79_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_79_10" id="tag_20_79_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_79_11" id="tag_20_79_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_79_12" id="tag_20_79_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_79_13" id="tag_20_79_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_79_14" id="tag_20_79_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>All the specified directories were created successfully, or the <b>-p</b> option was specified and all the specified +directories either already existed or were created successfully.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_79_15" id="tag_20_79_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_79_16" id="tag_20_79_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The default file mode for directories is <i>a</i>=<i>rwx</i> (777 on most systems) with selected permissions removed in +accordance with the file mode creation mask. For intermediate pathname components created by <i>mkdir</i>, the mode is the default +modified by <i>u</i>+<i>wx</i> so that the subdirectories can always be created regardless of the file mode creation mask; if +different ultimate permissions are desired for the intermediate directories, they can be changed afterwards with <a href= +"../utilities/chmod.html"><i>chmod</i></a>.</p> +<p>Note that some of the requested directories may have been created even if an error occurs.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_79_17" id="tag_20_79_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_79_18" id="tag_20_79_18"></a>RATIONALE</h4> +<blockquote> +<p>The System V <b>-m</b> option was included to control the file mode.</p> +<p>The System V <b>-p</b> option was included to create any needed intermediate directories and to complement the functionality +provided by <a href="../utilities/rmdir.html"><i>rmdir</i></a> for removing directories in the path prefix as they become empty. +Because no error is produced if any path component already exists, the <b>-p</b> option is also useful to ensure that a particular +directory exists.</p> +<p>The functionality of <i>mkdir</i> is described substantially through a reference to the <a href= +"../functions/mkdir.html"><i>mkdir</i>()</a> function in the System Interfaces volume of POSIX.1-2024. For example, by default, the +mode of the directory is affected by the file mode creation mask in accordance with the specified behavior of the <a href= +"../functions/mkdir.html"><i>mkdir</i>()</a> function. In this way, there is less duplication of effort required for describing +details of the directory creation.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_79_19" id="tag_20_79_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a +<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require +implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_79_20" id="tag_20_79_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/chmod.html#tag_20_17"><i>chmod</i></a> , <a href="../utilities/rm.html#"><i>rm</i></a> , <a href= +"../utilities/rmdir.html#tag_20_106"><i>rmdir</i></a> , <a href="../utilities/umask.html#tag_20_132"><i>umask</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/mkdir.html#tag_17_338"><i>mkdir</i></a> , <a href= +"../functions/umask.html#tag_17_645"><i>umask</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_79_21" id="tag_20_79_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_79_22" id="tag_20_79_22"></a>Issue 5</h4> +<blockquote> +<p>The FUTURE DIRECTIONS section is added.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_79_23" id="tag_20_79_23"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-56 is applied, aligning the <b>-m</b> option with the IEEE P1003.2b draft standard to clarify an ambiguity.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0122 [161] is applied.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0145 [843] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_79_24" id="tag_20_79_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to disallow the creation of filenames containing any bytes that +have the encoded value of a <newline> character.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/mesg.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/mkfifo.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/mkfifo.html b/bdd/mkfifo.html @@ -0,0 +1,215 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>mkfifo</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/mkdir.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/more.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="mkfifo" id="mkfifo"></a> <a name="tag_20_80" id="tag_20_80"></a><!-- mkfifo --> +<h4 class="mansect"><a name="tag_20_80_01" id="tag_20_80_01"></a>NAME</h4> +<blockquote>mkfifo — make FIFO special files</blockquote> +<h4 class="mansect"><a name="tag_20_80_02" id="tag_20_80_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>mkfifo</tt> <b>[</b><tt>-m</tt> <i>mode</i><b>]</b> <i>file</i><tt>...</tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_80_03" id="tag_20_80_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>mkfifo</i> utility shall create the FIFO special files specified by the operands, in the order specified.</p> +<p>For each <i>file</i> operand, the <i>mkfifo</i> utility shall perform actions equivalent to the <a href= +"../functions/mkfifo.html"><i>mkfifo</i>()</a> function defined in the System Interfaces volume of POSIX.1-2024, called with the +following arguments:</p> +<ol> +<li> +<p>The <i>file</i> operand is used as the <i>path</i> argument.</p> +</li> +<li> +<p>The value of the bitwise-inclusive OR of S_IRUSR, S_IWUSR, S_IRGRP, S_IWGRP, S_IROTH, and S_IWOTH is used as the <i>mode</i> +argument. (If the <b>-m</b> option is specified, the value of the <a href="../functions/mkfifo.html"><i>mkfifo</i>()</a> +<i>mode</i> argument is unspecified, but the FIFO shall at no time have permissions less restrictive than the <b>-m</b> <i>mode</i> +option-argument.)</p> +</li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_80_04" id="tag_20_80_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>mkfifo</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following option shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-m </b><i>mode</i></dt> +<dd>Set the file permission bits of the newly-created FIFO to the specified <i>mode</i> value. The <i>mode</i> option-argument +shall be the same as the <i>mode</i> operand defined for the <a href="../utilities/chmod.html"><i>chmod</i></a> utility. In the +<i>symbolic_mode</i> strings, the <i>op</i> characters <tt>'+'</tt> and <tt>'-'</tt> shall be interpreted relative to an assumed +initial mode of <i>a</i>=<i>rw</i>.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_80_05" id="tag_20_80_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of the FIFO special file to be created.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_80_06" id="tag_20_80_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_80_07" id="tag_20_80_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_80_08" id="tag_20_80_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>mkfifo</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_80_09" id="tag_20_80_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_80_10" id="tag_20_80_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_80_11" id="tag_20_80_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_80_12" id="tag_20_80_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_80_13" id="tag_20_80_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_80_14" id="tag_20_80_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>All the specified FIFO special files were created successfully.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_80_15" id="tag_20_80_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_80_16" id="tag_20_80_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_80_17" id="tag_20_80_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_80_18" id="tag_20_80_18"></a>RATIONALE</h4> +<blockquote> +<p>This utility was added to permit shell applications to create FIFO special files.</p> +<p>The <b>-m</b> option was added to control the file mode, for consistency with the similar functionality provided by the <a href= +"../utilities/mkdir.html"><i>mkdir</i></a> utility.</p> +<p>Early proposals included a <b>-p</b> option similar to the <a href="../utilities/mkdir.html"><i>mkdir</i></a> <b>-p</b> option +that created intermediate directories leading up to the FIFO specified by the final component. This was removed because it is not +commonly needed and is not common practice with similar utilities.</p> +<p>The functionality of <i>mkfifo</i> is described substantially through a reference to the <a href= +"../functions/mkfifo.html"><i>mkfifo</i>()</a> function in the System Interfaces volume of POSIX.1-2024. For example, by default, +the mode of the FIFO file is affected by the file mode creation mask in accordance with the specified behavior of the <a href= +"../functions/mkfifo.html"><i>mkfifo</i>()</a> function. In this way, there is less duplication of effort required for describing +details of the file creation.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_80_19" id="tag_20_80_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a +<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require +implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_80_20" id="tag_20_80_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/chmod.html#tag_20_17"><i>chmod</i></a> , <a href="../utilities/umask.html#tag_20_132"><i>umask</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/mkfifo.html#tag_17_340"><i>mkfifo</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_80_21" id="tag_20_80_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 3.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_80_22" id="tag_20_80_22"></a>Issue 6</h4> +<blockquote> +<p>The <b>-m</b> option is aligned with the IEEE P1003.2b draft standard to clarify an ambiguity.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_80_23" id="tag_20_80_23"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to disallow the creation of filenames containing any bytes that +have the encoded value of a <newline> character.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/mkdir.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/more.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/more.html b/bdd/more.html @@ -0,0 +1,830 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>more</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/mkfifo.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/msgfmt.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="more" id="more"></a> <a name="tag_20_81" id="tag_20_81"></a><!-- more --> +<h4 class="mansect"><a name="tag_20_81_01" id="tag_20_81_01"></a>NAME</h4> +<blockquote>more — display files on a page-by-page basis</blockquote> +<h4 class="mansect"><a name="tag_20_81_02" id="tag_20_81_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> more</tt> <b>[</b><tt>-ceisu</tt><b>] [</b><tt>-n</tt> <i>number</i><b>] [</b><tt>-p</tt> +<i>command</i><b>] [</b><tt>-t</tt> <i>tagstring</i><b>] [</b><i>file</i><tt>...</tt><b>]</b> <tt><img src="../images/opt-end.gif" +alt="[Option End]" border="0"></tt></code></div> +</blockquote> +<h4 class="mansect"><a name="tag_20_81_03" id="tag_20_81_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>more</i> utility shall read files and either write them to the terminal on a page-by-page basis or filter them to +standard output. If standard output is not a terminal device, all input files shall be copied to standard output in their entirety, +without modification, except as specified for the <b>-s</b> option. If standard output is a terminal device, the files shall be +written a number of lines (one screenful) at a time under the control of user commands. See the EXTENDED DESCRIPTION section.</p> +<p>Certain block-mode terminals do not have all the capabilities necessary to support the complete <i>more</i> definition; they are +incapable of accepting commands that are not terminated with a <newline>. Implementations that support such terminals shall +provide an operating mode to <i>more</i> in which all commands can be terminated with a <newline> on those terminals. This +mode:</p> +<ul> +<li> +<p>Shall be documented in the system documentation</p> +</li> +<li> +<p>Shall, at invocation, inform the user of the terminal deficiency that requires the <newline> usage and provide +instructions on how this warning can be suppressed in future invocations</p> +</li> +<li> +<p>Shall not be required for implementations supporting only fully capable terminals</p> +</li> +<li> +<p>Shall not affect commands already requiring <newline> characters</p> +</li> +<li> +<p>Shall not affect users on the capable terminals from using <i>more</i> as described in this volume of POSIX.1-2024</p> +</li> +</ul> +</blockquote> +<h4 class="mansect"><a name="tag_20_81_04" id="tag_20_81_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>more</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> , except that <tt>'+'</tt> may be recognized as an option delimiter as well as <tt>'-'</tt>.</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-c</b></dt> +<dd>If a screen is to be written that has no lines in common with the current screen, or <i>more</i> is writing its first screen, +<i>more</i> shall not scroll the screen, but instead shall redraw each line of the screen in turn, from the top of the screen to +the bottom. In addition, if <i>more</i> is writing its first screen, the screen shall be cleared. This option may be silently +ignored on devices with insufficient terminal capabilities.</dd> +<dt><b>-e</b></dt> +<dd>Exit immediately after writing the last line of the last file in the argument list; see the EXTENDED DESCRIPTION section.</dd> +<dt><b>-i</b></dt> +<dd>Perform pattern matching in a case-insensitive manner; see XBD <a href="../basedefs/V1_chap09.html#tag_09_02"><i>9.2 Regular +Expression General Requirements</i></a> .</dd> +<dt><b>-n </b><i>number</i></dt> +<dd>Specify the number of lines per screenful. The <i>number</i> argument is a positive decimal integer. The <b>-n</b> option shall +override any values obtained from any other source.</dd> +<dt><b>-p </b><i>command</i></dt> +<dd>Each time a screen from a new file is displayed or redisplayed (including as a result of <i>more</i> commands; for example, +<b>:p</b>), execute the <i>more</i> command(s) in the command arguments in the order specified, as if entered by the user after the +first screen has been displayed. No intermediate results shall be displayed (that is, if the command is a movement to a screen +different from the normal first screen, only the screen resulting from the command shall be displayed.) If any of the commands fail +for any reason, an informational message to this effect shall be written, and no further commands specified using the <b>-p</b> +option shall be executed for this file.</dd> +<dt><b>-s</b></dt> +<dd>Behave as if consecutive empty lines were a single empty line.</dd> +<dt><b>-t </b><i>tagstring</i></dt> +<dd>Write the screenful of the file containing the tag named by the <i>tagstring</i> argument. See the <a href= +"../utilities/ctags.html#"><i>ctags</i></a> utility. The tags feature represented by <b>-t</b> <i>tagstring</i> and the <b>:t</b> +command is optional. It shall be provided on any system that also provides a conforming implementation of <a href= +"../utilities/ctags.html"><i>ctags</i></a>; otherwise, the use of <b>-t</b> produces undefined results. +<p>The filename resulting from the <b>-t</b> option shall be logically added as a prefix to the list of command line files, as if +specified by the user. If the tag named by the <i>tagstring</i> argument is not found, it shall be an error, and <i>more</i> shall +take no further action.</p> +<p>If the tag specifies a line number, the first line of the display shall contain the beginning of that line. If the tag specifies +a pattern, the first line of the display shall contain the beginning of the matching text from the first line of the file that +contains that pattern. If the line does not exist in the file or matching text is not found, an informational message to this +effect shall be displayed, and <i>more</i> shall display the default screen as if <b>-t</b> had not been specified.</p> +<p>If both the <b>-t</b> <i>tagstring</i> and <b>-p</b> <i>command</i> options are given, the <b>-t</b> <i>tagstring</i> shall be +processed first; that is, the file and starting line for the display shall be as specified by <b>-t</b>, and then the <b>-p</b> +<i>more</i> command shall be executed. If the line (matching text) specified by the <b>-t</b> command does not exist (is not +found), no <b>-p</b> <i>more</i> command shall be executed for this file at any time.</p> +</dd> +<dt><b>-u</b></dt> +<dd>Treat a <backspace> as a printable control character, displayed as an implementation-defined character sequence (see the +EXTENDED DESCRIPTION section), suppressing backspacing and the special handling that produces underlined or standout mode text on +some terminal types. Also, do not ignore a <carriage-return> at the end of a line.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_81_05" id="tag_20_81_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of an input file. If no <i>file</i> operands are specified, the standard input shall be used. If a <i>file</i> is +<tt>'-'</tt>, the standard input shall be read at that point in the sequence.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_81_06" id="tag_20_81_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be used only if no <i>file</i> operands are specified, or if a <i>file</i> operand is <tt>'-'</tt>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_81_07" id="tag_20_81_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files being examined shall be text files. If standard output is a terminal, standard error shall be used to read +commands from the user. If standard output is a terminal, standard error is not readable, and command input is needed, <i>more</i> +may attempt to obtain user commands from the controlling terminal (for example, <b>/dev/tty</b>); otherwise, <i>more</i> shall +terminate with an error indicating that it was unable to read user commands. If standard output is not a terminal, no error shall +result if standard error cannot be opened for reading.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_81_08" id="tag_20_81_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>more</i>:</p> +<dl compact> +<dd></dd> +<dt><i>COLUMNS</i></dt> +<dd>Override the system-selected horizontal display line size. See XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. +Environment Variables</i></a> for valid values and results when it is unset or null.</dd> +<dt><i>EDITOR</i></dt> +<dd>Used by the <b>v</b> command to select an editor. See the EXTENDED DESCRIPTION section.</dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_COLLATE</i></dt> +<dd><br> +Determine the locale for the behavior of ranges, equivalence classes, and multi-character collating elements within regular +expressions.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files) and the behavior of character classes within regular +expressions.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error and +informative messages written to standard output.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>LINES</i></dt> +<dd>Override the system-selected vertical screen size, used as the number of lines in a screenful. See XBD <a href= +"../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> for valid values and results when it is unset or null. The +<b>-n</b> option shall take precedence over the <i>LINES</i> variable for determining the number of lines in a screenful.</dd> +<dt><i>MORE</i></dt> +<dd>Determine a string containing options described in the OPTIONS section preceded with <hyphen-minus> characters and +<blank>-separated as on the command line. Any command line options shall be processed after those in the <i>MORE</i> +variable, as if the command line were: +<pre> +<tt>more $MORE </tt><i>options operands</i><tt> +</tt></pre> +<p>The <i>MORE</i> variable shall take precedence over the <i>TERM</i> and <i>LINES</i> variables for determining the number of +lines in a screenful.</p> +</dd> +<dt><i>TERM</i></dt> +<dd>Determine the name of the terminal type. If this variable is unset or null, an unspecified default terminal type is used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_81_09" id="tag_20_81_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>The following actions shall be taken upon receipt of signals:</p> +<dl compact> +<dd></dd> +<dt>SIGCONT</dt> +<dd>The actions described below for SIGWINCH shall be taken, except that the screen shall always be refreshed (regardless of +whether the terminal window size changed).</dd> +<dt>SIGWINCH</dt> +<dd>If standard output is a terminal, the current terminal window size associated with the terminal on standard output shall be +obtained, as if by a call to XSH <a href="../functions/tcgetwinsize.html#"><i>tcgetwinsize</i></a> . If the terminal window size is +successfully obtained, it shall be used as follows: +<ul> +<li> +<p>If the <i>COLUMNS</i> environment variable is unset or does not contain a number, the horizontal display line size shall be set +to the number of columns in the obtained terminal window size.</p> +</li> +<li> +<p>If the <b>-n</b> option was not specified (neither on the command line nor via the <i>MORE</i> environment variable) and the +<i>LINES</i> environment variable is unset or does not contain a number, the vertical screen size shall be set to the number of +rows in the obtained terminal window size.</p> +</li> +</ul> +<p>If the above resulted in either the vertical screen size or the horizontal display line size (or both) changing to a different +value, the number of lines available per screen and the number of columns available per line shall be updated correspondingly (see +XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> ) and the screen shall be refreshed; otherwise, +the screen may be refreshed.</p> +</dd> +</dl> +<p>The action taken for all other signals shall be the default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_81_10" id="tag_20_81_10"></a>STDOUT</h4> +<blockquote> +<p>The standard output shall be used to write the contents of the input files.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_81_11" id="tag_20_81_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used for diagnostic messages and user commands (see the INPUT FILES section), and, if standard +output is a terminal device, to write a prompting string. The prompting string shall appear on the screen line below the last line +of the file displayed in the current screenful. The prompt shall contain the name of the file currently being examined and shall +contain an end-of-file indication and the name of the next file, if any, when prompting at the end-of-file. If an error or +informational message is displayed, it is unspecified whether it is contained in the prompt. If it is not contained in the prompt, +it shall be displayed and then the user shall be prompted for a continuation character, at which point another message or the user +prompt may be displayed. The prompt is otherwise unspecified. It is unspecified whether informational messages are written for +other user commands.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_81_12" id="tag_20_81_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_81_13" id="tag_20_81_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>The following section describes the behavior of <i>more</i> when the standard output is a terminal device. If the standard +output is not a terminal device, no options other than <b>-s</b> shall have any effect, and all input files shall be copied to +standard output otherwise unmodified, at which time <i>more</i> shall exit without further action.</p> +<p>The number of lines available per screen shall be determined by the <b>-n</b> option, if present, or by obtaining the vertical +screen size from the <i>LINES</i> environment variable (see the ENVIRONMENT VARIABLES section) or from the terminal window size +associated with the terminal on standard output (see XSH <a href="../functions/tcgetwinsize.html#"><i>tcgetwinsize</i></a> ), with +a default value as described in XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> .</p> +<p>The maximum number of lines written shall be one less than this number, because the screen line after the last line written +shall be used to write a user prompt and user input. If the number of lines in the screen is less than two, the results are +undefined. It is unspecified whether user input is permitted to be longer than the remainder of the single line where the prompt +has been written.</p> +<p>The number of columns available per line shall be determined by obtaining the horizontal display line size from the +<i>COLUMNS</i> environment variable (see the ENVIRONMENT VARIABLES section) or from the terminal window size associated with the +terminal on standard output (see XSH <a href="../functions/tcgetwinsize.html#"><i>tcgetwinsize</i></a> ), with a default value as +described in XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> .</p> +<p>Lines that are longer than the display shall be folded; the length at which folding occurs is unspecified, but should be +appropriate for the output device. Folding may occur between glyphs of single characters that take up multiple display columns.</p> +<p>When standard output is a terminal and <b>-u</b> is not specified, <i>more</i> shall treat <backspace> and +<carriage-return> characters specially:</p> +<ul> +<li> +<p>A character, followed first by a sequence of <i>n</i> <backspace> characters (where <i>n</i> is the same as the number of +column positions that the character occupies), then by <i>n</i> <underscore> characters (<tt>'_'</tt>), shall cause that +character to be written as underlined text, if the terminal type supports that. The <i>n</i> <underscore> characters, +followed first by <i>n</i> <backspace> characters, then any character with <i>n</i> column positions, shall also cause that +character to be written as underlined text, if the terminal type supports that.</p> +</li> +<li> +<p>A sequence of <i>n</i> <backspace> characters (where <i>n</i> is the same as the number of column positions that the +previous character occupies) that appears between two identical printable characters shall cause the first of those two characters +to be written as emboldened text (that is, visually brighter, standout mode, or inverse-video mode), if the terminal type supports +that, and the second to be discarded. Immediately subsequent occurrences of <backspace>/character pairs for that same +character shall also be discarded. (For example, the sequence <tt>"a\ba\ba\ba"</tt> is interpreted as a single emboldened +<tt>'a'</tt>.)</p> +</li> +<li> +<p>The <i>more</i> utility shall logically discard all other <backspace> characters from the line as well as the character +which precedes them, if any.</p> +</li> +<li> +<p>A <carriage-return> at the end of a line shall be ignored, rather than being written as a non-printable character, as +described in the next paragraph.</p> +</li> +</ul> +<p>It is implementation-defined how other non-printable characters are written. Implementations should use the same format that +they use for the <a href="../utilities/ex.html"><i>ex</i></a> <b>print</b> command; see the OPTIONS section within the <a href= +"../utilities/ed.html"><i>ed</i></a> utility. It is unspecified whether a multi-column character shall be separated if it crosses a +display line boundary; it shall not be discarded. The behavior is unspecified if the number of columns on the display is less than +the number of columns any single character in the line being displayed would occupy.</p> +<p>When each new file is displayed (or redisplayed), <i>more</i> shall write the first screen of the file. Once the initial screen +has been written, <i>more</i> shall prompt for a user command. If the execution of the user command results in a screen that has +lines in common with the current screen, and the device has sufficient terminal capabilities, <i>more</i> shall scroll the screen; +otherwise, it is unspecified whether the screen is scrolled or redrawn.</p> +<p>For all files but the last (including standard input if no file was specified, and for the last file as well, if the <b>-e</b> +option was not specified), when <i>more</i> has written the last line in the file, <i>more</i> shall prompt for a user command. +This prompt shall contain the name of the next file as well as an indication that <i>more</i> has reached end-of-file. If the user +command is <b>f</b>, <control>-F, <space>, <b>j</b>, <newline>, <b>d</b>, <control>-D, or <b>s</b>, +<i>more</i> shall display the next file. Otherwise, if displaying the last file, <i>more</i> shall exit. Otherwise, <i>more</i> +shall execute the user command specified.</p> +<p>Several of the commands described in this section display a previous screen from the input stream. In the case that text is +being taken from a non-rewindable stream, such as a pipe, it is implementation-defined how much backwards motion is supported. If a +command cannot be executed because of a limitation on backwards motion, an error message to this effect shall be displayed, the +current screen shall not change, and the user shall be prompted for another command.</p> +<p>If a command cannot be performed because there are insufficient lines to display, <i>more</i> shall alert the terminal. If a +command cannot be performed because there are insufficient lines to display or a <b>/</b> command fails: if the input is the +standard input, the last screen in the file may be displayed; otherwise, the current file and screen shall not change, and the user +shall be prompted for another command.</p> +<p>The interactive commands in the following sections shall be supported. Some commands can be preceded by a decimal integer, +called <i>count</i> in the following descriptions. If not specified with the command, <i>count</i> shall default to 1. In the +following descriptions, <i>pattern</i> is a basic regular expression, as described in XBD <a href= +"../basedefs/V1_chap09.html#tag_09_03"><i>9.3 Basic Regular Expressions</i></a> . The term "examine" is historical usage meaning +"open the file for viewing"; for example, <i>more</i> <b>foo</b> would be expressed as examining file <b>foo</b>.</p> +<p>In the following descriptions, unless otherwise specified, <i>line</i> is a line in the <i>more</i> display, not a line from the +file being examined.</p> +<p>In the following descriptions, the <i>current position</i> refers to two things:</p> +<ol> +<li> +<p>The position of the current line on the screen</p> +</li> +<li> +<p>The line number (in the file) of the current line on the screen</p> +</li> +</ol> +<p>Usually, the line on the screen corresponding to the current position is the third line on the screen. If this is not possible +(there are fewer than three lines to display or this is the first page of the file, or it is the last page of the file), then the +current position is either the first or last line on the screen as described later.</p> +<h5><a name="tag_20_81_13_01" id="tag_20_81_13_01"></a>Help</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>h +</tt></pre></dd> +</dl> +<p>Write a summary of these commands and other implementation-defined commands. The behavior shall be as if the <i>more</i> utility +were executed with the <b>-e</b> option on a file that contained the summary information. The user shall be prompted as described +earlier in this section when end-of-file is reached. If the user command is one of those specified to continue to the next file, +<i>more</i> shall return to the file and screen state from which the <b>h</b> command was executed.</p> +<h5><a name="tag_20_81_13_02" id="tag_20_81_13_02"></a>Scroll Forward One Screenful</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt>f +</tt><b>[</b><i>count</i><b>]</b><tt><control>-F +</tt></pre></dd> +</dl> +<p>Scroll forward <i>count</i> lines, with a default of one screenful. If <i>count</i> is more than the screen size, only the final +screenful shall be written.</p> +<h5><a name="tag_20_81_13_03" id="tag_20_81_13_03"></a>Scroll Backward One Screenful</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt>b +</tt><b>[</b><i>count</i><b>]</b><tt><control>-B +</tt></pre></dd> +</dl> +<p>Scroll backward <i>count</i> lines, with a default of one screenful (see the <b>-n</b> option). If <i>count</i> is more than the +screen size, only the final screenful shall be written.</p> +<h5><a name="tag_20_81_13_04" id="tag_20_81_13_04"></a>Scroll Forward One Line</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt><space> +</tt><b>[</b><i>count</i><b>]</b><tt>j +</tt><b>[</b><i>count</i><b>]</b><tt><newline> +</tt></pre></dd> +</dl> +<p>Scroll forward <i>count</i> lines. The default <i>count</i> for the <space> shall be one screenful; for <b>j</b> and +<newline>, one line. The entire <i>count</i> lines shall be written, even if <i>count</i> is more than the screen size.</p> +<h5><a name="tag_20_81_13_05" id="tag_20_81_13_05"></a>Scroll Backward One Line</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt>k +</tt></pre></dd> +</dl> +<p>Scroll backward <i>count</i> lines. The entire <i>count</i> lines shall be written, even if <i>count</i> is more than the screen +size.</p> +<h5><a name="tag_20_81_13_06" id="tag_20_81_13_06"></a>Scroll Forward One Half Screenful</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt>d +</tt><b>[</b><i>count</i><b>]</b><tt><control>-D +</tt></pre></dd> +</dl> +<p>Scroll forward <i>count</i> lines, with a default of one half of the screen size. If <i>count</i> is specified, it shall become +the new default for subsequent <b>d</b>, <control>-D, and <b>u</b> commands.</p> +<h5><a name="tag_20_81_13_07" id="tag_20_81_13_07"></a>Skip Forward One Line</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt>s +</tt></pre></dd> +</dl> +<p>Display the screenful beginning with the line <i>count</i> lines after the last line on the current screen. If <i>count</i> +would cause the current position to be such that less than one screenful would be written, the last screenful in the file shall be +written.</p> +<h5><a name="tag_20_81_13_08" id="tag_20_81_13_08"></a>Scroll Backward One Half Screenful</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt>u +</tt><b>[</b><i>count</i><b>]</b><tt><control>-U +</tt></pre></dd> +</dl> +<p>Scroll backward <i>count</i> lines, with a default of one half of the screen size. If <i>count</i> is specified, it shall become +the new default for subsequent <b>d</b>, <control>-D, <b>u</b>, and <control>-U commands. The entire <i>count</i> lines +shall be written, even if <i>count</i> is more than the screen size.</p> +<h5><a name="tag_20_81_13_09" id="tag_20_81_13_09"></a>Go to Beginning of File</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt>g +</tt></pre></dd> +</dl> +<p>Display the screenful beginning with line <i>count</i>.</p> +<h5><a name="tag_20_81_13_10" id="tag_20_81_13_10"></a>Go to End-of-File</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt>G +</tt></pre></dd> +</dl> +<p>If <i>count</i> is specified, display the screenful beginning with the line <i>count</i>. Otherwise, display the last screenful +of the file.</p> +<h5><a name="tag_20_81_13_11" id="tag_20_81_13_11"></a>Refresh the Screen</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>r +<control>-L +</tt></pre></dd> +</dl> +<p>Refresh the screen.</p> +<h5><a name="tag_20_81_13_12" id="tag_20_81_13_12"></a>Discard and Refresh</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>R +</tt></pre></dd> +</dl> +<p>Refresh the screen, discarding any buffered input. If the current file is non-seekable, buffered input shall not be discarded +and the <b>R</b> command shall be equivalent to the <b>r</b> command.</p> +<h5><a name="tag_20_81_13_13" id="tag_20_81_13_13"></a>Mark Position</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>m</tt><i>letter</i><tt> +</tt></pre></dd> +</dl> +<p>Mark the current position with the letter named by <i>letter</i>, where <i>letter</i> represents the name of one of the +lowercase letters of the portable character set. When a new file is examined, all marks may be lost.</p> +<h5><a name="tag_20_81_13_14" id="tag_20_81_13_14"></a>Return to Mark</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>'</tt><i>letter</i><tt> +</tt></pre></dd> +</dl> +<p>Return to the position that was previously marked with the letter named by <i>letter</i>, making that line the current +position.</p> +<h5><a name="tag_20_81_13_15" id="tag_20_81_13_15"></a>Return to Previous Position</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>'' +</tt></pre></dd> +</dl> +<p>Return to the position from which the last large movement command was executed (where a "large movement" is defined as any +movement of more than a screenful of lines). If no such movements have been made, return to the beginning of the file.</p> +<h5><a name="tag_20_81_13_16" id="tag_20_81_13_16"></a>Search Forward for Pattern</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt>/</tt><b>[</b><tt>!</tt><b>]</b><i>pattern</i><tt><newline> +</tt></pre></dd> +</dl> +<p>Display the screenful beginning with the <i>count</i>th line containing the pattern. The search shall start after the first line +currently displayed. The null regular expression (<tt>'/'</tt> followed by a <newline>) shall repeat the search using the +previous regular expression, with a default <i>count</i>. If the character <tt>'!'</tt> is included, the matching lines shall be +those that do not contain the <i>pattern</i>. If no match is found for the <i>pattern</i>, a message to that effect shall be +displayed.</p> +<h5><a name="tag_20_81_13_17" id="tag_20_81_13_17"></a>Search Backward for Pattern</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt>?</tt><b>[</b><tt>!</tt><b>]</b><i>pattern</i><tt><newline> +</tt></pre></dd> +</dl> +<p>Display the screenful beginning with the <i>count</i>th previous line containing the pattern. The search shall start on the last +line before the first line currently displayed. The null regular expression (<tt>'?'</tt> followed by a <newline>) shall +repeat the search using the previous regular expression, with a default <i>count</i>. If the character <tt>'!'</tt> is included, +matching lines shall be those that do not contain the <i>pattern</i>. If no match is found for the <i>pattern</i>, a message to +that effect shall be displayed.</p> +<h5><a name="tag_20_81_13_18" id="tag_20_81_13_18"></a>Repeat Search</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt>n +</tt></pre></dd> +</dl> +<p>Repeat the previous search for <i>count</i>th line containing the last <i>pattern</i> (or not containing the last +<i>pattern</i>, if the previous search was <tt>"/!"</tt> or <tt>"?!"</tt>).</p> +<h5><a name="tag_20_81_13_19" id="tag_20_81_13_19"></a>Repeat Search in Reverse</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt>N +</tt></pre></dd> +</dl> +<p>Repeat the search in the opposite direction of the previous search for the <i>count</i>th line containing the last +<i>pattern</i> (or not containing the last <i>pattern</i>, if the previous search was <tt>"/!"</tt> or <tt>"?!"</tt>).</p> +<h5><a name="tag_20_81_13_20" id="tag_20_81_13_20"></a>Examine New File</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>:e </tt><b>[</b><i>filename</i><b>]</b><tt><newline> +</tt></pre></dd> +</dl> +<p>Examine a new file. If the <i>filename</i> argument is not specified, the current file (see the <b>:n</b> and <b>:p</b> commands +below) shall be re-examined. The <i>filename</i> shall be subjected to the process of shell word expansions (see <a href= +"../utilities/V3_chap02.html#tag_19_06"><i>2.6 Word Expansions</i></a> ); if more than a single pathname results, the effects are +unspecified. If <i>filename</i> is a <number-sign> (<tt>'#'</tt>), the previously examined file shall be re-examined. If +<i>filename</i> is not accessible for any reason (including that it is a non-seekable file), an error message to this effect shall +be displayed and the current file and screen shall not change.</p> +<h5><a name="tag_20_81_13_21" id="tag_20_81_13_21"></a>Examine Next File</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt>:n +</tt></pre></dd> +</dl> +<p>Examine the next file. If a number <i>count</i> is specified, the <i>count</i>th next file shall be examined. If <i>filename</i> +refers to a non-seekable file, the results are unspecified.</p> +<h5><a name="tag_20_81_13_22" id="tag_20_81_13_22"></a>Examine Previous File</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt>:p +</tt></pre></dd> +</dl> +<p>Examine the previous file. If a number <i>count</i> is specified, the <i>count</i>th previous file shall be examined. If +<i>filename</i> refers to a non-seekable file, the results are unspecified.</p> +<h5><a name="tag_20_81_13_23" id="tag_20_81_13_23"></a>Go to Tag</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>:t </tt><i>tagstring</i><tt><newline> +</tt></pre></dd> +</dl> +<p>If the file containing the tag named by the <i>tagstring</i> argument is not the current file, examine the file, as if the +<b>:e</b> command was executed with that file as the argument. Otherwise, or in addition, display the screenful beginning with the +tag, as described for the <b>-t</b> option (see the OPTIONS section). If the <a href="../utilities/ctags.html"><i>ctags</i></a> +utility is not supported by the system, the use of <b>:t</b> produces undefined results.</p> +<h5><a name="tag_20_81_13_24" id="tag_20_81_13_24"></a>Invoke Editor</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>v +</tt></pre></dd> +</dl> +<p>Invoke an editor to edit the current file being examined. If standard input is being examined, the results are unspecified. The +name of the editor shall be taken from the environment variable <i>EDITOR ,</i> or shall default to <a href= +"../utilities/vi.html"><i>vi</i></a>. If the last pathname component in <i>EDITOR</i> is either <a href= +"../utilities/vi.html"><i>vi</i></a> or <a href="../utilities/ex.html"><i>ex</i></a>, the editor shall be invoked with a <b>-c</b> +<i>linenumber</i> command line argument, where <i>linenumber</i> is the line number of the file line containing the display line +currently displayed as the first line of the screen. It is implementation-defined whether line-setting options are passed to +editors other than <a href="../utilities/vi.html"><i>vi</i></a> and <a href="../utilities/ex.html"><i>ex</i></a>.</p> +<p>When the editor exits, <i>more</i> shall resume with the same file and screen as when the editor was invoked.</p> +<h5><a name="tag_20_81_13_25" id="tag_20_81_13_25"></a>Display Position</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>= +<control>-G +</tt></pre></dd> +</dl> +<p>Write a message for which the information references the first byte of the line after the last line of the file on the screen. +This message shall include the name of the file currently being examined, its number relative to the total number of files there +are to examine, the line number in the file, the byte number and the total bytes in the file, and what percentage of the file +precedes the current position. If <i>more</i> is reading from standard input, or the file is shorter than a single screen, the line +number, the byte number, the total bytes, and the percentage need not be written.</p> +<h5><a name="tag_20_81_13_26" id="tag_20_81_13_26"></a>Quit</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>q +:q +ZZ +</tt></pre></dd> +</dl> +<p>Exit <i>more</i>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_81_14" id="tag_20_81_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_81_15" id="tag_20_81_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>If an error is encountered accessing a file when using the <b>:n</b> command, <i>more</i> shall attempt to examine the next file +in the argument list, but the final exit status shall be affected. If an error is encountered accessing a file via the <b>:p</b> +command, <i>more</i> shall attempt to examine the previous file in the argument list, but the final exit status shall be affected. +If an error is encountered accessing a file via the <b>:e</b> command, <i>more</i> shall remain in the current file and the final +exit status shall not be affected.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_81_16" id="tag_20_81_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>When the standard output is not a terminal, only the <b>-s</b> filter-modification option is effective. This is based on +historical practice. For example, a typical implementation of <a href="../utilities/man.html"><i>man</i></a> pipes its output +through <i>more</i> <b>-s</b> to squeeze excess white space for terminal users. When <a href="../utilities/man.html"><i>man</i></a> +is piped to <a href="../utilities/lp.html"><i>lp</i></a>, however, it is undesirable for this squeezing to happen.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_81_17" id="tag_20_81_17"></a>EXAMPLES</h4> +<blockquote> +<p>The <b>-p</b> allows arbitrary commands to be executed at the start of each file. Examples are:</p> +<dl compact> +<dd></dd> +<dt><i>more </i><b>-p G </b><i>file1 file2</i></dt> +<dd><br> +Examine each file starting with its last screenful.</dd> +<dt><i>more </i><b>-p </b>100 <i>file1 file2</i></dt> +<dd><br> +Examine each file starting with line 100 in the current position (usually the third line, so line 98 would be the first line +written).</dd> +<dt><i>more </i><b>-p </b>/100 <i>file1 file2</i></dt> +<dd><br> +Examine each file starting with the first line containing the string <tt>"100"</tt> in the current position</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_81_18" id="tag_20_81_18"></a>RATIONALE</h4> +<blockquote> +<p>The <i>more</i> utility, available in BSD and BSD-derived systems, was chosen as the prototype for the POSIX file display +program since it is more widely available than either the public-domain program <i>less</i> or than <i>pg</i>, a pager provided in +System V. The 4.4 BSD <i>more</i> is the model for the features selected; it is almost fully upwards-compatible from the 4.3 BSD +version in wide use and has become more amenable for <a href="../utilities/vi.html"><i>vi</i></a> users. Several features +originally derived from various file editors, found in both <i>less</i> and <i>pg</i>, have been added to this volume of +POSIX.1-2024 as they have proved extremely popular with users.</p> +<p>There are inconsistencies between <i>more</i> and <a href="../utilities/vi.html"><i>vi</i></a> that result from historical +practice. For example, the single-character commands <b>h</b>, <b>f</b>, <b>b</b>, and <space> are screen movers in +<i>more</i>, but cursor movers in <a href="../utilities/vi.html"><i>vi</i></a>. These inconsistencies were maintained because the +cursor movements are not applicable to <i>more</i> and the powerful functionality achieved without the use of the control key +justifies the differences.</p> +<p>The tags interface has been included in a program that is not a text editor because it promotes another degree of consistent +operation with <a href="../utilities/vi.html"><i>vi</i></a>. It is conceivable that the paging environment of <i>more</i> would be +superior for browsing source code files in some circumstances.</p> +<p>The operating mode referred to for block-mode terminals effectively adds a <newline> to each Synopsis line that currently +has none. So, for example, <b>d</b><newline> would page one screenful. The mode could be triggered by a command line option, +environment variable, or some other method. The details are not imposed by this volume of POSIX.1-2024 because there are so few +systems known to support such terminals. Nevertheless, it was considered that all systems should be able to support <i>more</i> +given the exception cited for this small community of terminals because, in comparison to <a href= +"../utilities/vi.html"><i>vi</i></a>, the cursor movements are few and the command set relatively amenable to the optional +<newline> characters.</p> +<p>Historically some versions of <i>more</i> did not obtain the terminal window size on receipt of SIGCONT, resulting in incorrect +screen contents when the screen was refreshed if the size had been changed while <i>more</i> was suspended. This is considered to +be a bug in those implementations.</p> +<p>Some versions of <i>more</i> provide a shell escaping mechanism similar to the <a href="../utilities/ex.html"><i>ex</i></a> +<b>!</b> command. The standard developers did not consider that this was necessary in a paginator, particularly given the wide +acceptance of multiple window terminals and job control features. (They chose to retain such features in the editors and <a href= +"../utilities/mailx.html"><i>mailx</i></a> because the shell interaction also gives an opportunity to modify the editing buffer, +which is not applicable to <i>more</i>.)</p> +<p>The <b>-p</b> (position) option replaces the <b>+</b> command because of the Utility Syntax Guidelines. The +<b>+</b><i>command</i> option is no longer specified by POSIX.1-2024 but may be present in some implementations. In early +proposals, it took a <i>pattern</i> argument, but historical <i>less</i> provided the <i>more</i> general facility of a command. It +would have been desirable to use the same <b>-c</b> as <a href="../utilities/ex.html"><i>ex</i></a> and <a href= +"../utilities/vi.html"><i>vi</i></a>, but the letter was already in use.</p> +<p>The text stating "from a non-rewindable stream ... implementations may limit the amount of backwards motion supported" would +allow an implementation that permitted no backwards motion beyond text already on the screen. It was not possible to require a +minimum amount of backwards motion that would be effective for all conceivable device types. The implementation should allow the +user to back up as far as possible, within device and reasonable memory allocation constraints.</p> +<p>Historically, non-printable characters were displayed using the ARPA standard mappings, which are as follows:</p> +<ol> +<li> +<p>Printable characters are left alone.</p> +</li> +<li> +<p>Control characters less than \177 are represented as followed by the character offset from the <tt>'@'</tt> character in the +ASCII map; for example, \007 is represented as <tt>'G'</tt>.</p> +</li> +<li> +<p>\177 is represented as followed by <tt>'?'</tt>.</p> +</li> +</ol> +<p>The display of characters having their eighth bit set was less standard. Existing implementations use hex (0x00), octal (\000), +and a meta-bit display. (The latter displayed characters with their eighth bit set as the two characters <tt>"M-"</tt>, followed by +the seven-bit display as described previously.) The latter probably has the best claim to historical practice because it was used +with the <b>-v</b> option of 4 BSD and 4 BSD-derived versions of the <a href="../utilities/cat.html"><i>cat</i></a> utility since +1980.</p> +<p>No specific display format is required by POSIX.1-2024. Implementations are encouraged to conform to historic practice in the +absence of any strong reason to diverge.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_81_19" id="tag_20_81_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_81_20" id="tag_20_81_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19"><i>2. Shell Command Language</i></a> , <a href= +"../utilities/ctags.html#"><i>ctags</i></a> , <a href="../utilities/ed.html#"><i>ed</i></a> , <a href= +"../utilities/ex.html#"><i>ex</i></a> , <a href="../utilities/vi.html#"><i>vi</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap09.html#tag_09_02"><i>9.2 Regular Expression General Requirements</i></a> , <a href= +"../basedefs/V1_chap09.html#tag_09_03"><i>9.3 Basic Regular Expressions</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_81_21" id="tag_20_81_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_81_22" id="tag_20_81_22"></a>Issue 5</h4> +<blockquote> +<p>The FUTURE DIRECTIONS section is added.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_81_23" id="tag_20_81_23"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +<p>The obsolescent SYNOPSIS is removed.</p> +<p>The utility has been extensively reworked for alignment with the IEEE P1003.2b draft standard:</p> +<ul> +<li> +<p>Changes have been made as a result of IEEE PASC Interpretations 1003.2 #37 and #109.</p> +</li> +<li> +<p>The <i>more</i> utility should be able to handle underlined and emboldened displays of characters that are wider than a single +column position.</p> +</li> +</ul> +</blockquote> +<h4 class="mansect"><a name="tag_20_81_24" id="tag_20_81_24"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #027 is applied, clarifying that <tt>'+'</tt> may be recognized as an option delimiter +in the OPTIONS section.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0123 [265] is applied.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0146 [584] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_81_25" id="tag_20_81_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1031 is applied, changing the description of the <b>-i</b> option.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1185 is applied, changing the ASYNCHRONOUS EVENTS and EXTENDED DESCRIPTION sections in relation to the +terminal window size.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/mkfifo.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/msgfmt.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/msgfmt.html b/bdd/msgfmt.html @@ -0,0 +1,447 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>msgfmt</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/more.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/mv.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="msgfmt" id="msgfmt"></a> <a name="tag_20_82" id="tag_20_82"></a><!-- msgfmt --> +<h4 class="mansect"><a name="tag_20_82_01" id="tag_20_82_01"></a>NAME</h4> +<blockquote>msgfmt — create messages objects from portable messages object source files</blockquote> +<h4 class="mansect"><a name="tag_20_82_02" id="tag_20_82_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>msgfmt</tt> <b>[</b><tt>-cfSv</tt><b>] [</b><tt>-D</tt> <i>dir</i><b>] [</b><tt>-o</tt> <i>outputfile</i><b>]</b> +<i>pathname</i><tt>...</tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_82_03" id="tag_20_82_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>msgfmt</i> utility shall create messages object files from portable messages object source files (dot-po files).</p> +<p>A dot-po file contains messages to be output by system commands or by applications. The messages in these files should be able +to be translated to any language supported by the system.</p> +<p>The <i>msgfmt</i> utility shall interpret message strings for output as characters according to the codeset specified in the +dot-po file or, if not present, the current setting of the <i>LC_CTYPE</i> locale category.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_82_04" id="tag_20_82_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>msgfmt</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-c</b></dt> +<dd>If this option and <b>-v</b> are both specified, <i>msgfmt</i> shall detect and diagnose input file abnormalities which might +represent translation errors. The <b>msgid</b> and <b>msgstr</b> strings shall be compared. It shall be considered abnormal if one +string starts or ends with a <newline> while the other does not. Also, if the flag <b>c-format</b> appears in a <tt>"#,"</tt> +comment for a <b>msgid</b> directive (see EXTENDED DESCRIPTION), it shall be considered abnormal if the strings do not have the +same number of <tt>'%'</tt> conversion specifiers, or if corresponding conversion specifiers take different argument types (see XSH +<a href="../functions/fprintf.html#"><i>fprintf</i></a> ). If an abnormality is detected, the exit status shall be non-zero and a +diagnostic message shall be output. Additional checks beyond those described here may also be performed. These checks may produce +diagnostics or informational messages and need not affect the exit status. If <b>-c</b> is specified without <b>-v</b> or <b>-v</b> +is specified without <b>-c</b>, the behavior is unspecified.</dd> +<dt><b>-D </b><i>dir</i></dt> +<dd>Add <i>dir</i> to the list of directories to search for input files.</dd> +<dt><b>-f</b></dt> +<dd>Use fuzzy entries in output. If this option is not specified, fuzzy entries shall not be included in the output.</dd> +<dt><b>-o </b><i>outputfile</i></dt> +<dd><br> +Specify the name of an output file to be used instead of the default filename(s) specified in EXTENDED DESCRIPTION. All +<b>domain</b> <i>domainname</i> directives in the dot-po file(s) shall be ignored.</dd> +<dt><b>-S</b></dt> +<dd>Append the suffix <b>.mo</b> to each generated messages object filename if it does not have this suffix.</dd> +<dt><b>-v</b></dt> +<dd>See <b>-c</b>.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_82_05" id="tag_20_82_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>pathname</i></dt> +<dd>A pathname of a dot-po file.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_82_06" id="tag_20_82_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_82_07" id="tag_20_82_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files shall be text files in the format described in EXTENDED DESCRIPTION.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_82_08" id="tag_20_82_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>msgfmt</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LANGUAGE</i></dt> +<dd>Determine the location of messages objects <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src= +"../images/opt-start.gif" alt="[Option Start]" border="0"> if <i>NLSPATH</i> is not set or the evaluation of <i>NLSPATH</i> +did not lead to a suitable messages object being found. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale name used to locate messages objects, and the locale that should be used to affect the format and contents of +diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_82_09" id="tag_20_82_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_82_10" id="tag_20_82_10"></a>STDOUT</h4> +<blockquote> +<p>Not Used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_82_11" id="tag_20_82_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used for diagnostic messages and may also be used for warning messages. If the <b>-c</b> and +<b>-v</b> options are specified, additional unspecified informational messages may be written to standard error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_82_12" id="tag_20_82_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>The format of the created messages object files is unspecified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_82_13" id="tag_20_82_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>The <i>msgfmt</i> utility shall accept portable messages object source files (dot-po files) in the following format.</p> +<p>A dot-po file contains zero or more lines, with each non-blank line containing a comment, a statement, or a statement +continuation. A comment has an unquoted <number-sign> (<tt>'#'</tt>) as the first non-<blank> character and ends with +the next <newline> character. A statement continuation is a double-quoted string on a line by itself, optionally preceded +and/or followed by <blank> characters, and the string shall be concatenated with the string on the previous statement line. +If a comment occurs between a statement and a statement continuation, the behavior is unspecified. All other comments, except for +comments beginning with <number-sign><comma> (<tt>"#,"</tt>), and blank lines shall be ignored.</p> +<p>The format of a statement is:</p> +<pre> +<i>directive value</i><tt> +</tt></pre> +<p>The <i>directive</i> starts at the first non-<blank> character of the line and is separated from the <i>value</i> by one +or more <blank> characters. The <i>value</i> consists of a double-quoted string optionally followed by <blank> +characters. Zero or more statement continuation lines (see above) can follow the statement. The following directives shall be +supported:<br></p> +<pre> +<b>domain </b><i>domainname</i><tt> +</tt><b>msgid </b><i>message_identifier</i><tt> +</tt><b>msgid_plural </b><i>untranslated_string_plural</i><tt> +</tt><b>msgstr </b><i>message_string</i><tt> +</tt><b>msgstr[</b><i>index</i><b>] </b><i>message_string</i><tt> +</tt></pre> +<p>A dot-po file consists of zero or more sections. Each section specifies the messages to be processed in a domain. The first +directive in each section shall be a <b>domain</b> directive (except for the first section which shall behave as if</p> +<pre> +<tt>domain "messages" +</tt></pre> +<p>had been specified if the first directive is not a <b>domain</b> directive).</p> +<p>The behavior of the <b>domain</b> directive is affected by the options used. See OPTIONS for the behavior when the <b>-o</b> +option is specified. If the <b>-o</b> option is not specified, all data obtained from the non-<b>domain</b> directives in a dot-po +section shall be output to the messages object file named <i>domainname</i><b>.mo</b> when the <b>-S</b> option is specified. When +the <b>-S</b> option is not specified, it is implementation-defined whether <i>domainname</i> or <i>domainname</i><b>.mo</b> is +used.</p> +<p>If multiple <b>domain</b> directives specify the same <i>domainname</i>, the sections shall be processed as if there was only +one section that starts with a <b>domain</b> <i>domainname</i> statement which contained the statements of the sections, in the +same order, excluding all but the first <b>domain</b> <i>domainname</i> statement.</p> +<p>Within each section, there can be a header. A header is identified by having a <b>msgid</b> directive with the empty string +(<tt>""</tt>) as the <i>message_identifier</i> immediately followed by a statement containing a <b>msgstr</b> directive. The +<i>message_string</i> in this <b>msgstr</b> statement in a header shall be treated specially. If <i>message_string</i> contains a +specification of the form:</p> +<pre> +<tt>"nplurals=</tt><i>count</i><tt>; plural=</tt><i>expression</i><tt>" +</tt></pre> +<p>then <i>count</i> indicates the number of plural forms for messages in that domain, and <i>expression</i> is a C-language +expression that evaluates to an unsigned integer value which determines the <b>msgstr[</b><i>index</i><b>]</b> directive to be +used. The value of <i>expression</i> is used as the index value. The variable <i>n</i> in <i>expression</i> is assigned the value +of the <i>n</i> argument to the <a href="../functions/ngettext.html"><i>ngettext</i>()</a>, <a href= +"../functions/ngettext_l.html"><i>ngettext_l</i>()</a>, <a href="../functions/dngettext.html"><i>dngettext</i>()</a>, <a href= +"../functions/dngettext_l.html"><i>dngettext_l</i>()</a>, <a href="../functions/dcngettext.html"><i>dcngettext</i>()</a>, and +<a href="../functions/dcngettext_l.html"><i>dcngettext_l</i>()</a> functions or of the <i>n</i> operand of the <a href= +"../utilities/ngettext.html"><i>ngettext</i></a> utility before <i>expression</i> is evaluated. The application shall ensure that +<i>expression</i> evaluates to a non-negative value less than <i>count</i> for all <i>n</i> that can be supplied by the +aforementioned functions and utility.</p> +<p>If <i>message_string</i> in the header contains a specification of the form:</p> +<pre> +<tt>"charset=</tt><i>codeset</i><tt>" +</tt></pre> +<p>then <i>codeset</i> indicates the codeset to be used to encode the message strings in this section's domain (overriding +<i>LC_CTYPE ).</i> If the output string's codeset is different from the message string's codeset, codeset conversion from the +message string's codeset to the output string's codeset shall be performed by the <i>gettext</i> family of functions and by the +<a href="../utilities/gettext.html"><i>gettext</i></a> and <a href="../utilities/ngettext.html"><i>ngettext</i></a> utilities. See +XSH <a href="../functions/gettext.html#tag_17_238"><i>gettext</i></a> and <a href= +"../utilities/gettext.html#tag_20_54"><i>gettext</i></a> . The output string's codeset shall be determined by the current or +specified locale's codeset. <basefont size="2"></p> +<dl> +<dt><b>Note:</b></dt> +<dd>It is the responsibility of translators to ensure that the characters they enter into message strings in a dot-po file are +encoded in the codeset specified in the header.</dd> +</dl> +<basefont size="3"> +<p>If a header is present in a section, the application shall ensure that the header is provided by the first <b>msgid</b> +directive in that section.</p> +<p>After the header, if present, zero or more messages are identified by a <b>msgid</b> directive with a <i>message_identifier</i> +that is not an empty string. Each of these directives start a subsection that is used to get a translated message from the +<i>gettext</i> family of functions and from the <a href="../utilities/gettext.html"><i>gettext</i></a> and <a href= +"../utilities/ngettext.html"><i>ngettext</i></a> utilities. If the <i>message_identifier</i> string is the string identified by the +<i>gettext</i> family of functions <i>msgid</i> argument or by the <a href="../utilities/gettext.html"><i>gettext</i></a> and +<a href="../utilities/ngettext.html"><i>ngettext</i></a> utility <i>msgid</i> operand, this subsection specifies how that +translation is to be processed.</p> +<p>If there is only a singular form for the given <i>message_identifier</i>, the application shall ensure that the statement +containing the <b>msgid</b> directive is immediately followed by a <b>msgstr</b> directive.</p> +<p>If there are plural forms for the given <i>message_identifier</i> and the header for this section exists and contains an</p> +<pre> +<tt>"nplurals=</tt><i>count</i><tt>; plural=</tt><i>expression</i><tt>" +</tt></pre> +<p>specification, the application shall ensure that the statement containing the <b>msgid</b> directive is immediately followed by +a <b>msgid_plural</b> directive and that each statement containing a <b>msgid_plural</b> directive is followed by <i>count</i> +statements containing <b>msgstr[</b><i>index</i><b>]</b> directives, starting with <b>msgstr[0]</b> and ending with +<b>msgstr[</b><i>count</i><b>-1]</b> in increasing order, with no duplicate index values. If a header for this section does not +exist or does not contain an</p> +<pre> +<tt>"nplurals=</tt><i>count</i><tt>; plural=</tt><i>expression</i><tt>" +</tt></pre> +<p>specification, the application shall ensure that no <b>msgid_plural</b> or <b>msgstr[</b><i>index</i><b>]</b> directives are +used in this section.</p> +<p>For example, if the header's <i>message_string</i> contains the specification:</p> +<pre> +<tt>"nplurals=2; plural= n == 1 ? 0 : 1" +</tt></pre> +<p>there are two forms in the domain; <b>msgstr[0]</b> is used if <i>n</i> is equal to 1, otherwise <b>msgstr[1]</b> is used. For +another example, if the header's <i>message_string</i> contains:</p> +<pre> +<tt>"nplurals=3; plural= n == 1 ? 0 : n == 2 ? 1 : 2" +</tt></pre> +<p>there are three forms in the domain; <b>msgstr[0]</b> is used if <i>n</i> is equal to 1, <b>msgstr[1]</b> is used if <i>n</i> is +equal to 2, otherwise <b>msgstr[2]</b> is used.</p> +<p>C-language escape sequences in strings shall be processed as specified for character string literals in the ISO C standard, +except that <i>universal-character-name</i> escape sequences need not be supported.</p> +<p>Comments in a dot-po file can be in one of the following formats:</p> +<pre> +<tt>#: </tt><i>reference</i><tt> +#. </tt><i>utility-added-comments</i><tt> +#, </tt><i>flag</i><tt> +#</tt><i>translator-comments</i> (where <i>translator-comments</i> does not begin with <tt>'.'</tt>, <tt>':'</tt> or <tt>','</tt>)<tt> +</tt></pre> +<p>A <tt>#: <i>reference</i></tt> comment indicates the location(s) of the <b>msgid</b> string in the source files, in</p> +<pre> +<i>pathname1</i><tt>:</tt><i>linenumber1 </i><b>[</b><i>pathname2</i><tt>:</tt><i>linenumber2</i><tt> ... </tt><b>]</b><tt> +</tt></pre> +<p>format. They can be added, as might <tt>"#."</tt> prefixed additional comments of unspecified format, by the <a href= +"../utilities/xgettext.html"><i>xgettext</i></a> utility. All comments that do not begin with <tt>"#,"</tt> are informative only +and shall be silently ignored by the <i>msgfmt</i> utility. In <tt>"#,"</tt> comments the following values for <i>flag</i> can be +specified:</p> +<dl compact> +<dd></dd> +<dt><b>fuzzy</b></dt> +<dd>This flag indicates that the <b>msgstr</b> string might not be a correct translation at this point in time. Only the translator +can judge if the translation requires further modification or is acceptable as is. Once satisfied with the translation, the +translator should remove this <b>fuzzy</b> flag. If this flag is specified, the <i>msgfmt</i> utility shall not generate the entry +for the next following <b>msgid</b> in the output message catalog, unless the <b>-f</b> option is specified. If other flag comments +are specified between <b>fuzzy</b> and the <b>msgid</b>, the behavior is unspecified.</dd> +<dt><b>c-format</b></dt> +<dd></dd> +<dt><b>no-c-format</b></dt> +<dd>The <b>c-format</b> flag indicates that the next following <b>msgid</b> string contains a <a href= +"../functions/printf.html"><i>printf</i>()</a> format string. When the <b>c-format</b> flag is given and the <b>-c</b> and +<b>-v</b> options are specified, the <i>msgfmt</i> utility shall perform additional tests to check the validity of the translation +(see OPTIONS); these additional tests may also be performed if neither <b>c-format</b> nor <b>no-c-format</b> is given. When the +<b>no-c-format</b> flag is given for a string, no additional checks shall be performed for the string. When both the +<b>c-format</b> and the <b>no-c-format</b> flags are given, the last flag specified takes precedence.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_82_14" id="tag_20_82_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_82_15" id="tag_20_82_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>The <i>msgfmt</i> utility need not continue processing later <i>pathname</i> operands when an error condition that affects the +exit status is detected. It is unspecified whether a messages object file is written when checks performed for the <b>-c</b> and +<b>-v</b> options fail.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_82_16" id="tag_20_82_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The <a href="../utilities/xgettext.html"><i>xgettext</i></a> utility can be used to create template dot-po files from C-language +source files.</p> +<p>Installing messages object files for the POSIX or C locale is not recommended, since they may be ignored for the sake of +efficiency.</p> +<p>The first section for each domain in a dot-po file should include a header containing a</p> +<pre> +<tt>"charset=</tt><i>codeset</i><tt>" +</tt></pre> +<p>specification. If this specification is omitted, message conversions in the <i>gettext</i> family of functions and in the +<a href="../utilities/gettext.html"><i>gettext</i></a> and <a href="../utilities/ngettext.html"><i>ngettext</i></a> utilities may +fail.</p> +<p>The <b>msgid_plural</b> directive's <i>untranslated_string_plural</i> string comes from the <i>msgid_plural</i> arguments in +calls to the <a href="../functions/ngettext.html"><i>ngettext</i>()</a>, <a href= +"../functions/ngettext_l.html"><i>ngettext_l</i>()</a>, <a href="../functions/dngettext.html"><i>dngettext</i>()</a>, <a href= +"../functions/dngettext_l.html"><i>dngettext_l</i>()</a>, <a href="../functions/dcngettext.html"><i>dcngettext</i>()</a>, and +<a href="../functions/dcngettext_l.html"><i>dcngettext_l</i>()</a> functions when a prototype dot-po file is created by the +<a href="../utilities/xgettext.html"><i>xgettext</i></a> utility. These strings (and the <i>msgid_plural</i> operands in calls to +the <a href="../utilities/ngettext.html"><i>ngettext</i></a> utility) can provide context when a translator is modifying a template +dot-po file into a dot-po file for a specific language. These functions and the <a href= +"../utilities/ngettext.html"><i>ngettext</i></a> utility do not try to match the <i>msgid_plural</i> arguments or operands with +anything in a messages object file; they only match the <i>msgid</i> arguments and operands.</p> +<p>Unlike shell command language strings, double-quoted strings in dot-po files cannot contain a literal <newline> +character.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_82_17" id="tag_20_82_17"></a>EXAMPLES</h4> +<blockquote> +<p>In this example, <b>module1.po</b> and <b>module2.po</b> are portable messages object source files.</p> +<pre> +<b>$</b><tt> cat module1.po</tt><b> +# default domain "messages" +msgid "" +msgstr "charset=utf-8" +msgid "msg 1" +msgstr "msg 1 translation" +# +domain "help_domain" +msgid "" +msgstr "charset=utf-8" +msgid "help 2" +msgstr "help 2 translation" +# +domain "error_domain" +msgid "" +msgstr "charset=utf-8" +msgid "error 3" +msgstr "error 3 translation"</b><tt> +</tt></pre> +<pre> +<b>$</b><tt> cat module2.po</tt><b> +# default domain "messages" +msgid "" +msgstr "charset=utf-8" +msgid "mesg 4" +msgstr "mesg 4 translation" +# +domain "error_domain" +msgid "" +msgstr "charset=utf-8" +#, c-format +msgid "error 5 %s" +msgstr "error 5 translation %s" +# +domain "window_domain" +msgid "" +msgstr "charset=utf-8" +msgid "window 6" +msgstr "window 6 translation"</b><tt> +</tt></pre> +<pre> +<b>$</b><tt> cat module3.po</tt><b> +# default domain "messages" +# header will be used for the whole output file in the third example +msgid "" +msgstr "charset=utf-8" +msgid "info 0" +msgstr "info 0 translation"</b><tt> +</tt></pre> +<pre> +<b>$</b><tt> cat opt_debug.po</tt><b> +# +domain "debug_domain" +msgid "debug 8" +msgstr "debug 8 translation"</b><tt> +</tt></pre> +<p>The following command will produce the output files <b>messages.mo</b>, <b>help_domain.mo</b>, and <b>error_domain.mo</b>:</p> +<pre> +<b>$</b><tt> msgfmt -S module1.po +</tt></pre> +<p>The following command will produce the output files <b>messages.mo</b>, <b>help_domain.mo</b>, <b>error_domain.mo</b>, and +<b>window_domain.mo</b>:</p> +<pre> +<b>$</b><tt> msgfmt -S module1.po module2.po +</tt></pre> +<p>The following command will produce the output file <b>hello.mo</b>:</p> +<pre> +<b>$</b><tt> msgfmt -o hello.mo module3.po opt_debug.po +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_82_18" id="tag_20_82_18"></a>RATIONALE</h4> +<blockquote> +<p>Some implementations are less strict about the format of dot-po files and simply treat all occurrences of one or more white +space characters as a separator. The format described in this standard is accepted by all known implementations.</p> +<p>In some implementations, duplicate <b>msgid</b> directives within a domain are ignored, and only an entry for the first +<b>msgid</b> directive and the following <b>msgid</b>, <b>msgid_plural</b>, <b>msgstr</b>, or <b>msgstr[</b><i>index</i><b>]</b> +directives is created. However, some implementations consider duplicate <b>msgid</b> directives within a domain to be an error and +do not produce output at all. Consequently this standard does not specify the behavior of <i>msgfmt</i> if duplicate <b>msgid</b> +directives are encountered within one domain.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_82_19" id="tag_20_82_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a +<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require +implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_82_20" id="tag_20_82_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/gettext.html#tag_20_54"><i>gettext</i></a> , <a href="../utilities/xgettext.html#"><i>xgettext</i></a></p> +<p>XSH <a href="../functions/fprintf.html#"><i>fprintf</i></a> , <a href= +"../functions/gettext.html#tag_17_238"><i>gettext</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_82_21" id="tag_20_82_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 8.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/more.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/mv.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/mv.html b/bdd/mv.html @@ -0,0 +1,385 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>mv</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/msgfmt.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/newgrp.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="mv" id="mv"></a> <a name="tag_20_83" id="tag_20_83"></a><!-- mv --> +<h4 class="mansect"><a name="tag_20_83_01" id="tag_20_83_01"></a>NAME</h4> +<blockquote>mv — move files</blockquote> +<h4 class="mansect"><a name="tag_20_83_02" id="tag_20_83_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>mv</tt> <b>[</b><tt>-if</tt><b>]</b> <i>source_file target_file</i> <tt><br> +<br> +mv</tt> <b>[</b><tt>-if</tt><b>]</b> <i>source_file</i><tt>...</tt> <i>target_dir</i> <tt><br></tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_83_03" id="tag_20_83_03"></a>DESCRIPTION</h4> +<blockquote> +<p>In the first synopsis form, the <i>mv</i> utility shall move the file named by the <i>source_file</i> operand to the destination +specified by the <i>target_file</i>. This first synopsis form is assumed when the final operand does not name an existing directory +and is not a symbolic link referring to an existing directory. In this case, if <i>source_file</i> names a non-directory file and +<i>target_file</i> ends with a trailing <slash> character, <i>mv</i> shall treat this as an error and no <i>source_file</i> +operands shall be processed.</p> +<p>In the second synopsis form, <i>mv</i> shall move each file named by a <i>source_file</i> operand to a destination file in the +existing directory named by the <i>target_dir</i> operand, or referenced if <i>target_dir</i> is a symbolic link referring to an +existing directory. The destination path for each <i>source_file</i> shall be the concatenation of the target directory, a single +<slash> character if the target did not end in a <slash>, and the last pathname component of the <i>source_file</i>. +This second form is assumed when the final operand names an existing directory.</p> +<p>If any operand specifies an existing file of a type not specified by the System Interfaces volume of POSIX.1-2024, the behavior +is implementation-defined.</p> +<p>For each <i>source_file</i> the following steps shall be taken:</p> +<ol> +<li> +<p>If the destination path exists, the <b>-f</b> option is not specified, and either of the following conditions is true:</p> +<ol type="a"> +<li> +<p>The permissions of the destination path do not permit writing and the standard input is a terminal.</p> +</li> +<li> +<p>The <b>-i</b> option is specified.</p> +</li> +</ol> +<p>the <i>mv</i> utility shall write a prompt to standard error and read a line from standard input. If the response is not +affirmative, <i>mv</i> shall do nothing more with the current <i>source_file</i> and go on to any remaining +<i>source_file</i>s.</p> +</li> +<li> +<p>If the <i>source_file</i> operand and destination path resolve to either the same existing directory entry or different +directory entries for the same existing file, then the destination path shall not be removed, and one of the following shall +occur:</p> +<ol type="a"> +<li> +<p>No change is made to <i>source_file</i>, no error occurs, and no diagnostic is issued.</p> +</li> +<li> +<p>No change is made to <i>source_file</i>, a diagnostic is issued to standard error identifying the two names, and the exit status +is affected.</p> +</li> +<li> +<p>If the <i>source_file</i> operand and destination path name distinct directory entries, then the <i>source_file</i> operand is +removed, no error occurs, and no diagnostic is issued.</p> +</li> +</ol> +<p>The <i>mv</i> utility shall do nothing more with the current <i>source_file</i>, and go on to any remaining +<i>source_file</i>s.</p> +</li> +<li> +<p>The <i>mv</i> utility shall perform actions equivalent to the <a href="../functions/rename.html"><i>rename</i>()</a> function +defined in the System Interfaces volume of POSIX.1-2024, called with the following arguments:</p> +<ol type="a"> +<li> +<p>The <i>source_file</i> operand is used as the <i>old</i> argument.</p> +</li> +<li> +<p>The destination path is used as the <i>new</i> argument.</p> +</li> +</ol> +<p>If this succeeds, <i>mv</i> shall do nothing more with the current <i>source_file</i> and go on to any remaining +<i>source_file</i>s. If this fails for any reasons other than those described for the <i>errno</i> [EXDEV] in the System Interfaces +volume of POSIX.1-2024, <i>mv</i> shall write a diagnostic message to standard error, do nothing more with the current +<i>source_file</i>, and go on to any remaining <i>source_file</i>s.</p> +</li> +<li> +<p>If the destination path exists, and it is a file of type directory and <i>source_file</i> is not a file of type directory, or it +is a file not of type directory and <i>source_file</i> is a file of type directory, <i>mv</i> shall write a diagnostic message to +standard error, do nothing more with the current <i>source_file</i>, and go on to any remaining <i>source_file</i>s. If the +destination path exists and was created by a previous step, it is unspecified whether this will treated as an error or the +destination path will be overwritten.</p> +</li> +<li> +<p>If the destination path exists, <i>mv</i> shall attempt to remove it. If this fails for any reason, <i>mv</i> shall write a +diagnostic message to standard error, do nothing more with the current <i>source_file</i>, and go on to any remaining +<i>source_file</i>s.</p> +</li> +<li> +<p>The file hierarchy rooted in <i>source_file</i> shall be duplicated as a file hierarchy rooted in the destination path. If +<i>source_file</i> or any of the files below it in the hierarchy are symbolic links, the links themselves shall be duplicated, +including their contents, rather than any files to which they refer. The following characteristics of each file in the file +hierarchy shall be duplicated:</p> +<ul> +<li> +<p>The time of last data modification and time of last access</p> +</li> +<li> +<p>The user ID and group ID</p> +</li> +<li> +<p>The file mode</p> +</li> +</ul> +<p>If the user ID, group ID, or file mode of a regular file cannot be duplicated, the file mode bits S_ISUID and S_ISGID shall not +be duplicated.</p> +<p>When files are duplicated to another file system, the implementation may require that the process invoking <i>mv</i> has read +access to each file being duplicated.</p> +<p>If files being duplicated to another file system have hard links to other files, it is unspecified whether the files copied to +the new file system have the hard links preserved or separate copies are created for the linked files.</p> +<p>If the duplication of the file hierarchy fails for any reason, <i>mv</i> shall write a diagnostic message to standard error, do +nothing more with the current <i>source_file</i>, and go on to any remaining <i>source_file</i>s.</p> +<p>If the duplication of the file characteristics fails for any reason, <i>mv</i> shall write a diagnostic message to standard +error, but this failure shall not cause <i>mv</i> to modify its exit status.</p> +</li> +<li> +<p>The file hierarchy rooted in <i>source_file</i> shall be removed. If this fails for any reason, <i>mv</i> shall write a +diagnostic message to the standard error, do nothing more with the current <i>source_file</i>, and go on to any remaining +<i>source_file</i>s.</p> +</li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_83_04" id="tag_20_83_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>mv</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-f</b></dt> +<dd>Do not prompt for confirmation if the destination path exists. Any previous occurrence of the <b>-i</b> option is ignored.</dd> +<dt><b>-i</b></dt> +<dd>Prompt for confirmation if the destination path exists. Any previous occurrence of the <b>-f</b> option is ignored.</dd> +</dl> +<p>Specifying more than one of the <b>-f</b> or <b>-i</b> options shall not be considered an error. The last option specified shall +determine the behavior of <i>mv</i>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_83_05" id="tag_20_83_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>source_file</i></dt> +<dd>A pathname of a file or directory to be moved.</dd> +<dt><i>target_file</i></dt> +<dd>A new pathname for the file or directory being moved.</dd> +<dt><i>target_dir</i></dt> +<dd>A pathname of an existing directory into which to move the input files.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_83_06" id="tag_20_83_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be used to read an input line in response to each prompt specified in the STDERR section. Otherwise, +the standard input shall not be used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_83_07" id="tag_20_83_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files specified by each <i>source_file</i> operand can be of any file type.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_83_08" id="tag_20_83_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>mv</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_COLLATE</i></dt> +<dd><br> +Determine the locale for the behavior of ranges, equivalence classes, and multi-character collating elements used in the extended +regular expression defined for the <b>yesexpr</b> locale keyword in the <i>LC_MESSAGES</i> category.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files), the behavior of character classes used in the extended regular +expression defined for the <b>yesexpr</b> locale keyword in the <i>LC_MESSAGES</i> category.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale used to process affirmative responses, and the locale used to affect the format and contents of diagnostic +messages and prompts written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_83_09" id="tag_20_83_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_83_10" id="tag_20_83_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_83_11" id="tag_20_83_11"></a>STDERR</h4> +<blockquote> +<p>Prompts shall be written to the standard error under the conditions specified in the DESCRIPTION section. The prompts shall +contain the destination pathname, but their format is otherwise unspecified. Otherwise, the standard error shall be used only for +diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_83_12" id="tag_20_83_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>The output files may be of any file type.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_83_13" id="tag_20_83_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_83_14" id="tag_20_83_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>All requested files (excluding files where a non-affirmative response was given to a request for confirmation) were +successfully moved.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_83_15" id="tag_20_83_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>If the copying or removal of <i>source_file</i> is prematurely terminated by a signal or error, <i>mv</i> may leave a partial +copy of <i>source_file</i> at the source or destination. The <i>mv</i> utility shall not modify both <i>source_file</i> and the +destination path simultaneously; termination at any point shall leave either <i>source_file</i> or the destination path +complete.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_83_16" id="tag_20_83_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Some implementations mark for update the last file status change timestamp of renamed files and some do not. Applications which +make use of the last file status change timestamp may behave differently with respect to renamed files unless they are designed to +allow for either behavior.</p> +<p>The specification ensures that <i>mv</i> <b>a</b> <b>a</b> will not alter the contents of file <b>a</b>, and allows the +implementation to issue an error that a file cannot be moved onto itself. Likewise, when <b>a</b> and <b>b</b> are hard links to +the same file, <i>mv</i> <b>a</b> <b>b</b> will not alter <b>b</b>, but if a diagnostic is not issued, then it is unspecified +whether <b>a</b> is left untouched (as it would be by the <a href="../functions/rename.html"><i>rename</i>()</a> function) or +unlinked (reducing the link count of <b>b</b>).</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_83_17" id="tag_20_83_17"></a>EXAMPLES</h4> +<blockquote> +<p>If the current directory contains only files <b>a</b> (of any type defined by the System Interfaces volume of POSIX.1-2024), +<b>b</b> (also of any type), and a directory <b>c</b>:</p> +<pre> +<tt>mv a b c +mv c d +</tt></pre> +<p>results with the original files <b>a</b> and <b>b</b> residing in the directory <b>d</b> in the current directory.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_83_18" id="tag_20_83_18"></a>RATIONALE</h4> +<blockquote> +<p>Early proposals diverged from the SVID and BSD historical practice in that they required that when the destination path exists, +the <b>-f</b> option is not specified, and input is not a terminal, <i>mv</i> fails. This was done for compatibility with <a href= +"../utilities/cp.html"><i>cp</i></a>. The current text returns to historical practice. It should be noted that this is consistent +with the <a href="../functions/rename.html"><i>rename</i>()</a> function defined in the System Interfaces volume of POSIX.1-2024, +which does not require write permission on the target.</p> +<p>For absolute clarity, paragraph (1), describing the behavior of <i>mv</i> when prompting for confirmation, should be interpreted +in the following manner:</p> +<pre> +<tt>if (exists AND (NOT f_option) AND + ((not_writable AND input_is_terminal) OR i_option)) +</tt></pre> +<p>The <b>-i</b> option exists on BSD systems, giving applications and users a way to avoid accidentally unlinking files when +moving others. When the standard input is not a terminal, the 4.3 BSD <i>mv</i> deletes all existing destination paths without +prompting, even when <b>-i</b> is specified; this is inconsistent with the behavior of the 4.3 BSD <a href= +"../utilities/cp.html"><i>cp</i></a> utility, which always generates an error when the file is unwritable and the standard input is +not a terminal. The standard developers decided that use of <b>-i</b> is a request for interaction, so when the destination path +exists, the utility takes instructions from whatever responds to standard input.</p> +<p>The <a href="../functions/rename.html"><i>rename</i>()</a> function is able to move directories within the same file system. +Some historical versions of <i>mv</i> have been able to move directories, but not to a different file system. The standard +developers considered that this was an annoying inconsistency, so this volume of POSIX.1-2024 requires directories to be able to be +moved even across file systems. There is no <b>-R</b> option to confirm that moving a directory is actually intended, since such an +option was not required for moving directories in historical practice. Requiring the application to specify it sometimes, depending +on the destination, seemed just as inconsistent. The semantics of the <a href="../functions/rename.html"><i>rename</i>()</a> +function were preserved as much as possible. For example, <i>mv</i> is not permitted to "rename" files to or from directories, +even though they might be empty and removable.</p> +<p>Historic implementations of <i>mv</i> did not exit with a non-zero exit status if they were unable to duplicate any file +characteristics when moving a file across file systems, nor did they write a diagnostic message for the user. The former behavior +has been preserved to prevent scripts from breaking; a diagnostic message is now required, however, so that users are alerted that +the file characteristics have changed.</p> +<p>The exact format of the interactive prompts is unspecified. Only the general nature of the contents of prompts are specified +because implementations may desire more descriptive prompts than those used on historical implementations. Therefore, an +application not using the <b>-f</b> option or using the <b>-i</b> option relies on the system to provide the most suitable dialog +directly with the user, based on the behavior specified.</p> +<p>When <i>mv</i> is dealing with a single file system and <i>source_file</i> is a symbolic link, the link itself is moved as a +consequence of the dependence on the <a href="../functions/rename.html"><i>rename</i>()</a> functionality, per the DESCRIPTION. +Across file systems, this has to be made explicit.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_83_19" id="tag_20_83_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a +<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require +implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_83_20" id="tag_20_83_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/cp.html#"><i>cp</i></a> , <a href="../utilities/ln.html#"><i>ln</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/rename.html#"><i>rename</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_83_21" id="tag_20_83_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_83_22" id="tag_20_83_22"></a>Issue 6</h4> +<blockquote> +<p>The <i>mv</i> utility is changed to describe processing of symbolic links as specified in the IEEE P1003.2b draft +standard.</p> +<p>The APPLICATION USAGE section is added.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_83_23" id="tag_20_83_23"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #016 is applied.</p> +<p>Austin Group Interpretation 1003.1-2001 #126 is applied, changing the description of the <i>LC_MESSAGES</i> environment +variable.</p> +<p>Austin Group Interpretations 1003.1-2001 #164, #168, and #169 are applied.</p> +<p>SD5-XCU-ERN-13 is applied, making an editorial correction to the SYNOPSIS.</p> +<p>SD5-XCU-ERN-51 is applied to the DESCRIPTION, defining the behavior for when files are being duplicated to another file system +while having hard links.</p> +<p>Changes are made related to support for finegrained timestamps.</p> +<p>POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0124 [48] is applied.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0147 [534] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_83_24" id="tag_20_83_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to disallow the creation of filenames containing any bytes that +have the encoded value of a <newline> character.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1732 is applied, changing the EXIT STATUS section.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/msgfmt.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/newgrp.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/newgrp.html b/bdd/newgrp.html @@ -0,0 +1,280 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>newgrp</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/mv.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/ngettext.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="newgrp" id="newgrp"></a> <a name="tag_20_84" id="tag_20_84"></a><!-- newgrp --> +<h4 class="mansect"><a name="tag_20_84_01" id="tag_20_84_01"></a>NAME</h4> +<blockquote>newgrp — change to a new group</blockquote> +<h4 class="mansect"><a name="tag_20_84_02" id="tag_20_84_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>newgrp</tt> <b>[</b><tt>-l</tt><b>] [</b><i>group</i><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_84_03" id="tag_20_84_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>newgrp</i> utility shall create a new shell execution environment with a new real and effective group identification. Of +the attributes listed in <a href="../utilities/V3_chap02.html#tag_19_13"><i>2.13 Shell Execution Environment</i></a> , the new +shell execution environment shall retain the working directory, file creation mask, and exported variables from the previous +environment (that is, open files, traps, unexported variables, alias definitions, shell functions, and <a href= +"../utilities/V3_chap02.html#set"><i>set</i></a> options may be lost). All other aspects of the process environment that are +preserved by the <i>exec</i> family of functions defined in the System Interfaces volume of POSIX.1-2024 shall also be preserved by +<i>newgrp</i>; whether other aspects are preserved is unspecified.</p> +<p>A failure to assign the new group identifications (for example, for security or password-related reasons) shall not prevent the +new shell execution environment from being created.</p> +<p>The <i>newgrp</i> utility shall affect the supplemental groups for the process as follows:</p> +<ul> +<li> +<p>On systems where the effective group ID is normally in the supplementary group list (or whenever the old effective group ID +actually is in the supplementary group list):</p> +<ul> +<li> +<p>If the new effective group ID is also in the supplementary group list, <i>newgrp</i> shall change the effective group ID.</p> +</li> +<li> +<p>If the new effective group ID is not in the supplementary group list, <i>newgrp</i> shall add the new effective group ID to the +list, if there is room to add it.</p> +</li> +</ul> +</li> +<li> +<p>On systems where the effective group ID is not normally in the supplementary group list (or whenever the old effective group ID +is not in the supplementary group list):</p> +<ul> +<li> +<p>If the new effective group ID is in the supplementary group list, <i>newgrp</i> shall delete it.</p> +</li> +<li> +<p>If the old effective group ID is not in the supplementary list, <i>newgrp</i> shall add it if there is room.</p> +</li> +</ul> +</li> +</ul> +<basefont size="2"> +<dl> +<dt><b>Note:</b></dt> +<dd>The System Interfaces volume of POSIX.1-2024 does not specify whether the effective group ID of a process is included in its +supplementary group list.</dd> +</dl> +<basefont size="3"> +<p>With no operands, <i>newgrp</i> shall change the effective group back to the groups identified in the user's user entry, and +shall set the list of supplementary groups to that set in the user's group database entries.</p> +<p>If the first argument is <tt>'-'</tt>, the results are unspecified.</p> +<p>If a password is required for the specified group, and the user is not listed as a member of that group in the group database, +the user shall be prompted to enter the correct password for that group. If the user is listed as a member of that group, no +password shall be requested. If no password is required for the specified group, it is implementation-defined whether users not +listed as members of that group can change to that group. Whether or not a password is required, implementation-defined system +accounting or security mechanisms may impose additional authorization restrictions that may cause <i>newgrp</i> to write a +diagnostic message and suppress the changing of the group identification.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_84_04" id="tag_20_84_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>newgrp</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> , except for the unspecified usage of <tt>'-'</tt>.</p> +<p>The following option shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-l</b></dt> +<dd>(The letter ell.) Change the environment to what would be expected if the user actually logged in again.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_84_05" id="tag_20_84_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>group</i></dt> +<dd>A group name from the group database or a non-negative numeric group ID. Specifies the group ID to which the real and effective +group IDs shall be set. If <i>group</i> is a non-negative numeric string and exists in the group database as a group name (see +<a href="../functions/getgrnam.html"><i>getgrnam</i>()</a>), the numeric group ID associated with that group name shall be used as +the group ID.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_84_06" id="tag_20_84_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_84_07" id="tag_20_84_07"></a>INPUT FILES</h4> +<blockquote> +<p>The file <b>/dev/tty</b> shall be used to read a single line of text for password checking, when one is required.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_84_08" id="tag_20_84_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>newgrp</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_84_09" id="tag_20_84_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_84_10" id="tag_20_84_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_84_11" id="tag_20_84_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used for diagnostic messages and a prompt string for a password, if one is required. Diagnostic +messages may be written in cases where the exit status is not available. See the EXIT STATUS section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_84_12" id="tag_20_84_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_84_13" id="tag_20_84_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_84_14" id="tag_20_84_14"></a>EXIT STATUS</h4> +<blockquote> +<p>If <i>newgrp</i> succeeds in creating a new shell execution environment, whether or not the group identification was changed +successfully, the exit status shall be the exit status of the shell. Otherwise, the following exit value shall be returned:</p> +<dl compact> +<dd></dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_84_15" id="tag_20_84_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>The invoking shell may terminate.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_84_16" id="tag_20_84_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>There is no convenient way to enter a password into the group database. Use of group passwords is not encouraged, because by +their very nature they encourage poor security practices. Group passwords may disappear in the future.</p> +<p>A common implementation of <i>newgrp</i> is that the current shell uses <i>exec</i> to overlay itself with <i>newgrp</i>, which +in turn overlays itself with a new shell after changing group. On some implementations, however, this may not occur and +<i>newgrp</i> may be invoked as a subprocess.</p> +<p>The <i>newgrp</i> command is intended only for use from an interactive terminal. It does not offer a useful interface for the +support of applications.</p> +<p>The exit status of <i>newgrp</i> is generally inapplicable. If <i>newgrp</i> is used in a script, in most cases it successfully +invokes a new shell and the rest of the original shell script is bypassed when the new shell exits. Used interactively, +<i>newgrp</i> displays diagnostic messages to indicate problems. But usage such as:</p> +<pre> +<tt>newgrp foo +echo $? +</tt></pre> +<p>is not useful because the new shell might not have access to any status <i>newgrp</i> may have generated (and most historical +systems do not provide this status). A zero status echoed here does not necessarily indicate that the user has changed to the new +group successfully. Following <i>newgrp</i> with the <a href="../utilities/id.html"><i>id</i></a> command provides a portable means +of determining whether the group change was successful or not.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_84_17" id="tag_20_84_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_84_18" id="tag_20_84_18"></a>RATIONALE</h4> +<blockquote> +<p>Most historical implementations use one of the <i>exec</i> functions to implement the behavior of <i>newgrp</i>. Errors detected +before the <i>exec</i> leave the environment unchanged, while errors detected after the <i>exec</i> leave the user in a changed +environment. While it would be useful to have <i>newgrp</i> issue a diagnostic message to tell the user that the environment +changed, it would be inappropriate to require this change to some historical implementations.</p> +<p>The password mechanism is allowed in the group database, but how this would be implemented is not specified.</p> +<p>The <i>newgrp</i> utility was retained in this volume of POSIX.1-2024, even given the existence of the multiple group +permissions feature in the System Interfaces volume of POSIX.1-2024, for several reasons. First, in some implementations, the group +ownership of a newly created file is determined by the group of the directory in which the file is created, as allowed by the +System Interfaces volume of POSIX.1-2024; on other implementations, the group ownership of a newly created file is determined by +the effective group ID. On implementations of the latter type, <i>newgrp</i> allows files to be created with a specific group +ownership. Finally, many implementations use the real group ID in accounting, and on such systems, <i>newgrp</i> allows the +accounting identity of the user to be changed.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_84_19" id="tag_20_84_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_84_20" id="tag_20_84_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19"><i>2. Shell Command Language</i></a> , <a href= +"../utilities/sh.html#"><i>sh</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/exec.html#tag_17_129"><i>exec</i></a> , <a href="../functions/getgrnam.html#"><i>getgrnam</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_84_21" id="tag_20_84_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_84_22" id="tag_20_84_22"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +<p>The obsolescent SYNOPSIS is removed.</p> +<p>The text describing supplemental groups is no longer conditional on {NGROUPS_MAX} being greater than 1. This is because +{NGROUPS_MAX} now has a minimum value of 8. This is a FIPS requirement.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_84_23" id="tag_20_84_23"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #027 is applied, clarifying the behavior if the first argument is <tt>'-'</tt>.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>The <i>newgrp</i> utility is moved from the User Portability Utilities option to the Base. User Portability Utilities is now an +option for interactive utilities.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_84_24" id="tag_20_84_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/mv.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/ngettext.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/ngettext.html b/bdd/ngettext.html @@ -0,0 +1,439 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>gettext</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/getopts.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/grep.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="gettext" id="gettext"></a> <a name="tag_20_54" id="tag_20_54"></a><!-- gettext --> +<h4 class="mansect"><a name="tag_20_54_01" id="tag_20_54_01"></a>NAME</h4> +<blockquote>gettext, ngettext — retrieve text string from messages object</blockquote> +<h4 class="mansect"><a name="tag_20_54_02" id="tag_20_54_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>gettext</tt> <b>[</b><tt>-e|-E</tt><b>] [</b><tt>-d textdomain</tt><b>] [</b><i>textdomain</i><b>]</b> <i>msgid</i> <tt><br> +<br> +gettext</tt> <b>[</b><tt>-e|-E</tt><b>] [</b><tt>-n</tt><b>]</b> <tt>-s</tt> <b>[</b><tt>-d</tt> <i>textdomain</i><b>]</b> +<i>msgid</i><tt>...<br> +<br> +ngettext</tt> <b>[</b><tt>-e|-E</tt><b>] [</b><tt>-d</tt> <i>textdomain</i><b>] [</b><i>textdomain</i><b>]</b> <i>msgid +msgid_plural n</i> <tt><br></tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_03" id="tag_20_54_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>gettext</i> and <i>ngettext</i> utilities shall write to standard output the message string(s) that would result from the +following calls to functions defined in the System Interfaces volume of POSIX.1-2024:</p> +<pre> +<tt>if (textdomainname == NULL || textdomainname[0] == '\0') + message_string = msgid; +else { + setlocale(LC_ALL, ""); + if (textdomaindir != NULL) + bindtextdomain(textdomainname, textdomaindir); + if (msgid_plural == NULL) + message_string = dgettext(textdomainname, msgid); + else + message_string = dngettext(textdomainname, msgid, msgid_plural, n); +} +</tt></pre> +<p>where:</p> +<ul> +<li> +<p>The <i>textdomaindir</i> variable is a string containing the value of the <i>TEXTDOMAINDIR</i> environment variable, if set and +not empty, or is NULL otherwise.</p> +</li> +<li> +<p>The <i>textdomainname</i> variable is a string containing the text domain name obtained from, in decreasing order of +precedence:</p> +<ul> +<li> +<p>The optional operand <i>textdomain,</i> if present</p> +</li> +<li> +<p>The <b>-d</b> <i>textdomain</i> option, if specified</p> +</li> +<li> +<p>The <i>TEXTDOMAIN</i> environment variable, if set and not empty</p> +</li> +</ul> +<p>If the text domain name cannot be obtained from these sources, the <i>textdomainname</i> variable is NULL.</p> +</li> +<li> +<p>If the <b>-s</b> option of <i>gettext</i> is not specified and for the <i>ngettext</i> utility, the <i>msgid</i> variable is a +string containing:</p> +<ul> +<li> +<p>The value of the <i>msgid</i> operand, if the <b>-E</b> option is specified</p> +</li> +<li> +<p>The value of the <i>msgid</i> operand with C-language escape sequences processed (see below), if the <b>-e</b> option is +specified</p> +</li> +<li> +<p>The value of the <i>msgid</i> operand with C-language escape sequences optionally processed (see below), otherwise</p> +</li> +</ul> +</li> +<li> +<p>If the <b>-s</b> option of <i>gettext</i> is specified, the <i>msgid</i> variable is a string containing:</p> +<ul> +<li> +<p>The value of each <i>msgid</i> operand in turn, if the <b>-E</b> option is specified or neither the <b>-e</b> nor the <b>-E</b> +option is specified</p> +</li> +<li> +<p>The value of each <i>msgid</i> operand in turn with C-language escape sequences processed (see below), if the <b>-e</b> option +is specified</p> +</li> +</ul> +</li> +<li> +<p>For the <i>gettext</i> utility, the <i>msgid_plural</i> variable is NULL. For the <i>ngettext</i> utility, the +<i>msgid_plural</i> variable is a string containing:</p> +<ul> +<li> +<p>The value of the <i>msgid_plural</i> operand, if the <b>-E</b> option is specified</p> +</li> +<li> +<p>The value of the <i>msgid_plural</i> operand with C-language escape sequences processed (see below), if the <b>-e</b> option is +specified</p> +</li> +<li> +<p>The value of the <i>msgid_plural</i> operand with C-language escape sequences optionally processed (see below), otherwise</p> +</li> +</ul> +</li> +<li> +<p>For the <i>gettext</i> utility, the <i>n</i> variable is 1 (one). For the <i>ngettext</i> utility the <i>n</i> variable is the +<i>n</i> operand, parsed as an integer as if by using the <a href="../functions/strtoul.html"><i>strtoul</i>()</a> function with a +<i>base</i> argument of 10.</p> +</li> +</ul> +<p>When C-language escape sequences are processed, they shall be processed as specified for character string literals in the +ISO C standard, except that <i>universal-character-name</i> escape sequences need not be supported. Implementations may also +support a <backslash> <tt>'c'</tt> escape sequence; if supported, the <tt>'\c'</tt> and all characters following it shall be +removed and, if the <b>-s</b> option is specified, the behavior shall be as if the <b>-n</b> option is also specified.</p> +<p>For the <i>ngettext</i> utility, and for the <i>gettext</i> utility if the <b>-s</b> option is not specified, the resulting +message string shall be written to standard output. If the <b>-s</b> option of <i>gettext</i> is specified, the resulting message +string for each <i>msgid</i> shall be written to standard output with consecutive message strings separated by a single +<space> character and, if the <b>-n</b> option is not specified, a <newline> shall be written after the last message +string. If the <b>-s</b> and <b>-n</b> options are specified, the trailing <newline> shall be omitted.</p> +<p>Under conditions where the <i>textdomainname</i> variable in the above code would be NULL, these utilities may write a +diagnostic message to standard error and exit with non-zero status.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_04" id="tag_20_54_04"></a>OPTIONS</h4> +<blockquote> +<p>These utilities shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a> +.</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-d </b><i>textdomain</i></dt> +<dd><br> +Retrieve the translated message from the domain <i>textdomain</i>, if <i>textdomain</i> is not specified as an operand.</dd> +<dt><b>-e</b></dt> +<dd>Process C-language escape sequences in <i>msgid</i> and <i>msgid_plural</i> operands.</dd> +<dt><b>-E</b></dt> +<dd>Do not process C-language escape sequences in <i>msgid</i> and <i>msgid_plural</i> operands.</dd> +</dl> +<p>The <i>gettext</i> utility shall also support the following options:</p> +<dl compact> +<dd></dd> +<dt><b>-n</b></dt> +<dd>Modify the behavior of the <b>-s</b> option such that a <newline> is not appended to the output.</dd> +<dt><b>-s</b></dt> +<dd>Separate the message strings obtained from each <i>msgid</i> operand with <space> characters in the output, and (if +<b>-n</b> is not also specified) append a <newline> to the output.</dd> +</dl> +<p>If neither of the mutually exclusive <b>-e</b> and <b>-E</b> options is specified, it is unspecified which is the default, +except that if the <b>-s</b> option of <i>gettext</i> is specified then <b>-E</b> shall be the default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_05" id="tag_20_54_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>textdomain</i></dt> +<dd>A text domain name used to retrieve the translated message. This shall override the specification by the <b>-d</b> option, if +present.</dd> +<dt><i>msgid</i></dt> +<dd>A key to retrieve the translated message.</dd> +<dt><i>msgid_plural</i></dt> +<dd>A default plural if no corresponding plural message can be found.</dd> +<dt><i>n</i></dt> +<dd>A non-negative decimal integer to be used as the <i>n</i> argument to <a href= +"../functions/dngettext.html"><i>dngettext</i>()</a> (see the DESCRIPTION).</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_06" id="tag_20_54_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_07" id="tag_20_54_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files are messages object files (see <a href="../utilities/msgfmt.html#"><i>msgfmt</i></a> ).</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_08" id="tag_20_54_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>gettext</i> and <i>ngettext</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LANGUAGE</i></dt> +<dd>Determine the location of messages objects <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src= +"../images/opt-start.gif" alt="[Option Start]" border="0"> if <i>NLSPATH</i> is not set or the evaluation of <i>NLSPATH</i> +did not lead to a suitable messages object being found. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale name used to locate messages objects, and the locale that should be used to affect the format and contents of +diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>TEXTDOMAIN</i></dt> +<dd><br> +Specify the text domain name. (See XBD <a href="../basedefs/V1_chap03.html#tag_03_386"><i>3.386 Text Domain</i></a> .)</dd> +<dt><i>TEXTDOMAINDIR</i></dt> +<dd><br> +Specify the pathname to the messages object hierarchy. <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src= +"../images/opt-start.gif" alt="[Option Start]" border="0"> <i>NLSPATH</i> shall have precedence over <i>TEXTDOMAINDIR .</i> +<img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_09" id="tag_20_54_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_10" id="tag_20_54_10"></a>STDOUT</h4> +<blockquote> +<p>See DESCRIPTION.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_11" id="tag_20_54_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_12" id="tag_20_54_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_13" id="tag_20_54_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_14" id="tag_20_54_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_15" id="tag_20_54_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_54_16" id="tag_20_54_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Since it is unspecified which of the <b>-e</b> or <b>-E</b> options is the default, except when the <b>-s</b> option of +<i>gettext</i> is specified, portable applications need to ensure that <b>-e</b>, <b>-E</b>, or (for <i>gettext</i>) <b>-s</b> is +specified whenever a <i>msgid</i> or <i>msgid_plural</i> operand contains, or might contain, a <backslash> character.</p> +<p>Note that, unless the <b>-s</b> option of <i>gettext</i> is specified without <b>-n</b>, the message(s) written to standard +output are not followed by a <newline>. (Therefore the output only ends with a <newline> if the last message ends with +one.)</p> +<p>Both <i>msgid</i> and <i>msgid_plural</i> should be properly quoted for the shell.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_17" id="tag_20_54_17"></a>EXAMPLES</h4> +<blockquote> +<p>The following examples assume that the following portable messages object source file (dot-po file) has been compiled to a valid +file <b>mail.mo</b> by the <a href="../utilities/msgfmt.html"><i>msgfmt</i></a> utility. See the EXTENDED DESCRIPTION section of +the <a href="../utilities/msgfmt.html"><i>msgfmt</i></a> utility for a description of the dot-po file format.</p> +<pre> +<tt>msgid "" +msgstr "" +"Content-Type: text/plain; charset=utf-8\n" +"Plural-Forms: nplurals=4; plural=n==1?0: (n>1&&n<=10)?1: (n==0)?2:3;\n" +<br> +msgid "recipient" +msgid_plural "recipients" +msgstr[0] "1 recipient" +msgstr[1] "2 to 10 recipients" +msgstr[2] "no recipients" +msgstr[3] "more than 10 recipients" +<br> +msgid "%d attachment\n" +msgid_plural "%d attachments\n" +msgstr[0] "1 (%d) attachment\n" +msgstr[1] "2 to 10 (%d) attachments\n" +msgstr[2] "no (%d) attachments\n" +msgstr[3] "more than 10 (%d) attachments\n" +</tt></pre> +<p>They also assume that <b>mail.mo</b> is installed in the directory that <i>gettext</i> and <i>ngettext</i> search for the +current locale. See the OPTIONS and ENVIRONMENT VARIABLES sections above and the description of <a href= +"../functions/gettext.html"><i>gettext</i>()</a> for details on how this search is performed.</p> +<p>The command</p> +<pre> +<tt>ngettext -d mail recipient recipients 0 +</tt></pre> +<p>will write <tt>"no recipients"</tt>.</p> +<p>The command</p> +<pre> +<tt>ngettext -d mail recipient recipients 1 +</tt></pre> +<p>will write <tt>"1 recipient"</tt>.</p> +<p>The command</p> +<pre> +<tt>ngettext -d mail recipient recipients 5 +</tt></pre> +<p>will write <tt>"2 to 10 recipients"</tt>.</p> +<p>The command</p> +<pre> +<tt>ngettext -d mail recipient recipients 11 +</tt></pre> +<p>will write <tt>"more than 10 recipients"</tt>.</p> +<p>The command</p> +<pre> +<tt>ngettext -d mail Call Calls 1 +</tt></pre> +<p>will write <tt>"Call"</tt>. Note that <tt>"Call"</tt> is not in the messages object.</p> +<p>The command</p> +<pre> +<tt>ngettext -d mail Call Calls 0 +</tt></pre> +<p>will write <tt>"Calls"</tt>.</p> +<p>The command</p> +<pre> +<tt>ngettext -d mail Call Calls 10 +</tt></pre> +<p>will write <tt>"Calls"</tt>.</p> +<p>The command</p> +<pre> +<tt>ngettext -ed mail "%d attachment\n" "%d attachments\n" 1 +</tt></pre> +<p>will write the same as</p> +<pre> +<tt>printf "1 (%%d) attachment\n" +</tt></pre> +<p>(i.e. <tt>"1 (%d) attachment"</tt> followed by a <newline> character). The output of <i>ngettext</i> can be used as a +format string for <a href="../utilities/printf.html"><i>printf</i></a>.</p> +<p>The command</p> +<pre> +<tt>printf "$(ngettext -ed mail "%d attachment\n" "%d attachments\n" 1)" 10 +</tt></pre> +<p>will write the same as</p> +<pre> +<tt>printf "1 (%d) attachment\n" 10 +</tt></pre> +<p>(i.e. <tt>"1 (10) attachment"</tt> followed by a <newline> character).</p> +<p>The command</p> +<pre> +<tt>ngettext -e -d mail "\tsubject\n" "\tsubjects\n" 0 +</tt></pre> +<p>will write the same as</p> +<pre> +<tt>printf "\tsubjects\n" +</tt></pre> +<p>(i.e. a <tab> character, followed by <tt>"subjects"</tt> followed by a <newline> character). Note that +<tt>"\tsubject\n"</tt> is not in the messages object.</p> +<p>The command</p> +<pre> +<tt>printf "%s\n" "$(ngettext -E -d mail "subject" "subjects" 0)" +</tt></pre> +<p>will write the same as</p> +<pre> +<tt>printf "subjects\n" +</tt></pre> +<p>(i.e. <tt>"subjects"</tt> followed by a <newline> character). Note that <tt>"subject"</tt> is not in the messages +object.</p> +<p>The command</p> +<pre> +<tt>gettext -s -d mail "recipient" +</tt></pre> +<p>will write <tt>"1 recipient"</tt> followed by a <newline> character.</p> +<p>The command</p> +<pre> +<tt>gettext -s -n -d mail "recipient" +</tt></pre> +<p>will write <tt>"1 recipient"</tt> without a <newline> character.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_18" id="tag_20_54_18"></a>RATIONALE</h4> +<blockquote> +<p>Historical implementations did not support the <tt>'\a'</tt> C-language escape sequence. This standard requires it to be +supported for consistency with other utilities that support the table in XBD <a href="../basedefs/V1_chap05.html#tag_05"><i>5. File +Format Notation</i></a> .</p> +<p>Unlike other standard utilities, the behavior of <i>gettext</i> and <i>ngettext</i> is not undefined when <i>NLSPATH</i> +overrides the system default path; see XBD <a href="../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization +Variables</i></a> . This is so that applications can use these utilities to obtain message strings from messages objects in other +locations. However, it also means that they need to be implemented in such a way that they do not do anything that would result in +undefined behavior when they need to write a diagnostic message. In particular, they should not use a string obtained from a +message catalog or a messages object as a format string (or should only do so after checking that the string contains the correct +conversions).</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_19" id="tag_20_54_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_20" id="tag_20_54_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/msgfmt.html#"><i>msgfmt</i></a> , <a href="../utilities/printf.html#tag_20_96"><i>printf</i></a></p> +<p>XBD <a href="../basedefs/V1_chap07.html#tag_07"><i>7. Locale</i></a> , <a href="../basedefs/V1_chap08.html#tag_08"><i>8. +Environment Variables</i></a> , <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/gettext.html#tag_17_238"><i>gettext</i></a> , <a href= +"../functions/iconv.html#tag_17_248"><i>iconv</i></a> , <a href="../functions/setlocale.html#"><i>setlocale</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_54_21" id="tag_20_54_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 8.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/getopts.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/grep.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/nice.html b/bdd/nice.html @@ -0,0 +1,265 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>nice</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/ngettext.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/nl.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="nice" id="nice"></a> <a name="tag_20_86" id="tag_20_86"></a><!-- nice --> +<h4 class="mansect"><a name="tag_20_86_01" id="tag_20_86_01"></a>NAME</h4> +<blockquote>nice — invoke a utility with an altered nice value</blockquote> +<h4 class="mansect"><a name="tag_20_86_02" id="tag_20_86_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>nice</tt> <b>[</b><tt>-n</tt> <i>increment</i><b>]</b> <i>utility</i> <b>[</b><i>argument</i><tt>...</tt><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_86_03" id="tag_20_86_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>nice</i> utility shall invoke a utility, requesting that it be run with a different nice value (see XBD <a href= +"../basedefs/V1_chap03.html#tag_03_225"><i>3.225 Nice Value</i></a> ). With no options, the executed utility shall be run with a +nice value that is some implementation-defined quantity greater than or equal to the nice value of the current process. If the user +lacks appropriate privileges to affect the nice value in the requested manner, the <i>nice</i> utility shall not affect the nice +value; in this case, a warning message may be written to standard error, but this shall not prevent the invocation of +<i>utility</i> or affect the exit status.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_86_04" id="tag_20_86_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>nice</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following option is supported:</p> +<dl compact> +<dd></dd> +<dt><b>-n </b><i>increment</i></dt> +<dd>A positive or negative decimal integer which shall have the same effect on the execution of the utility as if the utility had +called the <a href="../functions/nice.html"><i>nice</i>()</a> function with the numeric value of the <i>increment</i> +option-argument.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_86_05" id="tag_20_86_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>utility</i></dt> +<dd>The name of a utility that is to be invoked. If the <i>utility</i> operand names any of the special built-in utilities in +<a href="../utilities/V3_chap02.html#tag_19_15"><i>2.15 Special Built-In Utilities</i></a> , the results are undefined.</dd> +<dt><i>argument</i></dt> +<dd>Any string to be supplied as an argument when invoking the utility named by the <i>utility</i> operand.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_86_06" id="tag_20_86_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_86_07" id="tag_20_86_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_86_08" id="tag_20_86_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>nice</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>PATH</i></dt> +<dd>Determine the search path used to locate the utility to be invoked. See XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. +Environment Variables</i></a> .</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_86_09" id="tag_20_86_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_86_10" id="tag_20_86_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_86_11" id="tag_20_86_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_86_12" id="tag_20_86_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_86_13" id="tag_20_86_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_86_14" id="tag_20_86_14"></a>EXIT STATUS</h4> +<blockquote> +<p>If <i>utility</i> is invoked, the exit status of <i>nice</i> shall be the exit status of <i>utility</i>; otherwise, the +<i>nice</i> utility shall exit with one of the following values:</p> +<dl compact> +<dd></dd> +<dt>1-125</dt> +<dd>An error occurred in the <i>nice</i> utility.</dd> +<dt> 126</dt> +<dd>The utility specified by <i>utility</i> was found but could not be invoked.</dd> +<dt> 127</dt> +<dd>The utility specified by <i>utility</i> could not be found.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_86_15" id="tag_20_86_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_86_16" id="tag_20_86_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The only guaranteed portable uses of this utility are:</p> +<dl compact> +<dd></dd> +<dt><i>nice utility</i></dt> +<dd><br> +Run <i>utility</i> with the default higher or equal nice value.</dd> +<dt><i>nice </i><b>-n </b><<i>positive integer</i>><i> utility</i></dt> +<dd><br> +Run <i>utility</i> with a higher nice value.</dd> +</dl> +<p>On some implementations they have no discernible effect on the invoked utility and on some others they are exactly +equivalent.</p> +<p>Historical systems have frequently supported the <<i>positive integer</i>> up to 20. Since there is no error penalty +associated with guessing a number that is too high, users without access to the system conformance document (to see what limits are +actually in place) could use the historical 1 to 20 range or attempt to use very large numbers if the job should be truly low +priority.</p> +<p>The nice value of a process can be displayed using the command:</p> +<pre> +<tt>ps -o nice +</tt></pre> +<p>The <a href="../utilities/command.html"><i>command</i></a>, <a href="../utilities/env.html"><i>env</i></a>, <i>nice</i>, +<a href="../utilities/nohup.html"><i>nohup</i></a>, <a href="../utilities/time.html"><i>time</i></a>, <a href= +"../utilities/timeout.html"><i>timeout</i></a>, and <a href="../utilities/xargs.html"><i>xargs</i></a> utilities have been +specified to use exit code 127 if a utility to be invoked cannot be found, so that applications can distinguish "failure to find a +utility" from "invoked utility exited with an error indication". The value 127 was chosen because it is not commonly used for +other meanings; most utilities use small values for "normal error conditions" and the values above 128 can be confused with +termination due to receipt of a signal. The value 126 was chosen in a similar manner to indicate that the utility could be found, +but not invoked. Some scripts produce meaningful error messages differentiating the 126 and 127 cases. The distinction between exit +codes 126 and 127 is based on KornShell practice that uses 127 when all attempts to <i>exec</i> the utility fail with [ENOENT], and +uses 126 when any attempt to <i>exec</i> the utility fails for any other reason.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_86_17" id="tag_20_86_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_86_18" id="tag_20_86_18"></a>RATIONALE</h4> +<blockquote> +<p>The 4.3 BSD version of <i>nice</i> does not check whether <i>increment</i> is a valid decimal integer. The command <i>nice</i> +<b>-x</b> <i>utility</i>, for example, would be treated the same as the command <i>nice</i> <b>--1</b> <i>utility</i>. If the user +does not have appropriate privileges, this results in a "permission denied" error. This is considered a bug.</p> +<p>When a user without appropriate privileges gives a negative <i>increment</i>, System V treats it like the command <i>nice</i> +<b>-0</b> <i>utility</i>, while 4.3 BSD writes a "permission denied" message and does not run the utility. The standard specifies +the System V behavior together with an optional BSD-style "permission denied" message.</p> +<p>The C shell has a built-in version of <i>nice</i> that has a different interface from the one described in this volume of +POSIX.1-2024.</p> +<p>The term "utility" is used, rather than "command", to highlight the fact that shell compound commands, pipelines, and so on, +cannot be used. Special built-ins also cannot be used. However, "utility" includes user application programs and shell scripts, +not just utilities defined in this volume of POSIX.1-2024.</p> +<p>Historical implementations of <i>nice</i> provide a nice value range of 40 or 41 discrete steps, with the default nice value +being the midpoint of that range. By default, they raise the nice value of the executed utility by 10.</p> +<p>Some historical documentation states that the <i>increment</i> value must be within a fixed range. This is misleading; the valid +<i>increment</i> values on any invocation are determined by the current process nice value, which is not always the default.</p> +<p>The definition of nice value is not intended to suggest that all processes in a system have priorities that are comparable. +Scheduling policy extensions such as the realtime priorities in the System Interfaces volume of POSIX.1-2024 make the notion of a +single underlying priority for all scheduling policies problematic. Some implementations may implement the <i>nice</i>-related +features to affect all processes on the system, others to affect just the general time-sharing activities implied by this volume of +POSIX.1-2024, and others may have no effect at all. Because of the use of "implementation-defined" in <i>nice</i> and <a href= +"../utilities/renice.html"><i>renice</i></a>, a wide range of implementation strategies are possible.</p> +<p>Earlier versions of this standard allowed a <b>-</b><i>increment</i> option. This form is no longer specified by POSIX.1-2024 +but may be present in some implementations.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_86_19" id="tag_20_86_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_86_20" id="tag_20_86_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19"><i>2. Shell Command Language</i></a> , <a href= +"../utilities/renice.html#"><i>renice</i></a></p> +<p>XBD <a href="../basedefs/V1_chap03.html#tag_03_225"><i>3.225 Nice Value</i></a> , <a href= +"../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 +Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/nice.html#tag_17_370"><i>nice</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_86_21" id="tag_20_86_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_86_22" id="tag_20_86_22"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +<p>The obsolescent SYNOPSIS is removed.</p> +<p>IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/18 is applied, deleting a paragraph of RATIONALE that referred +to text no longer in the standard.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_86_23" id="tag_20_86_23"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #027 is applied.</p> +<p>SD5-XCU-ERN-32 and SD5-XCU-ERN-33 are applied, updating the DESCRIPTION, APPLICATION USAGE, and RATIONALE sections.</p> +<p>The <i>nice</i> utility is moved from the User Portability Utilities option to the Base. User Portability Utilities is now an +option for interactive utilities.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_86_24" id="tag_20_86_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1586 is applied, adding the <a href="../utilities/timeout.html"><i>timeout</i></a> utility.</p> +<p>Austin Group Defect 1594 is applied, changing the APPLICATION USAGE section.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/ngettext.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/nl.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/nl.html b/bdd/nl.html @@ -0,0 +1,315 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>nl</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/nice.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/nm.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="nl" id="nl"></a> <a name="tag_20_87" id="tag_20_87"></a><!-- nl --> +<h4 class="mansect"><a name="tag_20_87_01" id="tag_20_87_01"></a>NAME</h4> +<blockquote>nl — line numbering filter</blockquote> +<h4 class="mansect"><a name="tag_20_87_02" id="tag_20_87_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> nl</tt> <b>[</b><tt>-p</tt><b>] [</b><tt>-b</tt> <i>type</i><b>] [</b><tt>-d</tt> <i>delim</i><b>] +[</b><tt>-f</tt> <i>type</i><b>] [</b><tt>-h</tt> <i>type</i><b>] [</b><tt>-i</tt> <i>incr</i><b>] [</b><tt>-l</tt> +<i>num</i><b>]<br></b> <tt> </tt> <b>[</b><tt>-n</tt> <i>format</i><b>] [</b><tt>-s</tt> +<i>sep</i><b>] [</b><tt>-v</tt> <i>startnum</i><b>] [</b><tt>-w</tt> <i>width</i><b>] [</b><i>file</i><b>]</b> <tt><img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div> +</blockquote> +<h4 class="mansect"><a name="tag_20_87_03" id="tag_20_87_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>nl</i> utility shall read lines from the named <i>file</i> or the standard input if no <i>file</i> is named and shall +reproduce the lines to standard output. Lines shall be numbered on the left. Additional functionality may be provided in accordance +with the command options in effect.</p> +<p>The <i>nl</i> utility views the text it reads in terms of logical pages. Line numbering shall be reset at the start of each +logical page. A logical page consists of a header, a body, and a footer section. Empty sections are valid. Different line numbering +options are independently available for header, body, and footer (for example, no numbering of header and footer lines while +numbering blank lines only in the body).</p> +<p>The starts of logical page sections shall be signaled by input lines containing nothing but the following delimiter +characters:</p> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Line</b></p> +</th> +<th align="center"> +<p class="tent"><b>Start of</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">\:\:\:</p> +</td> +<td align="left"> +<p class="tent">Header</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">\:\:</p> +</td> +<td align="left"> +<p class="tent">Body</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">\:</p> +</td> +<td align="left"> +<p class="tent">Footer</p> +</td> +</tr> +</table> +</center> +<p class="tent">Unless otherwise specified, <i>nl</i> shall assume the text being read is in a single logical page body.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_87_04" id="tag_20_87_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>nl</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> . Only one file can be named.</p> +<p class="tent">The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-b </b><i>type</i></dt> +<dd>Specify which logical page body lines shall be numbered. Recognized <i>types</i> and their meaning are: +<dl compact> +<dd></dd> +<dt><b>a</b></dt> +<dd>Number all lines.</dd> +<dt><b>t</b></dt> +<dd>Number only non-empty lines.</dd> +<dt><b>n</b></dt> +<dd>No line numbering.</dd> +<dt><b>p</b><i>string</i></dt> +<dd>Number only lines that contain the basic regular expression specified in <i>string</i>.</dd> +</dl> +<p class="tent">The default <i>type</i> for logical page body shall be <b>t</b> (text lines numbered).</p> +</dd> +<dt><b>-d </b><i>delim</i></dt> +<dd>Specify the delimiter characters that indicate the start of a logical page section. These can be changed from the default +characters <tt>"\:"</tt> to two user-specified characters. If only one character is entered, the second character shall remain the +default character <tt>':'</tt>.</dd> +<dt><b>-f </b><i>type</i></dt> +<dd>Specify the same as <b>b</b> <i>type</i> except for footer. The default for logical page footer shall be <b>n</b> (no lines +numbered).</dd> +<dt><b>-h </b><i>type</i></dt> +<dd>Specify the same as <b>b</b> <i>type</i> except for header. The default <i>type</i> for logical page header shall be <b>n</b> +(no lines numbered).</dd> +<dt><b>-i </b><i>incr</i></dt> +<dd>Specify the increment value used to number logical page lines. The default shall be 1.</dd> +<dt><b>-l </b><i>num</i></dt> +<dd>Specify the number of blank lines to be considered as one. For example, <b>-l 2</b> results in only the second adjacent +blank line being numbered (if the appropriate <b>-h a</b>, <b>-b a</b>, or <b>-f a</b> option is set). The default +shall be 1.</dd> +<dt><b>-n </b><i>format</i></dt> +<dd>Specify the line numbering format. Recognized values are: <b>ln</b>, left justified, leading zeros suppressed; <b>rn</b>, right +justified, leading zeros suppressed; <b>rz</b>, right justified, leading zeros kept. The default <i>format</i> shall be <b>rn</b> +(right justified).</dd> +<dt><b>-p</b></dt> +<dd>Specify that numbering should not be restarted at logical page delimiters.</dd> +<dt><b>-s </b><i>sep</i></dt> +<dd>Specify the characters used in separating the line number and the corresponding text line. The default <i>sep</i> shall be a +<tab>.</dd> +<dt><b>-v </b><i>startnum</i></dt> +<dd>Specify the initial value used to number logical page lines. The default shall be 1.</dd> +<dt><b>-w </b><i>width</i></dt> +<dd>Specify the number of characters to be used for the line number. The default <i>width</i> shall be 6.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_87_05" id="tag_20_87_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of a text file to be line-numbered.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_87_06" id="tag_20_87_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be used if no <i>file</i> operand is specified, and shall be used if the <i>file</i> operand is +<tt>'-'</tt> and the implementation treats the <tt>'-'</tt> as meaning standard input. Otherwise, the standard input shall not be +used. See the INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_87_07" id="tag_20_87_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input file shall be a text file.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_87_08" id="tag_20_87_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>nl</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_COLLATE</i></dt> +<dd><br> +Determine the locale for the behavior of ranges, equivalence classes, and multi-character collating elements within regular +expressions.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files), the behavior of character classes within regular expressions, and +for deciding which characters are in character class <b>graph</b> (for the <b>-b t</b>, <b>-f t</b>, and <b>-h t</b> +options).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd>Determine the location of messages objects and message catalogs.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_87_09" id="tag_20_87_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_87_10" id="tag_20_87_10"></a>STDOUT</h4> +<blockquote> +<p>The standard output shall be a text file in the following format:</p> +<pre> +<tt>"%s%s%s", <</tt><i>line number</i><tt>>, <</tt><i>separator</i><tt>>, <</tt><i>input line</i><tt>> +</tt></pre> +<p class="tent">where <<i>line number</i>> is one of the following numeric formats:</p> +<dl compact> +<dd></dd> +<dt><tt>%6d</tt></dt> +<dd>When the <b>rn</b> format is used (the default; see <b>-n</b>).</dd> +<dt><tt>%06d</tt></dt> +<dd>When the <b>rz</b> format is used.</dd> +<dt><tt>%-6d</tt></dt> +<dd>When the <b>ln</b> format is used.</dd> +<dt><empty></dt> +<dd>When line numbers are suppressed for a portion of the page; the <<i>separator</i>> is also suppressed.</dd> +</dl> +<p class="tent">In the preceding list, the number 6 is the default width; the <b>-w</b> option can change this value.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_87_11" id="tag_20_87_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_87_12" id="tag_20_87_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_87_13" id="tag_20_87_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_87_14" id="tag_20_87_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_87_15" id="tag_20_87_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_87_16" id="tag_20_87_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>In using the <b>-d</b> <i>delim</i> option, care should be taken to escape characters that have special meaning to the command +interpreter.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_87_17" id="tag_20_87_17"></a>EXAMPLES</h4> +<blockquote> +<p>The command:</p> +<pre> +<tt>nl -v 10 -i 10 -d \!+ file1 +</tt></pre> +<p class="tent">numbers <i>file1</i> starting at line number 10 with an increment of 10. The logical page delimiter is +<tt>"!+"</tt>. Note that the <tt>'!'</tt> has to be escaped when using <i>csh</i> as a command interpreter because of its history +substitution syntax. For <i>ksh</i> and <a href="../utilities/sh.html"><i>sh</i></a> the escape is not necessary, but does not do +any harm.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_87_18" id="tag_20_87_18"></a>RATIONALE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_87_19" id="tag_20_87_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_87_20" id="tag_20_87_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/pr.html#"><i>pr</i></a></p> +<p class="tent">XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_87_21" id="tag_20_87_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_87_22" id="tag_20_87_22"></a>Issue 5</h4> +<blockquote> +<p>The option [<b>-f</b> <i>type</i>] is added to the SYNOPSIS. The option descriptions are presented in alphabetic order. The +description of <b>-bt</b> is changed to "Number only non-empty lines".</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_87_23" id="tag_20_87_23"></a>Issue 6</h4> +<blockquote> +<p>The obsolescent behavior allowing the options to be intermingled with the optional <i>file</i> operand is removed.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_87_24" id="tag_20_87_24"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #092 is applied.</p> +<p class="tent">SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_87_25" id="tag_20_87_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/nice.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/nm.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/nm.html b/bdd/nm.html @@ -0,0 +1,363 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>nm</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/nl.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/nohup.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="nm" id="nm"></a> <a name="tag_20_88" id="tag_20_88"></a><!-- nm --> +<h4 class="mansect"><a name="tag_20_88_01" id="tag_20_88_01"></a>NAME</h4> +<blockquote>nm — write the name list of an object file (<b>DEVELOPMENT</b>)</blockquote> +<h4 class="mansect"><a name="tag_20_88_02" id="tag_20_88_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('SD')">SD</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> nm</tt> <b>[</b><tt>-APv</tt><b>] [</b><tt>-g|-u</tt><b>] [</b><tt>-t</tt> <i>format</i><b>]</b> +<i>file</i><tt>... <img src="../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div> +<tt><br> +<br></tt> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> nm</tt> <b>[</b><tt>-APv</tt><b>] [</b><tt>-efox</tt><b>] [</b><tt>-g|-u</tt><b>] [</b><tt>-t</tt> +<i>format</i><b>]</b> <i>file</i><tt>... <img src="../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div> +<tt><br></tt></blockquote> +<h4 class="mansect"><a name="tag_20_88_03" id="tag_20_88_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>nm</i> utility shall display symbolic information appearing in the object file, executable file, or object-file library +named by <i>file</i>. If no symbolic information is available for a valid input file, the <i>nm</i> utility shall report that fact, +but not consider it an error condition.</p> +<p>The default base used when numeric values are written is unspecified. <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> +<img src="../images/opt-start.gif" alt="[Option Start]" border="0"> On XSI-conformant systems, it shall be decimal if the +<b>-P</b> option is not specified. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_88_04" id="tag_20_88_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>nm</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-A</b></dt> +<dd>Write the full pathname or library name of an object on each line.</dd> +<dt><b>-e</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Write only external (global) and static symbol information. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-f</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Produce full output. Write redundant symbols (<b>.text</b>, <b>.data</b>, and <b>.bss</b>), normally suppressed. <img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-g</b></dt> +<dd>Write only external (global) symbol information.</dd> +<dt><b>-o</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Write numeric values in octal (equivalent to <b>-t o</b>). <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><b>-P</b></dt> +<dd>Write information in a portable output format, as specified in the STDOUT section.</dd> +<dt><b>-t </b><i>format</i></dt> +<dd>Write each numeric value in the specified format. The format shall be dependent on the single character used as the +<i>format</i> option-argument: +<dl compact> +<dd></dd> +<dt><tt>d</tt></dt> +<dd>decimal <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" +border="0"> (default if <b>-P</b> is not specified). <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><tt>o</tt></dt> +<dd>octal.</dd> +<dt><tt>x</tt></dt> +<dd>hexadecimal (default if <b>-P</b> is specified).</dd> +</dl> +</dd> +<dt><b>-u</b></dt> +<dd>Write only undefined symbols.</dd> +<dt><b>-v</b></dt> +<dd>Sort output by value instead of by symbol name.</dd> +<dt><b>-x</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Write numeric values in hexadecimal (equivalent to <b>-t x</b>). <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_88_05" id="tag_20_88_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of an object file, executable file, or object-file library.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_88_06" id="tag_20_88_06"></a>STDIN</h4> +<blockquote> +<p>See the INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_88_07" id="tag_20_88_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input file shall be an object file, an object-file library whose format is the same as those produced by the <a href= +"../utilities/ar.html"><i>ar</i></a> utility for link editing, or an executable file. The <i>nm</i> utility may accept additional +implementation-defined object library formats for the input file.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_88_08" id="tag_20_88_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>nm</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_COLLATE</i></dt> +<dd><br> +Determine the locale for character collation information for the symbol-name and symbol-value collation sequences.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_88_09" id="tag_20_88_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_88_10" id="tag_20_88_10"></a>STDOUT</h4> +<blockquote> +<p>If symbolic information is present in the input files, then for each file or for each member of an archive, the <i>nm</i> +utility shall write the following information to standard output. By default, the format is unspecified, but the output shall be +sorted by symbol name according to the collation sequence in the current locale.</p> +<ul> +<li> +<p>Library or object name, if <b>-A</b> is specified</p> +</li> +<li> +<p>Symbol name</p> +</li> +<li> +<p>Symbol type, which shall either be one of the following single characters or an implementation-defined type represented by a +single character:</p> +<dl compact> +<dd></dd> +<dt><tt>A</tt></dt> +<dd>Global absolute symbol.</dd> +<dt><tt>a</tt></dt> +<dd>Local absolute symbol.</dd> +<dt><tt>B</tt></dt> +<dd>Global "bss" (that is, uninitialized data space) symbol.</dd> +<dt><tt>b</tt></dt> +<dd>Local bss symbol.</dd> +<dt><tt>D</tt></dt> +<dd>Global data symbol.</dd> +<dt><tt>d</tt></dt> +<dd>Local data symbol.</dd> +<dt><tt>T</tt></dt> +<dd>Global text symbol.</dd> +<dt><tt>t</tt></dt> +<dd>Local text symbol.</dd> +<dt><tt>U</tt></dt> +<dd>Undefined symbol.</dd> +</dl> +</li> +<li> +<p>Value of the symbol</p> +</li> +<li> +<p>The size associated with the symbol, if applicable</p> +</li> +</ul> +<p>This information may be supplemented by additional information specific to the implementation.</p> +<p>If the <b>-P</b> option is specified, the previous information shall be displayed using the following portable format. The three +versions differ depending on whether <b>-t d</b>, <b>-t o</b>, or <b>-t x</b> was specified, respectively:</p> +<pre> +<tt>"%s%s %s %d %d\n", <</tt><i>library/object name</i><tt>>, <</tt><i>name</i><tt>>, <</tt><i>type</i><tt>>, + <</tt><i>value</i><tt>>, <</tt><i>size</i><tt>> +<br> +"%s%s %s %o %o\n", <</tt><i>library/object name</i><tt>>, <</tt><i>name</i><tt>>, <</tt><i>type</i><tt>>, + <</tt><i>value</i><tt>>, <</tt><i>size</i><tt>> +<br> +"%s%s %s %x %x\n", <</tt><i>library/object name</i><tt>>, <</tt><i>name</i><tt>>, <</tt><i>type</i><tt>>, + <</tt><i>value</i><tt>>, <</tt><i>size</i><tt>> +</tt></pre> +where <<i>library/object name</i>> shall be formatted as follows: +<ul> +<li> +<p>If <b>-A</b> is not specified, <<i>library/object name</i>> shall be an empty string.</p> +</li> +<li> +<p>If <b>-A</b> is specified and the corresponding <i>file</i> operand does not name a library:</p> +<pre> +<tt>"%s: ", <</tt><i>file</i><tt>> +</tt></pre></li> +<li> +<p>If <b>-A</b> is specified and the corresponding <i>file</i> operand names a library. In this case, +<<i>object file</i>> shall name the object file in the library containing the symbol being described:</p> +<pre> +<tt>"%s[%s]: ", <</tt><i>file</i><tt>>, <</tt><i>object file</i><tt>> +</tt></pre></li> +</ul> +<p>If <b>-A</b> is not specified, then if more than one <i>file</i> operand is specified or if only one <i>file</i> operand is +specified and it names a library, <i>nm</i> shall write a line identifying the object containing the following symbols before the +lines containing those symbols, in the form:</p> +<ul> +<li> +<p>If the corresponding <i>file</i> operand does not name a library:</p> +<pre> +<tt>"%s:\n", <</tt><i>file</i><tt>> +</tt></pre></li> +<li> +<p>If the corresponding <i>file</i> operand names a library; in this case, <<i>object file</i>> shall be the name of the +file in the library containing the following symbols:</p> +<pre> +<tt>"%s[%s]:\n", <</tt><i>file</i><tt>>, <</tt><i>object file</i><tt>> +</tt></pre></li> +</ul> +<p>If <b>-P</b> is specified, but <b>-t</b> is not, the format shall be as if <b>-t x</b> had been specified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_88_11" id="tag_20_88_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_88_12" id="tag_20_88_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_88_13" id="tag_20_88_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_88_14" id="tag_20_88_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_88_15" id="tag_20_88_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_88_16" id="tag_20_88_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Mechanisms for dynamic linking make this utility less meaningful when applied to an executable file because a dynamically linked +executable may omit numerous library routines that would be found in a statically linked executable.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_88_17" id="tag_20_88_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_88_18" id="tag_20_88_18"></a>RATIONALE</h4> +<blockquote> +<p>Historical implementations of <i>nm</i> have used different bases for numeric output and supplied different default types of +symbols that were reported. The <b>-t</b> <i>format</i> option, similar to that used in <a href= +"../utilities/od.html"><i>od</i></a> and <a href="../utilities/strings.html"><i>strings</i></a>, can be used to specify the numeric +base; <b>-g</b> and <b>-u</b> can be used to restrict the amount of output or the types of symbols included in the output.</p> +<p>The compromise of using <b>-t</b> <i>format</i> <i>versus</i> using <b>-d</b>, <b>-o</b>, and other similar options was +necessary because of differences in the meaning of <b>-o</b> between implementations. The <b>-o</b> option from BSD has been +provided here as <b>-A</b> to avoid confusion with the <b>-o</b> from System V (which has been provided here as <b>-t</b> and as +<b>-o</b> on XSI-conformant systems).</p> +<p>The option list was significantly reduced from that provided by historical implementations.</p> +<p>The <i>nm</i> description is a subset of both the System V and BSD <i>nm</i> utilities with no specified default output.</p> +<p>It was recognized that mechanisms for dynamic linking make this utility less meaningful when applied to an executable file +(because a dynamically linked executable file may omit numerous library routines that would be found in a statically linked +executable file), but the value of <i>nm</i> during software development was judged to outweigh other limitations.</p> +<p>The default output format of <i>nm</i> is not specified because of differences in historical implementations. The <b>-P</b> +option was added to allow some type of portable output format. After a comparison of the different formats used in SunOS, BSD, +SVR3, and SVR4, it was decided to create one that did not match the current format of any of these four systems. The format devised +is easy to parse by humans, easy to parse in shell scripts, and does not need to vary depending on locale (because no English +descriptions are included). All of the systems currently have the information available to use this format.</p> +<p>The format given in <i>nm</i> STDOUT uses <space> characters between the fields, which may be any number of <blank> +characters required to align the columns. The single-character types were selected to match historical practice, and the +requirement that implementation additions also be single characters made parsing the information easier for shell scripts.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_88_19" id="tag_20_88_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_88_20" id="tag_20_88_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/ar.html#"><i>ar</i></a> , <a href="../utilities/c17.html#"><i>c17</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_88_21" id="tag_20_88_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_88_22" id="tag_20_88_22"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as supported when both the User Portability Utilities option and the Software Development Utilities +option are supported.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_88_23" id="tag_20_88_23"></a>Issue 7</h4> +<blockquote> +<p>The <i>nm</i> utility is removed from the User Portability Utilities option. User Portability Utilities is now an option for +interactive utilities.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0125 [263] and XCU/TC1-2008/0126 [263] are applied.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0148 [744] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_88_24" id="tag_20_88_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to report an error if a utility is directed to display a +pathname that contains any bytes that have the encoded value of a <newline> character when <newline> is a terminator or +separator in the output format being used.</p> +<p>Austin Group Defect 1062 is applied, inserting an empty line between the two SYNOPSIS forms.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/nl.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/nohup.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/nohup.html b/bdd/nohup.html @@ -0,0 +1,248 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>nohup</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/nm.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/od.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="nohup" id="nohup"></a> <a name="tag_20_89" id="tag_20_89"></a><!-- nohup --> +<h4 class="mansect"><a name="tag_20_89_01" id="tag_20_89_01"></a>NAME</h4> +<blockquote>nohup — invoke a utility immune to hangups</blockquote> +<h4 class="mansect"><a name="tag_20_89_02" id="tag_20_89_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>nohup</tt> <i>utility</i> <b>[</b><i>argument</i><tt>...</tt><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_89_03" id="tag_20_89_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>nohup</i> utility shall invoke the utility named by the <i>utility</i> operand with arguments supplied as the +<i>argument</i> operands. At the time the named <i>utility</i> is invoked, the SIGHUP signal shall be set to be ignored.</p> +<p>If standard input is associated with a terminal, the <i>nohup</i> utility may redirect standard input from an unspecified +file.</p> +<p>If the standard output is a terminal, all output written by the named <i>utility</i> to its standard output shall be appended to +the end of the file <b>nohup.out</b> in the current directory. If <b>nohup.out</b> cannot be created or opened for appending, the +output shall be appended to the end of the file <b>nohup.out</b> in the directory specified by the <i>HOME</i> environment +variable. If neither file can be created or opened for appending, <i>utility</i> shall not be invoked. If a file is created, the +file's permission bits shall be set to S_IRUSR | S_IWUSR.</p> +<p>If standard error is a terminal and standard output is open but is not a terminal, all output written by the named utility to +its standard error shall be redirected to the same open file description as the standard output. If standard error is a terminal +and standard output either is a terminal or is closed, the same output shall instead be appended to the end of the <b>nohup.out</b> +file as described above.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_89_04" id="tag_20_89_04"></a>OPTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_89_05" id="tag_20_89_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>utility</i></dt> +<dd>The name of a utility that is to be invoked. If the <i>utility</i> operand names any of the special built-in utilities in +<a href="../utilities/V3_chap02.html#tag_19_15"><i>2.15 Special Built-In Utilities</i></a> , the results are undefined.</dd> +<dt><i>argument</i></dt> +<dd>Any string to be supplied as an argument when invoking the utility named by the <i>utility</i> operand.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_89_06" id="tag_20_89_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_89_07" id="tag_20_89_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_89_08" id="tag_20_89_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>nohup</i>:</p> +<dl compact> +<dd></dd> +<dt><i>HOME</i></dt> +<dd>Determine the pathname of the user's home directory: if the output file <b>nohup.out</b> cannot be created in the current +directory, the <i>nohup</i> utility shall use the directory named by <i>HOME</i> to create the file.</dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>PATH</i></dt> +<dd>Determine the search path that is used to locate the utility to be invoked. See XBD <a href= +"../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> .</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_89_09" id="tag_20_89_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>The <i>nohup</i> utility shall take the standard action for all signals except that SIGHUP shall be ignored.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_89_10" id="tag_20_89_10"></a>STDOUT</h4> +<blockquote> +<p>If the standard output is not a terminal, the standard output of <i>nohup</i> shall be the standard output generated by the +execution of the <i>utility</i> specified by the operands. Otherwise, nothing shall be written to the standard output.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_89_11" id="tag_20_89_11"></a>STDERR</h4> +<blockquote> +<p>If the standard output is a terminal, a message shall be written to the standard error, indicating the name of the file to which +the output is being appended. The name of the file shall be either <b>nohup.out</b> or <b>$HOME/nohup.out</b>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_89_12" id="tag_20_89_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>Output written by the named utility is appended to the file <b>nohup.out</b> (or <b>$HOME/nohup.out</b>), if the conditions hold +as described in the DESCRIPTION.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_89_13" id="tag_20_89_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_89_14" id="tag_20_89_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt>126</dt> +<dd>The utility specified by <i>utility</i> was found but could not be invoked.</dd> +<dt>127</dt> +<dd>An error occurred in the <i>nohup</i> utility or the utility specified by <i>utility</i> could not be found.</dd> +</dl> +<p>Otherwise, the exit status of <i>nohup</i> shall be that of the utility specified by the <i>utility</i> operand.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_89_15" id="tag_20_89_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_89_16" id="tag_20_89_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The <a href="../utilities/command.html"><i>command</i></a>, <a href="../utilities/env.html"><i>env</i></a>, <a href= +"../utilities/nice.html"><i>nice</i></a>, <i>nohup</i>, <a href="../utilities/time.html"><i>time</i></a>, <a href= +"../utilities/timeout.html"><i>timeout</i></a>, and <a href="../utilities/xargs.html"><i>xargs</i></a> utilities have been +specified to use exit code 127 if a utility to be invoked cannot be found, so that applications can distinguish "failure to find a +utility" from "invoked utility exited with an error indication". However, the <a href= +"../utilities/command.html"><i>command</i></a> and <i>nohup</i> utilities also use exit code 127 when an error occurs in those +utilities, which means exit code 127 is not universally a "not found" indicator. The value 127 was chosen because it is not +commonly used for other meanings; most utilities use small values for "normal error conditions" and the values above 128 can be +confused with termination due to receipt of a signal. The value 126 was chosen in a similar manner to indicate that the utility +could be found, but not invoked. Some scripts produce meaningful error messages differentiating the 126 and 127 cases. The +distinction between exit codes 126 and 127 is based on KornShell practice that uses 127 when all attempts to <i>exec</i> the +utility fail with [ENOENT], and uses 126 when any attempt to <i>exec</i> the utility fails for any other reason.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_89_17" id="tag_20_89_17"></a>EXAMPLES</h4> +<blockquote> +<p>It is frequently desirable to apply <i>nohup</i> to pipelines or lists of commands. This can be done by placing pipelines and +command lists in a single file; this file can then be invoked as a utility, and the <i>nohup</i> applies to everything in the +file.</p> +<p>Alternatively, the following command can be used to apply <i>nohup</i> to a complex command:</p> +<pre> +<tt>nohup sh -c -- '</tt><i>complex-command-line</i><tt>' </dev/null +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_89_18" id="tag_20_89_18"></a>RATIONALE</h4> +<blockquote> +<p>The 4.3 BSD version ignores SIGTERM and SIGHUP, and if <b>./nohup.out</b> cannot be used, it fails instead of trying to use +<b>$HOME/nohup.out</b>.</p> +<p>The <i>csh</i> utility has a built-in version of <i>nohup</i> that acts differently from the <i>nohup</i> defined in this volume +of POSIX.1-2024.</p> +<p>The term <i>utility</i> is used, rather than <i>command</i>, to highlight the fact that shell compound commands, pipelines, +special built-ins, and so on, cannot be used directly. However, <i>utility</i> includes user application programs and shell +scripts, not just the standard utilities.</p> +<p>Historical versions of the <i>nohup</i> utility use default file creation semantics. Some more recent versions use the +permissions specified here as an added security precaution.</p> +<p>Some historical implementations ignore SIGQUIT in addition to SIGHUP; others ignore SIGTERM. An early proposal allowed, but did +not require, SIGQUIT to be ignored. Several reviewers objected that <i>nohup</i> should only modify the handling of SIGHUP as +required by this volume of POSIX.1-2024.</p> +<p>Historical versions of <i>nohup</i> did not affect standard input, but that causes problems in the common scenario where the +user logs into a system, types the command:</p> +<pre> +<tt>nohup make & +</tt></pre> +<p>at the prompt, and then logs out. If standard input is not affected by <i>nohup</i>, the login session may not terminate for +quite some time, since standard input remains open until <a href="../utilities/make.html"><i>make</i></a> exits. To avoid this +problem, POSIX.1-2024 allows implementations to redirect standard input if it is a terminal. Since the behavior is +implementation-defined, portable applications that may run into the problem should redirect standard input themselves. For example, +instead of:</p> +<pre> +<tt>nohup make & +</tt></pre> +<p>an application can invoke:</p> +<pre> +<tt>nohup make </dev/null & +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_89_19" id="tag_20_89_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_89_20" id="tag_20_89_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19"><i>2. Shell Command Language</i></a> , <a href= +"../utilities/sh.html#"><i>sh</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a></p> +<p>XSH <a href="../functions/signal.html#"><i>signal</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_89_21" id="tag_20_89_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_89_22" id="tag_20_89_22"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretations 1003.1-2001 #104, #105, and #106 are applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_89_23" id="tag_20_89_23"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1530 is applied, changing "<tt>sh -c</tt>" to "<tt>sh -c --</tt>".</p> +<p>Austin Group Defect 1586 is applied, adding the <a href="../utilities/timeout.html"><i>timeout</i></a> utility.</p> +<p>Austin Group Defect 1594 is applied, changing the APPLICATION USAGE section.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/nm.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/od.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/od.html b/bdd/od.html @@ -0,0 +1,760 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>od</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/nohup.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/paste.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="od" id="od"></a> <a name="tag_20_90" id="tag_20_90"></a><!-- od --> +<h4 class="mansect"><a name="tag_20_90_01" id="tag_20_90_01"></a>NAME</h4> +<blockquote>od — dump files in various formats</blockquote> +<h4 class="mansect"><a name="tag_20_90_02" id="tag_20_90_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>od</tt> <b>[</b><tt>-v</tt><b>] [</b><tt>-A</tt> <i>address_base</i><b>] [</b><tt>-j</tt> <i>skip</i><b>] [</b><tt>-N</tt> +<i>count</i><b>] [</b><tt>-t</tt> <i>type_string</i><b>]</b><tt>...<br> + </tt> <b>[</b><i>file</i><tt>...</tt><b>]</b> <tt><br> +<br></tt></code></p> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> od</tt> <b>[</b><tt>-bcdosx</tt><b>] [</b><i>file</i><b>] +[[</b><tt>+</tt><b>]</b><i>offset</i><b>[</b><tt>.</tt><b>][</b><tt>b</tt><b>]]</b> <tt><img src="../images/opt-end.gif" alt= +"[Option End]" border="0"></tt></code></div> +<tt><br></tt></blockquote> +<h4 class="mansect"><a name="tag_20_90_03" id="tag_20_90_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>od</i> utility shall write the contents of its input files to standard output in a user-specified format.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_90_04" id="tag_20_90_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>od</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> , except that the order of presentation of the <b>-t</b> options <sup>[<a href= +"javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> and the +<b>-bcdosx</b> options <img src="../images/opt-end.gif" alt="[Option End]" border="0"> is significant.</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-A </b><i>address_base</i></dt> +<dd><br> +Specify the input offset base. See the EXTENDED DESCRIPTION section. The application shall ensure that the <i>address_base</i> +option-argument is a character. The characters <tt>'d'</tt>, <tt>'o'</tt>, and <tt>'x'</tt> specify that the offset base shall be +written in decimal, octal, or hexadecimal, respectively. The character <tt>'n'</tt> specifies that the offset shall not be +written.</dd> +<dt><b>-b</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Interpret bytes in octal. This shall be equivalent to <b>-t o1</b>. <img src="../images/opt-end.gif" alt="[Option End]" +border="0"></dd> +<dt><b>-c</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Interpret bytes as characters specified by the current setting of the <i>LC_CTYPE</i> category. Certain non-graphic characters +appear as C escapes: <tt>"NUL=\0"</tt>, <tt>"BS=\b"</tt>, <tt>"FF=\f"</tt>, <tt>"NL=\n"</tt>, <tt>"CR=\r"</tt>, <tt>"HT=\t"</tt>; +others appear as 3-digit octal numbers. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-d</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Interpret <i>word</i>s (two-byte units) in unsigned decimal. This shall be equivalent to <b>-t u2</b>. <img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-j </b><i>skip</i></dt> +<dd>Jump over <i>skip</i> bytes from the beginning of the input. The <i>od</i> utility shall read or seek past the first +<i>skip</i> bytes in the concatenated input files. If the combined input is not at least <i>skip</i> bytes long, the <i>od</i> +utility shall write a diagnostic message to standard error and exit with a non-zero exit status. +<p>By default, the <i>skip</i> option-argument shall be interpreted as a decimal number. With a leading 0x or 0X, the offset shall +be interpreted as a hexadecimal number; otherwise, with a leading <tt>'0'</tt>, the offset shall be interpreted as an octal number. +Appending the character <tt>'b'</tt>, <tt>'k'</tt>, or <tt>'m'</tt> to offset shall cause it to be interpreted as a multiple of +512, 1024, or 1048576 bytes, respectively. If the <i>skip</i> number is hexadecimal, any appended <tt>'b'</tt> shall be considered +to be the final hexadecimal digit.</p> +</dd> +<dt><b>-N </b><i>count</i></dt> +<dd>Format no more than <i>count</i> bytes of input. By default, <i>count</i> shall be interpreted as a decimal number. With a +leading 0x or 0X, <i>count</i> shall be interpreted as a hexadecimal number; otherwise, with a leading <tt>'0'</tt>, it shall be +interpreted as an octal number. If <i>count</i> bytes of input (after successfully skipping, if <b>-j</b> <i>skip</i> is specified) +are not available, it shall not be considered an error; the <i>od</i> utility shall format the input that is available.</dd> +<dt><b>-o</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Interpret <i>word</i>s (two-byte units) in octal. This shall be equivalent to <b>-t o2</b>. <img src="../images/opt-end.gif" +alt="[Option End]" border="0"></dd> +<dt><b>-s</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Interpret <i>word</i>s (two-byte units) in signed decimal. This shall be equivalent to <b>-t d2</b>. <img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-t </b><i>type_string</i></dt> +<dd><br> +Specify one or more output types. See the EXTENDED DESCRIPTION section. The application shall ensure that the <i>type_string</i> +option-argument is a string specifying the types to be used when writing the input data. The string shall consist of the type +specification characters <tt>a</tt>, <tt>c</tt>, <tt>d</tt>, <tt>f</tt>, <tt>o</tt>, <tt>u</tt>, and <tt>x</tt>, specifying named +character, character, signed decimal, floating point, octal, unsigned decimal, and hexadecimal, respectively. The type +specification characters <tt>d</tt>, <tt>f</tt>, <tt>o</tt>, <tt>u</tt>, and <tt>x</tt> can be followed by an optional unsigned +decimal integer that specifies the number of bytes to be transformed by each instance of the output type. The type specification +character <tt>f</tt> can be followed by an optional <tt>F</tt>, <tt>D</tt>, or <tt>L</tt> indicating that the conversion should be +applied to an item of type <b>float</b>, <b>double</b>, or <b>long double</b>, respectively. The type specification characters +<tt>d</tt>, <tt>o</tt>, <tt>u</tt>, and <tt>x</tt> can be followed by an optional <tt>C</tt>, <tt>S</tt>, <tt>I</tt>, or <tt>L</tt> +indicating that the conversion should be applied to an item of type <b>char</b>, <b>short</b>, <b>int</b>, or <b>long</b>, +respectively. Multiple types can be concatenated within the same <i>type_string</i> and multiple <b>-t</b> options can be +specified. Output lines shall be written for each type specified in the order in which the type specification characters are +specified.</dd> +<dt><b>-v</b></dt> +<dd>Write all input data. Without the <b>-v</b> option, any number of groups of output lines, which would be identical to the +immediately preceding group of output lines (except for the byte offsets), shall be replaced with a line containing only an +<asterisk> (<tt>'*'</tt>).</dd> +<dt><b>-x</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Interpret <i>word</i>s (two-byte units) in hexadecimal. This shall be equivalent to <b>-t x2</b>. <img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></dd> +</dl> +<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Multiple types can be specified by using multiple <b>-bcdostx</b> options. Output lines are written for each type specified in the +order in which the types are specified. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_90_05" id="tag_20_90_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of a file to be read. If no <i>file</i> operands are specified, the standard input shall be used. +<p>If there are no more than two operands, none of the <b>-A</b>, <b>-j</b>, <b>-N</b>, <b>-t</b>, or <b>-v</b> options is +specified, and either of the following is true: the first character of the last operand is a <plus-sign> (<tt>'+'</tt>), or +there are two operands and the first character of the last operand is numeric; <sup>[<a href= +"javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> the last +operand shall be interpreted as an offset operand on XSI-conformant systems. <img src="../images/opt-end.gif" alt="[Option End]" +border="0"> Under these conditions, the results are unspecified on systems that are not XSI-conformant systems.</p> +</dd> +<dt><b>[+]</b><i>offset</i><b>[.][b]</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +The <i>offset</i> operand specifies the offset in the file where dumping is to commence. This operand is normally interpreted as +octal bytes. If <tt>'.'</tt> is appended, the offset shall be interpreted in decimal. If <tt>'b'</tt> is appended, the offset shall +be interpreted in units of 512 bytes. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_90_06" id="tag_20_90_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be used if no <i>file</i> operands are specified, and shall be used if a <i>file</i> operand is +<tt>'-'</tt> and the implementation treats the <tt>'-'</tt> as meaning standard input. Otherwise, the standard input shall not be +used. See the INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_90_07" id="tag_20_90_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files can be any file type.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_90_08" id="tag_20_90_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>od</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>LC_NUMERIC</i></dt> +<dd><br> +Determine the locale for selecting the radix character used when writing floating-point formatted output.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_90_09" id="tag_20_90_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_90_10" id="tag_20_90_10"></a>STDOUT</h4> +<blockquote> +<p>See the EXTENDED DESCRIPTION section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_90_11" id="tag_20_90_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_90_12" id="tag_20_90_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_90_13" id="tag_20_90_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>The <i>od</i> utility shall copy sequentially each input file to standard output, transforming the input data according to the +output types specified by the <b>-t</b> option <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src= +"../images/opt-start.gif" alt="[Option Start]" border="0"> or the <b>-bcdosx</b> options. <img src="../images/opt-end.gif" +alt="[Option End]" border="0"> If no output type is specified, the default output shall be as if <b>-t oS</b> had been +specified.</p> +<p>The number of bytes transformed by the output type specifier <tt>c</tt> may be variable depending on the <i>LC_CTYPE</i> +category.</p> +<p>The default number of bytes transformed by output type specifiers <tt>d</tt>, <tt>f</tt>, <tt>o</tt>, <tt>u</tt>, and <tt>x</tt> +corresponds to the various C-language types as follows. If the <a href="../utilities/c17.html"><i>c17</i></a> compiler is present +on the system, these specifiers shall correspond to the sizes used by default in that compiler. Otherwise, these sizes may vary +among systems that conform to POSIX.1-2024.</p> +<ul> +<li> +<p>For the type specifier characters <tt>d</tt>, <tt>o</tt>, <tt>u</tt>, and <tt>x</tt>, the default number of bytes shall +correspond to the size of the underlying implementation's basic integer type. For these specifier characters, the implementation +shall support values of the optional number of bytes to be converted corresponding to the number of bytes in the C-language types +<b>char</b>, <b>short</b>, <b>int</b>, and <b>long</b>. These numbers can also be specified by an application as the characters +<tt>'C'</tt>, <tt>'S'</tt>, <tt>'I'</tt>, and <tt>'L'</tt>, respectively. The implementation shall also support the values 1, 2, 4, +and 8, even if it provides no C-Language types of those sizes. The implementation shall support the decimal value corresponding to +the C-language type <b>long long</b>. The byte order used when interpreting numeric values is implementation-defined, but shall +correspond to the order in which a constant of the corresponding type is stored in memory on the system.</p> +</li> +<li> +<p>For the type specifier character <tt>f</tt>, the default number of bytes shall correspond to the number of bytes in the +underlying implementation's basic double precision floating-point data type. The implementation shall support values of the +optional number of bytes to be converted corresponding to the number of bytes in the C-language types <b>float,</b> <b>double</b>, +and <b>long double</b>. These numbers can also be specified by an application as the characters <tt>'F'</tt>, <tt>'D'</tt>, and +<tt>'L'</tt>, respectively.</p> +</li> +</ul> +<p>The type specifier character <tt>a</tt> specifies that bytes shall be interpreted as named characters from the International +Reference Version (IRV) of the ISO/IEC 646:1991 standard. Only the least significant seven bits of each byte shall be used for +this type specification. Bytes with the values listed in the following table shall be written using the corresponding names for +those characters.<br></p> +<p class="caption">Table: Named Characters in <i>od</i></p> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Value</b></p> +</th> +<th align="center"> +<p class="tent"><b>Name</b></p> +</th> +<th align="center"> +<p class="tent"><b>Value</b></p> +</th> +<th align="center"> +<p class="tent"><b>Name</b></p> +</th> +<th align="center"> +<p class="tent"><b>Value</b></p> +</th> +<th align="center"> +<p class="tent"><b>Name</b></p> +</th> +<th align="center"> +<p class="tent"><b>Value</b></p> +</th> +<th align="center"> +<p class="tent"><b>Name</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">\000</p> +</td> +<td align="left"> +<p class="tent"><b>nul</b></p> +</td> +<td align="left"> +<p class="tent">\001</p> +</td> +<td align="left"> +<p class="tent"><b>soh</b></p> +</td> +<td align="left"> +<p class="tent">\002</p> +</td> +<td align="left"> +<p class="tent"><b>stx</b></p> +</td> +<td align="left"> +<p class="tent">\003</p> +</td> +<td align="left"> +<p class="tent"><b>etx</b></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">\004</p> +</td> +<td align="left"> +<p class="tent"><b>eot</b></p> +</td> +<td align="left"> +<p class="tent">\005</p> +</td> +<td align="left"> +<p class="tent"><b>enq</b></p> +</td> +<td align="left"> +<p class="tent">\006</p> +</td> +<td align="left"> +<p class="tent"><b>ack</b></p> +</td> +<td align="left"> +<p class="tent">\007</p> +</td> +<td align="left"> +<p class="tent"><b>bel</b></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">\010</p> +</td> +<td align="left"> +<p class="tent"><b>bs</b></p> +</td> +<td align="left"> +<p class="tent">\011</p> +</td> +<td align="left"> +<p class="tent"><b>ht</b></p> +</td> +<td align="left"> +<p class="tent">\012</p> +</td> +<td align="left"> +<p class="tent"><b>lf or nl<sup><small>*</small></sup></b></p> +</td> +<td align="left"> +<p class="tent">\013</p> +</td> +<td align="left"> +<p class="tent"><b>vt</b></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">\014</p> +</td> +<td align="left"> +<p class="tent"><b>ff</b></p> +</td> +<td align="left"> +<p class="tent">\015</p> +</td> +<td align="left"> +<p class="tent"><b>cr</b></p> +</td> +<td align="left"> +<p class="tent">\016</p> +</td> +<td align="left"> +<p class="tent"><b>so</b></p> +</td> +<td align="left"> +<p class="tent">\017</p> +</td> +<td align="left"> +<p class="tent"><b>si</b></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">\020</p> +</td> +<td align="left"> +<p class="tent"><b>dle</b></p> +</td> +<td align="left"> +<p class="tent">\021</p> +</td> +<td align="left"> +<p class="tent"><b>dc1</b></p> +</td> +<td align="left"> +<p class="tent">\022</p> +</td> +<td align="left"> +<p class="tent"><b>dc2</b></p> +</td> +<td align="left"> +<p class="tent">\023</p> +</td> +<td align="left"> +<p class="tent"><b>dc3</b></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">\024</p> +</td> +<td align="left"> +<p class="tent"><b>dc4</b></p> +</td> +<td align="left"> +<p class="tent">\025</p> +</td> +<td align="left"> +<p class="tent"><b>nak</b></p> +</td> +<td align="left"> +<p class="tent">\026</p> +</td> +<td align="left"> +<p class="tent"><b>syn</b></p> +</td> +<td align="left"> +<p class="tent">\027</p> +</td> +<td align="left"> +<p class="tent"><b>etb</b></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">\030</p> +</td> +<td align="left"> +<p class="tent"><b>can</b></p> +</td> +<td align="left"> +<p class="tent">\031</p> +</td> +<td align="left"> +<p class="tent"><b>em</b></p> +</td> +<td align="left"> +<p class="tent">\032</p> +</td> +<td align="left"> +<p class="tent"><b>sub</b></p> +</td> +<td align="left"> +<p class="tent">\033</p> +</td> +<td align="left"> +<p class="tent"><b>esc</b></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">\034</p> +</td> +<td align="left"> +<p class="tent"><b>fs</b></p> +</td> +<td align="left"> +<p class="tent">\035</p> +</td> +<td align="left"> +<p class="tent"><b>gs</b></p> +</td> +<td align="left"> +<p class="tent">\036</p> +</td> +<td align="left"> +<p class="tent"><b>rs</b></p> +</td> +<td align="left"> +<p class="tent">\037</p> +</td> +<td align="left"> +<p class="tent"><b>us</b></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">\040</p> +</td> +<td align="left"> +<p class="tent"><b>sp</b></p> +</td> +<td align="left"> +<p class="tent">\177</p> +</td> +<td align="left"> +<p class="tent"><b>del</b></p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent"><b> </b></p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent"><b> </b></p> +</td> +</tr> +</table> +</center> +<basefont size="2"> +<dl> +<dt><b>Note:</b></dt> +<dd>The <tt>"\012"</tt> value may be written either as <b>lf</b> or <b>nl</b>.</dd> +</dl> +<basefont size="3"> +<p class="tent">The type specifier character <tt>c</tt> specifies that bytes shall be interpreted as characters specified by the +current setting of the <i>LC_CTYPE</i> locale category. Characters listed in the table in XBD <a href= +"../basedefs/V1_chap05.html#tag_05"><i>5. File Format Notation</i></a> (<tt>'\\'</tt>, <tt>'\a'</tt>, <tt>'\b'</tt>, <tt>'\f'</tt>, +<tt>'\n'</tt>, <tt>'\r'</tt>, <tt>'\t'</tt>, <tt>'\v'</tt>) shall be written as the corresponding escape sequences, except that +<backslash> shall be written as a single <backslash> and a NUL shall be written as <tt>'\0'</tt>. Other non-printable +characters shall be written as one three-digit octal number for each byte in the character. Printable multi-byte characters shall +be written in the area corresponding to the first byte of the character; the two-character sequence <tt>"**"</tt> shall be written +in the area corresponding to each remaining byte in the character, as an indication that the character is continued. When either +the <b>-j</b> <i>skip</i> or <b>-N</b> <i>count</i> option is specified along with the <tt>c</tt> type specifier, and this results +in an attempt to start or finish in the middle of a multi-byte character, the result is implementation-defined.</p> +<p class="tent">The input data shall be manipulated in blocks, where a block is defined as a multiple of the least common multiple +of the number of bytes transformed by the specified output types. If the least common multiple is greater than 16, the results are +unspecified. Each input block shall be written as transformed by each output type, one per written line, in the order that the +output types were specified. If the input block size is larger than the number of bytes transformed by the output type, the output +type shall sequentially transform the parts of the input block, and the output from each of the transformations shall be separated +by one or more <blank> characters.</p> +<p class="tent">If, as a result of the specification of the <b>-N</b> option or end-of-file being reached on the last input file, +input data only partially satisfies an output type, the input shall be extended sufficiently with null bytes to write the last byte +of the input.</p> +<p class="tent">Unless <b>-A n</b> is specified, the first output line produced for each input block shall be preceded by the +input offset, cumulative across input files, of the next byte to be written. The format of the input offset is unspecified; +however, it shall not contain any <blank> characters, shall start at the first character of the output line, and shall be +followed by one or more <blank> characters. In addition, the offset of the byte following the last byte written shall be +written after all the input data has been processed, but shall not be followed by any <blank> characters. If <b>-A n</b> +is specified, it is unspecified whether the line that would contain this final offset is written as an empty line or is not +written.</p> +<p class="tent">If no <b>-A</b> option is specified, the input offset base is unspecified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_90_14" id="tag_20_90_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>All input files were processed successfully.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_90_15" id="tag_20_90_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_90_16" id="tag_20_90_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>XSI-conformant applications are warned not to use filenames starting with <tt>'+'</tt> or a first operand starting with a +numeric character so that the old functionality can be maintained by implementations, unless they specify one of the <b>-A</b>, +<b>-j</b>, or <b>-N</b> options. To guarantee that one of these filenames is always interpreted as a filename, an application could +always specify the address base format with the <b>-A</b> option.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_90_17" id="tag_20_90_17"></a>EXAMPLES</h4> +<blockquote> +<p>If a file containing 128 bytes with decimal values zero to 127, in increasing order, is supplied as standard input to the +command:</p> +<pre> +<tt>od -A d -t a +</tt></pre> +<p class="tent">on an implementation using an input block size of 16 bytes, the standard output, independent of the current locale +setting, would be similar to:</p> +<pre> +<tt>0000000 nul soh stx etx eot enq ack bel bs ht nl vt ff cr so si +0000016 dle dc1 dc2 dc3 dc4 nak syn etb can em sub esc fs gs rs us +0000032 sp ! " # $ % & ' ( ) * + , - . / +0000048 0 1 2 3 4 5 6 7 8 9 : ; < = > ? +0000064 @ A B C D E F G H I J K L M N O +0000080 P Q R S T U V W X Y Z [ \ ] ^ _ +0000096 ` a b c d e f g h i j k l m n o +0000112 p q r s t u v w x y z { | } ~ del +0000128 +</tt></pre> +<p class="tent">Note that this volume of POSIX.1-2024 allows <b>nl</b> or <b>lf</b> to be used as the name for the +ISO/IEC 646:1991 standard IRV character with decimal value 10. The IRV names this character <b>lf</b> (line feed), but +traditional implementations have referred to this character as newline (<b>nl</b>) and the POSIX locale character set symbolic name +for the corresponding character is a <newline>.</p> +<p class="tent">The command:</p> +<pre> +<tt>od -A o -t o2x2x -N 18 +</tt></pre> +<p class="tent">on a system with 32-bit words and an implementation using an input block size of 16 bytes could write 18 bytes in +approximately the following format:</p> +<pre> +<tt>0000000 032056 031440 041123 042040 052516 044530 020043 031464 + 342e 3320 4253 4420 554e 4958 2023 3334 + 342e3320 42534420 554e4958 20233334 +0000020 032472 + 353a + 353a0000 +0000022 +</tt></pre> +<p class="tent">The command:</p> +<pre> +<tt>od -A d -t f -t o4 -t x4 -N 24 -j 0x15 +</tt></pre> +<p class="tent">on a system with 64-bit doubles (for example, IEEE Std 754-1985 double precision floating-point format) +would skip 21 bytes of input data and then write 24 bytes in approximately the following format:</p> +<pre> +<tt>0000000 1.00000000000000e+00 1.57350000000000e+01 + 07774000000 00000000000 10013674121 35341217270 + 3ff00000 00000000 402f3851 eb851eb8 +0000016 1.40668230000000e+02 + 10030312542 04370303230 + 40619562 23e18698 +0000024 +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_90_18" id="tag_20_90_18"></a>RATIONALE</h4> +<blockquote> +<p>The <i>od</i> utility went through several names in early proposals, including <i>hd</i>, <i>xd</i>, and most recently +<i>hexdump</i>. There were several objections to all of these based on the following reasons:</p> +<ul> +<li class="tent">The <i>hd</i> and <i>xd</i> names conflicted with historical utilities that behaved differently.</li> +<li class="tent">The <i>hexdump</i> description was much more complex than needed for a simple dump utility.</li> +<li class="tent">The <i>od</i> utility has been available on all historical implementations and there was no need to create a new +name for a utility so similar to the historical <i>od</i> utility.</li> +</ul> +<p class="tent">The original reasons for not standardizing historical <i>od</i> were also fairly widespread. Those reasons are +given below along with rationale explaining why the standard developers believe that this version does not suffer from the +indicated problem:</p> +<ul> +<li class="tent">The BSD and System V versions of <i>od</i> have diverged, and the intersection of features provided by both does +not meet the needs of the user community. In fact, the System V version only provides a mechanism for dumping octal bytes and +<b>short</b>s, signed and unsigned decimal <b>short</b>s, hexadecimal <b>short</b>s, and ASCII characters. BSD added the ability to +dump <b>float</b>s, <b>double</b>s, named ASCII characters, and octal, signed decimal, unsigned decimal, and hexadecimal +<b>long</b>s. The version presented here provides more normalized forms for dumping bytes, <b>short</b>s, <b>int</b>s, and +<b>long</b>s in octal, signed decimal, unsigned decimal, and hexadecimal; <b>float</b>, <b>double</b>, and <b>long double</b>; and +named ASCII as well as current locale characters.</li> +<li class="tent">It would not be possible to come up with a compatible superset of the BSD and System V flags that met the +requirements of the standard developers. The historical default <i>od</i> output is the specified default output of this utility. +None of the option letters chosen for this version of <i>od</i> conflict with any of the options to historical versions of +<i>od</i>.</li> +<li class="tent">On systems with different sizes for <b>short</b>, <b>int</b>, and <b>long</b>, there was no way to ask for dumps +of <b>int</b>s, even in the BSD version. Because of the way options are named, the name space could not be extended to solve these +problems. This is why the <b>-t</b> option was added (with type specifiers more closely matched to the <a href= +"../functions/printf.html"><i>printf</i>()</a> formats used in the rest of this volume of POSIX.1-2024) and the optional field +sizes were added to the <tt>d</tt>, <tt>f</tt>, <tt>o</tt>, <tt>u</tt>, and <tt>x</tt> type specifiers. It is also one of the +reasons why the historical practice was not mandated as a required obsolescent form of <i>od</i>. (Although the old versions of +<i>od</i> are not listed as an obsolescent form, implementations are urged to continue to recognize the older forms for several +more years.) The <tt>a</tt>, <tt>c</tt>, <tt>f</tt>, <tt>o</tt>, and <tt>x</tt> types match the meaning of the corresponding format +characters in the historical implementations of <i>od</i> except for the default sizes of the fields converted. The <tt>d</tt> +format is signed in this volume of POSIX.1-2024 to match the <a href="../functions/printf.html"><i>printf</i>()</a> notation. +(Historical versions of <i>od</i> used <tt>d</tt> as a synonym for <tt>u</tt> in this version. The System V implementation uses +<tt>s</tt> for signed decimal; BSD uses <tt>i</tt> for signed decimal and <tt>s</tt> for null-terminated strings.) Other than +<tt>d</tt> and <tt>u</tt>, all of the type specifiers match format characters in the historical BSD version of <b>od</b>. +<p class="tent">The sizes of the C-language types <b>char</b>, <b>short</b>, <b>int</b>, <b>long</b>, <b>float</b>, <b>double</b>, +and <b>long double</b> are used even though it is recognized that there may be zero or more than one compiler for the C language on +an implementation and that they may use different sizes for some of these types. (For example, one compiler might use 2 bytes +<b>short</b>s, 2 bytes <b>int</b>s, and 4 bytes <b>long</b>s, while another compiler (or an option to the same compiler) uses 2 +bytes <b>short</b>s, 4 bytes <b>int</b>s, and 4 bytes <b>long</b>s.) Nonetheless, there has to be a basic size known by the +implementation for these types, corresponding to the values reported by invocations of the <a href= +"../utilities/getconf.html"><i>getconf</i></a> utility when called with <i>system_var</i> operands {UCHAR_MAX}, {USHORT_MAX}, +{UINT_MAX}, and {ULONG_MAX} for the types <b>char</b>, <b>short</b>, <b>int</b>, and <b>long</b>, respectively. There are similar +constants required by the ISO C standard, but not required by the System Interfaces volume of POSIX.1-2024 or this volume of +POSIX.1-2024. They are {FLT_MANT_DIG}, {DBL_MANT_DIG}, and {LDBL_MANT_DIG} for the types <b>float</b>, <b>double</b>, and <b>long +double</b>, respectively. If the optional <a href="../utilities/c17.html"><i>c17</i></a> utility is provided by the implementation +and used as specified by this volume of POSIX.1-2024, these are the sizes that would be provided. If an option is used that +specifies different sizes for these types, there is no guarantee that the <i>od</i> utility is able to interpret binary data output +by such a program correctly.</p> +<p class="tent">This volume of POSIX.1-2024 requires that the numeric values of these lengths be recognized by the <i>od</i> +utility and that symbolic forms also be recognized. Thus, a conforming application can always look at an array of <b>unsigned +long</b> data elements using <i>od</i> <b>-t</b> <i>uL</i>.</p> +</li> +<li class="tent">The method of specifying the format for the address field based on specifying a starting offset in a file +unnecessarily tied the two together. The <b>-A</b> option now specifies the address base and the <b>-S</b> option specifies a +starting offset.</li> +<li class="tent">It would be difficult to break the dependence on US ASCII to achieve an internationalized utility. It does not +seem to be any harder for <i>od</i> to dump characters in the current locale than it is for the <a href= +"../utilities/ed.html"><i>ed</i></a> or <a href="../utilities/sed.html"><i>sed</i></a> <b>l</b> commands. The <tt>c</tt> type +specifier does this without difficulty and is completely compatible with the historical implementations of the <b>c</b> format +character when the current locale uses a superset of the ISO/IEC 646:1991 standard as a codeset. The <tt>a</tt> type specifier +(from the BSD <b>a</b> format character) was left as a portable means to dump ASCII (or more correctly ISO/IEC 646:1991 +standard (IRV)) so that headers produced by <a href="../utilities/pax.html"><i>pax</i></a> could be deciphered even on systems that +do not use the ISO/IEC 646:1991 standard as a subset of their base codeset.</li> +</ul> +<p class="tent">The use of <tt>"**"</tt> as an indication of continuation of a multi-byte character in <tt>c</tt> specifier output +was chosen based on seeing an implementation that uses this method. The continuation bytes have to be marked in a way that is not +ambiguous with another single-byte or multi-byte character.</p> +<p class="tent">An early proposal used <b>-S</b> and <b>-n</b>, respectively, for the <b>-j</b> and <b>-N</b> options eventually +selected. These were changed to avoid conflicts with historical implementations.</p> +<p class="tent">The original standard specified <b>-t o2</b> as the default when no output type was given. This was changed to +<b>-t oS</b> (the length of a <b>short</b>) to accommodate a supercomputer implementation that historically used 64 bits as its +default (and that defined shorts as 64 bits). This change should not affect conforming applications. The requirement to support +lengths of 1, 2, and 4 was added at the same time to address an historical implementation that had no two-byte data types in its C +compiler.</p> +<p class="tent">The use of a basic integer data type is intended to allow the implementation to choose a word size commonly used by +applications on that architecture.</p> +<p class="tent">Earlier versions of this standard allowed for implementations with bytes other than eight bits, but this has been +modified in this version.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_90_19" id="tag_20_90_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>All option and operand interfaces marked XSI may be removed in a future version.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_90_20" id="tag_20_90_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/c17.html#"><i>c17</i></a> , <a href="../utilities/sed.html#"><i>sed</i></a></p> +<p class="tent">XBD <a href="../basedefs/V1_chap05.html#tag_05"><i>5. File Format Notation</i></a> , <a href= +"../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 +Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_90_21" id="tag_20_90_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_90_22" id="tag_20_90_22"></a>Issue 5</h4> +<blockquote> +<p>In the description of the <b>-c</b> option, the phrase "This is equivalent to <b>-t c</b>." is deleted.</p> +<p class="tent">The FUTURE DIRECTIONS section is modified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_90_23" id="tag_20_90_23"></a>Issue 6</h4> +<blockquote> +<p>The <i>od</i> utility is changed to remove the assumption that <b>short</b> was a two-byte entity, as per the revisions in the +IEEE P1003.2b draft standard.</p> +<p class="tent">The normative text is reworded to avoid use of the term "must" for application requirements.</p> +<p class="tent">IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/33 is applied, correcting the examples which used +an undefined <b>-n</b> option, which should have been <b>-N</b>.</p> +<p class="tent">IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/19 is applied, removing text describing behavior on +systems with bytes consisting of more than eight bits.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_90_24" id="tag_20_90_24"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #092 is applied.</p> +<p class="tent">SD5-XCU-ERN-37 is applied, updating the OPERANDS section.</p> +<p class="tent">SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_90_25" id="tag_20_90_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1017 is applied, clarifying that when <b>-A n</b> is specified, the line that would contain the final +offset can either be written as an empty line or not be written.</p> +<p class="tent">Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/nohup.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/paste.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/paste.html b/bdd/paste.html @@ -0,0 +1,288 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>paste</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/od.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/patch.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="paste" id="paste"></a> <a name="tag_20_91" id="tag_20_91"></a><!-- paste --> +<h4 class="mansect"><a name="tag_20_91_01" id="tag_20_91_01"></a>NAME</h4> +<blockquote>paste — merge corresponding or subsequent lines of files</blockquote> +<h4 class="mansect"><a name="tag_20_91_02" id="tag_20_91_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>paste</tt> <b>[</b><tt>-s</tt><b>] [</b><tt>-d</tt> <i>list</i><b>]</b> <i>file</i><tt>...</tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_91_03" id="tag_20_91_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>paste</i> utility shall concatenate the corresponding lines of the given input files, and write the resulting lines to +standard output.</p> +<p>The default operation of <i>paste</i> shall concatenate the corresponding lines of the input files. The <newline> of every +line except the line from the last input file shall be replaced with a <tab>.</p> +<p>If an end-of-file condition is detected on one or more input files, but not all input files, <i>paste</i> shall behave as though +empty lines were read from the files on which end-of-file was detected, unless the <b>-s</b> option is specified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_91_04" id="tag_20_91_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>paste</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-d </b><i>list</i></dt> +<dd>Unless a <backslash> character appears in <i>list</i>, each character in <i>list</i> is an element specifying a delimiter +character. If a <backslash> character appears in <i>list</i>, the <backslash> character and one or more characters +following it are an element specifying a delimiter character as described below. These elements specify one or more delimiters to +use, instead of the default <tab>, to replace the <newline> of the input lines. The elements in <i>list</i> shall be +used circularly; that is, when the list is exhausted the first element from the list is reused. When the <b>-s</b> option is +specified: +<ul> +<li> +<p>The last <newline> in a file shall not be modified.</p> +</li> +<li> +<p>The delimiter shall be reset to the first element of <i>list</i> after each <i>file</i> operand is processed.</p> +</li> +</ul> +<p>When the <b>-s</b> option is not specified:</p> +<ul> +<li> +<p>The <newline> characters in the file specified by the last <i>file</i> operand shall not be modified.</p> +</li> +<li> +<p>The delimiter shall be reset to the first element of list each time a line is processed from each file.</p> +</li> +</ul> +<p>If a <backslash> character appears in <i>list</i>, it and the character following it shall be used to represent the +following delimiter characters:</p> +<dl compact> +<dd></dd> +<dt><tt>\n</tt></dt> +<dd><newline>.</dd> +<dt><tt>\t</tt></dt> +<dd><tab>.</dd> +<dt><tt>\\</tt></dt> +<dd><backslash> character.</dd> +<dt><tt>\0</tt></dt> +<dd>Empty string (not a null character). If <tt>'\0'</tt> is immediately followed by the character <tt>'x'</tt>, the character +<tt>'X'</tt>, or any character defined by the <i>LC_CTYPE</i> <b>digit</b> keyword (see XBD <a href= +"../basedefs/V1_chap07.html#tag_07"><i>7. Locale</i></a> ), the results are unspecified.</dd> +</dl> +<p>If any other characters follow the <backslash>, the results are unspecified.</p> +</dd> +<dt><b>-s</b></dt> +<dd>Concatenate all of the lines from each input file into one line of output per file, in command line order. The <newline> +of every line except the last line in each input file shall be replaced with a <tab>, unless otherwise specified by the +<b>-d</b> option. If an input file is empty, the output line corresponding to that file shall consist of only a <newline> +character.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_91_05" id="tag_20_91_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of an input file. If <tt>'-'</tt> is specified for one or more of the <i>file</i>s, the standard input shall be +used; the standard input shall be read one line at a time, circularly, for each instance of <tt>'-'</tt>. Implementations shall +support pasting of at least 12 <i>file</i> operands.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_91_06" id="tag_20_91_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be used only if one or more <i>file</i> operands is <tt>'-'</tt>. See the INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_91_07" id="tag_20_91_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files shall be text files, except that line lengths shall be unlimited.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_91_08" id="tag_20_91_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>paste</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_91_09" id="tag_20_91_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_91_10" id="tag_20_91_10"></a>STDOUT</h4> +<blockquote> +<p>Concatenated lines of input files shall be separated by the <tab> (or other characters under the control of the <b>-d</b> +option) and terminated by a <newline>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_91_11" id="tag_20_91_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_91_12" id="tag_20_91_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_91_13" id="tag_20_91_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_91_14" id="tag_20_91_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_91_15" id="tag_20_91_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>If one or more input files cannot be opened when the <b>-s</b> option is not specified, a diagnostic message shall be written to +standard error, but no output is written to standard output. If the <b>-s</b> option is specified, the <i>paste</i> utility shall +provide the default behavior described in <a href="../utilities/V3_chap01.html#tag_18_04"><i>1.4 Utility Description +Defaults</i></a> .</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_91_16" id="tag_20_91_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>When the escape sequences of the <i>list</i> option-argument are used in a shell script, they must be quoted; otherwise, the +shell treats the <backslash> as a special character.</p> +<p>Conforming applications should only use the specific <backslash>-escaped delimiters presented in this volume of +POSIX.1-2024. Historical implementations treat <tt>'\x'</tt>, where <tt>'x'</tt> is not in this list, as <tt>'x'</tt>, but future +implementations are free to expand this list to recognize other common escapes similar to those accepted by <a href= +"../utilities/printf.html"><i>printf</i></a> and other standard utilities.</p> +<p>Most of the standard utilities work on text files. The <a href="../utilities/cut.html"><i>cut</i></a> utility can be used to +turn files with arbitrary line lengths into a set of text files containing the same data. The <i>paste</i> utility can be used to +create (or recreate) files with arbitrary line lengths. For example, if <i>file</i> contains long lines:</p> +<pre> +<tt>cut -b 1-500 -n file > file1 +cut -b 501- -n file > file2 +</tt></pre> +<p>creates <b>file1</b> (a text file) with lines no longer than 500 bytes (plus the <newline>) and <b>file2</b> that contains +the remainder of the data from <i>file</i>. Note that <b>file2</b> is not a text file if there are lines in <i>file</i> that are +longer than 500 + {LINE_MAX} bytes. The original file can be recreated from <b>file1</b> and <b>file2</b> using the command:</p> +<pre> +<tt>paste -d "\0" file1 file2 > file +</tt></pre> +<p>The commands:</p> +<pre> +<tt>paste -d "\0" ... +paste -d "" ... +</tt></pre> +<p>are not necessarily equivalent; the latter is not specified by this volume of POSIX.1-2024 and may result in an error. The +construct <tt>'\0'</tt> is used to mean "no separator" because historical versions of <i>paste</i> did not follow the syntax +guidelines, and the command:</p> +<pre> +<tt>paste -d"" ... +</tt></pre> +<p>could not be handled properly by <a href="../functions/getopt.html"><i>getopt</i>()</a>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_91_17" id="tag_20_91_17"></a>EXAMPLES</h4> +<blockquote> +<ol> +<li> +<p>Write out a directory in four columns:</p> +<pre> +<tt>ls | paste - - - - +</tt></pre></li> +<li> +<p>Combine pairs of lines from a file into single lines:</p> +<pre> +<tt>paste -s -d "\t\n" file +</tt></pre></li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_91_18" id="tag_20_91_18"></a>RATIONALE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_91_19" id="tag_20_91_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_91_20" id="tag_20_91_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap01.html#tag_18_04"><i>1.4 Utility Description Defaults</i></a> , <a href= +"../utilities/cut.html#"><i>cut</i></a> , <a href="../utilities/grep.html#"><i>grep</i></a> , <a href= +"../utilities/pr.html#"><i>pr</i></a></p> +<p>XBD <a href="../basedefs/V1_chap07.html#tag_07"><i>7. Locale</i></a> , <a href="../basedefs/V1_chap08.html#tag_08"><i>8. +Environment Variables</i></a> , <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_91_21" id="tag_20_91_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_91_22" id="tag_20_91_22"></a>Issue 6</h4> +<blockquote> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_91_23" id="tag_20_91_23"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0149 [973] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_91_24" id="tag_20_91_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/od.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/patch.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/patch.html b/bdd/patch.html @@ -0,0 +1,447 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>patch</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/paste.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/pathchk.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="patch" id="patch"></a> <a name="tag_20_92" id="tag_20_92"></a><!-- patch --> +<h4 class="mansect"><a name="tag_20_92_01" id="tag_20_92_01"></a>NAME</h4> +<blockquote>patch — apply changes to files</blockquote> +<h4 class="mansect"><a name="tag_20_92_02" id="tag_20_92_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>patch</tt> <b>[</b><tt>-blNR</tt><b>] [</b><tt>-c|-e|-n|-u</tt><b>] [</b><tt>-d</tt> <i>dir</i><b>] [</b><tt>-D</tt> +<i>define</i><b>] [</b><tt>-i</tt> <i>patchfile</i><b>]<br></b> <tt> </tt> <b>[</b><tt>-o</tt> +<i>outfile</i><b>] [</b><tt>-p</tt> <i>num</i><b>] [</b><tt>-r</tt> <i>rejectfile</i><b>] [</b><i>file</i><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_92_03" id="tag_20_92_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>patch</i> utility shall read a source (patch) file containing any of four forms of difference (diff) listings produced by +the <a href="../utilities/diff.html"><i>diff</i></a> utility (normal, copied context, unified context, or in the style of <a href= +"../utilities/ed.html"><i>ed</i></a>) and apply those differences to a file. By default, <i>patch</i> shall read from the standard +input.</p> +<p>The <i>patch</i> utility shall attempt to determine the type of the <a href="../utilities/diff.html"><i>diff</i></a> listing, +unless overruled by a <b>-c</b>, <b>-e</b>, <b>-n</b>, or <b>-u</b> option.</p> +<p>If the patch file contains more than one patch, <i>patch</i> shall attempt to apply each of them as if they came from separate +patch files. (In this case, the application shall ensure that the name of the patch file is determinable for each <a href= +"../utilities/diff.html"><i>diff</i></a> listing.)</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_92_04" id="tag_20_92_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>patch</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-b</b></dt> +<dd>Save a copy of the original contents of each modified file, before the differences are applied, in a file of the same name with +the suffix <b>.orig</b> appended to it. If the file already exists, it shall be overwritten; if multiple patches are applied to the +same file, the <b>.orig</b> file shall be written only for the first patch. When the <b>-o</b> <i>outfile</i> option is also +specified, <i>file</i><b>.orig</b> shall not be created but, if <i>outfile</i> already exists, <i>outfile</i><b>.orig</b> shall be +created.</dd> +<dt><b>-c</b></dt> +<dd>Interpret the patch file as a copied context difference (the output of the utility <a href= +"../utilities/diff.html"><i>diff</i></a> when the <b>-c</b> or <b>-C</b> options are specified).</dd> +<dt><b>-d </b><i>dir</i></dt> +<dd>Change the current directory to <i>dir</i> before processing as described in the EXTENDED DESCRIPTION section.</dd> +<dt><b>-D </b><i>define</i></dt> +<dd>Mark changes with one of the following C preprocessor constructs: +<pre> +<tt>#ifdef define +... +#endif +<br> +#ifndef define +... +#endif +</tt></pre> +<p>optionally combined with the C preprocessor construct <b>#else</b>. If the patched file is processed with the C preprocessor, +where the macro <i>define</i> is defined, the output shall contain the changes from the patch file; otherwise, the output shall not +contain the patches specified in the patch file.</p> +</dd> +<dt><b>-e</b></dt> +<dd>Interpret the patch file as an <a href="../utilities/ed.html"><i>ed</i></a> script, rather than a <a href= +"../utilities/diff.html"><i>diff</i></a> script.</dd> +<dt><b>-i </b><i>patchfile</i></dt> +<dd>Read the patch information from the file named by the pathname <i>patchfile</i>, rather than the standard input.</dd> +<dt><b>-l</b></dt> +<dd>(The letter ell.) Cause any sequence of <blank> characters in the difference script to match any sequence of +<blank> characters in the input file. Other characters shall be matched exactly.</dd> +<dt><b>-n</b></dt> +<dd>Interpret the script as a normal difference.</dd> +<dt><b>-N</b></dt> +<dd>Ignore patches where the differences have already been applied to the file; by default, already-applied patches shall be +rejected.</dd> +<dt><b>-o </b><i>outfile</i></dt> +<dd>Instead of modifying the files (specified by the <i>file</i> operand or the difference listings) directly, write a copy of the +file referenced by each patch, with the appropriate differences applied, to <i>outfile</i>. Multiple patches for a single file +shall be applied to the intermediate versions of the file created by any previous patches, and shall result in multiple, +concatenated versions of the file being written to <i>outfile</i>.</dd> +<dt><b>-p </b><i>num</i></dt> +<dd>For all pathnames in the patch file that indicate the names of files to be patched, delete <i>num</i> pathname components from +the beginning of each pathname. If the pathname in the patch file is absolute, any leading <slash> characters shall be +considered the first component (that is, <b>-p 1</b> shall remove the leading <slash> characters). Specifying +<b>-p 0</b> shall cause the full pathname to be used. If <b>-p</b> is not specified, only the basename (the final pathname +component) shall be used.</dd> +<dt><b>-R</b></dt> +<dd>Reverse the sense of the patch script; that is, assume that the difference script was created from the new version to the old +version. The <b>-R</b> option cannot be used with <a href="../utilities/ed.html"><i>ed</i></a> scripts. The <i>patch</i> utility +shall attempt to reverse each portion of the script before applying it. Rejected differences shall be saved in swapped format. If +this option is not specified, and until a portion of the patch file is successfully applied, <i>patch</i> attempts to apply each +portion in its reversed sense as well as in its normal sense. If the attempt is successful, the user shall be prompted to determine +whether the <b>-R</b> option should be set.</dd> +<dt><b>-r </b><i>rejectfile</i></dt> +<dd>Override the default reject filename. In the default case, the reject file shall have the same name as the output file, with +the suffix <b>.rej</b> appended to it; see <a href="#tag_20_92_13_03">Patch Application</a> .</dd> +<dt><b>-u</b></dt> +<dd>Interpret the patch file as a unified context difference (the output of the <a href="../utilities/diff.html"><i>diff</i></a> +utility when the <b>-u</b> or <b>-U</b> options are specified).</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_92_05" id="tag_20_92_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of a file to patch.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_92_06" id="tag_20_92_06"></a>STDIN</h4> +<blockquote> +<p>See the INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_92_07" id="tag_20_92_07"></a>INPUT FILES</h4> +<blockquote> +<p>Input files shall be text files.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_92_08" id="tag_20_92_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>patch</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_COLLATE</i></dt> +<dd><br> +Determine the locale for the behavior of ranges, equivalence classes, and multi-character collating elements used in the extended +regular expression defined for the <b>yesexpr</b> locale keyword in the <i>LC_MESSAGES</i> category.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files), and the behavior of character classes used in the extended regular +expression defined for the <b>yesexpr</b> locale keyword in the <i>LC_MESSAGES</i> category.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale used to process affirmative responses, and the locale used to affect the format and contents of diagnostic +messages and prompts written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>LC_TIME</i></dt> +<dd>Determine the locale for recognizing the format of file timestamps written by the <a href= +"../utilities/diff.html"><i>diff</i></a> utility in a context-difference input file.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_92_09" id="tag_20_92_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_92_10" id="tag_20_92_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_92_11" id="tag_20_92_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used for diagnostic and informational messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_92_12" id="tag_20_92_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>The output of the <i>patch</i> utility, the save files (<b>.orig</b> suffixes), and the reject files (<b>.rej</b> suffixes) +shall be text files.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_92_13" id="tag_20_92_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>A patch file may contain patching instructions for more than one file; filenames shall be determined as specified in <a href= +"#tag_20_92_13_02">Filename Determination</a> . When the <b>-b</b> option is specified, for each patched file, the original shall +be saved in a file of the same name with the suffix <b>.orig</b> appended to it.</p> +<p>For each patched file, a reject file may also be created as noted in <a href="#tag_20_92_13_03">Patch Application</a> . In the +absence of a <b>-r</b> option, the name of this file shall be formed by appending the suffix <b>.rej</b> to the original +filename.</p> +<h5><a name="tag_20_92_13_01" id="tag_20_92_13_01"></a>Patch File Format</h5> +<p>The patch file shall contain zero or more lines of header information followed by one or more patches. Each patch shall contain +zero or more lines of filename identification in the format produced by the <b>-c</b>, <b>-C</b>, <b>-u</b>, or <b>-U</b> options +of the <a href="../utilities/diff.html"><i>diff</i></a> utility, and one or more sets of <a href= +"../utilities/diff.html"><i>diff</i></a> output, which are customarily called <i>hunks</i>.</p> +<p>The <i>patch</i> utility shall recognize the following expression in the header information:</p> +<dl compact> +<dd></dd> +<dt><b>Index: </b><i>pathname</i></dt> +<dd><br> +The file to be patched is named <i>pathname</i>.</dd> +</dl> +<p>If all lines (including headers) within a patch begin with the same leading sequence of <blank> characters, the +<i>patch</i> utility shall remove this sequence before proceeding. Within each patch, if the type of difference is common context, +the <i>patch</i> utility shall recognize the following expressions:</p> +<dl compact> +<dd></dd> +<dt>*** <i>filename timestamp</i></dt> +<dd><br> +The patches arose from <i>filename</i>.</dd> +<dt>--- <i>filename timestamp</i></dt> +<dd><br> +The patches should be applied to <i>filename</i>.</dd> +</dl> +<p>If the type of difference is unified context, the <i>patch</i> utility shall recognize the following expressions:</p> +<dl compact> +<dd></dd> +<dt>--- <i>filename timestamp</i></dt> +<dd><br> +The patches arose from <i>filename</i>.</dd> +<dt>+++ <i>filename timestamp</i></dt> +<dd><br> +The patches should be applied to <i>filename</i>.</dd> +</dl> +<p>Each hunk within a patch shall be the <a href="../utilities/diff.html"><i>diff</i></a> output to change a line range within the +original file. The line numbers for successive hunks within a patch shall occur in ascending order.</p> +<h5><a name="tag_20_92_13_02" id="tag_20_92_13_02"></a>Filename Determination</h5> +<p>If no <i>file</i> operand is specified, <i>patch</i> shall perform the following steps to determine the filename to use:</p> +<ol> +<li> +<p>If the type of <a href="../utilities/diff.html"><i>diff</i></a> is context, the <i>patch</i> utility shall delete pathname +components (as specified by the <b>-p</b> option) from the filename on the line beginning with <tt>"***"</tt> (if copied context) +or <tt>"---"</tt> (if unified context), then test for the existence of this file relative to the current directory (or the +directory specified with the <b>-d</b> option). If the file exists, the <i>patch</i> utility shall use this filename.</p> +</li> +<li> +<p>If the type of <a href="../utilities/diff.html"><i>diff</i></a> is context, the <i>patch</i> utility shall delete the pathname +components (as specified by the <b>-p</b> option) from the filename on the line beginning with <tt>"---"</tt> (if copied context) +or <tt>"+++"</tt> (if unified context), then test for the existence of this file relative to the current directory (or the +directory specified with the <b>-d</b> option). If the file exists, the <i>patch</i> utility shall use this filename.</p> +</li> +<li> +<p>If the header information contains a line beginning with the string <b>Index:</b>, the <i>patch</i> utility shall delete +pathname components (as specified by the <b>-p</b> option) from this line, then test for the existence of this file relative to the +current directory (or the directory specified with the <b>-d</b> option). If the file exists, the <i>patch</i> utility shall use +this filename.</p> +</li> +<li> +<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +If an <b>SCCS</b> directory exists in the current directory, <i>patch</i> shall attempt to perform a <a href= +"../utilities/get.html"><i>get</i></a> <b>-e</b> <b>SCCS/s.</b><i>filename</i> command to retrieve an editable version of the file. +If the file exists, the <i>patch</i> utility shall use this filename. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></p> +</li> +<li> +<p>The <i>patch</i> utility shall write a prompt to standard output and request a filename interactively from the controlling +terminal (for example, <b>/dev/tty</b>).</p> +</li> +</ol> +<h5><a name="tag_20_92_13_03" id="tag_20_92_13_03"></a>Patch Application</h5> +<p>If the <b>-c</b>, <b>-e</b>, <b>-n</b>, or <b>-u</b> option is present, the <i>patch</i> utility shall interpret information +within each hunk as a copied context difference, an <a href="../utilities/ed.html"><i>ed</i></a> difference, a normal difference, +or a unified context difference, respectively. In the absence of any of these options, the <i>patch</i> utility shall determine the +type of difference based on the format of information within the hunk.</p> +<p>For each hunk, the <i>patch</i> utility shall begin to search for the place to apply the patch at the line number at the +beginning of the hunk, plus or minus any offset used in applying the previous hunk. If lines matching the hunk context are not +found, <i>patch</i> shall scan both forwards and backwards at least 1000 bytes for a set of lines that match the hunk context.</p> +<p>If no such place is found and it is a context difference, then another scan shall take place, ignoring the first and last line +of context. If that fails, the first two and last two lines of context shall be ignored and another scan shall be made. +Implementations may search more extensively for installation locations.</p> +<p>If no location can be found, the <i>patch</i> utility shall append the hunk to the reject file. A rejected hunk that is a copied +context difference, an <a href="../utilities/ed.html"><i>ed</i></a> difference, or a normal difference shall be written in +copied-context-difference format regardless of the format of the patch file. It is implementation-defined whether a rejected hunk +that is a unified context difference is written in copied-context-difference format or in unified-context-difference format. If the +input was a normal or <a href="../utilities/ed.html"><i>ed</i></a>-style difference, the reject file may contain differences with +zero lines of context. The line numbers on the hunks in the reject file may be different from the line numbers in the patch file +since they shall reflect the approximate locations for the failed hunks in the new file rather than the old one.</p> +<p>If the type of patch is an <a href="../utilities/ed.html"><i>ed</i></a> diff, the implementation may accomplish the patching by +invoking the <a href="../utilities/ed.html"><i>ed</i></a> utility.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_92_14" id="tag_20_92_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt> 1</dt> +<dd>One or more lines were written to a reject file.</dd> +<dt>>1</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_92_15" id="tag_20_92_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Patches that cannot be correctly placed in the file shall be written to a reject file.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_92_16" id="tag_20_92_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The <b>-R</b> option does not work with <a href="../utilities/ed.html"><i>ed</i></a> scripts because there is too little +information to reconstruct the reverse operation.</p> +<p>The <b>-p</b> option makes it possible to customize a patch file to local user directory structures without manually editing the +patch file. For example, if the filename in the patch file was:</p> +<pre> +<tt>/curds/whey/src/blurfl/blurfl.c +</tt></pre> +<p>Setting <b>-p 0</b> gives the entire pathname unmodified; <b>-p 1</b> gives:</p> +<pre> +<tt>curds/whey/src/blurfl/blurfl.c +</tt></pre> +<p>without the leading <slash>, <b>-p 4</b> gives:</p> +<pre> +<tt>blurfl/blurfl.c +</tt></pre> +<p>and not specifying <b>-p</b> at all gives:</p> +<pre> +<tt>blurfl.c . +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_92_17" id="tag_20_92_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_92_18" id="tag_20_92_18"></a>RATIONALE</h4> +<blockquote> +<p>Some of the functionality in historical <i>patch</i> implementations was not specified. The following documents those features +present in historical implementations that have not been specified.</p> +<p>A deleted piece of functionality was the <tt>'+'</tt> pseudo-option allowing an additional set of options and a patch file +operand to be given. This was seen as being insufficiently useful to standardize.</p> +<p>In historical implementations, if the string <tt>"Prereq:"</tt> appeared in the header, the <i>patch</i> utility would search +for the corresponding version information (the string specified in the header, delimited by <blank> characters or the +beginning or end of a line or the file) anywhere in the original file. This was deleted as too simplistic and insufficiently +trustworthy a mechanism to standardize. For example, if:</p> +<pre> +<tt>Prereq: 1.2 +</tt></pre> +<p>were in the header, the presence of a delimited 1.2 anywhere in the file would satisfy the prerequisite.</p> +<p>The following options were dropped from historical implementations of <i>patch</i> as insufficiently useful to standardize:</p> +<dl compact> +<dd></dd> +<dt><b>-b</b></dt> +<dd>The <b>-b</b> option historically provided a method for changing the name extension of the backup file from the default +<b>.orig</b>. This option has been modified and retained in this volume of POSIX.1-2024.</dd> +<dt><b>-F</b></dt> +<dd>The <b>-F</b> option specified the number of lines of a context diff to ignore when searching for a place to install a +patch.</dd> +<dt><b>-f</b></dt> +<dd>The <b>-f</b> option historically caused <i>patch</i> not to request additional information from the user.</dd> +<dt><b>-r</b></dt> +<dd>The <b>-r</b> option historically provided a method of overriding the extension of the reject file from the default +<b>.rej</b>.</dd> +<dt><b>-s</b></dt> +<dd>The <b>-s</b> option historically caused <i>patch</i> to work silently unless an error occurred.</dd> +<dt><b>-x</b></dt> +<dd>The <b>-x</b> option historically set internal debugging flags.</dd> +</dl> +<p>In some file system implementations, the saving of a <b>.orig</b> file may produce unwanted results. In the case of 12, 13, or +14-character filenames (on file systems supporting 14-character maximum filenames), the <b>.orig</b> file overwrites the new file. +The reject file may also exceed this filename limit. It was suggested, due to some historical practice, that a <tilde> +(<tt>'~'</tt>) suffix be used instead of <b>.orig</b> and some other character instead of the <b>.rej</b> suffix. This was rejected +because it is not obvious to the user which file is which. The suffixes <b>.orig</b> and <b>.rej</b> are clearer and more +understandable.</p> +<p>The <b>-b</b> option has the opposite sense in some historical implementations—do not save the <b>.orig</b> file. The default +case here is not to save the files, making <i>patch</i> behave more consistently with the other standard utilities.</p> +<p>The <b>-w</b> option in early proposals was changed to <b>-l</b> to match historical practice.</p> +<p>The <b>-N</b> option was included because without it, a non-interactive application cannot reject previously applied patches. +For example, if a user is piping the output of <a href="../utilities/diff.html"><i>diff</i></a> into the <i>patch</i> utility, and +the user only wants to patch a file to a newer version non-interactively, the <b>-N</b> option is required.</p> +<p>Changes to the <b>-l</b> option description were proposed to allow matching across <newline> characters in addition to +just <blank> characters. Since this is not historical practice, and since some ambiguities could result, it is suggested that +future developments in this area utilize another option letter, such as <b>-L</b>.</p> +<p>The <b>-u</b> option of GNU <i>patch</i> has been added, along with support for unified context formats.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_92_19" id="tag_20_92_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a +<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require +implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_92_20" id="tag_20_92_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/diff.html#"><i>diff</i></a> , <a href="../utilities/ed.html#"><i>ed</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_92_21" id="tag_20_92_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_92_22" id="tag_20_92_22"></a>Issue 5</h4> +<blockquote> +<p>The FUTURE DIRECTIONS section is added.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_92_23" id="tag_20_92_23"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +<p>The description of the <b>-D</b> option and the steps in <a href="#tag_20_92_13_02">Filename Determination</a> are changed to +match historical practice as defined in the IEEE P1003.2b draft standard.</p> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +<p>IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/34 is applied, clarifying the way that the <i>patch</i> utility +performs <b>ifdef</b> selection for the <b>-D</b> option.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_92_24" id="tag_20_92_24"></a>Issue 7</h4> +<blockquote> +<p>The <i>patch</i> utility is moved from the User Portability Utilities option to the Base. User Portability Utilities is now an +option for interactive utilities.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>SD5-XCU-ERN-103 and SD5-XCU-ERN-120 are applied, adding the <b>-u</b> option.</p> +<p>Austin Group Interpretation 1003.1-2001 #126 is applied, changing the description of the <i>LC_MESSAGES</i> and <i>LC_CTYPE</i> +environment variables and adding the <i>LC_COLLATE</i> environment variable.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_92_25" id="tag_20_92_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to disallow the creation of filenames containing any bytes that +have the encoded value of a <newline> character.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/paste.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/pathchk.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/pathchk.html b/bdd/pathchk.html @@ -0,0 +1,360 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>pathchk</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/patch.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/pax.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="pathchk" id="pathchk"></a> <a name="tag_20_93" id="tag_20_93"></a><!-- pathchk --> +<h4 class="mansect"><a name="tag_20_93_01" id="tag_20_93_01"></a>NAME</h4> +<blockquote>pathchk — check pathnames</blockquote> +<h4 class="mansect"><a name="tag_20_93_02" id="tag_20_93_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>pathchk</tt> <b>[</b><tt>-p</tt><b>] [</b><tt>-P</tt><b>]</b> <i>pathname</i><tt>...</tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_93_03" id="tag_20_93_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>pathchk</i> utility shall check that one or more pathnames are valid (that is, they could be used to access or create a +file without causing syntax errors) and portable (that is, no filename truncation results). More extensive portability checks are +provided by the <b>-p</b> and <b>-P</b> options.</p> +<p>By default, the <i>pathchk</i> utility shall check each component of each <i>pathname</i> operand based on the underlying file +system. A diagnostic shall be written for each <i>pathname</i> operand that:</p> +<ul> +<li> +<p>Is longer than {PATH_MAX} bytes (see <b>Pathname Variable Values</b> in XBD <a href= +"../basedefs/limits.h.html"><i><limits.h></i></a> )</p> +</li> +<li> +<p>Contains any component longer than {NAME_MAX} bytes in its containing directory</p> +</li> +<li> +<p>Contains any component in a directory that is not searchable</p> +</li> +<li> +<p>Contains any byte sequence that is not valid in its containing directory</p> +</li> +</ul> +<p>The format of the diagnostic message is not specified, but shall indicate the error detected and the corresponding +<i>pathname</i> operand.</p> +<p>It shall not be considered an error if one or more components of a <i>pathname</i> operand do not exist as long as a file +matching the pathname specified by the missing components could be created that does not violate any of the checks specified +above.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_93_04" id="tag_20_93_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>pathchk</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following option shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-p</b></dt> +<dd>Instead of performing checks based on the underlying file system, write a diagnostic for each <i>pathname</i> operand that: +<ul> +<li> +<p>Is longer than {_POSIX_PATH_MAX} bytes (see <b>Minimum Values</b> in XBD <a href= +"../basedefs/limits.h.html"><i><limits.h></i></a> )</p> +</li> +<li> +<p>Contains any component longer than {_POSIX_NAME_MAX} bytes</p> +</li> +<li> +<p>Contains any character in any component that is not in the portable filename character set</p> +</li> +</ul> +</dd> +<dt><b>-P</b></dt> +<dd>Write a diagnostic for each <i>pathname</i> operand that: +<ul> +<li> +<p>Contains a component whose first character is the <hyphen-minus> character</p> +</li> +<li> +<p>Is empty</p> +</li> +</ul> +</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_93_05" id="tag_20_93_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>pathname</i></dt> +<dd>A pathname to be checked.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_93_06" id="tag_20_93_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_93_07" id="tag_20_93_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_93_08" id="tag_20_93_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>pathchk</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_93_09" id="tag_20_93_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_93_10" id="tag_20_93_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_93_11" id="tag_20_93_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_93_12" id="tag_20_93_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_93_13" id="tag_20_93_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_93_14" id="tag_20_93_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>All <i>pathname</i> operands passed all of the checks.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_93_15" id="tag_20_93_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_93_16" id="tag_20_93_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The <a href="../utilities/test.html"><i>test</i></a> utility can be used to determine whether a given pathname names an existing +file; it does not, however, give any indication of whether or not any component of the pathname was truncated in a directory where +the _POSIX_NO_TRUNC feature is not in effect. The <i>pathchk</i> utility does not check for file existence; it performs checks to +determine whether a pathname does exist or could be created with no pathname component truncation.</p> +<p>The <i>noclobber</i> option in the shell (see the <a href="../utilities/V3_chap02.html#tag_19_26"><i>set</i></a> special +built-in) can be used to atomically create a file. As with all file creation semantics in the System Interfaces volume of +POSIX.1-2024, it guarantees atomic creation, but still depends on applications to agree on conventions and cooperate on the use of +files after they have been created.</p> +<p>To verify that a pathname meets the requirements of filename portability, applications should use both the <b>-p</b> and +<b>-P</b> options together.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_93_17" id="tag_20_93_17"></a>EXAMPLES</h4> +<blockquote> +<p>To verify that all pathnames in an imported data interchange archive are legitimate and unambiguous on the current system:</p> +<pre> +<tt># This example assumes that no pathnames in the archive +# contain <newline> characters. +pax -f archive | sed -e 's/[^[:alnum:]]/\\&/g' | xargs pathchk -- +if [ $? -eq 0 ] +then + pax -r -f archive +else + echo Investigate problems before importing files. + exit 1 +fi +</tt></pre> +<p>To verify that all files in the current directory hierarchy could be moved to any system conforming to the System Interfaces +volume of POSIX.1-2024 that also supports the <a href="../utilities/pax.html"><i>pax</i></a> utility:</p> +<pre> +<tt>find . -exec pathchk -p -P {} + +if [ $? -eq 0 ] +then + pax -w -f ../archive . +else + echo Portable archive cannot be created. + exit 1 +fi +</tt></pre> +<p>To verify that a user-supplied pathname names a readable file and that the application can create a file extending the given +path without truncation and without overwriting any existing file:</p> +<pre> +<tt>case $- in + *C*) reset="";; + *) reset="set +C" + set -C;; +esac +test -r "$path" && pathchk "$path.out" && + rm "$path.out" > "$path.out" +if [ $? -ne 0 ]; then + printf "%s: %s not found or %s.out fails \ +creation checks.\n" $0 "$path" "$path" + $reset # Reset the noclobber option in case a trap + # on EXIT depends on it. + exit 1 +fi +$reset +PROCESSING < "$path" > "$path.out" +</tt></pre> +<p>The following assumptions are made in this example:</p> +<ol> +<li> +<p><b>PROCESSING</b> represents the code that is used by the application to use <b>$path</b> once it is verified that +<b>$path.out</b> works as intended.</p> +</li> +<li> +<p>The state of the <i>noclobber</i> option is unknown when this code is invoked and should be set on exit to the state it was in +when this code was invoked. (The <b>reset</b> variable is used in this example to restore the initial state.)</p> +</li> +<li> +<p>Note the usage of:</p> +<pre> +<tt>rm "$path.out" > "$path.out" +</tt></pre> +<ol type="a"> +<li> +<p>The <i>pathchk</i> command has already verified, at this point, that <b>$path.out</b> is not truncated.</p> +</li> +<li> +<p>With the <i>noclobber</i> option set, the shell verifies that <b>$path.out</b> does not already exist before invoking <a href= +"../utilities/rm.html"><i>rm</i></a>.</p> +</li> +<li> +<p>If the shell succeeded in creating <b>$path.out</b>, <a href="../utilities/rm.html"><i>rm</i></a> removes it so that the +application can create the file again in the <b>PROCESSING</b> step.</p> +</li> +<li> +<p>If the <b>PROCESSING</b> step wants the file to exist already when it is invoked, the:</p> +<pre> +<tt>rm "$path.out" > "$path.out" +</tt></pre> +<p>should be replaced with:</p> +<pre> +<tt>> "$path.out" +</tt></pre> +<p>which verifies that the file did not already exist, but leaves <b>$path.out</b> in place for use by <b>PROCESSING</b>.</p> +</li> +</ol> +</li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_93_18" id="tag_20_93_18"></a>RATIONALE</h4> +<blockquote> +<p>The <i>pathchk</i> utility was new for the ISO POSIX-2:1993 standard. It, along with the <a href= +"../utilities/V3_chap02.html#set"><i>set</i></a> <b>-C</b>(<i>noclobber</i>) option added to the shell, replaces the <i>mktemp</i>, +<i>validfnam</i>, and <i>create</i> utilities that appeared in early proposals. All of these utilities were attempts to solve +several common problems:</p> +<ul> +<li> +<p>Verify the validity (for several different definitions of "valid") of a pathname supplied by a user, generated by an +application, or imported from an external source.</p> +</li> +<li> +<p>Atomically create a file.</p> +</li> +<li> +<p>Perform various string handling functions to generate a temporary filename.</p> +</li> +</ul> +<p>The <i>create</i> utility, included in an early proposal, provided checking and atomic creation in a single invocation of the +utility; these are orthogonal issues and need not be grouped into a single utility. Note that the <i>noclobber</i> option also +provides a way of creating a lock for process synchronization; since it provides an atomic <i>create</i>, there is no race between +a test for existence and the following creation if it did not exist.</p> +<p>Having a function like <a href="../functions/tmpnam.html"><i>tmpnam</i>()</a> in the ISO C standard is important in many +high-level languages. The shell programming language, however, has built-in string manipulation facilities, making it very easy to +construct temporary filenames. The names needed obviously depend on the application, but are frequently of a form similar to:</p> +<pre> +<b>$TMPDIR/</b><i>application_abbreviation</i><b>$$.</b><i>suffix</i><tt> +</tt></pre> +<p>In cases where there is likely to be contention for a given suffix, a simple shell <b>for</b> or <b>while</b> loop can be used +with the shell <i>noclobber</i> option to create a file without risk of collisions, as long as applications trying to use the same +filename name space are cooperating on the use of files after they have been created.</p> +<p>For historical purposes, <b>-p</b> does not check for the use of the <hyphen-minus> character as the first character in a +component of the pathname, or for an empty <i>pathname</i> operand.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_93_19" id="tag_20_93_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_93_20" id="tag_20_93_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19_07"><i>2.7 Redirection</i></a> , <a href= +"../utilities/V3_chap02.html#tag_19_26"><i>set</i></a> , <a href="../utilities/test.html#"><i>test</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a> , <a href= +"../basedefs/limits.h.html"><i><limits.h></i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_93_21" id="tag_20_93_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_93_22" id="tag_20_93_22"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretations 1003.1-2001 #039, #040, and #094 are applied.</p> +<p>SD5-XCU-ERN-121 is applied, updating the EXAMPLES section.</p> +<p>POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0127 [291] is applied.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0150 [584] and XCU/TC2-2008/0151 [584] are applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_93_23" id="tag_20_93_23"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/patch.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/pax.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/pax.html b/bdd/pax.html @@ -0,0 +1,2739 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>pax</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/pathchk.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/pr.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="pax" id="pax"></a> <a name="tag_20_94" id="tag_20_94"></a><!-- pax --> +<h4 class="mansect"><a name="tag_20_94_01" id="tag_20_94_01"></a>NAME</h4> +<blockquote>pax — portable archive interchange</blockquote> +<h4 class="mansect"><a name="tag_20_94_02" id="tag_20_94_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>pax</tt> <b>[</b><tt>-dv</tt><b>] [</b><tt>-c|-n</tt><b>] [</b><tt>-H|-L</tt><b>] [</b><tt>-o</tt> <i>options</i><b>] +[</b><tt>-f</tt> <i>archive</i><b>] [</b><tt>-s</tt> <i>replstr</i><b>]</b><tt>...<br> + </tt> <b>[</b><i>pattern</i><tt>...</tt><b>]</b> <tt><br> +<br> +pax -r</tt><b>[</b><tt>-c|-n</tt><b>] [</b><tt>-dikuv</tt><b>] [</b><tt>-H|-L</tt><b>] [</b><tt>-f</tt> <i>archive</i><b>] +[</b><tt>-o</tt> <i>options</i><b>]</b><tt>...</tt> <b>[</b><tt>-p</tt> <i>string</i><b>]</b><tt>...<br> + </tt> <b>[</b><tt>-s</tt> <i>replstr</i><b>]</b><tt>...</tt> +<b>[</b><i>pattern</i><tt>...</tt><b>]</b> <tt><br> +<br> +pax -w</tt> <b>[</b><tt>-dituvX</tt><b>] [</b><tt>-H|-L</tt><b>] [</b><tt>-b</tt> <i>blocksize</i><b>] [[</b><tt>-a</tt><b>] +[</b><tt>-f</tt> <i>archive</i><b>]] [</b><tt>-o</tt> <i>options</i><b>]</b><tt>...<br> + </tt> <b>[</b><tt>-s</tt> <i>replstr</i><b>]</b><tt>...</tt> <b>[</b><tt>-x</tt> +<i>format</i><b>] [</b><i>file</i><tt>...</tt><b>]</b> <tt><br> +<br> +pax -r -w</tt> <b>[</b><tt>-dikltuvX</tt><b>] [</b><tt>-H|-L</tt><b>] [</b><tt>-o</tt> <i>options</i><b>]</b><tt>...</tt> +<b>[</b><tt>-p</tt> <i>string</i><b>]</b><tt>...<br> + </tt> <b>[</b><tt>-s</tt> <i>replstr</i><b>]</b><tt>...</tt> +<b>[</b><i>file</i><tt>...</tt><b>]</b> <i>directory</i> <tt><br></tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_94_03" id="tag_20_94_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>pax</i> utility shall read, write, and write lists of the members of archive files and copy directory hierarchies. A +variety of archive formats shall be supported; see the <b>-x</b> <i>format</i> option.</p> +<p>The action to be taken depends on the presence of the <b>-r</b> and <b>-w</b> options. The four combinations of <b>-r</b> and +<b>-w</b> are referred to as the four modes of operation: <b>list</b>, <b>read</b>, <b>write</b>, and <b>copy</b> modes, +corresponding respectively to the four forms shown in the SYNOPSIS section.</p> +<dl compact> +<dd></dd> +<dt><b>list</b></dt> +<dd>In <b>list</b> mode (when neither <b>-r</b> nor <b>-w</b> are specified), <i>pax</i> shall write the names of the members of +the archive file read from the standard input, with pathnames matching the specified patterns, to standard output. If a named file +is of type directory, the file hierarchy rooted at that file shall be listed as well.</dd> +<dt><b>read</b></dt> +<dd>In <b>read</b> mode (when <b>-r</b> is specified, but <b>-w</b> is not), <i>pax</i> shall extract the members of the archive +file read from the standard input, with pathnames matching the specified patterns. If an extracted file is of type directory, the +file hierarchy rooted at that file shall be extracted as well. The extracted files shall be created performing pathname resolution +with the directory in which <i>pax</i> was invoked as the current working directory. +<p>If an attempt is made to extract a directory when the directory already exists, this shall not be considered an error. If an +attempt is made to extract a FIFO when the FIFO already exists, this shall not be considered an error.</p> +<p>The ownership, access, and modification times, and file mode of the restored files are discussed under the <b>-p</b> option.</p> +</dd> +<dt><b>write</b></dt> +<dd>In <b>write</b> mode (when <b>-w</b> is specified, but <b>-r</b> is not), <i>pax</i> shall write the contents of the +<i>file</i> operands to the standard output in an archive format. If no <i>file</i> operands are specified, a list of files to +copy, one per line, shall be read from the standard input and each entry in this list shall be processed as if it had been a +<i>file</i> operand on the command line. A file of type directory shall include all of the files in the file hierarchy rooted at +the file.</dd> +<dt><b>copy</b></dt> +<dd>In <b>copy</b> mode (when both <b>-r</b> and <b>-w</b> are specified), <i>pax</i> shall copy the <i>file</i> operands to the +destination directory. +<p>If no <i>file</i> operands are specified, a list of files to copy, one per line, shall be read from the standard input. A file +of type directory shall include all of the files in the file hierarchy rooted at the file.</p> +<p>The effect of the <b>copy</b> shall be as if the copied files were written to a <i>pax</i> format archive file and then +subsequently extracted, except that copying of sockets may be supported even if archiving them in write mode is not supported, and +that there may be hard links between the original and the copied files. If the destination directory is a subdirectory of one of +the files to be copied, the results are unspecified. If the destination directory is a file of a type not defined by the System +Interfaces volume of POSIX.1-2024, the results are implementation-defined; otherwise, it shall be an error for the file named by +the <i>directory</i> operand not to exist, not be writable by the user, or not be a file of type directory.</p> +</dd> +</dl> +<p>In <b>read</b> or <b>copy</b> modes, if intermediate directories are necessary to extract an archive member, <i>pax</i> shall +perform actions equivalent to the <a href="../functions/mkdir.html"><i>mkdir</i>()</a> function defined in the System Interfaces +volume of POSIX.1-2024, called with the following arguments:</p> +<ul> +<li> +<p>The intermediate directory used as the <i>path</i> argument</p> +</li> +<li> +<p>The value of the bitwise-inclusive OR of S_IRWXU, S_IRWXG, and S_IRWXO as the <i>mode</i> argument</p> +</li> +</ul> +<p>If any specified <i>pattern</i> or <i>file</i> operands are not matched by at least one file or archive member, <i>pax</i> shall +write a diagnostic message to standard error for each one that did not match and exit with a non-zero exit status.</p> +<p>The archive formats described in the EXTENDED DESCRIPTION section shall be automatically detected on input. The default output +archive format shall be implementation-defined.</p> +<p>A single archive can span multiple files. The <i>pax</i> utility shall determine, in an implementation-defined manner, what file +to read or write as the next file.</p> +<p>If the selected archive format supports the specification of linked files, it shall be an error if these files cannot be linked +when the archive is extracted. For archive formats that do not store file contents with each name that causes a hard link, if the +file that contains the data is not extracted during this <i>pax</i> session, either the data shall be restored from the original +file, or a diagnostic message shall be displayed with the name of a file that can be used to extract the data. In traversing +directories, <i>pax</i> shall detect infinite loops; that is, entering a previously visited directory that is an ancestor of the +last file visited. When it detects an infinite loop, <i>pax</i> shall write a diagnostic message to standard error and shall +terminate.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_94_04" id="tag_20_94_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>pax</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> , except that the order of presentation of the <b>-o</b>, <b>-p</b>, and <b>-s</b> options is significant.</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-r</b></dt> +<dd>Read an archive file from standard input.</dd> +<dt><b>-w</b></dt> +<dd>Write files to the standard output in the specified archive format.</dd> +<dt><b>-a</b></dt> +<dd>Append files to the end of the archive. It is implementation-defined which devices on the system support appending. Additional +file formats unspecified by this volume of POSIX.1-2024 may impose restrictions on appending.</dd> +<dt><b>-b </b><i>blocksize</i></dt> +<dd>Block the output at a positive decimal integer number of bytes per write to the archive file. Devices and archive formats may +impose restrictions on blocking. Blocking shall be automatically determined on input. Conforming applications shall not specify a +<i>blocksize</i> value larger than 32256. Default blocking when creating archives depends on the archive format. (See the <b>-x</b> +option below.)</dd> +<dt><b>-c</b></dt> +<dd>Match all file or archive members except those specified by the <i>pattern</i> or <i>file</i> operands.</dd> +<dt><b>-d</b></dt> +<dd>Cause files of type directory being copied or archived or archive members of type directory being extracted or listed to match +only the file or archive member itself and not the file hierarchy rooted at the file.</dd> +<dt><b>-f </b><i>archive</i></dt> +<dd>Specify the pathname of the input or output archive, overriding the default standard input (in <b>list</b> or <b>read</b> +modes) or standard output (<b>write</b> mode).</dd> +<dt><b>-H</b></dt> +<dd>If a symbolic link referencing a file of type directory is specified on the command line, <i>pax</i> shall archive the file +hierarchy rooted in the file referenced by the link, using the name of the link as the root of the file hierarchy. Otherwise, if a +symbolic link referencing a file of any other file type which <i>pax</i> can normally archive is specified on the command line, +then <i>pax</i> shall archive the file referenced by the link, using the name of the link. The default behavior, when neither +<b>-H</b> or <b>-L</b> are specified, shall be to archive the symbolic link itself.</dd> +<dt><b>-i</b></dt> +<dd>Interactively rename files or archive members. For each archive member matching a <i>pattern</i> operand or file matching a +<i>file</i> operand, a prompt shall be written to the file <b>/dev/tty</b>. The prompt shall contain the name of the file or +archive member, but the format is otherwise unspecified. A line shall then be read from <b>/dev/tty</b>. If this line is blank, the +file or archive member shall be skipped. If this line consists of a single period, the file or archive member shall be processed +with no modification to its name. Otherwise, its name shall be replaced with the contents of the line. The <i>pax</i> utility shall +immediately exit with a non-zero exit status if end-of-file is encountered when reading a response or if <b>/dev/tty</b> cannot be +opened for reading and writing. +<p>The results of extracting a hard link to a file that has been renamed during extraction are unspecified.</p> +</dd> +<dt><b>-k</b></dt> +<dd>Prevent the overwriting of existing files.</dd> +<dt><b>-l</b></dt> +<dd>(The letter ell.) In <b>copy</b> mode, hard links shall be made between the source and destination file hierarchies whenever +possible. If specified in conjunction with <b>-H</b> or <b>-L</b>, when a symbolic link is encountered, the hard link created in +the destination file hierarchy shall be to the file referenced by the symbolic link. If specified when neither <b>-H</b> nor +<b>-L</b> is specified, when a symbolic link is encountered, the implementation shall create a hard link to the symbolic link in +the source file hierarchy or copy the symbolic link to the destination.</dd> +<dt><b>-L</b></dt> +<dd>If a symbolic link referencing a file of type directory is specified on the command line or encountered during the traversal of +a file hierarchy, <i>pax</i> shall archive the file hierarchy rooted in the file referenced by the link, using the name of the link +as the root of the file hierarchy. Otherwise, if a symbolic link referencing a file of any other file type which <i>pax</i> can +normally archive is specified on the command line or encountered during the traversal of a file hierarchy, <i>pax</i> shall archive +the file referenced by the link, using the name of the link. The default behavior, when neither <b>-H</b> or <b>-L</b> are +specified, shall be to archive the symbolic link itself.</dd> +<dt><b>-n</b></dt> +<dd>Select the first archive member that matches each <i>pattern</i> operand. No more than one archive member shall be matched for +each pattern (although members of type directory shall still match the file hierarchy rooted at that file).</dd> +<dt><b>-o </b><i>options</i></dt> +<dd>Provide information to the implementation to modify the algorithm for extracting or writing files. The value of <i>options</i> +shall consist of one or more <comma>-separated keywords of the form: +<pre> +<i>keyword</i><b>[[</b><tt>:</tt><b>]</b><tt>=</tt><i>value</i><b>][</b><tt>,</tt><i>keyword</i><b>[[</b><tt>:</tt><b>]</b><tt>=</tt><i>value</i><b>]</b><tt>, ...</tt><b>]</b><tt> +</tt></pre> +<p>Some keywords apply only to certain file formats, as indicated with each description. Use of keywords that are inapplicable to +the file format being processed produces undefined results.</p> +<p>Keywords in the <i>options</i> argument shall be a string that would be a valid portable filename as described in XBD <a href= +"../basedefs/V1_chap03.html#tag_03_265"><i>3.265 Portable Filename Character Set</i></a> . <basefont size="2"></p> +<dl> +<dt><b>Note:</b></dt> +<dd>Keywords are not expected to be filenames, merely to follow the same character composition rules as portable filenames.</dd> +</dl> +<basefont size="3"> +<p>Keywords can be preceded with white space. The <i>value</i> field shall consist of zero or more characters; within <i>value</i>, +the application shall precede any literal <comma> with a <backslash>, which shall be ignored, but preserves the +<comma> as part of <i>value</i>. A <comma> as the final character, or a <comma> followed solely by white space as +the final characters, in <i>options</i> shall be ignored. Multiple <b>-o</b> options can be specified; if keywords given to these +multiple <b>-o</b> options conflict, the keywords and values appearing later in command line sequence shall take precedence and the +earlier shall be silently ignored. The following keyword values of <i>options</i> shall be supported for the file formats as +indicated:</p> +<dl compact> +<dd></dd> +<dt><b>delete</b>=<i>pattern</i></dt> +<dd><br> +(Applicable only to the <b>-x</b> <b>pax</b> format.) When used in <b>write</b> or <b>copy</b> mode, <i>pax</i> shall omit from +extended header records that it produces any keywords matching the string pattern. When used in <b>read</b> or <b>list</b> mode, +<i>pax</i> shall ignore any keywords matching the string pattern in the extended header records. In both cases, matching shall be +performed using the pattern matching notation described in <a href="../utilities/V3_chap02.html#tag_19_14_01"><i>2.14.1 Patterns +Matching a Single Character</i></a> and <a href="../utilities/V3_chap02.html#tag_19_14_02"><i>2.14.2 Patterns Matching Multiple +Characters</i></a> . For example: +<pre> +<tt>-o </tt><b>delete</b><tt>=</tt><i>security</i><tt>.* +</tt></pre> +<p>would suppress security-related information. See <a href="#tag_20_94_13_03">pax Extended Header</a> for extended header record +keyword usage.</p> +<p>When multiple <b>-o</b><b>delete=pattern</b> options are specified, the patterns shall be additive; all keywords matching the +specified string patterns shall be omitted from extended header records that <i>pax</i> produces.</p> +</dd> +<dt><b>exthdr.name</b>=<i>string</i></dt> +<dd><br> +(Applicable only to the <b>-x</b> <b>pax</b> format.) This keyword allows user control over the name that is written into the +<b>ustar</b> header blocks for the extended header produced under the circumstances described in <a href="#tag_20_94_13_02">pax +Header Block</a> . The name shall be the contents of <i>string</i>, after the following character substitutions have been made: +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b><i>string</i> Includes:</b></p> +</th> +<th align="center"> +<p class="tent"><b>Replaced by:</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">%d</p> +</td> +<td align="left"> +<p class="tent">The directory name of the file, equivalent to the result of the <a href= +"../utilities/dirname.html"><i>dirname</i></a> utility on the translated pathname.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">%f</p> +</td> +<td align="left"> +<p class="tent">The filename of the file, equivalent to the result of the <a href="../utilities/basename.html"><i>basename</i></a> +utility on the translated pathname.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">%p</p> +</td> +<td align="left"> +<p class="tent">The process ID of the <i>pax</i> process.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">%%</p> +</td> +<td align="left"> +<p class="tent">A <tt>'%'</tt> character.</p> +</td> +</tr> +</table> +</center> +<p class="tent">Any other <tt>'%'</tt> characters in <i>string</i> produce undefined results.</p> +<p class="tent">If no <b>-o</b> <b>exthdr.name=string</b> is specified, <i>pax</i> shall use the following default value:</p> +<pre> +<tt>%d/PaxHeaders.%p/%f +</tt></pre></dd> +<dt><b>globexthdr.name</b>=<i>string</i></dt> +<dd><br> +(Applicable only to the <b>-x</b> <b>pax</b> format.) When used in <b>write</b> or <b>copy</b> mode with the appropriate options, +<i>pax</i> shall create global extended header records with <b>ustar</b> header blocks that are treated as regular files by +previous versions of <i>pax</i>. This keyword allows user control over the name that is written into the <b>ustar</b> header blocks +for global extended header records. The name shall be the contents of string, after the following character substitutions have been +made: +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b><i>string</i> Includes:</b></p> +</th> +<th align="center"> +<p class="tent"><b>Replaced by:</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">%n</p> +</td> +<td align="left"> +<p class="tent">An integer that represents the sequence number of the global extended header record in the archive, starting at +1.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">%p</p> +</td> +<td align="left"> +<p class="tent">The process ID of the <i>pax</i> process.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">%%</p> +</td> +<td align="left"> +<p class="tent">A <tt>'%'</tt> character.</p> +</td> +</tr> +</table> +</center> +<p class="tent">Any other <tt>'%'</tt> characters in <i>string</i> produce undefined results.</p> +<p class="tent">If no <b>-o</b> <b>globexthdr.name=string</b> is specified, <i>pax</i> shall use the following default value:</p> +<pre> +<tt>$TMPDIR/GlobalHead.%p.%n +</tt></pre> +<p class="tent">where $<i>TMPDIR</i> represents the value of the <i>TMPDIR</i> environment variable. If <i>TMPDIR</i> is not set, +<i>pax</i> shall use <b>/tmp</b>.</p> +</dd> +<dt><b>invalid</b>=<i>action</i></dt> +<dd><br> +(Applicable only to the <b>-x</b> <b>pax</b> format.) This keyword allows user control over the action <i>pax</i> takes upon +encountering values in an extended header record that, in <b>read</b> or <b>copy</b> mode, are invalid in the destination hierarchy +or, in <b>list</b> mode, cannot be written in the codeset and current locale of the implementation. The following are invalid +values that shall be recognized by <i>pax</i>: +<ul> +<li class="tent">In <b>read</b> or <b>copy</b> mode, a filename or link name that contains character encodings invalid in the +destination hierarchy. (For example, the name may contain embedded NULs.)</li> +<li class="tent">In <b>read</b> or <b>copy</b> mode, a filename or link name that is longer than the maximum allowed in the +destination hierarchy (for either a pathname component or the entire pathname).</li> +<li class="tent">In <b>list</b> mode, any character string value (filename, link name, user name, and so on) that cannot be written +in the codeset and current locale of the implementation.</li> +</ul> +<p class="tent">The following mutually-exclusive values of the <i>action</i> argument are supported:</p> +<dl compact> +<dd></dd> +<dt><b>binary</b></dt> +<dd>In <b>write</b> mode, <i>pax</i> shall generate a <b>hdrcharset</b>=<b>BINARY</b> extended header record for each file with a +filename, link name, group name, owner name, or any other field in an extended header record that cannot be translated to the UTF-8 +codeset, allowing the archive to contain the files with unencoded extended header record values. In <b>read</b> or <b>copy</b> +mode, <i>pax</i> shall use the values specified in the header without translation, regardless of whether this may overwrite an +existing file with a valid name. In <b>list</b> mode, <i>pax</i> shall behave identically to the <b>bypass</b> action.</dd> +<dt><b>bypass</b></dt> +<dd>In <b>read</b> or <b>copy</b> mode, <i>pax</i> shall bypass the file, causing no change to the destination hierarchy. In +<b>list</b> mode, <i>pax</i> shall write all requested valid values for the file, but its method for writing invalid values is +unspecified.</dd> +<dt><b>rename</b></dt> +<dd>In <b>read</b> or <b>copy</b> mode, <i>pax</i> shall act as if the <b>-i</b> option were in effect for each file with invalid +filename or link name values, allowing the user to provide a replacement name interactively. In <b>list</b> mode, <i>pax</i> shall +behave identically to the <b>bypass</b> action.</dd> +<dt><b>UTF-8</b></dt> +<dd>When used in <b>read</b>, <b>copy</b>, or <b>list</b> mode and a filename, link name, owner name, or any other field in an +extended header record cannot be translated from the <b>pax</b> UTF-8 codeset format to the codeset and current locale of the +implementation, <i>pax</i> shall use the actual UTF-8 encoding for the name. If a <b>hdrcharset</b> extended header record is in +effect for this file, the character set specified by that record shall be used instead of UTF-8. If a +<b>hdrcharset</b>=<b>BINARY</b> extended header record is in effect for this file, no translation shall be performed.</dd> +<dt><b>write</b></dt> +<dd>In <b>read</b> or <b>copy</b> mode, <i>pax</i> shall write the file, translating the name, regardless of whether this may +overwrite an existing file with a valid name. In <b>list</b> mode, <i>pax</i> shall behave identically to the <b>bypass</b> +action.</dd> +</dl> +<p class="tent">If no <b>-o</b> <b>invalid=option</b> is specified, <i>pax</i> shall act as if <b>-o</b><b>invalid=bypass</b> were +specified. Any overwriting of existing files that may be allowed by the <b>-o</b><b>invalid=</b> actions shall be subject to +permission (<b>-p</b>) and modification time (<b>-u</b>) restrictions, and shall be suppressed if the <b>-k</b> option is also +specified.</p> +</dd> +<dt><b>linkdata</b></dt> +<dd><br> +(Applicable only to the <b>-x</b> <b>pax</b> format.) In <b>write</b> mode, <i>pax</i> shall write the contents of a file to the +archive even when that file is merely a hard link to a file whose contents have already been written to the archive.</dd> +<dt><b>listopt</b>=<i>format</i></dt> +<dd><br> +This keyword specifies the output format of the table of contents produced when the <b>-v</b> option is specified in <b>list</b> +mode. See <a href="#tag_20_94_04_01">List Mode Format Specifications</a> . To avoid ambiguity, the <b>listopt=format</b> shall be +the only or final <b>keyword=value</b> pair in a <b>-o</b> option-argument; all characters in the remainder of the option-argument +shall be considered part of the format string. When multiple <b>-o</b><b>listopt=format</b> options are specified, the format +strings shall be considered a single, concatenated string, evaluated in command line order.</dd> +<dt><b>times</b></dt> +<dd><br> +(Applicable only to the <b>-x</b> <i>pax</i> format.) When used in <b>write</b> or <b>copy</b> mode, <i>pax</i> shall include +<b>atime</b> and <b>mtime</b> extended header records for each file. See <a href="#tag_20_94_13_05">pax Extended Header File +Times</a> .</dd> +</dl> +<p class="tent">In addition to these keywords, if the <b>-x</b> <i>pax</i> format is specified, any of the keywords and values +defined in <a href="#tag_20_94_13_03">pax Extended Header</a> , including implementation extensions, can be used in <b>-o</b> +option-arguments, in either of two modes:</p> +<dl compact> +<dd></dd> +<dt><b>keyword</b>=<i>value</i></dt> +<dd><br> +When used in <b>write</b> or <b>copy</b> mode, these keyword/value pairs shall be included at the beginning of the archive as +<b>typeflag</b> <b>g</b> global extended header records. When used in <b>read</b> or <b>list</b> mode, these keyword/value pairs +shall act as if they had been at the beginning of the archive as <b>typeflag</b> <b>g</b> global extended header records.</dd> +<dt><b>keyword</b>:=<i>value</i></dt> +<dd><br> +When used in <b>write</b> or <b>copy</b> mode, these keyword/value pairs shall be included as records at the beginning of a +<b>typeflag</b> <b>x</b> extended header for each file. (This shall be equivalent to the <equals-sign> form except that it +creates no <b>typeflag</b> <b>g</b> global extended header records.) When used in <b>read</b> or <b>list</b> mode, these +keyword/value pairs shall act as if they were included as records at the end of each extended header; thus, they shall override any +global or file-specific extended header record keywords of the same names. For example, in the command: +<pre> +<tt>pax -r -o " +gname:=mygroup, +" <archive +</tt></pre> +<p class="tent">the group name is forced to a new value for all files read from the archive.</p> +</dd> +</dl> +<p class="tent">The precedence of <b>-o</b> keywords over various fields in the archive is described in <a href= +"#tag_20_94_13_04">pax Extended Header Keyword Precedence</a> . If the <b>-o</b> <b>delete</b>=<i>pattern</i>, <b>-o</b> +<b>keyword</b>=<i>value</i>, or <b>-o</b> <b>keyword</b>:=<i>value</i> options are used to override or remove any extended header +data needed to find files in an archive (e.g., <tt>-o delete=size</tt> for a file whose size cannot be represented in a +<b>ustar</b> header or <tt>-o size=100</tt> for a file whose size is not 100 bytes), the behavior is undefined.</p> +</dd> +<dt><b>-p </b><i>string</i></dt> +<dd>Specify one or more file characteristic options (privileges). The <i>string</i> option-argument shall be a string specifying +file characteristics to be retained or discarded on extraction. The string shall consist of the specification characters +<tt>a</tt>, <tt>e</tt>, <tt>m</tt>, <tt>o</tt>, and <tt>p</tt>. Other implementation-defined characters can be included. Multiple +characteristics can be concatenated within the same string and multiple <b>-p</b> options can be specified. The meaning of the +specification characters are as follows: +<dl compact> +<dd></dd> +<dt><tt>a</tt></dt> +<dd>Do not preserve file access times.</dd> +<dt><tt>e</tt></dt> +<dd>Preserve the user ID, group ID, file mode bits (see XBD <a href="../basedefs/V1_chap03.html#tag_03_145"><i>3.145 File Mode +Bits</i></a> ), access time, modification time, and any other implementation-defined file characteristics.</dd> +<dt><tt>m</tt></dt> +<dd>Do not preserve file modification times.</dd> +<dt><tt>o</tt></dt> +<dd>Preserve the user ID and group ID.</dd> +<dt><tt>p</tt></dt> +<dd>Preserve the file mode bits. Other implementation-defined file mode attributes may be preserved.</dd> +</dl> +<p class="tent">In the preceding list, "preserve" indicates that an attribute stored in the archive shall be given to the +extracted file, subject to the permissions of the invoking process. The access and modification times of the file shall be +preserved unless otherwise specified with the <b>-p</b> option or not stored in the archive. All attributes that are not preserved +shall be determined as part of the normal file creation action (see <a href= +"../utilities/V3_chap01.html#tag_18_01_01_04"><i>1.1.1.4 File Read, Write, and Creation</i></a> ).</p> +<p class="tent">If neither the <tt>e</tt> nor the <tt>o</tt> specification character is specified, or the user ID and group ID are +not preserved for any reason, <i>pax</i> shall not set the S_ISUID and S_ISGID bits of the file mode.</p> +<p class="tent">If the preservation of any of these items fails for any reason, <i>pax</i> shall write a diagnostic message to +standard error. Failure to preserve these items shall affect the final exit status, but shall not cause the extracted file to be +deleted.</p> +<p class="tent">If file characteristic letters in any of the <i>string</i> option-arguments are duplicated or conflict with each +other, the ones given last shall take precedence. For example, if <b>-p</b> <tt>eme</tt> is specified, file modification times are +preserved.</p> +</dd> +<dt><b>-s </b><i>replstr</i></dt> +<dd>Modify file or archive member names named by <i>pattern</i> or <i>file</i> operands according to the substitution expression +<i>replstr</i>, using the syntax of the <a href="../utilities/ed.html"><i>ed</i></a> utility. The concepts of "address" and +"line" are meaningless in the context of the <i>pax</i> utility, and shall not be supplied. The format shall be: +<pre> +<tt>-s /</tt><i>old</i><tt>/</tt><i>new</i><tt>/</tt><b>[</b><tt>gpsS</tt><b>]</b><tt> +</tt></pre> +<p class="tent">where as in <a href="../utilities/ed.html"><i>ed</i></a>, <i>old</i> is a basic regular expression and <i>new</i> +can contain an <ampersand>, <tt>'\n'</tt> (where <i>n</i> is a digit) back-references, or subexpression matching. The +<i>old</i> string shall also be permitted to contain <newline> characters.</p> +<p class="tent">Any non-null character can be used as a delimiter (<tt>'/'</tt> shown here). Multiple <b>-s</b> expressions can be +specified; the expressions shall be applied in the order specified, terminating with the first successful substitution. The +optional trailing <tt>'g'</tt> is as defined in the <a href="../utilities/ed.html"><i>ed</i></a> utility. The optional trailing +<tt>'p'</tt> shall cause successful substitutions to be written to standard error. The optional trailing <tt>'s'</tt> and +<tt>'S'</tt> control whether the substitutions are applied to symbolic link contents: <tt>'s'</tt> shall cause them not to be +applied; <tt>'S'</tt> shall cause them to be applied. If neither is present, it is unspecified which is the default. If both are +present, the behavior is unspecified. File or archive member names that substitute to the empty string shall be ignored when +reading and writing archives. Symbolic link contents that substitute to the empty string shall not be treated specially.</p> +</dd> +<dt><b>-t</b></dt> +<dd>When reading files from the file system, and if the user has the permissions required by <a href= +"../functions/futimens.html"><i>futimens</i>()</a> to do so, set the access time of each file read to the access time that it had +before being read by <i>pax</i>.</dd> +<dt><b>-u</b></dt> +<dd>Ignore files that are older (having a less recent file modification time) than a pre-existing file or archive member with the +same name. In <b>read</b> mode, an archive member with the same name as a file in the file system shall be extracted if the archive +member is newer than the file. In <b>write</b> mode, an archive file member with the same name as a file in the file system shall +be superseded if the file is newer than the archive member. If <b>-a</b> is also specified, this is accomplished by appending to +the archive; otherwise, it is unspecified whether this is accomplished by actual replacement in the archive or by appending to the +archive. In <b>copy</b> mode, the file in the destination hierarchy shall be replaced if the file in the source hierarchy is +newer.</dd> +<dt><b>-v</b></dt> +<dd>In <b>list</b> mode, produce a verbose table of contents (see the STDOUT section). Otherwise, write archive member pathnames to +standard error (see the STDERR section).</dd> +<dt><b>-x </b><i>format</i></dt> +<dd>Specify the output archive format. The <i>pax</i> utility shall support the following formats: +<dl compact> +<dd></dd> +<dt><b>cpio</b></dt> +<dd>The <b>cpio</b> interchange format; see the EXTENDED DESCRIPTION section. The default <i>blocksize</i> for this format for +character special archive files shall be 5120. Implementations shall support all <i>blocksize</i> values less than or equal to +32256 that are multiples of 512.</dd> +<dt><b>pax</b></dt> +<dd>The <b>pax</b> interchange format; see the EXTENDED DESCRIPTION section. The default <i>blocksize</i> for this format for +character special archive files shall be 5120. Implementations shall support all <i>blocksize</i> values less than or equal to +32256 that are multiples of 512.</dd> +<dt><b>ustar</b></dt> +<dd>The <b>tar</b> interchange format; see the EXTENDED DESCRIPTION section. The default <i>blocksize</i> for this format for +character special archive files shall be 10240. Implementations shall support all <i>blocksize</i> values less than or equal to +32256 that are multiples of 512.</dd> +</dl> +<p class="tent">Implementation-defined formats shall specify a default block size as well as any other block sizes supported for +character special archive files.</p> +<p class="tent">Any attempt to append to an archive file in a format different from the existing archive format shall cause +<i>pax</i> to exit immediately with a non-zero exit status.</p> +</dd> +<dt><b>-X</b></dt> +<dd>When traversing the file hierarchy specified by a pathname, <i>pax</i> shall not descend below directories that have a +different device ID (<i>st_dev</i>; see XSH <a href="../functions/fstatat.html#"><i>fstatat</i></a> ) than the specified pathname; +that is, when a directory with a different device ID is encountered, <i>pax</i> shall process (archive or copy) the directory +itself but shall not process any files below the directory.</dd> +</dl> +<p class="tent">Specifying more than one of the mutually-exclusive options <b>-H</b> and <b>-L</b> shall not be considered an error +and the last option specified shall determine the behavior of the utility.</p> +<p class="tent">The options that operate on the names of files or archive members (<b>-c</b>, <b>-i</b>, <b>-n</b>, <b>-s</b>, +<b>-u</b>, and <b>-v</b>) shall interact as follows. In <b>read</b> mode, the archive members shall be selected based on the +user-specified <i>pattern</i> operands as modified by the <b>-c</b>, <b>-n</b>, and <b>-u</b> options. Then, any <b>-s</b> and +<b>-i</b> options shall modify, in that order, the names of the selected files. The <b>-v</b> option shall write names resulting +from these modifications.</p> +<p class="tent">In <b>write</b> mode, the files shall be selected based on the user-specified pathnames as modified by the +<b>-u</b> option. Then, any <b>-s</b> and <b>-i</b> options shall modify, in that order, the names of these selected files. The +<b>-v</b> option shall write names resulting from these modifications.</p> +<p class="tent">If both the <b>-u</b> and <b>-n</b> options are specified, <i>pax</i> shall not consider a file selected unless it +is newer than the file to which it is compared.</p> +<h5><a name="tag_20_94_04_01" id="tag_20_94_04_01"></a>List Mode Format Specifications</h5> +<p class="tent">In <b>list</b> mode with the <b>-o</b> <b>listopt=format</b> option, the <i>format</i> argument shall be applied +for each selected file. The <i>pax</i> utility shall append a <newline> to the <b>listopt</b> output for each selected file. +The <i>format</i> argument shall be used as the <i>format</i> string described in XBD <a href= +"../basedefs/V1_chap05.html#tag_05"><i>5. File Format Notation</i></a> , with the exceptions 1. through 6. defined in the EXTENDED +DESCRIPTION section of <a href="../utilities/printf.html"><i>printf</i></a>, plus the following exceptions:</p> +<dl compact> +<dd></dd> +<dt>7.</dt> +<dd>The sequence (<i>keyword</i>) can occur before a format conversion specifier. The conversion argument is defined by the value +of <i>keyword</i>. The implementation shall support the following keywords: +<ul> +<li class="tent">Any of the Field Name entries in <a href="#tagtcjh_21">ustar Header Block</a> and <a href= +"#tagtcjh_22">Octet-Oriented cpio Archive Entry</a> . The implementation may support the <i>cpio</i> keywords without the leading +<b>c_</b> in addition to the form required by <a href="#tagtcjh_22">Octet-Oriented cpio Archive Entry</a> .</li> +<li class="tent">Any keyword defined for the extended header in <a href="#tag_20_94_13_03">pax Extended Header</a> .</li> +<li class="tent">Any keyword provided as an implementation-defined extension within the extended header defined in <a href= +"#tag_20_94_13_03">pax Extended Header</a> .</li> +</ul> +<p class="tent">For example, the sequence <tt>"%(charset)s"</tt> is the string value of the name of the character set in the +extended header.</p> +<p class="tent">The result of the keyword conversion argument shall be the value from the applicable header field or extended +header, without any trailing NULs.</p> +<p class="tent">All keyword values used as conversion arguments shall be translated from the UTF-8 encoding (or alternative +encoding specified by any <b>hdrcharset</b> extended header record) to the character set appropriate for the local file system, +user database, and so on, as applicable.</p> +</dd> +<dt>8.</dt> +<dd>An additional conversion specifier character, <tt>T</tt>, shall be used to specify time formats. The <tt>T</tt> conversion +specifier character can be preceded by the sequence (<i>keyword=</i><i>subformat</i>), where <i>subformat</i> is a date format as +defined by <a href="../utilities/date.html"><i>date</i></a> operands. The default <i>keyword</i> shall be <b>mtime</b> and the +default subformat shall be: +<pre> +<tt>%b %e %H:%M %Y +</tt></pre></dd> +<dt>9.</dt> +<dd>An additional conversion specifier character, <tt>M</tt>, shall be used to specify the file mode string as defined in <a href= +"../utilities/ls.html"><i>ls</i></a> Standard Output. If (<i>keyword</i>) is omitted, the <b>mode</b> keyword shall be used. For +example, <tt>%.1M</tt> writes the single character corresponding to the <<i>entry type</i>> field of the <a href= +"../utilities/ls.html"><i>ls</i></a> <b>-l</b> command.</dd> +<dt>10.</dt> +<dd>An additional conversion specifier character, <tt>D</tt>, shall be used to specify the device for block or special files, if +applicable, in an implementation-defined format. If not applicable, and (<i>keyword</i>) is specified, then this conversion shall +be equivalent to <tt>%(</tt><i>keyword</i><tt>)u</tt>. If not applicable, and (<i>keyword</i>) is omitted, then this conversion +shall be equivalent to <space>.</dd> +<dt>11.</dt> +<dd>An additional conversion specifier character, <tt>F</tt>, shall be used to specify a pathname. The <tt>F</tt> conversion +character can be preceded by a sequence of <comma>-separated keywords: +<pre> +<tt>(</tt><i>keyword</i><b>[</b><tt>,</tt><i>keyword</i><b>]</b><tt> ... ) +</tt></pre> +<p class="tent">The values for all the keywords that are non-null shall be concatenated together, each separated by a <tt>'/'</tt>. +The default shall be (<b>path</b>) if the keyword <b>path</b> is defined; otherwise, the default shall be +(<b>prefix</b>,<b>name</b>).</p> +</dd> +<dt>12.</dt> +<dd>An additional conversion specifier character, <tt>L</tt>, shall be used to specify a symbolic link expansion. If the current +file is a symbolic link, then <tt>%L</tt> shall expand to: +<pre> +<tt>"%s -> %s", <</tt><i>value of keyword</i><tt>>, <</tt><i>contents of link</i><tt>> +</tt></pre> +<p class="tent">Otherwise, the <tt>%L</tt> conversion specification shall be the equivalent of <tt>%F</tt>.</p> +</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_94_05" id="tag_20_94_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>directory</i></dt> +<dd>The destination directory pathname for <b>copy</b> mode.</dd> +<dt><i>file</i></dt> +<dd>A pathname of a file to be copied or archived.</dd> +<dt><i>pattern</i></dt> +<dd>A pattern matching one or more pathnames of archive members. A pattern needs to be given in the name-generating notation of the +pattern matching notation in <a href="../utilities/V3_chap02.html#tag_19_14"><i>2.14 Pattern Matching Notation</i></a> , including +the filename expansion rules in <a href="../utilities/V3_chap02.html#tag_19_14_03"><i>2.14.3 Patterns Used for Filename +Expansion</i></a> . The default, if no <i>pattern</i> is specified, is to select all members in the archive.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_94_06" id="tag_20_94_06"></a>STDIN</h4> +<blockquote> +<p>In <b>write</b> mode, the standard input shall be used only if no <i>file</i> operands are specified. It shall be a file +containing a list of pathnames, each terminated by a <newline> character.</p> +<p class="tent">In <b>list</b> and <b>read</b> modes, if <b>-f</b> is not specified, the standard input shall be an archive +file.</p> +<p class="tent">Otherwise, the standard input shall not be used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_94_07" id="tag_20_94_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input file named by the <i>archive</i> option-argument, or standard input when the archive is read from there, shall be a +file formatted according to one of the specifications in the EXTENDED DESCRIPTION section or some other implementation-defined +format.</p> +<p class="tent">The file <b>/dev/tty</b> shall be used to write prompts and read responses.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_94_08" id="tag_20_94_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>pax</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_COLLATE</i></dt> +<dd><br> +Determine the locale for the behavior of ranges, equivalence classes, and multi-character collating elements used in the pattern +matching expressions for the <i>pattern</i> operand and the basic regular expression for the <b>-s</b> option.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files), and the behavior of character classes used in the pattern matching +expressions for the <i>pattern</i> operand and the basic regular expression for the <b>-s</b> option.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale used to affect the format and contents of diagnostic messages and prompts written to standard error.</dd> +<dt><i>LC_TIME</i></dt> +<dd>Determine the format and contents of date and time strings when the <b>-v</b> option is specified.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>TMPDIR</i></dt> +<dd>Determine the pathname that provides part of the default global extended header record file, as described for the <b>-o</b> +<b>globexthdr=</b> keyword in the OPTIONS section.</dd> +<dt><i>TZ</i></dt> +<dd>Determine the timezone used to calculate date and time strings when the <b>-v</b> option is specified. If <i>TZ</i> is unset or +null, an unspecified default timezone shall be used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_94_09" id="tag_20_94_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_94_10" id="tag_20_94_10"></a>STDOUT</h4> +<blockquote> +<p>In <b>write</b> mode, if <b>-f</b> is not specified, the standard output shall be the archive formatted according to one of the +specifications in the EXTENDED DESCRIPTION section, or some other implementation-defined format (see <b>-x</b> <i>format</i>).</p> +<p class="tent">In <b>list</b> mode, when the <b>-o</b><b>listopt</b>=<i>format</i> has been specified, the selected archive +members shall be written to standard output using the format described under <a href="#tag_20_94_04_01">List Mode Format +Specifications</a> . In <b>list</b> mode without the <b>-o</b><b>listopt</b>=<i>format</i> option, the table of contents of the +selected archive members shall be written to standard output using the following format:</p> +<pre> +<tt>"%s\n", <</tt><i>pathname</i><tt>> +</tt></pre> +<p class="tent">If the <b>-v</b> option is specified in <b>list</b> mode, the table of contents of the selected archive members +shall be written to standard output using the following formats.</p> +<p class="tent">For pathnames representing hard links to previous members of the archive:</p> +<pre> +<tt>"%sΔ==Δ%s\n", <</tt><i>ls</i><tt> -l </tt><i>listing</i><tt>>, <</tt><i>linkname</i><tt>> +</tt></pre> +<p class="tent">For all other pathnames:</p> +<pre> +<tt>"%s\n", <</tt><i>ls</i><tt> -l </tt><i>listing</i><tt>> +</tt></pre> +<p class="tent">where <<i>ls </i>-l <i>listing</i>> shall be the format specified by the <a href= +"../utilities/ls.html"><i>ls</i></a> utility with the <b>-l</b> option. When writing pathnames in this format, it is unspecified +what is written for fields for which the underlying archive format does not have the correct information, although the correct +number of <blank>-separated fields shall be written.</p> +<p class="tent">In <b>list</b> mode, standard output shall not be buffered more than a pathname (plus any associated information +and a <newline> terminator) at a time.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_94_11" id="tag_20_94_11"></a>STDERR</h4> +<blockquote> +<p>If <b>-v</b> is specified in <b>read</b>, <b>write</b>, or <b>copy</b> modes, <i>pax</i> shall write the pathnames it processes +to the standard error output using the following format:</p> +<pre> +<tt>"%s\n", <</tt><i>pathname</i><tt>> +</tt></pre> +<p class="tent">These pathnames shall be written as soon as processing is begun on the file or archive member, and shall be flushed +to standard error. The trailing <newline>, which shall not be buffered, is written when the file has been read or +written.</p> +<p class="tent">If the <b>-s</b> option is specified, and the replacement string has a trailing <tt>'p'</tt>, substitutions shall +be written to standard error in the following format:</p> +<pre> +<tt>"%sΔ>>Δ%s\n", <</tt><i>original pathname</i><tt>>, <</tt><i>new pathname</i><tt>> +</tt></pre> +<p class="tent">In all operating modes of <i>pax</i>, optional messages of unspecified format concerning the input archive format +and volume number, the number of files, blocks, volumes, and media parts as well as other diagnostic messages may be written to +standard error.</p> +<p class="tent">In all formats, for both standard output and standard error, it is unspecified how non-printable characters in +pathnames or link names are written.</p> +<p class="tent">When using the <b>-x</b><b>pax</b> archive format, if a filename, link name, group name, owner name, or any other +field in an extended header record cannot be translated between the codeset in use for that extended header record and the +character set of the current locale, <i>pax</i> shall write a diagnostic message to standard error, shall process the file as +described for the <b>-o</b> <b>invalid=</b> option, and then shall continue processing with the next file.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_94_12" id="tag_20_94_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>In <b>read</b> mode, the extracted output files shall be of the archived file type. In <b>copy</b> mode, the copied output files +shall be the type of the file being copied. In either mode, existing files in the destination hierarchy shall be overwritten only +when all permission (<b>-p</b>), modification time (<b>-u</b>), and invalid-value (<b>-o</b><b>invalid=</b>) tests allow it.</p> +<p class="tent">In <b>write</b> mode, the output file named by the <b>-f</b> option-argument shall be a file formatted according to +one of the specifications in the EXTENDED DESCRIPTION section, or some other implementation-defined format.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_94_13" id="tag_20_94_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<h5><a name="tag_20_94_13_01" id="tag_20_94_13_01"></a>pax Interchange Format</h5> +<p class="tent">A <i>pax</i> archive tape or file produced in the <b>-x</b><b>pax</b> format shall contain a series of blocks. The +physical layout of the archive shall be identical to the <b>ustar</b> format described in <a href="#tag_20_94_13_06">ustar +Interchange Format</a> . Each file archived shall be represented by the following sequence:</p> +<ul> +<li class="tent">An optional header block with extended header records. This header block is of the form described in <a href= +"#tag_20_94_13_02">pax Header Block</a> , with a <i>typeflag</i> value of <b>x</b> or <b>g</b>. The extended header records, +described in <a href="#tag_20_94_13_03">pax Extended Header</a> , shall be included as the data for this header block.</li> +<li class="tent">A header block that describes the file. Any fields in the preceding optional extended header shall override the +associated fields in this header block for this file.</li> +<li class="tent">Zero or more blocks that contain the contents of the file.</li> +</ul> +<p class="tent">At the end of the archive file there shall be two 512-byte blocks filled with binary zeros, interpreted as an +end-of-archive indicator.</p> +<p class="tent">A schematic of an example archive with global extended header records and two actual files is shown in <a href= +"#tagfcjh_1">pax Format Archive Example</a> . In the example, the second file in the archive has no extended header preceding it, +presumably because it has no need for extended attributes.</p> +<dl compact> +<dd><img src=".././Figures/xcu-pax.gif"></dd> +</dl> +<p class="caption"><a name="tagfcjh_1" id="tagfcjh_1"></a> Figure: pax Format Archive Example</p> +<h5><a name="tag_20_94_13_02" id="tag_20_94_13_02"></a>pax Header Block</h5> +<p class="tent">The <b>pax</b> header block shall be identical to the <b>ustar</b> header block described in <a href= +"#tag_20_94_13_06">ustar Interchange Format</a> , except that two additional <i>typeflag</i> values are defined:</p> +<dl compact> +<dd></dd> +<dt><tt>x</tt></dt> +<dd>Represents extended header records for the following file in the archive (which shall have its own <b>ustar</b> header block). +The format of these extended header records shall be as described in <a href="#tag_20_94_13_03">pax Extended Header</a> .</dd> +<dt><tt>g</tt></dt> +<dd>Represents global extended header records for the following files in the archive. The format of these extended header records +shall be as described in <a href="#tag_20_94_13_03">pax Extended Header</a> . Each value shall affect all subsequent files that do +not override that value in their own extended header record and until another global extended header record is reached that +provides another value for the same field. The <i>typeflag</i> <b>g</b> global headers should not be used with interchange media +that could suffer partial data loss in transporting the archive.</dd> +</dl> +<p class="tent">For both of these types, the <i>size</i> field shall be the size of the extended header records in octets. The +other fields in the header block are not meaningful to this version of the <i>pax</i> utility. However, if this archive is read by +a <i>pax</i> utility conforming to the ISO POSIX-2:1993 standard, the header block fields are used to create a regular file +that contains the extended header records as data. Therefore, header block field values should be selected to provide reasonable +file access to this regular file.</p> +<p class="tent">A further difference from the <b>ustar</b> header block is that data blocks for files of <i>typeflag</i> 1 (the +digit one) (hard link) may be included, which means that the size field may be greater than zero. Archives created by <i>pax</i> +<b>-o</b> <b>linkdata</b> shall include these data blocks with the hard links.</p> +<h5><a name="tag_20_94_13_03" id="tag_20_94_13_03"></a>pax Extended Header</h5> +<p class="tent">A <b>pax</b> extended header contains values that are inappropriate for the <b>ustar</b> header block because of +limitations in that format: fields requiring a character encoding other than that described in the ISO/IEC 646:1991 standard, +fields representing file attributes not described in the <b>ustar</b> header, and fields whose format or length do not fit the +requirements of the <b>ustar</b> header. The values in an extended header add attributes to the following file (or files; see the +description of the <i>typeflag</i> <b>g</b> header block) or override values in the following header block(s), as indicated in the +following list of keywords.</p> +<p class="tent">An extended header shall consist of one or more records, each constructed as follows:</p> +<pre> +<tt>"%d %s=%s\n", <</tt><i>length</i><tt>>, <</tt><i>keyword</i><tt>>, <</tt><i>value</i><tt>> +</tt></pre> +<p class="tent">The extended header records shall be encoded according to the ISO/IEC 10646-1:2020 standard UTF-8 encoding. +The <<i>length</i>> field, <blank>, <equals-sign>, and <newline> shown shall be limited to the portable +character set, as encoded in UTF-8. The <<i>keyword</i>> fields can be any UTF-8 characters. The <<i>length</i>> field +shall be the decimal length of the extended header record in octets, including the trailing <newline>. If there is a +<b>hdrcharset</b> extended header in effect for a file, the <i>value</i> field for any <b>gname</b>, <b>linkpath</b>, <b>path</b>, +and <b>uname</b> extended header records shall be encoded using the character set specified by the <b>hdrcharset</b> extended +header record; otherwise, the <i>value</i> field shall be encoded using UTF-8. The <i>value</i> field for all other keywords +specified by POSIX.1-2024 shall be encoded using UTF-8.</p> +<p class="tent">The <<i>keyword</i>> field shall be one of the entries from the following list or a keyword provided as an +implementation extension. Keywords consisting entirely of lowercase letters, digits, and periods are reserved for future +standardization. A keyword shall not include an <equals-sign>. (In the following list, the notations "file(s)" or +"block(s)" is used to acknowledge that a keyword affects the following single file after a <i>typeflag</i> <b>x</b> extended +header, but possibly multiple files after <i>typeflag</i> <b>g</b>. Any requirements in the list for <i>pax</i> to include a record +when in <b>write</b> or <b>copy</b> mode shall apply only when such a record has not already been provided through the use of the +<b>-o</b> option. When used in <b>copy</b> mode, <i>pax</i> shall behave as if an archive had been created with applicable extended +header records and then extracted.)</p> +<dl compact> +<dd></dd> +<dt><b>atime</b></dt> +<dd>The file access time for the following file(s), equivalent to the value of the <i>st_atim</i> member of the <b>stat</b> +structure for a file, as described by the <a href="../functions/stat.html"><i>stat</i>()</a> function. The access time shall be +restored if the process has appropriate privileges required to do so. The format of the <<i>value</i>> shall be as described +in <a href="#tag_20_94_13_05">pax Extended Header File Times</a> .</dd> +<dt><b>charset</b></dt> +<dd>The name of the character set used to encode the data in the following file(s). The entries in the following table are defined +to refer to known standards; additional names may be agreed on between the originator and recipient. +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b><value></b></p> +</th> +<th align="center"> +<p class="tent"><b>Formal Standard</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">ISO-IRΔ646Δ1990</p> +</td> +<td align="left"> +<p class="tent">ISO/IEC 646:1990</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">ISO-IRΔ8859Δ1Δ1998</p> +</td> +<td align="left"> +<p class="tent">ISO/IEC 8859-1:1998</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">ISO-IRΔ8859Δ2Δ1999</p> +</td> +<td align="left"> +<p class="tent">ISO/IEC 8859-2:1999</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">ISO-IRΔ8859Δ3Δ1999</p> +</td> +<td align="left"> +<p class="tent">ISO/IEC 8859-3:1999</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">ISO-IRΔ8859Δ4Δ1998</p> +</td> +<td align="left"> +<p class="tent">ISO/IEC 8859-4:1998</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">ISO-IRΔ8859Δ5Δ1999</p> +</td> +<td align="left"> +<p class="tent">ISO/IEC 8859-5:1999</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">ISO-IRΔ8859Δ6Δ1999</p> +</td> +<td align="left"> +<p class="tent">ISO/IEC 8859-6:1999</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">ISO-IRΔ8859Δ7Δ1987</p> +</td> +<td align="left"> +<p class="tent">ISO/IEC 8859-7:1987</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">ISO-IRΔ8859Δ8Δ1999</p> +</td> +<td align="left"> +<p class="tent">ISO/IEC 8859-8:1999</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">ISO-IRΔ8859Δ9Δ1999</p> +</td> +<td align="left"> +<p class="tent">ISO/IEC 8859-9:1999</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">ISO-IRΔ8859Δ10Δ1998</p> +</td> +<td align="left"> +<p class="tent">ISO/IEC 8859-10:1998</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">ISO-IRΔ8859Δ13Δ1998</p> +</td> +<td align="left"> +<p class="tent">ISO/IEC 8859-13:1998</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">ISO-IRΔ8859Δ14Δ1998</p> +</td> +<td align="left"> +<p class="tent">ISO/IEC 8859-14:1998</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">ISO-IRΔ8859Δ15Δ1999</p> +</td> +<td align="left"> +<p class="tent">ISO/IEC 8859-15:1999</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">ISO-IRΔ10646Δ2000</p> +</td> +<td align="left"> +<p class="tent">ISO/IEC 10646:2000</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">ISO-IRΔ10646Δ2000ΔUTF-8</p> +</td> +<td align="left"> +<p class="tent">ISO/IEC 10646, UTF-8 encoding</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">BINARY</p> +</td> +<td align="left"> +<p class="tent">None.</p> +</td> +</tr> +</table> +</center> +<p class="tent">The encoding is included in an extended header for information only; when <i>pax</i> is used as described in +POSIX.1-2024, it shall not translate the file data into any other encoding. The <b>BINARY</b> entry indicates unencoded binary +data.</p> +<p class="tent">When used in <b>write</b> or <b>copy</b> mode, it is implementation-defined whether <i>pax</i> includes a +<b>charset</b> extended header record for a file.</p> +</dd> +<dt><b>comment</b></dt> +<dd>A series of characters used as a comment. All characters in the <<i>value</i>> field shall be ignored by <i>pax</i>.</dd> +<dt><b>gid</b></dt> +<dd>The group ID of the group that owns the file, expressed as a decimal number using digits from the ISO/IEC 646:1991 +standard. This record shall override the <i>gid</i> field in the following header block(s). When used in <b>write</b> or +<b>copy</b> mode, <i>pax</i> shall include a <i>gid</i> extended header record for each file whose group ID is greater than 2097151 +(octal 7777777).</dd> +<dt><b>gname</b></dt> +<dd>The group of the file(s), formatted as a group name in the group database. This record shall override the <i>gid</i> and +<i>gname</i> fields in the following header block(s), and any <i>gid</i> extended header record. When used in <b>read</b>, +<b>copy</b>, or <b>list</b> mode, <i>pax</i> shall translate the name from the encoding in the header record to the character set +appropriate for the group database on the receiving system. If any of the characters cannot be translated, and if neither the +<b>-o</b><b>invalid=UTF-8</b> option nor the <b>-o</b><b>invalid=binary</b> option is specified, the results are +implementation-defined. When used in <b>write</b> or <b>copy</b> mode, <i>pax</i> shall include a <b>gname</b> extended header +record for each file whose group name cannot be represented entirely with the letters and digits of the portable character +set.</dd> +<dt><b>hdrcharset</b></dt> +<dd>The name of the character set used to encode the value field of the <b>gname</b>, <b>linkpath</b>, <b>path</b>, and +<b>uname</b> <i>pax</i> extended header records. The entries in the following table are defined to refer to known standards; +additional names may be agreed between the originator and the recipient.<br> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b><value></b></p> +</th> +<th align="center"> +<p class="tent"><b>Formal Standard</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">ISO-IRΔ10646Δ2000ΔUTF-8</p> +</td> +<td align="left"> +<p class="tent">ISO/IEC 10646, UTF-8 encoding</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">BINARY</p> +</td> +<td align="left"> +<p class="tent">None.</p> +</td> +</tr> +</table> +</center> +<p class="tent">If no <b>hdrcharset</b> extended header record is specified, the default character set used to encode all values in +extended header records shall be the ISO/IEC 10646-1:2020 standard UTF-8 encoding.</p> +<p class="tent">The <b>BINARY</b> entry indicates that all values recorded in extended headers for affected files are unencoded +binary data from the underlying system.</p> +</dd> +<dt><b>linkpath</b></dt> +<dd>The pathname of a link being created to another file, of any type, previously archived. This record shall override the +<i>linkname</i> field in the following <b>ustar</b> header block(s). The following <b>ustar</b> header block shall determine the +type of link created. If <i>typeflag</i> of the following header block is 1, it shall be a hard link. If <i>typeflag</i> is 2, it +shall be a symbolic link and the <b>linkpath</b> value shall be the contents of the symbolic link. The <i>pax</i> utility shall +translate the name of the link (contents of the symbolic link) from the encoding in the header to the character set appropriate for +the local file system. When used in <b>write</b> or <b>copy</b> mode, <i>pax</i> shall include a <b>linkpath</b> extended header +record for each link whose pathname cannot be represented entirely with the members of the portable character set other than +NUL.</dd> +<dt><b>mtime</b></dt> +<dd>The file modification time of the following file(s), equivalent to the value of the <i>st_mtim</i> member of the <b>stat</b> +structure for a file, as described in the <a href="../functions/stat.html"><i>stat</i>()</a> function. This record shall override +the <i>mtime</i> field in the following header block(s). The modification time shall be restored if the process has appropriate +privileges required to do so. The format of the <<i>value</i>> shall be as described in <a href="#tag_20_94_13_05">pax +Extended Header File Times</a> .</dd> +<dt><b>path</b></dt> +<dd>The pathname of the following file(s). This record shall override the <i>name</i> and <i>prefix</i> fields in the following +header block(s). The <i>pax</i> utility shall translate the pathname of the file from the encoding in the header to the character +set appropriate for the local file system. +<p class="tent">When used in <b>write</b> or <b>copy</b> mode, <i>pax</i> shall include a <i>path</i> extended header record for +each file whose pathname cannot be represented entirely with the members of the portable character set other than NUL.</p> +</dd> +<dt><b>realtime.</b><i>any</i></dt> +<dd>The keywords prefixed by "realtime." are reserved for future standardization.</dd> +<dt><b>security.</b><i>any</i></dt> +<dd>The keywords prefixed by "security." are reserved for future standardization.</dd> +<dt><b>size</b></dt> +<dd>The size of the file in octets, expressed as a decimal number using digits from the ISO/IEC 646:1991 standard. This record +shall override the <i>size</i> field in the following header block(s). When used in <b>write</b> or <b>copy</b> mode, <i>pax</i> +shall include a <i>size</i> extended header record for each file with a size value greater than 8589934591 (octal +77777777777).</dd> +<dt><b>uid</b></dt> +<dd>The user ID of the file owner, expressed as a decimal number using digits from the ISO/IEC 646:1991 standard. This record +shall override the <i>uid</i> field in the following header block(s). When used in <b>write</b> or <b>copy</b> mode, <i>pax</i> +shall include a <i>uid</i> extended header record for each file whose owner ID is greater than 2097151 (octal 7777777).</dd> +<dt><b>uname</b></dt> +<dd>The owner of the following file(s), formatted as a user name in the user database. This record shall override the <i>uid</i> +and <i>uname</i> fields in the following header block(s), and any <i>uid</i> extended header record. When used in <b>read</b>, +<b>copy</b>, or <b>list</b> mode, <i>pax</i> shall translate the name from the encoding in the header record to the character set +appropriate for the user database on the receiving system. If any of the characters cannot be translated, and if neither the +<b>-o</b><b>invalid=UTF-8</b> option nor the <b>-o</b><b>invalid=binary</b> option is specified, the results are +implementation-defined. When used in <b>write</b> or <b>copy</b> mode, <i>pax</i> shall include a <b>uname</b> extended header +record for each file whose user name cannot be represented entirely with the letters and digits of the portable character set.</dd> +</dl> +<p class="tent">If the <<i>value</i>> field is zero length, it shall delete any header block field, previously entered +extended header value, or global extended header value of the same name.</p> +<p class="tent">If a keyword in an extended header record (or in a <b>-o</b> option-argument) overrides or deletes a corresponding +field in the <b>ustar</b> header block, <i>pax</i> shall ignore the contents of that header block field.</p> +<p class="tent">Unlike the <b>ustar</b> header block fields, NULs shall not delimit <<i>value</i>>s; all characters within +the <<i>value</i>> field shall be considered data for the field. None of the length limitations of the <b>ustar</b> header +block fields in <a href="#tagtcjh_21">ustar Header Block</a> shall apply to the extended header records.</p> +<h5><a name="tag_20_94_13_04" id="tag_20_94_13_04"></a>pax Extended Header Keyword Precedence</h5> +<p class="tent">This section describes the precedence in which the various header records and fields and command line options are +selected to apply to a file in the archive. When <i>pax</i> is used in <b>read</b> or <b>list</b> modes, it shall determine a file +attribute in the following sequence:</p> +<ol> +<li class="tent">If <b>-o</b><b>delete=keyword-prefix</b> is used, the affected attributes shall be determined from step 7., if +applicable, or ignored otherwise.</li> +<li class="tent">If <b>-o</b><i>keyword</i>:= is used, the affected attributes shall be ignored.</li> +<li class="tent">If <b>-o</b><b>keyword:=value</b> is used, the affected attribute shall be assigned the value.</li> +<li class="tent">If there is a <i>typeflag</i> <b>x</b> extended header record, the affected attribute shall be assigned the +<<i>value</i>>. When extended header records conflict, the last one given in the header shall take precedence.</li> +<li class="tent">If <b>-o</b><b>keyword=value</b> is used, the affected attribute shall be assigned the value.</li> +<li class="tent">If there is a <i>typeflag</i> <b>g</b> global extended header record, the affected attribute shall be assigned the +<<i>value</i>>. When global extended header records conflict, the last one given in the global header shall take +precedence.</li> +<li class="tent">Otherwise, the attribute shall be determined from the <b>ustar</b> header block.</li> +</ol> +<h5><a name="tag_20_94_13_05" id="tag_20_94_13_05"></a>pax Extended Header File Times</h5> +<p class="tent">The <i>pax</i> utility shall write an <b>mtime</b> record for each file in <b>write</b> or <b>copy</b> modes if the +file's modification time cannot be represented exactly in the <b>ustar</b> header logical record described in <a href= +"#tag_20_94_13_06">ustar Interchange Format</a> . This can occur if the time is out of <b>ustar</b> range, or if the file system of +the underlying implementation supports non-integer time granularities and the time is not an integer. All of these time records +shall be formatted as a decimal representation of the time in seconds since the Epoch. If a <period> (<tt>'.'</tt>) decimal +point character is present, the digits to the right of the point shall represent the units of a subsecond timing granularity, where +the first digit is tenths of a second and each subsequent digit is a tenth of the previous digit. In <b>read</b> or <b>copy</b> +mode, the <i>pax</i> utility shall truncate the time of a file to the greatest value that is not greater than the input header file +time. In <b>write</b> or <b>copy</b> mode, the <i>pax</i> utility shall output a time exactly if it can be represented exactly as a +decimal number, and otherwise shall generate only enough digits so that the same time shall be recovered if the file is extracted +on a system whose underlying implementation supports the same time granularity.</p> +<h5><a name="tag_20_94_13_06" id="tag_20_94_13_06"></a>ustar Interchange Format</h5> +<p class="tent">A <b>ustar</b> archive tape or file shall contain a series of logical records. Each logical record shall be a +fixed-size logical record of 512 octets (see below). Although this format may be thought of as being stored on 9-track +industry-standard 12.7 mm (0.5 in) magnetic tape, other types of transportable media are not excluded. Each file archived shall be +represented by a header logical record that describes the file, followed by zero or more logical records that give the contents of +the file. At the end of the archive file there shall be two 512-octet logical records filled with binary zeros, interpreted as an +end-of-archive indicator.</p> +<p class="tent">The logical records may be grouped for physical I/O operations, as described under the <b>-b</b><i>blocksize</i> +and <b>-x</b> <b>ustar</b> options. Each group of logical records may be written with a single operation equivalent to the <a href= +"../functions/write.html"><i>write</i>()</a> function. On magnetic tape, the result of this write shall be a single tape physical +block. The last physical block shall always be the full size, so logical records after the two zero logical records may contain +undefined data.</p> +<p class="tent">The header logical record shall be structured as shown in the following table. All lengths and offsets are in +decimal.<br></p> +<p class="caption"><a name="tagtcjh_21" id="tagtcjh_21"></a> Table: ustar Header Block</p> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Field Name</b></p> +</th> +<th align="center"> +<p class="tent"><b>Octet Offset</b></p> +</th> +<th align="center"> +<p class="tent"><b>Length (in Octets)</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>name</i></p> +</td> +<td align="left"> +<p class="tent">0</p> +</td> +<td align="left"> +<p class="tent">100</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>mode</i></p> +</td> +<td align="left"> +<p class="tent">100</p> +</td> +<td align="left"> +<p class="tent">8</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>uid</i></p> +</td> +<td align="left"> +<p class="tent">108</p> +</td> +<td align="left"> +<p class="tent">8</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>gid</i></p> +</td> +<td align="left"> +<p class="tent">116</p> +</td> +<td align="left"> +<p class="tent">8</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>size</i></p> +</td> +<td align="left"> +<p class="tent">124</p> +</td> +<td align="left"> +<p class="tent">12</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>mtime</i></p> +</td> +<td align="left"> +<p class="tent">136</p> +</td> +<td align="left"> +<p class="tent">12</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>chksum</i></p> +</td> +<td align="left"> +<p class="tent">148</p> +</td> +<td align="left"> +<p class="tent">8</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>typeflag</i></p> +</td> +<td align="left"> +<p class="tent">156</p> +</td> +<td align="left"> +<p class="tent">1</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>linkname</i></p> +</td> +<td align="left"> +<p class="tent">157</p> +</td> +<td align="left"> +<p class="tent">100</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>magic</i></p> +</td> +<td align="left"> +<p class="tent">257</p> +</td> +<td align="left"> +<p class="tent">6</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>version</i></p> +</td> +<td align="left"> +<p class="tent">263</p> +</td> +<td align="left"> +<p class="tent">2</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>uname</i></p> +</td> +<td align="left"> +<p class="tent">265</p> +</td> +<td align="left"> +<p class="tent">32</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>gname</i></p> +</td> +<td align="left"> +<p class="tent">297</p> +</td> +<td align="left"> +<p class="tent">32</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>devmajor</i></p> +</td> +<td align="left"> +<p class="tent">329</p> +</td> +<td align="left"> +<p class="tent">8</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>devminor</i></p> +</td> +<td align="left"> +<p class="tent">337</p> +</td> +<td align="left"> +<p class="tent">8</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>prefix</i></p> +</td> +<td align="left"> +<p class="tent">345</p> +</td> +<td align="left"> +<p class="tent">155</p> +</td> +</tr> +</table> +</center> +<p class="tent">All characters in the header logical record shall be represented in the coded character set of the +ISO/IEC 646:1991 standard. For maximum portability between implementations, names should be selected from characters +represented by the portable filename character set as octets with the most significant bit zero. If an implementation supports the +use of characters outside of <slash> and the portable filename character set in names for files, users, and groups, one or +more implementation-defined encodings of these characters shall be provided for interchange purposes.</p> +<p class="tent">However, the <i>pax</i> utility shall never create filenames on the local system that cannot be accessed via the +procedures described in POSIX.1-2024. If a filename is found on the medium that would create an invalid filename, it is +implementation-defined whether the data from the file is stored on the file hierarchy and under what name it is stored. The +<i>pax</i> utility may choose to ignore these files as long as it produces an error indicating that the file is being ignored.</p> +<p class="tent">Each field within the header logical record is contiguous; that is, there is no padding used. Each character on the +archive medium shall be stored contiguously.</p> +<p class="tent">The fields <i>magic</i>, <i>uname</i>, and <i>gname</i> are character strings each terminated by a NUL character. +The fields <i>name</i>, <i>linkname</i>, and <i>prefix</i> are NUL-terminated character strings except when all characters in the +array contain non-NUL characters including the last character. The <i>version</i> field is two octets containing the characters +<tt>"00"</tt> (zero-zero). The <i>typeflag</i> contains a single character. All other fields are leading zero-filled octal numbers +using digits from the ISO/IEC 646:1991 standard IRV. Each numeric field is terminated by one or more <space> or NUL +characters.</p> +<p class="tent">The <i>name</i> and the <i>prefix</i> fields shall produce the pathname of the file. A new pathname shall be +formed, if <i>prefix</i> is not an empty string (its first character is not NUL), by concatenating <i>prefix</i> (up to the first +NUL character), a <slash> character, and <i>name</i>; otherwise, <i>name</i> is used alone. In either case, <i>name</i> is +terminated at the first NUL character. If <i>prefix</i> begins with a NUL character, it shall be ignored. In this manner, pathnames +of at most 256 characters can be supported. If a pathname does not fit in the space provided, <i>pax</i> shall notify the user of +the error, and shall not store any part of the file—header or data—on the medium.</p> +<p class="tent">The <i>linkname</i> field, described below, shall not use the <i>prefix</i> to produce a pathname. As such, a +<i>linkname</i> is limited to 100 characters. If the name does not fit in the space provided, <i>pax</i> shall notify the user of +the error, and shall not attempt to store the link on the medium.</p> +<p class="tent">The <i>mode</i> field provides 12 bits encoded in the ISO/IEC 646:1991 standard octal digit representation. +The encoded bits shall represent the following values:<br></p> +<p class="caption">Table: ustar <i>mode</i> Field</p> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Bit Value</b></p> +</th> +<th align="center"> +<p class="tent"><b>POSIX.1-2024 Bit</b></p> +</th> +<th align="center"> +<p class="tent"><b>Description</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">04000</p> +</td> +<td align="left"> +<p class="tent">S_ISUID</p> +</td> +<td align="left"> +<p class="tent">Set UID on execution.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">02000</p> +</td> +<td align="left"> +<p class="tent">S_ISGID</p> +</td> +<td align="left"> +<p class="tent">Set GID on execution.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">01000</p> +</td> +<td align="left"> +<p class="tent"><reserved></p> +</td> +<td align="left"> +<p class="tent">Reserved for future standardization.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">00400</p> +</td> +<td align="left"> +<p class="tent">S_IRUSR</p> +</td> +<td align="left"> +<p class="tent">Read permission for file owner class.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">00200</p> +</td> +<td align="left"> +<p class="tent">S_IWUSR</p> +</td> +<td align="left"> +<p class="tent">Write permission for file owner class.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">00100</p> +</td> +<td align="left"> +<p class="tent">S_IXUSR</p> +</td> +<td align="left"> +<p class="tent">Execute/search permission for file owner class.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">00040</p> +</td> +<td align="left"> +<p class="tent">S_IRGRP</p> +</td> +<td align="left"> +<p class="tent">Read permission for file group class.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">00020</p> +</td> +<td align="left"> +<p class="tent">S_IWGRP</p> +</td> +<td align="left"> +<p class="tent">Write permission for file group class.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">00010</p> +</td> +<td align="left"> +<p class="tent">S_IXGRP</p> +</td> +<td align="left"> +<p class="tent">Execute/search permission for file group class.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">00004</p> +</td> +<td align="left"> +<p class="tent">S_IROTH</p> +</td> +<td align="left"> +<p class="tent">Read permission for file other class.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">00002</p> +</td> +<td align="left"> +<p class="tent">S_IWOTH</p> +</td> +<td align="left"> +<p class="tent">Write permission for file other class.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">00001</p> +</td> +<td align="left"> +<p class="tent">S_IXOTH</p> +</td> +<td align="left"> +<p class="tent">Execute/search permission for file other class.</p> +</td> +</tr> +</table> +</center> +<p class="tent">When appropriate privileges are required to set one of these mode bits, and the user restoring the files from the +archive does not have appropriate privileges, the mode bits for which the user does not have appropriate privileges shall be +ignored. Some of the mode bits in the archive format are not mentioned elsewhere in this volume of POSIX.1-2024. If the +implementation does not support those bits, they may be ignored.</p> +<p class="tent">The <i>uid</i> and <i>gid</i> fields are the user and group ID of the owner and group of the file, +respectively.</p> +<p class="tent">The <i>size</i> field is the size of the file in octets. If the <i>typeflag</i> field is set to specify a file to +be of type 1 (a hard link) or 2 (a symbolic link), the <i>size</i> field shall be specified as zero. If the <i>typeflag</i> field +is set to specify a file of type 5 (directory), the <i>size</i> field shall be interpreted as described under the definition of +that record type. No data logical records are stored for types 1, 2, or 5. If the <i>typeflag</i> field is set to 3 (character +special file), 4 (block special file), or 6 (FIFO), the meaning of the <i>size</i> field is unspecified by this volume of +POSIX.1-2024, and no data logical records shall be stored on the medium. Additionally, for type 6, the <i>size</i> field shall be +ignored when reading. If the <i>typeflag</i> field is set to any other value, the number of logical records written following the +header shall be (<i>size</i>+511)/512, ignoring any fraction in the result of the division.</p> +<p class="tent">The <i>mtime</i> field shall be the modification time of the file at the time it was archived. It is the +ISO/IEC 646:1991 standard representation of the octal value of the modification time obtained from the <a href= +"../functions/stat.html"><i>stat</i>()</a> function.</p> +<p class="tent">The <i>chksum</i> field shall be the ISO/IEC 646:1991 standard IRV representation of the octal value of the +simple sum of all octets in the header logical record. Each octet in the header shall be treated as an unsigned value. These values +shall be added to an unsigned integer, initialized to zero, the precision of which is not less than 17 bits. When calculating the +checksum, the <i>chksum</i> field is treated as if it were all <space> characters.</p> +<p class="tent">The <i>typeflag</i> field specifies the type of file archived. If a particular implementation does not recognize +the type, or the user does not have appropriate privileges to create that type, the file shall be extracted as if it were a regular +file if the file type is defined to have a meaning for the <i>size</i> field that could cause data logical records to be written on +the medium (see the previous description for <i>size</i>). If conversion to a regular file occurs, the <i>pax</i> utility shall +produce an error indicating that the conversion took place. All of the <i>typeflag</i> fields shall be coded in the +ISO/IEC 646:1991 standard IRV:</p> +<dl compact> +<dd></dd> +<dt><tt>0</tt></dt> +<dd>Represents a regular file. For backwards-compatibility, a <i>typeflag</i> value of binary zero (<tt>'\0'</tt>) should be +recognized as meaning a regular file when extracting files from the archive. Archives written with this version of the archive file +format create regular files with a <i>typeflag</i> value of the ISO/IEC 646:1991 standard IRV <tt>'0'</tt>.</dd> +<dt><tt>1</tt></dt> +<dd>Represents a file linked to another file, of any type, previously archived. Such files are identified by having the same device +and file serial numbers, and pathnames that refer to different directory entries. All such files shall be archived as linked files. +The linked-to name is specified in the <i>linkname</i> field with a NUL-character terminator if it is less than 100 octets in +length.</dd> +<dt><tt>2</tt></dt> +<dd>Represents a symbolic link. The contents of the symbolic link shall be stored in the <i>linkname</i> field.</dd> +<dt><tt>3,4</tt></dt> +<dd>Represent character special files and block special files respectively. In this case the <i>devmajor</i> and <i>devminor</i> +fields shall contain information defining the device, the format of which is unspecified by this volume of POSIX.1-2024. +Implementations may map the device specifications to their own local specification or may ignore the entry.</dd> +<dt><tt>5</tt></dt> +<dd>Specifies a directory or subdirectory. On systems where disk allocation is performed on a directory basis, the <i>size</i> +field shall contain the maximum number of octets (which may be rounded to the nearest disk block allocation unit) that the +directory may hold. A <i>size</i> field of zero indicates no such limiting. Systems that do not support limiting in this manner +should ignore the <i>size</i> field.</dd> +<dt><tt>6</tt></dt> +<dd>Specifies a FIFO special file. Note that the archiving of a FIFO file archives the existence of this file and not its +contents.</dd> +<dt><tt>7</tt></dt> +<dd>Reserved to represent a file to which an implementation has associated some high-performance attribute. Implementations without +such extensions should treat this file as a regular file (type 0).</dd> +<dt><tt>A-Z</tt></dt> +<dd>The letters <tt>'A'</tt> to <tt>'Z'</tt>, inclusive, are reserved for custom implementations. All other values are reserved for +future versions of this standard.</dd> +</dl> +<p class="tent">It is unspecified whether files with pathnames that refer to the same directory entry are archived as linked files +or as separate files. If they are archived as linked files, this means that attempting to extract both pathnames from the resulting +archive always causes an error (unless the <b>-u</b> option is used) because the link cannot be created.</p> +<p class="tent">It is unspecified whether files with the same device and file serial numbers being appended to an archive are +treated as linked files to members that were in the archive before the append.</p> +<p class="tent">Attempts to archive a socket shall produce a diagnostic message when <b>ustar</b> interchange format is used, but +may be allowed when <b>pax</b> interchange format is used. Handling of other file types is implementation-defined.</p> +<p class="tent">The <i>magic</i> field is the specification that this archive was output in this archive format. If this field +contains <b>ustar</b> (the five characters from the ISO/IEC 646:1991 standard IRV shown followed by NUL), the <i>uname</i> and +<i>gname</i> fields shall contain the ISO/IEC 646:1991 standard IRV representation of the owner and group of the file, +respectively (truncated to fit, if necessary). When the file is restored by a privileged, protection-preserving version of the +utility, the user and group databases shall be scanned for these names. If found, the user and group IDs contained within these +files shall be used rather than the values contained within the <i>uid</i> and <i>gid</i> fields.</p> +<h5><a name="tag_20_94_13_07" id="tag_20_94_13_07"></a>cpio Interchange Format</h5> +<p class="tent">The octet-oriented <b>cpio</b> archive format shall be a series of entries, each comprising a header that describes +the file, the name of the file, and then the contents of the file.</p> +<p class="tent">An archive may be recorded as a series of fixed-size blocks of octets. This blocking shall be used only to make +physical I/O more efficient. The last group of blocks shall always be at the full size.</p> +<p class="tent">For the octet-oriented <b>cpio</b> archive format, the individual entry information shall be in the order indicated +and described by the following table; see also the <a href="../basedefs/cpio.h.html"><i><cpio.h></i></a> header.<br></p> +<p class="caption"><a name="tagtcjh_22" id="tagtcjh_22"></a> Table: Octet-Oriented cpio Archive Entry</p> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Header Field Name</b></p> +</th> +<th align="center"> +<p class="tent"><b>Length (in Octets)</b></p> +</th> +<th align="center"> +<p class="tent"><b>Interpreted as</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>c_magic</i></p> +</td> +<td align="left"> +<p class="tent">6</p> +</td> +<td align="left"> +<p class="tent">Octal number</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>c_dev</i></p> +</td> +<td align="left"> +<p class="tent">6</p> +</td> +<td align="left"> +<p class="tent">Octal number</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>c_ino</i></p> +</td> +<td align="left"> +<p class="tent">6</p> +</td> +<td align="left"> +<p class="tent">Octal number</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>c_mode</i></p> +</td> +<td align="left"> +<p class="tent">6</p> +</td> +<td align="left"> +<p class="tent">Octal number</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>c_uid</i></p> +</td> +<td align="left"> +<p class="tent">6</p> +</td> +<td align="left"> +<p class="tent">Octal number</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>c_gid</i></p> +</td> +<td align="left"> +<p class="tent">6</p> +</td> +<td align="left"> +<p class="tent">Octal number</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>c_nlink</i></p> +</td> +<td align="left"> +<p class="tent">6</p> +</td> +<td align="left"> +<p class="tent">Octal number</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>c_rdev</i></p> +</td> +<td align="left"> +<p class="tent">6</p> +</td> +<td align="left"> +<p class="tent">Octal number</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>c_mtime</i></p> +</td> +<td align="left"> +<p class="tent">11</p> +</td> +<td align="left"> +<p class="tent">Octal number</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>c_namesize</i></p> +</td> +<td align="left"> +<p class="tent">6</p> +</td> +<td align="left"> +<p class="tent">Octal number</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>c_filesize</i></p> +</td> +<td align="left"> +<p class="tent">11</p> +</td> +<td align="left"> +<p class="tent">Octal number</p> +</td> +</tr> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Filename Field Name</b></p> +</th> +<th align="center"> +<p class="tent"><b>Length</b></p> +</th> +<th align="center"> +<p class="tent"><b>Interpreted as</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>c_name</i></p> +</td> +<td align="left"> +<p class="tent"><i>c_namesize</i></p> +</td> +<td align="left"> +<p class="tent">Pathname string</p> +</td> +</tr> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>File Data Field Name</b></p> +</th> +<th align="center"> +<p class="tent"><b>Length</b></p> +</th> +<th align="center"> +<p class="tent"><b>Interpreted as</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><i>c_filedata</i></p> +</td> +<td align="left"> +<p class="tent"><i>c_filesize</i></p> +</td> +<td align="left"> +<p class="tent">Data</p> +</td> +</tr> +</table> +</center> +<h5><a name="tag_20_94_13_08" id="tag_20_94_13_08"></a>cpio Header</h5> +<p class="tent">For each file in the archive, a header as defined previously shall be written. The information in the header fields +is written as streams of the ISO/IEC 646:1991 standard characters interpreted as octal numbers. The octal numbers shall be +extended to the necessary length by appending the ISO/IEC 646:1991 standard IRV zeros at the most-significant-digit end of the +number; the result is written to the most-significant digit of the stream of octets first. The fields shall be interpreted as +follows:</p> +<dl compact> +<dd></dd> +<dt><i>c_magic</i></dt> +<dd>Identify the archive as being a transportable archive by containing the identifying value <tt>"070707"</tt>.</dd> +<dt><i>c_dev</i>, <i>c_ino</i></dt> +<dd>Contains values that uniquely identify the file within the archive (that is, no files contain the same pair of <i>c_dev</i> and +<i>c_ino</i> values unless they are links to the same file). The values shall be determined in an unspecified manner.</dd> +<dt><i>c_mode</i></dt> +<dd>Contains the file type and access permissions as defined in the following table.<br> +<p class="caption"><a name="tagtcjh_23" id="tagtcjh_23"></a> Table: Values for cpio c_mode Field</p> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>File Permissions Name</b></p> +</th> +<th align="center"> +<p class="tent"><b>Value</b></p> +</th> +<th align="center"> +<p class="tent"><b>Indicates</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">C_IRUSR</p> +</td> +<td align="left"> +<p class="tent">000400</p> +</td> +<td align="left"> +<p class="tent">Read by owner</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">C_IWUSR</p> +</td> +<td align="left"> +<p class="tent">000200</p> +</td> +<td align="left"> +<p class="tent">Write by owner</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">C_IXUSR</p> +</td> +<td align="left"> +<p class="tent">000100</p> +</td> +<td align="left"> +<p class="tent">Execute by owner</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">C_IRGRP</p> +</td> +<td align="left"> +<p class="tent">000040</p> +</td> +<td align="left"> +<p class="tent">Read by group</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">C_IWGRP</p> +</td> +<td align="left"> +<p class="tent">000020</p> +</td> +<td align="left"> +<p class="tent">Write by group</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">C_IXGRP</p> +</td> +<td align="left"> +<p class="tent">000010</p> +</td> +<td align="left"> +<p class="tent">Execute by group</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">C_IROTH</p> +</td> +<td align="left"> +<p class="tent">000004</p> +</td> +<td align="left"> +<p class="tent">Read by others</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">C_IWOTH</p> +</td> +<td align="left"> +<p class="tent">000002</p> +</td> +<td align="left"> +<p class="tent">Write by others</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">C_IXOTH</p> +</td> +<td align="left"> +<p class="tent">000001</p> +</td> +<td align="left"> +<p class="tent">Execute by others</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">C_ISUID</p> +</td> +<td align="left"> +<p class="tent">004000</p> +</td> +<td align="left"> +<p class="tent">Set <i>uid</i></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">C_ISGID</p> +</td> +<td align="left"> +<p class="tent">002000</p> +</td> +<td align="left"> +<p class="tent">Set <i>gid</i></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">C_ISVTX</p> +</td> +<td align="left"> +<p class="tent">001000</p> +</td> +<td align="left"> +<p class="tent">Reserved</p> +</td> +</tr> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>File Type Name</b></p> +</th> +<th align="center"> +<p class="tent"><b>Value</b></p> +</th> +<th align="center"> +<p class="tent"><b>Indicates</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">C_ISDIR</p> +</td> +<td align="left"> +<p class="tent">040000</p> +</td> +<td align="left"> +<p class="tent">Directory</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">C_ISFIFO</p> +</td> +<td align="left"> +<p class="tent">010000</p> +</td> +<td align="left"> +<p class="tent">FIFO</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">C_ISREG</p> +</td> +<td align="left"> +<p class="tent">0100000</p> +</td> +<td align="left"> +<p class="tent">Regular file</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">C_ISLNK</p> +</td> +<td align="left"> +<p class="tent">0120000</p> +</td> +<td align="left"> +<p class="tent">Symbolic link</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">C_ISBLK</p> +</td> +<td align="left"> +<p class="tent">060000</p> +</td> +<td align="left"> +<p class="tent">Block special file</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">C_ISCHR</p> +</td> +<td align="left"> +<p class="tent">020000</p> +</td> +<td align="left"> +<p class="tent">Character special file</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">C_ISSOCK</p> +</td> +<td align="left"> +<p class="tent">0140000</p> +</td> +<td align="left"> +<p class="tent">Socket</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">C_ISCTG</p> +</td> +<td align="left"> +<p class="tent">0110000</p> +</td> +<td align="left"> +<p class="tent">Reserved</p> +</td> +</tr> +</table> +</center> +<p class="tent">Directories, FIFOs, symbolic links, and regular files shall be supported on a system conforming to this volume of +POSIX.1-2024; additional values defined previously are reserved for compatibility with existing systems. Additional file types may +be supported; however, such files should not be written to archives intended to be transported to other systems.</p> +</dd> +<dt><i>c_uid</i></dt> +<dd>Contains the user ID of the owner.</dd> +<dt><i>c_gid</i></dt> +<dd>Contains the group ID of the group.</dd> +<dt><i>c_nlink</i></dt> +<dd>Contains a number greater than or equal to the number of links in the archive referencing the file. If the <b>-a</b> option is +used to append to a <i>cpio</i> archive, then the <i>pax</i> utility need not account for the files in the existing part of the +archive when calculating the <i>c_nlink</i> values for the appended part of the archive, and need not alter the <i>c_nlink</i> +values in the existing part of the archive if additional files with the same <i>c_dev</i> and <i>c_ino</i> values are appended to +the archive.</dd> +<dt><i>c_rdev</i></dt> +<dd>Contains implementation-defined information for character or block special files.</dd> +<dt><i>c_mtime</i></dt> +<dd>Contains the latest time of modification of the file at the time the archive was created.</dd> +<dt><i>c_namesize</i></dt> +<dd>Contains the length of the pathname, including the terminating NUL character.</dd> +<dt><i>c_filesize</i></dt> +<dd>Contains the length in octets of the data section following the header structure.</dd> +</dl> +<h5><a name="tag_20_94_13_09" id="tag_20_94_13_09"></a>cpio Filename</h5> +<p class="tent">The <i>c_name</i> field shall contain the pathname of the file. The length of this field in octets is the value of +<i>c_namesize</i>.</p> +<p class="tent">If a filename is found on the medium that would create an invalid pathname, it is implementation-defined whether +the data from the file is stored on the file hierarchy and under what name it is stored.</p> +<p class="tent">All characters shall be represented in the ISO/IEC 646:1991 standard IRV. For maximum portability between +implementations, names should be selected from characters represented by the portable filename character set as octets with the +most significant bit zero. If an implementation supports the use of characters outside the portable filename character set in names +for files, users, and groups, one or more implementation-defined encodings of these characters shall be provided for interchange +purposes. However, the <i>pax</i> utility shall never create filenames on the local system that cannot be accessed via the +procedures described previously in this volume of POSIX.1-2024. If a filename is found on the medium that would create an invalid +filename, it is implementation-defined whether the data from the file is stored on the local file system and under what name it is +stored. The <i>pax</i> utility may choose to ignore these files as long as it produces an error indicating that the file is being +ignored.</p> +<h5><a name="tag_20_94_13_10" id="tag_20_94_13_10"></a>cpio File Data</h5> +<p class="tent">Following <i>c_name</i>, there shall be <i>c_filesize</i> octets of data. Interpretation of such data occurs in a +manner dependent on the file. For regular files, the data shall consist of the contents of the file. For symbolic links, the data +shall consist of the contents of the symbolic link. If <i>c_filesize</i> is zero, no data shall be contained in +<i>c_filedata</i>.</p> +<p class="tent">When restoring from an archive:</p> +<ul> +<li class="tent">If the user does not have appropriate privileges to create a file of the specified type, <i>pax</i> shall ignore +the entry and write an error message to standard error.</li> +<li class="tent">Only regular files and symbolic links have data to be restored. Presuming a regular file meets any selection +criteria that might be imposed on the format-reading utility by the user, such data shall be restored.</li> +<li class="tent">If a user does not have appropriate privileges to set a particular mode flag, the flag shall be ignored. Some of +the mode flags in the archive format are not mentioned elsewhere in this volume of POSIX.1-2024. If the implementation does not +support those flags, they may be ignored.</li> +</ul> +<h5><a name="tag_20_94_13_11" id="tag_20_94_13_11"></a>cpio Special Entries</h5> +<p class="tent">FIFO special files, directories, and the trailer shall be recorded with <i>c_filesize</i> equal to zero. Symbolic +links shall be recorded with <i>c_filesize</i> equal to the length of the contents of the symbolic link. For other special files, +<i>c_filesize</i> is unspecified by this volume of POSIX.1-2024. The header for the next file entry in the archive shall be written +directly after the last octet of the file entry preceding it. A header denoting the filename <b>TRAILER!!!</b> shall indicate the +end of the archive; the contents of octets in the last block of the archive following such a header are undefined.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_94_14" id="tag_20_94_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>All files were processed successfully.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_94_15" id="tag_20_94_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>If <i>pax</i> cannot create a file or a link when reading an archive or cannot find a file when writing an archive, or cannot +preserve the user ID, group ID, or file mode when the <b>-p</b> option is specified, a diagnostic message shall be written to +standard error and a non-zero exit status shall be returned, but processing shall continue. In the case where <i>pax</i> cannot +create a hard link to a file, <i>pax</i> shall not, by default, create a second copy of the file.</p> +<p class="tent">If the extraction of a file from an archive is prematurely terminated by a signal or error, <i>pax</i> may have +only partially extracted the file or (if the <b>-n</b> option was not specified) may have extracted a file of the same name as that +specified by the user, but which is not the file the user wanted. Additionally, the file modes of extracted directories may have +additional bits from the S_IRWXU mask set as well as incorrect modification and access times.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_94_16" id="tag_20_94_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Caution is advised when using the <b>-a</b> option to append to a <i>cpio</i> format archive. If any of the files being appended +happen to be given the same <i>c_dev</i> and <i>c_ino</i> values as a file in the existing part of the archive, then they may be +treated as links to that file on extraction. Thus, it is risky to use <b>-a</b> with <i>cpio</i> format except when it is done on +the same system that the original archive was created on, and with the same <i>pax</i> utility, and in the knowledge that there has +been little or no file system activity since the original archive was created that could lead to any of the files appended being +given the same <i>c_dev</i> and <i>c_ino</i> values as an unrelated file in the existing part of the archive. Also, when +(intentionally) appending additional links to a file in the existing part of the archive, the <i>c_nlink</i> values in the modified +archive can be smaller than the number of links to the file in the archive, which may mean that the links are not preserved on +extraction.</p> +<p class="tent">The <b>-p</b> (privileges) option was invented to reconcile differences between historical <i>tar</i> and +<i>cpio</i> implementations. In particular, the two utilities use <b>-m</b> in diametrically opposed ways. The <b>-p</b> option +also provides a consistent means of extending the ways in which future file attributes can be addressed, such as for enhanced +security systems or high-performance files. Although it may seem complex, there are really two modes that are most commonly +used:</p> +<dl compact> +<dd></dd> +<dt><b>-p e</b></dt> +<dd>"Preserve everything". This would be used by the historical superuser, someone with all appropriate privileges, to preserve +all aspects of the files as they are recorded in the archive. The <b>e</b> flag is the sum of <b>o</b> and <b>p</b>, and other +implementation-defined attributes.</dd> +<dt><b>-p p</b></dt> +<dd>"Preserve" the file mode bits. This would be used by the user with regular privileges who wished to preserve aspects of the +file other than the ownership. The file times are preserved by default, but two other flags are offered to disable these and use +the time of extraction.</dd> +</dl> +<p class="tent">The one pathname per line format of standard input precludes pathnames containing <newline> characters. +Although such pathnames violate the portable filename guidelines, they may exist and their presence may inhibit usage of <i>pax</i> +within shell scripts. This problem is inherited from historical archive programs. The problem can be avoided by listing filename +arguments on the command line instead of on standard input.</p> +<p class="tent">It is almost certain that appropriate privileges are required for <i>pax</i> to accomplish parts of this volume of +POSIX.1-2024. Specifically, creating files of type block special or character special, restoring file access times unless the files +are owned by the user (the <b>-t</b> option), or preserving file owner, group, and mode (the <b>-p</b> option) all probably require +appropriate privileges.</p> +<p class="tent">In <b>read</b> mode, implementations are permitted to overwrite files when the archive has multiple members with +the same name. This may fail if permissions on the first version of the file do not permit it to be overwritten.</p> +<p class="tent">The <b>cpio</b> and <b>ustar</b> formats can only support files up to 8589934592 bytes (8 * 2^30) in size.</p> +<p class="tent">When archives containing binary header information are listed , the filenames printed may cause strange behavior on +some terminals.</p> +<p class="tent">When all of the following are true:</p> +<ol> +<li class="tent">A file of type directory is being placed into an archive.</li> +<li class="tent">The <b>ustar</b> archive format is being used.</li> +<li class="tent">The pathname of the directory is less than or equal to 155 bytes long (it will fit in the <i>prefix</i> field in +the <b>ustar</b> header block).</li> +<li class="tent">The last component of the pathname of the directory is longer than 100 bytes long (it will not fit in the +<i>name</i> field in the <b>ustar</b> header block).</li> +</ol> +<p class="tent">some implementations of the <i>pax</i> utility will place the entire directory pathname in the <i>prefix</i> field, +set the <i>name</i> field to an empty string, and place the directory in the archive. Other implementations of the <i>pax</i> +utility will give an error under these conditions because the <i>name</i> field is not large enough to hold the last component of +the directory name. This standard allows either behavior. However, when extracting a directory from a <b>ustar</b> format archive, +this standard requires that all implementations be able to extract a directory even if the <i>name</i> field contains an empty +string as long as the <i>prefix</i> field does not also contain an empty string.</p> +<p class="tent">When restricting file hierarchy traversal to one file system, it can sometimes be desirable for the crossing points +themselves to be processed (archived or copied) and sometimes for them not to be processed. (Crossing points are mount points and, +if the <b>-L</b> option is specified, symbolic links to directories on other file systems.) With the <b>-X</b> option <i>pax</i> +processes them, but there is no standard way to have <i>pax</i> not process them. However, this can be achieved by using <a href= +"../utilities/find.html"><i>find</i></a> to do the hierarchy traversal and piping the output of find to <i>pax</i> (with the +<b>-d</b> option); see the APPLICATION USAGE for <a href="../utilities/find.html#"><i>find</i></a> .</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_94_17" id="tag_20_94_17"></a>EXAMPLES</h4> +<blockquote> +<p>The following command:</p> +<pre> +<tt>pax -w -f /dev/rmt/1m . +</tt></pre> +<p class="tent">copies the contents of the current directory to tape drive 1, medium density (assuming historical System V device +naming procedures—the historical BSD device name would be <b>/dev/rmt9</b>).</p> +<p class="tent">The following commands:</p> +<pre> +<tt>mkdir </tt><i>newdir</i><tt> +pax -rw </tt><i>olddir newdir</i><tt> +</tt></pre> +<p class="tent">copy the <i>olddir</i> directory hierarchy to <i>newdir</i>.</p> +<pre> +<tt>pax -r -s ',^//*usr//*,,' -f a.pax +</tt></pre> +<p class="tent">reads the archive <b>a.pax</b>, with all files rooted in <b>/usr</b> in the archive extracted relative to the +current directory.</p> +<p class="tent">Using the option:</p> +<pre> +<tt>-o listopt="%M %(atime)T %(size)D %(name)s" +</tt></pre> +<p class="tent">overrides the default output description in Standard Output and instead writes:</p> +<pre> +<tt>-rw-rw--- Jan 12 15:53 2003 1492 /usr/foo/bar +</tt></pre> +<p class="tent">Using the options:</p> +<pre> +<tt>-o listopt='%L\t%(size)D\n%.7' \ +-o listopt='(name)s\n%(atime)T\n%T' +</tt></pre> +<p class="tent">overrides the default output description in Standard Output and instead writes:</p> +<pre> +<tt>/usr/foo/bar -> /tmp 1492 +/usr/fo +Jan 12 15:53 1991 +Jan 31 15:53 2003 +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_94_18" id="tag_20_94_18"></a>RATIONALE</h4> +<blockquote> +<p>The <i>pax</i> utility was new for the ISO POSIX-2:1993 standard. It represents a peaceful compromise between advocates of +the historical <i>tar</i> and <i>cpio</i> utilities.</p> +<p class="tent">A fundamental difference between <i>cpio</i> and <i>tar</i> was in the way directories were treated. The +<i>cpio</i> utility did not treat directories differently from other files, and to select a directory and its contents required +that each file in the hierarchy be explicitly specified. For <i>tar</i>, a directory matched every file in the file hierarchy it +rooted.</p> +<p class="tent">The <i>pax</i> utility offers both interfaces; by default, directories map into the file hierarchy they root. The +<b>-d</b> option causes <i>pax</i> to skip any file not explicitly referenced, as <i>cpio</i> historically did. The <i>tar</i> +<b>-</b><i>style</i> behavior was chosen as the default because it was believed that this was the more common usage and because +<i>tar</i> is the more commonly available interface, as it was historically provided on both System V and BSD implementations.</p> +<p class="tent">The data interchange format specification in this volume of POSIX.1-2024 requires that processes with "appropriate +privileges" shall always restore the ownership and permissions of extracted files exactly as archived. If viewed from the historic +equivalence between superuser and "appropriate privileges", there are two problems with this requirement. First, users running as +superusers may unknowingly set dangerous permissions on extracted files. Second, it is needlessly limiting, in that superusers +cannot extract files and own them as superuser unless the archive was created by the superuser. (It should be noted that +restoration of ownerships and permissions for the superuser, by default, is historical practice in <i>cpio</i>, but not in +<i>tar</i>.) In order to avoid these two problems, the <i>pax</i> specification has an additional "privilege" mechanism, the +<b>-p</b> option. Only a <i>pax</i> invocation with the privileges needed, and which has the <b>-p</b> option set using the +<tt>e</tt> specification character, has appropriate privileges to restore full ownership and permission information.</p> +<p class="tent">Note also that this volume of POSIX.1-2024 requires that the file ownership and access permissions shall be set, on +extraction, in the same fashion as the <a href="../functions/creat.html"><i>creat</i>()</a> function when provided with the mode +stored in the archive. This means that the file creation mask of the user is applied to the file permissions.</p> +<p class="tent">Users should note that directories may be created by <i>pax</i> while extracting files with permissions that are +different from those that existed at the time the archive was created. When extracting sensitive information into a directory +hierarchy that no longer exists, users are encouraged to set their file creation mask appropriately to protect these files during +extraction.</p> +<p class="tent">The table of contents output is written to standard output to facilitate pipeline processing.</p> +<p class="tent">An early proposal had hard links displaying for all pathnames. This was removed because it complicates the output +of the case where <b>-v</b> is not specified and does not match historical <i>cpio</i> usage. The hard-link information is +available in the <b>-v</b> display.</p> +<p class="tent">The description of the <b>-l</b> option allows implementations to make hard links to symbolic links. Earlier +versions of this standard did not specify any way to create a hard link to a symbolic link, but many implementations provided this +capability as an extension. If there are hard links to symbolic links when an archive is created, the implementation is required to +archive the hard link in the archive (unless <b>-H</b> or <b>-L</b> is specified). When in <b>read</b> mode and in <b>copy</b> +mode, implementations supporting hard links to symbolic links should use them when appropriate.</p> +<p class="tent">The archive formats inherited from the POSIX.1-1990 standard have certain restrictions that have been brought along +from historical usage. For example, there are restrictions on the length of pathnames stored in the archive. When <i>pax</i> is +used in <b>copy</b>(<b>-rw</b>) mode (copying directory hierarchies), the ability to use extensions from the <b>-x</b><b>pax</b> +format overcomes these restrictions.</p> +<p class="tent">The default <i>blocksize</i> value of 5120 bytes for <i>cpio</i> was selected because it is one of the standard +block-size values for <i>cpio</i>, set when the <b>-B</b> option is specified. (The other default block-size value for <i>cpio</i> +is 512 bytes, and this was considered to be too small.) The default block value of 10240 bytes for <i>tar</i> was selected because +that is the standard block-size value for BSD <i>tar</i>. The maximum block size of 32256 bytes (2<small><sup>15</sup></small>-512 +bytes) is the largest multiple of 512 bytes that fits into a signed 16-bit tape controller transfer register. There are known +limitations in some historical systems that would prevent larger blocks from being accepted. Historical values were chosen to +improve compatibility with historical scripts using <a href="../utilities/dd.html"><i>dd</i></a> or similar utilities to manipulate +archives. Also, default block sizes for any file type other than character special file has been deleted from this volume of +POSIX.1-2024 as unimportant and not likely to affect the structure of the resulting archive.</p> +<p class="tent">Implementations are permitted to modify the block-size value based on the archive format or the device to which the +archive is being written. This is to provide implementations with the opportunity to take advantage of special types of devices, +and it should not be used without a great deal of consideration as it almost certainly decreases archive portability.</p> +<p class="tent">The intended use of the <b>-n</b> option was to permit extraction of one or more files from the archive without +processing the entire archive. This was viewed by the standard developers as offering significant performance advantages over +historical implementations. The <b>-n</b> option in early proposals had three effects; the first was to cause special characters in +patterns to not be treated specially. The second was to cause only the first file that matched a pattern to be extracted. The third +was to cause <i>pax</i> to write a diagnostic message to standard error when no file was found matching a specified pattern. Only +the second behavior is retained by this volume of POSIX.1-2024, for many reasons. First, it is in general not acceptable for a +single option to have multiple effects. Second, the ability to make pattern matching characters act as normal characters is useful +for parts of <i>pax</i> other than file extraction. Third, a finer degree of control over the special characters is useful because +users may wish to normalize only a single special character in a single filename. Fourth, given a more general escape mechanism, +the previous behavior of the <b>-n</b> option can be easily obtained using the <b>-s</b> option or a <a href= +"../utilities/sed.html"><i>sed</i></a> script. Finally, writing a diagnostic message when a pattern specified by the user is +unmatched by any file is useful behavior in all cases.</p> +<p class="tent">In this version, the <b>-n</b> was removed from the <b>copy</b> mode synopsis of <i>pax</i>; it is inapplicable +because there are no pattern operands specified in this mode.</p> +<p class="tent">There is another method than <i>pax</i> for copying subtrees in POSIX.1-2024 described as part of the <a href= +"../utilities/cp.html"><i>cp</i></a> utility. Both methods are historical practice: <a href="../utilities/cp.html"><i>cp</i></a> +provides a simpler, more intuitive interface, while <i>pax</i> offers a finer granularity of control. Each provides additional +functionality to the other; in particular, <i>pax</i> maintains the hard-link structure of the hierarchy while <a href= +"../utilities/cp.html"><i>cp</i></a> does not. It is the intention of the standard developers that the results be similar (using +appropriate option combinations in both utilities). The results are not required to be identical; there seemed insufficient gain to +applications to balance the difficulty of implementations having to guarantee that the results would be exactly identical.</p> +<p class="tent">A single archive may span more than one file. It is suggested that implementations provide informative messages to +the user on standard error whenever the archive file is changed.</p> +<p class="tent">The <b>-d</b> option (do not create intermediate directories not listed in the archive) found in early proposals +was originally provided as a complement to the historic <b>-d</b> option of <i>cpio</i>. It has been deleted.</p> +<p class="tent">The <b>-s</b> option in early proposals specified a subset of the substitution command from the <a href= +"../utilities/ed.html"><i>ed</i></a> utility. As there was no reason for only a subset to be supported, the <b>-s</b> option is now +compatible with the current <a href="../utilities/ed.html"><i>ed</i></a> specification. Since the delimiter can be any non-null +character, the following usage with single <space> characters is valid:</p> +<pre> +<tt>pax -s " foo bar " ... +</tt></pre> +<p class="tent">The <b>-t</b> description is worded so as to note that this may cause the access time update caused by some other +activity (which occurs while the file is being read) to be overwritten.</p> +<p class="tent">The default behavior of <i>pax</i> with regard to file modification times is the same as historical implementations +of <i>tar</i>. It is not the historical behavior of <i>cpio</i>.</p> +<p class="tent">Because the <b>-i</b> option uses <b>/dev/tty</b>, utilities without a controlling terminal are not able to use +this option.</p> +<p class="tent">The <b>-y</b> option, found in early proposals, has been deleted because a line containing a single <period> +for the <b>-i</b> option has equivalent functionality. The special lines for the <b>-i</b> option (a single <period> and the +empty line) are historical practice in <i>cpio</i>.</p> +<p class="tent">In early drafts, a <b>-e</b><i>charmap</i> option was included to increase portability of files between systems +using different coded character sets. This option was omitted because it was apparent that consensus could not be formed for it. In +this version, the use of UTF-8 should be an adequate substitute.</p> +<p class="tent">The ISO POSIX-2:1993 standard and ISO POSIX-1 standard requirements for <i>pax</i>, however, made it very +difficult to create a single archive containing files created using extended characters provided by different locales. This version +adds the <b>hdrcharset</b> keyword to make it possible to archive files in these cases without dropping files due to translation +errors.</p> +<p class="tent">Translating filenames and other attributes from a locale's encoding to UTF-8 and then back again can lose +information, as the resulting filename might not be byte-for-byte equivalent to the original. To avoid this problem, users can +specify the <b>-o</b> <b>hdrcharset=binary</b> option, which will cause the resulting archive to use binary format for all names +and attributes. Such archives are not portable among hosts that use different native encodings (e.g., EBCDIC <i>versus</i> +ASCII-based encodings), but they will allow interchange among the vast majority of POSIX file systems in practical use. Also, the +<b>-o</b> <b>hdrcharset=binary</b> option will cause <i>pax</i> in <b>copy</b> mode to behave more like other standard utilities +such as <a href="../utilities/cp.html"><i>cp</i></a>.</p> +<p class="tent">If the values specified by the <b>-o</b> <b>exthdr.name=value</b>, <b>-o</b> <b>globexthdr.name=value</b>, or by +<b>$TMPDIR</b> (if <b>-o</b> <b>globexthdr.name</b> is not specified) require a character encoding other than that described in the +ISO/IEC 646:1991 standard, a <b>path</b> extended header record will have to be created for the file. If a <b>hdrcharset</b> +extended header record is active for such headers, it will determine the codeset used for the value field in these extended +<b>path</b> header records. These <b>path</b> extended header records always need to be created when writing an archive even if +<b>hdrcharset=binary</b> has been specified and would contain the same (binary) data that appears in the <b>ustar</b> header record +prefix and <i>name</i> fields. (In other words, an extended header <b>path</b> record is always required to be generated if the +<i>prefix</i> or <i>name</i> fields contain non-ASCII characters even when <b>hdrcharset=binary</b> is also in effect for that +file.)</p> +<p class="tent">The <b>-k</b> option was added to address international concerns about the dangers involved in the character set +transformations of <b>-e</b> (if the target character set were different from the source, the filenames might be transformed into +names matching existing files) and also was made more general to protect files transferred between file systems with different +{NAME_MAX} values (truncating a filename on a smaller system might also inadvertently overwrite existing files). As stated, it +prevents any overwriting, even if the target file is older than the source. This version adds more granularity of options to solve +this problem by introducing the <b>-o</b><b>invalid=option</b>—specifically the <b>UTF-8</b> and <b>binary</b> actions. (Note that +an existing file is still subject to overwriting in this case. The <b>-k</b> option closes that loophole.)</p> +<p class="tent">Some of the file characteristics referenced in this volume of POSIX.1-2024 might not be supported by some archive +formats. For example, neither the <b>tar</b> nor <b>cpio</b> formats contain the file access time. For this reason, the <tt>e</tt> +specification character has been provided, intended to cause all file characteristics specified in the archive to be retained.</p> +<p class="tent">It is required that extracted directories, by default, have their access and modification times and permissions set +to the values specified in the archive. This has obvious problems in that the directories are almost certainly modified after being +extracted and that directory permissions may not permit file creation. One possible solution is to create directories with the mode +specified in the archive, as modified by the <a href="../utilities/umask.html"><i>umask</i></a> of the user, with sufficient +permissions to allow file creation. After all files have been extracted, <i>pax</i> would then reset the access and modification +times and permissions as necessary.</p> +<p class="tent">The list-mode formatting description borrows heavily from the one defined by the <a href= +"../utilities/printf.html"><i>printf</i></a> utility. However, since there is no separate operand list to get conversion arguments, +the format was extended to allow specifying the name of the conversion argument as part of the conversion specification.</p> +<p class="tent">The <tt>T</tt> conversion specifier allows time fields to be displayed in any of the date formats. Unlike the +<a href="../utilities/ls.html"><i>ls</i></a> utility, <i>pax</i> does not adjust the format when the date is less than six months +in the past. This makes parsing the output more predictable.</p> +<p class="tent">The <tt>D</tt> conversion specifier handles the ability to display the major/minor or file size, as with <a href= +"../utilities/ls.html"><i>ls</i></a>, by using <tt>%-8(</tt><i>size</i><tt>)D</tt>.</p> +<p class="tent">The <tt>L</tt> conversion specifier handles the <a href="../utilities/ls.html"><i>ls</i></a> display for symbolic +links.</p> +<p class="tent">Conversion specifiers were added to generate existing known types used for <a href= +"../utilities/ls.html"><i>ls</i></a>.</p> +<h5><a name="tag_20_94_18_01" id="tag_20_94_18_01"></a>pax Interchange Format</h5> +<p class="tent">The new POSIX data interchange format was developed primarily to satisfy international concerns that the +<b>ustar</b> and <b>cpio</b> formats did not provide for file, user, and group names encoded in characters outside a subset of the +ISO/IEC 646:1991 standard. The standard developers realized that this new POSIX data interchange format should be very +extensible because there were other requirements they foresaw in the near future:</p> +<ul> +<li class="tent">Support international character encodings and locale information</li> +<li class="tent">Support security information (ACLs, and so on)</li> +<li class="tent">Support future file types, such as realtime or contiguous files</li> +<li class="tent">Include data areas for implementation use</li> +<li class="tent">Support systems with words larger than 32 bits and timers with subsecond granularity</li> +</ul> +<p class="tent">The following were not goals for this format because these are better handled by separate utilities or are +inappropriate for a portable format:</p> +<ul> +<li class="tent">Encryption</li> +<li class="tent">Compression</li> +<li class="tent">Data translation between locales and codesets</li> +<li class="tent"><i>inode</i> storage</li> +</ul> +<p class="tent">The format chosen to support the goals is an extension of the <b>ustar</b> format. Of the two formats previously +available, only the <b>ustar</b> format was selected for extensions because:</p> +<ul> +<li class="tent">It was easier to extend in an upwards-compatible way. It offered version flags and header block type fields with +room for future standardization. The <b>cpio</b> format, while possessing a more flexible file naming methodology, could not be +extended without breaking some theoretical implementation or using a dummy filename that could be a legitimate filename.</li> +<li class="tent">Industry experience since the original "<i>tar</i> wars" fought in developing the ISO POSIX-1 standard has +clearly been in favor of the <b>ustar</b> format, which is generally the default output format selected for <i>pax</i> +implementations on new systems.</li> +</ul> +<p class="tent">The new format was designed with one additional goal in mind: reasonable behavior when an older <i>tar</i> or +<i>pax</i> utility happened to read an archive. Since the POSIX.1-1990 standard mandated that a "format-reading utility" had to +treat unrecognized <i>typeflag</i> values as regular files, this allowed the format to include all the extended information in a +pseudo-regular file that preceded each real file. An option is given that allows the archive creator to set up reasonable names for +these files on the older systems. Also, the normative text suggests that reasonable file access values be used for this +<b>ustar</b> header block. Making these header files inaccessible for convenient reading and deleting would not be reasonable. File +permissions of 600 or 700 are suggested.</p> +<p class="tent">The <b>ustar</b> <i>typeflag</i> field was used to accommodate the additional functionality of the new format +rather than magic or version because the POSIX.1-1990 standard (and, by reference, the previous version of <i>pax</i>), mandated +the behavior of the format-reading utility when it encountered an unknown <i>typeflag</i>, but was silent about the other two +fields.</p> +<p class="tent">Early proposals for the first version of this standard contained a proposed archive format that was based on +compatibility with the standard for tape files (ISO 1001, similar to the format used historically on many mainframes and +minicomputers). This format was overly complex and required considerable overhead in volume and header records. Furthermore, the +standard developers felt that it would not be acceptable to the community of POSIX developers, so it was later changed to be a +format more closely related to historical practice on POSIX systems.</p> +<p class="tent">The prefix and name split of pathnames in <b>ustar</b> was replaced by the single path extended header record for +simplicity.</p> +<p class="tent">The concept of a global extended header (<i>typeflag</i><b>g</b>) was controversial. If this were applied to an +archive being recorded on magnetic tape, a few unreadable blocks at the beginning of the tape could be a serious problem; a utility +attempting to extract as many files as possible from a damaged archive could lose a large percentage of file header information in +this case. However, if the archive were on a reliable medium, such as a CD-ROM, the global extended header offers considerable +potential size reductions by eliminating redundant information. Thus, the text warns against using the global method for unreliable +media and provides a method for implanting global information in the extended header for each file, rather than in the +<i>typeflag</i> <b>g</b> records.</p> +<p class="tent">No facility for data translation or filtering on a per-file basis is included because the standard developers could +not invent an interface that would allow this in an efficient manner. If a filter, such as encryption or compression, is to be +applied to all the files, it is more efficient to apply the filter to the entire archive as a single file. The standard developers +considered interfaces that would invoke a shell script for each file going into or out of the archive, but the system overhead in +this approach was considered to be too high.</p> +<p class="tent">One such approach would be to have <b>filter=</b> records that give a pathname for an executable. When the program +is invoked, the file and archive would be open for standard input/output and all the header fields would be available as +environment variables or command-line arguments. The standard developers did discuss such schemes, but they were omitted from +POSIX.1-2024 due to concerns about excessive overhead. Also, the program itself would need to be in the archive if it were to be +used portably.</p> +<p class="tent">There is currently no portable means of identifying the character set(s) used for a file in the file system. +Therefore, <i>pax</i> has not been given a mechanism to generate charset records automatically. The only portable means of doing +this is for the user to write the archive using the <b>-o</b><b>charset=string</b> command line option. This assumes that all of +the files in the archive use the same encoding. The "implementation-defined" text is included to allow for a system that can +identify the encodings used for each of its files.</p> +<p class="tent">The table of standards that accompanies the charset record description is acknowledged to be very limited. Only a +limited number of character set standards is reasonable for maximal interchange. Any character set is, of course, possible by prior +agreement. It was suggested that EBCDIC be listed, but it was omitted because it is not defined by a formal standard. Formal +standards, and then only those with reasonably large followings, can be included here, simply as a matter of practicality. The +<<i>value</i>>s represent names of officially registered character sets in the format required by the ISO 2375:1985 +standard.</p> +<p class="tent">The normal <comma> or <blank>-separated list rules are not followed in the case of keyword options to +allow ease of argument parsing for <a href="../utilities/getopts.html"><i>getopts</i></a>.</p> +<p class="tent">Further information on character encodings is in <a href="#tag_20_94_18_02">pax Archive Character Set +Encoding/Decoding</a> .</p> +<p class="tent">The standard developers have reserved keyword name space for vendor extensions. It is suggested that the format to +be used is:</p> +<pre> +<i>VENDOR.keyword</i> +</pre> +<p class="tent">where <i>VENDOR</i> is the name of the vendor or organization in all uppercase letters. It is further suggested +that the keyword following the <period> be named differently than any of the standard keywords so that it could be used for +future standardization, if appropriate, by omitting the <i>VENDOR</i> prefix.</p> +<p class="tent">The <<i>length</i>> field in the extended header record was included to make it simpler to step through the +records, even if a record contains an unknown format (to a particular <i>pax</i>) with complex interactions of special characters. +It also provides a minor integrity checkpoint within the records to aid a program attempting to recover files from a damaged +archive.</p> +<p class="tent">There are no extended header versions of the <i>devmajor</i> and <i>devminor</i> fields because the unspecified +format <b>ustar</b> header field should be sufficient. If they are not, vendor-specific extended keywords (such as +<i>VENDOR.devmajor</i>) should be used.</p> +<p class="tent">Device and <i>i</i>-number labeling of files was not adopted from <i>cpio</i>; files are interchanged strictly on a +symbolic name basis, as in <b>ustar</b>.</p> +<p class="tent">Just as with the <b>ustar</b> format descriptions, the new format makes no special arrangements for multi-volume +archives. Each of the <i>pax</i> archive types is assumed to be inside a single POSIX file and splitting that file over multiple +volumes (diskettes, tape cartridges, and so on), processing their labels, and mounting each in the proper sequence are considered +to be implementation details that cannot be described portably.</p> +<p class="tent">The <b>pax</b> format is intended for interchange, not only for backup on a single (family of) systems. It is not +as densely packed as might be possible for backup:</p> +<ul> +<li class="tent">It contains information as coded characters that could be coded in binary.</li> +<li class="tent">It identifies extended records with name fields that could be omitted in favor of a fixed-field layout.</li> +<li class="tent">It translates names into a portable character set and identifies locale-related information, both of which are +probably unnecessary for backup.</li> +</ul> +<p class="tent">The requirements on restoring from an archive are slightly different from the historical wording, allowing for +non-monolithic privilege to bring forward as much as possible. In particular, attributes such as "high performance file" might be +broadly but not universally granted while set-user-ID or <a href="../functions/chown.html"><i>chown</i>()</a> might be much more +restricted. There is no implication in POSIX.1-2024 that the security information be honored after it is restored to the file +hierarchy, in spite of what might be improperly inferred by the silence on that topic. That is a topic for another standard.</p> +<p class="tent">Hard links are recorded in the fashion described here because a hard link can be to any file type. It is desirable +in general to be able to restore part of an archive selectively and restore all of those files completely. If the data is not +associated with each hard link, it is not possible to do this. However, the data associated with a file can be large, and when +selective restoration is not needed, this can be a significant burden. The archive is structured so that files that have no +associated data can always be restored by the name of any link name of any hard link, and the user can choose whether data is +recorded with each instance of a file that contains data. The format permits mixing of hard links with data and hard links without +data in a single archive; this can be done for special needs, and <i>pax</i> is expected to interpret such archives on input +properly, despite the fact that there is no <i>pax</i> option that would force this mixed case on output. (When <b>-o</b> +<b>linkdata</b> is used, the output must contain the duplicate data, but the implementation is free to include it or omit it when +<b>-o</b> <b>linkdata</b> is not used.)</p> +<p class="tent">The time values are included as extended header records for those implementations needing more than the eleven +octal digits allowed by the <b>ustar</b> format. Portable file timestamps cannot be negative. If <i>pax</i> encounters a file with +a negative timestamp in <b>copy</b> or <b>write</b> mode, it can reject the file, substitute a non-negative timestamp, or generate +a non-portable timestamp with a leading <tt>'-'</tt>. Even though some implementations can support finer file-time granularities +than seconds, the normative text requires support only for seconds since the Epoch because the ISO POSIX-1 standard states +them that way. The <b>ustar</b> format includes only <i>mtime</i>; the new format adds <i>atime</i> and <i>ctime</i> for symmetry. +The <i>atime</i> access time restored to the file system will be affected by the <b>-p</b> <b>a</b> and <b>-p</b> <b>e</b> options. +The <i>ctime</i> creation time (actually <i>inode</i> modification time) is described with appropriate privileges so that it can be +ignored when writing to the file system. POSIX does not provide a portable means to change file creation time. Nothing is intended +to prevent a non-portable implementation of <i>pax</i> from restoring the value.</p> +<p class="tent">The <i>gid</i>, <i>size</i>, and <i>uid</i> extended header records were included to allow expansion beyond the +sizes specified in the regular <i>tar</i> header. New file system architectures are emerging that will exhaust the 12-digit size +field. There are probably not many systems requiring more than 8 digits for user and group IDs, but the extended header values were +included for completeness, allowing overrides for all of the decimal values in the <i>tar</i> header.</p> +<p class="tent">The standard developers intended to describe the effective results of <i>pax</i> with regard to file ownerships and +permissions; implementations are not restricted in timing or sequencing the restoration of such, provided the results are as +specified.</p> +<p class="tent">Much of the text describing the extended headers refers to use in "<b>write</b> or <b>copy</b> modes". The +<b>copy</b> mode references are due to the normative text: "The effect of the copy shall be as if the copied files were written to +an archive file and then subsequently extracted ...". There is certainly no way to test whether <i>pax</i> is actually generating +the extended headers in <b>copy</b> mode, but the effects must be as if it had.</p> +<h5><a name="tag_20_94_18_02" id="tag_20_94_18_02"></a>pax Archive Character Set Encoding/Decoding</h5> +<p class="tent">There is a need to exchange archives of files between systems of different native codesets. Filenames, group names, +and user names must be preserved to the fullest extent possible when an archive is read on the receiving platform. Translation of +the contents of files is not within the scope of the <i>pax</i> utility.</p> +<p class="tent">There will also be the need to represent characters that are not available on the receiving platform. These +unsupported characters cannot be automatically folded to the local set of characters due to the chance of collisions. This could +result in overwriting previous extracted files from the archive or pre-existing files on the system.</p> +<p class="tent">For these reasons, the codeset used to represent characters within the extended header records of the <i>pax</i> +archive must be sufficiently rich to handle all commonly used character sets. The fields requiring translation include, at a +minimum, filenames, user names, group names, and link pathnames. Implementations may wish to have localized extended keywords that +use non-portable characters.</p> +<p class="tent">The standard developers considered the following options:</p> +<ul> +<li class="tent">The archive creator specifies the well-defined name of the source codeset. The receiver must then recognize the +codeset name and perform the appropriate translations to the destination codeset.</li> +<li class="tent">The archive creator includes within the archive the character mapping table for the source codeset used to encode +extended header records. The receiver must then read the character mapping table and perform the appropriate translations to the +destination codeset.</li> +<li class="tent">The archive creator translates the extended header records in the source codeset into a canonical form. The +receiver must then perform the appropriate translations to the destination codeset.</li> +</ul> +<p class="tent">The approach that incorporates the name of the source codeset poses the problem of codeset name registration, and +makes the archive useless to <i>pax</i> archive decoders that do not recognize that codeset.</p> +<p class="tent">Because parts of an archive may be corrupted, the standard developers felt that including the character map of the +source codeset was too fragile. The loss of this one key component could result in making the entire archive useless. (The +difference between this and the global extended header decision was that the latter has a workaround—duplicating extended header +records on unreliable media—but this would be too burdensome for large character set maps.)</p> +<p class="tent">Both of the above approaches also put an undue burden on the <i>pax</i> archive receiver to handle the +cross-product of all source and destination codesets.</p> +<p class="tent">To simplify the translation from the source codeset to the canonical form and from the canonical form to the +destination codeset, the standard developers decided that the internal representation should be a stateless encoding. A stateless +encoding is one where each codepoint has the same meaning, without regard to the decoder being in a specific state. An example of a +stateful encoding would be the Japanese Shift-JIS; an example of a stateless encoding would be the ISO/IEC 646:1991 standard +(equivalent to 7-bit ASCII).</p> +<p class="tent">For these reasons, the standard developers decided to adopt a canonical format for the representation of file +information strings. The obvious, well-endorsed candidate is the ISO/IEC 10646-1:2020 standard (based in part on Unicode), +which can be used to represent the characters of virtually all standardized character sets. The standard developers initially +agreed upon using UCS2 (16-bit Unicode) as the internal representation. This repertoire of characters provides a sufficiently rich +set to represent all commonly-used codesets.</p> +<p class="tent">However, the standard developers found that the 16-bit Unicode representation had some problems. It forced the +issue of standardizing byte ordering. The 2-byte length of each character made the extended header records twice as long for the +case of strings coded entirely from historical 7-bit ASCII. For these reasons, the standard developers chose the UTF-8 defined in +the ISO/IEC 10646-1:2020 standard. This multi-byte representation encodes UCS2 or UCS4 characters reliably and +deterministically, eliminating the need for a canonical byte ordering. In addition, NUL octets and other characters possibly +confusing to POSIX file systems do not appear, except to represent themselves. It was realized that certain national codesets take +up more space after the encoding, due to their placement within the UCS range; it was felt that the usefulness of the encoding of +the names outweighs the disadvantage of size increase for file, user, and group names.</p> +<p class="tent">The encoding of UTF-8 is as follows:</p> +<pre> +<tt>UCS4 Hex Encoding UTF-8 Binary Encoding +<br class="tent"> +00000000-0000007F 0xxxxxxx +00000080-000007FF 110xxxxx 10xxxxxx +00000800-0000FFFF 1110xxxx 10xxxxxx 10xxxxxx +00010000-001FFFFF 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx +00200000-03FFFFFF 111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx +04000000-7FFFFFFF 1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx +</tt></pre> +<p class="tent">where each <tt>'x'</tt> represents a bit value from the character being translated.</p> +<h5><a name="tag_20_94_18_03" id="tag_20_94_18_03"></a>ustar Interchange Format</h5> +<p class="tent">The description of the <b>ustar</b> format reflects numerous enhancements over pre-1988 versions of the historical +<i>tar</i> utility. The goal of these changes was not only to provide the functional enhancements desired, but also to retain +compatibility between new and old versions. This compatibility has been retained. Archives written using the old archive format are +compatible with the new format.</p> +<p class="tent">Implementors should be aware that the previous file format did not include a mechanism to archive directory type +files. For this reason, the convention of using a filename ending with <slash> was adopted to specify a directory on the +archive.</p> +<p class="tent">The total size of the <i>name</i> and <i>prefix</i> fields have been set to meet the minimum requirements for +{PATH_MAX}. If a pathname will fit within the <i>name</i> field, it is recommended that the pathname be stored there without the +use of the <i>prefix</i> field. Although the name field is known to be too small to contain {PATH_MAX} characters, the value was +not changed in this version of the archive file format to retain backwards-compatibility, and instead the prefix was introduced. +Also, because of the earlier version of the format, there is no way to remove the restriction on the <i>linkname</i> field being +limited in size to just that of the <i>name</i> field.</p> +<p class="tent">The <i>size</i> field is required to be meaningful in all implementation extensions, although it could be zero. +This is required so that the data blocks can always be properly counted.</p> +<p class="tent">It is suggested that if device special files need to be represented that cannot be represented in the standard +format, that one of the extension types (<b>A</b>-<b>Z</b>) be used, and that the additional information for the special file be +represented as data and be reflected in the <i>size</i> field.</p> +<p class="tent">Attempting to restore a special file type, where it is converted to ordinary data and conflicts with an existing +filename, need not be specially detected by the utility. If run as an ordinary user, <i>pax</i> should not be able to overwrite the +entries in, for example, <b>/dev</b> in any case (whether the file is converted to another type or not). If run as a privileged +user, it should be able to do so, and it would be considered a bug if it did not. The same is true of ordinary data files and +similarly named special files; it is impossible to anticipate the needs of the user (who could really intend to overwrite the +file), so the behavior should be predictable (and thus regular) and rely on the protection system as required.</p> +<p class="tent">The value 7 in the <i>typeflag</i> field is intended to define how contiguous files can be stored in a <b>ustar</b> +archive. POSIX.1-2024 does not require the contiguous file extension, but does define a standard way of archiving such files so +that all conforming systems can interpret these file types in a meaningful and consistent manner. On a system that does not support +extended file types, the <i>pax</i> utility should do the best it can with the file and go on to the next.</p> +<p class="tent">The file protection modes are those conventionally used by the <a href="../utilities/ls.html"><i>ls</i></a> +utility. This is extended beyond the usage in the ISO POSIX-2 standard to support the "shared text" or "sticky" bit. It is +intended that the conformance document should not document anything beyond the existence of and support of such a mode. Further +extensions are expected to these bits, particularly with overloading the set-user-ID and set-group-ID flags.</p> +<h5><a name="tag_20_94_18_04" id="tag_20_94_18_04"></a>cpio Interchange Format</h5> +<p class="tent">The reference to appropriate privileges in the <b>cpio</b> format refers to an error on standard output; the +<b>ustar</b> format does not make comparable statements.</p> +<p class="tent">The model for this format was the historical System V <i>cpio</i><b>-c</b> data interchange format. This model +documents the portable version of the <b>cpio</b> format and not the binary version. It has the flexibility to transfer data of any +type described within POSIX.1-2024, yet is extensible to transfer data types specific to extensions beyond POSIX.1-2024 (for +example, contiguous files). Because it describes existing practice, there is no question of maintaining upwards-compatibility.</p> +<h5><a name="tag_20_94_18_05" id="tag_20_94_18_05"></a>cpio Header</h5> +<p class="tent">There has been some concern that the size of the <i>c_ino</i> field of the header is too small to handle those +systems that have very large <i>inode</i> numbers. However, the <i>c_ino</i> field in the header is used strictly as a hard-link +resolution mechanism for archives. It is not necessarily the same value as the <i>inode</i> number of the file in the location from +which that file is extracted.</p> +<p class="tent">The name <i>c_magic</i> is based on historical usage.</p> +<h5><a name="tag_20_94_18_06" id="tag_20_94_18_06"></a>cpio Filename</h5> +<p class="tent">For most historical implementations of the <i>cpio</i> utility, {PATH_MAX} octets can be used to describe the +pathname without the addition of any other header fields (the NUL character would be included in this count). {PATH_MAX} is the +minimum value for pathname size, documented as 256 bytes. However, an implementation may use <i>c_namesize</i> to determine the +exact length of the pathname. With the current description of the <a href="../basedefs/cpio.h.html"><i><cpio.h></i></a> +header, this pathname size can be as large as a number that is described in six octal digits.</p> +<p class="tent">Two values are documented under the <i>c_mode</i> field values to provide for extensibility for known file +types:</p> +<dl compact> +<dd></dd> +<dt><b>0110 000</b></dt> +<dd>Reserved for contiguous files. The implementation may treat the rest of the information for this archive like a regular file. +If this file type is undefined, the implementation may create the file as a regular file.</dd> +</dl> +<p class="tent">This provides for extensibility of the <b>cpio</b> format while allowing for the ability to read old archives. +Files of an unknown type may be read as "regular files" on some implementations. On a system that does not support extended file +types, the <i>pax</i> utility should do the best it can with the file and go on to the next.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_94_19" id="tag_20_94_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +<p class="tent">If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of +a <newline> character, implementations are encouraged to treat this as an error. A future version of this standard may +require implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_94_20" id="tag_20_94_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19"><i>2. Shell Command Language</i></a> , <a href= +"../utilities/cp.html#"><i>cp</i></a> , <a href="../utilities/ed.html#"><i>ed</i></a> , <a href= +"../utilities/getopts.html#"><i>getopts</i></a> , <a href="../utilities/ls.html#"><i>ls</i></a> , <a href= +"../utilities/printf.html#tag_20_96"><i>printf</i></a></p> +<p class="tent">XBD <a href="../basedefs/V1_chap03.html#tag_03_145"><i>3.145 File Mode Bits</i></a> , <a href= +"../basedefs/V1_chap05.html#tag_05"><i>5. File Format Notation</i></a> , <a href="../basedefs/V1_chap08.html#tag_08"><i>8. +Environment Variables</i></a> , <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a> , <a href= +"../basedefs/cpio.h.html"><i><cpio.h></i></a> , <a href="../basedefs/tar.h.html"><i><tar.h></i></a></p> +<p class="tent">XSH <a href="../functions/chown.html#tag_17_73"><i>chown</i></a> , <a href= +"../functions/creat.html#"><i>creat</i></a> , <a href="../functions/fstatat.html#"><i>fstatat</i></a> , <a href= +"../functions/futimens.html#"><i>futimens</i></a> , <a href="../functions/mkdir.html#tag_17_338"><i>mkdir</i></a> , <a href= +"../functions/mkfifo.html#tag_17_340"><i>mkfifo</i></a> , <a href="../functions/write.html#tag_17_699"><i>write</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_94_21" id="tag_20_94_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_94_22" id="tag_20_94_22"></a>Issue 5</h4> +<blockquote> +<p>A note is added to the APPLICATION USAGE indicating that the <b>cpio</b> and <b>tar</b> formats can only support files up to 8 +gigabytes in size.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_94_23" id="tag_20_94_23"></a>Issue 6</h4> +<blockquote> +<p>The <i>pax</i> utility is aligned with the IEEE P1003.2b draft standard:</p> +<ul> +<li class="tent">Support has been added for symbolic links in the options and interchange formats.</li> +<li class="tent">A new format has been devised, based on extensions to <b>ustar</b>.</li> +<li class="tent">References to the "extended" <b>tar</b> and <b>cpio</b> formats derived from the POSIX.1-1990 standard have been +changed to remove the "extended" adjective because this could cause confusion with the extended <b>tar</b> header added in this +version. (All references to <b>tar</b> are actually to <b>ustar</b>.)</li> +</ul> +<p class="tent">The <i>TZ</i> entry is added to the ENVIRONMENT VARIABLES section.</p> +<p class="tent">IEEE PASC Interpretation 1003.2 #168 is applied, clarifying that <a href= +"../functions/mkdir.html"><i>mkdir</i>()</a> and <a href="../functions/mkfifo.html"><i>mkfifo</i>()</a> calls can ignore an +[EEXIST] error when extracting an archive.</p> +<p class="tent">IEEE PASC Interpretation 1003.2 #180 is applied, clarifying how extracted files are created when in <b>read</b> +mode.</p> +<p class="tent">IEEE PASC Interpretation 1003.2 #181 is applied, clarifying the description of the <b>-t</b> option.</p> +<p class="tent">IEEE PASC Interpretation 1003.2 #195 is applied.</p> +<p class="tent">IEEE PASC Interpretation 1003.2 #206 is applied, clarifying the handling of links for the <b>-H</b>, <b>-L</b>, and +<b>-l</b> options.</p> +<p class="tent">IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/35 is applied, adding the process ID of the +<i>pax</i> process into certain fields. This change provides a method for the implementation to ensure that different instances of +<i>pax</i> extracting a file named <b>/a/b/foo</b> will not collide when processing the extended header information associated with +<b>foo</b>.</p> +<p class="tent">IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/36 is applied, changing <b>-x B</b> to <b>-x</b> +<i>pax</i> in the OPTIONS section.</p> +<p class="tent">IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/20 is applied, updating the SYNOPSIS to be +consistent with the normative text.</p> +<p class="tent">IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/21 is applied, updating the DESCRIPTION to describe +the behavior when files to be linked are symbolic links and the system is not capable of making hard links to symbolic links.</p> +<p class="tent">IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/22 is applied, updating the OPTIONS section to +describe the behavior for how multiple <b>-o</b><b>delete=pattern</b> options are to be handled.</p> +<p class="tent">IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/23 is applied, updating the <b>write</b> option +within the OPTIONS section.</p> +<p class="tent">IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/24 is applied, adding a paragraph into the OPTIONS +section that states that specifying more than one of the mutually-exclusive options (<b>-H</b> and <b>-L</b>) is not considered an +error and that the last option specified will determine the behavior of the utility.</p> +<p class="tent">IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/25 is applied, removing the <i>ctime</i> paragraph +within the EXTENDED DESCRIPTION. There is a contradiction in the definition of the <i>ctime</i> keyword for the <i>pax</i> extended +header, in that the <i>st_ctime</i> member of the <b>stat</b> structure does not refer to a file creation time. No field in the +standard <b>stat</b> structure from <a href="../basedefs/sys_stat.h.html"><i><sys/stat.h></i></a> includes a file creation +time.</p> +<p class="tent">IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/26 is applied, making it clear that <i>typeflag</i> +1 (<b>ustar</b> Interchange Format) applies not only to files that are hard-linked, but also to files that are aliased via symbolic +links.</p> +<p class="tent">IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/27 is applied, clarifying the <i>cpio</i> +<i>c_nlink</i> field.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_94_24" id="tag_20_94_24"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretations 1003.1-2001 #011, #036, #086, and #109 are applied.</p> +<p class="tent">Austin Group Interpretation 1003.1-2001 #126 is applied, changing the description of the <i>LC_MESSAGES</i> +environment variable.</p> +<p class="tent">SD5-XCU-ERN-2 is applied, making <b>-c</b> and <b>-n</b> mutually-exclusive in the SYNOPSIS.</p> +<p class="tent">SD5-XCU-ERN-3 is applied, revising the default behavior of <b>-H</b> and <b>-L</b>.</p> +<p class="tent">SD5-XCU-ERN-5, SD5-XCU-ERN-6, SD5-XCU-ERN-7, SD5-XCU-ERN-60 are applied.</p> +<p class="tent">SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p class="tent">The <i>pax</i> utility is no longer allowed to create separate identical symbolic links when extracting linked +symbolic links from an archive.</p> +<p class="tent">POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0128 [260], XCU/TC1-2008/0129 [261], XCU/TC1-2008/0130 [261], +XCU/TC1-2008/0131 [313], and XCU/TC1-2008/0132 [233] are applied.</p> +<p class="tent">POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0152 [886], XCU/TC2-2008/0153 [814], XCU/TC2-2008/0154 [886], +and XCU/TC2-2008/0155 [707] are applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_94_25" id="tag_20_94_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to behave as follows:</p> +<ol type="a"> +<li class="tent">Report an error if a utility is directed to display a pathname that contains any bytes that have the encoded value +of a <newline> character when <newline> is a terminator or separator in the output format being used.</li> +<li class="tent">Disallow the creation of filenames containing any bytes that have the encoded value of a <newline> +character.</li> +</ol> +<p class="tent">Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p class="tent">Austin Group Defect 1133 is applied, clarifying the <b>-X</b> option and adding a paragraph to the APPLICATION +USAGE section.</p> +<p class="tent">Austin Group Defect 1270 is applied, removing the <b>-n</b> option from the copy mode SYNOPSIS line.</p> +<p class="tent">Austin Group Defect 1278 is applied, removing mention of the <b>-n</b> option in connection with write mode.</p> +<p class="tent">Austin Group Defect 1330 is applied, removing obsolescent interfaces.</p> +<p class="tent">Austin Group Defect 1331 is applied, changing "st_atime" to "st_atim" and "st_mtime" to "st_mtim".</p> +<p class="tent">Austin Group Defect 1379 is applied, changing the ENVIRONMENT VARIABLES section.</p> +<p class="tent">Austin Group Defect 1380 is applied, changing text using the term "link" in line with its updated definition and +changing the description of the <b>-u</b> option.</p> +<p class="tent">Austin Group Defect 1618 is applied, adding optional trailing <tt>'s'</tt> and <tt>'S'</tt> characters to the +option-argument of the <b>-s</b> option.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/pathchk.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/pr.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/pr.html b/bdd/pr.html @@ -0,0 +1,402 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>pr</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/pax.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/printf.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="pr" id="pr"></a> <a name="tag_20_95" id="tag_20_95"></a><!-- pr --> +<h4 class="mansect"><a name="tag_20_95_01" id="tag_20_95_01"></a>NAME</h4> +<blockquote>pr — print files</blockquote> +<h4 class="mansect"><a name="tag_20_95_02" id="tag_20_95_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> pr</tt> <b>[</b><tt>+</tt><i>page</i><b>] +[</b><tt>-</tt><i>column</i><b>] [</b><tt>-ad<img src="../images/opt-start.gif" border="0">f<img src="../images/opt-end.gif" +border="0">Fmprt</tt><b>] [</b><tt>-e</tt><b>[</b><i>char</i><b>][</b><i>gap</i><b>]] [</b><tt>-h</tt> <i>header</i><b>]<br></b> +<tt> </tt> <b>[</b><tt>-i</tt><b>[</b><i>char</i><b>][</b><i>gap</i><b>]] [</b><tt>-l</tt> +<i>lines</i><b>] [</b><tt>-n</tt><b>[</b><i>char</i><b>][</b><i>width</i><b>]] [</b><tt>-o</tt> <i>offset</i><b>] +[</b><tt>-s</tt><b>[</b><i>char</i><b>]]<br></b> <tt> </tt> <b>[</b><tt>-w</tt> <i>width</i><b>] +[</b><i>file</i><tt>...</tt><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_95_03" id="tag_20_95_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>pr</i> utility is a printing and pagination filter. If multiple input files are specified, each shall be read, formatted, +and written to standard output. By default, the input shall be separated into 66-line pages, each with:</p> +<ul> +<li> +<p>A 5-line header that includes the page number, date, time, and the pathname of the file</p> +</li> +<li> +<p>A 5-line trailer consisting of blank lines</p> +</li> +</ul> +<p>If standard output is associated with a terminal, diagnostic messages shall be deferred until the <i>pr</i> utility has +completed processing.</p> +<p>When options specifying multi-column output are specified, output text columns shall be of equal width; input lines that do not +fit into a text column shall be truncated. By default, text columns shall be separated with at least one <blank>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_95_04" id="tag_20_95_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>pr</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> , except that: the <i>page</i> option has a <tt>'+'</tt> delimiter; <i>page</i> and <i>column</i> can be +multi-digit numbers; some of the option-arguments are optional; and some of the option-arguments cannot be specified as separate +arguments from the preceding option letter. In particular, the <b>-s</b> option does not allow the option letter to be separated +from its argument, and the options <b>-e</b>, <b>-i</b>, and <b>-n</b> require that both arguments, if present, not be separated +from the option letter.</p> +<p>The following options shall be supported. In the following option descriptions, <i>column</i>, <i>lines</i>, <i>offset</i>, +<i>page</i>, and <i>width</i> are positive decimal integers; <i>gap</i> is a non-negative decimal integer.</p> +<dl compact> +<dd></dd> +<dt><b>+</b><i>page</i></dt> +<dd>Begin output at page number <i>page</i> of the formatted input.</dd> +<dt><b>-</b><i>column</i></dt> +<dd>Produce multi-column output that is arranged in <i>column</i> columns (the default shall be 1) and is written down each column +in the order in which the text is received from the input file. This option should not be used with <b>-m</b>. The options +<b>-e</b> and <b>-i</b> shall be assumed for multiple text-column output. Whether or not text columns are produced with identical +vertical lengths is unspecified, but a text column shall never exceed the length of the page (see the <b>-l</b> option). When used +with <b>-t</b>, use the minimum number of lines to write the output.</dd> +<dt><b>-a</b></dt> +<dd>Modify the effect of the <b>-</b><i>column</i> option so that the columns are filled across the page in a round-robin order +(for example, when <i>column</i> is 2, the first input line heads column 1, the second heads column 2, the third is the second line +in column 1, and so on).</dd> +<dt><b>-d</b></dt> +<dd>Produce output that is double-spaced; append an extra <newline> following every <newline> found in the input.</dd> +<dt><b>-e[</b><i>char</i><b>][</b><i>gap</i><b>]</b></dt> +<dd><br> +Expand each input <tab> to the next greater column position specified by the formula <i>n</i>*<i>gap</i>+1, where <i>n</i> is +an integer > 0. If <i>gap</i> is zero or is omitted, it shall default to 8. All <tab> characters in the input shall be +expanded into the appropriate number of <space> characters. If any non-digit character, <i>char</i>, is specified, it shall +be used as the input <tab>. If the first character of the <b>-e</b> option-argument is a digit, the entire option-argument +shall be assumed to be <i>gap</i>.</dd> +<dt><b>-f</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Use a <form-feed> for new pages, instead of the default behavior that uses a sequence of <newline> characters. Pause +before beginning the first page if the standard output is associated with a terminal. <img src="../images/opt-end.gif" alt= +"[Option End]" border="0"></dd> +<dt><b>-F</b></dt> +<dd>Use a <form-feed> for new pages, instead of the default behavior that uses a sequence of <newline> characters.</dd> +<dt><b>-h </b><i>header</i></dt> +<dd>Use the string <i>header</i> to replace the contents of the <i>file</i> operand in the page header.</dd> +<dt><b>-i[</b><i>char</i><b>][</b><i>gap</i><b>]</b></dt> +<dd>In output, replace <space> characters with <tab> characters wherever one or more adjacent <space> characters +reach column positions <i>gap</i>+1, 2* <i>gap</i>+1, 3* <i>gap</i>+1, and so on. If <i>gap</i> is zero or is omitted, default tab +settings at every eighth column position shall be assumed. If any non-digit character, <i>char</i>, is specified, it shall be used +as the output <tab>. If the first character of the <b>-i</b> option-argument is a digit, the entire option-argument shall be +assumed to be <i>gap</i>.</dd> +<dt><b>-l </b><i>lines</i></dt> +<dd>Override the 66-line default and reset the page length to <i>lines</i>. If <i>lines</i> is not greater than the sum of both the +header and trailer depths (in lines), the <i>pr</i> utility shall suppress both the header and trailer, as if the <b>-t</b> option +were in effect.</dd> +<dt><b>-m</b></dt> +<dd>Merge files. Standard output shall be formatted so the <i>pr</i> utility writes one line from each file specified by a +<i>file</i> operand, side by side into text columns of equal fixed widths, in terms of the number of column positions. +Implementations shall support merging of at least nine <i>file</i> operands.</dd> +<dt><b>-n[</b><i>char</i><b>][</b><i>width</i><b>]</b></dt> +<dd><br> +Provide <i>width</i>-digit line numbering (default for <i>width</i> shall be 5). The number shall occupy the first <i>width</i> +column positions of each text column of default output or each line of <b>-m</b> output. If <i>char</i> (any non-digit character) +is given, it shall be appended to the line number to separate it from whatever follows (default for <i>char</i> is a +<tab>).</dd> +<dt><b>-o </b><i>offset</i></dt> +<dd>Each line of output shall be preceded by offset <space> characters. If the <b>-o</b> option is not specified, the default +offset shall be zero. The space taken is in addition to the output line width (see the <b>-w</b> option below).</dd> +<dt><b>-p</b></dt> +<dd>Pause before beginning each page if the standard output is directed to a terminal; <i>pr</i> shall write an <alert> to +standard error and wait for a <newline> to be read on <b>/dev/tty</b>.</dd> +<dt><b>-r</b></dt> +<dd>Write no diagnostic reports on failure to open files.</dd> +<dt><b>-s[</b><i>char</i><b>]</b></dt> +<dd>Separate text columns by the single character <i>char</i> instead of by the appropriate number of <space> characters +(default for <i>char</i> shall be <tab>).</dd> +<dt><b>-t</b></dt> +<dd>Write neither the five-line identifying header nor the five-line trailer usually supplied for each page. Quit writing after the +last line of each file without spacing to the end of the page.</dd> +<dt><b>-w </b><i>width</i></dt> +<dd>Set the width of the line to <i>width</i> column positions for multiple text-column output only. If the <b>-w</b> option is not +specified and the <b>-s</b> option is not specified, the default width shall be 72. If the <b>-w</b> option is not specified and +the <b>-s</b> option is specified, the default width shall be 512. +<p>For single column output, input lines shall not be truncated.</p> +</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_95_05" id="tag_20_95_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of a file to be written. If no <i>file</i> operands are specified, or if a <i>file</i> operand is <tt>'-'</tt>, the +standard input shall be used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_95_06" id="tag_20_95_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be used only if no <i>file</i> operands are specified, or if a <i>file</i> operand is <tt>'-'</tt>. See +the INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_95_07" id="tag_20_95_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files shall be text files. If the <b>-m</b> option is not specified, an empty input file may, but should not, be +treated as an error.</p> +<p>The file <b>/dev/tty</b> shall be used to read responses required by the <b>-p</b> option.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_95_08" id="tag_20_95_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>pr</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files) and which characters are defined as printable (character class +<b>print</b>). Non-printable characters are still written to standard output, but are not counted for the purpose for column-width +and line-length calculations.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>LC_TIME</i></dt> +<dd>Determine the format of the date and time for use in writing header lines.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>TZ</i></dt> +<dd>Determine the timezone used to calculate date and time strings written in header lines. If <i>TZ</i> is unset or null, an +unspecified default timezone shall be used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_95_09" id="tag_20_95_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>If <i>pr</i> receives an interrupt while writing to a terminal, it shall flush all accumulated error messages to the screen +before terminating.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_95_10" id="tag_20_95_10"></a>STDOUT</h4> +<blockquote> +<p>If the <b>-m</b> option is not specified, the <i>pr</i> utility output shall be as follows:</p> +<ul> +<li> +<p>If an input file is empty and the implementation does not treat this as an error, no output shall be written for that file and +this shall be considered to be successful completion of the processing for that file.</p> +</li> +<li> +<p>For each non-empty input file, the output shall be a paginated version of the original file.</p> +</li> +</ul> +<p>If the <b>-m</b> option is specified, the <i>pr</i> utility output shall be a paginated version of the merged file contents, as +described in OPTIONS.</p> +<p>In both cases, the pagination shall be accomplished using either <form-feed> characters or a sequence of <newline> +characters, as controlled by the <b>-F</b> <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src= +"../images/opt-start.gif" alt="[Option Start]" border="0"> or <b>-f</b> <img src="../images/opt-end.gif" alt="[Option End]" +border="0"> option. Page headers shall be generated unless the <b>-t</b> option is specified, the <b>-l</b> option is specified +with too small a value (see OPTIONS), or the <b>-m</b> option is specified and all of the input files are empty. The page headers +shall be of the form:</p> +<pre> +<tt>"\n\n%s %s Page %d\n\n\n", <</tt><i>output of date</i><tt>>, <</tt><i>file</i><tt>>, <</tt><i>page number</i><tt>> +</tt></pre> +<p>In the POSIX locale, the <<i>output of date</i>> field shall be equivalent to the output of the following +command:</p> +<pre> +<tt>date "+%b %e %H:%M %Y" +</tt></pre> +<p>without the trailing <newline>, as it would appear if executed at the current time if the <b>-m</b> option is specified, +or at the following time otherwise:</p> +<ul> +<li> +<p>The current time on pages being written from standard input.</p> +</li> +<li> +<p>The modification time of the file named by the corresponding <i>file</i> operand on pages not being written from standard +input.</p> +</li> +</ul> +<p>When the <i>LC_TIME</i> locale category is not set to the POSIX locale, a different format and order of presentation of this +field may be used.</p> +<p>If the <b>-h</b> option is specified, the <<i>file</i>> field shall be replaced by the <i>header</i> argument. +Otherwise:</p> +<ul> +<li> +<p>If the <b>-m</b> option is specified, the <<i>file</i>> field shall be replaced by a null string on all pages.</p> +</li> +<li> +<p>If the <b>-m</b> option is not specified, the <<i>file</i>> field shall be replaced by a null string on pages containing +output that was read from standard input.</p> +</li> +</ul> +</blockquote> +<h4 class="mansect"><a name="tag_20_95_11" id="tag_20_95_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used for diagnostic messages and for alerting the terminal when <b>-p</b> is specified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_95_12" id="tag_20_95_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_95_13" id="tag_20_95_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_95_14" id="tag_20_95_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_95_15" id="tag_20_95_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_95_16" id="tag_20_95_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>A conforming application must protect its first operand, if it starts with a <plus-sign>, by preceding it with the +<tt>"--"</tt> argument that denotes the end of the options. For example, <i>pr</i>+<i>x</i> could be interpreted as an invalid page +number or a <i>file</i> operand.</p> +<p>If a <i>file</i> operand contains <newline>, <form-feed>, or <vertical-tab> characters, or is overly long, and +the <i>pr</i> utility is instructed to include the pathname of that file in the header, pagination may not be handled correctly. +Applications can guard against this by using the <b>-h</b> option (for example, passing a sanitized, truncated form of the pathname +with <b>-h</b>).</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_95_17" id="tag_20_95_17"></a>EXAMPLES</h4> +<blockquote> +<ol> +<li> +<p>Print a numbered list of all files in the current directory:</p> +<pre> +<tt>ls -a | pr -n -h "Files in $(pwd)." +</tt></pre></li> +<li> +<p>Print <b>file1</b> and <b>file2</b> as a double-spaced, three-column listing headed by "file list":</p> +<pre> +<tt>pr -3d -h "file list" file1 file2 +</tt></pre></li> +<li> +<p>Write <b>file1</b> on <b>file2</b>, expanding tabs to columns 10, 19, 28, ...:</p> +<pre> +<tt>pr -e9 -t <file1 >file2 +</tt></pre></li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_95_18" id="tag_20_95_18"></a>RATIONALE</h4> +<blockquote> +<p>This utility is one of those that does not follow the Utility Syntax Guidelines because of its historical origins. The standard +developers could have added new options that obeyed the guidelines (and marked the old options obsolescent) or devised an entirely +new utility; there are examples of both actions in this volume of POSIX.1-2024. Because of its widespread use by historical +applications, the standard developers decided to exempt this version of <i>pr</i> from many of the guidelines.</p> +<p>Implementations are required to accept option-arguments to the <b>-h</b>, <b>-l</b>, <b>-o</b>, and <b>-w</b> options whether +presented as part of the same argument or as a separate argument to <i>pr</i>, as suggested by the Utility Syntax Guidelines. The +<b>-n</b> and <b>-s</b> options, however, are specified as in historical practice because they are frequently specified without +their optional arguments. If a <blank> were allowed before the option-argument in these cases, a <i>file</i> operand could +mistakenly be interpreted as an option-argument in historical applications.</p> +<p>The text about the minimum number of lines in multi-column output was included to ensure that a best effort is made in balancing +the length of the columns. There are known historical implementations in which, for example, 60-line files are listed by <i>pr</i> +-2 as one column of 56 lines and a second of 4. Although this is not a problem when a full page with headers and trailers is +produced, it would be relatively useless when used with <b>-t</b>.</p> +<p>Historical implementations of the <i>pr</i> utility have differed in the action taken for the <b>-f</b> option. BSD uses it as +described here for the <b>-F</b> option; System V uses it to change trailing <newline> characters on each page to a +<form-feed> and, if standard output is a TTY device, sends an <alert> to standard error and reads a line from +<b>/dev/tty</b> before the first page. There were strong arguments from both sides of this issue concerning historical practice and +as a result the <b>-F</b> option was added. XSI-conformant systems support the System V historical actions for the <b>-f</b> +option.</p> +<p>The <<i>output of date</i>> field in the <b>-l</b> format is specified only for the POSIX locale. As noted, the +format can be different in other locales. No mechanism for defining this is present in this volume of POSIX.1-2024, as the +appropriate vehicle is a message catalog; that is, the format should be specified as a "message".</p> +<p>Some implementations of <i>pr</i> treat an empty file as an error when <b>-m</b> is not specified, but not when <b>-m</b> is +specified (even if there is only one input file). Implementations are encouraged to eliminate this inconsistency by never treating +an empty file as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_95_19" id="tag_20_95_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>A future version of this standard may require that an empty file is never treated as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_95_20" id="tag_20_95_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/expand.html#"><i>expand</i></a> , <a href="../utilities/lp.html#"><i>lp</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_95_21" id="tag_20_95_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_95_22" id="tag_20_95_22"></a>Issue 6</h4> +<blockquote> +<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p> +<ul> +<li> +<p>The <b>-p</b> option is added.</p> +</li> +</ul> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_95_23" id="tag_20_95_23"></a>Issue 7</h4> +<blockquote> +<p>PASC Interpretation 1003.2-92 #151 (SD5-XCU-ERN-44) is applied.</p> +<p>Austin Group Interpretation 1003.1-2001 #093 is applied.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_95_24" id="tag_20_95_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, adding a paragraph about problematic pathnames to the APPLICATION USAGE section.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1433 is applied, changing <carriage-return> to <newline> in the description of the <b>-p</b> +option.</p> +<p>Austin Group Defect 1434 is applied, combining the two option groups in the SYNOPSIS into one.</p> +<p>Austin Group Defect 1590 is applied, clarifying the requirements when an input file is empty and changing the STDOUT +section.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/pax.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/printf.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/printf.html b/bdd/printf.html @@ -0,0 +1,675 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>printf</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/pr.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/prs.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="printf" id="printf"></a> <a name="tag_20_96" id="tag_20_96"></a><!-- printf --> +<h4 class="mansect"><a name="tag_20_96_01" id="tag_20_96_01"></a>NAME</h4> +<blockquote>printf — write formatted output</blockquote> +<h4 class="mansect"><a name="tag_20_96_02" id="tag_20_96_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>printf</tt> <i>format</i> <b>[</b><i>argument</i><tt>...</tt><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_96_03" id="tag_20_96_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>printf</i> utility shall write formatted operands to the standard output. The <i>argument</i> operands shall be formatted +under control of the <i>format</i> operand.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_96_04" id="tag_20_96_04"></a>OPTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_96_05" id="tag_20_96_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>format</i></dt> +<dd>A character string describing the format to use to write the remaining operands. See the EXTENDED DESCRIPTION section.</dd> +<dt><i>argument</i></dt> +<dd>The values to be written to standard output, under the control of <i>format</i>. See the EXTENDED DESCRIPTION section.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_96_06" id="tag_20_96_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_96_07" id="tag_20_96_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_96_08" id="tag_20_96_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>printf</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>LC_NUMERIC</i></dt> +<dd><br> +Determine the locale for numeric formatting. It shall affect the format of numbers written using the <tt>e</tt>, <tt>E</tt>, +<tt>f</tt>, <tt>g</tt>, and <tt>G</tt> conversion specifier characters (if supported).</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_96_09" id="tag_20_96_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_96_10" id="tag_20_96_10"></a>STDOUT</h4> +<blockquote> +<p>See the EXTENDED DESCRIPTION section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_96_11" id="tag_20_96_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_96_12" id="tag_20_96_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_96_13" id="tag_20_96_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>The application shall ensure that the <i>format</i> operand is a character string, beginning and ending in its initial shift +state, if any. The <i>format</i> operand shall be used as the format string described in XBD <a href= +"../basedefs/V1_chap05.html#tag_05"><i>5. File Format Notation</i></a> with the following exceptions:</p> +<ol> +<li> +<p>A <space> in the format string, in any context other than a flag of a conversion specification, shall be treated as an +ordinary character that is copied to the output.</p> +</li> +<li> +<p>A <tt>'Δ'</tt> character in the format string shall be treated as a <tt>'Δ'</tt> character, not as a <space>.</p> +</li> +<li> +<p>In addition to the escape sequences shown in XBD <a href="../basedefs/V1_chap05.html#tag_05"><i>5. File Format Notation</i></a> +(<tt>'\\'</tt>, <tt>'\a'</tt>, <tt>'\b'</tt>, <tt>'\f'</tt>, <tt>'\n'</tt>, <tt>'\r'</tt>, <tt>'\t'</tt>, <tt>'\v'</tt>), +<tt>"\ddd"</tt>, where <i>ddd</i> is a one, two, or three-digit octal number, shall be written as a byte with the numeric value +specified by the octal number.</p> +</li> +<li> +<p>The implementation shall not precede or follow output from the <tt>d</tt> or <tt>u</tt> conversion specifiers with <blank> +characters not specified by the <i>format</i> operand.</p> +</li> +<li> +<p>The implementation shall not precede output from the <tt>o</tt> conversion specifier with zeros not specified by the +<i>format</i> operand.</p> +</li> +<li> +<p>The <tt>a</tt>, <tt>A</tt>, <tt>e</tt>, <tt>E</tt>, <tt>f</tt>, <tt>F</tt>, <tt>g</tt>, and <tt>G</tt> conversion specifiers +need not be supported.</p> +</li> +<li> +<p>An additional conversion specifier character, <tt>b</tt>, shall be supported as follows. The argument shall be taken to be a +string that can contain <backslash>-escape sequences. The following <backslash>-escape sequences shall be +supported:</p> +<ul> +<li> +<p>The escape sequences listed in XBD <a href="../basedefs/V1_chap05.html#tag_05"><i>5. File Format Notation</i></a> +(<tt>'\\'</tt>, <tt>'\a'</tt>, <tt>'\b'</tt>, <tt>'\f'</tt>, <tt>'\n'</tt>, <tt>'\r'</tt>, <tt>'\t'</tt>, <tt>'\v'</tt>), which +shall be converted to the characters they represent.</p> +</li> +<li> +<p><tt>"\0ddd"</tt>, where <i>ddd</i> is a zero, one, two, or three-digit octal number that shall be converted to a byte with the +numeric value specified by the octal number.</p> +</li> +<li> +<p><tt>'\c'</tt>, which shall not be written and shall cause <i>printf</i> to ignore any remaining characters in the string operand +containing it, any remaining string operands, and any additional characters in the <i>format</i> operand. If a precision is +specified and the argument contains a <tt>'\c'</tt> after the point at which the number of bytes indicated by the precision +specification have been written, it is unspecified whether the <tt>'\c'</tt> takes effect.</p> +</li> +</ul> +<p>The interpretation of a <backslash> followed by any other sequence of characters is unspecified.</p> +<p>Bytes from the converted string shall be written until the end of the string or the number of bytes indicated by the precision +specification is reached. If the precision is omitted, it shall be taken to be infinite, so all bytes up to the end of the +converted string shall be written.</p> +</li> +<li> +<p>Conversions can be applied to the <i>n</i>th <i>argument</i> operand rather than to the next <i>argument</i> operand. In this +case, the conversion specifier character <tt>'%'</tt> is replaced by the sequence <tt>"%<i>n</i><tt>$"</tt></tt>, where <i>n</i> is +a decimal integer in the range [1,{NL_ARGMAX}], giving the <i>argument</i> operand number. This feature provides for the definition +of format strings that select arguments in an order appropriate to specific languages.</p> +<p>The format can contain either numbered argument conversion specifications (that is, ones beginning with +<tt>"%<i>n</i><tt>$"</tt></tt>), or unnumbered argument conversion specifications, but not both. The only exception to this is that +<tt>"%%"</tt> can be mixed with the <tt>"%<i>n</i><tt>$"</tt></tt> form. The results of mixing numbered and unnumbered argument +specifications that consume an argument are unspecified.</p> +</li> +<li> +<p>For each conversion specification that consumes an argument, an <i>argument</i> operand shall be evaluated and converted to the +appropriate type for the conversion as specified below. The operand to be evaluated shall be determined as follows:</p> +<ul> +<li> +<p>If the conversion specification begins with a <tt>"%<i>n</i><tt>$"</tt></tt> sequence, the <i>n</i>th <i>argument</i> operand +shall be evaluated.</p> +</li> +<li> +<p>Otherwise, the evaluated operand shall be the next <i>argument</i> operand after the one evaluated by the previous conversion +specification that consumed an argument; if there is no such previous conversion specification the first <i>argument</i> operand +shall be evaluated.</p> +</li> +</ul> +<p>If the <i>format</i> operand contains no conversion specifications that consume an argument and there are <i>argument</i> +operands present, the results are unspecified.</p> +</li> +<li> +<p>The <i>format</i> operand shall be reused as often as necessary to satisfy the <i>argument</i> operands. If conversion +specifications beginning with a <tt>"%<i>n</i><tt>$"</tt></tt> sequence are used, on format reuse the value of <i>n</i> shall refer +to the <i>n</i>th <i>argument</i> operand following the highest numbered <i>argument</i> operand consumed by the previous use of +the <i>format</i> operand.</p> +</li> +<li> +<p>If an <i>argument</i> operand to be consumed by a conversion specification does not exist:</p> +<ul> +<li> +<p>If it is a numbered argument conversion specification, <i>printf</i> should write a diagnostic message to standard error and +exit with non-zero status, but may behave as for an unnumbered argument conversion specification.</p> +</li> +<li> +<p>If it is an unnumbered argument conversion specification, any extra <tt>b</tt>, <tt>c</tt>, or <tt>s</tt> conversion specifiers +shall be evaluated as if a null string argument were supplied and any other extra conversion specifiers shall be evaluated as if a +zero argument were supplied.</p> +</li> +</ul> +</li> +<li> +<p>If a character sequence in the <i>format</i> operand begins with a <tt>'%'</tt> character, but does not form a valid conversion +specification, the behavior is unspecified.</p> +</li> +<li> +<p>The argument to the <tt>c</tt> conversion specifier can be a string containing zero or more bytes. If it contains one or more +bytes, the first byte shall be written and any additional bytes shall be ignored. If the argument is an empty string, it is +unspecified whether nothing is written or a null byte is written.</p> +</li> +</ol> +<p>The <i>argument</i> operands shall be treated as strings if the corresponding conversion specifier is <tt>b</tt>, <tt>c</tt>, or +<tt>s</tt>, and shall be evaluated as if by the <a href="../functions/strtod.html"><i>strtod</i>()</a> function if the +corresponding conversion specifier is <tt>a</tt>, <tt>A</tt>, <tt>e</tt>, <tt>E</tt>, <tt>f</tt>, <tt>F</tt>, <tt>g</tt>, or +<tt>G</tt>. Otherwise, they shall be evaluated as unsuffixed C integer constants, as described by the ISO C standard, with the +following extensions:</p> +<ul> +<li> +<p>A leading <plus-sign> or <hyphen-minus> shall be allowed.</p> +</li> +<li> +<p>If the leading character is a single-quote or double-quote, the value shall be the numeric value in the underlying codeset of +the character following the single-quote or double-quote.</p> +</li> +<li> +<p>Suffixed integer constants may be allowed.</p> +</li> +</ul> +<p>If an <i>argument</i> operand cannot be completely converted into an internal value appropriate to the corresponding conversion +specification, a diagnostic message shall be written to standard error and the utility shall not exit with a zero exit status, but +shall continue processing any remaining operands and shall write the value accumulated at the time the error was detected to +standard output.</p> +<p>It shall not be considered an error if an <i>argument</i> operand is not completely used for a <tt>b</tt>, <tt>c</tt>, or +<tt>s</tt> conversion.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_96_14" id="tag_20_96_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_96_15" id="tag_20_96_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_96_16" id="tag_20_96_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The floating-point formatting conversion specifications of <a href="../functions/printf.html"><i>printf</i>()</a> are not +required because all arithmetic in the shell is integer arithmetic. The <a href="../utilities/awk.html"><i>awk</i></a> utility +performs floating-point calculations and provides its own <b>printf</b> function. The <a href="../utilities/bc.html"><i>bc</i></a> +utility can perform arbitrary-precision floating-point arithmetic, but does not provide extensive formatting capabilities. (This +<i>printf</i> utility cannot really be used to format <a href="../utilities/bc.html"><i>bc</i></a> output; it does not support +arbitrary precision.) Implementations are encouraged to support the floating-point conversions as an extension.</p> +<p>Note that this <i>printf</i> utility, like the <a href="../functions/printf.html"><i>printf</i>()</a> function defined in the +System Interfaces volume of POSIX.1-2024 on which it is based, makes no special provision for dealing with multi-byte characters +when using the <tt>%c</tt> conversion specification or when a precision is specified in a <tt>%b</tt> or <tt>%s</tt> conversion +specification. Applications should be extremely cautious using either of these features when there are multi-byte characters in the +character set.</p> +<p>No provision is made in this volume of POSIX.1-2024 which allows field widths and precisions to be specified as <tt>'*'</tt> +since the <tt>'*'</tt> can be replaced directly in the <i>format</i> operand using shell variable substitution. Implementations can +also provide this feature as an extension if they so choose.</p> +<p>Hexadecimal character constants as defined in the ISO C standard are not recognized in the <i>format</i> operand because +there is no consistent way to detect the end of the constant. Octal character constants are limited to, at most, three octal +digits, but hexadecimal character constants are only terminated by a non-hex-digit character. In the ISO C standard, string +literal concatenation can be used to terminate a constant and follow it with a hexadecimal character to be written. In the shell, +similar concatenation can be done using <tt>$'...'</tt> so that the shell converts the hexadecimal sequence before it executes +<i>printf</i>.</p> +<p>The <tt>%b</tt> conversion specification is not part of the ISO C standard; it has been added here as a portable way to +process <backslash>-escapes expanded in string operands as provided by the <a href="../utilities/echo.html"><i>echo</i></a> +utility. See also the APPLICATION USAGE section of <a href="../utilities/echo.html#"><i>echo</i></a> for ways to use <i>printf</i> +as a replacement for all of the traditional versions of the <a href="../utilities/echo.html"><i>echo</i></a> utility.</p> +<p>If an argument cannot be parsed correctly for the corresponding conversion specification, the <i>printf</i> utility is required +to report an error. Thus, overflow and extraneous characters at the end of an argument being used for a numeric conversion shall be +reported as errors.</p> +<p>Unlike the <a href="../functions/printf.html"><i>printf</i>()</a> function, when numbered conversion specifications are used, +specifying the <i>N</i>th argument does not require that all the leading arguments, from the first to the (<i>N-1</i>)th, are +specified in the format string. For example, <tt>"%3$s %1$d\n"</tt> is an acceptable <i>format</i> operand which evaluates the +first and third <i>argument</i> operands but not the second.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_96_17" id="tag_20_96_17"></a>EXAMPLES</h4> +<blockquote> +<p>To alert the user and then print and read a series of prompts:</p> +<pre> +<tt>printf "\aPlease fill in the following: \nName: " +read name +printf "Phone number: " +read phone +</tt></pre> +<p>To read out a list of right and wrong answers from a file, calculate the percentage correctly, and print them out. The numbers +are right-justified and separated by a single <tab>. The percentage is written to one decimal place of accuracy:</p> +<pre> +<tt>while read right wrong ; do + percent=$(echo "scale=1;($right*100)/($right+$wrong)" | bc) + printf "%2d right\t%2d wrong\t(%s%%)\n" \ + $right $wrong $percent +done < database_file +</tt></pre> +The command: +<pre> +<tt>printf "%5d%4d\n" 1 21 321 4321 54321 +</tt></pre> +<p>produces:</p> +<pre> +<tt> 1 21 + 3214321 +54321 0 +</tt></pre> +<p>Note that the <i>format</i> operand is used three times to print all of the given strings and that a <tt>'0'</tt> was supplied +by <i>printf</i> to satisfy the last <tt>%4d</tt> conversion specification.</p> +<p>The command:</p> +<pre> +<tt>printf '%d\n' 10 010 0x10 +</tt></pre> +<p>produces:<br></p> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Output Line</b></p> +</th> +<th align="center"> +<p class="tent"><b>Explanation</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">10</p> +</td> +<td align="left"> +<p class="tent">Decimal representation of the numeric value of decimal integer constant 10</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">8</p> +</td> +<td align="left"> +<p class="tent">Decimal representation of the numeric value of octal integer constant 010</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">16</p> +</td> +<td align="left"> +<p class="tent">Decimal representation of the numeric value of hexadecimal integer constant 0x10</p> +</td> +</tr> +</table> +</center> +<p class="tent">If the implementation supports floating-point conversions, the command:</p> +<pre> +<tt>LC_ALL=C printf '%.2f\n' 10 010 0x10 10.1e2 010.1e2 0x10.1p2 +</tt></pre> +<p class="tent">produces:<br></p> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Output Line</b></p> +</th> +<th align="center"> +<p class="tent"><b>Explanation</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">10.00</p> +</td> +<td align="left"> +<p class="tent">The string <tt>"10"</tt> interpreted as a decimal value, with 2 digits of precision</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">10.00</p> +</td> +<td align="left"> +<p class="tent">The string <tt>"010"</tt> interpreted as a decimal (not octal) value, with 2 digits of precision</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">16.00</p> +</td> +<td align="left"> +<p class="tent">The string <tt>"0x10"</tt> interpreted as a hexadecimal value, with 2 digits of precision</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">1010.00</p> +</td> +<td align="left"> +<p class="tent">The string <tt>"10.1e2"</tt> interpreted as a decimal floating-point value, with 2 digits of precision</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">1010.00</p> +</td> +<td align="left"> +<p class="tent">The string <tt>"010.1e2"</tt> interpreted as a decimal (not octal) floating-point value, with 2 digits of +precision</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">64.25</p> +</td> +<td align="left"> +<p class="tent">The string <tt>"0x10.1p2"</tt> interpreted as a hexadecimal floating-point value, with 2 digits of precision</p> +</td> +</tr> +</table> +</center> +<p class="tent">The <i>printf</i> utility is required to notify the user when conversion errors are detected while producing +numeric output; thus, the following results would be expected on an implementation with 32-bit two's-complement integers when +<tt>%d</tt> is specified as the <i>format</i> operand:<br></p> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Argument</b></p> +</th> +<th align="center"> +<p class="tent"><b>Standard Output</b></p> +</th> +<th align="center"> +<p class="tent"><b>Diagnostic Output</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">5a</p> +</td> +<td align="left"> +<p class="tent">5</p> +</td> +<td align="left"> +<p class="tent">printf: "5a" not completely converted</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">9999999999</p> +</td> +<td align="left"> +<p class="tent">2147483647</p> +</td> +<td align="left"> +<p class="tent">printf: "9999999999" arithmetic overflow</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">-9999999999</p> +</td> +<td align="left"> +<p class="tent">-2147483648</p> +</td> +<td align="left"> +<p class="tent">printf: "-9999999999" arithmetic overflow</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">ABC</p> +</td> +<td align="left"> +<p class="tent">0</p> +</td> +<td align="left"> +<p class="tent">printf: "ABC" expected numeric value</p> +</td> +</tr> +</table> +</center> +<p class="tent">The diagnostic message format is not specified, but these examples convey the type of information that should be +reported. Note that the value shown on standard output is what would be expected as the return value from the <a href= +"../functions/strtol.html"><i>strtol</i>()</a> function as defined in the System Interfaces volume of POSIX.1-2024. A similar +correspondence exists between <tt>%u</tt> and <a href="../functions/strtoul.html"><i>strtoul</i>()</a> and <tt>%e</tt>, +<tt>%f</tt>, and <tt>%g</tt> (if the implementation supports floating-point conversions) and <a href= +"../functions/strtod.html"><i>strtod</i>()</a>.</p> +<p class="tent">In a locale that uses a codeset based on the ISO/IEC 646:1991 standard, the command:</p> +<pre> +<tt>printf "%d\n" 3 +3 -3 \'3 \"+3 "'-3" +</tt></pre> +<p class="tent">produces:<br></p> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Output Line</b></p> +</th> +<th align="center"> +<p class="tent"><b>Explanation</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">3</p> +</td> +<td align="left"> +<p class="tent">Decimal representation of the numeric value 3</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">3</p> +</td> +<td align="left"> +<p class="tent">Decimal representation of the numeric value +3</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">-3</p> +</td> +<td align="left"> +<p class="tent">Decimal representation of the numeric value -3</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">51</p> +</td> +<td align="left"> +<p class="tent">Decimal representation of the numeric value of the character <tt>'3'</tt> in the ISO/IEC 646:1991 standard +codeset</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">43</p> +</td> +<td align="left"> +<p class="tent">Decimal representation of the numeric value of the character <tt>'+'</tt> in the ISO/IEC 646:1991 standard +codeset</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">45</p> +</td> +<td align="left"> +<p class="tent">Decimal representation of the numeric value of the character <tt>'-'</tt> in the ISO/IEC 646:1991 standard +codeset</p> +</td> +</tr> +</table> +</center> +<p class="tent">Since the last two arguments contain more characters than used for the conversion, a diagnostic message is +generated and the exit status is non-zero. Note that in a locale with multi-byte characters, the value of a character is intended +to be the value of the equivalent of the <b>wchar_t</b> representation of the character as described in the System Interfaces +volume of POSIX.1-2024.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_96_18" id="tag_20_96_18"></a>RATIONALE</h4> +<blockquote> +<p>The <i>printf</i> utility was added to provide functionality that has historically been provided by <a href= +"../utilities/echo.html"><i>echo</i></a>. However, due to irreconcilable differences in the various versions of <a href= +"../utilities/echo.html"><i>echo</i></a> extant, the version has few special features, leaving those to this new <i>printf</i> +utility, which is based on one in the Ninth Edition system.</p> +<p class="tent">The format strings for the <i>printf</i> utility are handled differently than for the <a href= +"../functions/printf.html"><i>printf</i>()</a> function in several respects. Notable differences include:</p> +<ul> +<li class="tent">Reuse of the format until all arguments have been consumed.</li> +<li class="tent">No provision for obtaining field width and precision from argument values.</li> +<li class="tent">No requirement to support floating-point conversion specifiers.</li> +<li class="tent">An additional <tt>b</tt> conversion specifier.</li> +<li class="tent">Special handling of leading single-quote or double-quote for integer conversion specifiers.</li> +<li class="tent">Hexadecimal character constants are not recognized in the format.</li> +<li class="tent">Formats that use numbered argument conversion specifications can have gaps in the argument numbers.</li> +</ul> +<p class="tent">Although <i>printf</i> implementations have no difficulty handling formats with mixed numbered and unnumbered +conversion specifications (unlike the <a href="../functions/printf.html"><i>printf</i>()</a> function where it is undefined +behavior), existing implementations differ in behavior. Given the format operand <tt>"%2$d %d\n"</tt>, with some +implementations the <tt>"%d"</tt> evaluates the first argument and with others it evaluates the third. Consequently this standard +leaves the behavior unspecified (as opposed to undefined).</p> +<p class="tent">Earlier versions of this standard specified that arguments for all conversions other than <tt>b</tt>, <tt>c</tt>, +and <tt>s</tt> were evaluated in the same way (as C constants, but with stated exceptions). For implementations supporting the +floating-point conversions it was not clear whether integer conversions need only accept integer constants and floating-point +conversions need only accept floating-point constants, or whether both types of conversions should accept both types of constants. +Also by not distinguishing between them, the requirement relating to a leading single-quote or double-quote applied to +floating-point conversions even though this provided no useful functionality to applications that was not already available through +the integer conversions. The current standard clarifies the situation by specifying that the arguments for floating-point +conversions are evaluated as if by <a href="../functions/strtod.html"><i>strtod</i>()</a>, and the arguments for integer +conversions are evaluated as C integer constants, with the special treatment of leading single-quote and double-quote applying only +to integer conversions.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_96_19" id="tag_20_96_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>A future version of this standard may require that a missing <i>argument</i> operand to be consumed by a numbered argument +conversion specification is treated as an error.</p> +<p class="tent">A future version of this standard is expected to add a <tt>%b</tt> conversion to the <a href= +"../functions/printf.html"><i>printf</i>()</a> function for binary conversion of integers, in alignment with the next version of +the ISO C standard. This will result in an inconsistency between the <i>printf</i> utility and <a href= +"../functions/printf.html"><i>printf</i>()</a> function for format strings containing <tt>%b</tt>. Implementors are encouraged to +collaborate on a way to address this which could then be adopted in a future version of this standard. For example, the +<i>printf</i> utility could add a <b>-C</b> option to make the format string behave in the same way, as far as possible, as the +<a href="../functions/printf.html"><i>printf</i>()</a> function.</p> +<p class="tent">A future version of this standard may add a <tt>%q</tt> conversion to convert a string argument to a quoted output +format that can be reused as shell input.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_96_20" id="tag_20_96_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/awk.html#"><i>awk</i></a> , <a href="../utilities/bc.html#"><i>bc</i></a> , <a href= +"../utilities/echo.html#"><i>echo</i></a></p> +<p class="tent">XBD <a href="../basedefs/V1_chap05.html#tag_05"><i>5. File Format Notation</i></a> , <a href= +"../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a></p> +<p class="tent">XSH <a href="../functions/fprintf.html#"><i>fprintf</i></a> , <a href= +"../functions/strtod.html#"><i>strtod</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_96_21" id="tag_20_96_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_96_22" id="tag_20_96_22"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretations 1003.1-2001 #175 and #177 are applied.</p> +<p class="tent">SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p class="tent">POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0156 [727], XCU/TC2-2008/0157 [727,932], XCU/TC2-2008/0158 +[584], and XCU/TC2-2008/0159 [727] are applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_96_23" id="tag_20_96_23"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1108 is applied, changing "twos" to "two's".</p> +<p class="tent">Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p class="tent">Austin Group Defect 1202 is applied, changing the description of how <tt>'\c'</tt> is handled by the <tt>b</tt> +conversion specifier.</p> +<p class="tent">Austin Group Defects 1209 and 1476 are applied, changing the EXAMPLES section.</p> +<p class="tent">Austin Group Defect 1413 is applied, changing the APPLICATION USAGE section.</p> +<p class="tent">Austin Group Defect 1562 is applied, clarifying that it is the application's responsibility to ensure that the +format is a character string, beginning and ending in its initial shift state, if any.</p> +<p class="tent">Austin Group Defect 1592 is applied, adding support for numbered conversion specifications.</p> +<p class="tent">Austin Group Defect 1771 is applied, changing the FUTURE DIRECTIONS section.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/pr.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/prs.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/prs.html b/bdd/prs.html @@ -0,0 +1,1216 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>prs</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/printf.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/ps.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="prs" id="prs"></a> <a name="tag_20_97" id="tag_20_97"></a><!-- prs --> +<h4 class="mansect"><a name="tag_20_97_01" id="tag_20_97_01"></a>NAME</h4> +<blockquote>prs — print an SCCS file (<b>DEVELOPMENT</b>)</blockquote> +<h4 class="mansect"><a name="tag_20_97_02" id="tag_20_97_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> prs</tt> <b>[</b><tt>-a</tt><b>] [</b><tt>-d</tt> <i>dataspec</i><b>] +[</b><tt>-r</tt><b>[</b><i>SID</i><b>]]</b> <i>file</i><tt>...<br> +<br> +prs</tt> <b>[</b><tt>-e|-l</tt><b>]</b> <tt>-c</tt> <i>cutoff</i> <b>[</b><tt>-d</tt> <i>dataspec</i><b>]</b> +<i>file</i><tt>...<br> +<br> +prs</tt> <b>[</b><tt>-e|-l</tt><b>]</b> <tt>-r</tt><b>[</b><i>SID</i><b>] [</b><tt>-d</tt> <i>dataspec</i><b>]</b> +<i>file</i><tt>... <img src="../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div> +<tt><br></tt></blockquote> +<h4 class="mansect"><a name="tag_20_97_03" id="tag_20_97_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>prs</i> utility shall write to standard output parts or all of an SCCS file in a user-supplied format.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_97_04" id="tag_20_97_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>prs</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> , except that the <b>-r</b> option has an optional option-argument. This optional option-argument cannot be +presented as a separate argument. The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-d </b><i>dataspec</i></dt> +<dd>Specify the output data specification. The <i>dataspec</i> shall be a string consisting of SCCS file <i>data</i> +<i>keywords</i> (see <a href="#tag_20_97_10_01">Data Keywords</a> ) interspersed with optional user-supplied text.</dd> +<dt><b>-r[</b><i>SID</i><b>]</b></dt> +<dd>Specify the SCCS identification string (SID) of a delta for which information is desired. If no <i>SID</i> option-argument is +specified, the SID of the most recently created delta shall be assumed.</dd> +<dt><b>-e</b></dt> +<dd>Request information for all deltas created earlier than and including the delta designated via the <b>-r</b> option or the +date-time given by the <b>-c</b> option.</dd> +<dt><b>-l</b></dt> +<dd>Request information for all deltas created later than and including the delta designated via the <b>-r</b> option or the +date-time given by the <b>-c</b> option.</dd> +<dt><b>-c </b><i>cutoff</i></dt> +<dd>Indicate the <i>cutoff</i> date-time, in the form: +<pre> +<i>YY</i><b>[</b><i>MM</i><b>[</b><i>DD</i><b>[</b><i>HH</i><b>[</b><i>MM</i><b>[</b><i>SS</i><b>]]]]]</b><tt> +</tt></pre> +<p>For the <i>YY</i> component, values in the range [69,99] shall refer to years 1969 to 1999 inclusive, and values in the range +[00,68] shall refer to years 2000 to 2068 inclusive. <basefont size="2"></p> +<dl> +<dt><b>Note:</b></dt> +<dd>It is expected that in a future version of this standard the default century inferred from a 2-digit year will change. (This +would apply to all commands accepting a 2-digit year as input.)</dd> +</dl> +<basefont size="3"> +<p>No changes (deltas) to the SCCS file that were created after the specified <i>cutoff</i> date-time shall be included in the +output. Units omitted from the date-time default to their maximum possible values; for example, <b>-c 7502</b> is equivalent +to <b>-c 750228235959</b>.</p> +</dd> +<dt><b>-a</b></dt> +<dd>Request writing of information for both removed—that is, <a href="../utilities/delta.html"><i>delta</i></a> +<i>type</i>=<i>R</i> (see <a href="../utilities/rmdel.html#"><i>rmdel</i></a> )—and existing—that is, <a href= +"../utilities/delta.html"><i>delta</i></a> <i>type</i>=<i>D</i>,—deltas. If the <b>-a</b> option is not specified, information for +existing deltas only shall be provided.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_97_05" id="tag_20_97_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of an existing SCCS file or a directory. If <i>file</i> is a directory, the <i>prs</i> utility shall behave as +though each file in the directory were specified as a named file, except that non-SCCS files (last component of the pathname does +not begin with <b>s.</b>) and unreadable files shall be silently ignored. +<p>If exactly one <i>file</i> operand appears, and it is <tt>'-'</tt>, the standard input shall be read; each line of the standard +input shall be taken to be the name of an SCCS file to be processed. Non-SCCS files and unreadable files shall be silently +ignored.</p> +</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_97_06" id="tag_20_97_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be a text file used only when the <i>file</i> operand is specified as <tt>'-'</tt>. Each line of the +text file shall be interpreted as an SCCS pathname.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_97_07" id="tag_20_97_07"></a>INPUT FILES</h4> +<blockquote> +<p>Any SCCS files displayed are files of an unspecified format.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_97_08" id="tag_20_97_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>prs</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd>Determine the location of messages objects and message catalogs.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_97_09" id="tag_20_97_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_97_10" id="tag_20_97_10"></a>STDOUT</h4> +<blockquote> +<p>The standard output shall be a text file whose format is dependent on the data keywords specified with the <b>-d</b> option.</p> +<h5><a name="tag_20_97_10_01" id="tag_20_97_10_01"></a>Data Keywords</h5> +<p>Data keywords specify which parts of an SCCS file shall be retrieved and output. All parts of an SCCS file have an associated +data keyword. A data keyword may appear in a <i>dataspec</i> multiple times.</p> +<p>The information written by <i>prs</i> shall consist of:</p> +<ol> +<li> +<p>The user-supplied text</p> +</li> +<li> +<p>Appropriate values (extracted from the SCCS file) substituted for the recognized data keywords in the order of appearance in the +<i>dataspec</i></p> +</li> +</ol> +<p>The format of a data keyword value shall either be simple (<tt>'S'</tt>), in which keyword substitution is direct, or multi-line +(<tt>'M'</tt>).</p> +<p>User-supplied text shall be any text other than recognized data keywords. A <tab> shall be specified by <tt>'\t'</tt> and +<newline> by <tt>'\n'</tt>. When the <b>-r</b> option is not specified, the default <i>dataspec</i> shall be:</p> +<pre> +<tt>:PN::\n\n +</tt></pre> +<p>and the following <i>dataspec</i> shall be used for each selected delta:</p> +<pre> +<tt>:Dt:\t:DL:\nMRs:\n:MR:COMMENTS:\n:C: +</tt></pre> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th colspan="5" align="center"> +<p class="tent"><b>SCCS File Data Keywords</b></p> +</th> +</tr> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Keyword</b></p> +</th> +<th align="center"> +<p class="tent"><b>Data Item</b></p> +</th> +<th align="center"> +<p class="tent"><b>File Section</b></p> +</th> +<th align="center"> +<p class="tent"><b>Value</b></p> +</th> +<th align="center"> +<p class="tent"><b>Format</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:Dt:</b></p> +</td> +<td align="left"> +<p class="tent">Delta information</p> +</td> +<td align="center"> +<p class="tent">Delta Table</p> +</td> +<td align="left"> +<p class="tent"><b>See below*</b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:DL:</b></p> +</td> +<td align="left"> +<p class="tent">Delta line statistics</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b>:Li:/:Ld:/:Lu:</b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:Li:</b></p> +</td> +<td align="left"> +<p class="tent">Lines inserted by Delta</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b><i>nnnnn</i>***</b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:Ld:</b></p> +</td> +<td align="left"> +<p class="tent">Lines deleted by Delta</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b><i>nnnnn</i>***</b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:Lu:</b></p> +</td> +<td align="left"> +<p class="tent">Lines unchanged by Delta</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b><i>nnnnn</i>***</b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:DT:</b></p> +</td> +<td align="left"> +<p class="tent">Delta type</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b>D or R</b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:I:</b></p> +</td> +<td align="left"> +<p class="tent">SCCS ID string (SID)</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b>See below**</b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:R:</b></p> +</td> +<td align="left"> +<p class="tent">Release number</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b><i>nnnn</i></b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:L:</b></p> +</td> +<td align="left"> +<p class="tent">Level number</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b><i>nnnn</i></b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:B:</b></p> +</td> +<td align="left"> +<p class="tent">Branch number</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b><i>nnnn</i></b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:S:</b></p> +</td> +<td align="left"> +<p class="tent">Sequence number</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b><i>nnnn</i></b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:D:</b></p> +</td> +<td align="left"> +<p class="tent">Date delta created</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b>:Dy:/:Dm:/:Dd:</b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:Dy:</b></p> +</td> +<td align="left"> +<p class="tent">Year delta created</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b><i>nn</i></b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:Dm:</b></p> +</td> +<td align="left"> +<p class="tent">Month delta created</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b><i>nn</i></b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:Dd:</b></p> +</td> +<td align="left"> +<p class="tent">Day delta created</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b><i>nn</i></b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:T:</b></p> +</td> +<td align="left"> +<p class="tent">Time delta created</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b>:Th:::Tm:::Ts:</b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:Th:</b></p> +</td> +<td align="left"> +<p class="tent">Hour delta created</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b><i>nn</i></b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:Tm:</b></p> +</td> +<td align="left"> +<p class="tent">Minutes delta created</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b><i>nn</i></b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:Ts:</b></p> +</td> +<td align="left"> +<p class="tent">Seconds delta created</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b><i>nn</i></b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:P:</b></p> +</td> +<td align="left"> +<p class="tent">Programmer who created Delta</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b><i>logname</i></b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:DS:</b></p> +</td> +<td align="left"> +<p class="tent">Delta sequence number</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b><i>nnnn</i></b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:DP:</b></p> +</td> +<td align="left"> +<p class="tent">Predecessor Delta sequence number</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b><i>nnnn</i></b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:DI:</b></p> +</td> +<td align="left"> +<p class="tent">Sequence number of deltas included, excluded, or ignored</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b>:Dn:/:Dx:/:Dg:</b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:Dn:</b></p> +</td> +<td align="left"> +<p class="tent">Deltas included (sequence #)</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b>:DS: :DS: ...</b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:Dx:</b></p> +</td> +<td align="left"> +<p class="tent">Deltas excluded (sequence #)</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b>:DS: :DS: ...</b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:Dg:</b></p> +</td> +<td align="left"> +<p class="tent">Deltas ignored (sequence #)</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b>:DS: :DS: ...</b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:MR:</b></p> +</td> +<td align="left"> +<p class="tent">MR numbers for delta</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b><i>text</i></b></p> +</td> +<td align="center"> +<p class="tent">M</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:C:</b></p> +</td> +<td align="left"> +<p class="tent">Comments for delta</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b><i>text</i></b></p> +</td> +<td align="center"> +<p class="tent">M</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:UN:</b></p> +</td> +<td align="left"> +<p class="tent">User names</p> +</td> +<td align="center"> +<p class="tent">User Names</p> +</td> +<td align="left"> +<p class="tent"><b><i>text</i></b></p> +</td> +<td align="center"> +<p class="tent">M</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:FL:</b></p> +</td> +<td align="left"> +<p class="tent">Flag list</p> +</td> +<td align="center"> +<p class="tent">Flags</p> +</td> +<td align="left"> +<p class="tent"><b><i>text</i></b></p> +</td> +<td align="center"> +<p class="tent">M</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:Y:</b></p> +</td> +<td align="left"> +<p class="tent">Module type flag</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b><i>text</i></b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:MF:</b></p> +</td> +<td align="left"> +<p class="tent">MR validation flag</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b>yes or no</b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:MP:</b></p> +</td> +<td align="left"> +<p class="tent">MR validation program name</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b><i>text</i></b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:KF:</b></p> +</td> +<td align="left"> +<p class="tent">Keyword error, warning flag</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b>yes or no</b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:BF:</b></p> +</td> +<td align="left"> +<p class="tent">Branch flag</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b>yes or no</b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:J:</b></p> +</td> +<td align="left"> +<p class="tent">Joint edit flag</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b>yes or no</b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:LK:</b></p> +</td> +<td align="left"> +<p class="tent">Locked releases</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b>:R: ...</b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:Q:</b></p> +</td> +<td align="left"> +<p class="tent">User-defined keyword</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b><i>text</i></b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:M:</b></p> +</td> +<td align="left"> +<p class="tent">Module name</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b><i>text</i></b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:FB:</b></p> +</td> +<td align="left"> +<p class="tent">Floor boundary</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b>:R:</b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:CB:</b></p> +</td> +<td align="left"> +<p class="tent">Ceiling boundary</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b>:R:</b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:Ds:</b></p> +</td> +<td align="left"> +<p class="tent">Default SID</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b>:I:</b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:ND:</b></p> +</td> +<td align="left"> +<p class="tent">Null delta flag</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b>yes or no</b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:FD:</b></p> +</td> +<td align="left"> +<p class="tent">File descriptive text</p> +</td> +<td align="center"> +<p class="tent">Comments</p> +</td> +<td align="left"> +<p class="tent"><b><i>text</i></b></p> +</td> +<td align="center"> +<p class="tent">M</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:BD:</b></p> +</td> +<td align="left"> +<p class="tent">Body</p> +</td> +<td align="center"> +<p class="tent">Body</p> +</td> +<td align="left"> +<p class="tent"><b><i>text</i></b></p> +</td> +<td align="center"> +<p class="tent">M</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:GB:</b></p> +</td> +<td align="left"> +<p class="tent">Gotten body</p> +</td> +<td align="center"> +<p class="tent">"</p> +</td> +<td align="left"> +<p class="tent"><b><i>text</i></b></p> +</td> +<td align="center"> +<p class="tent">M</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:W:</b></p> +</td> +<td align="left"> +<p class="tent">A form of <i>what</i> string</p> +</td> +<td align="center"> +<p class="tent">N/A</p> +</td> +<td align="left"> +<p class="tent"><b>:Z::M:\t:I:</b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:A:</b></p> +</td> +<td align="left"> +<p class="tent">A form of <i>what</i> string</p> +</td> +<td align="center"> +<p class="tent">N/A</p> +</td> +<td align="left"> +<p class="tent"><b>:Z::Y: :M: :I::Z:</b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:Z:</b></p> +</td> +<td align="left"> +<p class="tent"><i>what</i> string delimiter</p> +</td> +<td align="center"> +<p class="tent">N/A</p> +</td> +<td align="left"> +<p class="tent"><b><tt>@(#)</tt></b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:F:</b></p> +</td> +<td align="left"> +<p class="tent">SCCS filename</p> +</td> +<td align="center"> +<p class="tent">N/A</p> +</td> +<td align="left"> +<p class="tent"><b><i>text</i></b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>:PN:</b></p> +</td> +<td align="left"> +<p class="tent">SCCS file pathname</p> +</td> +<td align="center"> +<p class="tent">N/A</p> +</td> +<td align="left"> +<p class="tent"><b><i>text</i></b></p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +</tr> +</table> +</center> +<dl compact> +<dd></dd> +<dt>*</dt> +<dd><b>:Dt:</b>=<b>:DT: :I: :D: :T: :P: :DS: :DP:</b></dd> +<dt>**</dt> +<dd><b>:R:.:L:.:B:.:S:</b> if the delta is a branch delta (<b>:BF:</b>==<b>yes</b>)<br> +<b>:R:.:L:</b> if the delta is not a branch delta (<b>:BF:</b>==<b>no</b>)</dd> +<dt>***</dt> +<dd>The line statistics are capped at 99999. For example, if 100000 lines were unchanged in a certain revision, <b>:Lu:</b> shall +produce the value 99999.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_97_11" id="tag_20_97_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_97_12" id="tag_20_97_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_97_13" id="tag_20_97_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_97_14" id="tag_20_97_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_97_15" id="tag_20_97_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_97_16" id="tag_20_97_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_97_17" id="tag_20_97_17"></a>EXAMPLES</h4> +<blockquote> +<ol> +<li class="tent">The following example: +<pre> +<tt>prs -d "User Names for :F: are:\n:UN:" s.file +</tt></pre> +<p class="tent">might write to standard output:</p> +<pre> +<tt>User Names for s.file are: +xyz +131 +abc +</tt></pre></li> +<li class="tent">The following example: +<pre> +<tt>prs -d "Delta for pgm :M:: :I: - :D: By :P:" -r s.file +</tt></pre> +<p class="tent">might write to standard output:</p> +<pre> +<tt>Delta for pgm main.c: 3.7 - 77/12/01 By cas +</tt></pre></li> +<li class="tent">As a special case: +<pre> +<tt>prs s.file +</tt></pre> +<p class="tent">might write to standard output:</p> +<pre> +<tt>s.file: +<</tt><i>blank line</i><tt>> +D 1.1 77/12/01 00:00:00 cas 1 000000/00000/00000 +MRs: +bl78-12345 +bl79-54321 +COMMENTS: +this is the comment line for s.file initial delta +<</tt><i>blank line</i><tt>> +</tt></pre> +<p class="tent">for each delta table entry of the <b>D</b> type. The only option allowed to be used with this special case is the +<b>-a</b> option.</p> +</li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_97_18" id="tag_20_97_18"></a>RATIONALE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_97_19" id="tag_20_97_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_97_20" id="tag_20_97_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/admin.html#"><i>admin</i></a> , <a href="../utilities/delta.html#"><i>delta</i></a> , <a href= +"../utilities/get.html#"><i>get</i></a> , <a href="../utilities/what.html#"><i>what</i></a></p> +<p class="tent">XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_97_21" id="tag_20_97_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_97_22" id="tag_20_97_22"></a>Issue 5</h4> +<blockquote> +<p>The phrase "in which keyword substitution is followed by a <newline>" is deleted from the end of the second paragraph of +<a href="#tag_20_97_10_01">Data Keywords</a> .</p> +<p class="tent">The interpretation of the <i>YY</i> component of the <b>-c</b> <i>cutoff</i> argument is noted.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_97_23" id="tag_20_97_23"></a>Issue 6</h4> +<blockquote> +<p>The normative text is reworded to emphasize the term "shall" for implementation requirements.</p> +<p class="tent">The Open Group Base Resolution bwg2001-007 is applied, updating the table in STDOUT with a note that line +statistics are capped at 99999 for the <b>:Li:</b>, <b>:Ld:</b>, <b>:Lu:</b>, and <b>:DL:</b> keywords.</p> +<p class="tent">The Open Group Interpretation PIN4C.00009 is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_97_24" id="tag_20_97_24"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_97_25" id="tag_20_97_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to report an error if a utility is directed to display a +pathname that contains any bytes that have the encoded value of a <newline> character when <newline> is a terminator or +separator in the output format being used.</p> +<p class="tent">Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p class="tent">Austin Group Defect 1452 is applied, deleting <b>:KV:</b> from the list of keywords.</p> +<p class="tent">Austin Group Defect 1570 is applied, removing extra spacing in <tt>"=="</tt>.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/printf.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/ps.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/ps.html b/bdd/ps.html @@ -0,0 +1,718 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>ps</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/prs.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/pwd.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="ps" id="ps"></a> <a name="tag_20_98" id="tag_20_98"></a><!-- ps --> +<h4 class="mansect"><a name="tag_20_98_01" id="tag_20_98_01"></a>NAME</h4> +<blockquote>ps — report process status</blockquote> +<h4 class="mansect"><a name="tag_20_98_02" id="tag_20_98_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> ps</tt> <b>[</b><tt>-aAw</tt><b>] [</b><tt>-defl</tt><b>] +[</b><tt>-g</tt> <i>grouplist</i><b>]<img src="../images/opt-end.gif" alt="[Option End]" border="0"> [</b><tt>-G</tt> +<i>grouplist</i><b>]<br></b> <tt> </tt> <b>[</b><tt>-n</tt> <i>namelist</i><b>]<img src= +"../images/opt-end.gif" alt="[Option End]" border="0"> [</b><tt>-o</tt> <i>format</i><b>]</b><tt>...</tt> <b>[</b><tt>-p</tt> +<i>proclist</i><b>] [</b><tt>-t</tt> <i>termlist</i><b>]<br></b> <tt> </tt> <b>[</b><tt>-u</tt> +<i>userlist</i><b>]<img src="../images/opt-end.gif" alt="[Option End]" border="0"> [</b><tt>-U</tt> <i>userlist</i><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_98_03" id="tag_20_98_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>ps</i> utility shall write information about processes, subject to having appropriate privileges to obtain information +about those processes.</p> +<p>By default, <i>ps</i> shall select all processes with the same effective user ID as the current user and the same controlling +terminal as the invoker.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_98_04" id="tag_20_98_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>ps</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-a</b></dt> +<dd>Write information for all processes associated with terminals. Implementations may omit session leaders from this list.</dd> +<dt><b>-A</b></dt> +<dd>Write information for all processes.</dd> +<dt><b>-d</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Write information for all processes, except session leaders. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-e</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Write information for all processes. <img src="../images/opt-end.gif" alt="[Option End]" border="0"> (Equivalent to +<b>-A</b>.)</dd> +<dt><b>-f</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Generate a <b>full</b> listing. (See the STDOUT section for the contents of a <b>full</b> listing.) <img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-g </b><i>grouplist</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Write information for processes whose session leaders are given in <i>grouplist</i>. The application shall ensure that the +<i>grouplist</i> is a single argument in the form of a <blank> or <comma>-separated list. <img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-G </b><i>grouplist</i></dt> +<dd>Write information for processes whose real group ID numbers are given in <i>grouplist</i>. The application shall ensure that +the <i>grouplist</i> is a single argument in the form of a <blank> or <comma>-separated list.</dd> +<dt><b>-l</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Generate a <b>long</b> listing. (See STDOUT for the contents of a <b>long</b> listing.) <img src="../images/opt-end.gif" alt= +"[Option End]" border="0"></dd> +<dt><b>-n </b><i>namelist</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Specify the name of an alternative system <i>namelist</i> file in place of the default. The name of the default file and the format +of a <i>namelist</i> file are unspecified. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-o </b><i>format</i></dt> +<dd>Write information according to the format specification given in <i>format</i>. This is fully described in the STDOUT section. +Multiple <b>-o</b> options can be specified; the format specification shall be interpreted as the <space>-separated +concatenation of all the <i>format</i> option-arguments.</dd> +<dt><b>-p </b><i>proclist</i></dt> +<dd>Write information for processes whose process ID numbers are given in <i>proclist</i>. The application shall ensure that the +<i>proclist</i> is a single argument in the form of a <blank> or <comma>-separated list.</dd> +<dt><b>-t </b><i>termlist</i></dt> +<dd>Write information for processes associated with terminals given in <i>termlist</i>. The application shall ensure that the +<i>termlist</i> is a single argument in the form of a <blank> or <comma>-separated list. Terminal identifiers shall be +given in an implementation-defined format. <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src= +"../images/opt-start.gif" alt="[Option Start]" border="0"> On XSI-conformant systems, they shall be given in one of two +forms: the device's filename (for example, <b>tty04</b>) or, if the device's filename starts with <b>tty</b>, just the identifier +following the characters <b>tty</b> (for example, <tt>"04"</tt>). <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><b>-u </b><i>userlist</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Write information for processes whose user ID numbers or login names are given in <i>userlist</i>. The application shall ensure +that the <i>userlist</i> is a single argument in the form of a <blank> or <comma>-separated list. In the listing, the +numerical user ID shall be written unless the <b>-f</b> option is used, in which case the login name shall be written. <img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-U </b><i>userlist</i></dt> +<dd>Write information for processes whose real user ID numbers or login names are given in <i>userlist</i>. The application shall +ensure that the <i>userlist</i> is a single argument in the form of a <blank> or <comma>-separated list.</dd> +<dt><b>-w</b></dt> +<dd>Behave as if the <i>COLUMNS</i> environment variable had a value of at least 132. If the <b>-w</b> option is not specified or +is specified exactly once, all output lines shall contain no more than the greater of {LINE_MAX} and <i>COLUMNS</i> bytes provided +that no format name is specified multiple times.</dd> +</dl> +<p>With the exception of <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> <b>-f</b>, <b>-l</b>, <b>-n</b> <i>namelist</i>, <img src="../images/opt-end.gif" alt="[Option End]" +border="0"> and <b>-o</b> <i>format</i>, all of the options shown are used to select processes. If any are specified, the +default list shall be ignored and <i>ps</i> shall select the processes represented by the inclusive OR of all the +selection-criteria options.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_98_05" id="tag_20_98_05"></a>OPERANDS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_98_06" id="tag_20_98_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_98_07" id="tag_20_98_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_98_08" id="tag_20_98_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>ps</i>:</p> +<dl compact> +<dd></dd> +<dt><i>COLUMNS</i></dt> +<dd>Override the system-selected horizontal display line size, used to determine the number of text columns to display. See XBD +<a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> for valid values and results when it is unset or +null.</dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error and +informative messages written to standard output.</dd> +<dt><i>LC_TIME</i></dt> +<dd>Determine the format and contents of the date and time strings displayed.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>TZ</i></dt> +<dd>Determine the timezone used to calculate date and time strings displayed. If <i>TZ</i> is unset or null, an unspecified default +timezone shall be used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_98_09" id="tag_20_98_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_98_10" id="tag_20_98_10"></a>STDOUT</h4> +<blockquote> +<p>When the <b>-o</b> option is not specified, the standard output format is unspecified.<br></p> +<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +On XSI-conformant systems, the output format shall be as follows. The column headings and descriptions of the columns in a +<i>ps</i> listing are given below. The precise meanings of these fields are implementation-defined. The letters <tt>'f'</tt> and +<tt>'l'</tt> (below) indicate the option (<b>full</b> or <b>long</b>) that shall cause the corresponding heading to appear; +<b>all</b> means that the heading always appears. Note that these two options determine only what information is provided for a +process; they do not determine which processes are listed.</p> +<table cellpadding="3"> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>F</b></p> +</td> +<td align="left"> +<p class="tent">(l)</p> +</td> +<td align="left"> +<p class="tent">Flags (octal and additive) associated with the process.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>S</b></p> +</td> +<td align="left"> +<p class="tent">(l)</p> +</td> +<td align="left"> +<p class="tent">The state of the process.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>UID</b></p> +</td> +<td align="left"> +<p class="tent">(f,l)</p> +</td> +<td align="left"> +<p class="tent">The user ID number of the process owner; the login name is printed under the <b>-f</b> option.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>PID</b></p> +</td> +<td align="left"> +<p class="tent">(all)</p> +</td> +<td align="left"> +<p class="tent">The process ID of the process; it is possible to kill a process if this datum is known.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>PPID</b></p> +</td> +<td align="left"> +<p class="tent">(f,l)</p> +</td> +<td align="left"> +<p class="tent">The process ID of the parent process.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>C</b></p> +</td> +<td align="left"> +<p class="tent">(f,l)</p> +</td> +<td align="left"> +<p class="tent">Processor utilization for scheduling.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>PRI</b></p> +</td> +<td align="left"> +<p class="tent">(l)</p> +</td> +<td align="left"> +<p class="tent">The priority of the process; higher numbers mean lower priority.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>NI</b></p> +</td> +<td align="left"> +<p class="tent">(l)</p> +</td> +<td align="left"> +<p class="tent">Nice value; used in priority computation.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>ADDR</b></p> +</td> +<td align="left"> +<p class="tent">(l)</p> +</td> +<td align="left"> +<p class="tent">The address of the process.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>SZ</b></p> +</td> +<td align="left"> +<p class="tent">(l)</p> +</td> +<td align="left"> +<p class="tent">The size in pages of the total memory requirements of the process, including text, data, stack, mapped memory and +other resources.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>WCHAN</b></p> +</td> +<td align="left"> +<p class="tent">(l)</p> +</td> +<td align="left"> +<p class="tent">The event for which the process is waiting or sleeping; if blank, the process is running.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>STIME</b></p> +</td> +<td align="left"> +<p class="tent">(f)</p> +</td> +<td align="left"> +<p class="tent">Starting time of the process.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>TTY</b></p> +</td> +<td align="left"> +<p class="tent">(all)</p> +</td> +<td align="left"> +<p class="tent">The controlling terminal for the process.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>TIME</b></p> +</td> +<td align="left"> +<p class="tent">(all)</p> +</td> +<td align="left"> +<p class="tent">The cumulative execution time for the process.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>CMD</b></p> +</td> +<td align="left"> +<p class="tent">(all)</p> +</td> +<td align="left"> +<p class="tent">The command name; the full command name and its arguments are written under the <b>-f</b> option.</p> +</td> +</tr> +</table> +<p class="tent">A process that has exited and has a parent, but has not yet been waited for by the parent, shall be marked +<b>defunct</b>.</p> +<p class="tent">Under the option <b>-f</b>, <i>ps</i> tries to determine the command name and arguments given when the process was +created by examining memory or the swap area. Failing this, the command name, as it would appear without the option <b>-f</b>, is +written in square brackets. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p> +<p class="tent">The <b>-o</b> option allows the output format to be specified under user control.</p> +<p class="tent">The application shall ensure that the format specification is a list of names presented as a single argument, +<blank> or <comma>-separated. Each variable has a default header. The default header can be overridden by appending an +<equals-sign> and the new text of the header. The rest of the characters in the argument shall be used as the header text. +The fields specified shall be written in the order specified on the command line, and should be arranged in columns in the output. +The field widths shall be selected by the system to be at least as wide as the header text (default or overridden value). If the +header text is null, such as <b>-o</b> <i>user</i>=, the field width shall be at least as wide as the default header text. If all +header text fields are null, no header line shall be written.</p> +<p class="tent">The following names are recognized in the POSIX locale:</p> +<dl compact> +<dd></dd> +<dt><b>ruser</b></dt> +<dd>The real user ID of the process. This shall be the textual user ID, if it can be obtained and the field width permits, or a +decimal representation otherwise.</dd> +<dt><b>user</b></dt> +<dd>The effective user ID of the process. This shall be the textual user ID, if it can be obtained and the field width permits, or +a decimal representation otherwise.</dd> +<dt><b>rgroup</b></dt> +<dd>The real group ID of the process. This shall be the textual group ID, if it can be obtained and the field width permits, or a +decimal representation otherwise.</dd> +<dt><b>group</b></dt> +<dd>The effective group ID of the process. This shall be the textual group ID, if it can be obtained and the field width permits, +or a decimal representation otherwise.</dd> +<dt><b>pid</b></dt> +<dd>The decimal value of the process ID.</dd> +<dt><b>ppid</b></dt> +<dd>The decimal value of the parent process ID.</dd> +<dt><b>pgid</b></dt> +<dd>The decimal value of the process group ID.</dd> +<dt><b>pcpu</b></dt> +<dd>The ratio of CPU time used recently to CPU time available in the same period, expressed as a percentage. The meaning of +"recently" in this context is unspecified. The CPU time available is determined in an unspecified manner.</dd> +<dt><b>vsz</b></dt> +<dd>The size of the process in (virtual) memory in 1024 byte units as a decimal integer.</dd> +<dt><b>nice</b></dt> +<dd>The decimal value of the nice value of the process; see <a href="../utilities/nice.html"><i>nice</i></a>.</dd> +<dt><b>etime</b></dt> +<dd>In the POSIX locale, the elapsed time since the process was started, in the form: +<pre> +<b>[[</b><i>dd</i><tt>-</tt><b>]</b><i>hh</i><tt>:</tt><b>]</b><i>mm</i><tt>:</tt><i>ss</i><tt> +</tt></pre> +<p class="tent">where <i>dd</i> shall represent the number of days, <i>hh</i> the number of hours, <i>mm</i> the number of minutes, +and <i>ss</i> the number of seconds. The <i>dd</i> field shall be a decimal integer. The <i>hh</i>, <i>mm</i>, and <i>ss</i> fields +shall be two-digit decimal integers padded on the left with zeros.</p> +</dd> +<dt><b>time</b></dt> +<dd>In the POSIX locale, the cumulative CPU time of the process in the form: +<pre> +<b>[</b><i>dd</i><tt>-</tt><b>]</b><i>hh</i><tt>:</tt><i>mm</i><tt>:</tt><i>ss</i><tt> +</tt></pre> +<p class="tent">The <i>dd</i>, <i>hh</i>, <i>mm</i>, and <i>ss</i> fields shall be as described in the <b>etime</b> specifier.</p> +</dd> +<dt><b>tty</b></dt> +<dd>The name of the controlling terminal of the process (if any) in the same format used by the <a href= +"../utilities/who.html"><i>who</i></a> utility.</dd> +<dt><b>comm</b></dt> +<dd>The name of the command being executed (<i>argv</i>[0] value) as a string.</dd> +<dt><b>args</b></dt> +<dd>The command with all its arguments as a string. The implementation may truncate this value to the field width; it is +implementation-defined whether any further truncation occurs. It is unspecified whether the string represented is a version of the +argument list as it was passed to the command when it started, or is a version of the arguments as they may have been modified by +the application. Applications cannot depend on being able to modify their argument list and having that modification be reflected +in the output of <i>ps</i>.</dd> +</dl> +<p class="tent">Any field need not be meaningful in all implementations. In such a case a <hyphen-minus> (<tt>'-'</tt>) +should be output in place of the field value.</p> +<p class="tent">Only <b>comm</b> and <b>args</b> shall be allowed to contain <blank> characters; all others shall not. Any +implementation-defined variables shall be specified in the system documentation along with the default header and indicating +whether the field may contain <blank> characters.</p> +<p class="tent">The following table specifies the default header to be used in the POSIX locale corresponding to each format +specifier.<br></p> +<p class="caption">Table: Variable Names and Default Headers in <i>ps</i></p> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Format Specifier</b></p> +</th> +<th align="center"> +<p class="tent"><b>Default Header</b></p> +</th> +<th align="center"> +<p class="tent"><b>Format Specifier</b></p> +</th> +<th align="center"> +<p class="tent"><b>Default Header</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>args</b></p> +</td> +<td align="left"> +<p class="tent"><b>COMMAND</b></p> +</td> +<td align="left"> +<p class="tent"><b>ppid</b></p> +</td> +<td align="left"> +<p class="tent"><b>PPID</b></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>comm</b></p> +</td> +<td align="left"> +<p class="tent"><b>COMMAND</b></p> +</td> +<td align="left"> +<p class="tent"><b>rgroup</b></p> +</td> +<td align="left"> +<p class="tent"><b>RGROUP</b></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>etime</b></p> +</td> +<td align="left"> +<p class="tent"><b>ELAPSED</b></p> +</td> +<td align="left"> +<p class="tent"><b>ruser</b></p> +</td> +<td align="left"> +<p class="tent"><b>RUSER</b></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>group</b></p> +</td> +<td align="left"> +<p class="tent"><b>GROUP</b></p> +</td> +<td align="left"> +<p class="tent"><b>time</b></p> +</td> +<td align="left"> +<p class="tent"><b>TIME</b></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>nice</b></p> +</td> +<td align="left"> +<p class="tent"><b>NI</b></p> +</td> +<td align="left"> +<p class="tent"><b>tty</b></p> +</td> +<td align="left"> +<p class="tent"><b>TT</b></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>pcpu</b></p> +</td> +<td align="left"> +<p class="tent"><b>%CPU</b></p> +</td> +<td align="left"> +<p class="tent"><b>user</b></p> +</td> +<td align="left"> +<p class="tent"><b>USER</b></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>pgid</b></p> +</td> +<td align="left"> +<p class="tent"><b>PGID</b></p> +</td> +<td align="left"> +<p class="tent"><b>vsz</b></p> +</td> +<td align="left"> +<p class="tent"><b>VSZ</b></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>pid</b></p> +</td> +<td align="left"> +<p class="tent"><b>PID</b></p> +</td> +<td align="left"> +<p class="tent"><b> </b></p> +</td> +<td align="left"> +<p class="tent"><b> </b></p> +</td> +</tr> +</table> +</center> +</blockquote> +<h4 class="mansect"><a name="tag_20_98_11" id="tag_20_98_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_98_12" id="tag_20_98_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_98_13" id="tag_20_98_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_98_14" id="tag_20_98_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_98_15" id="tag_20_98_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_98_16" id="tag_20_98_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Things can change while <i>ps</i> is running; the snapshot it gives is only true for an instant, and might not be accurate by +the time it is displayed.</p> +<p class="tent">The <b>args</b> format specifier is allowed to produce a truncated version of the command arguments. In some +implementations, this information is no longer available when the <i>ps</i> utility is executed.</p> +<p class="tent">If the field width is too narrow to display a textual ID, the system may use a numeric version. Normally, the +system would be expected to choose large enough field widths, but if a large number of fields were selected to write, it might +squeeze fields to their minimum sizes to fit on one line. One way to ensure adequate width for the textual IDs is to override the +default header for a field to make it larger than most or all user or group names.</p> +<p class="tent">Portable applications should not set <i>COLUMNS</i> to a value greater than {LINE_MAX} and should not specify the +<b>-w</b> option more than once if the output will be used as input for a utility that requires a text file as input because lines +containing more than {LINE_MAX} bytes may cause undefined behavior in some implementations of the utility.</p> +<p class="tent">There is no special quoting mechanism for header text. The header text is the rest of the argument. If multiple +header changes are needed, multiple <b>-o</b> options can be used, such as:</p> +<pre> +<tt>ps -o "user=User Name" -o pid=Process\ ID +</tt></pre> +<p class="tent">On some implementations, especially multi-level secure systems, <i>ps</i> may be severely restricted and produce +information only about child processes owned by the user.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_98_17" id="tag_20_98_17"></a>EXAMPLES</h4> +<blockquote> +<p>The command:</p> +<pre> +<tt>ps -o user,pid,ppid=MOM -o args +</tt></pre> +<p class="tent">writes at least the following in the POSIX locale:</p> +<pre> +<tt> USER PID MOM COMMAND +helene 34 12 ps -o user,pid,ppid=MOM -o args +</tt></pre> +<p class="tent">The contents of the <b>COMMAND</b> field need not be the same in all implementations, due to possible +truncation.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_98_18" id="tag_20_98_18"></a>RATIONALE</h4> +<blockquote> +<p>There is very little commonality between BSD and System V implementations of <i>ps</i>. Many options conflict or have subtly +different usages. The standard developers attempted to select a set of options for the base standard that were useful on a wide +range of systems and selected options that either can be implemented on both BSD and System V-based systems without breaking the +current implementations or where the options are sufficiently similar that any changes would not be unduly problematic for users or +implementors.</p> +<p class="tent">It is recognized that on some implementations, especially multi-level secure systems, <i>ps</i> may be nearly +useless. The default output has therefore been chosen such that it does not break historical implementations and also is likely to +provide at least some useful information on most systems.</p> +<p class="tent">The major change is the addition of the format specification capability. The motivation for this invention is to +provide a mechanism for users to access a wider range of system information, if the system permits it, in a portable manner. The +fields chosen to appear in this volume of POSIX.1-2024 were arrived at after considering what concepts were likely to be both +reasonably useful to the "average" user and had a reasonable chance of being implemented on a wide range of systems. Again it is +recognized that not all systems are able to provide all the information and, conversely, some may wish to provide more. It is hoped +that the approach adopted will be sufficiently flexible and extensible to accommodate most systems. Implementations may be expected +to introduce new format specifiers.</p> +<p class="tent">The default output should consist of a short listing containing the process ID, terminal name, cumulative execution +time, and command name of each process.</p> +<p class="tent">The preference of the standard developers would have been to make the format specification an operand of the +<i>ps</i> command. Unfortunately, BSD usage precluded this.</p> +<p class="tent">At one time a format was included to display the environment array of the process. This was deleted because there +is no portable way to display it.</p> +<p class="tent">The <b>-A</b> option is equivalent to the BSD <b>-g</b> and the SVID <b>-e</b>. Because the two systems differed, a +mnemonic compromise was selected.</p> +<p class="tent">The <b>-a</b> option is described with some optional behavior because the SVID omits session leaders, but BSD does +not.</p> +<p class="tent">In an early proposal, format specifiers appeared for priority and start time. The former was not defined adequately +in this volume of POSIX.1-2024 and was removed in deference to the defined nice value; the latter because elapsed time was +considered to be more useful.</p> +<p class="tent">In a new BSD version of <i>ps</i>, a <b>-O</b> option can be used to write all of the default information, followed +by additional format specifiers. This was not adopted because the default output is implementation-defined. Nevertheless, this is a +useful option that should be reserved for that purpose. In the <b>-o</b> option for the POSIX Shell and Utilities <i>ps</i>, the +format is the concatenation of each <b>-o</b>. Therefore, the user can have an alias or function that defines the beginning of +their desired format and add more fields to the end of the output in certain cases where that would be useful.</p> +<p class="tent">The format of the terminal name is unspecified, but the descriptions of <i>ps</i>, <a href= +"../utilities/talk.html"><i>talk</i></a>, <a href="../utilities/who.html"><i>who</i></a>, and <a href= +"../utilities/write.html"><i>write</i></a> require that they all use the same format.</p> +<p class="tent">The <b>pcpu</b> field indicates that the CPU time available is determined in an unspecified manner. This is because +it is difficult to express an algorithm that is useful across all possible machine architectures. Historical counterparts to this +value have attempted to show percentage of use in the recent past, such as the preceding minute. Frequently, these values for all +processes did not add up to 100%. Implementations are encouraged to provide data in this field to users that will help them +identify processes currently affecting the performance of the system.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_98_19" id="tag_20_98_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_98_20" id="tag_20_98_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/kill.html#tag_20_64"><i>kill</i></a> , <a href="../utilities/nice.html#tag_20_86"><i>nice</i></a> , +<a href="../utilities/renice.html#"><i>renice</i></a></p> +<p class="tent">XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_98_21" id="tag_20_98_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_98_22" id="tag_20_98_22"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +<p class="tent">The normative text is reworded to avoid use of the term "must" for application requirements.</p> +<p class="tent">The <i>TZ</i> entry is added to the ENVIRONMENT VARIABLES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_98_23" id="tag_20_98_23"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p class="tent">SD5-XCU-ERN-148 is applied, updating the OPTIONS section.</p> +<p class="tent">POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0160 [584] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_98_24" id="tag_20_98_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 905 is applied, adding the <b>-w</b> option.</p> +<p class="tent">Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p class="tent">Austin Group Defect 1141 is applied, changing the description of <b>SZ</b> in the STDOUT section.</p> +<p class="tent">Austin Group Defect 1175 is applied, changing "uid" to "user" in the EXAMPLES section.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/prs.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/pwd.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/pwd.html b/bdd/pwd.html @@ -0,0 +1,220 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>pwd</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/ps.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/read.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="pwd" id="pwd"></a> <a name="tag_20_99" id="tag_20_99"></a><!-- pwd --> +<h4 class="mansect"><a name="tag_20_99_01" id="tag_20_99_01"></a>NAME</h4> +<blockquote>pwd — return working directory name</blockquote> +<h4 class="mansect"><a name="tag_20_99_02" id="tag_20_99_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>pwd</tt> <b>[</b><tt>-L|-P</tt><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_99_03" id="tag_20_99_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>pwd</i> utility shall write to standard output an absolute pathname of the current working directory, which does not +contain the filenames dot or dot-dot.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_99_04" id="tag_20_99_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>pwd</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported by the implementation:</p> +<dl compact> +<dd></dd> +<dt><b>-L</b></dt> +<dd>If the <i>PWD</i> environment variable contains an absolute pathname of the current directory and the pathname does not contain +any components that are dot or dot-dot, <i>pwd</i> shall write this pathname to standard output, except that if the <i>PWD</i> +environment variable is longer than {PATH_MAX} bytes including the terminating null, it is unspecified whether <i>pwd</i> writes +this pathname to standard output or behaves as if the <b>-P</b> option had been specified. Otherwise, the <b>-L</b> option shall +behave as the <b>-P</b> option.</dd> +<dt><b>-P</b></dt> +<dd>The pathname written to standard output shall not contain any components that refer to files of type symbolic link. If there +are multiple pathnames that the <i>pwd</i> utility could write to standard output, one beginning with a single <slash> +character and one or more beginning with two <slash> characters, then it shall write the pathname beginning with a single +<slash> character. The pathname shall not contain any unnecessary <slash> characters after the leading one or two +<slash> characters.</dd> +</dl> +<p>If both <b>-L</b> and <b>-P</b> are specified, the last one shall apply. If neither <b>-L</b> nor <b>-P</b> is specified, the +<i>pwd</i> utility shall behave as if <b>-L</b> had been specified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_99_05" id="tag_20_99_05"></a>OPERANDS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_99_06" id="tag_20_99_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_99_07" id="tag_20_99_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_99_08" id="tag_20_99_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>pwd</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>PWD</i></dt> +<dd>An absolute pathname of the current working directory. If an application sets or unsets the value of <i>PWD ,</i> the behavior +of <i>pwd</i> is unspecified.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_99_09" id="tag_20_99_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_99_10" id="tag_20_99_10"></a>STDOUT</h4> +<blockquote> +<p>The <i>pwd</i> utility output is an absolute pathname of the current working directory:</p> +<pre> +<tt>"%s\n", <</tt><i>directory pathname</i><tt>> +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_99_11" id="tag_20_99_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_99_12" id="tag_20_99_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_99_13" id="tag_20_99_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_99_14" id="tag_20_99_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_99_15" id="tag_20_99_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>If an error is detected other than a write error when writing to standard output, no output shall be written to standard output, +a diagnostic message shall be written to standard error, and the exit status shall be non-zero.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_99_16" id="tag_20_99_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>If the pathname obtained from <i>pwd</i> is longer than {PATH_MAX} bytes, it could produce an error if passed to <a href= +"../utilities/cd.html"><i>cd</i></a>. Therefore, in order to return to that directory it may be necessary to break the pathname +into sections shorter than {PATH_MAX} and call <a href="../utilities/cd.html"><i>cd</i></a> on each section in turn (the first +section being an absolute pathname and subsequent sections being relative pathnames).</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_99_17" id="tag_20_99_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_99_18" id="tag_20_99_18"></a>RATIONALE</h4> +<blockquote> +<p>Some implementations have historically provided <i>pwd</i> as a shell special built-in command.</p> +<p>In most utilities, if an error occurs, partial output may be written to standard output. This does not happen in historical +implementations of <i>pwd</i> (unless an error condition causes a partial write). Because <i>pwd</i> is frequently used in +historical shell scripts without checking the exit status, it is important that the historical behavior is required here; +therefore, the CONSEQUENCES OF ERRORS section specifically disallows any partial output being written to standard output, except +when a write error occurs when writing to standard output.</p> +<p>An earlier version of this standard stated that the <i>PWD</i> environment variable was affected when the <b>-P</b> option was +in effect. This was incorrect; conforming implementations do not do this.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_99_19" id="tag_20_99_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_99_20" id="tag_20_99_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/cd.html#"><i>cd</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/getcwd.html#"><i>getcwd</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_99_21" id="tag_20_99_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_99_22" id="tag_20_99_22"></a>Issue 6</h4> +<blockquote> +<p>The <b>-P</b> and <b>-L</b> options are added to describe actions relating to symbolic links as specified in the +IEEE P1003.2b draft standard.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_99_23" id="tag_20_99_23"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #097 is applied.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>Changes to the <i>pwd</i> utility and <i>PWD</i> environment variable have been made to match the changes to the <a href= +"../functions/getcwd.html"><i>getcwd</i>()</a> function made for Austin Group Interpretation 1003.1-2001 #140.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0161 [471] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_99_24" id="tag_20_99_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to report an error if a utility is directed to display a +pathname that contains any bytes that have the encoded value of a <newline> character when <newline> is a terminator or +separator in the output format being used.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1488 is applied, clarifying the behavior when a write error occurs when writing to standard output.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/ps.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/read.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/read.html b/bdd/read.html @@ -0,0 +1,323 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>read</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/pwd.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/readlink.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="read" id="read"></a> <a name="tag_20_100" id="tag_20_100"></a><!-- read --> +<h4 class="mansect"><a name="tag_20_100_01" id="tag_20_100_01"></a>NAME</h4> +<blockquote>read — read from standard input into shell variables</blockquote> +<h4 class="mansect"><a name="tag_20_100_02" id="tag_20_100_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>read</tt> <b>[</b><tt>-r</tt><b>] [</b><tt>-d</tt> <i>delim</i><b>]</b> <i>var</i><tt>...</tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_100_03" id="tag_20_100_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>read</i> utility shall read a single logical line from standard input into one or more shell variables.</p> +<p>If the <b>-r</b> option is not specified, <backslash> shall act as an escape character. An unescaped <backslash> +shall preserve the literal value of a following <backslash> and shall prevent a following byte (if any) from being used to +split fields, with the exception of either <newline> or the logical line delimiter specified with the <b>-d</b> <i>delim</i> +option (if it is used and <i>delim</i> is not <newline>); it is unspecified which. If this excepted character follows the +<backslash>, the <i>read</i> utility shall interpret this as line continuation. The <backslash> and the excepted +character shall be removed before splitting the input into fields. All other unescaped <backslash> characters shall be +removed after splitting the input into fields.</p> +<p>If standard input is a terminal device and the invoking shell is interactive, <i>read</i> shall prompt for a continuation line +when it reads an input line ending with a <backslash> <newline>, unless the <b>-r</b> option is specified.</p> +<p>The terminating logical line delimiter (if any) shall be removed from the input. Then, if the shell variable <i>IFS</i> (see +<a href="../utilities/V3_chap02.html#tag_19_05_03"><i>2.5.3 Shell Variables</i></a> ) is set, and its value is an empty string, the +resulting data shall be assigned to the variable named by the first <i>var</i> operand, and the variables named by other <i>var</i> +operands (if any) shall be set to the empty string. No other processing shall be performed in this case.</p> +<p>If <i>IFS</i> is unset, or is set to any non-empty value, then a modified version of the field splitting algorithm specified in +<a href="../utilities/V3_chap02.html#tag_19_06_05"><i>2.6.5 Field Splitting</i></a> shall be applied, with the modifications as +follows:</p> +<ol> +<li> +<p>The input to the algorithm shall be the logical line (minus terminating delimiter) that was read from standard input, and shall +be considered as a single initial field, all of which resulted from expansions, with any escaped byte and the preceding +<backslash> escape character treated as if they were the result of a quoted expansion, and all other bytes treated as if they +were the results of unquoted expansions.</p> +</li> +<li> +<p>The loop over the contents of that initial field shall cease when either the input is empty or <i>n</i> output fields have been +generated, where <i>n</i> is one less than the number of <i>var</i> operands passed to the <i>read</i> utility. Any remaining input +in the original field being processed shall be returned to the <i>read</i> utility "unsplit"; that is, unmodified except that any +leading or trailing <i>IFS</i> white space, as defined in <a href="../utilities/V3_chap02.html#tag_19_06_05"><i>2.6.5 Field +Splitting</i></a> , shall be removed.</p> +</li> +</ol> +<p>The specified <i>var</i> operands shall be processed in the order they appear on the command line, and the output fields +generated by the field splitting algorithm shall be used in the order they were generated, by repeating the following checks until +neither is true:</p> +<ul> +<li> +<p>If more than one <i>var</i> operand is yet to be processed and one or more output fields are yet to be used, the variable named +by the first unprocessed <i>var</i> operand shall be assigned the value of the first unused output field.</p> +</li> +<li> +<p>If exactly one <i>var</i> operand is yet to be processed and there was some remaining unsplit input returned from the modified +field splitting algorithm, the variable named by the unprocessed <i>var</i> operand shall be assigned the unsplit input.</p> +</li> +</ul> +<p>If there are still one or more unprocessed <i>var</i> operands, each of the variables names by those operands shall be assigned +an empty string.</p> +<p>Note that in the case where just one <i>var</i> operand is given on the <i>read</i> command line, the modified field splitting +algorithm ceases after producing zero output fields and simply returns the original input field, with any leading and trailing +<i>IFS</i> white space removed, as unsplit input. This unsplit input is assigned to the variable named by the <i>var</i> +operand.</p> +<p>The setting of variables specified by the <i>var</i> operands shall affect the current shell execution environment; see <a href= +"../utilities/V3_chap02.html#tag_19_13"><i>2.13 Shell Execution Environment</i></a> . An error in setting any variable (such as if +a <i>var</i> has previously been marked <i>readonly</i>) shall be considered an error of <i>read</i> processing, and shall result +in a return value greater than one. Variables named before the one generating the error shall be set as described above; it is +unspecified whether variables named later shall be set as above, or <i>read</i> simply ceases processing when the error occurs, +leaving later named variables unaltered. If <i>read</i> is called in a subshell or separate utility execution environment, such as +one of the following:</p> +<pre> +<tt>(read foo) +nohup read ... +find . -exec read ... \; +</tt></pre> +<p>it shall not affect the shell variables in the caller's environment.</p> +<p>If end-of-file is detected before a terminating logical line delimiter is encountered, the variables specified by the <i>var</i> +operands shall be set as described above and the exit status shall be 1.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_100_04" id="tag_20_100_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>read</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-d</b> <i>delim</i></dt> +<dd>If <i>delim</i> consists of one single-byte character, that byte shall be used as the logical line delimiter. If <i>delim</i> +is the null string, the logical line delimiter shall be the null byte. Otherwise, the behavior is unspecified.</dd> +<dt><b>-r</b></dt> +<dd>Do not treat a <backslash> character in any special way. Consider each <backslash> to be part of the input +line.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_100_05" id="tag_20_100_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>var</i></dt> +<dd>The name of an existing or nonexisting shell variable. If a <i>var</i> operand names the variable <i>IFS ,</i> the behavior is +unspecified. +<p>If a <i>var</i> operand names one of the variables <i>LANG ,</i> <i>LC_CTYPE ,</i> or <i>LC_ALL</i> and the new value assigned +to the variable would change how the bytes in <i>IFS</i> form characters, or which characters in <i>IFS</i> are considered to be +<i>IFS</i> white space (see <a href="../utilities/V3_chap02.html#tag_19_06_05"><i>2.6.5 Field Splitting</i></a> ), it is +unspecified what effects, if any, the change has on how <i>read</i> performs field splitting.</p> +</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_100_06" id="tag_20_100_06"></a>STDIN</h4> +<blockquote> +<p>If the <b>-d</b> <i>delim</i> option is not specified, or if it is specified and <i>delim</i> is not the null string, the +standard input shall contain zero or more bytes (which need not form valid characters) and shall not contain any null bytes.</p> +<p>If the <b>-d</b> <i>delim</i> option is specified and <i>delim</i> is the null string, the standard input shall contain zero or +more bytes (which need not form valid characters).</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_100_07" id="tag_20_100_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_100_08" id="tag_20_100_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>read</i>:</p> +<dl compact> +<dd></dd> +<dt><i>IFS</i></dt> +<dd>Determine the internal field separators used to delimit fields; see <a href="../utilities/V3_chap02.html#tag_19_05_03"><i>2.5.3 +Shell Variables</i></a> .</dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>PS2</i></dt> +<dd>Provide the prompt string that an interactive shell shall write to standard error when a line ending with a <backslash> +<newline> is read and the <b>-r</b> option was not specified.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_100_09" id="tag_20_100_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_100_10" id="tag_20_100_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_100_11" id="tag_20_100_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used for diagnostic messages and prompts for continued input.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_100_12" id="tag_20_100_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_100_13" id="tag_20_100_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_100_14" id="tag_20_100_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt> 1</dt> +<dd>End-of-file was detected.</dd> +<dt>>1</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_100_15" id="tag_20_100_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_100_16" id="tag_20_100_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>This utility is required to be intrinsic. See <a href="../utilities/V3_chap01.html#tag_18_07"><i>1.7 Intrinsic Utilities</i></a> +for details.</p> +<p>The <b>-r</b> option is included to enable <i>read</i> to subsume the purpose of the <i>line</i> utility, which is not included +in POSIX.1-2024.</p> +<p>The <b>-d</b> <i>delim</i> option enables reading up to an arbitrary single-byte delimiter. When <i>delim</i> is the null +string, the delimiter is the null byte and this allows <i>read</i> to be used to process null-terminated lists of pathnames (as +produced by the <a href="../utilities/find.html"><i>find</i></a> <b>-print0</b> primary), with correct handling of pathnames that +contain <newline> characters. Note that in order to specify the null string as the delimiter, <b>-d</b> and <i>delim</i> need +to be specified as two separate arguments. Implementations differ in their handling of <backslash> for line continuation when +<b>-d</b> <i>delim</i> is specified (and <i>delim</i> is not <newline>); some treat <backslash><i>delim</i> (or +<backslash><NUL> if <i>delim</i> is the null string) as a line continuation, whereas others still treat +<backslash><newline> as a line continuation. Consequently, portable applications need to specify <b>-r</b> whenever +they specify <b>-d</b> <i>delim</i> (and <i>delim</i> is not <newline>).</p> +<p>When reading a pathname it is inadvisable to use the contents of the first <i>var</i> operand, if non-empty, when the exit +status of <i>read</i> is 1, as it is likely the result of the command used to generate the list of pathnames (for example <a href= +"../utilities/find.html"><i>find</i></a> with <b>-print</b> or <b>-print0</b>) being terminated after it has written a partial +pathname, and consequently using it could result in the wrong pathname being processed.</p> +<p>Since the <i>var</i> operands are processed in the order specified on the command line, if any variable name is specified more +than once as a <i>var</i> operand, the last assignment made is the one that is in effect when <i>read</i> returns, including when +an empty string is assigned because no field data was available.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_100_17" id="tag_20_100_17"></a>EXAMPLES</h4> +<blockquote> +<p>The following command:</p> +<pre> +<tt>while read -r xx yy +do + printf "%s %s\n" "$yy" "$xx" +done < </tt><i>input_file</i><tt> +</tt></pre> +<p>prints a file with the first field of each line moved to the end of the line.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_100_18" id="tag_20_100_18"></a>RATIONALE</h4> +<blockquote> +<p>The <i>read</i> utility historically has been a shell built-in. It was separated off into its own utility to take advantage of +the richer description of functionality introduced by this volume of POSIX.1-2024.</p> +<p>Since <i>read</i> affects the current shell execution environment, it is required to be intrinsic. If it is called in a subshell +or separate utility execution environment, such as one of the following:</p> +<pre> +<tt>(read foo) +nohup read ... +find . -exec read ... \; +</tt></pre> +<p>it does not affect the shell variables in the environment of the caller.</p> +<p>Earlier versions of this standard required the standard input to be a text file, and therefore the results were undefined if the +input was not empty and end-of-file was detected before a <newline> character was encountered. However, all of the most +popular shell implementations have been found to have consistent behavior in this case, and so the behavior is now specified and +the requirement for standard input to be a text file has been relaxed to allow non-empty input that does not end with a +<newline>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_100_19" id="tag_20_100_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_100_20" id="tag_20_100_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19"><i>2. Shell Command Language</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_100_21" id="tag_20_100_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_100_22" id="tag_20_100_22"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #194 is applied, clarifying the handling of the <backslash> escape character.</p> +<p>SD5-XCU-ERN-126 is applied, clarifying that input lines end with a <newline>.</p> +<p>The description of here-documents is removed from the <i>read</i> reference page.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0162 [958] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_100_23" id="tag_20_100_23"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 243 is applied, adding the <b>-d</b> option and relaxing the requirement for standard input to be a text +file.</p> +<p>Austin Group Defect 367 is applied, requiring that <i>read</i> distinguishes between detecting end-of-file and an error +occurring, setting its exit status to one and greater than one, respectively.</p> +<p>Austin Group Defect 854 is applied, adding a note to the APPLICATION USAGE section that this utility is required to be +intrinsic.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1778 is applied, clarifying how field splitting is performed.</p> +<p>Austin Group Defect 1779 is applied, clarifying how an error in setting any variable affects the processing of variables named +before or after the one generating the error.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/pwd.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/readlink.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/readlink.html b/bdd/readlink.html @@ -0,0 +1,186 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>readlink</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/read.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/realpath.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="readlink" id="readlink"></a> <a name="tag_20_101" id="tag_20_101"></a><!-- readlink --> +<h4 class="mansect"><a name="tag_20_101_01" id="tag_20_101_01"></a>NAME</h4> +<blockquote>readlink — display the contents of a symbolic link</blockquote> +<h4 class="mansect"><a name="tag_20_101_02" id="tag_20_101_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>readlink</tt> <b>[</b><tt>-n</tt><b>]</b> <i>file</i></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_101_03" id="tag_20_101_03"></a>DESCRIPTION</h4> +<blockquote> +<p>If the <i>file</i> operand names a symbolic link, the <i>readlink</i> utility shall not follow the symbolic link when resolving +<i>file</i> and shall write the contents of the symbolic link to standard output. If the <b>-n</b> option is not specified, the +output to standard output shall be followed by a <newline> character.</p> +<p>If <i>file</i> does not name a symbolic link, <i>readlink</i> shall write a diagnostic message to standard error and exit with +non-zero status.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_101_04" id="tag_20_101_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>readlink</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following option shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-n</b></dt> +<dd>Do not output a trailing <newline> character.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_101_05" id="tag_20_101_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of a symbolic link to be read.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_101_06" id="tag_20_101_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_101_07" id="tag_20_101_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_101_08" id="tag_20_101_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>readlink</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_101_09" id="tag_20_101_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_101_10" id="tag_20_101_10"></a>STDOUT</h4> +<blockquote> +<p>See DESCRIPTION.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_101_11" id="tag_20_101_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_101_12" id="tag_20_101_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_101_13" id="tag_20_101_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_101_14" id="tag_20_101_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_101_15" id="tag_20_101_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_101_16" id="tag_20_101_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_101_17" id="tag_20_101_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_101_18" id="tag_20_101_18"></a>RATIONALE</h4> +<blockquote> +<p>The <i>readlink</i> utility was added because using <a href="../utilities/ls.html"><i>ls</i></a> <b>-l</b> to obtain the +contents of a symbolic link is difficult if the output includes more than one occurrence of the string <tt>" -> "</tt>.</p> +<p>The <b>-f</b> option found in many implementations was not included, as the <a href= +"../utilities/realpath.html"><i>realpath</i></a> utility provides equivalent functionality with a choice of behaviors.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_101_19" id="tag_20_101_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_101_20" id="tag_20_101_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/ln.html#"><i>ln</i></a> , <a href="../utilities/ls.html#"><i>ls</i></a> , <a href= +"../utilities/realpath.html#tag_20_102"><i>realpath</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/readlink.html#"><i>readlink</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_101_21" id="tag_20_101_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 8.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/read.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/realpath.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/realpath.html b/bdd/realpath.html @@ -0,0 +1,239 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>realpath</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/readlink.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/renice.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="realpath" id="realpath"></a> <a name="tag_20_102" id="tag_20_102"></a><!-- realpath --> +<h4 class="mansect"><a name="tag_20_102_01" id="tag_20_102_01"></a>NAME</h4> +<blockquote>realpath — resolve a pathname</blockquote> +<h4 class="mansect"><a name="tag_20_102_02" id="tag_20_102_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>realpath</tt> <b>[</b><tt>-E|-e</tt><b>]</b> <i>file</i></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_102_03" id="tag_20_102_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>realpath</i> utility shall canonicalize the pathname specified by the <i>file</i> operand as follows:</p> +<p>If a call to the <a href="../functions/realpath.html"><i>realpath</i>()</a> function with the specified pathname as its first +argument would succeed, the canonicalized pathname shall be the pathname that would be returned by that <a href= +"../functions/realpath.html"><i>realpath</i>()</a> call. Otherwise:</p> +<ul> +<li> +<p>If the <b>-e</b> option is specified, the canonicalization shall fail.</p> +</li> +<li> +<p>If the <b>-E</b> option is specified, then if a call to the <a href="../functions/realpath.html"><i>realpath</i>()</a> function +with the specified pathname as its first argument would encounter an error condition other than [ENOENT], the canonicalization +shall fail; if the call would encounter an [ENOENT] error, <i>realpath</i> shall expand all symbolic links that would be +encountered in an attempt to resolve the specified pathname using the algorithm specified in XBD <a href= +"../basedefs/V1_chap04.html#tag_04_16"><i>4.16 Pathname Resolution</i></a> , except that any trailing <slash> characters that +are not also leading <slash> characters shall be ignored. If this expansion succeeds and the path prefix of the expanded +pathname resolves to an existing directory, the canonicalized pathname shall be the expanded pathname. In all other cases, the +canonicalization shall fail. If the expanded pathname is not empty, does not begin with a <slash>, and has exactly one +pathname component, it shall be treated as if it had a path prefix of <tt>"./"</tt>.</p> +</li> +<li> +<p>If no options are specified, <i>realpath</i> shall canonicalize the specified pathname in an unspecified manner such that the +resulting absolute pathname does not contain any components that refer to files of type symbolic link and does not contain any +components that are dot or dot-dot.</p> +</li> +</ul> +<p>Upon successful canonicalization, <i>realpath</i> shall write the canonicalized pathname, followed by a <newline> +character, to standard output.</p> +<p>If canonicalization fails, or the canonicalized pathname is empty, nothing shall be written to standard output, a diagnostic +message shall be written to standard error, and <i>realpath</i> shall exit with non-zero status.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_102_04" id="tag_20_102_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>realpath</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-E</b></dt> +<dd>Do not treat it as an error if attempting to resolve the last component of the canonicalized form of the <i>file</i> operand +results in an [ENOENT] error condition.</dd> +<dt><b>-e</b></dt> +<dd>Treat it as an error if attempting to resolve the last component of the canonicalized form of the <i>file</i> operand results +in an [ENOENT] error condition.</dd> +</dl> +<p>Specifying more than one of the mutually-exclusive options <b>-E</b> and <b>-e</b> shall not be considered an error. The last +option specified shall determine the behavior of the utility.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_102_05" id="tag_20_102_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname to be canonicalized.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_102_06" id="tag_20_102_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_102_07" id="tag_20_102_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_102_08" id="tag_20_102_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>realpath</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_102_09" id="tag_20_102_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_102_10" id="tag_20_102_10"></a>STDOUT</h4> +<blockquote> +<p>See DESCRIPTION.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_102_11" id="tag_20_102_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_102_12" id="tag_20_102_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_102_13" id="tag_20_102_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_102_14" id="tag_20_102_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_102_15" id="tag_20_102_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_102_16" id="tag_20_102_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>If neither the <b>-e</b> nor the <b>-E</b> option is specified, some implementations behave as if <b>-e</b> had been specified +and others as if <b>-E</b> had been specified, but there are also implementations where the behavior differs from both of these. +For example, the <i>mksh</i> shell has an internal implementation of <i>realpath</i> that canonicalizes <b>/dir/regular_file/..</b> +to <b>/dir</b>, whereas the <a href="../functions/realpath.html"><i>realpath</i>()</a> function would return an [ENOTDIR] error in +this case. Portable applications should always specify either <b>-e</b> or <b>-E</b>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_102_17" id="tag_20_102_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_102_18" id="tag_20_102_18"></a>RATIONALE</h4> +<blockquote> +<p>The <i>realpath</i> utility was added in preference to a <b>-f</b> option found in some implementations of the <a href= +"../utilities/readlink.html"><i>readlink</i></a> utility because it allows the application to specify whether or not a missing +final component is to be treated as an error.</p> +<p>The behavior with the <b>-E</b> option when <i>file</i> does not resolve (with symbolic links followed) to an existing file is +not the same as simply calling <a href="../functions/realpath.html"><i>realpath</i>()</a> with the path prefix of the <i>file</i> +operand and writing the resulting pathname, a <slash>, and the last component of <i>file</i> to standard output. For example, +if <b>/tmp/nofile</b> does not exist, and <i>file</i> is <b>A/B</b> where <b>A</b> is an existing directory and <b>B</b> is a +symbolic link to <b>/tmp/nofile</b>, <i>realpath</i> with <b>-E</b> will output <b>/tmp/nofile</b>, but if <b>B</b> is a symbolic +link to <b>/tmp/nofile/foo</b>, <i>realpath</i> with <b>-E</b> will treat this as an error. In both cases <tt>realpath("A/B")</tt> +would fail with <i>errno</i> set to [ENOENT]. Even though <tt>realpath("A")</tt> would succeed, in neither case is anything ending +<b>/B</b> the result.</p> +<p>Trailing <slash> characters (that follow a non-<slash>) are handled differently with <b>-E</b> than with <b>-e</b>. +With <b>-e</b> they are handled as for the <a href="../functions/realpath.html"><i>realpath</i>()</a> function. With <b>-E</b> they +are sometimes effectively ignored, and they are never included in the output. For example, if <b>/tmp/nofile</b> does not exist and +<b>/tmp/regfile</b> is an existing regular file:</p> +<pre> +<tt>$ realpath -E /tmp/nofile/ +/tmp/nofile +$ realpath -E /tmp/regfile/ +realpath: /tmp/regfile/: Not a directory +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_102_19" id="tag_20_102_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_102_20" id="tag_20_102_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/ln.html#"><i>ln</i></a> , <a href="../utilities/ls.html#"><i>ls</i></a> , <a href= +"../utilities/pwd.html#"><i>pwd</i></a> , <a href="../utilities/readlink.html#tag_20_101"><i>readlink</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/V2_chap02.html#tag_16_03"><i>2.3 Error Numbers</i></a> , <a href= +"../functions/realpath.html#"><i>realpath</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_102_21" id="tag_20_102_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 8.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/readlink.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/renice.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/renice.html b/bdd/renice.html @@ -0,0 +1,269 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>renice</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/realpath.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/rm.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="renice" id="renice"></a> <a name="tag_20_103" id="tag_20_103"></a><!-- renice --> +<h4 class="mansect"><a name="tag_20_103_01" id="tag_20_103_01"></a>NAME</h4> +<blockquote>renice — set nice values of running processes</blockquote> +<h4 class="mansect"><a name="tag_20_103_02" id="tag_20_103_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>renice</tt> <b>[</b><tt>-g|-p|-u</tt><b>]</b> <tt>-n</tt> <i>increment ID</i><tt>...</tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_103_03" id="tag_20_103_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>renice</i> utility shall request that the nice values (see XBD <a href="../basedefs/V1_chap03.html#tag_03_225"><i>3.225 +Nice Value</i></a> ) of one or more running processes be changed. By default, the applicable processes are specified by their +process IDs. When a process group is specified (see <b>-g</b>), the request shall apply to all processes in the process group.</p> +<p>The nice value shall be bounded in an implementation-defined manner. If the requested <i>increment</i> would raise or lower the +nice value of the executed utility beyond implementation-defined limits, then the limit whose value was exceeded shall be used.</p> +<p>When a user is <i>renice</i>d, the request applies to all processes whose saved set-user-ID matches the user ID corresponding to +the user.</p> +<p>Regardless of which options are supplied or any other factor, <i>renice</i> shall not alter the nice values of any process +unless the user requesting such a change has appropriate privileges to do so for the specified process. If the user lacks +appropriate privileges to perform the requested action, the utility shall return an error status.</p> +<p>The saved set-user-ID of the user's process shall be checked instead of its effective user ID when <i>renice</i> attempts to +determine the user ID of the process in order to determine whether the user has appropriate privileges.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_103_04" id="tag_20_103_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>renice</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> , except for Guideline 9.</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-g</b></dt> +<dd>Interpret the following operands as unsigned decimal integer process group IDs.</dd> +<dt><b>-n </b><i>increment</i></dt> +<dd>Specify how the nice value of the specified process or processes is to be adjusted. The <i>increment</i> option-argument is a +positive or negative decimal integer that shall be used to modify the nice value of the specified process or processes. Negative +<i>increment</i> values may require appropriate privileges.</dd> +<dt><b>-p</b></dt> +<dd>Interpret the following operands as unsigned decimal integer process IDs. The <b>-p</b> option is the default if no options are +specified.</dd> +<dt><b>-u</b></dt> +<dd>Interpret the following operands as users. If a user exists with a user name equal to the operand, then the user ID of that +user is used in further processing. Otherwise, if the operand represents an unsigned decimal integer, it shall be used as the +numeric user ID of the user.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_103_05" id="tag_20_103_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>ID</i></dt> +<dd>A process ID, process group ID, or user name/user ID, depending on the option selected.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_103_06" id="tag_20_103_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_103_07" id="tag_20_103_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_103_08" id="tag_20_103_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>renice</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_103_09" id="tag_20_103_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_103_10" id="tag_20_103_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_103_11" id="tag_20_103_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_103_12" id="tag_20_103_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_103_13" id="tag_20_103_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_103_14" id="tag_20_103_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_103_15" id="tag_20_103_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_103_16" id="tag_20_103_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_103_17" id="tag_20_103_17"></a>EXAMPLES</h4> +<blockquote> +<ol> +<li> +<p>Adjust the nice value so that process IDs 987 and 32 would have a lower nice value:</p> +<pre> +<tt>renice -n 5 -p 987 32 +</tt></pre></li> +<li> +<p>Adjust the nice value so that group IDs 324 and 76 would have a higher nice value, if the user has appropriate privileges to do +so:</p> +<pre> +<tt>renice -n -4 -g 324 76 +</tt></pre></li> +<li> +<p>Adjust the nice value so that numeric user ID 8 and user <b>sas</b> would have a lower nice value:</p> +<pre> +<tt>renice -n 4 -u 8 sas +</tt></pre></li> +</ol> +<p>Useful nice value increments on historical systems include 19 or 20 (the affected processes run only when nothing else in the +system attempts to run) and any negative number (to make processes run faster).</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_103_18" id="tag_20_103_18"></a>RATIONALE</h4> +<blockquote> +<p>The <i>gid</i>, <i>pid</i>, and <i>user</i> specifications do not fit either the definition of operand or option-argument. +However, for clarity, they have been included in the OPTIONS section, rather than the OPERANDS section.</p> +<p>The definition of nice value is not intended to suggest that all processes in a system have priorities that are comparable. +Scheduling policy extensions such as the realtime priorities in the System Interfaces volume of POSIX.1-2024 make the notion of a +single underlying priority for all scheduling policies problematic. Some implementations may implement the <a href= +"../utilities/nice.html"><i>nice</i></a>-related features to affect all processes on the system, others to affect just the general +time-sharing activities implied by this volume of POSIX.1-2024, and others may have no effect at all. Because of the use of +"implementation-defined" in <a href="../utilities/nice.html"><i>nice</i></a> and <i>renice</i>, a wide range of implementation +strategies are possible.</p> +<p>Originally, this utility was written in the historical manner, using the term "nice value". This was always a point of concern +with users because it was never intuitively obvious what this meant. With a newer version of <i>renice</i>, which used the term +"system scheduling priority", it was hoped that novice users could better understand what this utility was meant to do. Also, it +would be easier to document what the utility was meant to do. Unfortunately, the addition of the POSIX realtime scheduling +capabilities introduced the concepts of process and thread scheduling priorities that were totally unaffected by the <a href= +"../utilities/nice.html"><i>nice</i></a>/<a href="../utilities/renice.html"><i>renice</i></a> utilities or the <a href= +"../functions/nice.html"><i>nice</i>()</a>/<a href="../functions/setpriority.html"><i>setpriority</i>()</a> functions. Continuing +to use the term "system scheduling priority" would have incorrectly suggested that these utilities and functions were indeed +affecting these realtime priorities. It was decided to revert to the historical term "nice value" to reference this unrelated +process attribute.</p> +<p>Although this utility has use by system administrators (and in fact appears in the system administration portion of the BSD +documentation), the standard developers considered that it was very useful for individual end users to control their own +processes.</p> +<p>Earlier versions of this standard allowed the following forms in the SYNOPSIS:</p> +<pre> +<tt>renice </tt><i>nice_value</i><b>[</b><tt>-p</tt><b>] </b><i>pid</i><tt>...</tt><b>[</b><tt>-g </tt><i>gid</i><tt>...</tt><b>][</b><tt>-p </tt><i>pid</i><tt>...</tt><b>][</b><tt>-u </tt><i>user</i><tt>...</tt><b>]</b><tt> +renice </tt><i>nice_value -g gid</i><tt>...</tt><b>[</b><tt>-g </tt><i>gid</i><tt>...</tt><b>]</b><tt>-p </tt><i>pid</i><tt>...</tt><b>][</b><tt>-u </tt><i>user</i><tt>...</tt><b>]</b><tt> +renice </tt><i>nice_value -u user</i><tt>...</tt><b>[</b><tt>-g </tt><i>gid</i><tt>...</tt><b>]</b><tt>-p </tt><i>pid</i><tt>...</tt><b>][</b><tt>-u </tt><i>user</i><tt>...</tt><b>]</b><tt> +</tt></pre> +<p>These forms are no longer specified by POSIX.1-2024 but may be present in some implementations.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_103_19" id="tag_20_103_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_103_20" id="tag_20_103_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/nice.html#tag_20_86"><i>nice</i></a></p> +<p>XBD <a href="../basedefs/V1_chap03.html#tag_03_225"><i>3.225 Nice Value</i></a> , <a href= +"../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 +Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_103_21" id="tag_20_103_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_103_22" id="tag_20_103_22"></a>Issue 5</h4> +<blockquote> +<p>In the SYNOPSIS, an ellipsis is added to the <b>-u</b> option in all three obsolescent forms.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_103_23" id="tag_20_103_23"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +<p>The APPLICATION USAGE section is added.</p> +<p>The obsolescent forms of the SYNOPSIS are removed.</p> +<p>Text previously conditional on POSIX_SAVED_IDS is mandatory in this version. This is a FIPS requirement.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_103_24" id="tag_20_103_24"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #027 is applied, clarifying that Guideline 9 of the Utility Syntax Guidelines does not +apply.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>The <i>renice</i> utility is moved from the User Portability Utilities option to the Base. User Portability Utilities is now an +option for interactive utilities.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_103_25" id="tag_20_103_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1286 is applied, changing the description of the <b>-n</b> option.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/realpath.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/rm.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/rm.html b/bdd/rm.html @@ -0,0 +1,374 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>rm</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/renice.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/rmdel.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="rm" id="rm"></a> <a name="tag_20_104" id="tag_20_104"></a><!-- rm --> +<h4 class="mansect"><a name="tag_20_104_01" id="tag_20_104_01"></a>NAME</h4> +<blockquote>rm — remove directory entries</blockquote> +<h4 class="mansect"><a name="tag_20_104_02" id="tag_20_104_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>rm</tt> <b>[</b><tt>-diRrv</tt><b>]</b> <i>file</i><tt>...<br> +<br> +rm -f</tt> <b>[</b><tt>-diRrv</tt><b>]</b> <b>[</b><i>file</i><tt>...</tt><b>]</b> <tt><br></tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_104_03" id="tag_20_104_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>rm</i> utility shall remove the directory entry specified by each <i>file</i> argument.</p> +<p>If either of the files dot or dot-dot are specified as the basename portion of an operand (that is, the final pathname +component) or if an operand resolves to the root directory, <i>rm</i> shall write a diagnostic message to standard error and do +nothing more with such operands.</p> +<p>For each <i>file</i> the following steps shall be taken:</p> +<ol> +<li> +<p>If the <i>file</i> does not exist:</p> +<ol type="a"> +<li> +<p>If the <b>-f</b> option is not specified, <i>rm</i> shall write a diagnostic message to standard error.</p> +</li> +<li> +<p>Go on to any remaining <i>files</i>.</p> +</li> +</ol> +</li> +<li> +<p>If <i>file</i> is of type directory, the following steps shall be taken:</p> +<ol type="a"> +<li> +<p>If neither the <b>-R</b> option nor the <b>-r</b> option is specified, but <b>-d</b> is specified, <i>rm</i> shall proceed with +step 3 for the current file. If none of <b>-r</b>, <b>-R</b>, or <b>-d</b> is specified, <i>rm</i> shall write a diagnostic message +to standard error, do nothing more with <i>file</i>, and go on to any remaining files.</p> +</li> +<li> +<p>If <i>file</i> is an empty directory, <i>rm</i> may skip to step 2d. If the <b>-f</b> option is not specified, and either the +permissions of <i>file</i> do not permit writing and the standard input is a terminal or the <b>-i</b> option is specified, +<i>rm</i> shall write a prompt to standard error and read a line from the standard input. If the response is not affirmative, +<i>rm</i> shall do nothing more with the current file and go on to any remaining files.</p> +</li> +<li> +<p>For each entry contained in <i>file</i>, other than dot or dot-dot, the four steps listed here (1 to 4) shall be taken with the +entry as if it were a <i>file</i> operand. The <i>rm</i> utility shall not traverse directories by following symbolic links into +other parts of the hierarchy, but shall remove the links themselves.</p> +</li> +<li> +<p>If the <b>-i</b> option is specified, <i>rm</i> shall write a prompt to standard error and read a line from the standard input. +If the response is not affirmative, <i>rm</i> shall do nothing more with the current file, and go on to any remaining files.</p> +</li> +<li> +<p><i>rm</i> shall proceed with step 4 for the current file.</p> +</li> +</ol> +</li> +<li> +<p>If the <b>-f</b> option is not specified, and either the permissions of <i>file</i> do not permit writing and the standard input +is a terminal or the <b>-i</b> option is specified, <i>rm</i> shall write a prompt to the standard error and read a line from the +standard input. If the response is not affirmative, <i>rm</i> shall do nothing more with the current file and go on to any +remaining files.</p> +</li> +<li> +<p><i>rm</i> shall perform actions equivalent to the <a href="../functions/remove.html"><i>remove</i>()</a> function defined in the +System Interfaces volume of POSIX.1-2024 called with a pathname of the current file used as the <i>path</i> argument.</p> +<p>If <i>rm</i> successfully performed the above actions on the current file, and the <b>-v</b> option is specified, <i>rm</i> +shall write a message containing the pathname of the current file to the standard output. If the actions fail for any reason, +<i>rm</i> shall write a diagnostic message to standard error, do nothing more with the current file, and go on to any remaining +files.</p> +</li> +</ol> +<p>The <i>rm</i> utility shall be able to descend to arbitrary depths in a file hierarchy, and shall not fail due to path length +limitations (unless an operand specified by the user exceeds system limitations).</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_104_04" id="tag_20_104_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>rm</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-d</b></dt> +<dd>Remove empty directories. See the DESCRIPTION.</dd> +<dt><b>-f</b></dt> +<dd>Do not prompt for confirmation. Do not write diagnostic messages or modify the exit status in the case of no file operands, or +in the case of operands that do not exist. Any previous occurrences of the <b>-i</b> option shall be ignored.</dd> +<dt><b>-i</b></dt> +<dd>Prompt for confirmation as described previously. Any previous occurrences of the <b>-f</b> option shall be ignored.</dd> +<dt><b>-R</b></dt> +<dd>Remove file hierarchies. See the DESCRIPTION.</dd> +<dt><b>-r</b></dt> +<dd>Equivalent to <b>-R</b>.</dd> +<dt><b>-v</b></dt> +<dd>After each file has been removed, write a message to standard output indicating that it has been removed.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_104_05" id="tag_20_104_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of a directory entry to be removed.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_104_06" id="tag_20_104_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be used to read an input line in response to each prompt specified in the STDOUT section. Otherwise, +the standard input shall not be used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_104_07" id="tag_20_104_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_104_08" id="tag_20_104_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>rm</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_COLLATE</i></dt> +<dd><br> +Determine the locale for the behavior of ranges, equivalence classes, and multi-character collating elements used in the extended +regular expression defined for the <b>yesexpr</b> locale keyword in the <i>LC_MESSAGES</i> category.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments) and the behavior of character classes within regular expressions used in the +extended regular expression defined for the <b>yesexpr</b> locale keyword in the <i>LC_MESSAGES</i> category.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale used to process affirmative responses, and the locale used to affect the format and contents of diagnostic +messages and prompts written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_104_09" id="tag_20_104_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_104_10" id="tag_20_104_10"></a>STDOUT</h4> +<blockquote> +<p>If the <b>-v</b> option is specified, information about each removed file shall be written to standard output in an unspecified +format.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_104_11" id="tag_20_104_11"></a>STDERR</h4> +<blockquote> +<p>Prompts shall be written to standard error under the conditions specified in the DESCRIPTION and OPTIONS sections. The prompts +shall contain the <i>file</i> pathname, but their format is otherwise unspecified. The standard error also shall be used for +diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_104_12" id="tag_20_104_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_104_13" id="tag_20_104_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_104_14" id="tag_20_104_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>All requested directory entries (excluding directory entries where a non-affirmative response was given to a request for +confirmation) were successfully deleted. In addition, if the <b>-v</b> option is specified, information about each removed +directory entry was successfully written to standard output.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_104_15" id="tag_20_104_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_104_16" id="tag_20_104_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The <i>rm</i> utility is forbidden to remove the names dot and dot-dot in order to avoid the consequences of inadvertently doing +something like:</p> +<pre> +<tt>rm -r .* +</tt></pre> +<p>Some implementations do not permit the removal of the last hard link to an executable binary file that is being executed; see +the [EBUSY] error in the <a href="../functions/unlink.html"><i>unlink</i>()</a> function defined in the System Interfaces volume of +POSIX.1-2024. Thus, the <i>rm</i> utility can fail to remove such files.</p> +<p>The <b>-i</b> option causes <i>rm</i> to prompt and read the standard input even if the standard input is not a terminal, but in +the absence of <b>-i</b> the mode prompting is not done when the standard input is not a terminal.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_104_17" id="tag_20_104_17"></a>EXAMPLES</h4> +<blockquote> +<ol> +<li> +<p>The following command:</p> +<pre> +<tt>rm a.out core +</tt></pre> +<p>removes the directory entries: <b>a.out</b> and <b>core</b>, or issues an error if either directory entry is itself a directory +or does not exist.</p> +</li> +<li> +<p>The following command:</p> +<pre> +<tt>rm -Rf junk +</tt></pre> +<p>removes the directory <b>junk</b> and all its contents, without prompting.</p> +</li> +<li> +<p>The following command:</p> +<pre> +<tt>rm -d name +</tt></pre> +<p>behaves like</p> +<pre> +<tt>rmdir name +</tt></pre> +<p>if <b>name</b> is a directory (including failing if <b>name</b> is not empty), as if by the <a href= +"../functions/rmdir.html"><i>rmdir</i>()</a> function; and behaves like</p> +<pre> +<tt>rm name +</tt></pre> +<p>if <b>name</b> is not a directory, as if by the <a href="../functions/unlink.html"><i>unlink</i>()</a> function.</p> +</li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_104_18" id="tag_20_104_18"></a>RATIONALE</h4> +<blockquote> +<p>For absolute clarity, paragraphs (2b) and (3) in the DESCRIPTION of <i>rm</i> describing the behavior when prompting for +confirmation, should be interpreted in the following manner:</p> +<pre> +<tt>if ((NOT f_option) AND + ((not_writable AND input_is_terminal) OR i_option)) +</tt></pre> +<p>The exact format of the interactive prompts is unspecified. Only the general nature of the contents of prompts are specified +because implementations may desire more descriptive prompts than those used on historical implementations. Therefore, an +application not using the <b>-f</b> option, or using the <b>-i</b> option, relies on the system to provide the most suitable dialog +directly with the user, based on the behavior specified.</p> +<p>The <b>-r</b> option is historical practice on all known systems. The synonym <b>-R</b> option is provided for consistency with +the other utilities in this volume of POSIX.1-2024 that provide options requesting recursive descent through the file +hierarchy.</p> +<p>The behavior of the <b>-f</b> option in historical versions of <i>rm</i> is inconsistent. In general, along with "forcing" the +unlink without prompting for permission, it always causes diagnostic messages to be suppressed and the exit status to be unmodified +for nonexistent operands and files that cannot be unlinked. In some versions, however, the <b>-f</b> option suppresses usage +messages and system errors as well. Suppressing such messages is not a service to either shell scripts or users.</p> +<p>It is less clear that error messages regarding files that cannot be unlinked (removed) should be suppressed. Although this is +historical practice, this volume of POSIX.1-2024 does not permit the <b>-f</b> option to suppress such messages.</p> +<p>When given the <b>-r</b> and <b>-i</b> options, historical versions of <i>rm</i> prompt the user twice for each directory, once +before removing its contents and once before actually attempting to delete the directory entry that names it. This allows the user +to "prune" the file hierarchy walk. Historical versions of <i>rm</i> were inconsistent in that some did not do the former prompt +for directories named on the command line and others had obscure prompting behavior when the <b>-i</b> option was specified and the +permissions of the file did not permit writing. The POSIX Shell and Utilities <i>rm</i> differs little from historic practice, but +does require that prompts be consistent. Historical versions of <i>rm</i> were also inconsistent in that prompts were done to both +standard output and standard error. This volume of POSIX.1-2024 requires that prompts be done to standard error, for consistency +with <a href="../utilities/cp.html"><i>cp</i></a> and <a href="../utilities/mv.html"><i>mv</i></a>, and to allow historical +extensions to <i>rm</i> that provide an option to list deleted files on standard output.</p> +<p>The <i>rm</i> utility is required to descend to arbitrary depths so that any file hierarchy may be deleted. This means, for +example, that the <i>rm</i> utility cannot run out of file descriptors during its descent (that is, if the number of file +descriptors is limited, <i>rm</i> cannot be implemented in the historical fashion where one file descriptor is used per directory +level). Also, <i>rm</i> is not permitted to fail because of path length restrictions, unless an operand specified by the user is +longer than {PATH_MAX}.</p> +<p>The <i>rm</i> utility removes symbolic links themselves, not the files they refer to, as a consequence of the dependence on the +<a href="../functions/unlink.html"><i>unlink</i>()</a> functionality, per the DESCRIPTION. When removing hierarchies with <b>-r</b> +or <b>-R</b>, the prohibition on following symbolic links has to be made explicit.</p> +<p>The addition of the <b>-d</b> option allows the use of <i>rm</i> to delete either a file or an empty directory without the risk +of recursion into a non-empty directory, and without the inherent race between determining a file's type and deciding what action +to attempt on that file. If either the <b>-r</b> or <b>-R</b> option is specified, the use of recursion takes precedence.</p> +<p>The addition of the <b>-v</b> option allows a user of <i>rm</i> to see which files have been deleted.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_104_19" id="tag_20_104_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_104_20" id="tag_20_104_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/rmdir.html#tag_20_106"><i>rmdir</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/remove.html#"><i>remove</i></a> , <a href="../functions/rmdir.html#tag_17_493"><i>rmdir</i></a> , +<a href="../functions/unlink.html#tag_17_649"><i>unlink</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_104_21" id="tag_20_104_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_104_22" id="tag_20_104_22"></a>Issue 5</h4> +<blockquote> +<p>The FUTURE DIRECTIONS section is added.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_104_23" id="tag_20_104_23"></a>Issue 6</h4> +<blockquote> +<p>Text is added to clarify actions relating to symbolic links as specified in the IEEE P1003.2b draft standard.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_104_24" id="tag_20_104_24"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretations 1003.1-2001 #019 and #091 are applied.</p> +<p>Austin Group Interpretation 1003.1-2001 #126 is applied, changing the description of the <i>LC_MESSAGES</i> environment +variable.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0163 [542], XCU/TC2-2008/0164 [819], and XCU/TC2-2008/0165 [542] are +applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_104_25" id="tag_20_104_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to report an error if a utility is directed to display a +pathname that contains any bytes that have the encoded value of a <newline> character when <newline> is a terminator or +separator in the output format being used.</p> +<p>Austin Group Defect 802 is applied, adding the <b>-d</b> option.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defects 1154, 1365, and 1487 are applied, adding the <b>-v</b> option.</p> +<p>Austin Group Defect 1380 is applied, changing "last link" to "last hard link".</p> +<p>Austin Group Defect 1732 is applied, changing the EXIT STATUS section.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/renice.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/rmdel.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/rmdel.html b/bdd/rmdel.html @@ -0,0 +1,214 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>rmdel</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/rm.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/rmdir.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="rmdel" id="rmdel"></a> <a name="tag_20_105" id="tag_20_105"></a><!-- rmdel --> +<h4 class="mansect"><a name="tag_20_105_01" id="tag_20_105_01"></a>NAME</h4> +<blockquote>rmdel — remove a delta from an SCCS file (<b>DEVELOPMENT</b>)</blockquote> +<h4 class="mansect"><a name="tag_20_105_02" id="tag_20_105_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> rmdel -r</tt> <i>SID file</i><tt>... <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></tt></code></div> +</blockquote> +<h4 class="mansect"><a name="tag_20_105_03" id="tag_20_105_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>rmdel</i> utility shall remove the delta specified by the SID from each named SCCS file. The delta to be removed shall be +the most recent delta in its branch in the delta chain of each named SCCS file. In addition, the application shall ensure that the +SID specified is not that of a version being edited for the purpose of making a delta; that is, if a <i>p-file</i> (see <a href= +"../utilities/get.html#"><i>get</i></a> ) exists for the named SCCS file, the SID specified shall not appear in any entry of the +<i>p-file</i>.</p> +<p>Removal of a delta shall be restricted to:</p> +<ol> +<li> +<p>The user who made the delta</p> +</li> +<li> +<p>The owner of the SCCS file</p> +</li> +<li> +<p>The owner of the directory containing the SCCS file</p> +</li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_105_04" id="tag_20_105_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>rmdel</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following option shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-r </b><i>SID</i></dt> +<dd>Specify the SCCS identification string (<i>SID</i>) of the delta to be deleted.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_105_05" id="tag_20_105_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of an existing SCCS file or a directory. If <i>file</i> is a directory, the <i>rmdel</i> utility shall behave as +though each file in the directory were specified as a named file, except that non-SCCS files (last component of the pathname does +not begin with <b>s.</b>) and unreadable files shall be silently ignored. +<p>If exactly one <i>file</i> operand appears, and it is <tt>'-'</tt>, the standard input shall be read; each line of the standard +input is taken to be the name of an SCCS file to be processed. Non-SCCS files and unreadable files shall be silently ignored.</p> +</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_105_06" id="tag_20_105_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be a text file used only when the <i>file</i> operand is specified as <tt>'-'</tt>. Each line of the +text file shall be interpreted as an SCCS pathname.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_105_07" id="tag_20_105_07"></a>INPUT FILES</h4> +<blockquote> +<p>The SCCS files shall be files of unspecified format.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_105_08" id="tag_20_105_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>rmdel</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd>Determine the location of messages objects and message catalogs.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_105_09" id="tag_20_105_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_105_10" id="tag_20_105_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_105_11" id="tag_20_105_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_105_12" id="tag_20_105_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>The SCCS files shall be files of unspecified format. During processing of a <i>file</i>, a temporary <i>x-file</i>, as described +in <a href="../utilities/admin.html#"><i>admin</i></a> , may be created and deleted; a locking <i>z-file</i>, as described in +<a href="../utilities/get.html#"><i>get</i></a> , may be created and deleted.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_105_13" id="tag_20_105_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_105_14" id="tag_20_105_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_105_15" id="tag_20_105_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_105_16" id="tag_20_105_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_105_17" id="tag_20_105_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_105_18" id="tag_20_105_18"></a>RATIONALE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_105_19" id="tag_20_105_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a +<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require +implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_105_20" id="tag_20_105_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/admin.html#"><i>admin</i></a> , <a href="../utilities/delta.html#"><i>delta</i></a> , <a href= +"../utilities/get.html#"><i>get</i></a> , <a href="../utilities/prs.html#"><i>prs</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_105_21" id="tag_20_105_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_105_22" id="tag_20_105_22"></a>Issue 6</h4> +<blockquote> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_105_23" id="tag_20_105_23"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to disallow the creation of filenames containing any bytes that +have the encoded value of a <newline> character.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/rm.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/rmdir.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/rmdir.html b/bdd/rmdir.html @@ -0,0 +1,213 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>rmdir</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/rmdel.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/sact.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="rmdir" id="rmdir"></a> <a name="tag_20_106" id="tag_20_106"></a><!-- rmdir --> +<h4 class="mansect"><a name="tag_20_106_01" id="tag_20_106_01"></a>NAME</h4> +<blockquote>rmdir — remove directories</blockquote> +<h4 class="mansect"><a name="tag_20_106_02" id="tag_20_106_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>rmdir</tt> <b>[</b><tt>-p</tt><b>]</b> <i>dir</i><tt>...</tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_106_03" id="tag_20_106_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>rmdir</i> utility shall remove the directory entry specified by each <i>dir</i> operand.</p> +<p>For each <i>dir</i> operand, the <i>rmdir</i> utility shall perform actions equivalent to the <a href= +"../functions/rmdir.html"><i>rmdir</i>()</a> function called with the <i>dir</i> operand as its only argument.</p> +<p>Directories shall be processed in the order specified. If a directory and a subdirectory of that directory are specified in a +single invocation of the <i>rmdir</i> utility, the application shall specify the subdirectory before the parent directory so that +the parent directory is empty when the <i>rmdir</i> utility tries to remove it.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_106_04" id="tag_20_106_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>rmdir</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following option shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-p</b></dt> +<dd>Remove all directories in a pathname. For each <i>dir</i> operand: +<ol> +<li> +<p>The directory entry it names shall be removed.</p> +</li> +<li> +<p>If the <i>dir</i> operand includes more than one pathname component, effects equivalent to the following command shall +occur:</p> +<pre> +<tt>rmdir -p $(dirname </tt><i>dir</i><tt>) +</tt></pre></li> +</ol> +</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_106_05" id="tag_20_106_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>dir</i></dt> +<dd>A pathname of an empty directory to be removed.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_106_06" id="tag_20_106_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_106_07" id="tag_20_106_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_106_08" id="tag_20_106_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>rmdir</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_106_09" id="tag_20_106_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_106_10" id="tag_20_106_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_106_11" id="tag_20_106_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_106_12" id="tag_20_106_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_106_13" id="tag_20_106_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_106_14" id="tag_20_106_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Each directory entry specified by a <i>dir</i> operand was removed successfully.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_106_15" id="tag_20_106_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_106_16" id="tag_20_106_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The definition of an empty directory is one that contains, at most, directory entries for dot and dot-dot.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_106_17" id="tag_20_106_17"></a>EXAMPLES</h4> +<blockquote> +<p>If a directory <b>a</b> in the current directory is empty except it contains a directory <b>b</b> and <b>a/b</b> is empty except +it contains a directory <b>c</b>:</p> +<pre> +<tt>rmdir -p a/b/c +</tt></pre> +<p>removes all three directories.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_106_18" id="tag_20_106_18"></a>RATIONALE</h4> +<blockquote> +<p>On historical System V systems, the <b>-p</b> option also caused a message to be written to the standard output. The message +indicated whether the whole path was removed or whether part of the path remained for some reason. The STDERR section requires this +diagnostic when the entire path specified by a <i>dir</i> operand is not removed, but does not allow the status message reporting +success to be written as a diagnostic.</p> +<p>The <i>rmdir</i> utility on System V also included a <b>-s</b> option that suppressed the informational message output by the +<b>-p</b> option. This option has been omitted because the informational message is not specified by this volume of +POSIX.1-2024.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_106_19" id="tag_20_106_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_106_20" id="tag_20_106_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/rm.html#"><i>rm</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/remove.html#"><i>remove</i></a> , <a href="../functions/rmdir.html#tag_17_493"><i>rmdir</i></a> , +<a href="../functions/unlink.html#tag_17_649"><i>unlink</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_106_21" id="tag_20_106_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_106_22" id="tag_20_106_22"></a>Issue 6</h4> +<blockquote> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_106_23" id="tag_20_106_23"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/rmdel.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/sact.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/sact.html b/bdd/sact.html @@ -0,0 +1,211 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>sact</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/rmdir.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/sccs.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="sact" id="sact"></a> <a name="tag_20_107" id="tag_20_107"></a><!-- sact --> +<h4 class="mansect"><a name="tag_20_107_01" id="tag_20_107_01"></a>NAME</h4> +<blockquote>sact — print current SCCS file-editing activity (<b>DEVELOPMENT</b>)</blockquote> +<h4 class="mansect"><a name="tag_20_107_02" id="tag_20_107_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> sact</tt> <i>file</i><tt>... <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></tt></code></div> +</blockquote> +<h4 class="mansect"><a name="tag_20_107_03" id="tag_20_107_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>sact</i> utility shall inform the user of any impending deltas to a named SCCS file by writing a list to standard output. +This situation occurs when <a href="../utilities/get.html"><i>get</i></a> <b>-e</b> has been executed previously without a +subsequent execution of <a href="../utilities/delta.html"><i>delta</i></a>, <a href="../utilities/unget.html"><i>unget</i></a>, or +<a href="../utilities/sccs.html"><i>sccs</i></a> <b>unedit</b>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_107_04" id="tag_20_107_04"></a>OPTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_107_05" id="tag_20_107_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of an existing SCCS file or a directory. If <i>file</i> is a directory, the <i>sact</i> utility shall behave as +though each file in the directory were specified as a named file, except that non-SCCS files (last component of the pathname does +not begin with <b>s.</b>) and unreadable files shall be silently ignored. +<p>If exactly one <i>file</i> operand appears, and it is <tt>'-'</tt>, the standard input shall be read; each line of the standard +input shall be taken to be the name of an SCCS file to be processed. Non-SCCS files and unreadable files shall be silently +ignored.</p> +</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_107_06" id="tag_20_107_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be a text file used only when the <i>file</i> operand is specified as <tt>'-'</tt>. Each line of the +text file shall be interpreted as an SCCS pathname.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_107_07" id="tag_20_107_07"></a>INPUT FILES</h4> +<blockquote> +<p>Any SCCS files interrogated are files of an unspecified format.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_107_08" id="tag_20_107_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>sact</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd>Determine the location of messages objects and message catalogs.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_107_09" id="tag_20_107_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_107_10" id="tag_20_107_10"></a>STDOUT</h4> +<blockquote> +<p>The output for each named file shall consist of a line in the following format:</p> +<pre> +<tt>"%sΔ%sΔ%sΔ%sΔ%s\n", <</tt><i>SID</i><tt>>, <</tt><i>new SID</i><tt>>, <</tt><i>login</i><tt>>, <</tt><i>date</i><tt>>, <</tt><i>time</i><tt>> +</tt></pre> +<dl compact> +<dd></dd> +<dt><<i>SID</i>></dt> +<dd>Specifies the SID of a delta that currently exists in the SCCS file to which changes are made to make the new delta.</dd> +<dt><<i>new SID</i>></dt> +<dd>Specifies the SID for the new delta to be created.</dd> +<dt><<i>login</i>></dt> +<dd>Contains the login name of the user who makes the delta (that is, who executed a <a href="../utilities/get.html"><i>get</i></a> +for editing).</dd> +<dt><<i>date</i>></dt> +<dd>Contains the date that <a href="../utilities/get.html"><i>get</i></a> <b>-e</b> was executed, in the format used by the +<a href="../utilities/prs.html"><i>prs</i></a> <b>:D:</b> data keyword.</dd> +<dt><<i>time</i>></dt> +<dd>Contains the time that <a href="../utilities/get.html"><i>get</i></a> <b>-e</b> was executed, in the format used by the +<a href="../utilities/prs.html"><i>prs</i></a> <b>:T:</b> data keyword.</dd> +</dl> +<p>If there is more than one named file or if a directory or standard input is named, each pathname shall be written before each of +the preceding lines:</p> +<pre> +<tt>"\n%s:\n", <</tt><i>pathname</i><tt>> +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_107_11" id="tag_20_107_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for optional informative messages concerning SCCS files with no impending deltas, and for +diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_107_12" id="tag_20_107_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_107_13" id="tag_20_107_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_107_14" id="tag_20_107_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_107_15" id="tag_20_107_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_107_16" id="tag_20_107_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_107_17" id="tag_20_107_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_107_18" id="tag_20_107_18"></a>RATIONALE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_107_19" id="tag_20_107_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_107_20" id="tag_20_107_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/delta.html#"><i>delta</i></a> , <a href="../utilities/get.html#"><i>get</i></a> , <a href= +"../utilities/sccs.html#"><i>sccs</i></a> , <a href="../utilities/unget.html#"><i>unget</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_107_21" id="tag_20_107_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_107_22" id="tag_20_107_22"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to report an error if a utility is directed to display a +pathname that contains any bytes that have the encoded value of a <newline> character when <newline> is a terminator or +separator in the output format being used.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/rmdir.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/sccs.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/sccs.html b/bdd/sccs.html @@ -0,0 +1,347 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>sccs</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/sact.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/sed.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="sccs" id="sccs"></a> <a name="tag_20_108" id="tag_20_108"></a><!-- sccs --> +<h4 class="mansect"><a name="tag_20_108_01" id="tag_20_108_01"></a>NAME</h4> +<blockquote>sccs — front end for the SCCS subsystem (<b>DEVELOPMENT</b>)</blockquote> +<h4 class="mansect"><a name="tag_20_108_02" id="tag_20_108_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> sccs</tt> <b>[</b><tt>-r</tt><b>] [</b><tt>-d</tt> <i>path</i><b>] [</b><tt>-p</tt> +<i>path</i><b>]</b> <i>command</i> <b>[</b><i>options</i><tt>...</tt><b>] [</b><i>operands</i><tt>...</tt><b>]</b> <tt><img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div> +</blockquote> +<h4 class="mansect"><a name="tag_20_108_03" id="tag_20_108_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>sccs</i> utility is a front end to the SCCS programs. It also includes the capability to run set-user-id to another user +to provide additional protection.</p> +<p>The <i>sccs</i> utility shall invoke the specified <i>command</i> with the specified <i>options</i> and <i>operands</i>. By +default, each of the <i>operands</i> shall be modified by prefixing it with the string <tt>"SCCS/s."</tt>.</p> +<p>The <i>command</i> can be the name of one of the SCCS utilities in this volume of POSIX.1-2024 (<a href= +"../utilities/admin.html"><i>admin</i></a>, <a href="../utilities/delta.html"><i>delta</i></a>, <a href= +"../utilities/get.html"><i>get</i></a>, <a href="../utilities/prs.html"><i>prs</i></a>, <a href= +"../utilities/rmdel.html"><i>rmdel</i></a>, <a href="../utilities/sact.html"><i>sact</i></a>, <a href= +"../utilities/unget.html"><i>unget</i></a>, <a href="../utilities/val.html"><i>val</i></a>, or <a href= +"../utilities/what.html"><i>what</i></a>) or one of the pseudo-utilities listed in the EXTENDED DESCRIPTION section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_108_04" id="tag_20_108_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>sccs</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> , except that <i>options</i> operands are actually options to be passed to the utility named by <i>command</i>. +When the portion of the command:</p> +<pre> +<i>command </i><b>[</b><i>options</i><tt> ... </tt><b>] [</b><i>operands</i><tt> ... </tt><b>]</b><tt> +</tt></pre> +<p>is considered, all of the pseudo-utilities used as <i>command</i> shall support the Utility Syntax Guidelines. Any of the other +SCCS utilities that can be invoked in this manner support the Guidelines to the extent indicated by their individual OPTIONS +sections.</p> +<p>The following options shall be supported preceding the <i>command</i> operand:</p> +<dl compact> +<dd></dd> +<dt><b>-d </b><i>path</i></dt> +<dd>A pathname of a directory to be used as a root directory for the SCCS files. The default shall be the current directory. The +<b>-d</b> option shall take precedence over the <i>PROJECTDIR</i> variable. See <b>-p</b>.</dd> +<dt><b>-p </b><i>path</i></dt> +<dd>A pathname of a directory in which the SCCS files are located. The default shall be the <b>SCCS</b> directory. +<p>The <b>-p</b> option differs from the <b>-d</b> option in that the <b>-d</b> option-argument shall be prefixed to the entire +pathname and the <b>-p</b> option-argument shall be inserted before the final component of the pathname. For example:</p> +<pre> +<tt>sccs -d /x -p y get a/b +</tt></pre> +<p>converts to:</p> +<pre> +<tt>get /x/a/y/s.b +</tt></pre> +<p>This allows the creation of aliases such as:</p> +<pre> +<tt>alias syssccs="sccs -d /usr/src" +</tt></pre> +<p>which is used as:</p> +<pre> +<tt>syssccs get cmd/who.c +</tt></pre></dd> +<dt><b>-r</b></dt> +<dd>Invoke <i>command</i> with the real user ID of the process, not any effective user ID that the <i>sccs</i> utility is set to. +Certain commands (<a href="../utilities/admin.html"><i>admin</i></a>, <b>check</b>, <b>clean</b>, <b>diffs</b>, <b>info</b>, +<a href="../utilities/rmdel.html"><i>rmdel</i></a>, and <b>tell</b>) cannot be run set-user-ID by all users, since this would allow +anyone to change the authorizations. These commands are always run as the real user.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_108_05" id="tag_20_108_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>command</i></dt> +<dd>An SCCS utility name or the name of one of the pseudo-utilities listed in the EXTENDED DESCRIPTION section.</dd> +<dt><i>options</i></dt> +<dd>An option or option-argument to be passed to <i>command</i>.</dd> +<dt><i>operands</i></dt> +<dd>An operand to be passed to <i>command</i>.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_108_06" id="tag_20_108_06"></a>STDIN</h4> +<blockquote> +<p>See the utility description for the specified <i>command</i>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_108_07" id="tag_20_108_07"></a>INPUT FILES</h4> +<blockquote> +<p>See the utility description for the specified <i>command</i>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_108_08" id="tag_20_108_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>sccs</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd>Determine the location of messages objects and message catalogs.</dd> +<dt><i>PROJECTDIR</i></dt> +<dd><br> +Provide a default value for the <b>-d</b> <i>path</i> option. If the value of <i>PROJECTDIR</i> begins with a <slash>, it +shall be considered an absolute pathname; otherwise, the value of <i>PROJECTDIR</i> is treated as a user name and that user's +initial working directory shall be examined for a subdirectory <b>src</b> or <b>source</b>. If such a directory is found, it shall +be used. Otherwise, the value shall be used as a relative pathname.</dd> +</dl> +<p>Additional environment variable effects may be found in the utility description for the specified <i>command</i>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_108_09" id="tag_20_108_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_108_10" id="tag_20_108_10"></a>STDOUT</h4> +<blockquote> +<p>See the utility description for the specified <i>command</i>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_108_11" id="tag_20_108_11"></a>STDERR</h4> +<blockquote> +<p>See the utility description for the specified <i>command</i>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_108_12" id="tag_20_108_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>See the utility description for the specified <i>command</i>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_108_13" id="tag_20_108_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>The following pseudo-utilities shall be supported as <i>command</i> operands. All options referred to in the following list are +values given in the <i>options</i> operands following <i>command</i>.</p> +<dl compact> +<dd></dd> +<dt><b>check</b></dt> +<dd>Equivalent to <b>info</b>, except that nothing shall be printed if nothing is being edited, and a non-zero exit status shall be +returned if anything is being edited. The intent is to have this included in an "install" entry in a makefile to ensure that +everything is included into the SCCS file before a version is installed.</dd> +<dt><b>clean</b></dt> +<dd>Remove everything from the current directory that can be recreated from SCCS files, but do not remove any files being edited. +If the <b>-b</b> option is given, branches shall be ignored in the determination of whether they are being edited; this is +dangerous if branches are kept in the same directory.</dd> +<dt><b>create</b></dt> +<dd>Create an SCCS file, taking the initial contents from the file of the same name. Any options to <a href= +"../utilities/admin.html"><i>admin</i></a> are accepted. If the creation is successful, the original files shall be renamed by +prefixing the basenames with a comma. These renamed files should be removed after it has been verified that the SCCS files have +been created successfully.</dd> +<dt><b>delget</b></dt> +<dd>Perform a <a href="../utilities/delta.html"><i>delta</i></a> on the named files and then <a href= +"../utilities/get.html"><i>get</i></a> new versions. The new versions shall have ID keywords expanded and shall not be editable. +Any <b>-m</b>, <b>-p</b>, <b>-r</b>, <b>-s</b>, and <b>-y</b> options shall be passed to <a href= +"../utilities/delta.html"><i>delta</i></a>, and any <b>-b</b>, <b>-c</b>, <b>-e</b>, <b>-i</b>, <b>-k</b>, <b>-l</b>, <b>-s</b>, +and <b>-x</b> options shall be passed to <a href="../utilities/get.html"><i>get</i></a>.</dd> +<dt><b>deledit</b></dt> +<dd>Equivalent to <b>delget</b>, except that the <a href="../utilities/get.html"><i>get</i></a> phase shall include the <b>-e</b> +option. This option is useful for making a checkpoint of the current editing phase. The same options shall be passed to <a href= +"../utilities/delta.html"><i>delta</i></a> as described above, and all the options listed for <a href= +"../utilities/get.html"><i>get</i></a> above except <b>-e</b> shall be passed to <b>edit</b>.</dd> +<dt><b>diffs</b></dt> +<dd>Write a difference listing between the current version of the files checked out for editing and the versions in SCCS format. +Any <b>-r</b>, <b>-c</b>, <b>-i</b>, <b>-x</b>, and <b>-t</b> options shall be passed to <a href= +"../utilities/get.html"><i>get</i></a>; any <b>-l</b>, <b>-s</b>, <b>-e</b>, <b>-f</b>, <b>-h</b>, and <b>-b</b> options shall be +passed to <a href="../utilities/diff.html"><i>diff</i></a>. A <b>-C</b> option shall be passed to <a href= +"../utilities/diff.html"><i>diff</i></a> as <b>-c</b>.</dd> +<dt><b>edit</b></dt> +<dd>Equivalent to <a href="../utilities/get.html"><i>get</i></a> <b>-e</b>.</dd> +<dt><b>fix</b></dt> +<dd>Remove the named delta, but leave a copy of the delta with the changes that were in it. It is useful for fixing small compiler +bugs, and so on. The application shall ensure that it is followed by a <b>-r</b> <i>SID</i> option. Since <b>fix</b> does not leave +audit trails, it should be used carefully.</dd> +<dt><b>info</b></dt> +<dd>Write a listing of all files being edited. If the <b>-b</b> option is given, branches (that is, SIDs with two or fewer +components) shall be ignored. If a <b>-u</b> <i>user</i> option is given, then only files being edited by the named user shall be +listed. A <b>-U</b> option shall be equivalent to <b>-u</b><<i>current user</i>>.</dd> +<dt><b>print</b></dt> +<dd>Write out verbose information about the named files, equivalent to <i>sccs</i> <a href= +"../utilities/prs.html"><i>prs</i></a>.</dd> +<dt><b>tell</b></dt> +<dd>Write a <newline>-separated list of the files being edited to standard output. Takes the <b>-b</b>, <b>-u</b>, and +<b>-U</b> options like <b>info</b> and <b>check</b>.</dd> +<dt><b>unedit</b></dt> +<dd>This is the opposite of an <b>edit</b> or a <a href="../utilities/get.html"><i>get</i></a> <b>-e</b>. It should be used with +caution, since any changes made since the <a href="../utilities/get.html"><i>get</i></a> are lost.</dd> +</dl> +<br></blockquote> +<h4 class="mansect"><a name="tag_20_108_14" id="tag_20_108_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_108_15" id="tag_20_108_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_108_16" id="tag_20_108_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Many of the SCCS utilities take directory names as operands as well as specific filenames. The pseudo-utilities supported by +<i>sccs</i> are not described as having this capability, but are not prohibited from doing so.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_108_17" id="tag_20_108_17"></a>EXAMPLES</h4> +<blockquote> +<ol> +<li> +<p>To get a file for editing, edit it and produce a new delta:</p> +<pre> +<tt>sccs get -e file.c +ex file.c +sccs delta file.c +</tt></pre></li> +<li> +<p>To get a file from another directory:</p> +<pre> +<tt>sccs -p /usr/src/sccs/s. get cc.c +</tt></pre> +<p>or:</p> +<pre> +<tt>sccs get /usr/src/sccs/s.cc.c +</tt></pre></li> +<li> +<p>To make a delta of a large number of files in the current directory:</p> +<pre> +<tt>sccs delta *.c +</tt></pre></li> +<li> +<p>To get a list of files being edited that are not on branches:</p> +<pre> +<tt>sccs info -b +</tt></pre></li> +<li> +<p>To delta everything being edited by the current user:</p> +<pre> +<tt>sccs delta $(sccs tell -U) +</tt></pre></li> +<li> +<p>In a makefile, to get source files from an SCCS file if it does not already exist:</p> +<pre> +<tt>SRCS = <</tt><i>list of source files</i><tt>> +$(SRCS): + sccs get $(REL) $@ +</tt></pre></li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_108_18" id="tag_20_108_18"></a>RATIONALE</h4> +<blockquote> +<p><i>sccs</i> and its associated utilities are part of the XSI Development Utilities option within the XSI option.</p> +<p>SCCS is an abbreviation for Source Code Control System. It is a maintenance and enhancement tracking tool. When a file is put +under SCCS, the source code control system maintains the file and, when changes are made, identifies and stores them in the file +with the original source code and/or documentation. As other changes are made, they too are identified and retained in the +file.</p> +<p>Retrieval of the original and any set of changes is possible. Any version of the file as it develops can be reconstructed for +inspection or additional modification. History data can be stored with each version, documenting why the changes were made, who +made them, and when they were made.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_108_19" id="tag_20_108_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_108_20" id="tag_20_108_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/admin.html#"><i>admin</i></a> , <a href="../utilities/delta.html#"><i>delta</i></a> , <a href= +"../utilities/get.html#"><i>get</i></a> , <a href="../utilities/make.html#"><i>make</i></a> , <a href= +"../utilities/prs.html#"><i>prs</i></a> , <a href="../utilities/rmdel.html#"><i>rmdel</i></a> , <a href= +"../utilities/sact.html#"><i>sact</i></a> , <a href="../utilities/unget.html#"><i>unget</i></a> , <a href= +"../utilities/val.html#"><i>val</i></a> , <a href="../utilities/what.html#"><i>what</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_108_21" id="tag_20_108_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_108_22" id="tag_20_108_22"></a>Issue 6</h4> +<blockquote> +<p>In the ENVIRONMENT VARIABLES section, the <i>PROJECTDIR</i> description is updated from "otherwise, the home directory of a +user of that name is examined" to "otherwise, the value of <i>PROJECTDIR</i> is treated as a user name and that user's initial +working directory is examined".</p> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_108_23" id="tag_20_108_23"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_108_24" id="tag_20_108_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/sact.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/sed.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/sed.html b/bdd/sed.html @@ -0,0 +1,662 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>sed</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/sccs.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/sh.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="sed" id="sed"></a> <a name="tag_20_109" id="tag_20_109"></a><!-- sed --> +<h4 class="mansect"><a name="tag_20_109_01" id="tag_20_109_01"></a>NAME</h4> +<blockquote>sed — stream editor</blockquote> +<h4 class="mansect"><a name="tag_20_109_02" id="tag_20_109_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>sed</tt> <b>[</b><tt>-En</tt><b>]</b> <i>script</i> <b>[</b><i>file</i><tt>...</tt><b>]</b> <tt><br> +<br> +sed</tt> <b>[</b><tt>-En</tt><b>]</b> <tt>-e</tt> <i>script</i> <b>[</b><tt>-e</tt> <i>script</i><b>]</b><tt>...</tt> +<b>[</b><tt>-f</tt> <i>script_file</i><b>]</b><tt>...</tt> <b>[</b><i>file</i><tt>...</tt><b>]</b> <tt><br> +<br> +sed</tt> <b>[</b><tt>-En</tt><b>] [</b><tt>-e</tt> <i>script</i><b>]</b><tt>... -f</tt> <i>script_file</i> <b>[</b><tt>-f</tt> +<i>script_file</i><b>]</b><tt>...</tt> <b>[</b><i>file</i><tt>...</tt><b>]</b> <tt><br></tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_109_03" id="tag_20_109_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>sed</i> utility is a stream editor that shall read one or more text files, make editing changes according to a script of +editing commands, and write the results to standard output. The script shall be obtained from either the <i>script</i> operand +string or a combination of the option-arguments from the <b>-e</b> <i>script</i> and <b>-f</b> <i>script_file</i> options.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_109_04" id="tag_20_109_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>sed</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> , except that the order of presentation of the <b>-e</b> and <b>-f</b> options is significant.</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-E</b></dt> +<dd>Match using extended regular expressions. Treat each pattern specified as an ERE, as described in XBD <a href= +"../basedefs/V1_chap09.html#tag_09_04"><i>9.4 Extended Regular Expressions</i></a> .</dd> +<dt><b>-e </b><i>script</i></dt> +<dd>Add the editing commands specified by the <i>script</i> option-argument to the end of the script of editing commands.</dd> +<dt><b>-f </b><i>script_file</i></dt> +<dd>Add the editing commands in the file <i>script_file</i> to the end of the script of editing commands.</dd> +<dt><b>-n</b></dt> +<dd>Suppress the default output (in which each line, after it is examined for editing, is written to standard output). Only lines +explicitly selected for output are written.</dd> +</dl> +<p>If any <b>-e</b> or <b>-f</b> options are specified, the script of editing commands shall initially be empty. The commands +specified by each <b>-e</b> or <b>-f</b> option shall be added to the script in the order specified. When each addition is made, if +the previous addition (if any) was from a <b>-e</b> option, a <newline> shall be inserted before the new addition. The +resulting script shall have the same properties as the <i>script</i> operand, described in the OPERANDS section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_109_05" id="tag_20_109_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of a file whose contents are read and edited. If multiple <i>file</i> operands are specified, the named files shall +be read in the order specified and the concatenation shall be edited. If no <i>file</i> operands are specified, the standard input +shall be used.</dd> +<dt><i>script</i></dt> +<dd>A string to be used as the script of editing commands. The application shall not present a <i>script</i> that violates the +restrictions of a text file except that the final character need not be a <newline>.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_109_06" id="tag_20_109_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be used if no <i>file</i> operands are specified, and shall be used if a <i>file</i> operand is +<tt>'-'</tt> and the implementation treats the <tt>'-'</tt> as meaning standard input. Otherwise, the standard input shall not be +used. See the INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_109_07" id="tag_20_109_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files shall be text files. The <i>script_file</i>s named by the <b>-f</b> option shall consist of editing +commands.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_109_08" id="tag_20_109_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>sed</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_COLLATE</i></dt> +<dd><br> +Determine the locale for the behavior of ranges, equivalence classes, and multi-character collating elements within regular +expressions.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files), and the behavior of character classes within regular +expressions.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_109_09" id="tag_20_109_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_109_10" id="tag_20_109_10"></a>STDOUT</h4> +<blockquote> +<p>The input files shall be written to standard output, with the editing commands specified in the script applied. If the <b>-n</b> +option is specified, only those input lines selected by the script shall be written to standard output.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_109_11" id="tag_20_109_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic and warning messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_109_12" id="tag_20_109_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>The output files shall be text files whose formats are dependent on the editing commands given.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_109_13" id="tag_20_109_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>The <i>script</i> shall consist of editing commands of the following form:</p> +<pre> +<b>[</b><i>address</i><b>[</b><tt>,</tt><i>address</i><b>]]</b><i>function</i><tt> +</tt></pre> +<p>where <i>function</i> represents a single-character command verb from the list in <a href="#tag_20_109_13_03">Editing Commands +in sed</a> , followed by any applicable arguments.</p> +<p>The command can be preceded by <blank> characters and/or <semicolon> characters. The function can be preceded by +<blank> characters. These optional characters shall have no effect.</p> +<p>In default operation, <i>sed</i> cyclically shall append a line of input, less its terminating <newline> character, into +the pattern space. Reading from input shall be skipped if a <newline> was in the pattern space prior to a <b>D</b> command +ending the previous cycle. The <i>sed</i> utility shall then apply in sequence all commands whose addresses select that pattern +space, until a command starts the next cycle or quits. If no commands explicitly started a new cycle, then at the end of the script +the pattern space shall be copied to standard output (except when <b>-n</b> is specified) and the pattern space shall be deleted. +Whenever the pattern space is written to standard output or a named file, <i>sed</i> shall immediately follow it with a +<newline>.</p> +<p>Some of the editing commands use a hold space to save all or part of the pattern space for subsequent retrieval. The pattern and +hold spaces shall each be able to hold at least 8192 bytes.</p> +<h5><a name="tag_20_109_13_01" id="tag_20_109_13_01"></a>Addresses in sed</h5> +<p>An address is either a decimal number that counts input lines cumulatively across files, a <tt>'$'</tt> character that addresses +the last line of input, or a context address. A context address has either the form <tt>"/RE/"</tt> or +<tt>"\<i>c</i>RE<i>c</i>"</tt>, where RE is a regular expression as described in <a href="#tag_20_109_13_02">Regular Expressions in +sed</a> , and <i>c</i> is any character other than <backslash> or <newline>. In a <i>sed</i> context address, the BRE +and ERE syntax shall be extended to support escaping occurrences of the <slash> or <i>c</i> delimiter within the RE by means +of an escape sequence (see XBD <a href="../basedefs/V1_chap09.html#tag_09_01"><i>9.1 Regular Expression Definitions</i></a> ). For +the <tt>"\<i>c</i>RE<i>c</i>"</tt> form, if the character designated by <i>c</i> is not listed as a special BRE character (if the +<b>-E</b> option is not specified) or a special ERE character (if <b>-E</b> is specified) in XBD <a href= +"../basedefs/V1_chap09.html#tag_09_03_03"><i>9.3.3 BRE Special Characters</i></a> or XBD <a href= +"../basedefs/V1_chap09.html#tag_09_04_03"><i>9.4.3 ERE Special Characters</i></a> , respectively, the escape sequence +<backslash><i>c</i> shall be treated as that literal character; otherwise, it is unspecified whether the escape sequence +<backslash><i>c</i> is treated as the literal character or the special character. In either case, the escape sequence +<backslash><i>c</i> shall not terminate the RE. For example, in the context address <tt>"/abc\/def/"</tt>, the second +<slash> stands for itself, so that the RE is <tt>"abc/def"</tt>, and in <tt>"\xabc\xdefx"</tt>, the second <tt>'x'</tt> +stands for itself, so that the RE is <tt>"abcxdef"</tt>.</p> +<p>An editing command with no addresses shall select every pattern space.</p> +<p>An editing command with one address shall select each pattern space that matches the address.</p> +<p>An editing command with two addresses shall select the inclusive range from the first pattern space that matches the first +address through the next pattern space that matches the second. (If the second address is a number less than or equal to the line +number first selected, only one line shall be selected.) Starting at the first line following the selected range, <i>sed</i> shall +look again for the first address. Thereafter, the process shall be repeated. Omitting either or both of the address components in +the following form produces undefined results:</p> +<pre> +<b>[</b><i>address</i><b>[</b><tt>,</tt><i>address</i><b>]]</b><tt> +</tt></pre> +<h5><a name="tag_20_109_13_02" id="tag_20_109_13_02"></a>Regular Expressions in sed</h5> +<p>The <i>sed</i> utility shall support the REs described in XBD <a href="../basedefs/V1_chap09.html#tag_09"><i>9. Regular +Expressions</i></a> ; by default it shall use BREs as described in XBD <a href="../basedefs/V1_chap09.html#tag_09_03"><i>9.3 Basic +Regular Expressions</i></a> , but if the <b>-E</b> option is used, it shall use EREs as described in XBD <a href= +"../basedefs/V1_chap09.html#tag_09_04"><i>9.4 Extended Regular Expressions</i></a> . In <i>sed</i>, the BRE and ERE syntax shall be +extended as follows:</p> +<ul> +<li> +<p>The delimiter character that precedes and follows the RE shall not terminate the RE when it appears within a bracket expression, +and shall have its normal meaning in the bracket expression. For example, the context address <tt>"\%[%]%"</tt> is equivalent to +<tt>"/[%]/"</tt>, and the command <tt>"s-[0-9]--g"</tt> is equivalent to <tt>"s/[0-9]//g"</tt>.</p> +</li> +<li> +<p>The escape sequence <tt>'\n'</tt> shall match a <newline> embedded in the pattern space. A literal <newline> shall +not be used in the RE of a context address or in the substitute function.</p> +</li> +<li> +<p>If an RE is empty (that is, no pattern is specified) <i>sed</i> shall behave as if the last RE used in the last command applied +(either as an address or as part of a substitute command) was specified.</p> +</li> +</ul> +<h5><a name="tag_20_109_13_03" id="tag_20_109_13_03"></a>Editing Commands in sed</h5> +<p>In the following list of editing commands, the maximum number of permissible addresses for each function is indicated by +[<i>0addr</i>], [<i>1addr</i>], or [<i>2addr</i>], representing zero, one, or two addresses.</p> +<p>The argument <i>text</i> shall consist of one or more lines. A <backslash> in the text can be escaped with another +<backslash>. The application shall ensure that each embedded <newline> (that is, those other than the terminating +<newline> of the last line) in the text is preceded by an unescaped <backslash>. The behavior is unspecified if an +unescaped <backslash> is immediately followed by any character other than <backslash> or <newline>, or by the end +of a <i>script</i>.</p> +<p>The <b>r</b> and <b>w</b> command verbs, and the <i>w</i> flag to the <b>s</b> command, take an <i>rfile</i> (or <i>wfile</i>) +parameter, separated from the command verb letter or flag by one or more <blank> characters; implementations may allow zero +separation as an extension.</p> +<p>The argument <i>rfile</i> or the argument <i>wfile</i> shall terminate the editing command. Each <i>wfile</i> shall be created +before processing begins. Implementations shall support at least ten <i>wfile</i> arguments in the script; the actual number +(greater than or equal to 10) that is supported by the implementation is unspecified. The use of the <i>wfile</i> parameter shall +cause that file to be initially created, if it does not exist, or shall replace the contents of an existing file.</p> +<p>The <b>b</b>, <b>r</b>, <b>s</b>, <b>t</b>, <b>w</b>, <b>y</b>, and <b>:</b> command verbs shall accept additional arguments. +The following synopses indicate which arguments shall be separated from the command verbs by a single <space>.</p> +<p>The <b>a</b> and <b>r</b> commands schedule text for later output. The text specified for the <b>a</b> command, and the contents +of the file specified for the <b>r</b> command, shall be written to standard output just before the next attempt to fetch a line of +input when executing the <b>c</b>, <b>D</b>, <b>d</b>, <b>N</b>, or <b>n</b> commands, just before executing the <b>q</b> command, +or when reaching the end of the script. If written when reaching the end of the script, and the <b>-n</b> option was not specified, +the text shall be written after copying the pattern space to standard output. The contents of the file specified for the <b>r</b> +command shall be as of the time the output is written, not the time the <b>r</b> command is applied. The text shall be output in +the order in which the <b>a</b> and <b>r</b> commands were applied to the input.</p> +<p>Editing commands other than <b>a</b>, <b>b</b>, <b>c</b>, <b>i</b>, <b>r</b>, <b>t</b>, <b>w</b>, <b>:</b>, and <b>#</b> can be +followed by a <semicolon>, optional <blank> characters, and another editing command. However, when an <b>s</b> editing +command is used with the <i>w</i> flag, following it with another command in this manner produces undefined results.</p> +<p>A function can be preceded by a <tt>'!'</tt> character, in which case the function shall be applied if the addresses do not +select the pattern space. Zero or more <blank> characters shall be accepted before the <tt>'!'</tt> character. It is +unspecified whether <blank> characters can follow the <tt>'!'</tt> character, and conforming applications shall not follow +the <tt>'!'</tt> character with <blank> characters.</p> +<p>If a <i>label</i> argument (to a <b>b</b>, <b>t</b>, or <b>:</b> command) contains characters outside of the portable filename +character set, or if a <i>label</i> is longer than 8 bytes, the behavior is unspecified. The implementation shall support +<i>label</i> arguments recognized as unique up to at least 8 bytes; the actual length (greater than or equal to 8) supported by the +implementation is unspecified. It is unspecified whether exceeding the maximum supported label length causes an error or a silent +truncation.</p> +<dl compact> +<dd></dd> +<dt><b>[</b><i>2addr</i><b>] {</b><i>editing command</i></dt> +<dd></dd> +<dt><i>editing command</i></dt> +<dd></dd> +<dt>...</dt> +<dd></dd> +<dt><b>}</b></dt> +<dd>Execute a list of <i>sed</i> editing commands only when the pattern space is selected. The list of <i>sed</i> editing commands +shall be surrounded by braces. The braces can be preceded or followed by <blank> characters. The <right-brace> shall be +preceded by a <newline> or <semicolon> (before any optional <blank> characters preceding the +<right-brace>). +<p>Each command in the list of commands shall be terminated by a <newline> character, or by a <semicolon> character if +permitted when the command is used outside the braces. The editing commands can be preceded by <blank> characters, but shall +not be followed by <blank> characters.</p> +</dd> +<dt><b>[</b><i>1addr</i><b>]a\</b></dt> +<dd></dd> +<dt><i>text</i></dt> +<dd>Write text to standard output as described previously.</dd> +<dt><b>[</b><i>2addr</i><b>]b [</b><i>label</i><b>]</b></dt> +<dd><br> +Branch to the <b>:</b> command verb bearing the <i>label</i> argument. If <i>label</i> is not specified, branch to the end of the +script.</dd> +<dt><b>[</b><i>2addr</i><b>]c\</b></dt> +<dd></dd> +<dt><i>text</i></dt> +<dd>Delete the pattern space. With a 0 or 1 address or at the end of a 2-address range, place <i>text</i> on the output. Start the +next cycle.</dd> +<dt><b>[</b><i>2addr</i><b>]d</b></dt> +<dd>Delete the pattern space and start the next cycle.</dd> +<dt><b>[</b><i>2addr</i><b>]D</b></dt> +<dd>If the pattern space contains no <newline>, delete the pattern space and start a normal new cycle as if the <b>d</b> +command was issued. Otherwise, delete the initial segment of the pattern space through the first <newline>, and start the +next cycle with the resultant pattern space and without reading any new input.</dd> +<dt><b>[</b><i>2addr</i><b>]g</b></dt> +<dd>Replace the contents of the pattern space by the contents of the hold space.</dd> +<dt><b>[</b><i>2addr</i><b>]G</b></dt> +<dd>Append to the pattern space a <newline> followed by the contents of the hold space.</dd> +<dt><b>[</b><i>2addr</i><b>]h</b></dt> +<dd>Replace the contents of the hold space with the contents of the pattern space.</dd> +<dt><b>[</b><i>2addr</i><b>]H</b></dt> +<dd>Append to the hold space a <newline> followed by the contents of the pattern space.</dd> +<dt><b>[</b><i>1addr</i><b>]i\</b></dt> +<dd></dd> +<dt><i>text</i></dt> +<dd>Write <i>text</i> to standard output.</dd> +<dt><b>[</b><i>2addr</i><b>]l</b></dt> +<dd>(The letter ell.) Write the pattern space to standard output in a visually unambiguous form. The characters listed in XBD +<a href="../basedefs/V1_chap05.html#tagtcjh_2"><i>Escape Sequences and Associated Actions</i></a> (<tt>'\\'</tt>, <tt>'\a'</tt>, +<tt>'\b'</tt>, <tt>'\f'</tt>, <tt>'\r'</tt>, <tt>'\t'</tt>, <tt>'\v'</tt>) shall be written as the corresponding escape sequence; +the <tt>'\n'</tt> in that table is not applicable. Non-printable characters not in that table shall be written as one three-digit +octal number (with a preceding <backslash>) for each byte in the character (most significant byte first). +<p>Long lines shall be folded, with the point of folding indicated by writing a <backslash> followed by a <newline>; +the length at which folding occurs is unspecified, but should be appropriate for the output device. The end of each line shall be +marked with a <tt>'$'</tt>.</p> +</dd> +<dt><b>[</b><i>2addr</i><b>]n</b></dt> +<dd>Write the pattern space to standard output if the default output has not been suppressed, and replace the pattern space with +the next line of input, less its terminating <newline>. +<p>If no next line of input is available, the <b>n</b> command verb shall branch to the end of the script and quit without starting +a new cycle.</p> +</dd> +<dt><b>[</b><i>2addr</i><b>]N</b></dt> +<dd>Append the next line of input, less its terminating <newline>, to the pattern space, using an embedded <newline> to +separate the appended material from the original material. Note that the current line number changes. +<p>If no next line of input is available, the <b>N</b> command verb shall branch to the end of the script and quit without starting +a new cycle or copying the pattern space to standard output.</p> +</dd> +<dt><b>[</b><i>2addr</i><b>]p</b></dt> +<dd>Write the pattern space to standard output.</dd> +<dt><b>[</b><i>2addr</i><b>]P</b></dt> +<dd>Write the pattern space, up to the first <newline>, to standard output.</dd> +<dt><b>[</b><i>1addr</i><b>]q</b></dt> +<dd>Branch to the end of the script and quit without starting a new cycle.</dd> +<dt><b>[</b><i>1addr</i><b>]r </b><i>rfile</i></dt> +<dd>Copy the contents of <i>rfile</i> to standard output as described previously. If <i>rfile</i> does not exist or cannot be read, +it shall be treated as if it were an empty file, causing no error condition.</dd> +<dt><b>[</b><i>2addr</i><b>]s/</b><i>RE</i><b>/</b><i>replacement</i><b>/</b><i>flags</i></dt> +<dd><br> +Substitute the replacement string for instances of the RE in the pattern space. Any character other than <backslash> or +<newline> can be used instead of a <slash> to delimit the RE and the replacement. Within the RE (as a <i>sed</i> +extension to the BRE and ERE syntax) and the replacement, the delimiter shall not terminate the RE or replacement if it is the +second character of an escape sequence (see XBD <a href="../basedefs/V1_chap09.html#tag_09_01"><i>9.1 Regular Expression +Definitions</i></a> ). If the delimiter character is not listed as a special BRE character (if the <b>-E</b> option is not +specified) or a special ERE character (if <b>-E</b> is specified) in XBD <a href="../basedefs/V1_chap09.html#tag_09_03_03"><i>9.3.3 +BRE Special Characters</i></a> or XBD <a href="../basedefs/V1_chap09.html#tag_09_04_03"><i>9.4.3 ERE Special Characters</i></a> , +respectively, the escaped delimiter shall be treated as that literal character in the RE; otherwise, it is unspecified whether the +escaped delimiter is treated as the literal character or the special character. Likewise, if the delimiter character is not +<ampersand> (<tt>'&'</tt>), the escaped delimiter shall be treated as that literal character in the replacement; if it is +<ampersand>, it is unspecified whether the escaped delimiter is treated as the literal character or the special character +(see below). +<p>The replacement string shall be scanned from beginning to end. An <ampersand> (<tt>'&'</tt>) appearing in the +replacement shall be replaced by the string matching the RE. The special meaning of <tt>'&'</tt> in this context can be +suppressed by preceding it by a <backslash>. The characters <tt>"\</tt><i>n"</i>, where <i>n</i> is a digit, shall be +replaced by the text matched by the corresponding back-reference expression. If the corresponding back-reference expression does +not match, then the characters <tt>"\</tt><i>n"</i> shall be replaced by the empty string. The special meaning of +<tt>"\</tt><i>n"</i> where <i>n</i> is a digit in this context, can be suppressed by preceding it by a <backslash>. For each +other <backslash> encountered, the following character shall lose its special meaning (if any).</p> +<p>A line can be split by substituting a <newline> into it. The application shall escape the <newline> in the +replacement by preceding it by a <backslash>.</p> +<p>The meaning of an unescaped <backslash> immediately followed by any character other than <tt>'&'</tt>, +<backslash>, a digit, <newline>, or the delimiter character used for this command, is unspecified.</p> +<p>Any <backslash> used to alter the default meaning of a subsequent character shall be discarded from the resulting +replacement string. A substitution shall be considered to have been performed even if the resulting replacement string is identical +to the string that it replaces.</p> +<p>The value of <i>flags</i> shall be zero or more of:</p> +<dl compact> +<dd></dd> +<dt><i>n</i></dt> +<dd>Substitute for the <i>n</i>th occurrence only of the RE found within the pattern space.</dd> +<dt><b>g</b></dt> +<dd>Globally substitute for all non-overlapping instances of the RE rather than just the first one. If both <b>g</b> and <i>n</i> +are specified, the results are unspecified.</dd> +<dt><b>i</b></dt> +<dd>Match the regular expression in a case-insensitive way.</dd> +<dt><b>p</b></dt> +<dd>Write the pattern space to standard output if a replacement was made.</dd> +<dt><b>w </b><i>wfile</i></dt> +<dd>Write. Append the pattern space to <i>wfile</i> if a replacement was made. A conforming application shall precede the +<i>wfile</i> argument with one or more <blank> characters. If the <b>w</b> flag is not the last flag value given in a +concatenation of multiple flag values, the results are undefined.</dd> +</dl> +</dd> +<dt><b>[</b><i>2addr</i><b>]t [</b><i>label</i><b>]</b></dt> +<dd><br> +Test. Branch to the <b>:</b> command verb bearing the <i>label</i> if any substitutions have been made since the most recent +reading of an input line or execution of a <b>t</b>. If <i>label</i> is not specified, branch to the end of the script.</dd> +<dt><b>[</b><i>2addr</i><b>]w </b><i>wfile</i></dt> +<dd><br> +Append (write) the pattern space to <i>wfile</i>.</dd> +<dt><b>[</b><i>2addr</i><b>]x</b></dt> +<dd>Exchange the contents of the pattern and hold spaces.</dd> +<dt><b>[</b><i>2addr</i><b>]y/</b><i>string1</i><b>/</b><i>string2</i><b>/</b></dt> +<dd><br> +Replace all occurrences of characters in <i>string1</i> with the corresponding characters in <i>string2</i>. If a <backslash> +followed by an <tt>'n'</tt> appear in <i>string1</i> or <i>string2</i>, the two characters shall be handled as a single +<newline>. If (after resolving any escape sequences) the numbers of characters in <i>string1</i> and <i>string2</i> are not +equal, or if any of the characters in <i>string1</i> appear more than once, the results are undefined. Any character other than +<backslash> or <newline> can be used instead of <slash> to delimit the strings. If the delimiter is not +<tt>'n'</tt>, within <i>string1</i> and <i>string2</i>, the delimiter itself can be used as a literal character if it is preceded +by an unescaped <backslash>. If a <backslash> character is escaped by an immediately preceding unescaped +<backslash> character in <i>string1</i> or <i>string2</i>, the two <backslash> characters shall be treated as a single +literal <backslash> character. The meaning of an unescaped <backslash> followed by any character that is not +<tt>'n'</tt>, a <backslash>, or the delimiter character is undefined.</dd> +<dt><b>[</b><i>0addr</i><b>]:</b><i>label</i></dt> +<dd>Do nothing. This command bears a <i>label</i> to which the <b>b</b> and <b>t</b> commands branch.</dd> +<dt><b>[</b><i>1addr</i><b>]=</b></dt> +<dd>Write the following to standard output: +<pre> +<tt>"%d\n", <</tt><i>current line number</i><tt>> +</tt></pre></dd> +<dt><b>[</b><i>0addr</i><b>]</b></dt> +<dd>Ignore this empty command.</dd> +<dt><b>[</b><i>0addr</i><b>]#</b></dt> +<dd>Ignore the <tt>'#'</tt> and the remainder of the line (treat them as a comment), with the single exception that if the first +two characters in the script are <tt>"#n"</tt>, the default output shall be suppressed; this shall be the equivalent of specifying +<b>-n</b> on the command line.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_109_14" id="tag_20_109_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_109_15" id="tag_20_109_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_109_16" id="tag_20_109_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Regular expressions match entire strings, not just individual lines, but a <newline> is matched by <tt>'\n'</tt> in a +<i>sed</i> RE; a <newline> is not allowed by the general definition of regular expression in POSIX.1-2024. Also note that +<tt>'\n'</tt> cannot be used to match a <newline> at the end of an arbitrary input line; <newline> characters appear in +the pattern space as a result of the <b>N</b> editing command.</p> +<p>Applications that use a special RE character as a delimiter (for example, <tt>'.'</tt> or <tt>'*'</tt>) and need to use the +delimiter as a literal character in the RE should put it inside a bracket expression, as implementations differ regarding whether +escaping it with a <backslash> removes its special meaning. For example, for the context address <tt>"/\.[0-9]/"</tt> to be +written with <tt>'.'</tt> as delimiter, the form <tt>"\.[.][0-9]."</tt> needs to be used; <tt>"\.\.[0-9]."</tt> cannot be used +portably for this purpose, as it is unspecified whether this would be equivalent to <tt>"/\.[0-9]/"</tt> or <tt>"/.[0-9]/"</tt>. +Portable applications cannot use a special RE character as a delimiter if that character needs to have its special meaning in the +RE, as escaping it may remove its special meaning.</p> +<p>When using <i>sed</i> to process pathnames, it is recommended that LC_ALL, or at least LC_CTYPE and LC_COLLATE, are set to POSIX +or C in the environment, since pathnames can contain byte sequences that do not form valid characters in some locales, in which +case the utility's behavior would be undefined. In the POSIX locale each byte is a valid single-byte character, and therefore this +problem is avoided.</p> +<p>Note that some implementations of <i>sed</i> also support an <b>I</b> flag for the <b>s</b> command as an alias for the lower +case <b>i</b> flag.</p> +<p>Some implementations of <i>sed</i>, when executed in a non-conforming environment, handle <backslash> escapes in regular +expressions in a similar way to how <a href="../utilities/awk.html"><i>awk</i></a> handles them in the lexical token <b>ERE</b> +(processing <tt>"\t"</tt> as a tab character, etc.). This is a compatible extension except that it conflicts with the requirements +of this standard when <backslash> appears inside a bracket expression. A future version of this standard may allow this +behavior, and therefore applications should use two <backslash> characters in bracket expressions instead of one in order to +ensure future portability. On implementations conforming to the current standard, the second <backslash> is redundant. In the +future (and in current non-conforming environments) the first <backslash> may escape the second.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_109_17" id="tag_20_109_17"></a>EXAMPLES</h4> +<blockquote> +<p>This <i>sed</i> script simulates the BSD <a href="../utilities/cat.html"><i>cat</i></a> <b>-s</b> command, squeezing excess +empty lines from standard input.</p> +<pre> +<tt>sed -n ' +# Write non-empty lines. +/./ { + p + d + } +# Write a single empty line, then look for more empty lines. +/^$/ p +# Get next line, discard the held <newline> (empty line), +# and look for more empty lines. +:Empty +/^$/ { + N + s/.// + b Empty + } +# Write the non-empty line before going back to search +# for the first in a set of empty lines. + p +' +</tt></pre> +<p>The following <i>sed</i> command is a much simpler method of squeezing empty lines, although it is not quite the same as +<a href="../utilities/cat.html"><i>cat</i></a> <b>-s</b> since it removes any initial empty lines:</p> +<pre> +<tt>sed -n '/./,/^$/p' +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_109_18" id="tag_20_109_18"></a>RATIONALE</h4> +<blockquote> +<p>This volume of POSIX.1-2024 requires implementations to support at least ten distinct <i>wfile</i>s, matching historical +practice on many implementations. Implementations are encouraged to support more, but conforming applications should not exceed +this limit.</p> +<p>The exit status codes specified here are different from those in System V. System V returns 2 for garbled <i>sed</i> commands, +but returns zero with its usage message or if the input file could not be opened. The standard developers considered this to be a +bug.</p> +<p>The manner in which the <b>l</b> command writes non-printable characters was changed to avoid the historical +backspace-overstrike method, and other requirements to achieve unambiguous output were added. See the RATIONALE for <a href= +"../utilities/ed.html#"><i>ed</i></a> for details of the format chosen, which is the same as that chosen for <i>sed</i>.</p> +<p>This volume of POSIX.1-2024 requires implementations to provide pattern and hold spaces of at least 8192 bytes, larger than the +4000 bytes spaces used by some historical implementations, but less than the 20480 bytes limit used in an early proposal. +Implementations are encouraged to allocate dynamically larger pattern and hold spaces as needed.</p> +<p>The requirements for acceptance of <blank> and <space> characters in command lines has been made more explicit than +in early proposals to describe clearly the historical practice and to remove confusion about the phrase "protect initial blanks +[<i>sic</i>] and tabs from the stripping that is done on every script line" that appears in much of the historical documentation +of the <i>sed</i> utility description of text. (Not all implementations are known to have stripped <blank> characters from +text lines, although they all have allowed leading <blank> characters preceding the address on a command line.)</p> +<p>The treatment of <tt>'#'</tt> comments differs from the SVID which only allows a comment as the first line of the script, but +matches BSD-derived implementations. The comment character is treated as a command, and it has the same properties in terms of +being accepted with leading <blank> characters; the BSD implementation has historically supported this.</p> +<p>Early proposals required that a <i>script_file</i> have at least one non-comment line. Some historical implementations have +behaved in unexpected ways if this were not the case. The standard developers considered that this was incorrect behavior and that +application developers should not have to avoid this feature. A correct implementation of this volume of POSIX.1-2024 shall permit +<i>script_file</i>s that consist only of comment lines.</p> +<p>Early proposals indicated that if <b>-e</b> and <b>-f</b> options were intermixed, all <b>-e</b> options were processed before +any <b>-f</b> options. This has been changed to process them in the order presented because it matches historical practice and is +more intuitive.</p> +<p>The characters <backslash> and <newline> cannot be used as RE delimiter characters, as they can never be recognized +as the ending delimiter:</p> +<ul> +<li> +<p><backslash> does not work, because if it appears unescaped later in the RE, it either escapes the following character, +which can then never be the ending delimiter, or it is part of a bracket expression, inside which the ending delimiter for the RE +cannot be located.</p> +</li> +<li> +<p><newline> does not work, because if not escaped, it terminates the command, meaning it cannot be the ending delimiter.</p> +</li> +</ul> +<p>Some historical <i>sed</i> implementations did not support escaping <tt>'('</tt>, <tt>')'</tt>, <tt>'{'</tt>, and <tt>'}'</tt> +when used as a BRE delimiter, as the sequences <tt>"\("</tt> and so on were still treated as special, usually resulting in an +error. This standard requires that these sequences are treated as the literal character. This is for consistency with extensions. +For example, some implementations treat <tt>"\s"</tt> in a BRE as matching white-space characters, as an extension. This cannot +have its special meaning when <tt>'s'</tt> is used as a BRE delimiter in order to ensure portability of <i>sed</i> commands that +have <tt>'s'</tt> as a delimiter and escape it. If <tt>"\s"</tt> were allowed to keep its special meaning, then the potential for +further extensions would mean portable applications would not be able to escape any delimiter character other than +<slash>.</p> +<p>The treatment of the <b>p</b> flag to the <b>s</b> command differs between System V and BSD-based systems when the default +output is suppressed. In the two examples:</p> +<pre> +<tt>echo a | sed 's/a/A/p' +echo a | sed -n 's/a/A/p' +</tt></pre> +<p>this volume of POSIX.1-2024, BSD, System V documentation, and the SVID indicate that the first example should write two lines +with <b>A</b>, whereas the second should write one. Some System V systems write the <b>A</b> only once in both examples because the +<b>p</b> flag is ignored if the <b>-n</b> option is not specified.</p> +<p>This is a case of a diametrical difference between systems that could not be reconciled through the compromise of declaring the +behavior to be unspecified. The SVID/BSD/System V documentation behavior was adopted for this volume of POSIX.1-2024 because:</p> +<ul> +<li> +<p>No known documentation for any historic system describes the interaction between the <b>p</b> flag and the <b>-n</b> option.</p> +</li> +<li> +<p>The selected behavior is more correct as there is no technical justification for any interaction between the <b>p</b> flag and +the <b>-n</b> option. A relationship between <b>-n</b> and the <b>p</b> flag might imply that they are only used together, but this +ignores valid scripts that interrupt the cyclical nature of the processing through the use of the <b>D</b>, <b>d</b>, <b>q</b>, or +branching commands. Such scripts rely on the <b>p</b> suffix to write the pattern space because they do not make use of the default +output at the "bottom" of the script.</p> +</li> +<li> +<p>Because the <b>-n</b> option makes the <b>p</b> flag unnecessary, any interaction would only be useful if <i>sed</i> scripts +were written to run both with and without the <b>-n</b> option. This is believed to be unlikely. It is even more unlikely that +programmers have coded the <b>p</b> flag expecting it to be unnecessary. Because the interaction was not documented, the likelihood +of a programmer discovering the interaction and depending on it is further decreased.</p> +</li> +<li> +<p>Finally, scripts that break under the specified behavior produce too much output instead of too little, which is easier to +diagnose and correct.</p> +</li> +</ul> +<p>The form of the substitute command that uses the <b>n</b> suffix was limited to the first 512 matches in an early proposal. This +limit has been removed because there is no reason an editor processing lines of {LINE_MAX} length should have this restriction. The +command <b>s/a/A/2047</b> should be able to substitute the 2047th occurrence of <b>a</b> on a line.</p> +<p>The <b>b</b>, <b>t</b>, and <b>:</b> commands are documented to ignore leading white space, but no mention is made of trailing +white space. Historical implementations of <i>sed</i> assigned different locations to the labels <tt>'x'</tt> and +<tt>"x "</tt>. This is not useful, and leads to subtle programming errors, but it is historical practice, and changing it +could theoretically break working scripts. Implementors are encouraged to provide warning messages about labels that are never +referenced by a <b>b</b> or <b>t</b> command, jumps to labels that do not exist, and label arguments that are subject to +truncation.</p> +<p>Earlier versions of this standard allowed for implementations with bytes other than eight bits, but this has been modified in +this version.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_109_19" id="tag_20_109_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>A future version of this standard may allow <i>sed</i> to handle <backslash> escapes in regular expressions in a similar +way to how <a href="../utilities/awk.html"><i>awk</i></a> handles them in the lexical token <b>ERE</b>. ("Similar" rather than +"the same" because <i>sed</i> can use BREs or EREs whereas <a href="../utilities/awk.html"><i>awk</i></a> uses only EREs.)</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_109_20" id="tag_20_109_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/awk.html#"><i>awk</i></a> , <a href="../utilities/ed.html#"><i>ed</i></a> , <a href= +"../utilities/grep.html#"><i>grep</i></a></p> +<p>XBD <a href="../basedefs/V1_chap05.html#tagtcjh_2"><i>Escape Sequences and Associated Actions</i></a> , <a href= +"../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href="../basedefs/V1_chap09.html#tag_09_03"><i>9.3 +Basic Regular Expressions</i></a> , <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_109_21" id="tag_20_109_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_109_22" id="tag_20_109_22"></a>Issue 5</h4> +<blockquote> +<p>The FUTURE DIRECTIONS section is added.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_109_23" id="tag_20_109_23"></a>Issue 6</h4> +<blockquote> +<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p> +<ul> +<li> +<p>Implementations are required to support at least ten <i>wfile</i> arguments in an editing command.</p> +</li> +</ul> +<p>The EXTENDED DESCRIPTION is changed to align with the IEEE P1003.2b draft standard.</p> +<p>IEEE PASC Interpretation 1003.2 #190 is applied.</p> +<p>IEEE PASC Interpretation 1003.2 #203 is applied, clarifying the meaning of the <backslash>-escape sequences in a +replacement string for a BRE.</p> +<p>IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/28 is applied, removing text describing behavior on systems with +bytes consisting of more than eight bits.</p> +<p>IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/29 is applied, making an editorial correction within the Editing +Commands in <i>sed</i> section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_109_24" id="tag_20_109_24"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretations 1003.1-2001 #006, #036, and #092 are applied.</p> +<p>SD5-XCU-ERN-97 and SD5-XCU-ERN-123 are applied, updating the SYNOPSIS.</p> +<p>A second example is added.</p> +<p>POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0133 [262], XCU/TC1-2008/0134 [282,431], XCU/TC1-2008/0135 [269], and +XCU/TC1-2008/0136 [282,431] are applied.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0166 [945], XCU/TC2-2008/0167 [944], XCU/TC2-2008/0168 [945], +XCU/TC2-2008/0169 [944], XCU/TC2-2008/0170 [945], XCU/TC2-2008/0171 [533], XCU/TC2-2008/0172 [663], XCU/TC2-2008/0173 [945], and +XCU/TC2-2008/0174 [944] are applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_109_25" id="tag_20_109_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 528 is applied, adding support for selecting the use of EREs instead of BREs, by specifying the <b>-E</b> +option.</p> +<p>Austin Group Defect 779 is applied, adding the <b>i</b> flag to the <b>s</b> command.</p> +<p>Austin Group Defect 961 is applied, requiring that <b>{...}</b> can be followed by a <semicolon>, optional <blank> +characters, and another editing command.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1231 is applied, clarifying the handling of <backslash> in <i>text</i> arguments.</p> +<p>Austin Group Defect 1233 is applied, changing the APPLICATION USAGE and FUTURE DIRECTIONS sections.</p> +<p>Austin Group Defect 1319 is applied, changing when the text specified for the <b>a</b> command and the contents of the file +specified for the <b>r</b> command are written.</p> +<p>Austin Group Defect 1550 is applied, clarifying requirements relating to delimiters in context addresses and in <b>s</b> and +<b>y</b> commands.</p> +<p>Austin Group Defect 1578 is applied, clarifying the description of the <b>y</b> command.</p> +<p>Austin Group Defect 1767 is applied, clarifying that a <b>c</b> command starts the next cycle on every line that its address +range matches.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/sccs.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/sh.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/sh.html b/bdd/sh.html @@ -0,0 +1,1012 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>sh</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/sed.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/sleep.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="sh" id="sh"></a> <a name="tag_20_110" id="tag_20_110"></a><!-- sh --> +<h4 class="mansect"><a name="tag_20_110_01" id="tag_20_110_01"></a>NAME</h4> +<blockquote>sh — shell, the standard command language interpreter</blockquote> +<h4 class="mansect"><a name="tag_20_110_02" id="tag_20_110_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt><sup>[<a href="javascript:open_code('OB')">OB</a>]</sup> sh</tt> <b>[</b><tt>-abCef<img src="../images/opt-start.gif" +border="0">h<img src="../images/opt-end.gif" border="0">imnuvx</tt><b>] [</b><tt>-o</tt> <i>option</i><b>]</b><tt>...</tt> +<b>[</b><tt>+abCef<img src="../images/opt-start.gif" border="0">h<img src="../images/opt-end.gif" border="0">imnuvx</tt><b>] +[</b><tt>+o</tt> <i>option</i><b>]</b><tt>...<br> + </tt> <b>[</b><i>command_file</i> <b>[</b><i>argument</i><tt>...</tt><b>]]</b> <tt><br> +<br> +<sup>[<a href="javascript:open_code('OB')">OB</a>]</sup> sh -c</tt> <b>[</b><tt>-abCef<img src="../images/opt-start.gif" border= +"0">h<img src="../images/opt-end.gif" border="0">imnuvx</tt><b>] [</b><tt>-o</tt> <i>option</i><b>]</b><tt>...</tt> +<b>[</b><tt>+abCef<img src="../images/opt-start.gif" border="0">h<img src="../images/opt-end.gif" border="0">imnuvx</tt><b>] +[</b><tt>+o</tt> <i>option</i><b>]</b><tt>...<br> + </tt> <i>command_string</i> <b>[</b><i>command_name</i> +<b>[</b><i>argument</i><tt>...</tt><b>]]</b> <tt><br> +<br> +<sup>[<a href="javascript:open_code('OB')">OB</a>]</sup> sh -s</tt> <b>[</b><tt>-abCef<img src="../images/opt-start.gif" border= +"0">h<img src="../images/opt-end.gif" border="0">imnuvx</tt><b>] [</b><tt>-o</tt> <i>option</i><b>]</b><tt>...</tt> +<b>[</b><tt>+abCef<img src="../images/opt-start.gif" border="0">h<img src="../images/opt-end.gif" border="0">imnuvx</tt><b>] +[</b><tt>+o</tt> <i>option</i><b>]</b><tt>...<br> + </tt> <b>[</b><i>argument</i><tt>...</tt><b>]</b> <tt><br></tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_110_03" id="tag_20_110_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>sh</i> utility is a command language interpreter that shall execute commands read from a command line string, the +standard input, or a specified file. The application shall ensure that the commands to be executed are expressed in the language +described in <a href="../utilities/V3_chap02.html#tag_19"><i>2. Shell Command Language</i></a> .</p> +<p>Pathname expansion shall not fail due to the size of a file.</p> +<p>Shell input and output redirections have an implementation-defined offset maximum that is established in the open file +description.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_110_04" id="tag_20_110_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>sh</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> , with an extension for support of a leading <plus-sign> (<tt>'+'</tt>) as noted below.</p> +<p>The <b>-a</b>, <b>-b</b>, <b>-C</b>, <b>-e</b>, <b>-f</b>, <b>-h</b>, <b>-m</b>, <b>-n</b>, <b>-o</b> <i>option</i>, <b>-u</b>, +<b>-v</b>, and <b>-x</b> options are described as part of the <a href="../utilities/V3_chap02.html#set"><i>set</i></a> utility in +<a href="../utilities/V3_chap02.html#tag_19_15"><i>2.15 Special Built-In Utilities</i></a> . The option letters derived from the +<a href="../utilities/V3_chap02.html#set"><i>set</i></a> special built-in shall also be accepted with a leading <plus-sign> +(<tt>'+'</tt>) instead of a leading <hyphen-minus> (meaning the reverse case of the option as described in this volume of +POSIX.1-2024). If the <b>-o</b> or <b>+o</b> option is specified without an option-argument, the behavior is unspecified.</p> +<p>The following additional options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-c</b></dt> +<dd>Read commands from the <i>command_string</i> operand. Set the value of special parameter 0 (see <a href= +"../utilities/V3_chap02.html#tag_19_05_02"><i>2.5.2 Special Parameters</i></a> ) from the value of the <i>command_name</i> operand +and the positional parameters ($1, $2, and so on) in sequence from the remaining <i>argument</i> operands. No commands shall be +read from the standard input.</dd> +<dt><b>-i</b></dt> +<dd>Specify that the shell is <i>interactive</i>; see below. An implementation may treat specifying the <b>-i</b> option as an +error if the real user ID of the calling process does not equal the effective user ID or if the real group ID does not equal the +effective group ID.</dd> +<dt><b>-s</b></dt> +<dd>Read commands from the standard input.</dd> +</dl> +<p>If there are no operands and the <b>-c</b> option is not specified, the <b>-s</b> option shall be assumed.</p> +<p>If the <b>-i</b> option is present, or if the shell reads commands from the standard input and the shell's standard input and +standard error are attached to a terminal, the shell is considered to be <i>interactive</i>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_110_05" id="tag_20_110_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><tt>-</tt></dt> +<dd>A single <hyphen-minus> shall be treated as the first operand and then ignored. If both <tt>'-'</tt> and <tt>"--"</tt> +are given as arguments, or if other operands precede the single <hyphen-minus>, the results are undefined.</dd> +<dt><i>argument</i></dt> +<dd>The positional parameters ($1, $2, and so on) shall be set to <i>arguments</i>, if any.</dd> +<dt><i>command_file</i></dt> +<dd>The pathname of a file containing commands. If the pathname contains one or more <slash> characters, the implementation +attempts to read that file; the file need not be executable. If the pathname does not contain a <slash> character: +<ul> +<li> +<p>The implementation shall attempt to read that file from the current working directory; the file need not be executable.</p> +</li> +<li> +<p>If the file is not in the current working directory, the implementation may perform a search for an executable file using the +value of <i>PATH ,</i> as described in <a href="../utilities/V3_chap02.html#tag_19_09_01_04"><i>2.9.1.4 Command Search and +Execution</i></a> .</p> +</li> +</ul> +<p>Special parameter 0 (see <a href="../utilities/V3_chap02.html#tag_19_05_02"><i>2.5.2 Special Parameters</i></a> ) shall be set +to the value of <i>command_file</i>. If <i>sh</i> is called using a synopsis form that omits <i>command_file</i>, special parameter +0 shall be set to the value of the first argument passed to <i>sh</i> from its parent (for example, <i>argv</i>[0] for a C +program), which is normally a pathname used to execute the <i>sh</i> utility.</p> +</dd> +<dt><i>command_name</i></dt> +<dd><br> +A string assigned to special parameter 0 when executing the commands in <i>command_string</i>. If <i>command_name</i> is not +specified, special parameter 0 shall be set to the value of the first argument passed to <i>sh</i> from its parent (for example, +<i>argv</i>[0] for a C program), which is normally a pathname used to execute the <i>sh</i> utility.</dd> +<dt><i>command_string</i></dt> +<dd><br> +A string that shall be interpreted by the shell as one or more commands, as if the string were the argument to the <a href= +"../functions/system.html"><i>system</i>()</a> function defined in the System Interfaces volume of POSIX.1-2024. If the +<i>command_string</i> operand is an empty string, <i>sh</i> shall exit with a zero exit status.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_110_06" id="tag_20_110_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be used only if one of the following is true:</p> +<ul> +<li> +<p>The <b>-s</b> option is specified.</p> +</li> +<li> +<p>The <b>-c</b> option is not specified and no operands are specified.</p> +</li> +<li> +<p>The script executes one or more commands that require input from standard input (such as a <a href= +"../utilities/read.html"><i>read</i></a> command that does not redirect its input).</p> +</li> +</ul> +<p>See the INPUT FILES section.</p> +<p>When the shell is using standard input and it invokes a command that also uses standard input, the shell shall ensure that the +standard input file pointer points directly after the command it has read when the command begins execution. It shall not read +ahead in such a manner that any characters intended to be read by the invoked command are consumed by the shell (whether +interpreted by the shell or not) or that characters that are not read by the invoked command are not seen by the shell. When the +command expecting to read standard input is started asynchronously by an interactive shell, it is unspecified whether characters +are read by the command or interpreted by the shell.</p> +<p>If the standard input to <i>sh</i> is a FIFO or terminal device and is set to non-blocking reads, then <i>sh</i> shall enable +blocking reads on standard input. This shall remain in effect when the command completes.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_110_07" id="tag_20_110_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input file can be of any type, but the initial portion of the file intended to be parsed according to the shell grammar (see +<a href="../utilities/V3_chap02.html#tag_19_10_02"><i>2.10.2 Shell Grammar Rules</i></a> ) shall consist of characters and shall +not contain the NUL character. The shell shall not enforce any line length limits. If the input file consists solely of zero or +more blank lines and comments, <i>sh</i> shall exit with a zero exit status.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_110_08" id="tag_20_110_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>sh</i>:</p> +<dl compact> +<dd></dd> +<dt><i>ENV</i></dt> +<dd><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +This variable, when and only when an interactive shell is invoked, shall be subjected to parameter expansion (see <a href= +"../utilities/V3_chap02.html#tag_19_06_02"><i>2.6.2 Parameter Expansion</i></a> ) by the shell, and the resulting value shall be +used as a pathname of a file containing shell commands to execute in the current environment. The file need not be executable. If +the expanded value of <i>ENV</i> is not an absolute pathname, the results are unspecified. <i>ENV</i> shall be ignored if the real +and effective user IDs or real and effective group IDs of the process are different. The file specified by <i>ENV</i> need not be +processed if the file can be written by any user other than the user identified by the real (and effective) user ID of the shell +process. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><i>FCEDIT</i></dt> +<dd><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +This variable, when expanded by the shell, shall determine the default value for the <b>-e</b> <i>editor</i> option's <i>editor</i> +option-argument. If <i>FCEDIT</i> is null or unset, <a href="../utilities/ed.html"><i>ed</i></a> shall be used as the editor. +<img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><i>HISTFILE</i></dt> +<dd><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine a pathname naming a command history file. If the <i>HISTFILE</i> variable is not set, the shell may attempt to access or +create a file <b>.sh_history</b> in the directory referred to by the <i>HOME</i> environment variable. If the shell cannot obtain +both read and write access to, or create, the history file, it shall use an unspecified mechanism that allows the history to +operate properly. (References to history "file" in this section shall be understood to mean this unspecified mechanism in such +cases.) An implementation may choose to access this variable only when initializing the history file; this initialization shall +occur when <a href="../utilities/fc.html"><i>fc</i></a> or <i>sh</i> first attempt to retrieve entries from, or add entries to, the +file, as the result of commands issued by the user, the file named by the <i>ENV</i> variable, or implementation-defined system +start-up files. Implementations may choose to disable the history list mechanism for users with appropriate privileges who do not +set <i>HISTFILE ;</i> the specific circumstances under which this occurs are implementation-defined. If more than one instance of +the shell is using the same history file, it is unspecified how updates to the history file from those shells interact. As entries +are deleted from the history file, they shall be deleted oldest first. It is unspecified when history file entries are physically +removed from the history file. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><i>HISTSIZE</i></dt> +<dd><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine a decimal number representing the limit to the number of previous commands that are accessible. If this variable is +unset, an unspecified default greater than or equal to 128 shall be used. The maximum number of commands in the history list is +unspecified, but shall be at least 128. An implementation may choose to access this variable only when initializing the history +file, as described under <i>HISTFILE .</i> Therefore, it is unspecified whether changes made to <i>HISTSIZE</i> after the history +file has been initialized are effective. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><i>HOME</i></dt> +<dd>Determine the pathname of the user's home directory. The contents of <i>HOME</i> are used in tilde expansion as described in +<a href="../utilities/V3_chap02.html#tag_19_06_01"><i>2.6.1 Tilde Expansion</i></a> .</dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_COLLATE</i></dt> +<dd><br> +Determine the behavior of range expressions, equivalence classes, and multi-character collating elements within pattern +matching.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files), which characters are defined as letters (character class +<b>alpha</b>), and the behavior of character classes within pattern matching.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>MAIL</i></dt> +<dd><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine a pathname of the user's mailbox file for purposes of incoming mail notification. If this variable is set, the shell +shall inform the user if the file named by the variable is created or if its modification time has changed. Informing the user +shall be accomplished by writing a string of unspecified format to standard error prior to the writing of the next primary prompt +string. Such check shall be performed only after the completion of the interval defined by the <i>MAILCHECK</i> variable after the +last such check. The user shall be informed only if <i>MAIL</i> is set and <i>MAILPATH</i> is not set. <img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><i>MAILCHECK</i></dt> +<dd><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border= +"0"><br> +Establish a decimal integer value that specifies how often (in seconds) the shell shall check for the arrival of mail in the files +specified by the <i>MAILPATH</i> or <i>MAIL</i> variables. The default value shall be 600 seconds. If set to zero, the shell shall +check before issuing each primary prompt. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><i>MAILPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Provide a list of pathnames and optional messages separated by <colon> characters. If this variable is set, the shell shall +inform the user if any of the files named by the variable are created or if any of their modification times change. (See the +preceding entry for <i>MAIL</i> for descriptions of mail arrival and user informing.) Each pathname can be followed by <tt>'%'</tt> +and a string that shall be subjected to parameter expansion and written to standard error when the modification time changes. If a +<tt>'%'</tt> character in the pathname is preceded by a <backslash>, it shall be treated as a literal <tt>'%'</tt> in the +pathname. The default message is unspecified. +<p>The <i>MAILPATH</i> environment variable takes precedence over the <i>MAIL</i> variable. <img src="../images/opt-end.gif" alt= +"[Option End]" border="0"></p> +</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>PATH</i></dt> +<dd>Establish a string formatted as described in XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment +Variables</i></a> , used to effect command interpretation; see <a href="../utilities/V3_chap02.html#tag_19_09_01_04"><i>2.9.1.4 +Command Search and Execution</i></a> .</dd> +<dt><i>PWD</i></dt> +<dd>This variable shall represent an absolute pathname of the current working directory. Assignments to this variable may be +ignored.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_110_09" id="tag_20_110_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>The <i>sh</i> utility shall take the standard action for all signals (see <a href="../utilities/V3_chap01.html#tag_18_04"><i>1.4 +Utility Description Defaults</i></a> ) with the following exceptions.</p> +<p>If the shell is interactive, SIGINT signals received during command line editing shall be handled as described in the EXTENDED +DESCRIPTION, and SIGINT signals received at other times shall be caught but no action performed.<br></p> +<p>If the shell is interactive:</p> +<ul> +<li> +<p>SIGQUIT and SIGTERM signals shall be ignored.</p> +</li> +<li> +<p>If the <b>-m</b> option is in effect, SIGTTIN, SIGTTOU, and SIGTSTP signals shall be ignored.</p> +</li> +<li> +<p>If the <b>-m</b> option is not in effect, it is unspecified whether SIGTTIN, SIGTTOU, and SIGTSTP signals are ignored, set to +the default action, or caught. If they are caught, the shell shall, in the signal-catching function, set the signal to the default +action and raise the signal (after taking any appropriate steps, such as restoring terminal settings).</p> +</li> +</ul> +<p>The standard actions, and the actions described above for interactive shells, can be overridden by use of the <a href= +"../utilities/trap.html"><i>trap</i></a> special built-in utility (see <a href= +"../utilities/V3_chap02.html#tag_19_29"><i>trap</i></a> and <a href="../utilities/V3_chap02.html#tag_19_12"><i>2.12 Signals and +Error Handling</i></a> ).</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_110_10" id="tag_20_110_10"></a>STDOUT</h4> +<blockquote> +<p>See the STDERR section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_110_11" id="tag_20_110_11"></a>STDERR</h4> +<blockquote> +<p>Except as otherwise stated (by the descriptions of any invoked utilities or in interactive mode), standard error shall be used +only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_110_12" id="tag_20_110_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_110_13" id="tag_20_110_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>See <a href="../utilities/V3_chap02.html#tag_19"><i>2. Shell Command Language</i></a> . <sup>[<a href= +"javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> The +functionality described in the rest of the EXTENDED DESCRIPTION section shall be provided on implementations that support the User +Portability Utilities option (and the rest of this section is not further shaded for this option). <img src="../images/opt-end.gif" +alt="[Option End]" border="0"></p> +<h5><a name="tag_20_110_13_01" id="tag_20_110_13_01"></a>Command History List</h5> +<p>When the <i>sh</i> utility is being used interactively, it shall maintain a list of commands previously entered from the +terminal in the file named by the <i>HISTFILE</i> environment variable. The type, size, and internal format of this file are +unspecified. Multiple <i>sh</i> processes can share access to the file for a user, if file access permissions allow this; see the +description of the <i>HISTFILE</i> environment variable.</p> +<h5><a name="tag_20_110_13_02" id="tag_20_110_13_02"></a>Command Line Editing</h5> +<p>When <i>sh</i> is being used interactively from a terminal, the current command and the command history (see <a href= +"../utilities/fc.html#"><i>fc</i></a> ) can be edited using <a href="../utilities/vi.html"><i>vi</i></a>-mode command line editing. +This mode uses commands, described below, similar to a subset of those described in the <a href= +"../utilities/vi.html"><i>vi</i></a> utility. Implementations may offer other command line editing modes corresponding to other +editing utilities.</p> +<p>The command <a href="../utilities/V3_chap02.html#set"><i>set</i></a> <b>-o</b> <a href="../utilities/vi.html"><i>vi</i></a> +shall enable <a href="../utilities/vi.html"><i>vi</i></a>-mode editing and place <i>sh</i> into <a href= +"../utilities/vi.html"><i>vi</i></a> insert mode (see <a href="#tag_20_110_13_03">Command Line Editing (vi-mode)</a> ). This +command also shall disable any other editing mode that the implementation may provide. The command <a href= +"../utilities/V3_chap02.html#set"><i>set</i></a> <b>+o</b> <a href="../utilities/vi.html"><i>vi</i></a> disables <a href= +"../utilities/vi.html"><i>vi</i></a>-mode editing.</p> +<p>Certain block-mode terminals may be unable to support shell command line editing. If a terminal is unable to provide either edit +mode, it need not be possible to <a href="../utilities/V3_chap02.html#set"><i>set</i></a> <b>-o</b> <a href= +"../utilities/vi.html"><i>vi</i></a> when using the shell on this terminal.</p> +<p>In the following sections, the characters <i>erase</i>, <i>interrupt</i>, <i>kill</i>, and <i>end-of-file</i> are those set by +the <a href="../utilities/stty.html"><i>stty</i></a> utility.</p> +<h5><a name="tag_20_110_13_03" id="tag_20_110_13_03"></a>Command Line Editing (vi-mode)</h5> +<p>In <a href="../utilities/vi.html"><i>vi</i></a> editing mode, there shall be a distinguished line, the edit line. All the +editing operations which modify a line affect the edit line. The edit line is always the newest line in the command history +buffer.</p> +<p>With <a href="../utilities/vi.html"><i>vi</i></a>-mode enabled, <i>sh</i> can be switched between insert mode and command +mode.</p> +<p>When in insert mode, an entered character shall be inserted into the command line, except as noted in <a href= +"#tag_20_110_13_04">vi Line Editing Insert Mode</a> . Upon entering <i>sh</i> and after termination of the previous command, +<i>sh</i> shall be in insert mode.</p> +<p>Typing an escape character shall switch <i>sh</i> into command mode (see <a href="#tag_20_110_13_05">vi Line Editing Command +Mode</a> ). In command mode, an entered character shall either invoke a defined operation, be used as part of a multi-character +operation, or be treated as an error. A character that is not recognized as part of an editing command shall terminate any specific +editing command and shall alert the terminal. If <i>sh</i> receives a SIGINT signal in command mode (whether generated by typing +the <i>interrupt</i> character or by other means), it shall terminate command line editing on the current command line, reissue the +prompt on the next line of the terminal, and reset the command history (see <a href="../utilities/fc.html#"><i>fc</i></a> ) so that +the most recently executed command is the previous command (that is, the command that was being edited when it was interrupted is +not re-entered into the history).</p> +<p>In the following sections, the phrase "move the cursor to the beginning of the word" shall mean "move the cursor to the first +character of the current word" and the phrase "move the cursor to the end of the word" shall mean "move the cursor to the last +character of the current word". The phrase "beginning of the command line" indicates the point between the end of the prompt +string issued by the shell (or the beginning of the terminal line, if there is no prompt string) and the first character of the +command text.</p> +<h5><a name="tag_20_110_13_04" id="tag_20_110_13_04"></a>vi Line Editing Insert Mode</h5> +<p>While in insert mode, any character typed shall be inserted in the current command line, unless it is from the following +set.</p> +<dl compact> +<dd></dd> +<dt><newline></dt> +<dd>Execute the current command line. If the current command line is not empty, this line shall be entered into the command history +(see <a href="../utilities/fc.html#"><i>fc</i></a> ).</dd> +<dt><i>erase</i></dt> +<dd>Delete the character previous to the current cursor position and move the current cursor position back one character. In insert +mode, characters shall be erased from both the screen and the buffer when backspacing.</dd> +<dt><i>interrupt</i></dt> +<dd>If <i>sh</i> receives a SIGINT signal in insert mode (whether generated by typing the <i>interrupt</i> character or by other +means), it shall terminate command line editing with the same effects as described for interrupting command mode; see <a href= +"#tag_20_110_13_03">Command Line Editing (vi-mode)</a> .</dd> +<dt><i>kill</i></dt> +<dd>Clear all the characters from the input line.</dd> +<dt><control>-V</dt> +<dd>Insert the next character input, even if the character is otherwise a special insert mode character.</dd> +<dt><control>-W</dt> +<dd>Delete the characters from the one preceding the cursor to the preceding word boundary. The word boundary in this case is the +closer to the cursor of either the beginning of the line or a character that is in neither the <b>blank</b> nor <b>punct</b> +character classification of the current locale.</dd> +<dt><i>end-of-file</i></dt> +<dd>Interpreted as the end of input in <i>sh</i>. This interpretation shall occur only at the beginning of an input line. If +<i>end-of-file</i> is entered other than at the beginning of the line, the results are unspecified.</dd> +<dt><ESC></dt> +<dd>Place <i>sh</i> into command mode.</dd> +</dl> +<h5><a name="tag_20_110_13_05" id="tag_20_110_13_05"></a>vi Line Editing Command Mode</h5> +<p>In command mode for the command line editing feature, decimal digits not beginning with 0 that precede a command letter shall be +remembered. Some commands use these decimal digits as a count number that affects the operation.</p> +<p>The term <i>motion command</i> represents one of the commands:</p> +<pre> +<tt><space> 0 b F l W ^ $ ; E f T w | , B e h t +</tt></pre> +<p>If the current line is not the edit line, any command that modifies the current line shall cause the content of the current line +to replace the content of the edit line, and the current line shall become the edit line. This replacement cannot be undone (see +the <b>u</b> and <b>U</b> commands below). The modification requested shall then be performed to the edit line. When the current +line is the edit line, the modification shall be done directly to the edit line.</p> +<p>Any command that is preceded by <i>count</i> shall take a count (the numeric value of any preceding decimal digits). Unless +otherwise noted, this count shall cause the specified operation to repeat by the number of times specified by the count. Also +unless otherwise noted, a <i>count</i> that is out of range is considered an error condition and shall alert the terminal, but +neither the cursor position, nor the command line, shall change.</p> +<p>The terms <i>word</i> and <i>bigword</i> are used as defined in the <a href="../utilities/vi.html"><i>vi</i></a> description. +The term <i>save buffer</i> corresponds to the term <i>unnamed buffer</i> in <a href="../utilities/vi.html"><i>vi</i></a>.</p> +<p>The following commands shall be recognized in command mode:</p> +<dl compact> +<dd></dd> +<dt><newline></dt> +<dd>Execute the current command line. If the current command line is not empty, this line shall be entered into the command history +(see <a href="../utilities/fc.html#"><i>fc</i></a> ).</dd> +<dt><control>-L</dt> +<dd>Redraw the current command line. Position the cursor at the same location on the redrawn line.</dd> +<dt><b>#</b></dt> +<dd>Insert the character <tt>'#'</tt> at the beginning of the current command line and treat the resulting edit line as a comment. +This line shall be entered into the command history; see <a href="../utilities/fc.html#"><i>fc</i></a> .</dd> +<dt><b>=</b></dt> +<dd>Display the possible shell word expansions (see <a href="../utilities/V3_chap02.html#tag_19_06"><i>2.6 Word Expansions</i></a> +) of the bigword at the current command line position. <basefont size="2"> +<dl> +<dt><b>Note:</b></dt> +<dd>This does not modify the content of the current line, and therefore does not cause the current line to become the edit +line.</dd> +</dl> +<basefont size="3"> +<p>These expansions shall be displayed on subsequent terminal lines. If the bigword contains none of the characters <tt>'?'</tt>, +<tt>'*'</tt>, or <tt>'['</tt>, an <asterisk> (<tt>'*'</tt>) shall be implicitly assumed at the end. If any directories are +matched, these expansions shall have a <tt>'/'</tt> character appended. After the expansion, the line shall be redrawn, the cursor +repositioned at the current cursor position, and <i>sh</i> shall be placed in command mode.</p> +</dd> +<dt><b>\</b></dt> +<dd>Perform pathname expansion (see <a href="../utilities/V3_chap02.html#tag_19_06_06"><i>2.6.6 Pathname Expansion</i></a> ) on the +current bigword, up to the largest set of characters that can be matched uniquely. If the bigword contains none of the characters +<tt>'?'</tt>, <tt>'*'</tt>, or <tt>'['</tt>, an <asterisk> (<tt>'*'</tt>) shall be implicitly assumed at the end. This +maximal expansion then shall replace the original bigword in the command line, and the cursor shall be placed after this expansion. +If the resulting bigword completely and uniquely matches a directory, a <tt>'/'</tt> character shall be inserted directly after the +bigword. If some other file is completely matched, a single <space> shall be inserted after the bigword. After this +operation, <i>sh</i> shall be placed in insert mode.</dd> +<dt><b>*</b></dt> +<dd>Perform pathname expansion on the current bigword and insert all expansions into the command to replace the current bigword, +with each expansion separated by a single <space>. If at the end of the line, the current cursor position shall be moved to +the first column position following the expansions and <i>sh</i> shall be placed in insert mode. Otherwise, the current cursor +position shall be the last column position of the first character after the expansions and <i>sh</i> shall be placed in insert +mode. If the current bigword contains none of the characters <tt>'?'</tt>, <tt>'*'</tt>, or <tt>'['</tt>, before the operation, an +<asterisk> (<tt>'*'</tt>) shall be implicitly assumed at the end.</dd> +<dt><b>@</b><i>letter</i></dt> +<dd>Insert the value of the alias named <i>_letter</i>. The symbol <i>letter</i> represents a single alphabetic character from the +portable character set; implementations may support additional characters as an extension. If the alias <i>_letter</i> contains +other editing commands, these commands shall be performed as part of the insertion. If no alias <i>_letter</i> is enabled, this +command shall have no effect.</dd> +<dt><b>[</b><i>count</i><b>]~</b></dt> +<dd>Convert, if the current character is a lowercase letter, to the equivalent uppercase letter and <i>vice versa</i>, as +prescribed by the current locale. The current cursor position then shall be advanced by one character. If the cursor was positioned +on the last character of the line, the case conversion shall occur, but the cursor shall not advance. If the <tt>'~'</tt> command +is preceded by a <i>count</i>, that number of characters shall be converted, and the cursor shall be advanced to the character +position after the last character converted. If the <i>count</i> is larger than the number of characters after the cursor, this +shall not be considered an error; the cursor shall advance to the last character on the line.</dd> +<dt><b>[</b><i>count</i><b>].</b></dt> +<dd>Repeat the most recent non-motion command, even if it was executed on an earlier command line. If the previous command was +preceded by a <i>count</i>, and no count is given on the <tt>'.'</tt> command, the count from the previous command shall be +included as part of the repeated command. If the <tt>'.'</tt> command is preceded by a <i>count</i>, this shall override any +<i>count</i> argument to the previous command. The <i>count</i> specified in the <tt>'.'</tt> command shall become the count for +subsequent <tt>'.'</tt> commands issued without a count.</dd> +<dt><b>[</b><i>number</i><b>]v</b></dt> +<dd>Invoke the <a href="../utilities/vi.html"><i>vi</i></a> editor to edit the current command line in a temporary file. When the +editor exits, the commands in the temporary file shall be executed and placed in the command history. If a <i>number</i> is +included, it specifies the command number in the command history to be edited, rather than the current command line.</dd> +<dt><b>[</b><i>count</i><b>]l</b> (ell)</dt> +<dd></dd> +<dt><b>[</b><i>count</i><b>]</b><space></dt> +<dd><br> +Move the current cursor position to the next character position. If the cursor was positioned on the last character of the line, +the terminal shall be alerted and the cursor shall not be advanced. If the <i>count</i> is larger than the number of characters +after the cursor, this shall not be considered an error; the cursor shall advance to the last character on the line.</dd> +<dt><b>[</b><i>count</i><b>]h</b></dt> +<dd>Move the current cursor position to the <i>count</i>th (default 1) previous character position. If the cursor was positioned on +the first character of the line, the terminal shall be alerted and the cursor shall not be moved. If the count is larger than the +number of characters before the cursor, this shall not be considered an error; the cursor shall move to the first character on the +line.</dd> +<dt><b>[</b><i>count</i><b>]w</b></dt> +<dd>Move to the start of the next word. If the cursor was positioned on the last character of the line, the terminal shall be +alerted and the cursor shall not be advanced. If the <i>count</i> is larger than the number of words after the cursor, this shall +not be considered an error; the cursor shall advance to the last character on the line.</dd> +<dt><b>[</b><i>count</i><b>]W</b></dt> +<dd>Move to the start of the next bigword. If the cursor was positioned on the last character of the line, the terminal shall be +alerted and the cursor shall not be advanced. If the <i>count</i> is larger than the number of bigwords after the cursor, this +shall not be considered an error; the cursor shall advance to the last character on the line.</dd> +<dt><b>[</b><i>count</i><b>]e</b></dt> +<dd>Move to the end of the current word. If at the end of a word, move to the end of the next word. If the cursor was positioned on +the last character of the line, the terminal shall be alerted and the cursor shall not be advanced. If the <i>count</i> is larger +than the number of words after the cursor, this shall not be considered an error; the cursor shall advance to the last character on +the line.</dd> +<dt><b>[</b><i>count</i><b>]E</b></dt> +<dd>Move to the end of the current bigword. If at the end of a bigword, move to the end of the next bigword. If the cursor was +positioned on the last character of the line, the terminal shall be alerted and the cursor shall not be advanced. If the +<i>count</i> is larger than the number of bigwords after the cursor, this shall not be considered an error; the cursor shall +advance to the last character on the line.</dd> +<dt><b>[</b><i>count</i><b>]b</b></dt> +<dd>Move to the beginning of the current word. If at the beginning of a word, move to the beginning of the previous word. If the +cursor was positioned on the first character of the line, the terminal shall be alerted and the cursor shall not be moved. If the +<i>count</i> is larger than the number of words preceding the cursor, this shall not be considered an error; the cursor shall +return to the first character on the line.</dd> +<dt><b>[</b><i>count</i><b>]B</b></dt> +<dd>Move to the beginning of the current bigword. If at the beginning of a bigword, move to the beginning of the previous bigword. +If the cursor was positioned on the first character of the line, the terminal shall be alerted and the cursor shall not be moved. +If the <i>count</i> is larger than the number of bigwords preceding the cursor, this shall not be considered an error; the cursor +shall return to the first character on the line.</dd> +<dt><b>^</b></dt> +<dd>Move the current cursor position to the first character on the input line that is not a <blank>.</dd> +<dt><b>$</b></dt> +<dd>Move to the last character position on the current command line.</dd> +<dt><b>0</b></dt> +<dd>(Zero.) Move to the first character position on the current command line.</dd> +<dt><b>[</b><i>count</i><b>]|</b></dt> +<dd>Move to the <i>count</i>th character position on the current command line. If no number is specified, move to the first +position. The first character position shall be numbered 1. If the count is larger than the number of characters on the line, this +shall not be considered an error; the cursor shall be placed on the last character on the line.</dd> +<dt><b>[</b><i>count</i><b>]f</b><i>c</i></dt> +<dd>Move to the first occurrence of the character <tt>'c'</tt> that occurs after the current cursor position. If the cursor was +positioned on the last character of the line, the terminal shall be alerted and the cursor shall not be advanced. If the character +<tt>'c'</tt> does not occur in the line after the current cursor position, the terminal shall be alerted and the cursor shall not +be moved.</dd> +<dt><b>[</b><i>count</i><b>]F</b><i>c</i></dt> +<dd>Move to the first occurrence of the character <tt>'c'</tt> that occurs before the current cursor position. If the cursor was +positioned on the first character of the line, the terminal shall be alerted and the cursor shall not be moved. If the character +<tt>'c'</tt> does not occur in the line before the current cursor position, the terminal shall be alerted and the cursor shall not +be moved.</dd> +<dt><b>[</b><i>count</i><b>]t</b><i>c</i></dt> +<dd>Move to the character before the first occurrence of the character <tt>'c'</tt> that occurs after the current cursor position. +If the cursor was positioned on the last character of the line, the terminal shall be alerted and the cursor shall not be advanced. +If the character <tt>'c'</tt> does not occur in the line after the current cursor position, the terminal shall be alerted and the +cursor shall not be moved.</dd> +<dt><b>[</b><i>count</i><b>]T</b><i>c</i></dt> +<dd>Move to the character after the first occurrence of the character <tt>'c'</tt> that occurs before the current cursor position. +If the cursor was positioned on the first character of the line, the terminal shall be alerted and the cursor shall not be moved. +If the character <tt>'c'</tt> does not occur in the line before the current cursor position, the terminal shall be alerted and the +cursor shall not be moved.</dd> +<dt><b>[</b><i>count</i><b>];</b></dt> +<dd>Repeat the most recent <b>f</b>, <b>F</b>, <b>t</b>, or <b>T</b> command. Any number argument on that previous command shall be +ignored. Errors are those described for the repeated command.</dd> +<dt><b>[</b><i>count</i><b>],</b></dt> +<dd>Repeat the most recent <b>f</b>, <b>F</b>, <b>t</b>, or <b>T</b> command. Any number argument on that previous command shall be +ignored. However, reverse the direction of that command.</dd> +<dt><b>a</b></dt> +<dd>Enter insert mode after the current cursor position. Characters that are entered shall be inserted before the next +character.</dd> +<dt><b>A</b></dt> +<dd>Enter insert mode after the end of the current command line.</dd> +<dt><b>i</b></dt> +<dd>Enter insert mode at the current cursor position. Characters that are entered shall be inserted before the current +character.</dd> +<dt><b>I</b></dt> +<dd>Enter insert mode at the beginning of the current command line.</dd> +<dt><b>R</b></dt> +<dd>Enter insert mode, replacing characters from the command line beginning at the current cursor position.</dd> +<dt><b>[</b><i>count</i><b>]c</b><i>motion</i></dt> +<dd><br> +Delete the characters between the current cursor position and the cursor position that would result from the specified motion +command. Then enter insert mode before the first character following any deleted characters. If <i>count</i> is specified, it shall +be applied to the motion command. A <i>count</i> shall be ignored for the following motion commands: +<pre> +<tt>0 ^ $ c +</tt></pre> +<p>If the motion command is the character <tt>'c'</tt>, the current command line shall be cleared and insert mode shall be entered. +If the motion command would move the current cursor position toward the beginning of the command line, the character under the +current cursor position shall not be deleted. If the motion command would move the current cursor position toward the end of the +command line, the character under the current cursor position shall be deleted. If the <i>count</i> is larger than the number of +characters between the current cursor position and the end of the command line toward which the motion command would move the +cursor, this shall not be considered an error; all of the remaining characters in the aforementioned range shall be deleted and +insert mode shall be entered. If the motion command is invalid, the terminal shall be alerted, the cursor shall not be moved, and +no text shall be deleted.</p> +</dd> +<dt><b>C</b></dt> +<dd>Delete from the current character to the end of the line and enter insert mode at the new end-of-line.</dd> +<dt><b>S</b></dt> +<dd>Clear the entire edit line and enter insert mode.</dd> +<dt><b>[</b><i>count</i><b>]r</b><i>c</i></dt> +<dd>Replace the current character with the character <tt>'c'</tt>. With a number <i>count</i>, replace the current and the +following <i>count</i>-1 characters. After this command, the current cursor position shall be on the last character that was +changed. If the <i>count</i> is larger than the number of characters after the cursor, this shall not be considered an error; all +of the remaining characters shall be changed.</dd> +<dt><b>[</b><i>count</i><b>]_</b></dt> +<dd>Append a <space> after the current character position and then append the last bigword in the previous input line after +the <space>. Then enter insert mode after the last character just appended. With a number <i>count</i>, append the +<i>count</i>th bigword in the previous line.</dd> +<dt><b>[</b><i>count</i><b>]x</b></dt> +<dd>Delete the character at the current cursor position and place the deleted characters in the save buffer. If the cursor was +positioned on the last character of the line, the character shall be deleted and the cursor position shall be moved to the previous +character (the new last character). If the <i>count</i> is larger than the number of characters after the cursor, this shall not be +considered an error; all the characters from the cursor to the end of the line shall be deleted.</dd> +<dt><b>[</b><i>count</i><b>]X</b></dt> +<dd>Delete the character before the current cursor position and place the deleted characters in the save buffer. The character +under the current cursor position shall not change. If the cursor was positioned on the first character of the line, the terminal +shall be alerted, and the <b>X</b> command shall have no effect. If the line contained a single character, the <b>X</b> command +shall have no effect. If the line contained no characters, the terminal shall be alerted and the cursor shall not be moved. If the +<i>count</i> is larger than the number of characters before the cursor, this shall not be considered an error; all the characters +from before the cursor to the beginning of the line shall be deleted.</dd> +<dt><b>[</b><i>count</i><b>]d</b><i>motion</i></dt> +<dd><br> +Delete the characters between the current cursor position and the character position that would result from the motion command. A +number <i>count</i> repeats the motion command <i>count</i> times. If the motion command would move toward the beginning of the +command line, the character under the current cursor position shall not be deleted. If the motion command is <b>d</b>, the entire +current command line shall be cleared. If the <i>count</i> is larger than the number of characters between the current cursor +position and the end of the command line toward which the motion command would move the cursor, this shall not be considered an +error; all of the remaining characters in the aforementioned range shall be deleted. The deleted characters shall be placed in the +save buffer.</dd> +<dt><b>D</b></dt> +<dd>Delete all characters from the current cursor position to the end of the line. The deleted characters shall be placed in the +save buffer.</dd> +<dt><b>[</b><i>count</i><b>]y</b><i>motion</i></dt> +<dd><br> +Yank (that is, copy) the characters from the current cursor position to the position resulting from the motion command into the +save buffer. A number <i>count</i> shall be applied to the motion command. If the motion command would move toward the beginning of +the command line, the character under the current cursor position shall not be included in the set of yanked characters. If the +motion command is <b>y</b>, the entire current command line shall be yanked into the save buffer. The current cursor position shall +be unchanged. If the <i>count</i> is larger than the number of characters between the current cursor position and the end of the +command line toward which the motion command would move the cursor, this shall not be considered an error; all of the remaining +characters in the aforementioned range shall be yanked.</dd> +<dt><b>Y</b></dt> +<dd>Yank the characters from the current cursor position to the end of the line into the save buffer. The current character +position shall be unchanged.</dd> +<dt><b>[</b><i>count</i><b>]p</b></dt> +<dd>Put a copy of the current contents of the save buffer after the current cursor position. The current cursor position shall be +advanced to the last character put from the save buffer. A <i>count</i> shall indicate how many copies of the save buffer shall be +put.</dd> +<dt><b>[</b><i>count</i><b>]P</b></dt> +<dd>Put a copy of the current contents of the save buffer before the current cursor position. The current cursor position shall be +moved to the last character put from the save buffer. A <i>count</i> shall indicate how many copies of the save buffer shall be +put.</dd> +<dt><b>u</b></dt> +<dd>Undo the last command that changed the edit line. This operation shall not undo the copy of any command line to the edit +line.</dd> +<dt><b>U</b></dt> +<dd>Undo all changes made to the edit line. This operation shall not undo the copy of any command line to the edit line.</dd> +<dt><b>[</b><i>count</i><b>]k</b></dt> +<dd></dd> +<dt><b>[</b><i>count</i><b>]-</b></dt> +<dd>Set the current command line to be the <i>count</i>th previous command line in the shell command history. If <i>count</i> is +not specified, it shall default to 1. The cursor shall be positioned on the first character of the new command. If a <b>k</b> or +<b>-</b> command would retreat past the maximum number of commands in effect for this shell (affected by the <i>HISTSIZE</i> +environment variable), the terminal shall be alerted, and the command shall have no effect.</dd> +<dt><b>[</b><i>count</i><b>]j</b></dt> +<dd></dd> +<dt><b>[</b><i>count</i><b>]+</b></dt> +<dd>Set the current command line to be the <i>count</i>th next command line in the shell command history. If <i>count</i> is not +specified, it shall default to 1. The cursor shall be positioned on the first character of the new command. If a <b>j</b> or +<b>+</b> command advances past the edit line, the current command line shall be restored to the edit line and the terminal shall be +alerted.</dd> +<dt><b>[</b><i>number</i><b>]G</b></dt> +<dd>Set the current command line to be the oldest command line stored in the shell command history. With a number <i>number</i>, +set the current command line to be the command line <i>number</i> in the history. If command line <i>number</i> does not exist, the +terminal shall be alerted and the command line shall not be changed.</dd> +<dt><b>/</b><i>pattern</i><newline></dt> +<dd><br> +Move backwards through the command history, searching for the specified pattern, beginning with the previous command line. Patterns +use the pattern matching notation described in <a href="../utilities/V3_chap02.html#tag_19_14"><i>2.14 Pattern Matching +Notation</i></a> , except that the <tt>'^'</tt> character shall have special meaning when it appears as the first character of +<i>pattern</i>. In this case, the <tt>'^'</tt> is discarded and the characters after the <tt>'^'</tt> shall be matched only at the +beginning of a line. Commands in the command history shall be treated as strings, not as filenames. If the pattern is not found, +the current command line shall be unchanged and the terminal shall be alerted. If it is found in a previous line, the current +command line shall be set to that line and the cursor shall be set to the first character of the new command line. +<p>If <i>pattern</i> is empty, the last non-empty pattern provided to <b>/</b> or <b>?</b> shall be used. If there is no previous +non-empty pattern, the terminal shall be alerted and the current command line shall remain unchanged.</p> +</dd> +<dt><b>?</b><i>pattern</i><newline></dt> +<dd><br> +Move forwards through the command history, searching for the specified pattern, beginning with the next command line. Patterns use +the pattern matching notation described in <a href="../utilities/V3_chap02.html#tag_19_14"><i>2.14 Pattern Matching +Notation</i></a> , except that the <tt>'^'</tt> character shall have special meaning when it appears as the first character of +<i>pattern</i>. In this case, the <tt>'^'</tt> is discarded and the characters after the <tt>'^'</tt> shall be matched only at the +beginning of a line. Commands in the command history shall be treated as strings, not as filenames. If the pattern is not found, +the current command line shall be unchanged and the terminal shall be alerted. If it is found in a following line, the current +command line shall be set to that line and the cursor shall be set to the fist character of the new command line. +<p>If <i>pattern</i> is empty, the last non-empty pattern provided to <b>/</b> or <b>?</b> shall be used. If there is no previous +non-empty pattern, the terminal shall be alerted and the current command line shall remain unchanged.</p> +</dd> +<dt><b>n</b></dt> +<dd>Repeat the most recent <b>/</b> or <b>?</b> command. If there is no previous <b>/</b> or <b>?</b>, the terminal shall be +alerted and the current command line shall remain unchanged.</dd> +<dt><b>N</b></dt> +<dd>Repeat the most recent <b>/</b> or <b>?</b> command, reversing the direction of the search. If there is no previous <b>/</b> or +<b>?</b>, the terminal shall be alerted and the current command line shall remain unchanged.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_110_14" id="tag_20_110_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>The script to be executed consisted solely of zero or more blank lines or comments, or both.</dd> +<dt>1-125</dt> +<dd>A non-interactive shell detected an error other than <i>command_file</i> not found, <i>command_file</i> not executable, or an +unrecoverable read error while reading commands (except from the <i>file</i> operand of the <a href= +"../utilities/dot.html"><i>dot</i></a> special built-in); including but not limited to syntax, redirection, or variable assignment +errors.</dd> +<dt> 126</dt> +<dd>A specified <i>command_file</i> could not be executed due to an [ENOEXEC] error (see <a href= +"../utilities/V3_chap02.html#tag_19_09_01_04"><i>2.9.1.4 Command Search and Execution</i></a> , item 2).</dd> +<dt> 127</dt> +<dd>A specified <i>command_file</i> could not be found by a non-interactive shell.</dd> +<dt> 128</dt> +<dd>An unrecoverable read error was detected while reading commands, except from the <i>file</i> operand of the <a href= +"../utilities/dot.html"><i>dot</i></a> special built-in.</dd> +</dl> +<p>Otherwise, the shell shall terminate in the same manner as for an <a href="../utilities/V3_chap02.html#exit"><i>exit</i></a> +command with no operands, unless the last command the shell invoked was executed without forking, in which case the wait status +seen by the parent process of the shell shall be the wait status of the last command the shell invoked. See the <a href= +"../utilities/V3_chap02.html#exit"><i>exit</i></a> utility in <a href="../utilities/V3_chap02.html#tag_19_15"><i>2.15 Special +Built-In Utilities</i></a> .</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_110_15" id="tag_20_110_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>See <a href="../utilities/V3_chap02.html#tag_19_08_01"><i>2.8.1 Consequences of Shell Errors</i></a> .</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_110_16" id="tag_20_110_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Standard input and standard error are the files that determine whether a shell is interactive when <b>-i</b> is not specified. +For example:</p> +<pre> +<tt>sh > file +</tt></pre> +<p>and:</p> +<pre> +<tt>sh 2> file +</tt></pre> +<p>create interactive and non-interactive shells, respectively. Although both accept terminal input, the results of error +conditions are different, as described in <a href="../utilities/V3_chap02.html#tag_19_08_01"><i>2.8.1 Consequences of Shell +Errors</i></a> ; in the second example a redirection error encountered by a special built-in utility aborts the shell.</p> +<p><i>sh</i> <b>-n</b> can be used to check for many syntax errors without waiting for <i>complete_commands</i> to be executed, but +may be fooled into declaring false positives or missing actual errors that would occur when the shell actually evaluates <a href= +"../utilities/eval.html"><i>eval</i></a> commands present in the script, or if there are <a href= +"../utilities/alias.html"><i>alias</i></a> (or <a href="../utilities/unalias.html"><i>unalias</i></a>) commands in the script that +would alter the syntax of commands that use the affected aliases.</p> +<p>A conforming application must protect its first operand, if it starts with a <plus-sign>, by preceding it with the +<tt>"--"</tt> argument that denotes the end of the options.</p> +<p>Applications should note that the standard <i>PATH</i> to the shell cannot be assumed to be either <b>/bin/sh</b> or +<b>/usr/bin/sh</b>, and should be determined by interrogation of the <i>PATH</i> returned by <a href= +"../utilities/getconf.html"><i>getconf</i></a> <i>PATH ,</i> ensuring that the returned pathname is an absolute pathname and not a +shell built-in.</p> +<p>For example, to determine the location of the standard <i>sh</i> utility:</p> +<pre> +<tt>command -v sh +</tt></pre> +<p>On some implementations this might return:</p> +<pre> +<tt>/usr/xpg4/bin/sh +</tt></pre> +<p>Furthermore, on systems that support executable scripts (the <tt>"#!"</tt> construct), it is recommended that applications using +executable scripts install them using <a href="../utilities/getconf.html"><i>getconf</i></a> <i>PATH</i> to determine the shell +pathname and update the <tt>"#!"</tt> script appropriately as it is being installed (for example, with <a href= +"../utilities/sed.html"><i>sed</i></a>). For example:</p> +<pre> +<tt># +# Installation time script to install correct POSIX shell pathname +# +# Get list of paths to check +# +Sifs=$IFS +Sifs_set=${IFS+y} +IFS=: +set -- $(getconf PATH) +if [ "$Sifs_set" = y ] +then + IFS=$Sifs +else + unset IFS +fi +# +# Check each path for 'sh' +# +for i +do + if [ -x "${i}"/sh ] + then + Pshell=${i}/sh + fi +done +# +# This is the list of scripts to update. They should be of the +# form '${name}.source' and will be transformed to '${name}'. +# Each script should begin: +# +# #!INSTALLSHELLPATH +# +scripts="a b c" +# +# Transform each script +# +for i in ${scripts} +do + sed -e "s|INSTALLSHELLPATH|${Pshell}|" < ${i}.source > ${i} +done +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_110_17" id="tag_20_110_17"></a>EXAMPLES</h4> +<blockquote> +<ol> +<li> +<p>Execute a shell command from a string:</p> +<pre> +<tt>sh -c "cat myfile" +</tt></pre></li> +<li> +<p>Execute a shell script from a file in the current directory:</p> +<pre> +<tt>sh my_shell_cmds +</tt></pre></li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_110_18" id="tag_20_110_18"></a>RATIONALE</h4> +<blockquote> +<p>The <i>sh</i> utility and the <a href="../utilities/V3_chap02.html#set"><i>set</i></a> special built-in utility share a common +set of options.</p> +<p>The name <i>IFS</i> was originally an abbreviation of "Input Field Separators"; however, this name is misleading as the +<i>IFS</i> characters are actually used as field terminators. One justification for ignoring the contents of <i>IFS</i> upon entry +to the script, beyond security considerations, is to assist possible future shell compilers. Allowing <i>IFS</i> to be imported +from the environment prevents many optimizations that might otherwise be performed via dataflow analysis of the script itself.</p> +<p>The text in the STDIN section about non-blocking reads concerns an instance of <i>sh</i> that has been invoked, probably by a +C-language program, with standard input that has been opened using the O_NONBLOCK flag; see <a href= +"../functions/open.html"><i>open</i>()</a> in the System Interfaces volume of POSIX.1-2024. If the shell did not reset this flag, +it would immediately terminate because no input data would be available yet and that would be considered the same as +end-of-file.</p> +<p>The options associated with a <i>restricted shell</i> (command name <i>rsh</i> and the <b>-r</b> option) were excluded because +the standard developers considered that the implied level of security could not be achieved and they did not want to raise false +expectations.</p> +<p>On systems that support set-user-ID scripts, a historical trapdoor has been to link a script to the name <b>-i</b>. When it is +called by a sequence such as:</p> +<pre> +<tt>sh - +</tt></pre> +<p>or by:</p> +<pre> +<tt>#! usr/bin/sh - +</tt></pre> +<p>the historical systems have assumed that no option letters follow. Thus, this volume of POSIX.1-2024 allows the single +<hyphen-minus> to mark the end of the options, in addition to the use of the regular <tt>"--"</tt> argument, because it was +considered that the older practice was so pervasive. An alternative approach is taken by the KornShell, where real and effective +user/group IDs must match for an interactive shell; this behavior is specifically allowed by this volume of POSIX.1-2024. +<basefont size="2"></p> +<dl> +<dt><b>Note:</b></dt> +<dd>There are other problems with set-user-ID scripts that the two approaches described here do not resolve.</dd> +</dl> +<basefont size="3"> +<p>The initialization process for the history file can be dependent on the system start-up files, in that they may contain commands +that effectively preempt the user's settings of <i>HISTFILE</i> and <i>HISTSIZE .</i> In some historical shells, the history file +is initialized just after the <i>ENV</i> file has been processed. Therefore, it is implementation-defined whether changes made to +<i>HISTFILE</i> after the history file has been initialized are effective.</p> +<p>The default messages for the various <i>MAIL -related</i> messages are unspecified because they vary across implementations. +Typical messages are:</p> +<pre> +<tt>"you have mail\n" +</tt></pre> +<p>or:</p> +<pre> +<tt>"you have new mail\n" +</tt></pre> +<p>It is important that the descriptions of command line editing refer to the same shell as that in POSIX.1-2024 so that +interactive users can also be application programmers without having to deal with programmatic differences in their two +environments. It is also essential that the utility name <i>sh</i> be specified because this explicit utility name is too firmly +rooted in historical practice of application programs for it to change.</p> +<p>Consideration was given to mandating a diagnostic message when attempting to set <a href= +"../utilities/vi.html"><i>vi</i></a>-mode on terminals that do not support command line editing. However, it is not historical +practice for the shell to be cognizant of all terminal types and thus be able to detect inappropriate terminals in all cases. +Implementations are encouraged to supply diagnostics in this case whenever possible, rather than leaving the user in a state where +editing commands work incorrectly.</p> +<p>In early proposals, the KornShell-derived <i>emacs</i> mode of command line editing was included, even though the <i>emacs</i> +editor itself was not. The community of <i>emacs</i> proponents was adamant that the full <i>emacs</i> editor not be standardized +because they were concerned that an attempt to standardize this very powerful environment would encourage vendors to ship strictly +conforming versions lacking the extensibility required by the community. The author of the original <i>emacs</i> program also +expressed his desire to omit the program. Furthermore, there were a number of historical systems that did not include <i>emacs</i>, +or included it without supporting it, but there were very few that did not include and support <a href= +"../utilities/vi.html"><i>vi</i></a>. The shell <i>emacs</i> command line editing mode was finally omitted because it became +apparent that the KornShell version and the editor being distributed with the GNU system had diverged in some respects. The author +of <i>emacs</i> requested that the POSIX <i>emacs</i> mode either be deleted or have a significant number of unspecified +conditions. Although the KornShell author agreed to consider changes to bring the shell into alignment, the standard developers +decided to defer specification at that time. At the time, it was assumed that convergence on an acceptable definition would occur +for a subsequent draft, but that has not happened, and there appears to be no impetus to do so. In any case, implementations are +free to offer additional command line editing modes based on the exact models of editors their users are most comfortable with.</p> +<p>Early proposals had the following list entry in <a href="#tag_20_110_13_04">vi Line Editing Insert Mode</a> :</p> +<dl compact> +<dd></dd> +<dt><tt>\</tt></dt> +<dd>If followed by the <i>erase</i> or <i>kill</i> character, that character shall be inserted into the input line. Otherwise, the +<backslash> itself shall be inserted into the input line.</dd> +</dl> +<p>However, this is not actually a feature of <i>sh</i> command line editing insert mode, but one of some historical terminal line +drivers. Some conforming implementations continue to do this when the <a href="../utilities/stty.html"><i>stty</i></a> +<b>iexten</b> flag is set.</p> +<p>In interactive shells, SIGTERM is ignored so that <tt>kill 0</tt> does not kill the shell, and SIGINT is caught so that <a href= +"../utilities/wait.html"><i>wait</i></a> is interruptible. If the shell does not ignore SIGTTIN, SIGTTOU, and SIGTSTP signals when +it is interactive and the <b>-m</b> option is not in effect, these signals suspend the shell if it is not a session leader. If it +is a session leader, the signals are discarded if they would stop the process, as required by XSH <a href= +"../functions/V2_chap02.html#tag_16_04_03"><i>2.4.3 Signal Actions</i></a> for orphaned process groups.</p> +<p>Earlier versions of this standard required that input files to the shell be text files except that line lengths were unlimited. +However, that was overly restrictive in relation to the fact that shells can parse a script without a trailing newline, and in +relation to a common practice of concatenating a shell script ending with an <tt>exit</tt> or <tt>exec $command</tt> with a binary +data payload to form a single-file self-extracting archive.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_110_19" id="tag_20_110_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a +<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require +implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_110_20" id="tag_20_110_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19_09_01_04"><i>2.9.1.4 Command Search and Execution</i></a> , <a href= +"../utilities/V3_chap02.html#tag_19"><i>2. Shell Command Language</i></a> , <a href="../utilities/cd.html#"><i>cd</i></a> , +<a href="../utilities/echo.html#"><i>echo</i></a> , <a href="../utilities/V3_chap02.html#tag_19_22"><i>exit</i></a> , <a href= +"../utilities/fc.html#"><i>fc</i></a> , <a href="../utilities/pwd.html#"><i>pwd</i></a> , <a href= +"../utilities/read.html#tag_20_100"><i>read</i></a> , <a href="../utilities/V3_chap02.html#tag_19_26"><i>set</i></a> , <a href= +"../utilities/stty.html#"><i>stty</i></a> , <a href="../utilities/test.html#"><i>test</i></a> , <a href= +"../utilities/V3_chap02.html#tag_19_29"><i>trap</i></a> , <a href="../utilities/umask.html#tag_20_132"><i>umask</i></a> , <a href= +"../utilities/vi.html#"><i>vi</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/dup.html#"><i>dup</i></a> , <a href="../functions/exec.html#tag_17_129"><i>exec</i></a> , <a href= +"../functions/exit.html#tag_17_130"><i>exit</i></a> , <a href="../functions/fork.html#"><i>fork</i></a> , <a href= +"../functions/getrlimit.html#"><i>getrlimit</i></a> , <a href="../functions/open.html#"><i>open</i></a> , <a href= +"../functions/pipe.html#"><i>pipe</i></a> , <a href="../functions/signal.html#"><i>signal</i></a> , <a href= +"../functions/system.html#"><i>system</i></a> , <a href="../functions/umask.html#tag_17_645"><i>umask</i></a> , <a href= +"../functions/wait.html#tag_17_658"><i>wait</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_110_21" id="tag_20_110_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_110_22" id="tag_20_110_22"></a>Issue 5</h4> +<blockquote> +<p>The FUTURE DIRECTIONS section is added.</p> +<p>Text is added to the DESCRIPTION for the Large File Summit proposal.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_110_23" id="tag_20_110_23"></a>Issue 6</h4> +<blockquote> +<p>The Open Group Corrigendum U029/2 is applied, correcting the second SYNOPSIS.</p> +<p>The Open Group Corrigendum U027/3 is applied, correcting a typographical error.</p> +<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p> +<ul> +<li> +<p>The option letters derived from the <a href="../utilities/V3_chap02.html#set"><i>set</i></a> special built-in are also accepted +with a leading <plus-sign> (<tt>'+'</tt>).</p> +</li> +<li> +<p>Large file extensions are added:</p> +<ul> +<li> +<p>Pathname expansion does not fail due to the size of a file.</p> +</li> +<li> +<p>Shell input and output redirections have an implementation-defined offset maximum that is established in the open file +description.</p> +</li> +</ul> +</li> +</ul> +<p>In the ENVIRONMENT VARIABLES section, the text "user's home directory" is updated to "directory referred to by the +<i>HOME</i> environment variable".</p> +<p>Descriptions for the <i>ENV</i> and <i>PWD</i> environment variables are included to align with the IEEE P1003.2b draft +standard.</p> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_110_24" id="tag_20_110_24"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #098 is applied, changing the definition of <i>IFS .</i></p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>Changes to the <a href="../utilities/pwd.html"><i>pwd</i></a> utility and <i>PWD</i> environment variable have been made to +match the changes to the <a href="../functions/getcwd.html"><i>getcwd</i>()</a> function made for Austin Group Interpretation +1003.1-2001 #140.</p> +<p>Minor editorial changes are made to the User Portability Utilities option shading. No normative changes are implied.</p> +<p>Minor changes are made to the install script example in the APPLICATION USAGE section.</p> +<p>POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0137 [152], XCU/TC1-2008/0138 [347], XCU/TC1-2008/0139 [347], +XCU/TC1-2008/0140 [347], XCU/TC1-2008/0141 [299], and XCU/TC1-2008/0142 [347] are applied.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0175 [584], XCU/TC2-2008/0176 [584], XCU/TC2-2008/0177 [718], +XCU/TC2-2008/0178 [884], XCU/TC2-2008/0179 [809], XCU/TC2-2008/0180 [884], and XCU/TC2-2008/0181 [584] are applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_110_25" id="tag_20_110_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 51 is applied, changing the EXIT STATUS section.</p> +<p>Austin Group Defect 251 is applied, encouraging implementations to disallow the creation of filenames containing any bytes that +have the encoded value of a <newline> character.</p> +<p>Austin Group Defect 981 is applied, removing a reference to the <a href="../utilities/V3_chap02.html#set"><i>set</i></a> +<b>-o</b> <i>nolog</i> option from the RATIONALE section.</p> +<p>Austin Group Defect 1006 is applied, changing the description of the <i>ENV</i> environment variable.</p> +<p>Austin Group Defect 1055 is applied, adding a paragraph about the <b>-n</b> option to the APPLICATION USAGE section.</p> +<p>Austin Group Defect 1063 is applied, adding OB shading to the <b>-h</b> option and adding it to the list of options that are +described as part of the <a href="../utilities/V3_chap02.html#set"><i>set</i></a> utility.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1250 is applied, changing the INPUT FILES section.</p> +<p>Austin Group Defect 1266 is applied, clarifying the circumstances under which the shell is considered to be interactive.</p> +<p>Austin Group Defect 1267 is applied, changing the ENVIRONMENT VARIABLES section to remove the UP shading from <i>HOME</i> and +add it to <i>HISTSIZE .</i></p> +<p>Austin Group Defect 1519 is applied, making the behavior explicitly unspecified if the <b>-o</b> or <b>+o</b> option is +specified without an option-argument.</p> +<p>Austin Group Defect 1629 is applied, changing the EXIT STATUS section.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/sed.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/sleep.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/sleep.html b/bdd/sleep.html @@ -0,0 +1,206 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>sleep</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/sh.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/sort.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="sleep" id="sleep"></a> <a name="tag_20_111" id="tag_20_111"></a><!-- sleep --> +<h4 class="mansect"><a name="tag_20_111_01" id="tag_20_111_01"></a>NAME</h4> +<blockquote>sleep — suspend execution for an interval</blockquote> +<h4 class="mansect"><a name="tag_20_111_02" id="tag_20_111_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>sleep</tt> <i>time</i></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_111_03" id="tag_20_111_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>sleep</i> utility shall suspend execution for at least the integral number of seconds specified by the <i>time</i> +operand.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_111_04" id="tag_20_111_04"></a>OPTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_111_05" id="tag_20_111_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>time</i></dt> +<dd>A non-negative decimal integer specifying the number of seconds for which to suspend execution.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_111_06" id="tag_20_111_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_111_07" id="tag_20_111_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_111_08" id="tag_20_111_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>sleep</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_111_09" id="tag_20_111_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>If the <i>sleep</i> utility receives a SIGALRM signal, one of the following actions shall be taken:</p> +<ol> +<li> +<p>Terminate normally with a zero exit status.</p> +</li> +<li> +<p>Effectively ignore the signal.</p> +</li> +<li> +<p>Provide the default behavior for signals described in the ASYNCHRONOUS EVENTS section of <a href= +"../utilities/V3_chap01.html#tag_18_04"><i>1.4 Utility Description Defaults</i></a> . This could include terminating with a +non-zero exit status.</p> +</li> +</ol> +<p>The <i>sleep</i> utility shall take the standard action for all other signals.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_111_10" id="tag_20_111_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_111_11" id="tag_20_111_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_111_12" id="tag_20_111_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_111_13" id="tag_20_111_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_111_14" id="tag_20_111_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>The execution was successfully suspended for at least <i>time</i> seconds, or a SIGALRM signal was received. See the +ASYNCHRONOUS EVENTS section.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_111_15" id="tag_20_111_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_111_16" id="tag_20_111_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_111_17" id="tag_20_111_17"></a>EXAMPLES</h4> +<blockquote> +<p>The <i>sleep</i> utility can be used to execute a command after a certain amount of time, as in:</p> +<pre> +<tt>(sleep 105; </tt><i>command</i><tt>) & +</tt></pre> +<p>or to execute a command every so often, as in:</p> +<pre> +<tt>while true +do + </tt><i>command</i><tt> + sleep 37 +done +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_111_18" id="tag_20_111_18"></a>RATIONALE</h4> +<blockquote> +<p>The exit status is allowed to be zero when <i>sleep</i> is interrupted by the SIGALRM signal because most implementations of +this utility rely on the arrival of that signal to notify them that the requested finishing time has been successfully attained. +Such implementations thus do not distinguish this situation from the successful completion case. Other implementations are allowed +to catch the signal and go back to sleep until the requested time expires or to provide the normal signal termination +procedures.</p> +<p>As with all other utilities that take integral operands and do not specify subranges of allowed values, <i>sleep</i> is required +by this volume of POSIX.1-2024 to deal with <i>time</i> requests of up to 2147483647 seconds. This may mean that some +implementations have to make multiple calls to the delay mechanism of the underlying operating system if its argument range is less +than this.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_111_19" id="tag_20_111_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_111_20" id="tag_20_111_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/wait.html#tag_20_147"><i>wait</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a></p> +<p>XSH <a href="../functions/alarm.html#"><i>alarm</i></a> , <a href="../functions/sleep.html#tag_17_562"><i>sleep</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_111_21" id="tag_20_111_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_111_22" id="tag_20_111_22"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/sh.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/sort.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/sort.html b/bdd/sort.html @@ -0,0 +1,503 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>sort</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/sleep.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/split.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="sort" id="sort"></a> <a name="tag_20_112" id="tag_20_112"></a><!-- sort --> +<h4 class="mansect"><a name="tag_20_112_01" id="tag_20_112_01"></a>NAME</h4> +<blockquote>sort — sort, merge, or sequence check text files</blockquote> +<h4 class="mansect"><a name="tag_20_112_02" id="tag_20_112_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>sort</tt> <b>[</b><tt>-m</tt><b>] [</b><tt>-o</tt> <i>output</i><b>] [</b><tt>-bdfinru</tt><b>] [</b><tt>-t</tt> +<i>char</i><b>] [</b><tt>-k</tt> <i>keydef</i><b>]</b><tt>...</tt> <b>[</b><i>file</i><tt>...</tt><b>]</b> <tt><br> +<br> +sort</tt> <b>[</b><tt>-c|-C</tt><b>] [</b><tt>-bdfinru</tt><b>] [</b><tt>-t</tt> <i>char</i><b>] [</b><tt>-k</tt> <i>keydef</i><b>] +[</b><i>file</i><b>]</b> <tt><br></tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_112_03" id="tag_20_112_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>sort</i> utility shall perform one of the following functions:</p> +<ol> +<li> +<p>Sort lines of all the named files together and write the result to the specified output.</p> +</li> +<li> +<p>Merge lines of all the named (presorted) files together and write the result to the specified output.</p> +</li> +<li> +<p>Check that a single input file is correctly presorted.</p> +</li> +</ol> +<p>Comparisons shall be based on one or more sort keys extracted from each line of input (or, if no sort keys are specified, the +entire line up to, but not including, the terminating <newline>), and shall be performed using the collating sequence of the +current locale. If this collating sequence does not have a total ordering of all characters (see XBD <a href= +"../basedefs/V1_chap07.html#tag_07_03_02"><i>7.3.2 LC_COLLATE</i></a> ), any lines of input that collate equally shall be further +compared byte-by-byte using the collating sequence for the POSIX locale.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_112_04" id="tag_20_112_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>sort</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> , except for Guideline 9, and the <b>-k</b> <i>keydef</i> option should follow the <b>-b</b>, <b>-d</b>, +<b>-f</b>, <b>-i</b>, <b>-n</b>, and <b>-r</b> options. In addition, <tt>'+'</tt> may be recognized as an option delimiter as well +as <tt>'-'</tt>.</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-c</b></dt> +<dd>Check that the single input file is ordered as specified by the arguments and the collating sequence of the current locale. +Output shall not be sent to standard output. The exit code shall indicate whether or not disorder was detected or an error +occurred. If disorder (or, with <b>-u</b>, a duplicate key) is detected, a warning message shall be sent to standard error +indicating where the disorder or duplicate key was found.</dd> +<dt><b>-C</b></dt> +<dd>Same as <b>-c</b>, except that a warning message shall not be sent to standard error if disorder or, with <b>-u</b>, a +duplicate key is detected.</dd> +<dt><b>-m</b></dt> +<dd>Merge only; the input file shall be assumed to be already sorted.</dd> +<dt><b>-o </b><i>output</i></dt> +<dd>Specify the name of an output file to be used instead of the standard output. This file can be the same as one of the input +<i>file</i>s.</dd> +<dt><b>-u</b></dt> +<dd>Unique: suppress all but one in each set of lines having equal keys. If used with the <b>-c</b> option, check that there are no +lines with duplicate keys, in addition to checking that the input file is sorted.</dd> +</dl> +<p>The following options shall override the default ordering rules. When ordering options appear independent of any key field +specifications, the requested field ordering rules shall be applied globally to all sort keys. When attached to a specific key (see +<b>-k</b>), the specified ordering options shall override all global ordering options for that key.</p> +<dl compact> +<dd></dd> +<dt><b>-d</b></dt> +<dd>Specify that only <blank> characters and alphanumeric characters, according to the current setting of <i>LC_CTYPE ,</i> +shall be significant in comparisons. The behavior is undefined for a sort key to which <b>-i</b> or <b>-n</b> also applies.</dd> +<dt><b>-f</b></dt> +<dd>Consider all lowercase characters that have uppercase equivalents, according to the current setting of <i>LC_CTYPE ,</i> to be +the uppercase equivalent for the purposes of comparison.</dd> +<dt><b>-i</b></dt> +<dd>Ignore all characters that are non-printable, according to the current setting of <i>LC_CTYPE .</i> The behavior is undefined +for a sort key for which <b>-n</b> also applies.</dd> +<dt><b>-n</b></dt> +<dd>Restrict the sort key to an initial numeric string, consisting of optional <blank> characters, optional +<hyphen-minus> character, and zero or more digits with an optional radix character and thousands separators (as defined in +the current locale), which shall be sorted by arithmetic value. An empty digit string shall be treated as zero. Leading zeros and +signs on zeros shall not affect ordering.</dd> +<dt><b>-r</b></dt> +<dd>Reverse the sense of comparisons.</dd> +</dl> +<p>The treatment of field separators can be altered using the options:</p> +<dl compact> +<dd></dd> +<dt><b>-b</b></dt> +<dd>Ignore leading <blank> characters when determining the starting and ending positions of a restricted sort key. If the +<b>-b</b> option is specified before the first <b>-k</b> option, it shall be applied to all <b>-k</b> options. Otherwise, the +<b>-b</b> option can be attached independently to each <b>-k</b> <i>field_start</i> or <i>field_end</i> option-argument (see +below).</dd> +<dt><b>-t </b><i>char</i></dt> +<dd>Use <i>char</i> as the field separator character; <i>char</i> shall not be considered to be part of a field (although it can be +included in a sort key). Each occurrence of <i>char</i> shall be significant (for example, <<i>char</i>><<i>char</i>> +delimits an empty field). If <b>-t</b> is not specified, <blank> characters shall be used as default field separators; each +maximal non-empty sequence of <blank> characters that follows a non-<blank> shall be a field separator.</dd> +</dl> +<p>Sort keys can be specified using the options:</p> +<dl compact> +<dd></dd> +<dt><b>-k </b><i>keydef</i></dt> +<dd>The <i>keydef</i> argument is a restricted sort key field definition. The format of this definition is: +<pre> +<i>field_start</i><b>[</b><i>type</i><b>][</b><tt>,</tt><i>field_end</i><b>[</b><i>type</i><b>]]</b><tt> +</tt></pre> +<p>where <i>field_start</i> and <i>field_end</i> define a key field restricted to a portion of the line (see the EXTENDED +DESCRIPTION section), and <i>type</i> is one or more modifiers from the list of characters <tt>'b'</tt>, <tt>'d'</tt>, +<tt>'f'</tt>, <tt>'i'</tt>, <tt>'n'</tt>, <tt>'r'</tt>. The <tt>'b'</tt> modifier shall behave like the <b>-b</b> option, but shall +apply only to the <i>field_start</i> or <i>field_end</i> to which it is attached. The other modifiers shall behave like the +corresponding options, but shall apply only to the key field to which they are attached; they shall have this effect if specified +with <i>field_start</i>, <i>field_end</i>, or both. If any modifier is attached to a <i>field_start</i> or to a <i>field_end</i>, +no option shall apply to either. Implementations shall support at least nine occurrences of the <b>-k</b> option, which shall be +significant in command line order. If no <b>-k</b> option is specified, a default sort key of the entire line shall be used.</p> +<p>When there are multiple key fields, later keys shall be compared only after all earlier keys compare equal. Except when the +<b>-u</b> option is specified, lines that otherwise compare equal shall be ordered as if none of the options <b>-d</b>, <b>-f</b>, +<b>-i</b>, <b>-n</b>, or <b>-k</b> were present (but with <b>-r</b> still in effect, if it was specified) and with all bytes in the +lines significant to the comparison. The order in which lines that still compare equal are written is unspecified.</p> +</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_112_05" id="tag_20_112_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of a file to be sorted, merged, or checked. If no <i>file</i> operands are specified, or if a <i>file</i> operand is +<tt>'-'</tt>, the standard input shall be used. If <i>sort</i> encounters an error when opening or reading a <i>file</i> operand, +it may exit without writing any output to standard output or processing later operands.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_112_06" id="tag_20_112_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be used only if no <i>file</i> operands are specified, or if a <i>file</i> operand is <tt>'-'</tt>. See +the INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_112_07" id="tag_20_112_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files shall be text files, except that the <i>sort</i> utility shall add a <newline> to the end of a file ending +with an incomplete last line.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_112_08" id="tag_20_112_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>sort</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_COLLATE</i></dt> +<dd><br> +Determine the locale for ordering rules.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files) and the behavior of character classification for the <b>-b</b>, +<b>-d</b>, <b>-f</b>, <b>-i</b>, and <b>-n</b> options.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>LC_NUMERIC</i></dt> +<dd><br> +Determine the locale for the definition of the radix character and thousands separator for the <b>-n</b> option.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>TMPDIR</i></dt> +<dd>Provide a pathname that shall override the default directory for temporary files, if any.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_112_09" id="tag_20_112_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_112_10" id="tag_20_112_10"></a>STDOUT</h4> +<blockquote> +<p>Unless the <b>-o</b> or <b>-c</b> options are in effect, the standard output shall contain the sorted input.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_112_11" id="tag_20_112_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used for diagnostic messages. When <b>-c</b> is specified, if disorder is detected (or if <b>-u</b> +is also specified and a duplicate key is detected), a message shall be written to the standard error which identifies the input +line at which disorder (or a duplicate key) was detected. A warning message about correcting an incomplete last line of an input +file may be generated, but need not affect the final exit status.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_112_12" id="tag_20_112_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>If the <b>-o</b> option is in effect, the sorted input shall be written to the file <i>output</i>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_112_13" id="tag_20_112_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>The notation:</p> +<pre> +<tt>-k </tt><i>field_start</i><b>[</b><i>type</i><b>][</b><tt>,</tt><i>field_end</i><b>[</b><i>type</i><b>]]</b><tt> +</tt></pre> +<p>shall define a key field that begins at <i>field_start</i> and ends at <i>field_end</i> inclusive, unless <i>field_start</i> +falls beyond the end of the line or after <i>field_end</i>, in which case the key field is empty. A missing <i>field_end</i> shall +mean the last character of the line.</p> +<p>A field comprises a maximal sequence of non-separating characters and, in the absence of option <b>-t</b>, any preceding field +separator.</p> +<p>The <i>field_start</i> portion of the <i>keydef</i> option-argument shall have the form:</p> +<pre> +<i>field_number</i><b>[</b><tt>.</tt><i>first_character</i><b>]</b><tt> +</tt></pre> +<p>Fields and characters within fields shall be numbered starting with 1. The <i>field_number</i> and <i>first_character</i> +pieces, interpreted as positive decimal integers, shall specify the first character to be used as part of a sort key. If +<i>.first_character</i> is omitted, it shall refer to the first character of the field.</p> +<p>The <i>field_end</i> portion of the <i>keydef</i> option-argument shall have the form:</p> +<pre> +<i>field_number</i><b>[</b><tt>.</tt><i>last_character</i><b>]</b><tt> +</tt></pre> +<p>The <i>field_number</i> shall be as described above for <i>field_start.</i> The <i>last_character</i> piece, interpreted as a +non-negative decimal integer, shall specify the last character to be used as part of the sort key. If <i>last_character</i> +evaluates to zero or <i>.last_character</i> is omitted, it shall refer to the last character of the field specified by +<i>field_number</i>.</p> +<p>If the <b>-b</b> option or <b>b</b> type modifier is in effect, characters within a field shall be counted from the first +non-<blank> in the field. (This shall apply separately to <i>first_character</i> and <i>last_character</i>.)</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_112_14" id="tag_20_112_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>All input files were output successfully, or <b>-c</b> was specified and the input file was correctly sorted.</dd> +<dt> 1</dt> +<dd>Under the <b>-c</b> option, the file was not ordered as specified, or if the <b>-c</b> and <b>-u</b> options were both +specified, two input lines were found with equal keys.</dd> +<dt>>1</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_112_15" id="tag_20_112_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>The default requirements shall apply, except that if <i>sort</i> encounters an error when opening or reading a <i>file</i> +operand, it may exit without writing any output to standard output or processing later operands.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_112_16" id="tag_20_112_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The default value for <b>-t</b>, <blank>, has different properties from, for example, <b>-t</b>"<space>". If a line +contains:</p> +<pre> +<tt><space><space>foo +</tt></pre> +<p>the following treatment would occur with default separation as opposed to specifically selecting a <space>:</p> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Field</b></p> +</th> +<th align="center"> +<p class="tent"><b>Default</b></p> +</th> +<th align="center"> +<p class="tent"><b>-t "<space>"</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">1</p> +</td> +<td align="left"> +<p class="tent"><space><space>foo</p> +</td> +<td align="left"> +<p class="tent"><i>empty</i></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">2</p> +</td> +<td align="left"> +<p class="tent"><i>empty</i></p> +</td> +<td align="left"> +<p class="tent"><i>empty</i></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">3</p> +</td> +<td align="left"> +<p class="tent"><i>empty</i></p> +</td> +<td align="left"> +<p class="tent">foo</p> +</td> +</tr> +</table> +</center> +<p class="tent">The leading field separator itself is included in a field when <b>-t</b> is not used. For example, this command +returns an exit status of zero, meaning the input was already sorted:</p> +<pre> +<tt>sort -c -k 2 <<eof +y<tab>b +x<space>a +eof +</tt></pre> +<p class="tent">(assuming that a <tab> precedes the <space> in the current collating sequence). The field separator is +not included in a field when it is explicitly set via <b>-t</b>. This is historical practice and allows usage such as:</p> +<pre> +<tt>sort -t "|" -k 2n <<eof +Atlanta|425022|Georgia +Birmingham|284413|Alabama +Columbia|100385|South Carolina +eof +</tt></pre> +<p class="tent">where the second field can be correctly sorted numerically without regard to the non-numeric field separator.</p> +<p class="tent">The wording in the OPTIONS section clarifies that the <b>-b</b>, <b>-d</b>, <b>-f</b>, <b>-i</b>, <b>-n</b>, and +<b>-r</b> options have to come before the first sort key specified if they are intended to apply to all specified keys. The way it +is described in this volume of POSIX.1-2024 matches historical practice, not historical documentation. The results are unspecified +if these options are specified after a <b>-k</b> option.</p> +<p class="tent">The <b>-f</b> option might not work as expected in locales where there is not a one-to-one mapping between an +uppercase and a lowercase letter.</p> +<p class="tent">When using <i>sort</i> to process pathnames, it is recommended that LC_ALL, or at least LC_CTYPE and LC_COLLATE, +are set to POSIX or C in the environment, since pathnames can contain byte sequences that do not form valid characters in some +locales, in which case the utility's behavior would be undefined. In the POSIX locale each byte is a valid single-byte character, +and therefore this problem is avoided.</p> +<p class="tent">If the collating sequence of the current locale does not have a total ordering of all characters, since <i>sort</i> +<b>-u</b> suppresses lines with duplicate keys, it suppresses lines that collate equally but are not identical.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_112_17" id="tag_20_112_17"></a>EXAMPLES</h4> +<blockquote> +<ol> +<li class="tent">The following command sorts the contents of <b>infile</b> with the second field as the sort key: +<pre> +<tt>sort -k 2,2 infile +</tt></pre></li> +<li class="tent">The following command sorts, in reverse order, the contents of <b>infile1</b> and <b>infile2</b>, placing the +output in <b>outfile</b> and using the second character of the second field as the sort key (assuming that the first character of +the second field is the field separator): +<pre> +<tt>sort -r -o outfile -k 2.2,2.2 infile1 infile2 +</tt></pre></li> +<li class="tent">The following command sorts the contents of <b>infile1</b> and <b>infile2</b> using the second non-<blank> +of the second field as the sort key: +<pre> +<tt>sort -k 2.2b,2.2b infile1 infile2 +</tt></pre></li> +<li class="tent">The following command prints the System V password file (user database) sorted by the numeric user ID (the +third <colon>-separated field): +<pre> +<tt>sort -t : -k 3,3n /etc/passwd +</tt></pre></li> +<li class="tent">The following command prints the lines of the already sorted file <b>infile</b>, suppressing all but one +occurrence of lines having the same third field: +<pre> +<tt>sort -um -k 3.1,3.0 infile +</tt></pre></li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_112_18" id="tag_20_112_18"></a>RATIONALE</h4> +<blockquote> +<p>Examples in some historical documentation state that options <b>-um</b> with one input file keep the first in each set of lines +with equal keys. This behavior was deemed to be an implementation artifact and was not standardized.</p> +<p class="tent">The <b>-z</b> option was omitted; it is not standard practice on most systems and is inconsistent with using +<i>sort</i> to sort several files individually and then merge them together. The text concerning <b>-z</b> in historical +documentation appeared to require implementations to determine the proper buffer length during the sort phase of operation, but not +during the merge.</p> +<p class="tent">The <b>-y</b> option was omitted because of non-portability. The <b>-M</b> option, present in System V, was omitted +because of non-portability in international usage.</p> +<p class="tent">An undocumented <b>-T</b> option exists in some implementations. It is used to specify a directory for intermediate +files. Implementations are encouraged to support the use of the <i>TMPDIR</i> environment variable instead of adding an option to +support this functionality.</p> +<p class="tent">The <b>-k</b> option was added to satisfy two objections. First, the zero-based counting used by <i>sort</i> is not +consistent with other utility conventions. Second, it did not meet syntax guideline requirements.</p> +<p class="tent">Historical documentation indicates that "setting <b>-n</b> implies <b>-b</b>". The description of <b>-n</b> +already states that optional leading <blank>s are tolerated in doing the comparison. If <b>-b</b> is enabled, rather than +implied, by <b>-n</b>, this has unusual side-effects. When a character offset is used in a column of numbers (for example, to sort +modulo 100), that offset is measured relative to the most significant digit, not to the column. Based upon a recommendation from +the author of the original <i>sort</i> utility, the <b>-b</b> implication has been omitted from this volume of POSIX.1-2024, and an +application wishing to achieve the previously mentioned side-effects has to code the <b>-b</b> flag explicitly.</p> +<p class="tent">Earlier versions of this standard allowed the <b>-o</b> option to appear after operands. Historical practice +allowed all options to be interspersed with operands. This version of the standard allows implementations to accept options after +operands but conforming applications should not use this form.</p> +<p class="tent">Earlier versions of this standard also allowed the <b>-</b><i>number</i> and <b>+</b><i>number</i> options. These +options are no longer specified by POSIX.1-2024 but may be present in some implementations.</p> +<p class="tent">Historical implementations produced a message on standard error when <b>-c</b> was specified and disorder was +detected, and when <b>-c</b> and <b>-u</b> were specified and a duplicate key was detected. An earlier version of this standard +contained wording that did not make it clear that this message was allowed and some implementations removed this message to be sure +that they conformed to the standard's requirements. Confronted with this difference in behavior, interactive users that wanted to +be sure that they got visual feedback instead of just exit code 1 could have used a command like:</p> +<pre> +<tt>sort -c file || echo disorder +</tt></pre> +<p class="tent">whether or not the <i>sort</i> utility provided a message in this case. But, it was not easy for a user to find +where the disorder or duplicate key occurred on implementations that do not produce a message, especially when some parts of the +input line were not part of the key and when one or more of the <b>-b</b>, <b>-d</b>, <b>-f</b>, <b>-i</b>, <b>-n</b>, or <b>-</b>r +options or <i>keydef</i> type modifiers were in use. POSIX.1-2024 requires a message to be produced in this case. POSIX.1-2024 also +contains the <b>-C</b> option giving users the ability to choose either behavior.</p> +<p class="tent">When a disorder or duplicate is found when the <b>-c</b> option is specified, some implementations print a message +containing the first line that is out of order or contains a duplicate key; others print a message specifying the line number of +the offending line. This standard allows either type of message.</p> +<p class="tent">The required further byte-by-byte comparison of lines that collate equally may have an impact on efficiency, but +this can be mitigated by only performing the additional comparison if the current locale's collating sequence does not have a total +ordering of all characters (if the implementation provides a way to query this) or by only performing the additional comparison if +the locale name associated with the <i>LC_COLLATE</i> category has an <tt>'@'</tt> modifier in the name (since +implementation-supplied locales without an <tt>'@'</tt> modifier have a total ordering of all characters — see XBD <a href= +"../basedefs/V1_chap07.html#tag_07_03_02"><i>7.3.2 LC_COLLATE</i></a> — and <a href= +"../utilities/localedef.html"><i>localedef</i></a> users are warned to follow the same convention). Note that if the implementation +provides a <i>stable sort</i> option as an extension (usually <b>-s</b>), the additional comparison should not be performed when +this option has been specified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_112_19" id="tag_20_112_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a +<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require +implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_112_20" id="tag_20_112_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/comm.html#"><i>comm</i></a> , <a href="../utilities/join.html#"><i>join</i></a> , <a href= +"../utilities/uniq.html#"><i>uniq</i></a></p> +<p class="tent">XBD <a href="../basedefs/V1_chap07.html#tag_07_03_02"><i>7.3.2 LC_COLLATE</i></a> , <a href= +"../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 +Utility Syntax Guidelines</i></a></p> +<p class="tent">XSH <a href="../functions/toupper.html#"><i>toupper</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_112_21" id="tag_20_112_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_112_22" id="tag_20_112_22"></a>Issue 6</h4> +<blockquote> +<p>IEEE PASC Interpretation 1003.2 #174 is applied, updating the DESCRIPTION of comparisons.</p> +<p class="tent">IEEE PASC Interpretation 1003.2 #168 is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_112_23" id="tag_20_112_23"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #027 is applied, clarifying that Guideline 9 of the Utility Syntax Guidelines does not +apply and noting that <tt>'+'</tt> may be recognized as an option delimiter.</p> +<p class="tent">Austin Group Interpretation 1003.1-2001 #120 is applied, clarifying the use of the <b>-c</b> option and introducing +the <b>-C</b> option.</p> +<p class="tent">XCU-ERN-81 is applied, modifying the description of the <b>-i</b> option.</p> +<p class="tent">SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p class="tent">POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0182 [963], XCU/TC2-2008/0183 [584], XCU/TC2-2008/0184 [510], +XCU/TC2-2008/0185 [962], XCU/TC2-2008/0186 [663], and XCU/TC2-2008/0187 [963] are applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_112_24" id="tag_20_112_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to disallow the creation of filenames containing any bytes that +have the encoded value of a <newline> character.</p> +<p class="tent">Austin Group Defect 862 is applied, adding <i>TMPDIR</i> to the ENVIRONMENT VARIABLES section.</p> +<p class="tent">Austin Group Defect 1070 is applied, requiring that any lines of input that collate equally when comparing them as +whole lines are further compared byte-by-byte using the collating sequence for the POSIX locale.</p> +<p class="tent">Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/sleep.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/split.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/split.html b/bdd/split.html @@ -0,0 +1,270 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>split</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/sort.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/strings.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="split" id="split"></a> <a name="tag_20_113" id="tag_20_113"></a><!-- split --> +<h4 class="mansect"><a name="tag_20_113_01" id="tag_20_113_01"></a>NAME</h4> +<blockquote>split — split a file into pieces</blockquote> +<h4 class="mansect"><a name="tag_20_113_02" id="tag_20_113_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>split</tt> <b>[</b><tt>-l</tt> <i>line_count</i><b>] [</b><tt>-a</tt> <i>suffix_length</i><b>] [</b><i>file</i> +<b>[</b><i>name</i><b>]]</b> <tt><br> +<br> +split -b</tt> <i>n</i><b>[</b><tt>k|m</tt><b>] [</b><tt>-a</tt> <i>suffix_length</i><b>] [</b><i>file</i> +<b>[</b><i>name</i><b>]]</b> <tt><br></tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_113_03" id="tag_20_113_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>split</i> utility shall read an input file and write zero or more output files. The default size of each output file +shall be 1000 lines. The size of the output files can be modified by specification of the <b>-b</b> or <b>-l</b> options. Each +output file shall be created with a unique suffix. The suffix shall consist of exactly <i>suffix_length</i> lowercase letters from +the POSIX locale. The letters of the suffix shall be used as if they were a base-26 digit system, with the first suffix to be +created consisting of all <tt>'a'</tt> characters, the second with a <tt>'b'</tt> replacing the last <tt>'a'</tt>, and so on, until +a name of all <tt>'z'</tt> characters is created. By default, the names of the output files shall be <tt>'x'</tt>, followed by a +two-character suffix from the character set as described above, starting with <tt>"aa"</tt>, <tt>"ab"</tt>, <tt>"ac"</tt>, and so +on, and continuing until the suffix <tt>"zz"</tt>, for a maximum of 676 files.</p> +<p>If the number of files required exceeds the maximum allowed by the suffix length provided, such that the last allowable file +would be larger than the requested size, the <i>split</i> utility shall fail after creating the last file with a valid suffix; +<i>split</i> shall not delete the files it created with valid suffixes. If the file limit is not exceeded, the last file created +shall contain the remainder of the input file, and may be smaller than the requested size. If the input is an empty file, no output +file shall be created and this shall not be considered to be an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_113_04" id="tag_20_113_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>split</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-a </b><i>suffix_length</i></dt> +<dd><br> +Use <i>suffix_length</i> letters to form the suffix portion of the filenames of the split file. If <b>-a</b> is not specified, the +default suffix length shall be two. If the sum of the <i>name</i> operand and the <i>suffix_length</i> option-argument would create +a filename exceeding {NAME_MAX} bytes, an error shall result; <i>split</i> shall exit with a diagnostic message and no files shall +be created.</dd> +<dt><b>-b </b><i>n</i></dt> +<dd>Split a file into pieces <i>n</i> bytes in size.</dd> +<dt><b>-b </b><i>n</i><b>k</b></dt> +<dd>Split a file into pieces <i>n</i>*1024 bytes in size.</dd> +<dt><b>-b </b><i>n</i><b>m</b></dt> +<dd>Split a file into pieces <i>n</i>*1048576 bytes in size.</dd> +<dt><b>-l </b><i>line_count</i></dt> +<dd>Specify the number of lines in each resulting file piece. The <i>line_count</i> argument is an unsigned decimal integer. The +default is 1000. If the input does not end with a <newline>, the partial line shall be included in the last output file.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_113_05" id="tag_20_113_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>The pathname of the ordinary file to be split. If no input file is given or <i>file</i> is <tt>'-'</tt>, the standard input +shall be used.</dd> +<dt><i>name</i></dt> +<dd>The prefix to be used for each of the files resulting from the split operation. If no <i>name</i> argument is given, +<tt>'x'</tt> shall be used as the prefix of the output files. The combined length of the basename of <i>prefix</i> and +<i>suffix_length</i> cannot exceed {NAME_MAX} bytes. See the OPTIONS section.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_113_06" id="tag_20_113_06"></a>STDIN</h4> +<blockquote> +<p>See the INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_113_07" id="tag_20_113_07"></a>INPUT FILES</h4> +<blockquote> +<p>Any file can be used as input.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_113_08" id="tag_20_113_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>split</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_113_09" id="tag_20_113_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_113_10" id="tag_20_113_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_113_11" id="tag_20_113_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_113_12" id="tag_20_113_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>The output files contain portions of the original input file; otherwise, unchanged.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_113_13" id="tag_20_113_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_113_14" id="tag_20_113_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_113_15" id="tag_20_113_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_113_16" id="tag_20_113_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_113_17" id="tag_20_113_17"></a>EXAMPLES</h4> +<blockquote> +<p>In the following examples <b>foo</b> is a text file that contains 5000 lines.</p> +<ol> +<li> +<p>Create five files, <b>xaa</b>, <b>xab</b>, <b>xac</b>, <b>xad</b>, and <b>xae</b>:</p> +<pre> +<tt>split foo +</tt></pre></li> +<li> +<p>Create five files, but the suffixed portion of the created files consists of three letters, <b>xaaa</b>, <b>xaab</b>, +<b>xaac</b>, <b>xaad</b>, and <b>xaae</b>:</p> +<pre> +<tt>split -a 3 foo +</tt></pre></li> +<li> +<p>Create three files with four-letter suffixes and a supplied prefix, <b>bar_aaaa</b>, <b>bar_aaab</b>, and <b>bar_aaac</b>:</p> +<pre> +<tt>split -a 4 -l 2000 foo bar_ +</tt></pre></li> +<li> +<p>Create as many files as are necessary to contain at most 20*1024 bytes, each with the default prefix of <b>x</b> and a +five-letter suffix:</p> +<pre> +<tt>split -a 5 -b 20k foo +</tt></pre></li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_113_18" id="tag_20_113_18"></a>RATIONALE</h4> +<blockquote> +<p>The <b>-b</b> option was added to provide a mechanism for splitting files other than by lines. While most uses of the <b>-b</b> +option are for transmitting files over networks, some believed it would have additional uses.</p> +<p>The <b>-a</b> option was added to overcome the limitation of being able to create only 676 files.</p> +<p>Consideration was given to deleting this utility, using the rationale that the functionality provided by this utility is +available via the <a href="../utilities/csplit.html"><i>csplit</i></a> utility (see <a href= +"../utilities/csplit.html#"><i>csplit</i></a> ). Upon reconsideration of the purpose of the User Portability Utilities option, it +was decided to retain both this utility and the <a href="../utilities/csplit.html"><i>csplit</i></a> utility because users use both +utilities and have historical expectations of their behavior. Furthermore, the splitting on byte boundaries in <i>split</i> cannot +be duplicated with the historical <a href="../utilities/csplit.html"><i>csplit</i></a>.</p> +<p>The text "<a href="../utilities/split.html"><i>split</i></a> shall not delete the files it created with valid suffixes" would +normally be assumed, but since the related utility, <a href="../utilities/csplit.html"><i>csplit</i></a>, does delete files under +some circumstances, the historical behavior of <i>split</i> is made explicit to avoid misinterpretation.</p> +<p>Earlier versions of this standard allowed a <b>-</b><i>line_count</i> option. This form is no longer specified by POSIX.1-2024 +but may be present in some implementations.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_113_19" id="tag_20_113_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a +<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require +implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_113_20" id="tag_20_113_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/csplit.html#"><i>csplit</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_113_21" id="tag_20_113_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_113_22" id="tag_20_113_22"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +<p>The APPLICATION USAGE section is added.</p> +<p>The obsolescent SYNOPSIS is removed.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_113_23" id="tag_20_113_23"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #027 is applied.</p> +<p>The <i>split</i> utility is moved from the User Portability Utilities option to the Base. User Portability Utilities is now an +option for interactive utilities.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0188 [731] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_113_24" id="tag_20_113_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to disallow the creation of filenames containing any bytes that +have the encoded value of a <newline> character.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/sort.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/strings.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/strings.html b/bdd/strings.html @@ -0,0 +1,244 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>strings</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/split.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/strip.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="strings" id="strings"></a> <a name="tag_20_114" id="tag_20_114"></a><!-- strings --> +<h4 class="mansect"><a name="tag_20_114_01" id="tag_20_114_01"></a>NAME</h4> +<blockquote>strings — find printable strings in files</blockquote> +<h4 class="mansect"><a name="tag_20_114_02" id="tag_20_114_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>strings</tt> <b>[</b><tt>-a</tt><b>] [</b><tt>-t</tt> <i>format</i><b>] [</b><tt>-n</tt> <i>number</i><b>] +[</b><i>file</i><tt>...</tt><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_114_03" id="tag_20_114_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>strings</i> utility shall look for printable strings in regular files and shall write those strings to standard output. A +printable string is any sequence of four (by default) or more printable characters terminated by a <newline> or NUL +character. Additional implementation-defined strings may be written; see <a href= +"../utilities/localedef.html"><i>localedef</i></a>.</p> +<p>If any argument is <tt>'-'</tt>, the results are unspecified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_114_04" id="tag_20_114_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>strings</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> , except for the unspecified usage of <tt>'-'</tt>.</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-a</b></dt> +<dd>Scan files in their entirety. If <b>-a</b> is not specified, it is implementation-defined what portion of each file is scanned +for strings.</dd> +<dt><b>-n </b><i>number</i></dt> +<dd>Specify the minimum string length, where the <i>number</i> argument is a positive decimal integer. The default shall be 4.</dd> +<dt><b>-t </b><i>format</i></dt> +<dd>Write each string preceded by its byte offset from the start of the file. The format shall be dependent on the single character +used as the <i>format</i> option-argument: +<dl compact> +<dd></dd> +<dt><tt>d</tt></dt> +<dd>The offset shall be written in decimal.</dd> +<dt><tt>o</tt></dt> +<dd>The offset shall be written in octal.</dd> +<dt><tt>x</tt></dt> +<dd>The offset shall be written in hexadecimal.</dd> +</dl> +</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_114_05" id="tag_20_114_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of a regular file to be used as input. If no <i>file</i> operand is specified, the <i>strings</i> utility shall read +from the standard input.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_114_06" id="tag_20_114_06"></a>STDIN</h4> +<blockquote> +<p>See the INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_114_07" id="tag_20_114_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files named by the utility arguments or the standard input shall be regular files of any format.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_114_08" id="tag_20_114_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>strings</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files) and to identify printable strings.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_114_09" id="tag_20_114_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_114_10" id="tag_20_114_10"></a>STDOUT</h4> +<blockquote> +<p>Strings found shall be written to the standard output, one per line.</p> +<p>When the <b>-t</b> option is not specified, the format of the output shall be:</p> +<pre> +<tt>"%s", <</tt><i>string</i><tt>> +</tt></pre> +<p>With the <b>-t o</b> option, the format of the output shall be:</p> +<pre> +<tt>"%o %s", <</tt><i>byte offset</i><tt>>, <</tt><i>string</i><tt>> +</tt></pre> +<p>With the <b>-t x</b> option, the format of the output shall be:</p> +<pre> +<tt>"%x %s", <</tt><i>byte offset</i><tt>>, <</tt><i>string</i><tt>> +</tt></pre> +<p>With the <b>-t d</b> option, the format of the output shall be:</p> +<pre> +<tt>"%d %s", <</tt><i>byte offset</i><tt>>, <</tt><i>string</i><tt>> +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_114_11" id="tag_20_114_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_114_12" id="tag_20_114_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_114_13" id="tag_20_114_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_114_14" id="tag_20_114_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_114_15" id="tag_20_114_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_114_16" id="tag_20_114_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>By default the data area (as opposed to the text, "bss", or header areas) of a binary executable file is scanned. +Implementations document which areas are scanned.</p> +<p>Some historical implementations do not require NUL or <newline> terminators for strings to permit those languages that do +not use NUL as a string terminator to have their strings written.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_114_17" id="tag_20_114_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_114_18" id="tag_20_114_18"></a>RATIONALE</h4> +<blockquote> +<p>Apart from rationalizing the option syntax and slight difficulties with object and executable binary files, <i>strings</i> is +specified to match historical practice closely. The <b>-a</b> and <b>-n</b> options were introduced to replace the non-conforming +<b>-</b> and <b>-</b><i>number</i> options. These options are no longer specified by POSIX.1-2024 but may be present in some +implementations.</p> +<p>The <b>-o</b> option historically means different things on different implementations. Some use it to mean "<i>offset</i> in +decimal", while others use it as "<i>offset</i> in octal". Instead of trying to decide which way would be least objectionable, +the <b>-t</b> option was added. It was originally named <b>-O</b> to mean "offset", but was changed to <b>-t</b> to be consistent +with <a href="../utilities/od.html"><i>od</i></a>.</p> +<p>The ISO C standard function <a href="../functions/isprint.html"><i>isprint</i>()</a> is restricted to a domain of +<b>unsigned char</b>. This volume of POSIX.1-2024 requires implementations to write strings as defined by the current locale.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_114_19" id="tag_20_114_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_114_20" id="tag_20_114_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/localedef.html#"><i>localedef</i></a> , <a href="../utilities/nm.html#"><i>nm</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_114_21" id="tag_20_114_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_114_22" id="tag_20_114_22"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +<p>The obsolescent SYNOPSIS is removed.</p> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_114_23" id="tag_20_114_23"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #027 is applied, clarifying the behavior if the first argument is <tt>'-'</tt>.</p> +<p>The <i>strings</i> utility is moved from the User Portability Utilities option to the Base. User Portability Utilities is now an +option for interactive utilities.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_114_24" id="tag_20_114_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1599 is applied, making the behavior unspecified when any argument is <tt>'-'</tt>.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/split.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/strip.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/strip.html b/bdd/strip.html @@ -0,0 +1,200 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>strip</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/strings.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/stty.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="strip" id="strip"></a> <a name="tag_20_115" id="tag_20_115"></a><!-- strip --> +<h4 class="mansect"><a name="tag_20_115_01" id="tag_20_115_01"></a>NAME</h4> +<blockquote>strip — remove unnecessary information from strippable files (<b>DEVELOPMENT</b>)</blockquote> +<h4 class="mansect"><a name="tag_20_115_02" id="tag_20_115_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('SD')">SD</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> strip</tt> <i>file</i><tt>... <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></tt></code></div> +</blockquote> +<h4 class="mansect"><a name="tag_20_115_03" id="tag_20_115_03"></a>DESCRIPTION</h4> +<blockquote> +<p>A strippable file is defined as a relocatable, object, or executable file. <sup>[<a href= +"javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> On +XSI-conformant systems, a strippable file can also be an archive of object or relocatable files. <img src="../images/opt-end.gif" +alt="[Option End]" border="0"></p> +<p>The <i>strip</i> utility shall remove from strippable files named by the <i>file</i> operands any information the implementor +deems unnecessary for execution of those files. The nature of that information is unspecified. The effect of <i>strip</i> on object +and executable files shall be similar to the use of the <b>-s</b> option to <a href="../utilities/c17.html"><i>c17</i></a>. +<sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> + The effect of <i>strip</i> on an archive of object files shall be similar to the use of the <b>-s</b> option to <a href= +"../utilities/c17.html"><i>c17</i></a> for each object file in the archive. <img src="../images/opt-end.gif" alt="[Option End]" +border="0"></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_115_04" id="tag_20_115_04"></a>OPTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_115_05" id="tag_20_115_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname referring to a strippable file.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_115_06" id="tag_20_115_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_115_07" id="tag_20_115_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files shall be in the form of strippable files successfully produced by any compiler defined by this volume of +POSIX.1-2024 <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" +border="0"> or produced by creating or updating an archive of such files using the <a href= +"../utilities/ar.html"><i>ar</i></a> utility. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_115_08" id="tag_20_115_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>strip</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_115_09" id="tag_20_115_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_115_10" id="tag_20_115_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_115_11" id="tag_20_115_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_115_12" id="tag_20_115_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>The <i>strip</i> utility shall produce strippable files of unspecified format.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_115_13" id="tag_20_115_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_115_14" id="tag_20_115_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_115_15" id="tag_20_115_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_115_16" id="tag_20_115_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_115_17" id="tag_20_115_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_115_18" id="tag_20_115_18"></a>RATIONALE</h4> +<blockquote> +<p>Historically, this utility has been used to remove the symbol table from a strippable file. It was included since it is known +that the amount of symbolic information can amount to several megabytes; the ability to remove it in a portable manner was deemed +important, especially for smaller systems.</p> +<p>The behavior of <i>strip</i> on object and executable files is said to be the same as the <b>-s</b> option to a compiler. While +the end result is essentially the same, it is not required to be identical.</p> +<p>XSI-conformant systems support use of <i>strip</i> on archive files containing object files or relocatable files.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_115_19" id="tag_20_115_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_115_20" id="tag_20_115_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/ar.html#"><i>ar</i></a> , <a href="../utilities/c17.html#"><i>c17</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_115_21" id="tag_20_115_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_115_22" id="tag_20_115_22"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the Software Development Utilities option.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_115_23" id="tag_20_115_23"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #103 is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_115_24" id="tag_20_115_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1330 is applied, removing obsolescent interfaces.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/strings.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/stty.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/stty.html b/bdd/stty.html @@ -0,0 +1,938 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>stty</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/strip.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/tabs.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="stty" id="stty"></a> <a name="tag_20_116" id="tag_20_116"></a><!-- stty --> +<h4 class="mansect"><a name="tag_20_116_01" id="tag_20_116_01"></a>NAME</h4> +<blockquote>stty — set the options for a terminal</blockquote> +<h4 class="mansect"><a name="tag_20_116_02" id="tag_20_116_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>stty</tt> <b>[</b><tt>-a|-g</tt><b>]</b> <tt><br> +<br> +stty</tt> <i>operand</i><tt>...<br></tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_116_03" id="tag_20_116_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>stty</i> utility shall set or report on terminal I/O characteristics for the device that is its standard input. Without +options or operands specified, it shall report the settings of certain characteristics, usually those that differ from +implementation-defined defaults. Otherwise, it shall modify the terminal state according to the specified operands. Detailed +information about the modes listed in the first five groups below are described in XBD <a href= +"../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> . Operands in the Combination Modes group (see +<a href="#tag_20_116_05_06">Combination Modes</a> ) are implemented using operands in the previous groups. Some combinations of +operands are mutually-exclusive on some terminal types; the results of using such combinations are unspecified.</p> +<p>Typical implementations of this utility require a communications line configured to use the <b>termios</b> interface defined in +the System Interfaces volume of POSIX.1-2024. On systems where none of these lines are available, and on lines not currently +configured to support the <b>termios</b> interface, some of the operands need not affect terminal characteristics.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_116_04" id="tag_20_116_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>stty</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-a</b></dt> +<dd>Write to standard output all the current settings for the terminal.</dd> +<dt><b>-g</b></dt> +<dd>Write to standard output all the current settings, optionally excluding the terminal window size, in an unspecified form that, +when stripped of trailing <newline> characters, and used as the one and only argument to another invocation of the +<i>stty</i> utility on the same system, attempts to apply those settings to the terminal. The form used shall not contain any +sequence that would form an Informational Query, and shall consist of one line of text consisting of only printable characters from +the portable character set, excluding white-space characters (other than the terminating <newline>) and these characters that +could be altered by pathname expansion performed by the shell: <tt>'*'</tt>, <tt>'?'</tt>, and <tt>'['</tt>.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_116_05" id="tag_20_116_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported.</p> +<h5><a name="tag_20_116_05_01" id="tag_20_116_05_01"></a>Control Modes</h5> +<dl compact> +<dd></dd> +<dt><b>parenb </b>(<b>-parenb</b>)</dt> +<dd>Enable (disable) parity generation and detection. This shall have the effect of setting (not setting) PARENB in the +<b>termios</b> <i>c_cflag</i> field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal +Interface</i></a> .</dd> +<dt><b>parodd </b>(<b>-parodd</b>)</dt> +<dd><br> +Select odd (even) parity. This shall have the effect of setting (not setting) PARODD in the <b>termios</b> <i>c_cflag</i> field, as +defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> .</dd> +<dt><b>cs5 cs6 cs7 cs8</b></dt> +<dd>Select character size, if possible. This shall have the effect of setting CS5, CS6, CS7, and CS8, respectively, in the +<b>termios</b> <i>c_cflag</i> field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal +Interface</i></a> .</dd> +<dt><i>number</i></dt> +<dd>Set terminal baud rate to the number given, if possible. If the baud rate is set to zero, the modem control lines shall no +longer be asserted. This shall have the effect of setting the input and output <b>termios</b> baud rate values as defined in XBD +<a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> .</dd> +<dt><b>ispeed </b><i>number</i></dt> +<dd>Set terminal input baud rate to the number given, if possible. If the input baud rate is set to zero, the input baud rate shall +be specified by the value of the output baud rate. This shall have the effect of setting the input <b>termios</b> baud rate value +as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> .</dd> +<dt><b>ospeed </b><i>number</i></dt> +<dd>Set terminal output baud rate to the number given, if possible. If the output baud rate is set to zero, the modem control lines +shall no longer be asserted. This shall have the effect of setting the output <b>termios</b> baud rate value as defined in XBD +<a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> .</dd> +<dt><b>hupcl </b>(<b>-hupcl</b>)</dt> +<dd>Stop asserting modem control lines (do not stop asserting modem control lines) on last close. This shall have the effect of +setting (not setting) HUPCL in the <b>termios</b> <i>c_cflag</i> field, as defined in XBD <a href= +"../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> .</dd> +<dt><b>hup </b>(<b>-hup</b>)</dt> +<dd>Equivalent to <b>hupcl</b>(<b>-hupcl</b>).</dd> +<dt><b>cstopb </b>(<b>-cstopb</b>)</dt> +<dd>Use two (one) stop bits per character. This shall have the effect of setting (not setting) CSTOPB in the <b>termios</b> +<i>c_cflag</i> field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> +.</dd> +<dt><b>cread </b>(<b>-cread</b>)</dt> +<dd>Enable (disable) the receiver. This shall have the effect of setting (not setting) CREAD in the <b>termios</b> <i>c_cflag</i> +field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> .</dd> +<dt><b>clocal </b>(<b>-clocal</b>)</dt> +<dd>Assume a line without (with) modem control. This shall have the effect of setting (not setting) CLOCAL in the <b>termios</b> +<i>c_cflag</i> field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> +.</dd> +</dl> +<p>It is unspecified whether <i>stty</i> shall report an error if an attempt to set a Control Mode fails.</p> +<h5><a name="tag_20_116_05_02" id="tag_20_116_05_02"></a>Input Modes</h5> +<dl compact> +<dd></dd> +<dt><b>ignbrk </b>(<b>-ignbrk</b>)</dt> +<dd>Ignore (do not ignore) break on input. This shall have the effect of setting (not setting) IGNBRK in the <b>termios</b> +<i>c_iflag</i> field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> +.</dd> +<dt><b>brkint </b>(<b>-brkint</b>)</dt> +<dd>Signal (do not signal) INTR on break. This shall have the effect of setting (not setting) BRKINT in the <b>termios</b> +<i>c_iflag</i> field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> +.</dd> +<dt><b>ignpar </b>(<b>-ignpar</b>)</dt> +<dd>Ignore (do not ignore) bytes with parity errors. This shall have the effect of setting (not setting) IGNPAR in the +<b>termios</b> <i>c_iflag</i> field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal +Interface</i></a> .</dd> +<dt><b>parmrk </b>(<b>-parmrk</b>)</dt> +<dd><br> +Mark (do not mark) parity errors. This shall have the effect of setting (not setting) PARMRK in the <b>termios</b> <i>c_iflag</i> +field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> .</dd> +<dt><b>inpck </b>(<b>-inpck</b>)</dt> +<dd>Enable (disable) input parity checking. This shall have the effect of setting (not setting) INPCK in the <b>termios</b> +<i>c_iflag</i> field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> +.</dd> +<dt><b>istrip </b>(<b>-istrip</b>)</dt> +<dd>Strip (do not strip) input characters to seven bits. This shall have the effect of setting (not setting) ISTRIP in the +<b>termios</b> <i>c_iflag</i> field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal +Interface</i></a> .</dd> +<dt><b>inlcr </b>(<b>-inlcr</b>)</dt> +<dd>Map (do not map) NL to CR on input. This shall have the effect of setting (not setting) INLCR in the <b>termios</b> +<i>c_iflag</i> field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> +.</dd> +<dt><b>igncr (-igncr)</b></dt> +<dd>Ignore (do not ignore) CR on input. This shall have the effect of setting (not setting) IGNCR in the <b>termios</b> +<i>c_iflag</i> field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> +.</dd> +<dt><b>icrnl </b>(<b>-icrnl</b>)</dt> +<dd>Map (do not map) CR to NL on input. This shall have the effect of setting (not setting) ICRNL in the <b>termios</b> +<i>c_iflag</i> field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> +.</dd> +<dt><b>ixon </b>(<b>-ixon</b>)</dt> +<dd>Enable (disable) START/STOP output control. Output from the system is stopped when the system receives STOP and started when +the system receives START. This shall have the effect of setting (not setting) IXON in the <b>termios</b> <i>c_iflag</i> field, as +defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> .</dd> +<dt><b>ixany </b>(<b>-ixany</b>)</dt> +<dd>Allow any character to restart output. This shall have the effect of setting (not setting) IXANY in the <b>termios</b> +<i>c_iflag</i> field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> +.</dd> +<dt><b>ixoff </b>(<b>-ixoff</b>)</dt> +<dd>Request that the system send (not send) STOP characters when the input queue is nearly full and START characters to resume data +transmission. This shall have the effect of setting (not setting) IXOFF in the <b>termios</b> <i>c_iflag</i> field, as defined in +XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> .</dd> +</dl> +<h5><a name="tag_20_116_05_03" id="tag_20_116_05_03"></a>Output Modes</h5> +<dl compact> +<dd></dd> +<dt><b>opost </b>(<b>-opost</b>)</dt> +<dd>Post-process output (do not post-process output; ignore all other output modes). This shall have the effect of setting (not +setting) OPOST in the <b>termios</b> <i>c_oflag</i> field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. +General Terminal Interface</i></a> .</dd> +<dt><b>onlcr </b>(<b>-onlcr</b>)</dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Map (do not map) NL to CR-NL on output. This shall have the effect of setting (not setting) ONLCR in the <b>termios</b> +<i>c_oflag</i> field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> . +<img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>ocrnl </b>(<b>-ocrnl</b>)</dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Map (do not map) CR to NL on output. This shall have the effect of setting (not setting) OCRNL in the <b>termios</b> <i>c_oflag</i> +field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> . <img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>onocr </b>(<b>-onocr</b>)</dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Do not (do) output CR at column zero. This shall have the effect of setting (not setting) ONOCR in the <b>termios</b> +<i>c_oflag</i> field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> . +<img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>onlret </b>(<b>-onlret</b>)</dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +The terminal newline key performs (does not perform) the CR function. This shall have the effect of setting (not setting) ONLRET in +the <b>termios</b> <i>c_oflag</i> field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal +Interface</i></a> . <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>ofill </b>(<b>-ofill</b>)</dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Use fill characters (use timing) for delays. This shall have the effect of setting (not setting) OFILL in the <b>termios</b> +<i>c_oflag</i> field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> . +<img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>ofdel </b>(<b>-ofdel</b>)</dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Fill characters are DELs (NULs). This shall have the effect of setting (not setting) OFDEL in the <b>termios</b> <i>c_oflag</i> +field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> . <img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>cr0 cr1 cr2 cr3</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Select the style of delay for CRs. This shall have the effect of setting CRDLY to CR0, CR1, CR2, or CR3, respectively, in the +<b>termios</b> <i>c_oflag</i> field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal +Interface</i></a> . <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>nl0 nl1</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Select the style of delay for NL. This shall have the effect of setting NLDLY to NL0 or NL1, respectively, in the <b>termios</b> +<i>c_oflag</i> field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> . +<img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>tab0 tab1 tab2 tab3</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border= +"0"><br> +Select the style of delay for horizontal tabs. This shall have the effect of setting TABDLY to TAB0, TAB1, TAB2, or TAB3, +respectively, in the <b>termios</b> <i>c_oflag</i> field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. +General Terminal Interface</i></a> . Note that TAB3 has the effect of expanding <tab> characters to <space> characters. +<img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>tabs </b>(<b>-tabs</b>)</dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Synonym for <b>tab0</b> (<b>tab3</b>). <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>bs0 bs1</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Select the style of delay for <backspace> characters. This shall have the effect of setting BSDLY to BS0 or BS1, +respectively, in the <b>termios</b> <i>c_oflag</i> field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. +General Terminal Interface</i></a> . <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>ff0 ff1</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Select the style of delay for <form-feed> characters. This shall have the effect of setting FFDLY to FF0 or FF1, +respectively, in the <b>termios</b> <i>c_oflag</i> field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. +General Terminal Interface</i></a> . <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>vt0 vt1</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Select the style of delay for <vertical-tab> characters. This shall have the effect of setting VTDLY to VT0 or VT1, +respectively, in the <b>termios</b> <i>c_oflag</i> field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. +General Terminal Interface</i></a> . <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +</dl> +<h5><a name="tag_20_116_05_04" id="tag_20_116_05_04"></a>Local Modes</h5> +<dl compact> +<dd></dd> +<dt><b>isig </b>(<b>-isig</b>)</dt> +<dd>Enable (disable) the checking of characters against the special control characters INTR, QUIT, and SUSP. This shall have the +effect of setting (not setting) ISIG in the <b>termios</b> <i>c_lflag</i> field, as defined in XBD <a href= +"../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> .</dd> +<dt><b>icanon </b>(<b>-icanon</b>)</dt> +<dd>Enable (disable) canonical input (ERASE and KILL processing). This shall have the effect of setting (not setting) ICANON in the +<b>termios</b> <i>c_lflag</i> field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal +Interface</i></a> .</dd> +<dt><b>iexten </b>(<b>-iexten</b>)</dt> +<dd>Enable (disable) any implementation-defined special control characters not currently controlled by <b>icanon</b>, <b>isig</b>, +<b>ixon</b>, or <b>ixoff</b>. This shall have the effect of setting (not setting) IEXTEN in the <b>termios</b> <i>c_lflag</i> +field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> .</dd> +<dt><b>echo </b>(<b>-echo</b>)</dt> +<dd>Echo back (do not echo back) every character typed. This shall have the effect of setting (not setting) ECHO in the +<b>termios</b> <i>c_lflag</i> field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal +Interface</i></a> .</dd> +<dt><b>echoe </b>(<b>-echoe</b>)</dt> +<dd>The ERASE character visually erases (does not erase) the last character in the current line from the display, if possible. This +shall have the effect of setting (not setting) ECHOE in the <b>termios</b> <i>c_lflag</i> field, as defined in XBD <a href= +"../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> .</dd> +<dt><b>echok </b>(<b>-echok</b>)</dt> +<dd>Echo (do not echo) NL after KILL character. This shall have the effect of setting (not setting) ECHOK in the <b>termios</b> +<i>c_lflag</i> field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> +.</dd> +<dt><b>echonl </b>(<b>-echonl</b>)</dt> +<dd>Echo (do not echo) NL, even if <b>echo</b> is disabled. This shall have the effect of setting (not setting) ECHONL in the +<b>termios</b> <i>c_lflag</i> field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal +Interface</i></a> .</dd> +<dt><b>noflsh </b>(<b>-noflsh</b>)</dt> +<dd>Disable (enable) flush after INTR, QUIT, SUSP. This shall have the effect of setting (not setting) NOFLSH in the <b>termios</b> +<i>c_lflag</i> field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> +.</dd> +<dt><b>tostop </b>(<b>-tostop</b>)</dt> +<dd>Send SIGTTOU for background output. This shall have the effect of setting (not setting) TOSTOP in the <b>termios</b> +<i>c_lflag</i> field, as defined in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> +.</dd> +</dl> +<h5><a name="tag_20_116_05_05" id="tag_20_116_05_05"></a>Special Control Character Assignments</h5> +<dl compact> +<dd></dd> +<dt><<i>control</i>>-<i>character string</i></dt> +<dd><br> +Set <<i>control</i>>-<i>character</i> to <i>string</i>. If <<i>control</i>>-<i>character</i> is one of the character +sequences in the first column of the following table, the corresponding XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. +General Terminal Interface</i></a> control character from the second column shall be recognized. This has the effect of setting the +corresponding element of the <b>termios</b> <i>c_cc</i> array (see XBD <a href="../basedefs/V1_chap14.html#tag_14"><i>14. +Headers</i></a> , <a href="../basedefs/termios.h.html"><i><termios.h></i></a>).<br> +<p class="caption">Table: Control Character Names in <i>stty</i></p> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Control Character</b></p> +</th> +<th align="center"> +<p class="tent"><b>c_cc Subscript</b></p> +</th> +<th align="center"> +<p class="tent"><b>Description</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>eof</b></p> +</td> +<td align="left"> +<p class="tent">VEOF</p> +</td> +<td align="left"> +<p class="tent">EOF character</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>eol</b></p> +</td> +<td align="left"> +<p class="tent">VEOL</p> +</td> +<td align="left"> +<p class="tent">EOL character</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>erase</b></p> +</td> +<td align="left"> +<p class="tent">VERASE</p> +</td> +<td align="left"> +<p class="tent">ERASE character</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>intr</b></p> +</td> +<td align="left"> +<p class="tent">VINTR</p> +</td> +<td align="left"> +<p class="tent">INTR character</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>kill</b></p> +</td> +<td align="left"> +<p class="tent">VKILL</p> +</td> +<td align="left"> +<p class="tent">KILL character</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>quit</b></p> +</td> +<td align="left"> +<p class="tent">VQUIT</p> +</td> +<td align="left"> +<p class="tent">QUIT character</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>susp</b></p> +</td> +<td align="left"> +<p class="tent">VSUSP</p> +</td> +<td align="left"> +<p class="tent">SUSP character</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>start</b></p> +</td> +<td align="left"> +<p class="tent">VSTART</p> +</td> +<td align="left"> +<p class="tent">START character</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>stop</b></p> +</td> +<td align="left"> +<p class="tent">VSTOP</p> +</td> +<td align="left"> +<p class="tent">STOP character</p> +</td> +</tr> +</table> +</center> +<p class="tent">If <i>string</i> is a single character, the control character shall be set to that character. If <i>string</i> is +the two-character sequence <tt>"^-"</tt> or the string <i>undef</i>, the control character shall be set to _POSIX_VDISABLE , if it +is in effect for the device; if _POSIX_VDISABLE is not in effect for the device, it shall be treated as an error. In the POSIX +locale, if <i>string</i> is a two-character sequence beginning with <circumflex> (<tt>'^'</tt>), and the second character is +one of those listed in the <tt>"^c"</tt> column of the following table, the control character shall be set to the corresponding +character value in the Value column of the table.<br></p> +<p class="caption">Table: Circumflex Control Characters in <i>stty</i></p> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>^c</b></p> +</th> +<th align="center"> +<p class="tent"><b>Value</b></p> +</th> +<th align="center"> +<p class="tent"><b>^c</b></p> +</th> +<th align="center"> +<p class="tent"><b>Value</b></p> +</th> +<th align="center"> +<p class="tent"><b>^c</b></p> +</th> +<th align="center"> +<p class="tent"><b>Value</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">a, A</p> +</td> +<td align="left"> +<p class="tent"><SOH></p> +</td> +<td align="left"> +<p class="tent">l, L</p> +</td> +<td align="left"> +<p class="tent"><FF></p> +</td> +<td align="left"> +<p class="tent">w, W</p> +</td> +<td align="left"> +<p class="tent"><ETB></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">b, B</p> +</td> +<td align="left"> +<p class="tent"><STX></p> +</td> +<td align="left"> +<p class="tent">m, M</p> +</td> +<td align="left"> +<p class="tent"><CR></p> +</td> +<td align="left"> +<p class="tent">x, X</p> +</td> +<td align="left"> +<p class="tent"><CAN></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">c, C</p> +</td> +<td align="left"> +<p class="tent"><ETX></p> +</td> +<td align="left"> +<p class="tent">n, N</p> +</td> +<td align="left"> +<p class="tent"><SO></p> +</td> +<td align="left"> +<p class="tent">y, Y</p> +</td> +<td align="left"> +<p class="tent"><EM></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">d, D</p> +</td> +<td align="left"> +<p class="tent"><EOT></p> +</td> +<td align="left"> +<p class="tent">o, O</p> +</td> +<td align="left"> +<p class="tent"><SI></p> +</td> +<td align="left"> +<p class="tent">z, Z</p> +</td> +<td align="left"> +<p class="tent"><SUB></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">e, E</p> +</td> +<td align="left"> +<p class="tent"><ENQ></p> +</td> +<td align="left"> +<p class="tent">p, P</p> +</td> +<td align="left"> +<p class="tent"><DLE></p> +</td> +<td align="left"> +<p class="tent">[</p> +</td> +<td align="left"> +<p class="tent"><ESC></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">f, F</p> +</td> +<td align="left"> +<p class="tent"><ACK></p> +</td> +<td align="left"> +<p class="tent">q, Q</p> +</td> +<td align="left"> +<p class="tent"><DC1></p> +</td> +<td align="left"> +<p class="tent">\</p> +</td> +<td align="left"> +<p class="tent"><FS></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">g, G</p> +</td> +<td align="left"> +<p class="tent"><BEL></p> +</td> +<td align="left"> +<p class="tent">r, R</p> +</td> +<td align="left"> +<p class="tent"><DC2></p> +</td> +<td align="left"> +<p class="tent">]</p> +</td> +<td align="left"> +<p class="tent"><GS></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">h, H</p> +</td> +<td align="left"> +<p class="tent"><BS></p> +</td> +<td align="left"> +<p class="tent">s, S</p> +</td> +<td align="left"> +<p class="tent"><DC3></p> +</td> +<td align="left"> +<p class="tent">^</p> +</td> +<td align="left"> +<p class="tent"><RS></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">i, I</p> +</td> +<td align="left"> +<p class="tent"><HT></p> +</td> +<td align="left"> +<p class="tent">t, T</p> +</td> +<td align="left"> +<p class="tent"><DC4></p> +</td> +<td align="left"> +<p class="tent">_</p> +</td> +<td align="left"> +<p class="tent"><US></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">j, J</p> +</td> +<td align="left"> +<p class="tent"><LF></p> +</td> +<td align="left"> +<p class="tent">u, U</p> +</td> +<td align="left"> +<p class="tent"><NAK></p> +</td> +<td align="left"> +<p class="tent">?</p> +</td> +<td align="left"> +<p class="tent"><DEL></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">k, K</p> +</td> +<td align="left"> +<p class="tent"><VT></p> +</td> +<td align="left"> +<p class="tent">v, V</p> +</td> +<td align="left"> +<p class="tent"><SYN></p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +</tr> +</table> +</center> +</dd> +<dt><b>min </b><i>number</i></dt> +<dd><br> +Set the value of MIN to <i>number</i>. MIN is used in non-canonical mode input processing (<b>-icanon</b>).</dd> +<dt><b>time </b><i>number</i></dt> +<dd><br> +Set the value of TIME to <i>number</i>. TIME is used in non-canonical mode input processing (<b>-icanon</b>).</dd> +</dl> +<h5><a name="tag_20_116_05_06" id="tag_20_116_05_06"></a>Combination Modes</h5> +<dl compact> +<dd></dd> +<dt><i>saved settings</i></dt> +<dd><br> +Set the current terminal characteristics to the saved settings produced by the <b>-g</b> option.</dd> +<dt><b>evenp</b> or <b>parity</b></dt> +<dd><br> +Enable <b>parenb</b> and <b>cs7</b>; disable <b>parodd</b>.</dd> +<dt><b>oddp</b></dt> +<dd><br> +Enable <b>parenb</b>, <b>cs7</b>, and <b>parodd</b>.</dd> +<dt><b>-parity</b>, <b>-evenp</b>, or <b>-oddp</b></dt> +<dd><br> +Disable <b>parenb</b>, and set <b>cs8</b>.</dd> +<dt><b>raw </b>(<b>-raw</b> or <b>cooked</b>)</dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border= +"0"><br> +Enable (disable) raw input and output. Raw mode shall be equivalent to setting: +<pre> +<tt>stty cs8 erase ^- kill ^- intr ^- \ + quit ^- eof ^- eol ^- -post -inpck +</tt></pre> +<img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>nl </b>(<b>-nl</b>)</dt> +<dd><br> +Disable (enable) <b>icrnl</b>. In addition, <b>-nl</b> unsets <b>inlcr</b> and <b>igncr</b>.</dd> +<dt><b>ek</b></dt> +<dd>Reset ERASE and KILL characters back to system defaults.</dd> +<dt><b>sane</b></dt> +<dd><br> +Reset all modes to some reasonable, unspecified, values.</dd> +</dl> +<h5><a name="tag_20_116_05_07" id="tag_20_116_05_07"></a>Terminal Window Size</h5> +<dl compact> +<dd></dd> +<dt><b>rows </b><i>number</i></dt> +<dd><br> +Set the number of rows in the terminal window size to the number given.</dd> +<dt><b>cols </b><i>number</i></dt> +<dd><br> +Set the number of columns in the terminal window size to the number given.</dd> +</dl> +<p class="tent">The terminal window size shall be updated as if the <i>stty</i> utility calls <a href= +"../functions/tcgetwinsize.html"><i>tcgetwinsize</i>()</a> to populate a <b>winsize</b> structure, updates one or both of the +<i>ws_row</i> and <i>ws_col</i> members according to the <b>rows</b> and <b>cols</b> numbers specified, and then calls <a href= +"../functions/tcsetwinsize.html"><i>tcsetwinsize</i>()</a> with the updated structure (see XSH <a href= +"../functions/tcgetwinsize.html#"><i>tcgetwinsize</i></a> and <a href="../functions/tcsetwinsize.html#"><i>tcsetwinsize</i></a> +).</p> +<h5><a name="tag_20_116_05_08" id="tag_20_116_05_08"></a>Informational Queries</h5> +<dl compact> +<dd></dd> +<dt><b>size</b></dt> +<dd><br> +Write the current terminal window size to standard output.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_116_06" id="tag_20_116_06"></a>STDIN</h4> +<blockquote> +<p>Although no input is read from standard input, standard input shall be used to get the current terminal I/O characteristics and +to set new terminal I/O characteristics.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_116_07" id="tag_20_116_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_116_08" id="tag_20_116_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>stty</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>This variable determines the locale for the interpretation of sequences of bytes of text data as characters (for example, +single-byte as opposed to multi-byte characters in arguments) and which characters are in the class <b>print</b>.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_116_09" id="tag_20_116_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_116_10" id="tag_20_116_10"></a>STDOUT</h4> +<blockquote> +<p>If operands are specified and they do not include any Informational Queries, no output shall be produced.</p> +<p class="tent">If the <b>size</b> operand is specified, <i>stty</i> shall write to standard output the terminal window size as +follows:</p> +<pre> +<tt>"%1dΔ%1d\n", <</tt><i>rows</i><tt>>, <</tt><i>columns</i><tt>> +</tt></pre> +where <<i>rows</i>> and <<i>columns</i>> are the number of rows and columns in the terminal window size, respectively. +<p class="tent">If the <b>-g</b> option is specified, <i>stty</i> shall write to standard output the current settings in a form +that can be used as arguments to another instance of <i>stty</i> on the same system.</p> +<p class="tent">If the <b>-a</b> option is specified, all of the information as described in the OPERANDS section shall be written +to standard output. Unless otherwise specified, this information shall be written as <space>-separated tokens in an +unspecified format, on one or more lines, with an unspecified number of tokens per line. Additional information may be written.</p> +<p class="tent">If no options or operands are specified, an unspecified subset of the information written for the <b>-a</b> option +shall be written.</p> +<p class="tent">If speed information is written as part of the default output, or if the <b>-a</b> option is specified and if the +terminal input speed and output speed are the same, the speed information shall be written as follows:</p> +<pre> +<tt>"speed %d baud;", <</tt><i>speed</i><tt>> +</tt></pre> +<p class="tent">Otherwise, speeds shall be written as:</p> +<pre> +<tt>"ispeed %d baud; ospeed %d baud;", <</tt><i>ispeed</i><tt>>, <</tt><i>ospeed</i><tt>> +</tt></pre> +<p class="tent">In locales other than the POSIX locale, the word <b>baud</b> may be changed to something more appropriate in those +locales.</p> +<p class="tent">If control characters are written as part of the default output, or if the <b>-a</b> option is specified, control +characters shall be written as:</p> +<pre> +<tt>"%s = %s;", <</tt><i>control-character name</i><tt>>, <</tt><i>value</i><tt>> +</tt></pre> +<p class="tent">where <<i>value</i>> is either the character, or some visual representation of the character if it is +non-printable, or the string <tt>"<undef>"</tt> if the character is disabled.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_116_11" id="tag_20_116_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_116_12" id="tag_20_116_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_116_13" id="tag_20_116_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_116_14" id="tag_20_116_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_116_15" id="tag_20_116_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_116_16" id="tag_20_116_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The <b>-g</b> flag is designed to facilitate the saving and restoring of terminal state from the shell level. For example, a +program may:</p> +<pre> +<tt>saveterm=$(stty -g) # save terminal state +restoresize=$( + printf "stty rows %d cols %d" $(stty size) +) # save terminal size +stty </tt><i>new settings</i><tt> # set new state +... +[ -n "$saveterm" ] && stty "$saveterm" # restore terminal state +eval "$restoresize" # restore terminal size +</tt></pre> +<p class="tent">Since the format is unspecified, the saved value is not portable across systems.</p> +<p class="tent">Since the <b>-a</b> format is so loosely specified, scripts that save and restore terminal settings should use the +<b>-g</b> option.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_116_17" id="tag_20_116_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_116_18" id="tag_20_116_18"></a>RATIONALE</h4> +<blockquote> +<p>The original <i>stty</i> description was taken directly from System V and reflected the System V terminal driver <b>termio</b>. +It has been modified to correspond to the terminal driver <b>termios</b>.</p> +<p class="tent">Output modes are specified only for XSI-conformant systems. All implementations are expected to provide <i>stty</i> +operands corresponding to all of the output modes they support.</p> +<p class="tent">The <i>stty</i> utility is primarily used to tailor the user interface of the terminal, such as selecting the +preferred ERASE and KILL characters. As an application programming utility, <i>stty</i> can be used within shell scripts to alter +the terminal settings for the duration of the script.</p> +<p class="tent">The <b>termios</b> section states that individual disabling of control characters is possible through the option +_POSIX_VDISABLE. If enabled, two conventions currently exist for specifying this: System V uses <tt>"^-"</tt>, and BSD uses +<i>undef</i>. Both are accepted by <i>stty</i> in this volume of POSIX.1-2024. The other BSD convention of using the letter +<tt>'u'</tt> was rejected because it conflicts with the actual letter <tt>'u'</tt>, which is an acceptable value for a control +character.</p> +<p class="tent">Early proposals did not specify the mapping of <tt>"^c"</tt> to control characters because the control characters +were not specified in the POSIX locale character set description file requirements. The control character set is now specified in +XBD <a href="../basedefs/V1_chap03.html#tag_03"><i>3. Definitions</i></a> , so the historical mapping is specified. Note that +although the mapping corresponds to control-character key assignments on many terminals that use the ISO/IEC 646:1991 standard +(or ASCII) character encodings, the mapping specified here is to the control characters, not their keyboard encodings.</p> +<p class="tent">Since <b>termios</b> supports separate speeds for input and output, two new options were added to specify each +distinctly.</p> +<p class="tent">Some historical implementations use standard input to get and set terminal characteristics; others use standard +output. Since input from a login TTY is usually restricted to the owner while output to a TTY is frequently open to anyone, using +standard input provides fewer chances of accidentally (or maliciously) altering the terminal settings of other users. Using +standard input also allows <i>stty</i> <b>-a</b> and <i>stty</i> <b>-g</b> output to be redirected for later use. Therefore, usage +of standard input is required by this volume of POSIX.1-2024.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_116_19" id="tag_20_116_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_116_20" id="tag_20_116_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19"><i>2. Shell Command Language</i></a></p> +<p class="tent">XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a> , <a href= +"../basedefs/termios.h.html"><i><termios.h></i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_116_21" id="tag_20_116_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_116_22" id="tag_20_116_22"></a>Issue 5</h4> +<blockquote> +<p>The description of <b>tabs</b> is clarified.</p> +<p class="tent">The FUTURE DIRECTIONS section is added.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_116_23" id="tag_20_116_23"></a>Issue 6</h4> +<blockquote> +<p>The LEGACY items <b>iuclc</b> (-<b>iuclc</b>), <b>xcase</b> (-<b>xcase</b>), <b>olcuc</b> (-<b>olcuc</b>), <b>lcase</b> +(-<b>lcase</b>), and <b>LCASE</b> (-<b>LCASE</b>) are removed.</p> +<p class="tent">IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/37 is applied, applying IEEE PASC Interpretation +1003.2 #133, fixing an error in the OPERANDS section for the Combination Modes <b>nl</b> (<b>-nl</b>).</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_116_24" id="tag_20_116_24"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #144 is applied, moving functionality relating to the IXANY symbol from the XSI option +to the Base.</p> +<p class="tent">SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p class="tent">POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0189 [908] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_116_25" id="tag_20_116_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defects 1053, 1532, and 1687 are applied, changing the <b>-g</b> option and adding the <b>rows</b> <i>number</i>, +<b>cols</b> <i>number</i>, and <b>size</b> operands.</p> +<p class="tent">Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p class="tent">Austin Group Defect 1508 is applied, changing the EXIT STATUS section.</p> +<p class="tent">Austin Group Defect 1604 is applied, changing <i>undef</i> to <tt>"<undef>"</tt> in the STDOUT section, and +changing <b>icanon</b> to <b>-icanon</b> in the descriptions of <b>min</b> and <b>time</b>.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/strip.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/tabs.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/tabs.html b/bdd/tabs.html @@ -0,0 +1,284 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>tabs</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/stty.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/tail.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="tabs" id="tabs"></a> <a name="tag_20_117" id="tag_20_117"></a><!-- tabs --> +<h4 class="mansect"><a name="tag_20_117_01" id="tag_20_117_01"></a>NAME</h4> +<blockquote>tabs — set terminal tabs</blockquote> +<h4 class="mansect"><a name="tag_20_117_02" id="tag_20_117_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> tabs</tt> <b>[</b><tt>-</tt><i>n</i><tt>|<img src= +"../images/opt-start.gif" border="0">-a|-a2|-c|-c2|-c3|-f|-p|-s|-u</tt><b><img src="../images/opt-end.gif" border="0">] +[</b><tt>-T</tt> <i>type</i><b>]</b> <tt><br> +<br> +tabs</tt> <b>[</b><tt>-T</tt> <i>type</i><b>]</b> +<i>n</i><b>[[</b><i>sep</i><b>[</b><tt>+</tt><b>]</b><i>n</i><b>]</b><tt>...</tt><b>]</b> <tt><br></tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_117_03" id="tag_20_117_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>tabs</i> utility shall display a series of characters that first clears the hardware terminal tab settings and then +initializes the tab stops at the specified positions <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src= +"../images/opt-start.gif" alt="[Option Start]" border="0"> and optionally adjusts the margin. <img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></p> +<p>The phrase "tab-stop position <i>N</i>" shall be taken to mean that, from the start of a line of output, tabbing to position +<i>N</i> shall cause the next character output to be in the (<i>N</i>+1)th column position on that line. The maximum number of tab +stops allowed is terminal-dependent.</p> +<p>It need not be possible to implement <i>tabs</i> on certain terminals. If the terminal type obtained from the <i>TERM</i> +environment variable or <b>-T</b> option represents such a terminal, an appropriate diagnostic message shall be written to standard +error and <i>tabs</i> shall exit with a status greater than zero.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_117_04" id="tag_20_117_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>tabs</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> , <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> except for various extensions: the options <b>-a2</b>, <b>-c2</b>, and <b>-c3</b> are +multi-character. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-</b><i>n</i></dt> +<dd>Specify repetitive tab stops separated by a uniform number of column positions, <i>n</i>, where <i>n</i> is a single-digit +decimal number. The default usage of <i>tabs</i> with no arguments shall be equivalent to <i>tabs</i> -8. When <b>-0</b> is used, +the tab stops shall be cleared and no new ones set.</dd> +<dt><b>-a</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +1,10,16,36,72<br> +Assembler, applicable to some mainframes. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-a2</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +1,10,16,40,72<br> +Assembler, applicable to some mainframes. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-c</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +1,8,12,16,20,55<br> +COBOL, normal format. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-c2</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +1,6,10,14,49<br> +COBOL, compact format (columns 1 to 6 omitted). <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-c3</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +1,6,10,14,18,22,26,30,34,38,42,46,50,54,58,62,67<br> +COBOL compact format (columns 1 to 6 omitted), with more tabs than <b>-c2</b>. <img src="../images/opt-end.gif" alt="[Option End]" +border="0"></dd> +<dt><b>-f</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +1,7,11,15,19,23<br> +FORTRAN <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-p</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +1,5,9,13,17,21,25,29,33,37,41,45,49,53,57,61<br> +PL/1 <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-s</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +1,10,55<br> +SNOBOL <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-u</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +1,12,20,44<br> +Assembler, applicable to some mainframes. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-T </b><i>type</i></dt> +<dd>Indicate the type of terminal. If this option is not supplied and the <i>TERM</i> variable is unset or null, an unspecified +default terminal type shall be used. The setting of <i>type</i> shall take precedence over the value in <i>TERM .</i></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_117_05" id="tag_20_117_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>n</i><b>[[</b><i>sep</i><b>[</b>+<b>]</b><i>n</i><b>]</b>...<b>]</b></dt> +<dd>A single command line argument that consists of one or more tab-stop values (<i>n</i>) separated by a separator character +(<i>sep</i>) which is either a <comma> or a <blank> character. The application shall ensure that the tab-stop values +are positive decimal integers in strictly ascending order. If any tab-stop value (except the first one) is preceded by a +<plus-sign>, it is taken as an increment to be added to the previous value. For example, the tab lists 1,10,20,30 and <tt>"1 +10 +10 +10"</tt> are considered to be identical.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_117_06" id="tag_20_117_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_117_07" id="tag_20_117_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_117_08" id="tag_20_117_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>tabs</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>TERM</i></dt> +<dd>Determine the terminal type. If this variable is unset or null, and if the <b>-T</b> option is not specified, an unspecified +default terminal type shall be used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_117_09" id="tag_20_117_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_117_10" id="tag_20_117_10"></a>STDOUT</h4> +<blockquote> +<p>If standard output is a terminal, the appropriate sequence to clear and set the tab stops may be written to standard output in +an unspecified format. If standard output is not a terminal, undefined results occur.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_117_11" id="tag_20_117_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_117_12" id="tag_20_117_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_117_13" id="tag_20_117_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_117_14" id="tag_20_117_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_117_15" id="tag_20_117_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_117_16" id="tag_20_117_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>This utility makes use of the terminal's hardware tabs and the <a href="../utilities/stty.html"><i>stty</i></a> <i>tabs</i> +option.</p> +<p>This utility is not recommended for application use.</p> +<p>Some integrated display units might not have escape sequences to set tab stops, but may be set by internal system calls. On +these terminals, <i>tabs</i> works if standard output is directed to the terminal; if output is directed to another file, however, +<i>tabs</i> fails.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_117_17" id="tag_20_117_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_117_18" id="tag_20_117_18"></a>RATIONALE</h4> +<blockquote> +<p>Consideration was given to having the <a href="../utilities/tput.html"><i>tput</i></a> utility handle all of the functions +described in <i>tabs</i>. However, the separate <i>tabs</i> utility was retained because it seems more intuitive to use a command +named <i>tabs</i> than <a href="../utilities/tput.html"><i>tput</i></a> with a new option. The <a href= +"../utilities/tput.html"><i>tput</i></a> utility does not support setting or clearing tabs, and no known historical version of +<i>tabs</i> supports the capability of setting arbitrary tab stops.</p> +<p>The System V <i>tabs</i> interface is very complex; the version in this volume of POSIX.1-2024 has a reduced feature list, but +many of the features omitted were restored as part of the XSI option even though the supported languages and coding styles are +primarily historical.</p> +<p>There was considerable sentiment for specifying only a means of resetting the tabs back to a known state—presumably the +"standard" of tabs every eight positions. The following features were omitted:</p> +<ul> +<li> +<p>Setting tab stops via the first line in a file, using --<i>file</i>. Since even the SVID has no complete explanation of this +feature, it is doubtful that it is in widespread use.</p> +</li> +</ul> +<p>In an early proposal, a <b>-t</b> <i>tablist</i> option was added for consistency with <a href= +"../utilities/expand.html"><i>expand</i></a>; this was later removed when inconsistencies with the historical list of tabs were +identified.</p> +<p>Consideration was given to adding a <b>-p</b> option that would output the current tab settings so that they could be saved and +then later restored. This was not accepted because querying the tab stops of the terminal is not a capability in historical +<i>terminfo</i> or <i>termcap</i> facilities and might not be supported on a wide range of terminals.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_117_19" id="tag_20_117_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_117_20" id="tag_20_117_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/expand.html#"><i>expand</i></a> , <a href="../utilities/stty.html#"><i>stty</i></a> , <a href= +"../utilities/tput.html#"><i>tput</i></a> , <a href="../utilities/unexpand.html#"><i>unexpand</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_117_21" id="tag_20_117_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_117_22" id="tag_20_117_22"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_117_23" id="tag_20_117_23"></a>Issue 7</h4> +<blockquote> +<p>The <i>tabs</i> utility is removed from the User Portability Utilities option. User Portability Utilities is now an option for +interactive utilities.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>The SYNOPSIS and OPERANDS sections are updated.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_117_24" id="tag_20_117_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/stty.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/tail.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/tail.html b/bdd/tail.html @@ -0,0 +1,320 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>tail</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/tabs.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/talk.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="tail" id="tail"></a> <a name="tag_20_118" id="tag_20_118"></a><!-- tail --> +<h4 class="mansect"><a name="tag_20_118_01" id="tag_20_118_01"></a>NAME</h4> +<blockquote>tail — copy the last part of a file</blockquote> +<h4 class="mansect"><a name="tag_20_118_02" id="tag_20_118_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>tail</tt> <b>[</b><tt>-f</tt><b>] [</b><tt>-c</tt> <i>number</i><tt>|-n</tt> <i>number</i><b>] [</b><i>file</i><b>]</b> +<tt><br> +<br> +tail -r</tt> <b>[</b><tt>-n</tt> <i>number</i><b>] [</b><i>file</i><b>]</b> <tt><br></tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_118_03" id="tag_20_118_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>tail</i> utility shall copy its input file to the standard output beginning at a designated place.</p> +<p>Copying shall begin at the point in the file indicated by the <b>-c</b> <i>number</i> or <b>-n</b> <i>number</i> options. The +option-argument <i>number</i> shall be counted in units of lines or bytes, according to the options <b>-n</b> and <b>-c</b>. Both +line and byte counts start from 1.</p> +<p>Tails relative to the end of the file may be saved in an internal buffer, and thus may be limited in length. Such a buffer, if +any, shall be no smaller than {LINE_MAX}*10 bytes.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_118_04" id="tag_20_118_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>tail</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> , except that <tt>'+'</tt> may be recognized as an option delimiter as well as <tt>'-'</tt>.</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-c </b><i>number</i></dt> +<dd>The application shall ensure that the <i>number</i> option-argument is a decimal integer, optionally including a sign. The sign +shall affect the location in the file, measured in bytes, to begin the copying: +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Sign</b></p> +</th> +<th align="center"> +<p class="tent"><b>Copying Starts</b></p> +</th> +</tr> +<tr valign="top"> +<td align="center"> +<p class="tent">+</p> +</td> +<td align="left"> +<p class="tent">Relative to the beginning of the file.</p> +</td> +</tr> +<tr valign="top"> +<td align="center"> +<p class="tent">-</p> +</td> +<td align="left"> +<p class="tent">Relative to the end of the file.</p> +</td> +</tr> +<tr valign="top"> +<td align="center"> +<p class="tent"><i>none</i></p> +</td> +<td align="left"> +<p class="tent">Relative to the end of the file.</p> +</td> +</tr> +</table> +</center> +<p class="tent">The application shall ensure that if the sign of the <i>number</i> option-argument is <tt>'+'</tt>, the +<i>number</i> option-argument is a non-zero decimal integer.</p> +<p class="tent">The origin for counting shall be 1; that is, <b>-c</b> +1 represents the first byte of the file, <b>-c</b> -1 the +last.</p> +</dd> +<dt><b>-f</b></dt> +<dd>If the input file is a regular file or if the <i>file</i> operand specifies a FIFO, do not terminate after the last line of the +input file has been copied, but read and copy further bytes from the input file when they become available. If no <i>file</i> +operand is specified and standard input is a pipe or FIFO, the <b>-f</b> option shall be ignored. If the input file is not a FIFO, +pipe, or regular file, it is unspecified whether or not the <b>-f</b> option shall be ignored.</dd> +<dt><b>-n </b><i>number</i></dt> +<dd>If <b>-r</b> is not specified, this option shall be equivalent to <b>-c</b> <i>number</i>, except the starting location in the +file shall be measured in lines instead of bytes. The origin for counting shall be 1; that is, <b>-n</b> +1 represents the first +line of the file, <b>-n</b> -1 the last. +<p class="tent">If <b>-r</b> is specified, <i>number</i> shall specify the number of lines to read (in reverse) from the end of the +input file. The application shall ensure that <i>number</i> does not have a sign.</p> +</dd> +<dt><b>-r</b></dt> +<dd>Copy the lines in reverse order (last line first). If <b>-n</b> is specified, that many lines of the file, starting with the +last line, shall be copied. If <b>-n</b> is not specified, every line of the input file shall be copied.</dd> +</dl> +<p class="tent">If none of the <b>-c</b>, <b>-n</b> or <b>-r</b> options is specified, <b>-n</b> 10 shall be assumed.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_118_05" id="tag_20_118_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of an input file. If no <i>file</i> operand is specified, the standard input shall be used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_118_06" id="tag_20_118_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be used if no <i>file</i> operand is specified, and shall be used if the <i>file</i> operand is +<tt>'-'</tt> and the implementation treats the <tt>'-'</tt> as meaning standard input. Otherwise, the standard input shall not be +used. See the INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_118_07" id="tag_20_118_07"></a>INPUT FILES</h4> +<blockquote> +<p>If the <b>-c</b> option is specified, the input file can contain arbitrary data; otherwise, the input file shall be a text +file.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_118_08" id="tag_20_118_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>tail</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_118_09" id="tag_20_118_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_118_10" id="tag_20_118_10"></a>STDOUT</h4> +<blockquote> +<p>The designated portion of the input file shall be written to standard output.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_118_11" id="tag_20_118_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_118_12" id="tag_20_118_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_118_13" id="tag_20_118_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_118_14" id="tag_20_118_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_118_15" id="tag_20_118_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_118_16" id="tag_20_118_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The <b>-c</b> option should be used with caution when the input is a text file containing multi-byte characters; it may produce +output that does not start on a character boundary.</p> +<p class="tent">Although the input file to <i>tail</i> can be any type, the results might not be what would be expected on some +character special device files or on file types not described by the System Interfaces volume of POSIX.1-2024. Since this volume of +POSIX.1-2024 does not specify the block size used when doing input, <i>tail</i> need not read all of the data from devices that +only perform block transfers.</p> +<p class="tent">When using <i>tail</i> to process pathnames, and the <b>-c</b> option is not specified, it is recommended that +LC_ALL, or at least LC_CTYPE and LC_COLLATE, are set to POSIX or C in the environment, since pathnames can contain byte sequences +that do not form valid characters in some locales, in which case the utility's behavior would be undefined. In the POSIX locale +each byte is a valid single-byte character, and therefore this problem is avoided.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_118_17" id="tag_20_118_17"></a>EXAMPLES</h4> +<blockquote> +<p>The <b>-f</b> option can be used to monitor the growth of a file that is being written by some other process. For example, the +command:</p> +<pre> +<tt>tail -f fred +</tt></pre> +<p class="tent">prints the last ten lines of the file <b>fred</b>, followed by any lines that are appended to <b>fred</b> between +the time <i>tail</i> is initiated and killed. As another example, the command:</p> +<pre> +<tt>tail -f -c 15 fred +</tt></pre> +<p class="tent">prints the last 15 bytes of the file <b>fred</b>, followed by any bytes that are appended to <b>fred</b> between +the time <i>tail</i> is initiated and killed.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_118_18" id="tag_20_118_18"></a>RATIONALE</h4> +<blockquote> +<p>This version of <i>tail</i> was created to allow conformance to the Utility Syntax Guidelines. The historical <b>-b</b> option +was omitted because of the general non-portability of block-sized units of text. The <b>-c</b> option historically meant +"characters", but this volume of POSIX.1-2024 indicates that it means "bytes". This was selected to allow reasonable +implementations when multi-byte characters are possible; it was not named <b>-b</b> to avoid confusion with the historical +<b>-b</b>.</p> +<p class="tent">The origin of counting both lines and bytes is 1, matching all widespread historical implementations. Hence +<i>tail</i> <b>-n</b> +0 is not conforming usage because it attempts to output line zero; but note that <i>tail</i> <b>-n</b> 0 +does conform, and outputs nothing.</p> +<p class="tent">Earlier versions of this standard allowed the following forms in the SYNOPSIS:</p> +<pre> +<tt>tail -</tt><b>[</b><tt>number</tt><b>][</b><tt>b|c|l</tt><b>][</b><tt>f</tt><b>] [</b><i>file</i><b>]</b><tt> +tail +</tt><b>[</b><tt>number</tt><b>][</b><tt>b|c|l</tt><b>][</b><tt>f</tt><b>] [</b><i>file</i><b>]</b><tt> +</tt></pre> +<p class="tent">These forms are no longer specified by POSIX.1-2024, but may be present in some implementations.</p> +<p class="tent">The restriction on the internal buffer is a compromise between the historical System V implementation of 4096 bytes +and the BSD 32768 bytes.</p> +<p class="tent">The <b>-f</b> option has been implemented as a loop that sleeps for 1 second and copies any bytes that are +available. This is sufficient, but if more efficient methods of determining when new data are available are developed, +implementations are encouraged to use them.</p> +<p class="tent">Historical documentation indicates that <i>tail</i> ignores the <b>-f</b> option if the input file is a pipe (pipe +and FIFO on systems that support FIFOs). On BSD-based systems, this has been true; on System V-based systems, this was true when +input was taken from standard input, but it did not ignore the <b>-f</b> flag if a FIFO was named as the <i>file</i> operand. Since +the <b>-f</b> option is not useful on pipes and all historical implementations ignore <b>-f</b> if no <i>file</i> operand is +specified and standard input is a pipe, this volume of POSIX.1-2024 requires this behavior. However, since the <b>-f</b> option is +useful on a FIFO, this volume of POSIX.1-2024 also requires that if a FIFO is named, the <b>-f</b> option shall not be ignored. +Earlier versions of this standard did not state any requirement for the case where no <i>file</i> operand is specified and standard +input is a FIFO. The standard has been updated to reflect current practice which is to treat this case the same as a pipe on +standard input. Although historical behavior does not ignore the <b>-f</b> option for other file types, this is unspecified so that +implementations are allowed to ignore the <b>-f</b> option if it is known that the file cannot be extended.</p> +<p class="tent">The functionality made available by <i>tail</i> <b>-r</b> has been historically provided on some systems by a +separate utility (<i>tac</i>), although <i>tac</i> traditionally lacked support for <b>-n</b> to limit the output. While both +<tt>tail -n$n | tac</tt> and <tt>tac | head -n$n</tt> can be used to output a fixed length of reversed line output, the standard +developers decided that it was preferable to have a single utility <tt>tail -r -n$n</tt> for the same purpose. Furthermore, in +deciding whether to standardize <i>tac</i> rather than <i>tail</i> <b>-r</b>, it was determined that more implementations that have +achieved POSIX certification had already implemented <i>tail</i> <b>-r</b> as an extension.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_118_19" id="tag_20_118_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_118_20" id="tag_20_118_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/head.html#"><i>head</i></a></p> +<p class="tent">XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_118_21" id="tag_20_118_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_118_22" id="tag_20_118_22"></a>Issue 6</h4> +<blockquote> +<p>The obsolescent SYNOPSIS lines and associated text are removed.</p> +<p class="tent">The normative text is reworded to avoid use of the term "must" for application requirements.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_118_23" id="tag_20_118_23"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #027 is applied, clarifying that <tt>'+'</tt> may be recognized as an option delimiter +in the OPTIONS section.</p> +<p class="tent">Austin Group Interpretation 1003.1-2001 #092 is applied.</p> +<p class="tent">Austin Group Interpretation 1003.1-2001 #100 is applied, adding the requirement on applications that if the sign of +the option-argument <i>number</i> is <tt>'+'</tt>, the <i>number</i> option-argument is a non-zero decimal integer.</p> +<p class="tent">SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p class="tent">SD5-XCU-ERN-114 is applied, updating the OPTIONS section (the <b>-f</b> option).</p> +<p class="tent">SD5-XCU-ERN-149 is applied.</p> +<p class="tent">POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0190 [663] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_118_24" id="tag_20_118_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 877 is applied, adding the <b>-r</b> option.</p> +<p class="tent">Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/tabs.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/talk.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/talk.html b/bdd/talk.html @@ -0,0 +1,277 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>talk</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/tail.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/tee.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="talk" id="talk"></a> <a name="tag_20_119" id="tag_20_119"></a><!-- talk --> +<h4 class="mansect"><a name="tag_20_119_01" id="tag_20_119_01"></a>NAME</h4> +<blockquote>talk — talk to another user</blockquote> +<h4 class="mansect"><a name="tag_20_119_02" id="tag_20_119_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> talk</tt> <i>address</i> <b>[</b><i>terminal</i><b>]</b> <tt><img src="../images/opt-end.gif" alt= +"[Option End]" border="0"></tt></code></div> +</blockquote> +<h4 class="mansect"><a name="tag_20_119_03" id="tag_20_119_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>talk</i> utility is a two-way, screen-oriented communication program.</p> +<p>When first invoked, <i>talk</i> shall send a message similar to:</p> +<pre> +<tt>Message from <</tt><i>unspecified string</i><tt>> +talk: connection requested by </tt><i>your_address</i><tt> +talk: respond with: talk </tt><i>your_address</i><tt> +</tt></pre> +<p>to the specified <i>address</i>. At this point, the recipient of the message can reply by typing:</p> +<pre> +<tt>talk </tt><i>your_address</i><tt> +</tt></pre> +<p>Once communication is established, the two parties can type simultaneously, with their output displayed in separate regions of +the screen. Characters shall be processed as follows:</p> +<ul> +<li> +<p>Typing the <alert> character shall alert the recipient's terminal.</p> +</li> +<li> +<p>Typing <control>-L shall cause the sender's screen regions to be refreshed.</p> +</li> +<li> +<p>Typing the erase and kill characters shall affect the sender's terminal in the manner described by the <b>termios</b> interface +in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> .</p> +</li> +<li> +<p>Typing the interrupt or end-of-file characters shall terminate the local <i>talk</i> utility. Once the <i>talk</i> session has +been terminated on one side, the other side of the <i>talk</i> session shall be notified that the <i>talk</i> session has been +terminated and shall be able to do nothing except exit.</p> +</li> +<li> +<p>Typing characters from <i>LC_CTYPE</i> classifications <b>print</b> or <b>space</b> shall cause those characters to be sent to +the recipient's terminal.</p> +</li> +<li> +<p>When and only when the <a href="../utilities/stty.html"><i>stty</i></a> <b>iexten</b> local mode is enabled, the existence and +processing of additional special control characters and multi-byte or single-byte functions shall be implementation-defined.</p> +</li> +<li> +<p>Typing other non-printable characters shall cause implementation-defined sequences of printable characters to be sent to the +recipient's terminal.</p> +</li> +</ul> +<p>Permission to be a recipient of a <i>talk</i> message can be denied or granted by use of the <a href= +"../utilities/mesg.html"><i>mesg</i></a> utility. However, a user's privilege may further constrain the domain of accessibility of +other users' terminals. The <i>talk</i> utility shall fail when the user lacks appropriate privileges to perform the requested +action.</p> +<p>Certain block-mode terminals do not have all the capabilities necessary to support the simultaneous exchange of messages +required for <i>talk</i>. When this type of exchange cannot be supported on such terminals, the implementation may support an +exchange with reduced levels of simultaneous interaction or it may report an error describing the terminal-related deficiency.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_119_04" id="tag_20_119_04"></a>OPTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_119_05" id="tag_20_119_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>address</i></dt> +<dd>The recipient of the <i>talk</i> session. One form of <i>address</i> is the <<i>user name</i>>, as returned by the +<a href="../utilities/who.html"><i>who</i></a> utility. Other address formats and how they are handled are unspecified.</dd> +<dt><i>terminal</i></dt> +<dd>If the recipient is logged in more than once, the <i>terminal</i> argument can be used to indicate the appropriate terminal +name. If <i>terminal</i> is not specified, the <i>talk</i> message shall be displayed on one or more accessible terminals in use by +the recipient. The format of <i>terminal</i> shall be the same as that returned by the <a href= +"../utilities/who.html"><i>who</i></a> utility.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_119_06" id="tag_20_119_06"></a>STDIN</h4> +<blockquote> +<p>Characters read from standard input shall be copied to the recipient's terminal in an unspecified manner. If standard input is +not a terminal, talk shall write a diagnostic message and exit with a non-zero status.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_119_07" id="tag_20_119_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_119_08" id="tag_20_119_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>talk</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). If the recipient's locale does not use an <i>LC_CTYPE</i> +equivalent to the sender's, the results are undefined.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error and +informative messages written to standard output.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>TERM</i></dt> +<dd>Determine the name of the invoker's terminal type. If this variable is unset or null, an unspecified default terminal type +shall be used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_119_09" id="tag_20_119_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>When the <i>talk</i> utility receives a SIGINT signal, the utility shall terminate and exit with a zero status. It shall take +the standard action for all other signals.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_119_10" id="tag_20_119_10"></a>STDOUT</h4> +<blockquote> +<p>If standard output is a terminal, characters copied from the recipient's standard input may be written to standard output. +Standard output also may be used for diagnostic messages. If standard output is not a terminal, <i>talk</i> shall exit with a +non-zero status.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_119_11" id="tag_20_119_11"></a>STDERR</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_119_12" id="tag_20_119_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_119_13" id="tag_20_119_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_119_14" id="tag_20_119_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred or <i>talk</i> was invoked on a terminal incapable of supporting it.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_119_15" id="tag_20_119_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_119_16" id="tag_20_119_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Because the handling of non-printable, non-<space> characters is tied to the <a href= +"../utilities/stty.html"><i>stty</i></a> description of <b>iexten</b>, implementation extensions within the terminal driver can be +accessed. For example, some implementations provide line editing functions with certain control character sequences.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_119_17" id="tag_20_119_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_119_18" id="tag_20_119_18"></a>RATIONALE</h4> +<blockquote> +<p>The <a href="../utilities/write.html"><i>write</i></a> utility was included in this volume of POSIX.1-2024 since it can be +implemented on all terminal types. The <i>talk</i> utility, which cannot be implemented on certain terminals, was considered to be +a "better" communications interface. Both of these programs are in widespread use on historical implementations. Therefore, both +utilities have been specified.</p> +<p>All references to networking abilities (<i>talk</i>ing to a user on another system) were removed as being outside the scope of +this volume of POSIX.1-2024.</p> +<p>Historical BSD and System V versions of <i>talk</i> terminate both of the conversations when either user breaks out of the +session. This can lead to adverse consequences if a user unwittingly continues to enter text that is interpreted by the shell when +the other terminates the session. Therefore, the version of <i>talk</i> specified by this volume of POSIX.1-2024 requires both +users to terminate their end of the session explicitly.</p> +<p>Only messages sent to the terminal of the invoking user can be internationalized in any way:</p> +<ul> +<li> +<p>The original "Message from <<i>unspecified string</i>> ..." message sent to the terminal of the recipient cannot be +internationalized because the environment of the recipient is as yet inaccessible to the <i>talk</i> utility. The environment of +the invoking party is irrelevant.</p> +</li> +<li> +<p>Subsequent communication between the two parties cannot be internationalized because the two parties may specify different +languages in their environment (and non-portable characters cannot be mapped from one language to another).</p> +</li> +<li> +<p>Neither party can be required to communicate in a language other than C and/or the one specified by their environment because +unavailable terminal hardware support (for example, fonts) may be required.</p> +</li> +</ul> +<p>The text in the STDOUT section reflects the usage of the verb "display" in this section; some <i>talk</i> implementations +actually use standard output to write to the terminal, but this volume of POSIX.1-2024 does not require that to be the case.</p> +<p>The format of the terminal name is unspecified, but the descriptions of <a href="../utilities/ps.html"><i>ps</i></a>, +<i>talk</i>, <a href="../utilities/who.html"><i>who</i></a>, and <a href="../utilities/write.html"><i>write</i></a> require that +they all use or accept the same format.</p> +<p>The handling of non-printable characters is partially implementation-defined because the details of mapping them to printable +sequences is not needed by the user. Historical implementations, for security reasons, disallow the transmission of non-printable +characters that may send commands to the other terminal.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_119_19" id="tag_20_119_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_119_20" id="tag_20_119_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/mesg.html#"><i>mesg</i></a> , <a href="../utilities/stty.html#"><i>stty</i></a> , <a href= +"../utilities/who.html#"><i>who</i></a> , <a href="../utilities/write.html#tag_20_151"><i>write</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_119_21" id="tag_20_119_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_119_22" id="tag_20_119_22"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_119_23" id="tag_20_119_23"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/tail.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/tee.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/tee.html b/bdd/tee.html @@ -0,0 +1,218 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>tee</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/talk.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/test.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="tee" id="tee"></a> <a name="tag_20_120" id="tag_20_120"></a><!-- tee --> +<h4 class="mansect"><a name="tag_20_120_01" id="tag_20_120_01"></a>NAME</h4> +<blockquote>tee — duplicate standard input</blockquote> +<h4 class="mansect"><a name="tag_20_120_02" id="tag_20_120_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>tee</tt> <b>[</b><tt>-ai</tt><b>] [</b><i>file</i><tt>...</tt><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_120_03" id="tag_20_120_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>tee</i> utility shall copy standard input to standard output, making a copy in zero or more files. The <i>tee</i> utility +shall not buffer output.</p> +<p>If the <b>-a</b> option is not specified, output files shall be written (see <a href= +"../utilities/V3_chap01.html#tag_18_01_01_04"><i>1.1.1.4 File Read, Write, and Creation</i></a> ).</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_120_04" id="tag_20_120_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>tee</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-a</b></dt> +<dd>Append the output to the files.</dd> +<dt><b>-i</b></dt> +<dd>Ignore the SIGINT signal.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_120_05" id="tag_20_120_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of an output file. If a <i>file</i> operand is <tt>'-'</tt>, it shall refer to a file named <b>-</b>; +implementations shall not treat it as meaning standard output. Processing of at least 13 <i>file</i> operands shall be +supported.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_120_06" id="tag_20_120_06"></a>STDIN</h4> +<blockquote> +<p>The standard input can be of any type.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_120_07" id="tag_20_120_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_120_08" id="tag_20_120_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>tee</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_120_09" id="tag_20_120_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default, except that if the <b>-i</b> option was specified, SIGINT shall be ignored.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_120_10" id="tag_20_120_10"></a>STDOUT</h4> +<blockquote> +<p>The standard output shall be a copy of the standard input.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_120_11" id="tag_20_120_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_120_12" id="tag_20_120_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>If any <i>file</i> operands are specified, the standard input shall be copied to each named file.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_120_13" id="tag_20_120_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_120_14" id="tag_20_120_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>The standard input was successfully copied to all output files.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_120_15" id="tag_20_120_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>If a write to any successfully opened <i>file</i> operand fails, writes to other successfully opened <i>file</i> operands and +standard output shall continue, but the exit status shall be non-zero. Otherwise, the default actions specified in <a href= +"../utilities/V3_chap01.html#tag_18_04"><i>1.4 Utility Description Defaults</i></a> apply.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_120_16" id="tag_20_120_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The <i>tee</i> utility is usually used in a pipeline, to make a copy of the output of some utility.</p> +<p>The <i>file</i> operand is technically optional, but <i>tee</i> is no more useful than <a href= +"../utilities/cat.html"><i>cat</i></a> when none is specified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_120_17" id="tag_20_120_17"></a>EXAMPLES</h4> +<blockquote> +<p>Save an unsorted intermediate form of the data in a pipeline:</p> +<pre> +<tt>... | tee unsorted | sort > sorted +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_120_18" id="tag_20_120_18"></a>RATIONALE</h4> +<blockquote> +<p>The buffering requirement means that <i>tee</i> is not allowed to use ISO C standard fully buffered or line-buffered +writes. It does not mean that <i>tee</i> has to do 1-byte reads followed by 1-byte writes.</p> +<p>It should be noted that early versions of BSD ignore any invalid options and accept a single <tt>'-'</tt> as an alternative to +<b>-i</b>. They also print a message if unable to open a file:</p> +<pre> +<tt>"tee: cannot access %s\n", <</tt><i>pathname</i><tt>> +</tt></pre> +<p>Historical implementations ignore write errors. This is explicitly not permitted by this volume of POSIX.1-2024.</p> +<p>Some historical implementations use O_APPEND when providing append mode; others use the <a href= +"../functions/lseek.html"><i>lseek</i>()</a> function to seek to the end-of-file after opening the file without O_APPEND. This +volume of POSIX.1-2024 requires functionality equivalent to using O_APPEND; see <a href= +"../utilities/V3_chap01.html#tag_18_01_01_04"><i>1.1.1.4 File Read, Write, and Creation</i></a> .</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_120_19" id="tag_20_120_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a +<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require +implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_120_20" id="tag_20_120_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap01.html#tag_18"><i>1. Introduction</i></a> , <a href="../utilities/cat.html#"><i>cat</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/lseek.html#"><i>lseek</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_120_21" id="tag_20_120_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_120_22" id="tag_20_120_22"></a>Issue 6</h4> +<blockquote> +<p>IEEE PASC Interpretation 1003.2 #168 is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_120_23" id="tag_20_120_23"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #092 is applied.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_120_24" id="tag_20_120_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to disallow the creation of filenames containing any bytes that +have the encoded value of a <newline> character.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1494 is applied, inserting a missing closing parenthesis.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/talk.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/test.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/test.html b/bdd/test.html @@ -0,0 +1,584 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>test</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/tee.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/time.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="test" id="test"></a> <a name="tag_20_121" id="tag_20_121"></a><!-- test --> +<h4 class="mansect"><a name="tag_20_121_01" id="tag_20_121_01"></a>NAME</h4> +<blockquote>test — evaluate expression</blockquote> +<h4 class="mansect"><a name="tag_20_121_02" id="tag_20_121_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>test</tt> <b>[</b><i>expression</i><b>]</b> <tt><br> +<br> +[</tt> <b>[</b><i>expression</i><b>]</b> <tt>]<br></tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_121_03" id="tag_20_121_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>test</i> utility shall evaluate the <i>expression</i> and indicate the result of the evaluation by its exit status. An +exit status of zero indicates that the expression evaluated as true and an exit status of 1 indicates that the expression evaluated +as false.</p> +<p>In the second form of the utility, where the utility name used is <i>[</i> rather than <i>test</i>, the application shall ensure +that the closing square bracket is a separate argument. The <i>test</i> and <i>[</i> utilities may be implemented as a single +linked utility which examines the basename of the zeroth command line argument to determine whether to behave as the <i>test</i> or +<i>[</i> variant. Applications using the <i>exec</i> family of functions to execute these utilities shall ensure that the argument +passed in <i>arg0</i> or <i>argv</i>[0] is <tt>'['</tt> when executing the <i>[</i> utility and has a basename of <tt>"test"</tt> +when executing the <i>test</i> utility.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_121_04" id="tag_20_121_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>test</i> utility shall not recognize the <tt>"--"</tt> argument in the manner specified by Guideline 10 in XBD <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a> . In addition, when the utility name used is +<i>[</i> the utility does not conform to Guidelines 1 and 2.</p> +<p>No options shall be supported.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_121_05" id="tag_20_121_05"></a>OPERANDS</h4> +<blockquote> +<p>The application shall ensure that all operators and elements of primaries are presented as separate arguments to the <i>test</i> +utility.</p> +<p>The following primaries can be used to construct <i>expression</i>:</p> +<dl compact> +<dd></dd> +<dt><b>-b </b><i>pathname</i></dt> +<dd>True if <i>pathname</i> resolves to an existing directory entry for a block special file. False if <i>pathname</i> cannot be +resolved, or if <i>pathname</i> resolves to an existing directory entry for a file that is not a block special file.</dd> +<dt><b>-c </b><i>pathname</i></dt> +<dd>True if <i>pathname</i> resolves to an existing directory entry for a character special file. False if <i>pathname</i> cannot +be resolved, or if <i>pathname</i> resolves to an existing directory entry for a file that is not a character special file.</dd> +<dt><b>-d </b><i>pathname</i></dt> +<dd>True if <i>pathname</i> resolves to an existing directory entry for a directory. False if <i>pathname</i> cannot be resolved, +or if <i>pathname</i> resolves to an existing directory entry for a file that is not a directory.</dd> +<dt><b>-e </b><i>pathname</i></dt> +<dd>True if <i>pathname</i> resolves to an existing directory entry. False if <i>pathname</i> cannot be resolved.</dd> +<dt><i>pathname1</i><b> -ef </b><i>pathname2</i></dt> +<dd><br> +True if <i>pathname1</i> and <i>pathname2</i> resolve to existing directory entries for the same file; otherwise, false.</dd> +<dt><b>-f </b><i>pathname</i></dt> +<dd>True if <i>pathname</i> resolves to an existing directory entry for a regular file. False if <i>pathname</i> cannot be +resolved, or if <i>pathname</i> resolves to an existing directory entry for a file that is not a regular file.</dd> +<dt><b>-g </b><i>pathname</i></dt> +<dd>True if <i>pathname</i> resolves to an existing directory entry for a file that has its set-group-ID flag set. False if +<i>pathname</i> cannot be resolved, or if <i>pathname</i> resolves to an existing directory entry for a file that does not have its +set-group-ID flag set.</dd> +<dt><b>-h </b><i>pathname</i></dt> +<dd>True if <i>pathname</i> resolves to an existing directory entry for a symbolic link. False if <i>pathname</i> cannot be +resolved, or if <i>pathname</i> resolves to an existing directory entry for a file that is not a symbolic link. If the final +component of <i>pathname</i> is a symbolic link, that symbolic link is not followed.</dd> +<dt><b>-L </b><i>pathname</i></dt> +<dd>True if <i>pathname</i> resolves to an existing directory entry for a symbolic link. False if <i>pathname</i> cannot be +resolved, or if <i>pathname</i> resolves to an existing directory entry for a file that is not a symbolic link. If the final +component of <i>pathname</i> is a symbolic link, that symbolic link is not followed.</dd> +<dt><b>-n </b><i>string</i></dt> +<dd>True if the length of <i>string</i> is non-zero; otherwise, false.</dd> +<dt><i>pathname1</i><b> -nt </b><i>pathname2</i></dt> +<dd><br> +True if <i>pathname1</i> resolves to an existing file and <i>pathname2</i> cannot be resolved, or if both resolve to existing files +and <i>pathname1</i> is newer than <i>pathname2</i> according to their last data modification timestamps; otherwise, false.</dd> +<dt><i>pathname1</i><b> -ot </b><i>pathname2</i></dt> +<dd><br> +True if <i>pathname2</i> resolves to an existing file and <i>pathname1</i> cannot be resolved, or if both resolve to existing files +and <i>pathname1</i> is older than <i>pathname2</i> according to their last data modification timestamps; otherwise, false.</dd> +<dt><b>-p </b><i>pathname</i></dt> +<dd>True if <i>pathname</i> resolves to an existing directory entry for a FIFO. False if <i>pathname</i> cannot be resolved, or if +<i>pathname</i> resolves to an existing directory entry for a file that is not a FIFO.</dd> +<dt><b>-r </b><i>pathname</i></dt> +<dd>True if <i>pathname</i> resolves to an existing directory entry for a file for which permission to read from the file is +granted, as defined in <a href="../utilities/V3_chap01.html#tag_18_01_01_04"><i>1.1.1.4 File Read, Write, and Creation</i></a> . +False if <i>pathname</i> cannot be resolved, or if <i>pathname</i> resolves to an existing directory entry for a file for which +permission to read from the file is not granted.</dd> +<dt><b>-S </b><i>pathname</i></dt> +<dd>True if <i>pathname</i> resolves to an existing directory entry for a socket. False if <i>pathname</i> cannot be resolved, or +if <i>pathname</i> resolves to an existing directory entry for a file that is not a socket.</dd> +<dt><b>-s </b><i>pathname</i></dt> +<dd>True if <i>pathname</i> resolves to an existing directory entry for a file that has a size greater than zero. False if +<i>pathname</i> cannot be resolved, or if <i>pathname</i> resolves to an existing directory entry for a file that does not have a +size greater than zero.</dd> +<dt><b>-t </b><i>file_descriptor</i></dt> +<dd><br> +True if file descriptor number <i>file_descriptor</i> is open and is associated with a terminal. False if <i>file_descriptor</i> is +not a valid file descriptor number, or if file descriptor number <i>file_descriptor</i> is not open, or if it is open but is not +associated with a terminal.</dd> +<dt><b>-u </b><i>pathname</i></dt> +<dd>True if <i>pathname</i> resolves to an existing directory entry for a file that has its set-user-ID flag set. False if +<i>pathname</i> cannot be resolved, or if <i>pathname</i> resolves to an existing directory entry for a file that does not have its +set-user-ID flag set.</dd> +<dt><b>-w </b><i>pathname</i></dt> +<dd>True if <i>pathname</i> resolves to an existing directory entry for a file for which permission to write to the file is +granted, as defined in <a href="../utilities/V3_chap01.html#tag_18_01_01_04"><i>1.1.1.4 File Read, Write, and Creation</i></a> . +False if <i>pathname</i> cannot be resolved, or if <i>pathname</i> resolves to an existing directory entry for a file for which +permission to write to the file is not granted.</dd> +<dt><b>-x </b><i>pathname</i></dt> +<dd>True if <i>pathname</i> resolves to an existing directory entry for a file for which permission to execute the file (or search +it, if it is a directory) is granted, as defined in <a href="../utilities/V3_chap01.html#tag_18_01_01_04"><i>1.1.1.4 File Read, +Write, and Creation</i></a> . False if <i>pathname</i> cannot be resolved, or if <i>pathname</i> resolves to an existing directory +entry for a file for which permission to execute (or search) the file is not granted.</dd> +<dt><b>-z </b><i>string</i></dt> +<dd>True if the length of string <i>string</i> is zero; otherwise, false.</dd> +<dt><i>string</i></dt> +<dd>True if the string <i>string</i> is not the null string; otherwise, false.</dd> +<dt><i>s1</i><b> = </b><i>s2</i></dt> +<dd>True if the strings <i>s1</i> and <i>s2</i> are identical; otherwise, false.</dd> +<dt><i>s1</i><b> != </b><i>s2</i></dt> +<dd>True if the strings <i>s1</i> and <i>s2</i> are not identical; otherwise, false.</dd> +<dt><i>s1</i><b> > </b><i>s2</i></dt> +<dd>True if <i>s1</i> collates after <i>s2</i> in the current locale; otherwise, false.</dd> +<dt><i>s1</i><b> < </b><i>s2</i></dt> +<dd>True if <i>s1</i> collates before <i>s2</i> in the current locale; otherwise, false.</dd> +<dt><i>n1</i><b> -eq </b><i>n2</i></dt> +<dd>True if the integers <i>n1</i> and <i>n2</i> are algebraically equal; otherwise, false.</dd> +<dt><i>n1</i><b> -ne </b><i>n2</i></dt> +<dd>True if the integers <i>n1</i> and <i>n2</i> are not algebraically equal; otherwise, false.</dd> +<dt><i>n1</i><b> -gt </b><i>n2</i></dt> +<dd>True if the integer <i>n1</i> is algebraically greater than the integer <i>n2</i>; otherwise, false.</dd> +<dt><i>n1</i><b> -ge </b><i>n2</i></dt> +<dd>True if the integer <i>n1</i> is algebraically greater than or equal to the integer <i>n2</i>; otherwise, false.</dd> +<dt><i>n1</i><b> -lt </b><i>n2</i></dt> +<dd>True if the integer <i>n1</i> is algebraically less than the integer <i>n2</i>; otherwise, false.</dd> +<dt><i>n1</i><b> -le </b><i>n2</i></dt> +<dd>True if the integer <i>n1</i> is algebraically less than or equal to the integer <i>n2</i>; otherwise, false.</dd> +</dl> +<p>With the exception of the <b>-h</b> <i>pathname</i> and <b>-L</b> <i>pathname</i> primaries, if a <i>pathname</i>, +<i>pathname1</i>, or <i>pathname2</i> argument is a symbolic link, <i>test</i> shall evaluate the expression by resolving the +symbolic link and using the file referenced by the link.</p> +<p>These primaries can be combined with the following operator:</p> +<dl compact> +<dd></dd> +<dt><b>! </b><i>expression</i></dt> +<dd>True if <i>expression</i> is false. False if <i>expression</i> is true.</dd> +</dl> +<p>The primaries with two elements of the form:</p> +<pre> +<tt>-</tt><i>primary_operator primary_operand</i><tt> +</tt></pre> +<p>are known as <i>unary primaries</i>. The primaries with three elements in either of the two forms:</p> +<pre> +<i>primary_operand </i><tt>-</tt><i>primary_operator primary_operand +<br> +primary_operand primary_operator primary_operand</i><tt> +</tt></pre> +<p>are known as <i>binary primaries</i>. Additional implementation-defined operators and <i>primary_operator</i>s may be provided +by implementations. They shall be of the form -<i>operator</i> where the first character of <i>operator</i> is not a digit.</p> +<p>The algorithm for determining the precedence of the operators and the return value that shall be generated is based on the +number of arguments presented to <i>test</i>. (However, when using the <tt>"[...]"</tt> form, the <right-square-bracket> +final argument shall not be counted in this algorithm.)</p> +<p>In the following list, $1, $2, $3, and $4 represent the arguments presented to <i>test</i>:</p> +<dl compact> +<dd></dd> +<dt>0 arguments:</dt> +<dd>Exit false (1).</dd> +<dt>1 argument:</dt> +<dd>Exit true (0) if $1 is not null; otherwise, exit false.</dd> +<dt>2 arguments:</dt> +<dd> +<ul> +<li> +<p>If $1 is <tt>'!'</tt>, exit true if $2 is null, false if $2 is not null.</p> +</li> +<li> +<p>If $1 is a unary primary, exit true if the unary test is true, false if the unary test is false.</p> +</li> +<li> +<p>Otherwise, produce unspecified results.</p> +</li> +</ul> +</dd> +<dt>3 arguments:</dt> +<dd> +<ul> +<li> +<p>If $2 is a binary primary, perform the binary test of $1 and $3.</p> +</li> +<li> +<p>If $1 is <tt>'!'</tt>, negate the two-argument test of $2 and $3.</p> +</li> +<li> +<p>Otherwise, produce unspecified results.</p> +</li> +</ul> +</dd> +<dt>4 arguments:</dt> +<dd> +<ul> +<li> +<p>If $1 is <tt>'!'</tt>, negate the three-argument test of $2, $3, and $4.</p> +</li> +<li> +<p>Otherwise, the results are unspecified.</p> +</li> +</ul> +</dd> +<dt>>4 arguments:</dt> +<dd>The results are unspecified.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_121_06" id="tag_20_121_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_121_07" id="tag_20_121_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_121_08" id="tag_20_121_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>test</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_COLLATE</i></dt> +<dd><br> +Determine the locale for the behavior of the <b>></b> and <b><</b> string comparison operators.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_121_09" id="tag_20_121_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_121_10" id="tag_20_121_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_121_11" id="tag_20_121_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_121_12" id="tag_20_121_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_121_13" id="tag_20_121_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_121_14" id="tag_20_121_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd><i>expression</i> evaluated to true.</dd> +<dt> 1</dt> +<dd><i>expression</i> evaluated to false or <i>expression</i> was missing.</dd> +<dt>>1</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_121_15" id="tag_20_121_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_121_16" id="tag_20_121_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Since <tt>'>'</tt> and <tt>'<'</tt> are operators in the shell language, applications need to quote them when passing them +as arguments to <i>test</i> from a shell.</p> +<p>The <b>-a</b> and <b>-o</b> binary primaries and the <tt>'('</tt> and <tt>')'</tt> operators have been removed. (Many +expressions using them were ambiguously defined by the grammar depending on the specific expressions being evaluated.) Scripts +using these expressions should be converted to the forms given below. Even though many implementations will continue to support +these forms, scripts should be extremely careful when dealing with user-supplied input that could be confused with these and other +primaries and operators. Unless the application developer knows all the cases that produce input to the script, invocations +like:</p> +<pre> +<tt>test "$1" -a "$2" +</tt></pre> +<p>should be written as:</p> +<pre> +<tt>test "$1" && test "$2" +</tt></pre> +<p>to avoid problems if a user supplied values such as $1 set to <tt>'!'</tt> and $2 set to the null string. That is, replace:</p> +<pre> +<tt>test expr1 -a expr2 +</tt></pre> +<p>with:</p> +<pre> +<tt>test expr1 && test expr2 +</tt></pre> +<p>and replace:</p> +<pre> +<tt>test expr1 -o expr2 +</tt></pre> +<p>with:</p> +<pre> +<tt>test expr1 || test expr2 +</tt></pre> +<p>but note that, in <i>test</i>, <b>-a</b> was specified as having higher precedence than <b>-o</b> while <tt>"&&"</tt> +and <tt>"||"</tt> have equal precedence in the shell.</p> +<p>Parentheses or braces can be used in the shell command language to effect grouping.</p> +<p>The two commands:</p> +<pre> +<tt>test "$1" +test ! "$1" +</tt></pre> +<p>could not be used reliably on some historical systems. Unexpected results would occur if such a <i>string</i> expression were +used and $1 expanded to <tt>'!'</tt>, <tt>'('</tt>, or a known unary primary. Better constructs are:</p> +<pre> +<tt>test -n "$1" +test -z "$1" +</tt></pre> +respectively. +<p>Historical systems have also been unreliable given the common construct:</p> +<pre> +<tt>test "$response" = "expected string" +</tt></pre> +<p>One of the following is a more reliable form:</p> +<pre> +<tt>test "X$response" = "Xexpected string" +test "expected string" = "$response" +</tt></pre> +<p>Note that the second form assumes that <i>expected string</i> could not be confused with any unary primary. If <i>expected +string</i> starts with <tt>'-'</tt>, <tt>'('</tt>, <tt>'!'</tt>, or even <tt>'='</tt>, the first form should be used instead. Using +the preceding rules, any of the three comparison forms is reliable, given any input. (However, note that the strings are quoted in +all cases.)</p> +<p>Historically, the string comparison binary primaries, <tt>'='</tt> and <tt>"!="</tt>, had a higher precedence than any unary +primary in the greater than 4 argument case, and consequently unexpected results could occur if arguments were not properly +prepared. For example, in:</p> +<pre> +<tt>test -d "$1" -o -d "$2" +</tt></pre> +<p>If $1 evaluates to a possible directory name of <tt>'='</tt>, the first three arguments are considered a string comparison, +which causes a syntax error when the second <b>-d</b> is encountered. The following form prevents this:</p> +<pre> +<tt>test -d "$1" || test -d "$2" +</tt></pre> +<p>Also in the greater than 4 argument case:</p> +<pre> +<tt>test "$1" = "bat" -a "$2" = "ball" +</tt></pre> +<p>syntax errors would occur if $1 evaluates to <tt>'('</tt> or <tt>'!'</tt>. One of the following forms prevents this; the second +is preferred:</p> +<pre> +<tt>test "$1" = "bat" && test "$2" = "ball" +test "X$1" = "Xbat" && test "X$2" = "Xball" +</tt></pre> +<p>Note that none of the following examples are permitted by the syntax described:</p> +<pre> +<tt>[-f file] +[-f file ] +[ -f file] +[ -f file +test -f file ] +</tt></pre> +<p>In the first two cases, if a utility named <i>[-f</i> exists, that utility would be invoked, and not <i>test</i>. In the +remaining cases, the brackets are mismatched, and the behavior is unspecified. However:</p> +<pre> +<tt>test ! ] +</tt></pre> +<p>does have a defined meaning, and must exit with status 1. Similarly:</p> +<pre> +<tt>test ] +</tt></pre> +<p>must exit with status 0.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_121_17" id="tag_20_121_17"></a>EXAMPLES</h4> +<blockquote> +<ol> +<li> +<p>Exit if there are not two or three arguments (two variations):</p> +<pre> +<tt>if [ $# -ne 2 ] && [ $# -ne 3 ]; then exit 1; fi +if [ $# -lt 2 ] || [ $# -gt 3 ]; then exit 1; fi +</tt></pre></li> +<li> +<p>Perform a <a href="../utilities/mkdir.html"><i>mkdir</i></a> if a directory does not exist:</p> +<pre> +<tt>test ! -d tempdir && mkdir tempdir +</tt></pre></li> +<li> +<p>Wait for a file to become non-readable:</p> +<pre> +<tt>while test -r thefile +do + sleep 30 +done +echo '"thefile" is no longer readable' +</tt></pre></li> +<li> +<p>Perform a command if the argument is one of three strings (two variations):</p> +<pre> +<tt>if [ "$1" = "pear" ] || [ "$1" = "grape" ] || [ "$1" = "apple" ] +then + </tt><i>command</i><tt> +fi +<br> +case "$1" in + pear|grape|apple) </tt><i>command</i><tt> ;; +esac +</tt></pre></li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_121_18" id="tag_20_121_18"></a>RATIONALE</h4> +<blockquote> +<p>The KornShell-derived conditional command (double bracket <b>[[]]</b>) was removed from the shell command language description +in an early proposal. Objections were raised that the real problem is misuse of the <i>test</i> command (<b>[</b>), and putting it +into the shell is the wrong way to fix the problem. Instead, proper documentation and a new shell reserved word (<b>!</b>) are +sufficient. A later proposal to add <b>[[]]</b> in Issue 8 was also rejected because existing implementations of it were found to +be error-prone in a similar way to historical versions of <i>test</i>, and there was also too much variation in behavior between +shells that support it.</p> +<p>Tests that require multiple <i>test</i> operations can be done at the shell level using individual invocations of the +<i>test</i> command and shell logicals, rather than using the error-prone historical <b>-a</b> and <b>-o</b> operators of +<i>test</i>.</p> +<p>The BSD and System V versions of <b>-f</b> were not the same. The BSD definition was:</p> +<dl compact> +<dd></dd> +<dt><b>-f </b><i>file</i></dt> +<dd>True if <i>file</i> exists and is not a directory.</dd> +</dl> +<p>The SVID version (true if the file exists and is a regular file) was chosen for this volume of POSIX.1-2024 because its use is +consistent with the <b>-b</b>, <b>-c</b>, <b>-d</b>, and <b>-p</b> operands (<i>file</i> exists and is a specific file type).</p> +<p>The <b>-e</b> primary, possessing similar functionality to that provided by the C shell, was added because it provides the only +way for a shell script to find out if a file exists without trying to open the file. Since implementations are allowed to add +additional file types, a portable script cannot use:</p> +<pre> +<tt>test -b foo || test -c foo || test -d foo || test -f foo || test -p foo +</tt></pre> +<p>to find out if <b>foo</b> is an existing file. On historical BSD systems, the existence of a file could be determined by:</p> +<pre> +<tt>test -f foo || test -d foo +</tt></pre> +<p>but there was no easy way to determine that an existing file was a regular file. An early proposal used the KornShell <b>-a</b> +primary (with the same meaning), but this was changed to <b>-e</b> because there were concerns about the high probability of humans +confusing the <b>-a</b> primary with the historical <b>-a</b> binary operator.</p> +<p>The following options were not included in this volume of POSIX.1-2024, although they are provided by some implementations. +These operands should not be used by new implementations for other purposes:</p> +<dl compact> +<dd></dd> +<dt><b>-k </b><i>file</i></dt> +<dd>True if <i>file</i> exists and its sticky bit is set.</dd> +<dt><b>-C </b><i>file</i></dt> +<dd>True if <i>file</i> is a contiguous file.</dd> +<dt><b>-V </b><i>file</i></dt> +<dd>True if <i>file</i> is a version file.</dd> +</dl> +<p>The following option was not included because it was undocumented in most implementations, has been removed from some +implementations (including System V), and the functionality is provided by the shell (see <a href= +"../utilities/V3_chap02.html#tag_19_06_02"><i>2.6.2 Parameter Expansion</i></a> .</p> +<dl compact> +<dd></dd> +<dt><b>-l </b><i>string</i></dt> +<dd>The length of the string <i>string</i>.</dd> +</dl> +<p>The <b>-b</b>, <b>-c</b>, <b>-g</b>, <b>-p</b>, <b>-u</b>, and <b>-x</b> operands are derived from the SVID; historical BSD does +not provide them. The <b>-k</b> operand is derived from System V; historical BSD does not provide it.</p> +<p>On historical BSD systems, <i>test</i> <b>-w</b> <i>directory</i> always returned false because <i>test</i> tried to open the +directory for writing, which always fails.</p> +<p>Some additional primaries newly invented or from the KornShell appeared in an early proposal as part of the conditional command +(<b>[[]]</b>): <i>s1</i> <b>></b> <i>s2</i>, <i>s1</i> <b><</b> <i>s2</i>, <i>f1</i> <b>-nt</b> <i>f2</i>, <i>f1</i> +<b>-ot</b> <i>f2</i>, and <i>f1</i> <b>-ef</b> <i>f2</i>. They were not carried forward into the <i>test</i> utility when the +conditional command was removed from the shell because they had not been included in the <i>test</i> utility built into historical +implementations of the <a href="../utilities/sh.html"><i>sh</i></a> utility. However, they were later added to this standard once +support for them became widespread.</p> +<p>The <b>-t</b> <i>file_descriptor</i> primary is shown with a mandatory argument because the grammar is ambiguous if it can be +omitted. Historical implementations have allowed it to be omitted, providing a default of 1.</p> +<p>It is noted that <tt>'['</tt> is not part of the portable filename character set; however, since it is required to be encoded by +a single byte, and is part of the portable character set, the name of this utility forms a character string across all supported +locales.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_121_19" id="tag_20_121_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_121_20" id="tag_20_121_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap01.html#tag_18_01_01_04"><i>1.1.1.4 File Read, Write, and Creation</i></a> , <a href= +"../utilities/find.html#"><i>find</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_121_21" id="tag_20_121_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_121_22" id="tag_20_121_22"></a>Issue 5</h4> +<blockquote> +<p>The FUTURE DIRECTIONS section is added.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_121_23" id="tag_20_121_23"></a>Issue 6</h4> +<blockquote> +<p>The <b>-h</b> operand is added for symbolic links, and access permission requirements are clarified for the <b>-r</b>, +<b>-w</b>, and <b>-x</b> operands to align with the IEEE P1003.2b draft standard.</p> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +<p>The <b>-L</b> and <b>-S</b> operands are added for symbolic links and sockets.</p> +<p>IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/38 is applied, adding XSI margin marking and shading to a line +in the OPERANDS section referring to the use of parentheses as arguments to the <i>test</i> utility.</p> +<p>IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/30 is applied, rewording the existence primaries for the +<i>test</i> utility.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_121_24" id="tag_20_121_24"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #107 is applied.</p> +<p>POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0143 [291] is applied.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0191 [898], XCU/TC2-2008/0192 [730], and XCU/TC2-2008/0193 [898] are +applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_121_25" id="tag_20_121_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 375 is applied, adding the <i>pathname1</i><b> -ef </b><i>pathname2</i>, +<i>pathname1</i><b> -nt </b><i>pathname2</i>, <i>pathname1</i><b> -ot </b><i>pathname2</i>, +<i>s1</i><b> > </b><i>s2</i>, and <i>s1</i><b> < </b><i>s2</i> primaries.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1330 is applied, removing the obsolescent (and optional) <b>-a</b> and <b>-o</b> binary primaries, and +<tt>'('</tt> and <tt>')'</tt> operators.</p> +<p>Austin Group Defect 1348 is applied, removing "()" from "the <i>exec</i>() family of functions".</p> +<p>Austin Group Defect 1373 is applied, clarifying that when the utility name used is <i>[</i> the utility does not conform to +Guidelines 1 and 2.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/tee.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/time.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/time.html b/bdd/time.html @@ -0,0 +1,329 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>time</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/test.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/timeout.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="time" id="time"></a> <a name="tag_20_122" id="tag_20_122"></a><!-- time --> +<h4 class="mansect"><a name="tag_20_122_01" id="tag_20_122_01"></a>NAME</h4> +<blockquote>time — time a simple command</blockquote> +<h4 class="mansect"><a name="tag_20_122_02" id="tag_20_122_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>time</tt> <b>[</b><tt>-p</tt><b>]</b> <i>utility</i> <b>[</b><i>argument</i><tt>...</tt><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_122_03" id="tag_20_122_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>time</i> utility shall invoke the utility named by the <i>utility</i> operand with arguments supplied as the +<i>argument</i> operands and write a message to standard error that lists timing statistics for the utility. The message shall +include the following information:</p> +<ul> +<li> +<p>The elapsed (real) time between invocation of <i>utility</i> and its termination.</p> +</li> +<li> +<p>The User CPU time, equivalent to the sum of the <i>tms_utime</i> and <i>tms_cutime</i> fields returned by the <a href= +"../functions/times.html"><i>times</i>()</a> function defined in the System Interfaces volume of POSIX.1-2024 for the process in +which <i>utility</i> is executed.</p> +</li> +<li> +<p>The System CPU time, equivalent to the sum of the <i>tms_stime</i> and <i>tms_cstime</i> fields returned by the <a href= +"../functions/times.html"><i>times</i>()</a> function for the process in which <i>utility</i> is executed.</p> +</li> +</ul> +<p>The precision of the timing shall be no less than the granularity defined for the size of the clock tick unit on the system, but +the results shall be reported in terms of standard time units (for example, 0.02 seconds, 00:00:00.02, 1m33.75s, 365.21 seconds), +not numbers of clock ticks.</p> +<p>When <i>time</i> is used in any of the following circumstances, via a simple command for which the word <b>time</b> is the +command name (see <a href="../utilities/V3_chap02.html#tag_19_09_01_01"><i>2.9.1.1 Order of Processing</i></a> ), and none of the +characters in the word <b>time</b> is quoted, the results (including parsing of later words) are unspecified:</p> +<ul> +<li> +<p>The simple command for which the word <b>time</b> is the command name includes one or more redirections (see <a href= +"../utilities/V3_chap02.html#tag_19_07"><i>2.7 Redirection</i></a> ) or is (directly) part of a pipeline (see <a href= +"../utilities/V3_chap02.html#tag_19_09_02"><i>2.9.2 Pipelines</i></a> ).</p> +</li> +<li> +<p>The next word that follows <b>time</b> would, if the word <b>time</b> were not present, be recognized as a reserved word (see +<a href="../utilities/V3_chap02.html#tag_19_04"><i>2.4 Reserved Words</i></a> ) or a control operator (see XBD <a href= +"../basedefs/V1_chap03.html#tag_03_85"><i>3.85 Control Operator</i></a> ).</p> +</li> +</ul> +<p>Since these limitations only apply when <i>time</i> is executed via a simple command for which the word <b>time</b> is the +command name and none of the characters in the word <b>time</b> is quoted, they can be avoided by quoting all or part of the word +<b>time</b>, by arranging for the command name not to be <b>time</b> (for example, by having the command name be a word expansion), +or by executing <i>time</i> via another utility such as <a href="../utilities/command.html"><i>command</i></a> or <a href= +"../utilities/env.html"><i>env</i></a>.</p> +<p>The limitations on redirections and pipelines can also be overcome by embedding the simple command within a compound +command—most commonly a grouping command (see <a href="../utilities/V3_chap02.html#tag_19_09_04_01"><i>2.9.4.1 Grouping +Commands</i></a> )—and applying the redirections or piping to the compound command instead.</p> +<p>Note that in no circumstances where the results are specified is it possible to apply different redirections to the <i>time</i> +utility than are applied to the utility it invokes.</p> +<p>The following examples (where <i>a</i> and <i>b</i> are assumed to be the names of utilities found by searching <i>PATH )</i> +show unspecified usages:</p> +<pre> +<tt>time a arg1 arg2 | b # part of a pipeline +a | time -p b # part of a pipeline +time a >/dev/null # output redirection +</dev/null time a # input redirection +time while anything... # reserved word after time +time ( cmd ) # control operator after time +time; # control operator after time +time shift # special built-in utility +time -p cd / # intrinsic utility +</tt></pre> +<p>The following examples have specified results and can be used as alternatives for the first four of the above when the +<i>time</i> utility as specified here is intended to be invoked:</p> +<pre> +<tt>{ time a arg1 arg2; } | b +t=time; a | $t -p b +command time a >/dev/null +</dev/null \time a +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_122_04" id="tag_20_122_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>time</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following option shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-p</b></dt> +<dd>Write the timing output to standard error in the format shown in the STDERR section.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_122_05" id="tag_20_122_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>utility</i></dt> +<dd>The name of a utility that is to be invoked. If the <i>utility</i> operand names a special built-in utility (see <a href= +"../utilities/V3_chap02.html#tag_19_15"><i>2.15 Special Built-In Utilities</i></a> ), an intrinsic utility (see <a href= +"../utilities/V3_chap01.html#tag_18_07"><i>1.7 Intrinsic Utilities</i></a> ), or a function (see <a href= +"../utilities/V3_chap02.html#tag_19_09_05"><i>2.9.5 Function Definition Command</i></a> ), the results are unspecified.</dd> +<dt><i>argument</i></dt> +<dd>Any string to be supplied as an argument when invoking the utility named by the <i>utility</i> operand.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_122_06" id="tag_20_122_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_122_07" id="tag_20_122_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_122_08" id="tag_20_122_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>time</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic and informative messages written to +standard error.</dd> +<dt><i>LC_NUMERIC</i></dt> +<dd><br> +Determine the locale for numeric formatting.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>PATH</i></dt> +<dd>Determine the search path that shall be used to locate the utility to be invoked; see XBD <a href= +"../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> .</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_122_09" id="tag_20_122_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_122_10" id="tag_20_122_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_122_11" id="tag_20_122_11"></a>STDERR</h4> +<blockquote> +<p>If the <i>utility</i> utility is invoked, the standard error shall be used to write the timing statistics and may be used to +write a diagnostic message if the utility terminates abnormally; otherwise, the standard error shall be used to write diagnostic +messages and may also be used to write the timing statistics.</p> +<p>If <b>-p</b> is specified, the following format shall be used for the timing statistics in the POSIX locale:</p> +<pre> +<tt>"real %f\nuser %f\nsys %f\n", <</tt><i>real seconds</i><tt>>, <</tt><i>user seconds</i><tt>>, + <</tt><i>system seconds</i><tt>> +</tt></pre> +<p>where each floating-point number shall be expressed in seconds. The precision used may be less than the default six digits of +<tt>%f</tt>, but shall be sufficiently precise to accommodate the size of the clock tick on the system (for example, if there were +60 clock ticks per second, at least two digits shall follow the radix character). The number of digits following the radix +character shall be no less than one, even if this always results in a trailing zero. The implementation may append white space and +additional information following the format shown here. The implementation may also prepend a single empty line before the format +shown here.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_122_12" id="tag_20_122_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_122_13" id="tag_20_122_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_122_14" id="tag_20_122_14"></a>EXIT STATUS</h4> +<blockquote> +<p>If the <i>utility</i> utility is invoked, the exit status of <i>time</i> shall be the exit status of <i>utility</i>; otherwise, +the <i>time</i> utility shall exit with one of the following values:</p> +<dl compact> +<dd></dd> +<dt>1-125</dt> +<dd>An error occurred in the <i>time</i> utility.</dd> +<dt> 126</dt> +<dd>The utility specified by <i>utility</i> was found but could not be invoked.</dd> +<dt> 127</dt> +<dd>The utility specified by <i>utility</i> could not be found.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_122_15" id="tag_20_122_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_122_16" id="tag_20_122_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The <a href="../utilities/command.html"><i>command</i></a>, <a href="../utilities/env.html"><i>env</i></a>, <a href= +"../utilities/nice.html"><i>nice</i></a>, <a href="../utilities/nohup.html"><i>nohup</i></a>, <i>time</i>, <a href= +"../utilities/timeout.html"><i>timeout</i></a>, and <a href="../utilities/xargs.html"><i>xargs</i></a> utilities have been +specified to use exit code 127 if a utility to be invoked cannot be found, so that applications can distinguish "failure to find a +utility" from "invoked utility exited with an error indication". The value 127 was chosen because it is not commonly used for +other meanings; most utilities use small values for "normal error conditions" and the values above 128 can be confused with +termination due to receipt of a signal. The value 126 was chosen in a similar manner to indicate that the utility could be found, +but not invoked. Some scripts produce meaningful error messages differentiating the 126 and 127 cases. The distinction between exit +codes 126 and 127 is based on KornShell practice that uses 127 when all attempts to <i>exec</i> the utility fail with [ENOENT], and +uses 126 when any attempt to <i>exec</i> the utility fails for any other reason.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_122_17" id="tag_20_122_17"></a>EXAMPLES</h4> +<blockquote> +<p>It is frequently desirable to apply <i>time</i> to pipelines or lists of commands. This can be done by placing pipelines and +command lists in a single file; this file can then be invoked as a utility, and the <i>time</i> applies to everything in the +file.</p> +<p>Alternatively, the following command can be used to apply <i>time</i> to a complex command:</p> +<pre> +<tt>time sh -c -- '</tt><i>complex-command-line</i><tt>' +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_122_18" id="tag_20_122_18"></a>RATIONALE</h4> +<blockquote> +<p>When the <i>time</i> utility was originally proposed to be included in the ISO POSIX-2:1993 standard, questions were raised +about its suitability for inclusion on the grounds that it was not useful for conforming applications, specifically:</p> +<ul> +<li> +<p>The underlying CPU definitions from the System Interfaces volume of POSIX.1-2024 are vague, so the numeric output could not be +compared accurately between systems or even between invocations.</p> +</li> +<li> +<p>The creation of portable benchmark programs was outside the scope this volume of POSIX.1-2024.</p> +</li> +</ul> +<p>However, <i>time</i> does fit in the scope of user portability. Human judgement can be applied to the analysis of the output, +and it could be very useful in hands-on debugging of applications or in providing subjective measures of system performance. Hence +it has been included in this volume of POSIX.1-2024.</p> +<p>The default output format has been left unspecified because historical implementations differ greatly in their style of +depicting this numeric output. The <b>-p</b> option was invented to provide scripts with a common means of obtaining this +information.</p> +<p>In the KornShell, <i>time</i> is a shell reserved word that can be used to time an entire pipeline, rather than just a simple +command. The POSIX definition has been worded to allow this implementation. Consideration was given to invalidating this approach +because of the historical model from the C shell and System V shell. However, since the System V <i>time</i> utility historically +has not produced accurate results in pipeline timing (because the constituent processes are not all owned by the same parent +process, as allowed by POSIX), it did not seem worthwhile to break historical KornShell usage.</p> +<p>The term <i>utility</i> is used, rather than <i>command</i>, to highlight the fact that shell compound commands, pipelines, +special built-ins, and so on, cannot be used directly. However, <i>utility</i> includes user application programs and shell +scripts, not just the standard utilities.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_122_19" id="tag_20_122_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_122_20" id="tag_20_122_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19"><i>2. Shell Command Language</i></a> , <a href= +"../utilities/sh.html#"><i>sh</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/times.html#tag_17_629"><i>times</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_122_21" id="tag_20_122_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_122_22" id="tag_20_122_22"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_122_23" id="tag_20_122_23"></a>Issue 7</h4> +<blockquote> +<p>The <i>time</i> utility is moved from the User Portability Utilities option to the Base. User Portability Utilities is now an +option for interactive utilities.</p> +<p>SD5-XCU-ERN-115 is applied, updating the example in the DESCRIPTION.</p> +<p>POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0144 [266] is applied.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0194 [723] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_122_24" id="tag_20_122_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 267 is applied, allowing <b>time</b> to be a reserved word.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1530 is applied, changing "<tt>sh -c</tt>" to "<tt>sh -c --</tt>".</p> +<p>Austin Group Defect 1586 is applied, adding the <a href="../utilities/timeout.html"><i>timeout</i></a> utility.</p> +<p>Austin Group Defect 1594 is applied, changing the APPLICATION USAGE section.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/test.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/timeout.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/timeout.html b/bdd/timeout.html @@ -0,0 +1,319 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>timeout</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/time.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/touch.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="timeout" id="timeout"></a> <a name="tag_20_123" id="tag_20_123"></a><!-- timeout --> +<h4 class="mansect"><a name="tag_20_123_01" id="tag_20_123_01"></a>NAME</h4> +<blockquote>timeout — execute a utility with a time limit</blockquote> +<h4 class="mansect"><a name="tag_20_123_02" id="tag_20_123_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>timeout</tt> <b>[</b><tt>-fp</tt><b>] [</b><tt>-k</tt> <i>time</i><b>] [</b><tt>-s</tt> <i>signal_name</i><b>]</b> +<i>duration utility</i> <b>[</b><i>argument</i><tt>...</tt><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_123_03" id="tag_20_123_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>timeout</i> utility shall execute the utility named by the <i>utility</i> operand, with arguments supplied as the +<i>argument</i> operands (if any), in a child process. If the value of the <i>duration</i> operand is non-zero and the child +process has not terminated after the specified time period, <i>timeout</i> shall send the signal specified by the <b>-s</b> option, +or the SIGTERM signal if <b>-s</b> is not given.</p> +<p>If the <b>-f</b> option is specified, the signal shall be sent only to the child process. Otherwise, it is implementation +defined which one of the following methods is used to signal additional processes:</p> +<ul> +<li> +<p>The <i>timeout</i> utility ensures it is a process group leader before creating the child process which executes the utility, in +which case it shall send the signal to its process group.</p> +</li> +<li> +<p>The <i>timeout</i> utility arranges for any descendants of the child process that are orphaned to have their parent process +changed to the <i>timeout</i> utility, in which case the signal shall be sent to the child process and all of its descendants.</p> +</li> +</ul> +<p>If the subsequent wait status of the child process shows that it was stopped by a signal, a SIGCONT signal shall also be sent in +the same manner as the first signal; otherwise, a SIGCONT signal may be sent in the same manner.</p> +<p>If the <b>-k</b> option is specified, and the child process created to execute the utility still has not terminated after the +time period specified by the <i>time</i> option-argument has elapsed since the first signal was sent, <i>timeout</i> shall send a +SIGKILL signal in the same manner as the first signal. If <i>timeout</i> receives a signal and propagates it to the child process +(see ASYNCHRONOUS EVENTS below), this shall be treated as the first signal.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_123_04" id="tag_20_123_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>timeout</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-f</b></dt> +<dd>Only time out the utility itself, not its descendants.</dd> +<dt><b>-k </b><i>time</i></dt> +<dd>Send a SIGKILL signal if the child process created to execute the utility has not terminated after the time period specified by +<i>time</i> has elapsed since the first signal was sent. The value of <i>time</i> shall be interpreted as specified for the +<i>duration</i> operand (see OPERANDS below).</dd> +<dt><b>-p</b></dt> +<dd>Always preserve (mimic) the wait status of the executed utility, even if the time limit was reached.</dd> +<dt><b>-s </b><i>signal_name</i></dt> +<dd><br> +Specify the signal to send when the time limit is reached, using one of the symbolic names defined in the <a href= +"../basedefs/signal.h.html"><i><signal.h></i></a> header. Values of <i>signal_name</i> shall be recognized in a +case-independent fashion, without the SIG prefix. By default, SIGTERM shall be sent.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_123_05" id="tag_20_123_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>duration</i></dt> +<dd>The maximum amount of time to allow the utility to run, specified as a decimal number with an optional decimal fraction and an +optional suffix, which can be:<br> +<dl compact> +<dd></dd> +<dt><b>s</b></dt> +<dd>seconds</dd> +<dt><b>m</b></dt> +<dd>minutes</dd> +<dt><b>h</b></dt> +<dd>hours</dd> +<dt><b>d</b></dt> +<dd>days</dd> +</dl> +<p>If a decimal fraction is present, the application shall ensure that it is separated from the units by a <period>. If no +suffix is present, the value shall specify seconds.</p> +<p>If the value is zero, <i>timeout</i> shall not enforce a time limit.</p> +</dd> +<dt><i>utility</i></dt> +<dd>The name of a utility that is to be executed. If the <i>utility</i> operand names any of the special built-in utilities in +<a href="../utilities/V3_chap02.html#tag_19_15"><i>2.15 Special Built-In Utilities</i></a> , the results are undefined.</dd> +<dt><i>argument</i></dt> +<dd>Any string to be supplied as an argument when executing the utility named by the <i>utility</i> operand.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_123_06" id="tag_20_123_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_123_07" id="tag_20_123_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_123_08" id="tag_20_123_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>timeout</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>PATH</i></dt> +<dd>Determine the search path that is used to locate the utility to be executed. See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_03"><i>8.3 Other Environment Variables</i></a> .</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_123_09" id="tag_20_123_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>The default behavior specified in <a href="../utilities/V3_chap01.html#tag_18_04"><i>1.4 Utility Description Defaults</i></a> +shall apply, except that:</p> +<ul> +<li> +<p>The <i>timeout</i> utility shall ignore SIGTTIN and SIGTTOU signals.</p> +</li> +<li> +<p>The <i>timeout</i> utility may alter the disposition of SIGALRM if the inherited disposition was for it to be ignored.</p> +</li> +<li> +<p>If the signal specified with the <b>-s</b> option, or any signal whose default action is to terminate the process, is delivered +to the <i>timeout</i> utility, then unless the signal is SIGKILL or SIGSTOP, the <i>timeout</i> utility shall immediately send the +same signal to the process or processes to which it would send a signal when the time limit is reached. If the delivered signal is +SIGALRM, <i>timeout</i> may behave as if the time limit had been reached instead of sending SIGALRM.</p> +</li> +<li> +<p>If the <b>-f</b> option is not specified, then if <i>timeout</i> sends a signal to its process group, it shall briefly change +the disposition of that signal to ignored while it sends the signal, so that it does not receive the signal itself.</p> +</li> +</ul> +<p>With the single exception of the signal specified with the <b>-s</b> option, or SIGTERM if <b>-s</b> is not used, all signal +dispositions inherited by the utility specified by the <i>utility</i> operand shall be the same as the disposition that +<i>timeout</i> inherited.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_123_10" id="tag_20_123_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_123_11" id="tag_20_123_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_123_12" id="tag_20_123_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_123_13" id="tag_20_123_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_123_14" id="tag_20_123_14"></a>EXIT STATUS</h4> +<blockquote> +<p>If the <b>-p</b> option is not specified and the time limit was reached:</p> +<ul> +<li> +<p>If the <b>-k</b> option was not specified or the utility terminated before the time period specified by the <i>time</i> +option-argument elapsed since the first signal was sent, the exit status shall be 124.</p> +</li> +<li> +<p>If the <b>-k</b> option was specified and the SIGKILL signal was sent, it is unspecified whether the exit status is 124 or the +behavior is as if the <b>-p</b> option was specified.</p> +</li> +</ul> +<p>Otherwise, if the executed utility terminated by exiting, the exit status of <i>timeout</i> shall be that of the utility; if the +utility was terminated by a signal, <i>timeout</i> shall terminate itself with the same signal while ensuring that a core image is +not created.</p> +<p>If an error occurs, the following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt>125</dt> +<dd>An error other than the two described below occurred.</dd> +<dt>126</dt> +<dd>The utility specified by <i>utility</i> was found but could not be executed.</dd> +<dt>127</dt> +<dd>The utility specified by <i>utility</i> could not be found.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_123_15" id="tag_20_123_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_123_16" id="tag_20_123_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Unlike the <a href="../utilities/kill.html"><i>kill</i></a> utility, the <b>-s</b> option of <i>timeout</i> is not required to +accept the symbolic name 0 to represent signal value zero.</p> +<p>When the value of <i>duration</i> is zero, <i>timeout</i> does not time out the utility, but it does still perform signal +propagation (including to descendants of the utility if <b>-f</b> is not specified).</p> +<p>Regardless of locale, the <period> character (the decimal-point character of the POSIX locale) is the decimal-point +character recognized in the <i>duration</i> operand and the <i>time</i> option-argument.</p> +<p>The <a href="../utilities/command.html"><i>command</i></a>, <a href="../utilities/env.html"><i>env</i></a>, <a href= +"../utilities/nice.html"><i>nice</i></a>, <a href="../utilities/nohup.html"><i>nohup</i></a>, <a href= +"../utilities/time.html"><i>time</i></a>, <i>timeout</i>, and <a href="../utilities/xargs.html"><i>xargs</i></a> utilities have +been specified to use exit code 127 if a utility to be invoked cannot be found, so that applications can distinguish "failure to +find a utility" from "invoked utility exited with an error indication". The value 127 was chosen because it is not commonly used +for other meanings; most utilities use small values for "normal error conditions" and the values above 128 can be confused with +termination due to receipt of a signal. The value 126 was chosen in a similar manner to indicate that the utility could be found, +but not invoked. Some scripts produce meaningful error messages differentiating the 126 and 127 cases. The distinction between exit +codes 126 and 127 is based on KornShell practice that uses 127 when all attempts to <i>exec</i> the utility fail with [ENOENT], and +uses 126 when any attempt to <i>exec</i> the utility fails for any other reason. The <i>timeout</i> utility extends these special +exit codes to 125 and 124, with the meanings described in EXIT STATUS. A <i>timeout</i> exit status below 124 can only result from +passing through the exit status of the executed utility.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_123_17" id="tag_20_123_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_123_18" id="tag_20_123_18"></a>RATIONALE</h4> +<blockquote> +<p>Some <i>timeout</i> implementations make themselves a process group leader (when <b>-f</b> is not used) in order to be able to +send signals to descendants of the child process. However, using this method means that any descendants which change their process +group do not receive the signal. To ensure all descendants receive the signal, some implementations instead make use of a feature +whereby descendants that are orphaned have their parent process changed to the <i>timeout</i> utility—that is, <i>timeout</i> +becomes their "reaper"—together with the ability of a reaper to send a signal to all of its descendants.</p> +<p>Some historical <i>timeout</i> implementations exited with status 128+<i>signal_number</i> when the child process was terminated +by a signal before the time limit was reached (or when <b>-p</b> was used). This is reasonable when <i>timeout</i> is invoked from +a shell which sets $? to 128+<i>signal_number</i>, but not all shells do that. In particular, the KornShell sets $? to +256+<i>signal_number</i> and so an exit status of 128+<i>signal_number</i> from <i>timeout</i> would be misleading. In order to +avoid any possible ambiguity, this standard requires that <i>timeout</i> mimics the wait status of the child process by terminating +itself with the same signal. When it does this it needs to ensure that it does not create a core image, otherwise it could +overwrite one created by the invoked utility.</p> +<p>The <i>timeout</i> utility ignores SIGTTIN and SIGTTOU so that if the utility it executes reads from or writes to the +controlling terminal and this generates a SIGTTIN or SIGTTOU for the process group, <i>timeout</i> will not be stopped by the +signal and can still time out the utility.</p> +<p>Some historical <i>timeout</i> implementations always set the disposition for SIGTTIN and SIGTTOU in the child process to +default, even if these signals were inherited as ignored. This could result in processes being stopped unexpectedly. Likewise, they +did not ensure that for signals they caught, the disposition inherited by the executed utility was the same as the disposition that +was inherited by <i>timeout</i>. This meant that, for example, if <i>timeout</i> was used in a script that was run with <a href= +"../utilities/nohup.html"><i>nohup</i></a>, the utility executed by <i>timeout</i> would unexpectedly not be protected from SIGHUP. +This standard requires that all signal dispositions inherited by the utility specified by the <i>utility</i> operand are the same +as the disposition that <i>timeout</i> inherited, with the single exception of the signal that <i>timeout</i> sends when the time +limit is reached, which needs to be inherited as default in order for the timeout to take effect (without resorting to SIGKILL if +<b>-k</b> is specified).</p> +<p>Some historical <i>timeout</i> implementations only propagated a subset of the signals whose default action is to terminate the +process to the child process if one was delivered to the <i>timeout</i> utility. Propagating these signals is beneficial, as +otherwise termination of the <i>timeout</i> utility by a signal results in the utility it executed being left running indefinitely +(unless it also received the signal, for example a terminal-generated SIGINT). There is no reason to select a subset of these +signals to be propagated, therefore this standard requires them all to be propagated (except SIGKILL, which cannot). In the event +that a user wants to prevent the utility being timed out, sending <i>timeout</i> a SIGKILL can be used for this purpose.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_123_19" id="tag_20_123_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_123_20" id="tag_20_123_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/kill.html#tag_20_64"><i>kill</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a> , <a href= +"../basedefs/signal.h.html"><i><signal.h></i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_123_21" id="tag_20_123_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 8.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/time.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/touch.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/touch.html b/bdd/touch.html @@ -0,0 +1,451 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>touch</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/timeout.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/tput.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="touch" id="touch"></a> <a name="tag_20_124" id="tag_20_124"></a><!-- touch --> +<h4 class="mansect"><a name="tag_20_124_01" id="tag_20_124_01"></a>NAME</h4> +<blockquote>touch — change file access and modification times</blockquote> +<h4 class="mansect"><a name="tag_20_124_02" id="tag_20_124_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>touch</tt> <b>[</b><tt>-acm</tt><b>] [</b><tt>-r</tt> <i>ref_file</i><tt>|-t</tt> <i>time</i><tt>|-d</tt> +<i>date_time</i><b>]</b> <i>file</i><tt>...</tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_124_03" id="tag_20_124_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>touch</i> utility shall change the last data modification timestamps, the last data access timestamps, or both.</p> +<p>The time used can be specified by the <b>-t</b> <i>time</i> option-argument, the corresponding <i>time</i> fields of the file +referenced by the <b>-r</b> <i>ref_file</i> option-argument, or the <b>-d</b> <i>date_time</i> option-argument, as specified in the +following sections. If none of these are specified, <i>touch</i> shall use the current time.</p> +<p>For each <i>file</i> operand, <i>touch</i> shall perform actions equivalent to the following functions defined in the System +Interfaces volume of POSIX.1-2024:</p> +<ol> +<li> +<p>If <i>file</i> does not exist:</p> +<ol type="a"> +<li> +<p>The <a href="../functions/creat.html"><i>creat</i>()</a> function is called with the following arguments:</p> +<ul> +<li> +<p>The <i>file</i> operand is used as the <i>path</i> argument.</p> +</li> +<li> +<p>The value of the bitwise-inclusive OR of S_IRUSR, S_IWUSR, S_IRGRP, S_IWGRP, S_IROTH, and S_IWOTH is used as the <i>mode</i> +argument.</p> +</li> +</ul> +</li> +<li> +<p>The <a href="../functions/futimens.html"><i>futimens</i>()</a> function is called with the following arguments:</p> +<ul> +<li> +<p>The file descriptor opened in step 1a.</p> +</li> +<li> +<p>The access time and the modification time, set as described in the OPTIONS section, are used as the first and second elements of +the <i>times</i> array argument, respectively.</p> +</li> +</ul> +</li> +</ol> +</li> +<li> +<p>If <i>file</i> exists, the <a href="../functions/utimensat.html"><i>utimensat</i>()</a> function is called with the following +arguments:</p> +<ol type="a"> +<li> +<p>The AT_FDCWD special value is used as the <i>fd</i> argument.</p> +</li> +<li> +<p>The <i>file</i> operand is used as the <i>path</i> argument.</p> +</li> +<li> +<p>The access time and the modification time, set as described in the OPTIONS section, are used as the first and second elements of +the <i>times</i> array argument, respectively.</p> +</li> +<li> +<p>The <i>flag</i> argument is set to zero.</p> +</li> +</ol> +</li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_124_04" id="tag_20_124_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>touch</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-a</b></dt> +<dd>Change the access time of <i>file</i>. Do not change the modification time unless <b>-m</b> is also specified.</dd> +<dt><b>-c</b></dt> +<dd>Do not create a specified <i>file</i> if it does not exist. Do not write any diagnostic messages concerning this +condition.</dd> +<dt><b>-d </b><i>date_time</i></dt> +<dd>Use the specified <i>date_time</i> instead of the current time. The option-argument shall be a string of the form: +<pre> +<i>YYYY</i><tt>-</tt><i>MM</i><tt>-</tt><i>DD</i><tt>T</tt><i>hh</i><tt>:</tt><i>mm</i><tt>:</tt><i>SS</i><b>[</b><tt>.</tt><i>frac</i><b>][</b><i>tz</i><b>]</b><tt> +</tt></pre> +<p>or:</p> +<pre> +<i>YYYY</i><tt>-</tt><i>MM</i><tt>-</tt><i>DD</i><tt>T</tt><i>hh</i><tt>:</tt><i>mm</i><tt>:</tt><i>SS</i><b>[</b><tt>,</tt><i>frac</i><b>][</b><i>tz</i><b>]</b><tt> +</tt></pre> +<p>where:</p> +<ul> +<li> +<p><i>YYYY</i> are at least four decimal digits giving the year.</p> +</li> +<li> +<p><i>MM</i>, <i>DD</i>, <i>hh</i>, <i>mm</i>, and <i>SS</i> are as with <b>-t</b> <i>time</i>.</p> +</li> +<li> +<p><tt>T</tt> is the time designator, and can be replaced by a single <space>.</p> +</li> +<li> +<p><tt>[.</tt><i>frac</i><tt>]</tt> and <tt>[,</tt><i>frac</i><tt>]</tt> are either empty, or a <period> (<tt>'.'</tt>) or a +<comma> (<tt>','</tt>) respectively, followed by one or more decimal digits, specifying a fractional second.</p> +</li> +<li> +<p><tt>[</tt><i>tz</i><tt>]</tt> is either empty, signifying local time, or the letter <tt>'Z'</tt>, signifying UTC. If +<tt>[</tt><i>tz</i><tt>]</tt> is empty, the resulting time shall be affected by the value of the <i>TZ</i> environment +variable.</p> +</li> +</ul> +<p>If the resulting time precedes the Epoch, the behavior is implementation-defined. If the time cannot be represented as the +file's timestamp, <i>touch</i> shall exit immediately with an error status.</p> +</dd> +<dt><b>-m</b></dt> +<dd>Change the modification time of <i>file</i>. Do not change the access time unless <b>-a</b> is also specified.</dd> +<dt><b>-r </b><i>ref_file</i></dt> +<dd>Use the corresponding time of the file named by the pathname <i>ref_file</i> instead of the current time.</dd> +<dt><b>-t </b><i>time</i></dt> +<dd>Use the specified <i>time</i> instead of the current time. The option-argument shall be a decimal number of the form: +<pre> +<b>[[</b><i>CC</i><b>]</b><i>YY</i><b>]</b><i>MMDDhhmm</i><b>[</b><tt>.</tt><i>SS</i><b>]</b><tt> +</tt></pre> +<p>where each two digits represents the following:</p> +<dl compact> +<dd></dd> +<dt><i>MM</i></dt> +<dd>The month of the year [01,12].</dd> +<dt><i>DD</i></dt> +<dd>The day of the month [01,31].</dd> +<dt><i>hh</i></dt> +<dd>The hour of the day [00,23].</dd> +<dt><i>mm</i></dt> +<dd>The minute of the hour [00,59].</dd> +<dt><i>CC</i></dt> +<dd>The first two digits of the year (the century).</dd> +<dt><i>YY</i></dt> +<dd>The second two digits of the year.</dd> +<dt><i>SS</i></dt> +<dd>The second of the minute [00,60].</dd> +</dl> +<p>Both <i>CC</i> and <i>YY</i> shall be optional. If neither is given, the current year shall be assumed. If <i>YY</i> is +specified, but <i>CC</i> is not, <i>CC</i> shall be derived as follows:</p> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>If <i>YY</i> is:</b></p> +</th> +<th align="center"> +<p class="tent"><b><i>CC</i> becomes:</b></p> +</th> +</tr> +<tr valign="top"> +<td align="center"> +<p class="tent">[69,99]</p> +</td> +<td align="left"> +<p class="tent">19</p> +</td> +</tr> +<tr valign="top"> +<td align="center"> +<p class="tent">[00,68]</p> +</td> +<td align="left"> +<p class="tent">20</p> +</td> +</tr> +</table> +</center> +<basefont size="2"> +<dl> +<dt><b>Note:</b></dt> +<dd>It is expected that in a future version of this standard the default century inferred from a 2-digit year will change. (This +would apply to all commands accepting a 2-digit year as input.)</dd> +</dl> +<basefont size="3"> +<p class="tent">The resulting time shall be affected by the value of the <i>TZ</i> environment variable. If the resulting time +value precedes the Epoch, the behavior is implementation-defined. If the time is out of range for the file's timestamp, +<i>touch</i> shall exit immediately with an error status. The range of valid times past the Epoch is implementation-defined, but it +shall extend to at least the time 0 hours, 0 minutes, 0 seconds, January 1, 2038, Coordinated Universal Time. Some implementations +may not be able to represent dates beyond January 18, 2038, because they use <b>signed int</b> as a time holder.</p> +<p class="tent">The range for <i>SS</i> is [00,60] rather than [00,59] because of leap seconds. If <i>SS</i> is 60, and the +resulting time, as affected by the <i>TZ</i> environment variable, does not refer to a leap second, the resulting time shall be one +second after a time where <i>SS</i> is 59. If <i>SS</i> is not given a value, it is assumed to be zero.</p> +</dd> +</dl> +<p class="tent">If neither the <b>-a</b> nor <b>-m</b> options were specified, <i>touch</i> shall behave as if both the <b>-a</b> +and <b>-m</b> options were specified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_124_05" id="tag_20_124_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of a file whose times shall be modified.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_124_06" id="tag_20_124_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_124_07" id="tag_20_124_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_124_08" id="tag_20_124_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>touch</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>TZ</i></dt> +<dd>Determine the timezone to be used for interpreting the <i>time</i> option-argument. If <i>TZ</i> is unset or null, an +unspecified default timezone shall be used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_124_09" id="tag_20_124_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_124_10" id="tag_20_124_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_124_11" id="tag_20_124_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_124_12" id="tag_20_124_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_124_13" id="tag_20_124_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_124_14" id="tag_20_124_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>The utility executed successfully and all requested changes were made.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_124_15" id="tag_20_124_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_124_16" id="tag_20_124_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The interpretation of time is taken to be <i>seconds since the Epoch</i> (see XBD <a href= +"../basedefs/V1_chap04.html#tag_04_19"><i>4.19 Seconds Since the Epoch</i></a> ). It should be noted that implementations +conforming to the System Interfaces volume of POSIX.1-2024 do not take leap seconds into account when computing seconds since the +Epoch. When <i>SS</i>=60 is used, the resulting time always refers to 1 plus <i>seconds since the Epoch</i> for a time when +<i>SS</i>=59.</p> +<p class="tent">Although the <b>-t</b> <i>time</i> option-argument specifies values in 1969, the access time and modification time +fields are defined in terms of seconds since the Epoch (00:00:00 on 1 January 1970 UTC). Therefore, depending on the value of +<i>TZ</i> when <i>touch</i> is run, there is never more than a few valid hours in 1969 and there need not be any valid times in +1969.</p> +<p class="tent">If the <i>T</i> time designator is replaced by a <space> for the <b>-d</b> <i>date_time</i> option-argument, +the <space> must be quoted to prevent the shell from splitting the argument.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_124_17" id="tag_20_124_17"></a>EXAMPLES</h4> +<blockquote> +<p>Create or update a file called <b>dwc</b>; the resulting file has both the last data modification and last data access +timestamps set to November 12, 2007 at 10:15:30 local time:</p> +<pre> +<tt>touch -d 2007-11-12T10:15:30 dwc +</tt></pre> +<p class="tent">Create or update a file called <b>nick</b>; the resulting file has both the last data modification and last data +access timestamps set to November 12, 2007 at 10:15:30 UTC:</p> +<pre> +<tt>touch -d 2007-11-12T10:15:30Z nick +</tt></pre> +<p class="tent">Create or update a file called <b>gwc</b>; the resulting file has both the last data modification and last data +access timestamps set to November 12, 2007 at 10:15:30 local time with a fractional second timestamp of .002 seconds:</p> +<pre> +<tt>touch -d 2007-11-12T10:15:30,002 gwc +</tt></pre> +<p class="tent">Create or update a file called <b>ajosey</b>; the resulting file has both the last data modification and last data +access timestamps set to November 12, 2007 at 10:15:30 UTC with a fractional second timestamp of .002 seconds:</p> +<pre> +<tt>touch -d "2007-11-12 10:15:30.002Z" ajosey +</tt></pre> +<p class="tent">Create or update a file called <b>cathy</b>; the resulting file has both the last data modification and last data +access timestamps set to November 12, 2007 at 10:15:00 local time:</p> +<pre> +<tt>touch -t 200711121015 cathy +</tt></pre> +<p class="tent">Create or update a file called <b>drepper</b>; the resulting file has both the last data modification and last data +access timestamps set to November 12, 2007 at 10:15:30 local time:</p> +<pre> +<tt>touch -t 200711121015.30 drepper +</tt></pre> +<p class="tent">Create or update a file called <b>ebb9</b>; the resulting file has both the last data modification and last data +access timestamps set to November 12, 2007 at 10:15:30 local time:</p> +<pre> +<tt>touch -t 0711121015.30 ebb9 +</tt></pre> +<p class="tent">Create or update a file called <b>eggert</b>; the resulting file has the last data access timestamp set to the +corresponding time of the file named <b>mark</b> instead of the current time. If the file exists, the last data modification time +is not changed:</p> +<pre> +<tt>touch -a -r mark eggert +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_124_18" id="tag_20_124_18"></a>RATIONALE</h4> +<blockquote> +<p>The functionality of <i>touch</i> is described almost entirely through references to functions in the System Interfaces volume +of POSIX.1-2024. In this way, there is no duplication of effort required for describing such side-effects as the relationship of +user IDs to the user database, permissions, and so on.</p> +<p class="tent">There are some significant differences between the <i>touch</i> utility in this volume of POSIX.1-2024 and those in +System V and BSD systems. They are upwards-compatible for historical applications from both implementations:</p> +<ol> +<li class="tent">In System V, an ambiguity exists when a pathname that is a decimal number leads the operands; it is treated as a +time value. In BSD, no <i>time</i> value is allowed; files may only be <i>touch</i>ed to the current time. The <b>-t</b> +<i>time</i> construct solves these problems for future conforming applications (note that the <b>-t</b> option is not historical +practice).</li> +<li class="tent">The inclusion of the century digits, <i>CC</i>, is also new. Note that a ten-digit <i>time</i> value is treated as +if <i>YY</i>, and not <i>CC</i>, were specified. The caveat about the range of dates following the Epoch was included as +recognition that some implementations are not able to represent dates beyond 18 January 2038 because they use <b>signed int</b> as +a time holder.</li> +</ol> +<p class="tent">The <b>-r</b> option was added because several comments requested this capability. This option was named <b>-f</b> +in an early proposal, but was changed because the <b>-f</b> option is used in the BSD version of <i>touch</i> with a different +meaning.</p> +<p class="tent">At least one historical implementation of <i>touch</i> incremented the exit code if <b>-c</b> was specified and the +file did not exist. This volume of POSIX.1-2024 requires exit status zero if no errors occur.</p> +<p class="tent">In previous version of the standard, if at least two operands are specified, and the first operand is an eight or +ten-digit decimal integer, the first operand was assumed to be a <i>date_time</i> operand. This usage was removed in this version +of the standard since it had been marked obsolescent previously.</p> +<p class="tent">The <b>-d</b> <i>date_time</i> format is an ISO 8601:2019 standard complete representation of date and time +extended format with an optional decimal point or <comma> followed by a string of digits following the seconds portion to +specify fractions of a second. It is not necessary to recognize <tt>"[+/-]hh:mm"</tt> and <tt>"[+/-]hh"</tt> to specify timezones +other than local time and UTC. The <i>T</i> time designator in the ISO 8601:2019 standard extended format may be replaced by +<space>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_124_19" id="tag_20_124_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a +<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require +implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_124_20" id="tag_20_124_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/date.html#"><i>date</i></a></p> +<p class="tent">XBD <a href="../basedefs/V1_chap04.html#tag_04_19"><i>4.19 Seconds Since the Epoch</i></a> , <a href= +"../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 +Utility Syntax Guidelines</i></a> , <a href="../basedefs/sys_stat.h.html"><i><sys/stat.h></i></a></p> +<p class="tent">XSH <a href="../functions/creat.html#"><i>creat</i></a> , <a href="../functions/futimens.html#"><i>futimens</i></a> +, <a href="../functions/time.html#tag_17_625"><i>time</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_124_21" id="tag_20_124_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_124_22" id="tag_20_124_22"></a>Issue 6</h4> +<blockquote> +<p>The obsolescent <i>date_time</i> operand is removed.</p> +<p class="tent">The Open Group Corrigendum U027/1 is applied. This extends the range of valid time past the Epoch to at least the +time 0 hours, 0 minutes, 0 seconds, January 1, 2038, Coordinated Universal Time. This is a new requirement on POSIX +implementations.</p> +<p class="tent">The range for seconds is changed from [00,61] to [00,60] to align with the ISO/IEC 9899:1999 standard, and to +allow for positive leap seconds.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_124_23" id="tag_20_124_23"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #118 is applied.</p> +<p class="tent">Austin Group Interpretation 1003.1-2001 #193 is applied, adding support for subsecond timestamps.</p> +<p class="tent">SD5-XCU-ERN-45 is applied, adding a new paragraph to the RATIONALE.</p> +<p class="tent">SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p class="tent">SD5-XCU-ERN-110 is applied, updating the OPTIONS section.</p> +<p class="tent">Changes are made related to support for finegrained timestamps.</p> +<p class="tent">POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0195 [474] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_124_24" id="tag_20_124_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to disallow the creation of filenames containing any bytes that +have the encoded value of a <newline> character.</p> +<p class="tent">Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/timeout.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/tput.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/tput.html b/bdd/tput.html @@ -0,0 +1,247 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>tput</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/touch.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/tr.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="tput" id="tput"></a> <a name="tag_20_125" id="tag_20_125"></a><!-- tput --> +<h4 class="mansect"><a name="tag_20_125_01" id="tag_20_125_01"></a>NAME</h4> +<blockquote>tput — change terminal characteristics</blockquote> +<h4 class="mansect"><a name="tag_20_125_02" id="tag_20_125_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>tput</tt> <b>[</b><tt>-T</tt> <i>type</i><b>]</b> <i>operand</i><tt>...</tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_125_03" id="tag_20_125_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>tput</i> utility shall display terminal-dependent information. The manner in which this information is retrieved is +unspecified. The information displayed shall clear the terminal screen, initialize the user's terminal, or reset the user's +terminal, depending on the operand given. The exact consequences of displaying this information are unspecified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_125_04" id="tag_20_125_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>tput</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following option shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-T </b><i>type</i></dt> +<dd>Indicate the type of terminal. If this option is not supplied and the <i>TERM</i> variable is unset or null, an unspecified +default terminal type shall be used. The setting of <i>type</i> shall take precedence over the value in <i>TERM .</i></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_125_05" id="tag_20_125_05"></a>OPERANDS</h4> +<blockquote> +<p>The following strings shall be supported as operands by the implementation in the POSIX locale:</p> +<dl compact> +<dd></dd> +<dt><b>clear</b></dt> +<dd>Display the clear-screen sequence.</dd> +<dt><b>init</b></dt> +<dd>Display the sequence that initializes the user's terminal in an implementation-defined manner.</dd> +<dt><b>reset</b></dt> +<dd>Display the sequence that resets the user's terminal in an implementation-defined manner.</dd> +</dl> +<p>If a terminal does not support any of the operations described by these operands, this shall not be considered an error +condition.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_125_06" id="tag_20_125_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_125_07" id="tag_20_125_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_125_08" id="tag_20_125_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>tput</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>TERM</i></dt> +<dd>Determine the terminal type. If this variable is unset or null, and if the <b>-T</b> option is not specified, an unspecified +default terminal type shall be used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_125_09" id="tag_20_125_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_125_10" id="tag_20_125_10"></a>STDOUT</h4> +<blockquote> +<p>If standard output is a terminal device, it may be used for writing the appropriate sequence to clear the screen or reset or +initialize the terminal. If standard output is not a terminal device, undefined results occur.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_125_11" id="tag_20_125_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_125_12" id="tag_20_125_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_125_13" id="tag_20_125_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_125_14" id="tag_20_125_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>The requested string was written successfully.</dd> +<dt> 1</dt> +<dd>Unspecified.</dd> +<dt> 2</dt> +<dd>Usage error.</dd> +<dt> 3</dt> +<dd>No information is available about the specified terminal type.</dd> +<dt> 4</dt> +<dd>The specified operand is invalid.</dd> +<dt>>4</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_125_15" id="tag_20_125_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>If one of the operands is not available for the terminal, <i>tput</i> continues processing the remaining operands.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_125_16" id="tag_20_125_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The difference between resetting and initializing a terminal is left unspecified, as they vary greatly based on hardware types. +In general, resetting is a more severe action.</p> +<p>Some terminals use control characters to perform the stated functions, and on such terminals it might make sense to use +<i>tput</i> to store the initialization strings in a file or environment variable for later use. However, because other terminals +might rely on system calls to do this work, the standard output cannot be used in a portable manner, such as the following +non-portable constructs:</p> +<pre> +<tt>ClearVar=`tput clear` +tput reset | mailx -s "Wake Up" ddg +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_125_17" id="tag_20_125_17"></a>EXAMPLES</h4> +<blockquote> +<ol> +<li> +<p>Initialize the terminal according to the type of terminal in the environmental variable <i>TERM .</i> This command can be +included in a <b>.profile</b> file.</p> +<pre> +<tt>tput init +</tt></pre></li> +<li> +<p>Reset a 450 terminal.</p> +<pre> +<tt>tput -T 450 reset +</tt></pre></li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_125_18" id="tag_20_125_18"></a>RATIONALE</h4> +<blockquote> +<p>The list of operands was reduced to a minimum for the following reasons:</p> +<ul> +<li> +<p>The only features chosen were those that were likely to be used by human users interacting with a terminal.</p> +</li> +<li> +<p>Specifying the full <i>terminfo</i> set was not considered desirable, but the standard developers did not want to select among +operands.</p> +</li> +<li> +<p>This volume of POSIX.1-2024 does not attempt to provide applications with sophisticated terminal handling capabilities, as that +falls outside of its assigned scope and intersects with the responsibilities of other standards bodies.</p> +</li> +</ul> +<p>The difference between resetting and initializing a terminal is left unspecified as this varies greatly based on hardware types. +In general, resetting is a more severe action.</p> +<p>The exit status of 1 is historically reserved for finding out if a Boolean operand is not set. Although the operands were +reduced to a minimum, the exit status of 1 should still be reserved for the Boolean operands, for those sites that wish to support +them.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_125_19" id="tag_20_125_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_125_20" id="tag_20_125_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/stty.html#"><i>stty</i></a> , <a href="../utilities/tabs.html#"><i>tabs</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_125_21" id="tag_20_125_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_125_22" id="tag_20_125_22"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_125_23" id="tag_20_125_23"></a>Issue 7</h4> +<blockquote> +<p>The <i>tput</i> utility is moved from the User Portability Utilities option to the Base. User Portability Utilities is now an +option for interactive utilities.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_125_24" id="tag_20_125_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/touch.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/tr.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/tr.html b/bdd/tr.html @@ -0,0 +1,442 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>tr</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/tput.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/true.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="tr" id="tr"></a> <a name="tag_20_126" id="tag_20_126"></a><!-- tr --> +<h4 class="mansect"><a name="tag_20_126_01" id="tag_20_126_01"></a>NAME</h4> +<blockquote>tr — translate characters</blockquote> +<h4 class="mansect"><a name="tag_20_126_02" id="tag_20_126_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>tr</tt> <b>[</b><tt>-c|-C</tt><b>] [</b><tt>-s</tt><b>]</b> <i>string1 string2</i> <tt><br> +<br> +tr -s</tt> <b>[</b><tt>-c|-C</tt><b>]</b> <i>string1</i> <tt><br> +<br> +tr -d</tt> <b>[</b><tt>-c|-C</tt><b>]</b> <i>string1</i> <tt><br> +<br> +tr -ds</tt> <b>[</b><tt>-c|-C</tt><b>]</b> <i>string1 string2</i> <tt><br></tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_126_03" id="tag_20_126_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>tr</i> utility shall copy the standard input to the standard output with substitution or deletion of selected characters. +The options specified and the <i>string1</i> and <i>string2</i> operands shall control translations that occur while copying +characters and single-character collating elements.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_126_04" id="tag_20_126_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>tr</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-c</b></dt> +<dd>Complement the set of values specified by <i>string1</i>. See the EXTENDED DESCRIPTION section.</dd> +<dt><b>-C</b></dt> +<dd>Complement the set of characters specified by <i>string1</i>. See the EXTENDED DESCRIPTION section.</dd> +<dt><b>-d</b></dt> +<dd>Delete all occurrences of input characters that are specified by <i>string1</i>.</dd> +<dt><b>-s</b></dt> +<dd>Replace instances of repeated characters with a single character, as described in the EXTENDED DESCRIPTION section.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_126_05" id="tag_20_126_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>string1</i>, <i>string2</i></dt> +<dd><br> +Translation control strings. Each string shall represent a set of characters to be converted into an array of characters used for +the translation. For a detailed description of how the strings are interpreted, see the EXTENDED DESCRIPTION section.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_126_06" id="tag_20_126_06"></a>STDIN</h4> +<blockquote> +<p>The standard input can be any type of file.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_126_07" id="tag_20_126_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_126_08" id="tag_20_126_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>tr</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_COLLATE</i></dt> +<dd><br> +Determine the locale for the behavior of range expressions and equivalence classes.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments) and the behavior of character classes.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_126_09" id="tag_20_126_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_126_10" id="tag_20_126_10"></a>STDOUT</h4> +<blockquote> +<p>The <i>tr</i> output shall be identical to the input, with the exception of the specified transformations.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_126_11" id="tag_20_126_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_126_12" id="tag_20_126_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_126_13" id="tag_20_126_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>The operands <i>string1</i> and <i>string2</i> (if specified) define two arrays of characters. The constructs in the following +list can be used to specify characters or single-character collating elements. If any of the constructs result in multi-character +collating elements, <i>tr</i> shall exclude, without a diagnostic, those multi-character elements from the resulting array.</p> +<dl compact> +<dd></dd> +<dt><i>character</i></dt> +<dd>Any character not described by one of the conventions below shall represent itself.</dd> +<dt>\<i>octal</i></dt> +<dd>Octal sequences can be used to represent characters with specific coded values. An octal sequence shall consist of a +<backslash> followed by the longest sequence of one, two, or three-octal-digit characters (01234567). The sequence shall +cause the value whose encoding is represented by the one, two, or three-digit octal integer to be placed into the array. Multi-byte +characters require multiple, concatenated escape sequences of this type, including the leading <backslash> for each +byte.</dd> +<dt>\<i>character</i></dt> +<dd>The <backslash>-escape sequences in XBD <a href="../basedefs/V1_chap05.html#tagtcjh_2"><i>Escape Sequences and Associated +Actions</i></a> (<tt>'\\'</tt>, <tt>'\a'</tt>, <tt>'\b'</tt>, <tt>'\f'</tt>, <tt>'\n'</tt>, <tt>'\r'</tt>, <tt>'\t'</tt>, +<tt>'\v'</tt>) shall be supported. The results of using any other character, other than an octal digit, following the +<backslash> are unspecified. Also, if there is no character following the <backslash>, the results are +unspecified.</dd> +<dt><i>c</i>-<i>c</i></dt> +<dd>In the POSIX locale, this construct shall represent the range of collating elements between the range endpoints (as long as +neither endpoint is an octal sequence of the form \<i>octal</i>), inclusive, as defined by the collation sequence. The characters +or collating elements in the range shall be placed in the array in ascending collation sequence. If the second endpoint precedes +the starting endpoint in the collation sequence, it is unspecified whether the range of collating elements is empty, or this +construct is treated as invalid. In locales other than the POSIX locale, this construct has unspecified behavior. +<p>If either or both of the range endpoints are octal sequences of the form \<i>octal</i>, this shall represent the range of +specific coded values between the two range endpoints, inclusive.</p> +</dd> +<dt>[:<i>class</i>:]</dt> +<dd>Represents all characters belonging to the defined character class, as defined by the current setting of the <i>LC_CTYPE</i> +locale category. The following character class names shall be accepted when specified in <i>string1</i>: +<table cellpadding="3"> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>alnum</b></p> +</td> +<td align="left"> +<p class="tent"><b>blank</b></p> +</td> +<td align="left"> +<p class="tent"><b>digit</b></p> +</td> +<td align="left"> +<p class="tent"><b>lower</b></p> +</td> +<td align="left"> +<p class="tent"><b>punct</b></p> +</td> +<td align="left"> +<p class="tent"><b>upper</b></p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent"><b>alpha</b></p> +</td> +<td align="left"> +<p class="tent"><b>cntrl</b></p> +</td> +<td align="left"> +<p class="tent"><b>graph</b></p> +</td> +<td align="left"> +<p class="tent"><b>print</b></p> +</td> +<td align="left"> +<p class="tent"><b>space</b></p> +</td> +<td align="left"> +<p class="tent"><b>xdigit</b></p> +</td> +</tr> +</table> +<p class="tent"><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" +border="0"> In addition, character class expressions of the form [:<i>name</i>:] shall be recognized in those locales where the +<i>name</i> keyword has been given a <b>charclass</b> definition in the <i>LC_CTYPE</i> category. <img src="../images/opt-end.gif" +alt="[Option End]" border="0"></p> +<p class="tent">When both the <b>-d</b> and <b>-s</b> options are specified, any of the character class names shall be accepted in +<i>string2</i>. Otherwise, only character class names <b>lower</b> or <b>upper</b> are valid in <i>string2</i> and then only if the +corresponding character class (<b>upper</b> and <b>lower</b>, respectively) is specified in the same relative position in +<i>string1</i>. Such a specification shall be interpreted as a request for case conversion. When [:<i>lower</i>:] appears in +<i>string1</i> and [:<i>upper</i>:] appears in <i>string2</i>, the arrays shall contain the characters from the <b>toupper</b> +mapping in the <i>LC_CTYPE</i> category of the current locale. When [:<i>upper</i>:] appears in <i>string1</i> and [:<i>lower</i>:] +appears in <i>string2</i>, the arrays shall contain the characters from the <b>tolower</b> mapping in the <i>LC_CTYPE</i> category +of the current locale. The first character from each mapping pair shall be in the array for <i>string1</i> and the second character +from each mapping pair shall be in the array for <i>string2</i> in the same relative position.</p> +<p class="tent">Except for case conversion, the characters specified by a character class expression shall be placed in the array +in an unspecified order.</p> +<p class="tent">If the name specified for <i>class</i> does not define a valid character class in the current locale, the behavior +is undefined.</p> +</dd> +<dt>[=<i>equiv</i>=]</dt> +<dd>Represents all characters or collating elements belonging to the same equivalence class as <i>equiv</i>, as defined by the +current setting of the <i>LC_COLLATE</i> locale category. An equivalence class expression shall be allowed only in <i>string1</i>, +or in <i>string2</i> when it is being used by the combined <b>-d</b> and <b>-s</b> options. The characters belonging to the +equivalence class shall be placed in the array in an unspecified order.</dd> +<dt>[<i>x</i>*<i>n</i>]</dt> +<dd>Represents <i>n</i> repeated occurrences of the character <i>x</i>. Because this expression is used to map multiple characters +to one, it is only valid when it occurs in <i>string2</i>. If <i>n</i> is omitted or is zero, it shall be interpreted as large +enough to extend the <i>string2</i>-based sequence to the length of the <i>string1</i>-based sequence. If <i>n</i> has a leading +zero, it shall be interpreted as an octal value. Otherwise, it shall be interpreted as a decimal value.</dd> +</dl> +<p class="tent">When the <b>-d</b> option is not specified:</p> +<ul> +<li class="tent">If <i>string2</i> is present, each input character found in the array specified by <i>string1</i> shall be +replaced by the character in the same relative position in the array specified by <i>string2</i>. If the array specified by +<i>string2</i> is shorter that the one specified by <i>string1</i>, or if a character occurs more than once in <i>string1</i>, the +results are unspecified.</li> +<li class="tent">If the <b>-C</b> option is specified, the complements of the characters specified by <i>string1</i> (the set of +all characters in the current character set, as defined by the current setting of <i>LC_CTYPE ,</i> except for those actually +specified in the <i>string1</i> operand) shall be placed in the array in ascending collation sequence, as defined by the current +setting of <i>LC_COLLATE .</i></li> +<li class="tent">If the <b>-c</b> option is specified, the complement of the values specified by <i>string1</i> shall be placed in +the array in ascending order by binary value.</li> +<li class="tent">Because the order in which characters specified by character class expressions or equivalence class expressions is +undefined, such expressions should only be used if the intent is to map several characters into one. An exception is case +conversion, as described previously.</li> +</ul> +<p class="tent">When the <b>-d</b> option is specified:</p> +<ul> +<li class="tent">Input characters found in the array specified by <i>string1</i> shall be deleted.</li> +<li class="tent">When the <b>-C</b> option is specified with <b>-d</b>, all characters except those specified by <i>string1</i> +shall be deleted. The contents of <i>string2</i> are ignored, unless the <b>-s</b> option is also specified.</li> +<li class="tent">When the <b>-c</b> option is specified with <b>-d</b>, all values except those specified by <i>string1</i> shall +be deleted. The contents of <i>string2</i> shall be ignored, unless the <b>-s</b> option is also specified.</li> +<li class="tent">The same string cannot be used for both the <b>-d</b> and the <b>-s</b> option; when both options are specified, +both <i>string1</i> (used for deletion) and <i>string2</i> (used for squeezing) shall be required.</li> +</ul> +<p class="tent">When the <b>-s</b> option is specified, after any deletions or translations have taken place, repeated sequences of +the same character shall be replaced by one occurrence of the same character, if the character is found in the array specified by +the last operand. If the last operand contains a character class, such as the following example:</p> +<pre> +<tt>tr -s '[:space:]' +</tt></pre> +<p class="tent">the last operand's array shall contain all of the characters in that character class. However, in a case +conversion, as described previously, such as:</p> +<pre> +<tt>tr -s '[:upper:]' '[:lower:]' +</tt></pre> +<p class="tent">the last operand's array shall contain only those characters defined as the second characters in each of the +<b>toupper</b> or <b>tolower</b> character pairs, as appropriate.</p> +<p class="tent">An empty string used for <i>string1</i> or <i>string2</i> produces undefined results.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_126_14" id="tag_20_126_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>All input was processed successfully.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_126_15" id="tag_20_126_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_126_16" id="tag_20_126_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>If necessary, <i>string1</i> and <i>string2</i> can be quoted to avoid pattern matching by the shell.</p> +<p class="tent">If an ordinary digit (representing itself) is to follow an octal sequence, the octal sequence must use the full +three digits to avoid ambiguity.</p> +<p class="tent">When <i>string2</i> is shorter than <i>string1</i>, a difference results between historical System V and BSD +systems. A BSD system pads <i>string2</i> with the last character found in <i>string2</i>. Thus, it is possible to do the +following:</p> +<pre> +<tt>tr 0123456789 d +</tt></pre> +<p class="tent">which would translate all digits to the letter <tt>'d'</tt>. Since this area is specifically unspecified in this +volume of POSIX.1-2024, both the BSD and System V behaviors are allowed, but a conforming application cannot rely on the BSD +behavior. It would have to code the example in the following way:</p> +<pre> +<tt>tr 0123456789 '[d*]' +</tt></pre> +<p class="tent">It should be noted that, despite similarities in appearance, the string operands used by <i>tr</i> are not regular +expressions.</p> +<p class="tent">Unlike some historical implementations, this definition of the <i>tr</i> utility correctly processes NUL characters +in its input stream. NUL characters can be stripped by using:</p> +<pre> +<tt>tr -d '\000' +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_126_17" id="tag_20_126_17"></a>EXAMPLES</h4> +<blockquote> +<ol> +<li class="tent">The following example creates a list of all words in <b>file1</b> one per line in <b>file2</b>, where a word is +taken to be a maximal string of letters. +<pre> +<tt>tr -cs "[:alpha:]" "[\n*]" <file1 >file2 +</tt></pre></li> +<li class="tent">The next example translates all lowercase characters in <b>file1</b> to uppercase and writes the results to +standard output. +<pre> +<tt>tr "[:lower:]" "[:upper:]" <file1 +</tt></pre></li> +<li class="tent">This example uses an equivalence class to identify accented variants of the base character <tt>'e'</tt> in +<b>file1</b>, which are stripped of diacritical marks and written to <b>file2</b>. +<pre> +<tt>tr "[=e=]" "[e*]" <file1 >file2 +</tt></pre></li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_126_18" id="tag_20_126_18"></a>RATIONALE</h4> +<blockquote> +<p>In some early proposals, an explicit option <b>-n</b> was added to disable the historical behavior of stripping NUL characters +from the input. It was considered that automatically stripping NUL characters from the input was not correct functionality. +However, the removal of <b>-n</b> in a later proposal does not remove the requirement that <i>tr</i> correctly process NUL +characters in its input stream. NUL characters can be stripped by using <i>tr</i> <b>-d</b> '\000'.</p> +<p class="tent">Historical implementations of <i>tr</i> differ widely in syntax and behavior. For example, the BSD version has not +needed the bracket characters for the repetition sequence. The <i>tr</i> utility syntax is based more closely on the System V and +XPG3 model while attempting to accommodate historical BSD implementations. In the case of the short <i>string2</i> padding, the +decision was to unspecify the behavior and preserve System V and XPG3 scripts, which might find difficulty with the BSD method. The +assumption was made that BSD users of <i>tr</i> have to make accommodations to meet the syntax defined here. Since it is possible +to use the repetition sequence to duplicate the desired behavior, whereas there is no simple way to achieve the System V method, +this was the correct, if not desirable, approach.</p> +<p class="tent">The use of octal values to specify control characters, while having historical precedents, is not portable. The +introduction of escape sequences for control characters should provide the necessary portability. It is recognized that this may +cause some historical scripts to break.</p> +<p class="tent">An early proposal included support for multi-character collating elements. It was pointed out that, while <i>tr</i> +does employ some syntactical elements from REs, the aim of <i>tr</i> is quite different; ranges, for example, do not have a similar +meaning ("any of the chars in the range matches", <i>versus</i> "translate each character in the range to the output +counterpart"). As a result, the previously included support for multi-character collating elements has been removed. What remains +are ranges in current collation order (to support, for example, accented characters), character classes, and equivalence +classes.</p> +<p class="tent">In XPG3 the [:<i>class</i>:] and [=<i>equiv</i>=] conventions are shown with double brackets, as in RE syntax. +However, <i>tr</i> does not implement RE principles; it just borrows part of the syntax. Consequently, [:<i>class</i>:] and +[=<i>equiv</i>=] should be regarded as syntactical elements on a par with [<i>x</i>*<i>n</i>], which is not an RE bracket +expression.</p> +<p class="tent">The standard developers will consider changes to <i>tr</i> that allow it to translate characters between different +character encodings, or they will consider providing a new utility to accomplish this.</p> +<p class="tent">On historical System V systems, a range expression requires enclosing square-brackets, such as:</p> +<pre> +<tt>tr '[a-z]' '[A-Z]' +</tt></pre> +<p class="tent">However, BSD-based systems did not require the brackets, and this convention is used here to avoid breaking large +numbers of BSD scripts:</p> +<pre> +<tt>tr a-z A-Z +</tt></pre> +<p class="tent">The preceding System V script will continue to work because the brackets, treated as regular characters, are +translated to themselves. However, any System V script that relied on <tt>"a-z"</tt> representing the three characters +<tt>'a'</tt>, <tt>'-'</tt>, and <tt>'z'</tt> have to be rewritten as <tt>"az-"</tt>.</p> +<p class="tent">The ISO POSIX-2:1993 standard had a <b>-c</b> option that behaved similarly to the <b>-C</b> option, but did +not supply functionality equivalent to the <b>-c</b> option specified in POSIX.1-2024.</p> +<p class="tent">The earlier version also said that octal sequences referred to collating elements and could be placed adjacent to +each other to specify multi-byte characters. However, it was noted that this caused ambiguities because <i>tr</i> would not be able +to tell whether adjacent octal sequences were intending to specify multi-byte characters or multiple single byte characters. +POSIX.1-2024 specifies that octal sequences always refer to single byte binary values when used to specify an endpoint of a range +of collating elements.</p> +<p class="tent">Earlier versions of this standard allowed for implementations with bytes other than eight bits, but this has been +modified in this version.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_126_19" id="tag_20_126_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_126_20" id="tag_20_126_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/sed.html#"><i>sed</i></a></p> +<p class="tent">XBD <a href="../basedefs/V1_chap05.html#tagtcjh_2"><i>Escape Sequences and Associated Actions</i></a> , <a href= +"../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 +Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_126_21" id="tag_20_126_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_126_22" id="tag_20_126_22"></a>Issue 6</h4> +<blockquote> +<p>The <b>-C</b> operand is added, and the description of the <b>-c</b> operand is changed to align with the IEEE P1003.2b +draft standard.</p> +<p class="tent">The normative text is reworded to avoid use of the term "must" for application requirements.</p> +<p class="tent">IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/31 is applied, removing text describing behavior on +systems with bytes consisting of more than eight bits.</p> +<p class="tent">IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/32 is applied, updating an example in the EXAMPLES +section to avoid using unspecified behavior.</p> +<p class="tent">IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/33 is applied, making a correction to the +RATIONALE.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_126_23" id="tag_20_126_23"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-30 is applied.</p> +<p class="tent">SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.<br></p> +<p class="tent">Austin Group Interpretation 1003.1-2001 #132 is applied, adding rationale to the \<i>character</i> construct.</p> +<p class="tent">POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0145 [325] is applied.</p> +<p class="tent">POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0196 [663] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_126_24" id="tag_20_126_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/tput.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/true.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/true.html b/bdd/true.html @@ -0,0 +1,175 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>true</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/tr.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/tsort.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="true" id="true"></a> <a name="tag_20_127" id="tag_20_127"></a><!-- true --> +<h4 class="mansect"><a name="tag_20_127_01" id="tag_20_127_01"></a>NAME</h4> +<blockquote>true — return true value</blockquote> +<h4 class="mansect"><a name="tag_20_127_02" id="tag_20_127_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>true</tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_127_03" id="tag_20_127_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>true</i> utility shall return with exit code zero.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_127_04" id="tag_20_127_04"></a>OPTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_127_05" id="tag_20_127_05"></a>OPERANDS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_127_06" id="tag_20_127_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_127_07" id="tag_20_127_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_127_08" id="tag_20_127_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_127_09" id="tag_20_127_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_127_10" id="tag_20_127_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_127_11" id="tag_20_127_11"></a>STDERR</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_127_12" id="tag_20_127_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_127_13" id="tag_20_127_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_127_14" id="tag_20_127_14"></a>EXIT STATUS</h4> +<blockquote> +<p>Zero.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_127_15" id="tag_20_127_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_127_16" id="tag_20_127_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>This utility is typically used in shell scripts, as shown in the EXAMPLES section.</p> +<p>Although the special built-in utility <b>:</b> (<a href="../utilities/colon.html"><i>colon</i></a>) is similar to <i>true</i>, +there are some notable differences, including:</p> +<ul> +<li> +<p>Whereas <a href="../utilities/colon.html"><i>colon</i></a> is required to accept, and do nothing with, any number of arguments, +<i>true</i> is only required to accept, and discard, a first argument of <tt>"--"</tt>. Passing any other argument(s) to +<i>true</i> may cause its behavior to differ from that described in this standard.</p> +</li> +<li> +<p>A non-interactive shell exits when a redirection error occurs with <a href="../utilities/colon.html"><i>colon</i></a> (unless +executed via <a href="../utilities/command.html"><i>command</i></a>), whereas with <i>true</i> it does not.</p> +</li> +<li> +<p>Variable assignments preceding the command name persist after executing <a href="../utilities/colon.html"><i>colon</i></a> +(unless executed via <a href="../utilities/command.html"><i>command</i></a>), but not after executing <i>true</i>.</p> +</li> +<li> +<p>In shell implementations where <i>true</i> is not provided as a built-in, using <a href= +"../utilities/colon.html"><i>colon</i></a> avoids the overheads associated with executing an external utility.</p> +</li> +</ul> +</blockquote> +<h4 class="mansect"><a name="tag_20_127_17" id="tag_20_127_17"></a>EXAMPLES</h4> +<blockquote> +<p>This command is executed forever:</p> +<pre> +<tt>while true +do + command +done +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_127_18" id="tag_20_127_18"></a>RATIONALE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_127_19" id="tag_20_127_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_127_20" id="tag_20_127_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19_09"><i>2.9 Shell Commands</i></a> , <a href= +"../utilities/V3_chap02.html#tag_19_17"><i>colon</i></a> , <a href="../utilities/command.html#"><i>command</i></a> , <a href= +"../utilities/false.html#"><i>false</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_127_21" id="tag_20_127_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_127_22" id="tag_20_127_22"></a>Issue 6</h4> +<blockquote> +<p>IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/39 is applied, replacing the terms "None" and "Default" from +the STDERR and EXIT STATUS sections, respectively, with terms as defined in <a href="../utilities/V3_chap01.html#tag_18_04"><i>1.4 +Utility Description Defaults</i></a> .</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_127_23" id="tag_20_127_23"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1640 is applied, clarifying the differences between <i>true</i> and <b>:</b> (<a href= +"../utilities/colon.html"><i>colon</i></a>).</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/tr.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/tsort.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/tsort.html b/bdd/tsort.html @@ -0,0 +1,226 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>tsort</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/true.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/tty.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="tsort" id="tsort"></a> <a name="tag_20_128" id="tag_20_128"></a><!-- tsort --> +<h4 class="mansect"><a name="tag_20_128_01" id="tag_20_128_01"></a>NAME</h4> +<blockquote>tsort — topological sort</blockquote> +<h4 class="mansect"><a name="tag_20_128_02" id="tag_20_128_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>tsort</tt> <b>[</b><tt>-w</tt><b>] [</b><i>file</i><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_128_03" id="tag_20_128_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>tsort</i> utility shall write to standard output a totally ordered list of items consistent with a partial ordering of +items contained in the input.</p> +<p>The application shall ensure that the input consists of pairs of items (non-empty strings) separated by one or more +<blank> or <newline> characters. It is unspecified whether other white-space characters can also be used as separators. +Pairs of different items shall indicate ordering. Pairs of identical items shall indicate presence, but not ordering.</p> +<p>If a cycle is found in the input, diagnostic or warning messages shall be written to standard error reporting that there is a +cycle and indicating which nodes are in the cycle(s). If the <b>-w</b> option is specified, these messages shall be diagnostic +messages. If a diagnostic message is written, the final exit status shall be non-zero.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_128_04" id="tag_20_128_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>tsort</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following option shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-w</b></dt> +<dd>Set the exit status to the number of cycles found in the input, or to an implementation-defined maximum if there are more +cycles than that maximum. If no cycles are found, the exit status shall be zero unless another error occurs.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_128_05" id="tag_20_128_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of a text file to order. If no <i>file</i> operand is given, the standard input shall be used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_128_06" id="tag_20_128_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be used if no <i>file</i> operand is specified, and shall be used if the <i>file</i> operand is +<tt>'-'</tt> and the implementation treats the <tt>'-'</tt> as meaning standard input. Otherwise, the standard input shall not be +used. See the INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_128_07" id="tag_20_128_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input file shall be a text file.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_128_08" id="tag_20_128_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>tsort</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_128_09" id="tag_20_128_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_128_10" id="tag_20_128_10"></a>STDOUT</h4> +<blockquote> +<p>The standard output shall be a text file consisting of the ordered list of items, with one item per line, produced from the +partially ordered input.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_128_11" id="tag_20_128_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic and warning messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_128_12" id="tag_20_128_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_128_13" id="tag_20_128_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_128_14" id="tag_20_128_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred. If the <b>-w</b> option is specified and one or more cycles were found in the input, the exit status shall +be the number of cycles found, or an implementation-defined maximum if more cycles than that maximum were found.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_128_15" id="tag_20_128_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_128_16" id="tag_20_128_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The <i>LC_COLLATE</i> variable need not affect the actions of <i>tsort</i>. The output ordering is not lexicographic, but +depends on the pairs of items given as input.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_128_17" id="tag_20_128_17"></a>EXAMPLES</h4> +<blockquote> +<p>The command:</p> +<pre> +<tt>tsort <<EOF +a b c c d e +g g +f g e f +h h +EOF +</tt></pre> +<p>produces the output:</p> +<pre> +<b>a +b +c +d +e +f +g +h</b><tt> +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_128_18" id="tag_20_128_18"></a>RATIONALE</h4> +<blockquote> +<p>At the time that the <b>-w</b> option was added to this standard, the only known implementation reported a maximum of 255 cycles +via the exit status. This has the drawback that applications cannot distinguish, from the exit status, errors caused by cycles from +other errors or (when <i>tsort</i> is executed from a shell) termination by a signal. Implementations are urged to set the +implementation-defined maximum number of cycles reported via the exit status to at most 124, leaving values above that maximum +through 125 for other errors, and leaving values 126 and greater to have the special meanings that the shell assigns to them.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_128_19" id="tag_20_128_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>A future version of this standard may require that when the <b>-w</b> option is specified, the maximum number of cycles reported +through the exit status of <i>tsort</i> is at most 124 and that exit status values greater than 126 are not used by +<i>tsort</i>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_128_20" id="tag_20_128_20"></a>SEE ALSO</h4> +<blockquote> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_128_21" id="tag_20_128_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_128_22" id="tag_20_128_22"></a>Issue 6</h4> +<blockquote> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_128_23" id="tag_20_128_23"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #092 is applied.</p> +<p>The <i>tsort</i> utility is moved from the XSI option to the Base.</p> +<p>POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0146 [241] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_128_24" id="tag_20_128_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defects 1617 and 1629 are applied, clarifying how <i>tsort</i> handles cycles found in the input.</p> +<p>Austin Group Defect 1745 is applied, clarifying the input separator characters and the output format.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/true.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/tty.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/tty.html b/bdd/tty.html @@ -0,0 +1,195 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>tty</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/tsort.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/type.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="tty" id="tty"></a> <a name="tag_20_129" id="tag_20_129"></a><!-- tty --> +<h4 class="mansect"><a name="tag_20_129_01" id="tag_20_129_01"></a>NAME</h4> +<blockquote>tty — return user's terminal name</blockquote> +<h4 class="mansect"><a name="tag_20_129_02" id="tag_20_129_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>tty</tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_129_03" id="tag_20_129_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>tty</i> utility shall write to the standard output the name of the terminal that is open as standard input. The name that +is used shall be equivalent to the string that would be returned by the <a href="../functions/ttyname.html"><i>ttyname</i>()</a> +function defined in the System Interfaces volume of POSIX.1-2024.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_129_04" id="tag_20_129_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>tty</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_129_05" id="tag_20_129_05"></a>OPERANDS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_129_06" id="tag_20_129_06"></a>STDIN</h4> +<blockquote> +<p>While no input is read from standard input, standard input shall be examined to determine whether or not it is a terminal, and, +if so, to determine the name of the terminal.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_129_07" id="tag_20_129_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_129_08" id="tag_20_129_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>tty</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error and +informative messages written to standard output.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_129_09" id="tag_20_129_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_129_10" id="tag_20_129_10"></a>STDOUT</h4> +<blockquote> +<p>If standard input is a terminal device, a pathname of the terminal as specified by the <a href= +"../functions/ttyname.html"><i>ttyname</i>()</a> function defined in the System Interfaces volume of POSIX.1-2024 shall be written +in the following format:</p> +<pre> +<tt>"%s\n", <</tt><i>terminal name</i><tt>> +</tt></pre> +<p>Otherwise, a message shall be written indicating that standard input is not connected to a terminal. In the POSIX locale, the +<i>tty</i> utility shall use the format:</p> +<pre> +<tt>"not a tty\n" +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_129_11" id="tag_20_129_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_129_12" id="tag_20_129_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_129_13" id="tag_20_129_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_129_14" id="tag_20_129_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Standard input is a terminal, and the output specified in STDOUT was successfully written to standard output.</dd> +<dt> 1</dt> +<dd>Standard input is not a terminal, and the output specified in STDOUT was successfully written to standard output.</dd> +<dt>>1</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_129_15" id="tag_20_129_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_129_16" id="tag_20_129_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>This utility checks the status of the file open as standard input against that of an implementation-defined set of files. It is +possible that no match can be found, or that the match found need not be the same file as that which was opened for standard input +(although they are the same device).</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_129_17" id="tag_20_129_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_129_18" id="tag_20_129_18"></a>RATIONALE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_129_19" id="tag_20_129_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_129_20" id="tag_20_129_20"></a>SEE ALSO</h4> +<blockquote> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/isatty.html#"><i>isatty</i></a> , <a href="../functions/ttyname.html#"><i>ttyname</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_129_21" id="tag_20_129_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_129_22" id="tag_20_129_22"></a>Issue 5</h4> +<blockquote> +<p>The SYNOPSIS is changed to indicate two forms of the command, with the second form marked as obsolete. This is a clarification +and does not change the functionality published in previous issues.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_129_23" id="tag_20_129_23"></a>Issue 6</h4> +<blockquote> +<p>The obsolescent <b>-s</b> option is removed.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_129_24" id="tag_20_129_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1509 is applied, changing the EXIT STATUS section.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/tsort.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/type.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/type.html b/bdd/type.html @@ -0,0 +1,194 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>type</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/tty.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/ulimit.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="type" id="type"></a> <a name="tag_20_130" id="tag_20_130"></a><!-- type --> +<h4 class="mansect"><a name="tag_20_130_01" id="tag_20_130_01"></a>NAME</h4> +<blockquote>type — write a description of command type</blockquote> +<h4 class="mansect"><a name="tag_20_130_02" id="tag_20_130_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> type</tt> <i>name</i><tt>... <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></tt></code></div> +</blockquote> +<h4 class="mansect"><a name="tag_20_130_03" id="tag_20_130_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>type</i> utility shall indicate how each argument would be interpreted if used as a command name.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_130_04" id="tag_20_130_04"></a>OPTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_130_05" id="tag_20_130_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>name</i></dt> +<dd>A name to be interpreted.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_130_06" id="tag_20_130_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_130_07" id="tag_20_130_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_130_08" id="tag_20_130_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>type</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd>Determine the location of messages objects and message catalogs.</dd> +<dt><i>PATH</i></dt> +<dd>Determine the location of <i>name</i>, as described in XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment +Variables</i></a> .</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_130_09" id="tag_20_130_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_130_10" id="tag_20_130_10"></a>STDOUT</h4> +<blockquote> +<p>The standard output of <i>type</i> contains information about each operand in an unspecified format. The information provided +typically identifies the operand as a shell built-in, function, alias, or keyword, and where applicable, may display the operand's +pathname.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_130_11" id="tag_20_130_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_130_12" id="tag_20_130_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_130_13" id="tag_20_130_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_130_14" id="tag_20_130_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_130_15" id="tag_20_130_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_130_16" id="tag_20_130_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>This utility is required to be intrinsic. See <a href="../utilities/V3_chap01.html#tag_18_07"><i>1.7 Intrinsic Utilities</i></a> +for details.</p> +<p>Since <i>type</i> must be aware of the contents of the current shell execution environment (such as the lists of commands, +functions, and built-ins processed by <a href="../utilities/hash.html"><i>hash</i></a>), it is always provided as a shell regular +built-in. If it is called in a separate utility execution environment, such as one of the following:</p> +<pre> +<tt>nohup type writer +find . -type f -exec type {} + +</tt></pre> +it might not produce accurate results.</blockquote> +<h4 class="mansect"><a name="tag_20_130_17" id="tag_20_130_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_130_18" id="tag_20_130_18"></a>RATIONALE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_130_19" id="tag_20_130_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_130_20" id="tag_20_130_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/command.html#"><i>command</i></a> , <a href="../utilities/hash.html#"><i>hash</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_130_21" id="tag_20_130_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_130_22" id="tag_20_130_22"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 248 is applied, changing a command line in the APPLICATION USAGE section.</p> +<p>Austin Group Defect 251 is applied, encouraging implementations to report an error if a utility is directed to display a +pathname that contains any bytes that have the encoded value of a <newline> character when <newline> is a terminator or +separator in the output format being used.</p> +<p>Austin Group Defect 854 is applied, adding a note to the APPLICATION USAGE section that this utility is required to be +intrinsic.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/tty.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/ulimit.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/ulimit.html b/bdd/ulimit.html @@ -0,0 +1,317 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>ulimit</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/type.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/umask.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="ulimit" id="ulimit"></a> <a name="tag_20_131" id="tag_20_131"></a><!-- ulimit --> +<h4 class="mansect"><a name="tag_20_131_01" id="tag_20_131_01"></a>NAME</h4> +<blockquote>ulimit — report or set resource limits</blockquote> +<h4 class="mansect"><a name="tag_20_131_02" id="tag_20_131_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>ulimit</tt> <b>[</b><tt>-H|-S</tt><b>]</b> <tt>-a<br> +<br> +<sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> ulimit</tt> <b>[</b><tt>-H|-S</tt><b>] [</b><tt>-c|-d|-f|-n|-s|<img src= +"../images/opt-start.gif" border="0">-t<img src="../images/opt-end.gif" border="0">|-v</tt><b>] [</b><i>newlimit</i><b>]</b> +<tt><br></tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_131_03" id="tag_20_131_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>ulimit</i> utility shall report or set the resource limits in effect in the process in which it is executed.</p> +<p>Soft limits can be changed by a process to any value that is less than or equal to the hard limit. A process can (irreversibly) +lower its hard limit to any value that is greater than or equal to the soft limit. Only a process with appropriate privileges can +raise a hard limit.</p> +<p>The value <b>unlimited</b> for a resource shall be considered to be larger than any other limit value. When a resource has this +limit value, the implementation shall not enforce limits on that resource. In locales other than the POSIX locale, <i>ulimit</i> +may support additional non-numeric values with the same meaning as <b>unlimited</b>.</p> +<p>The behavior when resource limits are exceeded shall be as described in the System Interfaces volume of POSIX.1-2024 for the +<a href="../functions/setrlimit.html"><i>setrlimit</i>()</a> function.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_131_04" id="tag_20_131_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>ulimit</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> , except that:</p> +<ul> +<li> +<p>The order in which options other than <b>-H</b>, <b>-S</b>, and <b>-a</b> are specified may be significant.</p> +</li> +<li> +<p>Conforming applications shall specify each option separately; that is, grouping option letters (for example, <b>-fH</b>) need +not be recognized by all implementations.</p> +</li> +</ul> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-H</b></dt> +<dd>Report hard limit(s) or set only a hard limit.</dd> +<dt><b>-S</b></dt> +<dd>Report soft limit(s) or set only a soft limit.</dd> +<dt><b>-a</b></dt> +<dd>Report the limit value for all of the resources named below and for any implementation-specific additional resources.</dd> +<dt><b>-c</b></dt> +<dd>Report, or set if the <i>newlimit</i> operand is present, the core image size limit(s) in units of 512 bytes. +[RLIMIT_CORE]</dd> +<dt><b>-d</b></dt> +<dd>Report, or set if the <i>newlimit</i> operand is present, the data segment size limit(s) in units of 1024 bytes. +[RLIMIT_DATA]</dd> +<dt><b>-f</b></dt> +<dd>Report, or set if the <i>newlimit</i> operand is present, the file size limit(s) in units of 512 bytes. [RLIMIT_FSIZE]</dd> +<dt><b>-n</b></dt> +<dd>Report, or set if the <i>newlimit</i> operand is present, the limit(s) on the number of open file descriptors, given as a +number one greater than the maximum value that the system assigns to a newly-created descriptor. [RLIMIT_NOFILE]</dd> +<dt><b>-s</b></dt> +<dd>Report, or set if the <i>newlimit</i> operand is present, the stack size limit(s) in units of 1024 bytes. [RLIMIT_STACK]</dd> +<dt><b>-t</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Report, or set if the <i>newlimit</i> operand is present, the per-process CPU time limit(s) in units of seconds. [RLIMIT_CPU] +<img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-v</b></dt> +<dd>Report, or set if the <i>newlimit</i> operand is present, the address space size limit(s) in units of 1024 bytes. +[RLIMIT_AS]</dd> +</dl> +<p>Where an option description is followed by [RLIMIT_<i>name</i>] it indicates which resource for the <a href= +"../functions/getrlimit.html"><i>getrlimit</i>()</a> and <a href="../functions/setrlimit.html"><i>setrlimit</i>()</a> functions, +defined in the System Interfaces volume of POSIX.1-2024, the option corresponds to.</p> +<p>If neither the <b>-H</b> nor <b>-S</b> option is specified:</p> +<ul> +<li> +<p>If the <i>newlimit</i> operand is present, it shall be used as the new value for both the hard and soft limits.</p> +</li> +<li> +<p>If the <i>newlimit</i> operand is not present, <b>-S</b> shall be the default.</p> +</li> +</ul> +<p>If no options other than <b>-H</b> or <b>-S</b> are specified, the behavior shall be as if the <b>-f</b> option was (also) +specified.</p> +<p>If any option other than <b>-H</b> or <b>-S</b> is repeated, the behavior is unspecified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_131_05" id="tag_20_131_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>newlimit</i></dt> +<dd>Either an integer value to use as the new limit(s) for the specified resource, in the units specified in OPTIONS, or a +non-numeric string indicating no limit, as described in the DESCRIPTION section. Numerals in the range 0 to the maximum limit value +supported by the implementation for any resource shall be syntactically recognized as numeric values.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_131_06" id="tag_20_131_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_131_07" id="tag_20_131_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_131_08" id="tag_20_131_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>ulimit</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd>Determine the location of messages objects and message catalogs.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_131_09" id="tag_20_131_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_131_10" id="tag_20_131_10"></a>STDOUT</h4> +<blockquote> +<p>The standard output shall be used when no <i>newlimit</i> operand is present.</p> +<p>If the <b>-a</b> option is specified, the output written for each resource shall consist of one line that includes:</p> +<ul> +<li> +<p>A short phrase identifying the resource (for example "file size").</p> +</li> +<li> +<p>An indication of the units used for the resource, if the corresponding option description in OPTIONS specifies the units to be +used.</p> +</li> +<li> +<p>The <i>ulimit</i> option used to specify the resource.</p> +</li> +<li> +<p>The limit value.</p> +</li> +</ul> +<p>The format used within each line is unspecified, except that the format used for the limit value shall be as described below for +the case where a single limit value is written.</p> +<p>If a single limit value is to be written; that is, the <b>-a</b> option is not specified and at most one option other than +<b>-H</b> or <b>-S</b> is specified:</p> +<ul> +<li> +<p>If the resource being reported has a numeric limit, the limit value shall be written in the following format:</p> +<pre> +<tt>"%1d\n", <</tt><i>limit value</i><tt>> +</tt></pre> +<p>where <<i>limit value</i>> is the value of the limit in the units specified in OPTIONS.</p> +</li> +<li> +<p>If the resource being reported does not have a numeric limit, in the POSIX locale the following format shall be used:</p> +<pre> +<tt>"unlimited\n" +</tt></pre></li> +</ul> +</blockquote> +<h4 class="mansect"><a name="tag_20_131_11" id="tag_20_131_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_131_12" id="tag_20_131_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_131_13" id="tag_20_131_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_131_14" id="tag_20_131_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>A request for a higher limit was rejected or an error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_131_15" id="tag_20_131_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_131_16" id="tag_20_131_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>This utility is required to be intrinsic. See <a href="../utilities/V3_chap01.html#tag_18_07"><i>1.7 Intrinsic Utilities</i></a> +for details.</p> +<p>Since <i>ulimit</i> affects the current shell execution environment, it is always provided as a shell regular built-in. If it is +called with an operand in a separate utility execution environment, such as one of the following:</p> +<pre> +<tt>nohup ulimit -f 10000 +env ulimit -S -c 10000 +</tt></pre> +<p>it does not affect the limit(s) in the caller's environment.</p> +<p>See also the APPLICATION USAGE for <a href="../functions/getrlimit.html#"><i>getrlimit</i></a> .</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_131_17" id="tag_20_131_17"></a>EXAMPLES</h4> +<blockquote> +<p>Set the hard and soft file size limits to 51200 bytes:</p> +<pre> +<tt>ulimit -f 100 +</tt></pre> +<p>Save and restore a soft resource limit (where <i>X</i> is an option letter specifying a resource):</p> +<pre> +<tt>saved=$(ulimit -</tt><i>X</i><tt>) + +... + +ulimit -</tt><i>X</i><tt> -S "$saved" +</tt></pre> +<p>Execute a utility with a CPU limit of 5 minutes (using an asynchronous subshell to ensure the limit is set in a child +process):</p> +<pre> +<tt>(ulimit -t 300; exec utility_name </dev/null) & +wait $! +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_131_18" id="tag_20_131_18"></a>RATIONALE</h4> +<blockquote> +<p>The <i>ulimit</i> utility has no equivalent of the special values RLIM_SAVED_MAX and RLIM_SAVED_CUR returned by <a href= +"../functions/getrlimit.html"><i>getrlimit</i>()</a>, as <i>ulimit</i> is required to be able to output, and accept as input, all +numeric limit values supported by the system.</p> +<p>Implementations differ in their behavior when the <b>-a</b> option is not specified and more than one option other than +<b>-H</b> or <b>-S</b> is specified. Some write output for all of the specified resources in the same format as for <b>-a</b>; +others write only the value for the last specified option. Both behaviors are allowed by the standard, since the SYNOPSIS lists the +options as mutually exclusive.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_131_19" id="tag_20_131_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_131_20" id="tag_20_131_20"></a>SEE ALSO</h4> +<blockquote> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/getrlimit.html#"><i>getrlimit</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_131_21" id="tag_20_131_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_131_22" id="tag_20_131_22"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_131_23" id="tag_20_131_23"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 854 is applied, adding a note to the APPLICATION USAGE section that this utility is required to be +intrinsic.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1418 is applied, adding the <b>-H</b>, <b>-S</b>, <b>-a</b>, <b>-c</b>, <b>-d</b>, <b>-n</b>, <b>-s</b>, +<b>-t</b>, and <b>-v</b> options, and relating the <b>-f</b> option to the RLIMIT_FSIZE resource for <a href= +"../functions/setrlimit.html"><i>setrlimit</i>()</a>.</p> +<p>Austin Group Defect 1669 is applied, moving the <i>ulimit</i> utility, excluding the <b>-t</b> option, from the XSI option to +the Base.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/type.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/umask.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/umask.html b/bdd/umask.html @@ -0,0 +1,286 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>umask</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/ulimit.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/unalias.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="umask" id="umask"></a> <a name="tag_20_132" id="tag_20_132"></a><!-- umask --> +<h4 class="mansect"><a name="tag_20_132_01" id="tag_20_132_01"></a>NAME</h4> +<blockquote>umask — get or set the file mode creation mask</blockquote> +<h4 class="mansect"><a name="tag_20_132_02" id="tag_20_132_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>umask</tt> <b>[</b><tt>-S</tt><b>] [</b><i>mask</i><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_132_03" id="tag_20_132_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>umask</i> utility shall set the file mode creation mask of the current shell execution environment (see <a href= +"../utilities/V3_chap02.html#tag_19_13"><i>2.13 Shell Execution Environment</i></a> ) to the value specified by the <i>mask</i> +operand. This mask shall affect the initial value of the file permission bits of subsequently created files. If <i>umask</i> is +called in a subshell or separate utility execution environment, such as one of the following:</p> +<pre> +<tt>(umask 002) +nohup umask ... +find . -exec umask ... \; +</tt></pre> +<p>it shall not affect the file mode creation mask of the caller's environment.</p> +<p>If the <i>mask</i> operand is not specified, the <i>umask</i> utility shall write to standard output the value of the file mode +creation mask of the invoking process.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_132_04" id="tag_20_132_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>umask</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following option shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-S</b></dt> +<dd>Produce symbolic output.</dd> +</dl> +<p>The default output style is unspecified, but shall be recognized on a subsequent invocation of <i>umask</i> on the same system +as a <i>mask</i> operand to restore the previous file mode creation mask.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_132_05" id="tag_20_132_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>mask</i></dt> +<dd>A string specifying the new file mode creation mask. The string is treated in the same way as the <i>mode</i> operand described +in the EXTENDED DESCRIPTION section for <a href="../utilities/chmod.html"><i>chmod</i></a>. +<p>For a <i>symbolic_mode</i> value, the new value of the file mode creation mask shall be the logical complement of the file +permission bits portion of the file mode specified by the <i>symbolic_mode</i> string.</p> +<p>In a <i>symbolic_mode</i> value, the permissions <i>op</i> characters <tt>'+'</tt> and <tt>'-'</tt> shall be interpreted +relative to the current file mode creation mask; <tt>'+'</tt> shall cause the bits for the indicated permissions to be cleared in +the mask; <tt>'-'</tt> shall cause the bits for the indicated permissions to be set in the mask.</p> +<p>The interpretation of <i>mode</i> values that specify file mode bits other than the file permission bits is unspecified.</p> +<p>In the octal integer form of <i>mode</i>, the specified bits are set in the file mode creation mask.</p> +<p>The file mode creation mask shall be set to the resulting numeric value.</p> +<p>The default output of a prior invocation of <i>umask</i> on the same system with no operand also shall be recognized as a +<i>mask</i> operand.</p> +</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_132_06" id="tag_20_132_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_132_07" id="tag_20_132_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_132_08" id="tag_20_132_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>umask</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_132_09" id="tag_20_132_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_132_10" id="tag_20_132_10"></a>STDOUT</h4> +<blockquote> +<p>When the <i>mask</i> operand is not specified, the <i>umask</i> utility shall write a message to standard output that can later +be used as a <i>umask</i> <i>mask</i> operand.</p> +<p>If <b>-S</b> is specified, the message shall be in the following format:</p> +<pre> +<tt>"u=%s,g=%s,o=%s\n", <</tt><i>owner permissions</i><tt>>, <</tt><i>group permissions</i><tt>>, + <</tt><i>other permissions</i><tt>> +</tt></pre> +<p>where the three values shall be combinations of letters from the set {<i>r</i>, <i>w</i>, <i>x</i>}; the presence of a letter +shall indicate that the corresponding bit is clear in the file mode creation mask.</p> +<p>If a <i>mask</i> operand is specified, there shall be no output written to standard output.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_132_11" id="tag_20_132_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_132_12" id="tag_20_132_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_132_13" id="tag_20_132_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_132_14" id="tag_20_132_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>The file mode creation mask was successfully changed, or no <i>mask</i> operand was supplied.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_132_15" id="tag_20_132_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_132_16" id="tag_20_132_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>This utility is required to be intrinsic. See <a href="../utilities/V3_chap01.html#tag_18_07"><i>1.7 Intrinsic Utilities</i></a> +for details.</p> +<p>Since <i>umask</i> affects the current shell execution environment, it is generally provided as a shell regular built-in.</p> +<p>In contrast to the negative permission logic provided by the file mode creation mask and the octal number form of the +<i>mask</i> argument, the symbolic form of the <i>mask</i> argument specifies those permissions that are left alone.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_132_17" id="tag_20_132_17"></a>EXAMPLES</h4> +<blockquote> +<p>Either of the commands:</p> +<pre> +<tt>umask a=rx,ug+w +<br> +umask 002 +</tt></pre> +<p>sets the mode mask so that subsequently created files have their S_IWOTH bit cleared.</p> +<p>After setting the mode mask with either of the above commands, the <i>umask</i> command can be used to write out the current +value of the mode mask:</p> +<pre> +<b>$ </b><tt>umask +</tt><b>0002</b><tt> +</tt></pre> +<p>(The output format is unspecified, but historical implementations use the octal integer mode format.)</p> +<pre> +<b>$ </b><tt>umask -S +</tt><b>u=rwx,g=rwx,o=rx</b><tt> +</tt></pre> +<p>Either of these outputs can be used as the mask operand to a subsequent invocation of the <i>umask</i> utility.</p> +<p>Assuming the mode mask is set as above, the command:</p> +<pre> +<tt>umask g-w +</tt></pre> +<p>sets the mode mask so that subsequently created files have their S_IWGRP and S_IWOTH bits cleared.</p> +<p>The command:</p> +<pre> +<tt>umask -- -w +</tt></pre> +<p>sets the mode mask so that subsequently created files have all their write bits cleared. Note that <i>mask</i> operands +<b>-r</b>, <b>-w</b>, <b>-x</b> or anything beginning with a <hyphen-minus>, must be preceded by <tt>"--"</tt> to keep it +from being interpreted as an option.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_132_18" id="tag_20_132_18"></a>RATIONALE</h4> +<blockquote> +<p>Since <i>umask</i> affects the current shell execution environment, it is generally provided as a shell regular built-in. If it +is called in a subshell or separate utility execution environment, such as one of the following:</p> +<pre> +<tt>(umask 002) +nohup umask ... +find . -exec umask ... \; +</tt></pre> +<p>it does not affect the file mode creation mask of the environment of the caller.</p> +<p>The description of the historical utility was modified to allow it to use the symbolic modes of <a href= +"../utilities/chmod.html"><i>chmod</i></a>. The <b>-s</b> option used in early proposals was changed to <b>-S</b> because <b>-s</b> +could be confused with a <i>symbolic_mode</i> form of mask referring to the S_ISUID and S_ISGID bits.</p> +<p>The default output style is unspecified to permit implementors to provide migration to the new symbolic style at the time most +appropriate to their users. A <b>-o</b> flag to force octal mode output was omitted because the octal mode may not be sufficient to +specify all of the information that may be present in the file mode creation mask when more secure file access permission checks +are implemented.</p> +<p>It has been suggested that trusted systems developers might appreciate ameliorating the requirement that the mode mask +"affects" the file access permissions, since it seems access control lists might replace the mode mask to some degree. The +wording has been changed to say that it affects the file permission bits, and it leaves the details of the behavior of how they +affect the file access permissions to the description in the System Interfaces volume of POSIX.1-2024.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_132_19" id="tag_20_132_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_132_20" id="tag_20_132_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19"><i>2. Shell Command Language</i></a> , <a href= +"../utilities/chmod.html#tag_20_17"><i>chmod</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/umask.html#tag_17_645"><i>umask</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_132_21" id="tag_20_132_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_132_22" id="tag_20_132_22"></a>Issue 6</h4> +<blockquote> +<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p> +<ul> +<li> +<p>The octal mode is supported.</p> +</li> +</ul> +<p>IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/34 is applied, making a correction to the RATIONALE.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_132_23" id="tag_20_132_23"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0197 [584] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_132_24" id="tag_20_132_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 854 is applied, adding a note to the APPLICATION USAGE section that this utility is required to be +intrinsic.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/ulimit.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/unalias.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/unalias.html b/bdd/unalias.html @@ -0,0 +1,206 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>unalias</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/umask.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/uname.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="unalias" id="unalias"></a> <a name="tag_20_133" id="tag_20_133"></a><!-- unalias --> +<h4 class="mansect"><a name="tag_20_133_01" id="tag_20_133_01"></a>NAME</h4> +<blockquote>unalias — remove alias definitions</blockquote> +<h4 class="mansect"><a name="tag_20_133_02" id="tag_20_133_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>unalias</tt> <i>alias-name</i><tt>...<br> +<br> +unalias -a<br></tt></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_133_03" id="tag_20_133_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>unalias</i> utility shall remove the definition for each alias name specified. See <a href= +"../utilities/V3_chap02.html#tag_19_03_01"><i>2.3.1 Alias Substitution</i></a> . The aliases shall be removed from the current +shell execution environment; see <a href="../utilities/V3_chap02.html#tag_19_13"><i>2.13 Shell Execution Environment</i></a> .</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_133_04" id="tag_20_133_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>unalias</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following option shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-a</b></dt> +<dd>Remove all alias definitions from the current shell execution environment.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_133_05" id="tag_20_133_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>alias-name</i></dt> +<dd>The name of an alias to be removed.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_133_06" id="tag_20_133_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_133_07" id="tag_20_133_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_133_08" id="tag_20_133_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>unalias</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_133_09" id="tag_20_133_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_133_10" id="tag_20_133_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_133_11" id="tag_20_133_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_133_12" id="tag_20_133_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_133_13" id="tag_20_133_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_133_14" id="tag_20_133_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>One of the <i>alias-name</i> operands specified did not represent a valid alias definition, or an error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_133_15" id="tag_20_133_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_133_16" id="tag_20_133_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>This utility is required to be intrinsic. See <a href="../utilities/V3_chap01.html#tag_18_07"><i>1.7 Intrinsic Utilities</i></a> +for details.</p> +<p>Since <i>unalias</i> affects the current shell execution environment, it is generally provided as a shell regular built-in.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_133_17" id="tag_20_133_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_133_18" id="tag_20_133_18"></a>RATIONALE</h4> +<blockquote> +<p>The <i>unalias</i> description is based on that from historical KornShell implementations. Known differences exist between that +and the C shell. The KornShell version was adopted to be consistent with all the other KornShell features in this volume of +POSIX.1-2024, such as command line editing.</p> +<p>The <b>-a</b> option is the equivalent of the <i>unalias</i> * form of the C shell and is provided to address security concerns +about unknown aliases entering the environment of a user (or application) through the allowable implementation-defined predefined +alias route or as a result of an <i>ENV</i> file. (Although <i>unalias</i> could be used to simplify the "secure" shell script +shown in the <a href="../utilities/command.html"><i>command</i></a> rationale, it does not obviate the need to quote all command +names. An initial call to <i>unalias</i> <b>-a</b> would have to be quoted in case there was an alias for <i>unalias</i>.)</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_133_19" id="tag_20_133_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_133_20" id="tag_20_133_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19"><i>2. Shell Command Language</i></a> , <a href= +"../utilities/alias.html#"><i>alias</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_133_21" id="tag_20_133_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_133_22" id="tag_20_133_22"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_133_23" id="tag_20_133_23"></a>Issue 7</h4> +<blockquote> +<p>The <i>unalias</i> utility is moved from the User Portability Utilities option to the Base. User Portability Utilities is now an +option for interactive utilities.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_133_24" id="tag_20_133_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 854 is applied, adding a note to the APPLICATION USAGE section that this utility is required to be +intrinsic.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/umask.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/uname.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/uname.html b/bdd/uname.html @@ -0,0 +1,215 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>uname</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/unalias.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/uncompress.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="uname" id="uname"></a> <a name="tag_20_134" id="tag_20_134"></a><!-- uname --> +<h4 class="mansect"><a name="tag_20_134_01" id="tag_20_134_01"></a>NAME</h4> +<blockquote>uname — return system name</blockquote> +<h4 class="mansect"><a name="tag_20_134_02" id="tag_20_134_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>uname</tt> <b>[</b><tt>-amnrsv</tt><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_134_03" id="tag_20_134_03"></a>DESCRIPTION</h4> +<blockquote> +<p>By default, the <i>uname</i> utility shall write the operating system name to standard output. When options are specified, +symbols representing one or more system characteristics shall be written to the standard output. The format and contents of the +symbols are implementation-defined. On systems conforming to the System Interfaces volume of POSIX.1-2024, the symbols written +shall be those supported by the <a href="../functions/uname.html"><i>uname</i>()</a> function as defined in the System Interfaces +volume of POSIX.1-2024.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_134_04" id="tag_20_134_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>uname</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-a</b></dt> +<dd>Behave as though all of the options <b>-mnrsv</b> were specified.</dd> +<dt><b>-m</b></dt> +<dd>Write the name of the hardware type on which the system is running to standard output.</dd> +<dt><b>-n</b></dt> +<dd>Write the name of this node within an implementation-defined communications network.</dd> +<dt><b>-r</b></dt> +<dd>Write the current release level of the operating system implementation.</dd> +<dt><b>-s</b></dt> +<dd>Write the name of the implementation of the operating system.</dd> +<dt><b>-v</b></dt> +<dd>Write the current version level of this release of the operating system implementation.</dd> +</dl> +<p>If no options are specified, the <i>uname</i> utility shall write the operating system name, as if the <b>-s</b> option had been +specified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_134_05" id="tag_20_134_05"></a>OPERANDS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_134_06" id="tag_20_134_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_134_07" id="tag_20_134_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_134_08" id="tag_20_134_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>uname</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_134_09" id="tag_20_134_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_134_10" id="tag_20_134_10"></a>STDOUT</h4> +<blockquote> +<p>By default, the output shall be a single line of the following form:</p> +<pre> +<tt>"%s\n", <</tt><i>sysname</i><tt>> +</tt></pre> +<p>If the <b>-a</b> option is specified, the output shall be a single line of the following form:</p> +<pre> +<tt>"%s %s %s %s %s\n", <</tt><i>sysname</i><tt>>, <</tt><i>nodename</i><tt>>, <</tt><i>release</i><tt>>, + <</tt><i>version</i><tt>>, <</tt><i>machine</i><tt>> +</tt></pre> +<p>Additional implementation-defined symbols may be written; all such symbols shall be written at the end of the line of output +before the <newline>.</p> +<p>If options are specified to select different combinations of the symbols, only those symbols shall be written, in the order +shown above for the <b>-a</b> option. If a symbol is not selected for writing, its corresponding trailing <blank> characters +also shall not be written.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_134_11" id="tag_20_134_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_134_12" id="tag_20_134_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_134_13" id="tag_20_134_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_134_14" id="tag_20_134_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>The requested information was successfully written.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_134_15" id="tag_20_134_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_134_16" id="tag_20_134_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Note that any of the symbols could include embedded <space> characters, which may affect parsing algorithms if multiple +options are selected for output.</p> +<p>The node name is typically a name that the system uses to identify itself for inter-system communication addressing.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_134_17" id="tag_20_134_17"></a>EXAMPLES</h4> +<blockquote> +<p>The following command:</p> +<pre> +<tt>uname -sr +</tt></pre> +<p>writes the operating system name and release level, separated by one or more <blank> characters.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_134_18" id="tag_20_134_18"></a>RATIONALE</h4> +<blockquote> +<p>It was suggested that this utility cannot be used portably since the format of the symbols is implementation-defined. The +POSIX.1 working group could not achieve consensus on defining these formats in the underlying <a href= +"../functions/uname.html"><i>uname</i>()</a> function, and there was no expectation that this volume of POSIX.1-2024 would be any +more successful. Some applications may still find this historical utility of value. For example, the symbols could be used for +system log entries or for comparison with operator or user input.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_134_19" id="tag_20_134_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_134_20" id="tag_20_134_20"></a>SEE ALSO</h4> +<blockquote> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/uname.html#tag_17_646"><i>uname</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_134_21" id="tag_20_134_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_134_22" id="tag_20_134_22"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/unalias.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/uncompress.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/uncompress.html b/bdd/uncompress.html @@ -0,0 +1,627 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!doctype HTML> +<html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><link type="text/css" rel="stylesheet" href="style.css"> +<!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>compress</title> +</head><body bgcolor="white"><DIV CLASS="NAVHEADER"> +<TABLE SUMMARY="Header navigation table" class="nav" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0"> +<TR class="nav"><TD class="nav" WIDTH="15%" ALIGN="left" VALIGN="bottom"><A href="../utilities/command.html" ACCESSKEY="P" ><<< Previous</A></TD><TD class="nav" WIDTH="70%" ALIGN="center" VALIGN="bottom" ><a href="contents.html">Home</a></TD><TD class="nav" WIDTH="15%" ALIGN="right" VALIGN="bottom"> <A href="../utilities/cp.html" ACCESSKEY="N" >Next >>></A></TD></TR></TABLE><HR ALIGN="LEFT" WIDTH="100%"></DIV> +<script LANGUAGE="JavaScript" src="../jscript/codes.js"></script><basefont size=3> +<center><font size="2"> +The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top"></a> + +<a name="compress"></a> +<a name = "tag_20_23"></a><!-- compress --> + + + +<h4 class="mansect"><a name = "tag_20_23_01"></a>NAME</h4><blockquote> +compress, uncompress, zcat — compress and decompress data + + + + + + +</blockquote><h4 class="mansect"><a name = "tag_20_23_02"></a>SYNOPSIS</h4><blockquote class="synopsis"> +<p> +<p> +<tt><div class="box"><code><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> +<img src="../images/opt-start.gif" alt="[Option Start]" border=0> +compress </tt><b>[</b><tt>-fv</tt><b>] [</b><tt>-b </tt><i>value</i><b>] [</b><tt>-g | -m </tt><i>algo</i><b>] [</b><i>file</i><tt>...</tt><b>]</b><tt> +<br> +<br> +compress -c </tt><b>[</b><tt>-fv</tt><b>] [</b><tt>-b </tt><i>value</i><b>] [</b><tt>-g | -m </tt><i>algo</i><b>] [</b><i>file</i><b>]</b><tt> +<br> +<br> +compress -d </tt><b>[</b><tt>-cfv</tt><b>] [</b><i>file</i><tt>...</tt><b>]</b><tt> +<br> +<br> +uncompress </tt><b>[</b><tt>-cfv</tt><b>] [</b><i>file</i><tt>...</tt><b>]</b><tt> +<br> +<br> +zcat </tt><b>[</b><i>file</i><tt>...</tt><b>]</b><tt> +<img src="../images/opt-end.gif" alt="[Option End]" border=0> +</code></div> +<br> +</tt> +</blockquote><h4 class="mansect"><a name = "tag_20_23_03"></a>DESCRIPTION</h4><blockquote> +<p> +The +<i>compress</i> +utility, when the +<b>-d</b> +option is not specified, shall apply the compression algorithm identified +by the +<b>-g</b> +option or the +<b>-m</b> +<i>algo</i> +option to the named files to attempt to reduce their size without loss +of information. The compress utility with the +<b>-d</b> +option shall apply the appropriate decompression algorithm to the +named files to restore the data to their original state. +<p> +The +<i>uncompress</i> +utility shall be equivalent to +<i>compress</i> +<b>-d</b>. +The +<i>zcat</i> +utility shall be equivalent to +<i>compress</i> +<b>-c -d</b>. +If multiple +<i>file</i> +operands are specified, the decompressed data from each input file +shall be concatenated to standard output. +<p> +When compressing data, unless the +<b>-c</b> +option is specified, after an input file other than standard input has +been compressed, the compressed data from the input file shall be +stored in a file with the same pathname as the input file but with an +added suffix. The added suffix shall be the suffix associated with the +algorithm (see the algorithms in +<a href="#tagtcjh_17"> +Compression algorithms, algo option-argument values, and suffixes +</a> +). +If appending the suffix would make the size of the last component of +the output file's pathname exceed +{NAME_MAX} +bytes, the command shall fail. If appending the suffix would make the +size of the pathname exceed +{PATH_MAX} +bytes, the command may fail. +<p> +When decompressing data, unless the +<b>-c</b> +option is specified, after an input file other than standard input has +been decompressed, the decompressed data from the input file shall be +stored in a file with the same pathname as the input file but with the +suffix associated with the algorithm removed. +<sup>[<a href="javascript:open_code('OB')">OB</a>]</sup> +<img src="../images/opt-start.gif" alt="[Option Start]" border=0> + If +<i>file</i> +has no suffix associated with a known compression algorithm or +<i>file</i> +does not exist and does not have a +<b>.Z</b> +suffix, +<i>file</i> +shall be used as the name of the output file, and the default suffix +<b>.Z</b> +shall be appended to +<i>file</i> +to form the input pathname. +<img src="../images/opt-end.gif" alt="[Option End]" border=0> +The behavior is unspecified if the input pathname ends with a suffix +other than the suffix associated with the algorithm used to compress +the data. When the +<b>-c</b> +option is specified, +<i>file</i> +can have any suffix, or no suffix, and the utility shall use +<i>file</i> +as the input file and examine the file's contents to determine which +algorithm to use to decompress the data (it is not an error if +<i>file</i> +does not have a suffix that matches the suffix associated with the +compression algorithm). +<p> +When compressing or decompressing a file other than standard input and the +<b>-c</b> +option is not specified, if the invoking process has sufficient privilege, +the ownership, modes, access time, and modification time of the output +file shall match the ownership, modes, access time, and modification +time of the input file. After the output file has been successfully +created, the input file shall be removed if the invoking process has +sufficient privileges. If the invoking process does not have sufficient +privileges to remove the input file (for example, if the directory has +the S_ISVTX bit set) the behavior depends on whether the +<b>-f</b> +option is specified: if +<b>-f</b> +is not specified, the output file shall be removed, a diagnostic +message shall be written and the utility shall continue processing +other files but the final exit status shall be non-zero; if +<b>-f</b> +is specified, the output file shall not be removed and it is +unspecified whether the inability to remove the input file is treated +as an error. If it is not treated as an error, a warning message may +be written to standard error +<p> +If no +<i>file</i> +operands are specified, standard input shall be compressed or +decompressed to standard output. +<p> +<sup>[<a href="javascript:open_code('OB')">OB</a>]</sup> +<img src="../images/opt-start.gif" alt="[Option Start]" border=0> +If an input file that is to be removed after processing has multiple +hard links, the +<i>compress</i> +and +<i>uncompress</i> +utilities may write a diagnostic message to standard error and do +nothing with the file; this behavior may depend on whether the +<b>-f</b> +option is specified. If a diagnostic message is written, the final +exit status shall be non-zero. +<img src="../images/opt-end.gif" alt="[Option End]" border=0> +</blockquote><h4 class="mansect"><a name = "tag_20_23_04"></a>OPTIONS</h4><blockquote> +<p> +The +<i>compress</i>, +<i>uncompress</i>, +and +<i>zcat</i> +utilities shall conform to XBD +<a href="../basedefs/V1_chap12.html#tag_12_02"> +<i>12.2 Utility Syntax Guidelines</i> +</a> +, +except that Guideline 1 does not apply to +<i>uncompress</i> +since the utility name has ten letters. +<p> +The following options shall be supported: +<dl compact><dd> +<p><dt><b>-b </b><i>value</i><dd>If the compression algorithm is LZW, +<i>value</i> +specifies the maximum number of bits to use in a code. For a +conforming application, the +<i>value</i> +argument shall be: +<pre> +<tt>9 <= </tt><i>value</i><tt> <= 16 +</tt></pre> +<p> +The implementation may allow values of greater than 16. The default +shall be 14, 15, or 16. +<p> +If the compression algorithm is DEFLATE, +<i>value</i> +specifies the compression level. For a conforming application, the +<i>value</i> +argument shall be: +<pre> +<tt>1 <= </tt><i>value</i><tt> <= 9 +</tt></pre> +<p> +The default shall be 6. +<p> +For other algorithms, value specifies implementation-defined tuning. +<p><dt><b>-c</b><dd>Write to standard output; the input files shall not be changed, and no +output files shall be created. +<p><dt><b>-d</b><dd>Decompress files. When invoked with the +<b>-d</b> +option, the +<i>compress</i> +utility shall restore previously compressed files to their original state. +<p><dt><b>-f</b><dd>Force compression or decompression of file, even if it does not (for +compression) actually reduce the size of the file, or if the +corresponding output file already exists. If the +<b>-f</b> +option is not given and the standard input is a terminal, the user +shall be prompted as to whether an existing output file should be +overwritten. If the response is affirmative, the existing file shall +be overwritten. If the standard input is not a terminal and +<b>-f</b> +is not given, +<i>compress</i> +or +<i>uncompress</i> +shall write a diagnostic message to standard error, the existing file +shall not be overwritten, and the utility shall exit with a status +greater than zero. If the +<b>-f</b> +option is specified and an input file other than standard input has +multiple hard links, it is implementation-defined whether the input +file is unlinked after the corresponding output file is successfully +written, or if processing of that file is skipped and a diagnostic +message is written to standard error. +<p><dt><b>-g</b><dd>Equivalent to +<b>-m</b> +<i>gzip</i>. +<p><dt><b>-m </b><i>algo</i><dd>Use the algorithm defined by +<i>algo</i> +to compress the files. The following algorithms shall be supported: +<br> +<p class="caption"><xref table="Compression algorithms, algo option-argument values, and suffixes"><a name="tagtcjh_17"></a> +Table: Compression algorithms, algo option-argument values, and suffixes</p> + + +<p> +<center> +<p> +<table border=1 cellpadding=3 align=center> +<tr valign=top><th align=center><p class="tent"><b>Algorithm</b></p></th> +<th align=center><p class="tent">algo</p></th> +<th align=center><p class="tent"><b>Filename Suffix</b></p></th> +</p></tr> +<tr valign=top><td align=left><p class="tent">Adaptive LZW +<td align=left><p class="tent"><b>lzw</b> +<td align=left><p class="tent"><b>.Z</b> +</p></tr> +<tr valign=top><td align=left><p class="tent">RFC1951 DEFLATE +<td align=left><p class="tent"><b>deflate</b> +<td align=left><p class="tent"><b>.gz</b> +</p></tr> +<tr valign=top><td align=left><p class="tent">Synonym for DEFLATE +<td align=left><p class="tent"><b>gzip</b> +<td align=left><p class="tent"><b>.gz</b> +</tr> +</table> +</center> +<p class="tent"> +Other implementation-defined algorithms may be supported. +<p class="tent"> +If neither of the +<b>-m</b> +<i>algo</i> +and +<b>-g</b> +options is specified, +<b>lzw</b> +shall be used as a default +<i>algo</i> +value. Specifying more than one of the mutually exclusive +<b>-g</b> +and +<b>-m</b> +<i>algo</i> +options, or multiple +<b>-m</b> +<i>algo</i> +options, shall not be considered an error. The last option specified +shall determine the behavior of the utility. +<p class="tent"> +On systems not supporting the selected algorithm, the input files +shall not be changed and an exit status greater than two shall be +returned. +<basefont size=2> +<dl><dt><b>Note:</b> +<dd>The Lempel-Ziv compression algorithm is described in the now-expired +US Patent 4464650, which was issued to William Eastman, Abraham Lempel, +Jacob Ziv, and Martin Cohn on August 7th, 1984 and assigned to Sperry +Corporation. +<p class="tent"> +The Lempel-Ziv-Welch compression algorithm is described in the +now-expired US Patent 4558302, which was issued to Terry A. Welch on +December 10th, 1985 and assigned to Sperry Corporation. +</dl> +<basefont size=3> +<p><dt><b>-v</b><dd>For +<i>compress</i>, +write the percentage reduction of each file to standard error. For +<i>uncompress</i>, +write messages to standard error concerning the expansion of each file. +</dl> +</blockquote><h4 class="mansect"><a name = "tag_20_23_05"></a>OPERANDS</h4><blockquote> +<p> +The following operand shall be supported: +<dl compact><dd> +<p><dt><i>file</i><dd>A pathname of a file to be compressed or decompressed. If a +<i>file</i> +is +<tt>'-'</tt>, +the utility shall read from standard input at that point in the +sequence and write to standard output. If more than one +<i>file</i> +operand is +<tt>'-'</tt>, +the behavior is unspecified. +</dl> +</blockquote><h4 class="mansect"><a name = "tag_20_23_06"></a>STDIN</h4><blockquote> +<p> +The standard input shall be used only if no +<i>file</i> +operands are specified, or if a +<i>file</i> +operand is +<tt>'-'</tt>. +</blockquote><h4 class="mansect"><a name = "tag_20_23_07"></a>INPUT FILES</h4><blockquote> +<p> +If +<i>file</i> +operands are specified, the corresponding input files contain the data +to be compressed or decompressed. +</blockquote><h4 class="mansect"><a name = "tag_20_23_08"></a>ENVIRONMENT VARIABLES</h4><blockquote> +<p> +The following environment variables shall affect the execution of +<i>compress</i>: +<dl compact><dd> +<p><dt><i>LANG</i><dd>Provide a default value for the internationalization variables that are +unset or null. (See XBD +<a href="../basedefs/V1_chap08.html#tag_08_02"> +<i>8.2 Internationalization Variables</i> +</a> +for the precedence of internationalization variables used to determine +the values of locale categories.) +<p><dt><i>LC_ALL</i><dd>If set to a non-empty string value, override the values of all the +other internationalization variables. +<p><dt><i>LC_COLLATE</i><dd><br> +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements used in the extended regular +expression defined for the +<b>yesexpr</b> +locale keyword in the +<i>LC_MESSAGES</i> +category. +<p><dt><i>LC_CTYPE</i><dd>Determine the locale for the interpretation of sequences of bytes of text +data as characters (for example, single-byte as opposed to multi-byte +characters in arguments), the behavior of character classes used in the +extended regular expression defined for the +<b>yesexpr</b> +locale keyword in the +<i>LC_MESSAGES</i> +category. +<p><dt><i>LC_MESSAGES</i><dd><br> +Determine the locale used to process affirmative responses, and the +locale used to affect the format and contents of diagnostic messages, +prompts, and the output from the +<b>-v</b> +option written to standard error. +<p><dt><i>NLSPATH</i><dd>Determine the location of messages objects and message catalogs. +</dl> +</blockquote><h4 class="mansect"><a name = "tag_20_23_09"></a>ASYNCHRONOUS EVENTS</h4><blockquote> +<p> +Default. +</blockquote><h4 class="mansect"><a name = "tag_20_23_10"></a>STDOUT</h4><blockquote> +<p> +For the +<i>compress</i> +and +<i>uncompress</i> +utilities, the standard output shall be used if no +<i>file</i> +operands are specified, if a +<i>file</i> +operand is +<tt>'-'</tt>, +or if the +<b>-c</b> +option is specified. Otherwise, the standard output shall not be used. +<p class="tent"> +The +<i>zcat</i> +utility shall write the decompressed data to the standard output. +</blockquote><h4 class="mansect"><a name = "tag_20_23_11"></a>STDERR</h4><blockquote> +<p> +The standard error shall be used only for diagnostic and prompt +messages, the optional warning message described in DESCRIPTION, and +the output from +<b>-v</b>. +</blockquote><h4 class="mansect"><a name = "tag_20_23_12"></a>OUTPUT FILES</h4><blockquote> +<p> +When decompressing input files other than standard input, the +corresponding output files shall contain the decompressed input data. +When compressing input files other than standard input, the +corresponding output files shall contain the compressed input data. +If the selected +<i>algo</i> +is +<b>deflate</b> +or +<b>gzip</b>, +the compressed output shall be in the GZIP format described in RFC 1952. +For other algorithms, the compressed output file format is +implementation-defined and interchange of such files between +implementations (including access via unspecified file sharing +mechanisms) is not required by POSIX.1-2024. +</blockquote><h4 class="mansect"><a name = "tag_20_23_13"></a>EXTENDED DESCRIPTION</h4><blockquote> +<p> +None. +</blockquote><h4 class="mansect"><a name = "tag_20_23_14"></a>EXIT STATUS</h4><blockquote> +<p> +The following exit values shall be returned for +<i>compress</i>: +<dl compact><dd> +<p><dt> 0<dd>Successful completion. +<p><dt> 1<dd>An error occurred. +<p><dt> 2<dd>One or more files were not compressed because they would have increased +in size (and the +<b>-f</b> +option was not specified). +<p><dt>>2<dd>An error occurred. +</dl> +<p class="tent"> +The following exit values shall be returned for +<i>uncompress</i> +and +<i>zcat</i>: +<dl compact><dd> +<p><dt> 0<dd>Successful completion. +<p><dt>>0<dd>An error occurred. +</dl> +</blockquote><h4 class="mansect"><a name = "tag_20_23_15"></a>CONSEQUENCES OF ERRORS</h4><blockquote> +<p> +If an error occurs while compressing or decompressing an input file +other than standard input, the input file shall remain unmodified. +</blockquote> +<hr><div class="box"><em>The following sections are informative.</em></div> +<blockquote> +</blockquote><h4 class="mansect"><a name = "tag_20_23_16"></a>APPLICATION USAGE</h4><blockquote> +<p> +The amount of compression obtained depends on the size of the input, +the number of bits +per code, and the distribution of common substrings. Typically, text +such as source code or English is reduced by 50-60%. Compression is +generally much better than that achieved by Huffman coding +or adaptive Huffman coding (<i>compact</i>), +and takes less time to compute. +<p class="tent"> +Although +<i>compress</i> +strictly follows the default actions upon receipt of a signal or when +an error occurs, some unexpected results may occur. In some +implementations it is likely that a partially compressed file is left +in place, alongside its uncompressed input file. Since the general +operation of +<i>compress</i> +is to delete the uncompressed file only after the +<b>.Z</b> +file has been successfully filled, an application should always +carefully check the exit status of +<i>compress</i> +before arbitrarily deleting files that have like-named neighbors with +<b>.Z</b> +suffixes. +<p class="tent"> +In addition to trying +<i>file</i> +and +<i>file</i><b>.Z</b> +when looking for a file to decompress, some implementations of +<i>uncompress</i> +and +<i>zcat</i> +also try suffixes for other known compression algorithms if neither +<i>file</i> +nor +<i>file</i><b>.Z</b> +is found. This version of the standard allows, but does not require +this behavior. Portable applications should always specify the full +pathname (including the suffix) of files to be decompressed. +</blockquote><h4 class="mansect"><a name = "tag_20_23_17"></a>EXAMPLES</h4><blockquote> +<p> +None. +</blockquote><h4 class="mansect"><a name = "tag_20_23_18"></a>RATIONALE</h4><blockquote> +<p> +Earlier versions of this standard limited the number of bits used by +conforming applications for the +<b>lzw</b> +algorithm to 14 due to address space limitations on 16-bit +architectures. Using 15 or 16 is a much more common default when using +current hardware. +<p class="tent"> +Earlier versions of this standard only supported LZW compression. The +standard developers noted that existing implementations added other +compression utilities, such as +<i>gzip</i>, +and found it desirable to support this widespread usage. Some +implementations had extended the +<i>compress</i> +utility to support such other schemes. The standard developers +generalized this practice by the addition of the +<b>-m</b> +option, even though this was not previous practice. +<p class="tent"> +The +<i>uncompress</i> +<b>-d</b> +option is added to match undocumented existing practice of tested +implementations. +</blockquote><h4 class="mansect"><a name = "tag_20_23_19"></a>FUTURE DIRECTIONS</h4><blockquote> +<p> +If this utility is directed to create a new directory entry that +contains any bytes that have the encoded value of a +<newline> +character, implementations are encouraged to treat this as an error. +A future version of this standard may require implementations to treat +this as an error. +<p class="tent"> +When decompressing a file, the requirement to add +<b>.Z</b> +to a +<i>file</i> +operand if the given pathname does not include a suffix associated +with a known compression algorithm or if +<i>file</i> +does not exist and does not already have a +<b>.Z</b> +extension is an obsolescent feature and may be removed in a future version. +</blockquote><h4 class="mansect"><a name = "tag_20_23_20"></a>SEE ALSO</h4><blockquote> +<p> +XBD +<a href="../basedefs/V1_chap08.html#tag_08"> +<i>8. Environment Variables</i> +</a> +, +<a href="../basedefs/V1_chap12.html#tag_12_02"> +<i>12.2 Utility Syntax Guidelines</i> +</a> +</blockquote><h4 class="mansect"><a name = "tag_20_23_21"></a>CHANGE HISTORY</h4><blockquote> +<p> +First released in Issue 4. +</blockquote><h4 class="mansect"><a name = "tag_20_23_22"></a>Issue 6</h4><blockquote> +<p> +The normative text is reworded to avoid use of the term "must" +for application requirements. +<p class="tent"> +An error case is added for systems not supporting adaptive Lempel-Ziv +coding. +</blockquote><h4 class="mansect"><a name = "tag_20_23_23"></a>Issue 7</h4><blockquote> +<p> +SD5-XCU-ERN-97 is applied, updating the SYNOPSIS. +<p class="tent"> +Austin Group Interpretation 1003.1-2001 #125 is applied, revising +the ENVIRONMENT VARIABLES section. +</blockquote><h4 class="mansect"><a name = "tag_20_23_24"></a>Issue 8</h4><blockquote> +<p> +Austin Group Defect 251 is applied, encouraging implementations to +disallow the creation of filenames containing any bytes that have the +encoded value of a +<newline> +character. +<p class="tent"> +Austin Group Defect 1041 is applied, combining the +<i>compress</i>, +<i>uncompress</i> +and +<i>zcat</i> +pages into one and extensively modifying most sections. +<p class="tent"> +Austin Group Defect 1122 is applied, changing the description of +<i>NLSPATH . +</i></blockquote> +<div class="box"><em>End of informative text.</em></div><hr> +<blockquote> +</blockquote> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | +<a href="../basedefs/contents.html">XBD</a> | +<a href="../functions/contents.html">XSH</a> | +<a href="../utilities/contents.html">XCU</a> | +<a href="../xrat/contents.html">XRAT</a> ] +</font></center> +<hr size="2" noshade> + +<DIV CLASS="NAVHEADER"> +<TABLE SUMMARY="Header navigation table" class="nav" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0"> +<TR class="nav"><TD class="nav" WIDTH="15%" ALIGN="left" VALIGN="bottom"><A href="../utilities/command.html" ACCESSKEY="P" ><<< Previous</A></TD><TD class="nav" WIDTH="70%" ALIGN="center" VALIGN="bottom" ><a href="contents.html">Home</a></TD><TD class="nav" WIDTH="15%" ALIGN="right" VALIGN="bottom"> <A href="../utilities/cp.html" ACCESSKEY="N" >Next >>></A></TD></TR></TABLE><HR ALIGN="LEFT" WIDTH="100%"></DIV></body></html> diff --git a/bdd/unexpand.html b/bdd/unexpand.html @@ -0,0 +1,227 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>unexpand</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/uncompress.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/unget.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="unexpand" id="unexpand"></a> <a name="tag_20_136" id="tag_20_136"></a><!-- unexpand --> +<h4 class="mansect"><a name="tag_20_136_01" id="tag_20_136_01"></a>NAME</h4> +<blockquote>unexpand — convert spaces to tabs</blockquote> +<h4 class="mansect"><a name="tag_20_136_02" id="tag_20_136_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>unexpand</tt> <b>[</b><tt>-a|-t</tt> <i>tablist</i><b>] [</b><i>file</i><tt>...</tt><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_136_03" id="tag_20_136_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>unexpand</i> utility shall copy files or standard input to standard output, converting <blank> characters at the +beginning of each line into the maximum number of <tab> characters followed by the minimum number of <space> characters +needed to fill the same column positions originally filled by the translated <blank> characters. By default, tabstops shall +be set at every eighth column position. Each <backspace> shall be copied to the output, and shall cause the column position +count for tab calculations to be decremented; the count shall never be decremented to a value less than one.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_136_04" id="tag_20_136_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>unexpand</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-a</b></dt> +<dd>In addition to translating <blank> characters at the beginning of each line, translate all sequences of two or more +<blank> characters immediately preceding a tab stop to the maximum number of <tab> characters followed by the minimum +number of <space> characters needed to fill the same column positions originally filled by the translated <blank> +characters.</dd> +<dt><b>-t </b><i>tablist</i></dt> +<dd>Specify the tab stops. The application shall ensure that the <i>tablist</i> option-argument is a single argument consisting of +a single positive decimal integer or multiple positive decimal integers, separated by <blank> or <comma> characters, in +ascending order. If a single number is given, tabs shall be set <i>tablist</i> column positions apart instead of the default 8. If +multiple numbers are given, the tabs shall be set at those specific column positions. +<p>The application shall ensure that each tab-stop position <i>N</i> is an integer value greater than zero, and the list shall be +in strictly ascending order. This is taken to mean that, from the start of a line of output, tabbing to position <i>N</i> shall +cause the next character output to be in the (<i>N</i>+1)th column position on that line. When the <b>-t</b> option is not +specified, the default shall be the equivalent of specifying <b>-t 8</b> (except for the interaction with <b>-a</b>, described +below).</p> +<p>No <space>-to-<tab> conversions shall occur for characters at positions beyond the last of those specified in a +multiple tab-stop list.</p> +<p>When <b>-t</b> is specified, the presence or absence of the <b>-a</b> option shall be ignored; conversion shall not be limited +to the processing of leading <blank> characters.</p> +</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_136_05" id="tag_20_136_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of a text file to be used as input.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_136_06" id="tag_20_136_06"></a>STDIN</h4> +<blockquote> +<p>See the INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_136_07" id="tag_20_136_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files shall be text files.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_136_08" id="tag_20_136_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>unexpand</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files), the processing of <tab> and <space> characters, and for +the determination of the width in column positions each character would occupy on an output device.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_136_09" id="tag_20_136_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_136_10" id="tag_20_136_10"></a>STDOUT</h4> +<blockquote> +<p>The standard output shall be equivalent to the input files with the specified <space>-to-<tab> conversions.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_136_11" id="tag_20_136_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_136_12" id="tag_20_136_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_136_13" id="tag_20_136_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_136_14" id="tag_20_136_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_136_15" id="tag_20_136_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_136_16" id="tag_20_136_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>One non-intuitive aspect of <i>unexpand</i> is its restriction to leading <space> characters when neither <b>-a</b> nor +<b>-t</b> is specified. Users who always want to convert all <space> characters in a file can easily alias <i>unexpand</i> to +use the <b>-a</b> or <b>-t 8</b> option.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_136_17" id="tag_20_136_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_136_18" id="tag_20_136_18"></a>RATIONALE</h4> +<blockquote> +<p>On several occasions, consideration was given to adding a <b>-t</b> option to the <i>unexpand</i> utility to complement the +<b>-t</b> in <a href="../utilities/expand.html"><i>expand</i></a> (see <a href="../utilities/expand.html#"><i>expand</i></a> ). The +historical intent of <i>unexpand</i> was to translate multiple <blank> characters into tab stops, where tab stops were a +multiple of eight column positions on most UNIX systems. An early proposal omitted <b>-t</b> because it seemed outside the scope of +the User Portability Utilities option; it was not described in any of the base documents for IEEE Std 1003.2-1992. +However, hard-coding tab stops every eight columns was not suitable for the international community and broke historical precedents +for some vendors in the FORTRAN community, so <b>-t</b> was restored in conjunction with the list of valid extension categories +considered by the standard developers. Thus, <i>unexpand</i> is now the logical converse of <a href= +"../utilities/expand.html"><i>expand</i></a>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_136_19" id="tag_20_136_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_136_20" id="tag_20_136_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/expand.html#"><i>expand</i></a> , <a href="../utilities/tabs.html#"><i>tabs</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_136_21" id="tag_20_136_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_136_22" id="tag_20_136_22"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +<p>The definition of the <i>LC_CTYPE</i> environment variable is changed to align with the IEEE P1003.2b draft standard.</p> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_136_23" id="tag_20_136_23"></a>Issue 7</h4> +<blockquote> +<p>The <i>unexpand</i> utility is moved from the User Portability Utilities option to the Base. User Portability Utilities is now +an option for interactive utilities.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0198 [885] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_136_24" id="tag_20_136_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/uncompress.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/unget.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/unget.html b/bdd/unget.html @@ -0,0 +1,218 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>unget</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/unexpand.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/uniq.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="unget" id="unget"></a> <a name="tag_20_137" id="tag_20_137"></a><!-- unget --> +<h4 class="mansect"><a name="tag_20_137_01" id="tag_20_137_01"></a>NAME</h4> +<blockquote>unget — undo a previous get of an SCCS file (<b>DEVELOPMENT</b>)</blockquote> +<h4 class="mansect"><a name="tag_20_137_02" id="tag_20_137_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> unget</tt> <b>[</b><tt>-ns</tt><b>] [</b><tt>-r</tt> <i>SID</i><b>]</b> <i>file</i><tt>... <img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div> +</blockquote> +<h4 class="mansect"><a name="tag_20_137_03" id="tag_20_137_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>unget</i> utility shall reverse the effect of a <a href="../utilities/get.html"><i>get</i></a> <b>-e</b> done prior to +creating the intended new delta.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_137_04" id="tag_20_137_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>unget</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-r </b><i>SID</i></dt> +<dd>Uniquely identify which delta is no longer intended. (This would have been specified by <a href= +"../utilities/get.html"><i>get</i></a> as the new delta.) The use of this option is necessary only if two or more outstanding +<a href="../utilities/get.html"><i>get</i></a> commands for editing on the same SCCS file were done by the same person (login +name).</dd> +<dt><b>-s</b></dt> +<dd>Suppress the writing to standard output of the intended delta's SID.</dd> +<dt><b>-n</b></dt> +<dd>Retain the file that was obtained by <a href="../utilities/get.html"><i>get</i></a>, which would normally be removed from the +current directory.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_137_05" id="tag_20_137_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of an existing SCCS file or a directory. If <i>file</i> is a directory, the <i>unget</i> utility shall behave as +though each file in the directory were specified as a named file, except that non-SCCS files (last component of the pathname does +not begin with <b>s.</b>) and unreadable files shall be silently ignored. +<p>If exactly one <i>file</i> operand appears, and it is <tt>'-'</tt>, the standard input shall be read; each line of the standard +input shall be taken to be the name of an SCCS file to be processed. Non-SCCS files and unreadable files shall be silently +ignored.</p> +</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_137_06" id="tag_20_137_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be a text file used only when the <i>file</i> operand is specified as <tt>'-'</tt>. Each line of the +text file shall be interpreted as an SCCS pathname.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_137_07" id="tag_20_137_07"></a>INPUT FILES</h4> +<blockquote> +<p>Any SCCS files processed shall be files of an unspecified format.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_137_08" id="tag_20_137_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>unget</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd>Determine the location of messages objects and message catalogs.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_137_09" id="tag_20_137_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_137_10" id="tag_20_137_10"></a>STDOUT</h4> +<blockquote> +<p>The standard output shall consist of a line for each file, in the following format:</p> +<pre> +<tt>"%s\n", <</tt><i>SID removed from file</i><tt>> +</tt></pre> +<p>If there is more than one named file or if a directory or standard input is named, each pathname shall be written before each of +the preceding lines:</p> +<pre> +<tt>"\n%s:\n", <</tt><i>pathname</i><tt>> +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_137_11" id="tag_20_137_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_137_12" id="tag_20_137_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>Any SCCS files updated shall be files of an unspecified format. During processing of a <i>file</i>, a locking <i>z-file</i>, as +described in <a href="../utilities/get.html"><i>get</i></a>, and a <i>q-file</i> (a working copy of the <i>p-file</i>), may be +created and deleted. The <i>p-file</i> and <i>g-file</i>, as described in <a href="../utilities/get.html"><i>get</i></a>, shall be +deleted.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_137_13" id="tag_20_137_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_137_14" id="tag_20_137_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_137_15" id="tag_20_137_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_137_16" id="tag_20_137_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_137_17" id="tag_20_137_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_137_18" id="tag_20_137_18"></a>RATIONALE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_137_19" id="tag_20_137_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a +<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require +implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_137_20" id="tag_20_137_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/delta.html#"><i>delta</i></a> , <a href="../utilities/get.html#"><i>get</i></a> , <a href= +"../utilities/sact.html#"><i>sact</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_137_21" id="tag_20_137_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_137_22" id="tag_20_137_22"></a>Issue 6</h4> +<blockquote> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_137_23" id="tag_20_137_23"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_137_24" id="tag_20_137_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to disallow the creation of filenames containing any bytes that +have the encoded value of a <newline> character.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/unexpand.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/uniq.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/uniq.html b/bdd/uniq.html @@ -0,0 +1,306 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>uniq</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/unget.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/unlink.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="uniq" id="uniq"></a> <a name="tag_20_138" id="tag_20_138"></a><!-- uniq --> +<h4 class="mansect"><a name="tag_20_138_01" id="tag_20_138_01"></a>NAME</h4> +<blockquote>uniq — report or filter out repeated lines in a file</blockquote> +<h4 class="mansect"><a name="tag_20_138_02" id="tag_20_138_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>uniq</tt> <b>[</b><tt>-c|-d|-u</tt><b>] [</b><tt>-f</tt> <i>fields</i><b>] [</b><tt>-s</tt> <i>char</i><b>] +[</b><i>input_file</i> <b>[</b><i>output_file</i><b>]]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_138_03" id="tag_20_138_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>uniq</i> utility shall read an input file comparing adjacent lines, and write one copy of each input line on the output. +The second and succeeding copies of repeated adjacent input lines shall not be written. The trailing <newline> of each line +in the input shall be ignored when doing comparisons.</p> +<p>Repeated lines in the input shall not be detected if they are not adjacent.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_138_04" id="tag_20_138_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>uniq</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> , except that <tt>'+'</tt> may be recognized as an option delimiter as well as <tt>'-'</tt>.</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-c</b></dt> +<dd>Precede each output line with a count of the number of times the line occurred in the input.</dd> +<dt><b>-d</b></dt> +<dd>Suppress the writing of lines that are not repeated in the input.</dd> +<dt><b>-f </b><i>fields</i></dt> +<dd>Ignore the first <i>fields</i> fields on each input line when doing comparisons, where <i>fields</i> is a positive decimal +integer. A field is the maximal string matched by the basic regular expression: +<pre> +<tt>[[:blank:]]*[^[:blank:]]* +</tt></pre> +<p>If the <i>fields</i> option-argument specifies more fields than appear on an input line, a null string shall be used for +comparison.</p> +</dd> +<dt><b>-s </b><i>chars</i></dt> +<dd>Ignore the first <i>chars</i> characters when doing comparisons, where <i>chars</i> shall be a positive decimal integer. If +specified in conjunction with the <b>-f</b> option, the first <i>chars</i> characters after the first <i>fields</i> fields shall be +ignored. If the <i>chars</i> option-argument specifies more characters than remain on an input line, a null string shall be used +for comparison.</dd> +<dt><b>-u</b></dt> +<dd>Suppress the writing of lines that are repeated in the input.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_138_05" id="tag_20_138_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>input_file</i></dt> +<dd>A pathname of the input file. If the <i>input_file</i> operand is not specified, or if the <i>input_file</i> is <tt>'-'</tt>, +the standard input shall be used.</dd> +<dt><i>output_file</i></dt> +<dd>A pathname of the output file. If the <i>output_file</i> operand is not specified, the standard output shall be used. The +results are unspecified if the file named by <i>output_file</i> is the file named by <i>input_file</i>.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_138_06" id="tag_20_138_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be used only if no <i>input_file</i> operand is specified or if <i>input_file</i> is <tt>'-'</tt>. See +the INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_138_07" id="tag_20_138_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input file shall be a text file.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_138_08" id="tag_20_138_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>uniq</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files) and which characters constitute a <blank> in the current +locale.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_138_09" id="tag_20_138_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_138_10" id="tag_20_138_10"></a>STDOUT</h4> +<blockquote> +<p>The standard output shall be used if no <i>output_file</i> operand is specified, and shall be used if the <i>output_file</i> +operand is <tt>'-'</tt> and the implementation treats the <tt>'-'</tt> as meaning standard output. Otherwise, the standard output +shall not be used. See the OUTPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_138_11" id="tag_20_138_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_138_12" id="tag_20_138_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>If the <b>-c</b> option is specified, the output file shall be empty or each line shall be of the form:</p> +<pre> +<tt>"%d %s", <</tt><i>number of duplicates</i><tt>>, <</tt><i>line</i><tt>> +</tt></pre> +<p>otherwise, the output file shall be empty or each line shall be of the form:</p> +<pre> +<tt>"%s", <</tt><i>line</i><tt>> +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_138_13" id="tag_20_138_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_138_14" id="tag_20_138_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_138_15" id="tag_20_138_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_138_16" id="tag_20_138_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The <a href="../utilities/sort.html"><i>sort</i></a> utility can be used to cause repeated lines to be adjacent in the input +file.</p> +<p>If the collating sequence of the current locale does not have a total ordering of all characters, the behavior of <tt>sort | +uniq</tt> differs from <tt>sort -u</tt>, as <tt>uniq</tt> treats lines as duplicates only if they are identical, whereas <tt>sort +-u</tt> treats lines as duplicates if they collate equally.</p> +<p>When using <i>uniq</i> to process pathnames, it is recommended that LC_ALL, or at least LC_CTYPE and LC_COLLATE, are set to +POSIX or C in the environment, since pathnames can contain byte sequences that do not form valid characters in some locales, in +which case the utility's behavior would be undefined. In the POSIX locale each byte is a valid single-byte character, and therefore +this problem is avoided.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_138_17" id="tag_20_138_17"></a>EXAMPLES</h4> +<blockquote> +<p>The following input file data (but flushed left) was used for a test series on <i>uniq</i>:</p> +<pre> +<tt>#01 foo0 bar0 foo1 bar1 +#02 bar0 foo1 bar1 foo1 +#03 foo0 bar0 foo1 bar1 +#04 +#05 foo0 bar0 foo1 bar1 +#06 foo0 bar0 foo1 bar1 +#07 bar0 foo1 bar1 foo0 +</tt></pre> +<p>What follows is a series of test invocations of the <i>uniq</i> utility that use a mixture of <i>uniq</i> options against the +input file data. These tests verify the meaning of <i>adjacent</i>. The <i>uniq</i> utility views the input data as a sequence of +strings delimited by <tt>'\n'</tt>. Accordingly, for the <i>fields</i>th member of the sequence, <i>uniq</i> interprets unique or +repeated adjacent lines strictly relative to the <i>fields</i>+1th member.</p> +<ol> +<li> +<p>This first example tests the line counting option, comparing each line of the input file data starting from the second +field:</p> +<pre> +<tt>uniq -c -f 1 uniq_0I.t + 1 #01 foo0 bar0 foo1 bar1 + 1 #02 bar0 foo1 bar1 foo1 + 1 #03 foo0 bar0 foo1 bar1 + 1 #04 + 2 #05 foo0 bar0 foo1 bar1 + 1 #07 bar0 foo1 bar1 foo0 +</tt></pre> +<p>The number <tt>'2'</tt>, prefixing the fifth line of output, signifies that the <i>uniq</i> utility detected a pair of repeated +lines. Given the input data, this can only be true when <i>uniq</i> is run using the <b>-f 1</b> option (which shall cause +<i>uniq</i> to ignore the first field on each input line).</p> +</li> +<li> +<p>The second example tests the option to suppress unique lines, comparing each line of the input file data starting from the +second field:</p> +<pre> +<tt>uniq -d -f 1 uniq_0I.t +#05 foo0 bar0 foo1 bar1 +</tt></pre></li> +<li> +<p>This test suppresses repeated lines, comparing each line of the input file data starting from the second field:</p> +<pre> +<tt>uniq -u -f 1 uniq_0I.t +#01 foo0 bar0 foo1 bar1 +#02 bar0 foo1 bar1 foo1 +#03 foo0 bar0 foo1 bar1 +#04 +#07 bar0 foo1 bar1 foo0 +</tt></pre></li> +<li> +<p>This suppresses unique lines, comparing each line of the input file data starting from the third character:</p> +<pre> +<tt>uniq -d -s 2 uniq_0I.t +</tt></pre> +<p>In the last example, the <i>uniq</i> utility found no input matching the above criteria.</p> +</li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_138_18" id="tag_20_138_18"></a>RATIONALE</h4> +<blockquote> +<p>Some historical implementations have limited lines to be 1080 bytes in length, which does not meet the implied {LINE_MAX} +limit.</p> +<p>Earlier versions of this standard allowed the <b>-</b><i>number</i> and <b>+</b><i>number</i> options. These options are no +longer specified by POSIX.1-2024 but may be present in some implementations.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_138_19" id="tag_20_138_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a +<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require +implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_138_20" id="tag_20_138_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/comm.html#"><i>comm</i></a> , <a href="../utilities/sort.html#"><i>sort</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_138_21" id="tag_20_138_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_138_22" id="tag_20_138_22"></a>Issue 6</h4> +<blockquote> +<p>The obsolescent SYNOPSIS and associated text are removed.</p> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +<p>IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/40 is applied, adding <i>LC_COLLATE</i> to the ENVIRONMENT +VARIABLES section, and changing "the application shall ensure that" in the OUTPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_138_23" id="tag_20_138_23"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #027 is applied, clarifying that <tt>'+'</tt> may be recognized as an option delimiter +in the OPTIONS section.</p> +<p>Austin Group Interpretation 1003.1-2001 #092 is applied.</p> +<p>Austin Group Interpretation 1003.1-2001 #133 is applied, clarifying the behavior of the trailing <newline>.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>SD5-XCU-ERN-141 is applied, updating the EXAMPLES section.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0199 [963] and XCU/TC2-2008/0200 [663] are applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_138_24" id="tag_20_138_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to disallow the creation of filenames containing any bytes that +have the encoded value of a <newline> character.</p> +<p>Austin Group Defect 1070 is applied, changing the APPLICATION USAGE section.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1492 is applied, changing the EXIT STATUS section.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/unget.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/unlink.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/unlink.html b/bdd/unlink.html @@ -0,0 +1,175 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>unlink</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/uniq.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/uucp.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="unlink" id="unlink"></a> <a name="tag_20_139" id="tag_20_139"></a><!-- unlink --> +<h4 class="mansect"><a name="tag_20_139_01" id="tag_20_139_01"></a>NAME</h4> +<blockquote>unlink — call the unlink function</blockquote> +<h4 class="mansect"><a name="tag_20_139_02" id="tag_20_139_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> unlink</tt> <i>file</i> <tt><img src="../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div> +</blockquote> +<h4 class="mansect"><a name="tag_20_139_03" id="tag_20_139_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>unlink</i> utility shall perform the function call:</p> +<pre> +<tt>unlink(</tt><i>file</i><tt>); +</tt></pre> +<p>A user may need appropriate privileges to invoke the <i>unlink</i> utility.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_139_04" id="tag_20_139_04"></a>OPTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_139_05" id="tag_20_139_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>The pathname of an existing file.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_139_06" id="tag_20_139_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_139_07" id="tag_20_139_07"></a>INPUT FILES</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_139_08" id="tag_20_139_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>unlink</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd>Determine the location of messages objects and message catalogs.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_139_09" id="tag_20_139_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_139_10" id="tag_20_139_10"></a>STDOUT</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_139_11" id="tag_20_139_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_139_12" id="tag_20_139_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_139_13" id="tag_20_139_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_139_14" id="tag_20_139_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_139_15" id="tag_20_139_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_139_16" id="tag_20_139_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_139_17" id="tag_20_139_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_139_18" id="tag_20_139_18"></a>RATIONALE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_139_19" id="tag_20_139_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_139_20" id="tag_20_139_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/link.html#tag_20_66"><i>link</i></a> , <a href="../utilities/rm.html#"><i>rm</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a></p> +<p>XSH <a href="../functions/unlink.html#tag_17_649"><i>unlink</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_139_21" id="tag_20_139_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 5.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_139_22" id="tag_20_139_22"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/uniq.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/uucp.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/uucp.html b/bdd/uucp.html @@ -0,0 +1,284 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>uucp</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/unlink.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/uudecode.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="uucp" id="uucp"></a> <a name="tag_20_140" id="tag_20_140"></a><!-- uucp --> +<h4 class="mansect"><a name="tag_20_140_01" id="tag_20_140_01"></a>NAME</h4> +<blockquote>uucp — system-to-system copy</blockquote> +<h4 class="mansect"><a name="tag_20_140_02" id="tag_20_140_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('UU')">UU</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> uucp</tt> <b>[</b><tt>-cCdfjmr</tt><b>] [</b><tt>-n</tt> <i>user</i><b>]</b> +<i>source-file</i><tt>...</tt> <i>destination-file</i> <tt><img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></tt></code></div> +</blockquote> +<h4 class="mansect"><a name="tag_20_140_03" id="tag_20_140_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>uucp</i> utility shall copy files named by the <i>source-file</i> argument to the <i>destination-file</i> argument. The +files named can be on local or remote systems.</p> +<p>The <i>uucp</i> utility cannot guarantee support for all character encodings in all circumstances. For example, transmission +data may be restricted to 7 bits by the underlying network, 8-bit data and filenames need not be portable to non-internationalized +systems, and so on. Under these circumstances, it is recommended that only characters defined in the ISO/IEC 646:1991 standard +International Reference Version (equivalent to ASCII) 7-bit range of characters be used, and that only characters defined in the +portable filename character set be used for naming files. The protocol for transfer of files is unspecified by POSIX.1-2024.</p> +<p>Typical implementations of this utility require a communications line configured to use XBD <a href= +"../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> , but other communications means may be used. On +systems where there are no available communications means (either temporarily or permanently), this utility shall write an error +message describing the problem and exit with a non-zero exit status.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_140_04" id="tag_20_140_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>uucp</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-c</b></dt> +<dd>Do not copy local file to the spool directory for transfer to the remote machine (default).</dd> +<dt><b>-C</b></dt> +<dd>Force the copy of local files to the spool directory for transfer.</dd> +<dt><b>-d</b></dt> +<dd>Make all necessary directories for the file copy (default).</dd> +<dt><b>-f</b></dt> +<dd>Do not make intermediate directories for the file copy.</dd> +<dt><b>-j</b></dt> +<dd>Write the job identification string to standard output. This job identification can be used by <a href= +"../utilities/uustat.html"><i>uustat</i></a> to obtain the status or terminate a job.</dd> +<dt><b>-m</b></dt> +<dd>Send mail to the requester when the copy is completed.</dd> +<dt><b>-n </b><i>user</i></dt> +<dd>Notify <i>user</i> on the remote system that a file was sent.</dd> +<dt><b>-r</b></dt> +<dd>Do not start the file transfer; just queue the job.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_140_05" id="tag_20_140_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>destination-file</i>, <i>source-file</i></dt> +<dd><br> +A pathname of a file to be copied to, or from, respectively. Either name can be a pathname on the local machine, or can have the +form: +<pre> +<i>system-name</i><tt>!</tt><i>pathname</i><tt> +</tt></pre> +<p>where <i>system-name</i> is taken from a list of system names that <i>uucp</i> knows about. The destination <i>system-name</i> +can also be a list of names such as:</p> +<pre> +<i>system-name</i><tt>!</tt><i>system-name</i><tt>!...!</tt><i>system-name</i><tt>!</tt><i>pathname</i><tt> +</tt></pre> +<p>in which case, an attempt is made to send the file via the specified route to the destination. Care should be taken to ensure +that intermediate nodes in the route are willing to forward information.</p> +<p>The shell pattern matching notation characters <tt>'?'</tt>, <tt>'*'</tt>, and <tt>"[...]"</tt> appearing in <i>pathname</i> +shall be expanded on the appropriate system.</p> +<p>Pathnames can be one of:</p> +<ol> +<li> +<p>An absolute pathname.</p> +</li> +<li> +<p>A pathname preceded by ~<i>user</i> where <i>user</i> is a login name on the specified system and is replaced by that user's +login directory. Note that if an invalid login is specified, the default is to the public directory (called <i>PUBDIR</i>; the +actual location of <i>PUBDIR</i> is implementation-defined).</p> +</li> +<li> +<p>A pathname preceded by ~/<i>destination</i> where <i>destination</i> is appended to <i>PUBDIR</i>. <basefont size="2"></p> +<dl> +<dt><b>Note:</b></dt> +<dd>This destination is treated as a filename unless more than one file is being transferred by this request or the destination is +already a directory. To ensure that it is a directory, follow the destination with a <tt>'/'</tt>. For example, <b>~/dan/</b> as +the destination makes the directory <b>PUBDIR/dan</b> if it does not exist and puts the requested files in that directory.</dd> +</dl> +<basefont size="3"></li> +<li> +<p>Anything else shall be prefixed by the current directory.</p> +</li> +</ol> +<p>If the result is an erroneous pathname for the remote system, the copy shall fail. If the <i>destination-file</i> is a +directory, the last part of the <i>source-file</i> name shall be used.</p> +<p>The read, write, and execute permissions given by <i>uucp</i> are implementation-defined.</p> +</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_140_06" id="tag_20_140_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_140_07" id="tag_20_140_07"></a>INPUT FILES</h4> +<blockquote> +<p>The files to be copied are regular files.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_140_08" id="tag_20_140_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>uucp</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_COLLATE</i></dt> +<dd><br> +Determine the locale for the behavior of ranges, equivalence classes, and multi-character collating elements within bracketed +filename patterns.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files) and the behavior of character classes within bracketed filename +patterns (for example, <tt>"'[[:lower:]]*'"</tt>).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error, and +informative messages written to standard output.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_140_09" id="tag_20_140_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_140_10" id="tag_20_140_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_140_11" id="tag_20_140_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_140_12" id="tag_20_140_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>The output files (which may be on other systems) are copies of the input files.</p> +<p>If <b>-m</b> is used, mail files are modified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_140_13" id="tag_20_140_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_140_14" id="tag_20_140_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_140_15" id="tag_20_140_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_140_16" id="tag_20_140_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>This utility is part of the UUCP Utilities option and need not be supported by all implementations.</p> +<p>The domain of remotely accessible files can (and for obvious security reasons usually should) be severely restricted.</p> +<p>Note that the <tt>'!'</tt> character in addresses has to be escaped when using <i>csh</i> as a command interpreter because of +its history substitution syntax. For <i>ksh</i> and <a href="../utilities/sh.html"><i>sh</i></a> the escape is not necessary, but +may be used.</p> +<p>As noted above, shell metacharacters appearing in pathnames are expanded on the appropriate system. On an internationalized +system, this is done under the control of local settings of <i>LC_COLLATE</i> and <i>LC_CTYPE .</i> Thus, care should be taken when +using bracketed filename patterns, as collation and typing rules may vary from one system to another. Also be aware that certain +types of expression (that is, equivalence classes, character classes, and collating symbols) need not be supported on +non-internationalized systems.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_140_17" id="tag_20_140_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_140_18" id="tag_20_140_18"></a>RATIONALE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_140_19" id="tag_20_140_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a +<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require +implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_140_20" id="tag_20_140_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/mailx.html#"><i>mailx</i></a> , <a href="../utilities/uuencode.html#"><i>uuencode</i></a> , <a href= +"../utilities/uustat.html#"><i>uustat</i></a> , <a href="../utilities/uux.html#"><i>uux</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_140_21" id="tag_20_140_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_140_22" id="tag_20_140_22"></a>Issue 6</h4> +<blockquote> +<p>The <i>LC_TIME</i> and <i>TZ</i> entries are removed from the ENVIRONMENT VARIABLES section.</p> +<p>The UN margin codes and associated shading are removed from the <b>-C</b>, <b>-f</b>, <b>-j</b>, <b>-n</b>, and <b>-r</b> +options in response to The Open Group Base Resolution bwg2001-003.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_140_23" id="tag_20_140_23"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-46 is applied, moving this utility to the UUCP Utilities Option Group.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_140_24" id="tag_20_140_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to disallow the creation of filenames containing any bytes that +have the encoded value of a <newline> character.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1516 is applied, adding XSI shading to text relating to <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/unlink.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/uudecode.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/uudecode.html b/bdd/uudecode.html @@ -0,0 +1,239 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>uudecode</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/uucp.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/uuencode.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="uudecode" id="uudecode"></a> <a name="tag_20_141" id="tag_20_141"></a><!-- uudecode --> +<h4 class="mansect"><a name="tag_20_141_01" id="tag_20_141_01"></a>NAME</h4> +<blockquote>uudecode — decode a binary file</blockquote> +<h4 class="mansect"><a name="tag_20_141_02" id="tag_20_141_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>uudecode</tt> <b>[</b><tt>-o</tt> <i>outfile</i><b>] [</b><i>file</i><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_141_03" id="tag_20_141_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>uudecode</i> utility shall read a file, or standard input if no file is specified, that includes data created by the +<a href="../utilities/uuencode.html"><i>uuencode</i></a> utility. The <i>uudecode</i> utility shall scan the input file, searching +for data compatible with one of the formats specified in <a href="../utilities/uuencode.html"><i>uuencode</i></a>, and determine +the pathname for the output file from the <b>-o</b> option if given, otherwise from the input data. If the pathname for the output +file is either of the magic cookies <b>-</b> or <b>/dev/stdout</b>, <i>uudecode</i> shall write the decoded file to standard +output, otherwise it shall attempt to create or overwrite the file named by the pathname. The file access permission bits and +contents for the file to be produced shall be contained in the input data. The mode bits of the created file (other than standard +output) shall be set from the file access permission bits contained in the data; that is, other attributes of the mode, including +the file mode creation mask (see <a href="../utilities/umask.html"><i>umask</i></a>), shall not affect the file being produced. If +either of the <i>op</i> characters <tt>'+'</tt> and <tt>'-'</tt> (see <a href="../utilities/chmod.html"><i>chmod</i></a>) are +specified in symbolic mode, the initial mode on which those operations are based is unspecified.</p> +<p>If the pathname of the file resolves to an existing file and the user does not have write permission on that file, +<i>uudecode</i> shall terminate with an error. If the pathname of the file resolves to an existing file and the user has write +permission on that file, the existing file shall be overwritten and, if possible, the mode bits of the file (other than standard +output) shall be set as described above; if the mode bits cannot be set, <i>uudecode</i> shall not treat this as an error.</p> +<p>If the input data was produced by <a href="../utilities/uuencode.html"><i>uuencode</i></a> on a system with a different number +of bits per byte than on the target system, the results of <i>uudecode</i> are unspecified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_141_04" id="tag_20_141_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>uudecode</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following option shall be supported by the implementation:</p> +<dl compact> +<dd></dd> +<dt><b>-o </b><i>outfile</i></dt> +<dd>A pathname of a file that shall be used instead of any pathname contained in the input data. Specifying an <i>outfile</i> +option-argument of <b>-</b> or <b>/dev/stdout</b> shall indicate standard output.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_141_05" id="tag_20_141_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>The pathname of a file containing the output of <a href="../utilities/uuencode.html"><i>uuencode</i></a>.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_141_06" id="tag_20_141_06"></a>STDIN</h4> +<blockquote> +<p>See the INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_141_07" id="tag_20_141_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files shall be files containing the output of <a href="../utilities/uuencode.html"><i>uuencode</i></a>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_141_08" id="tag_20_141_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>uudecode</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_141_09" id="tag_20_141_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_141_10" id="tag_20_141_10"></a>STDOUT</h4> +<blockquote> +<p>If the pathname specified for the output file is <b>-</b> or <b>/dev/stdout</b>, the standard output shall be in the same format +as the file originally encoded by <a href="../utilities/uuencode.html"><i>uuencode</i></a>. Otherwise, the standard output shall +not be used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_141_11" id="tag_20_141_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_141_12" id="tag_20_141_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>The output file shall be in the same format as the file originally encoded by <a href= +"../utilities/uuencode.html"><i>uuencode</i></a>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_141_13" id="tag_20_141_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_141_14" id="tag_20_141_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_141_15" id="tag_20_141_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_141_16" id="tag_20_141_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The user who is invoking <i>uudecode</i> must have write permission on any file being created.</p> +<p>The output of <a href="../utilities/uuencode.html"><i>uuencode</i></a> is essentially an encoded bit stream that is not +cognizant of byte boundaries. It is possible that a 9-bit byte target machine can process input from an 8-bit source, if it is +aware of the requirement, but the reverse is unlikely to be satisfying. Of course, the only data that is meaningful for such a +transfer between architectures is generally character data.</p> +<p>In order to create an output file named <b>-</b>, it needs to be specified using an alternative pathname, for example, <b>-o</b> +<b>./-</b>, since <b>-</b> alone is considered a magic cookie by <i>uudecode</i>. Likewise, in order to write to an output file +named <b>/dev/stdout</b> it also needs to be specified as, for example, <b>-o</b> <b>///dev/stdout</b>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_141_17" id="tag_20_141_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_141_18" id="tag_20_141_18"></a>RATIONALE</h4> +<blockquote> +<p>Input files are not necessarily text files, as stated by an early proposal. Although the <a href= +"../utilities/uuencode.html"><i>uuencode</i></a> output is a text file, that output could have been wrapped within another file or +mail message that is not a text file.</p> +<p>The <b>-o</b> option is not historical practice, but was added at the request of WG15 so that the user could override the target +pathname without having to edit the input data itself.</p> +<p>In early drafts, the [<b>-o</b> <i>outfile</i>] option-argument allowed the use of <b>-</b> to mean standard output. The +standard developers did not wish to overload the meaning of <b>-</b> in this manner, resulting in previous versions only using +<b>/dev/stdout</b> for this purpose. POSIX.1-2024 now allows it as most implementations were already supporting <b>-</b> as an +extension. The file <b>/dev/stdout</b> exists as a special file on most modern systems. However, the <b>/dev/stdout</b> syntax in +<i>uudecode</i> does not refer to a new file. It is just a magic cookie to specify standard output.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_141_19" id="tag_20_141_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a +<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require +implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_141_20" id="tag_20_141_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/chmod.html#tag_20_17"><i>chmod</i></a> , <a href="../utilities/umask.html#tag_20_132"><i>umask</i></a> , +<a href="../utilities/uuencode.html#"><i>uuencode</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_141_21" id="tag_20_141_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_141_22" id="tag_20_141_22"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +<p>The <b>-o</b> <i>outfile</i> option is added, as specified in the IEEE P1003.2b draft standard.</p> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +<p>IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/35 is applied, clarifying in the DESCRIPTION that the initial +mode used if either of the <i>op</i> characters is <tt>'+'</tt> or <tt>'-'</tt> is unspecified.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_141_23" id="tag_20_141_23"></a>Issue 7</h4> +<blockquote> +<p>The <i>uudecode</i> utility is moved from the User Portability Utilities option to the Base. User Portability Utilities is now +an option for interactive utilities.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0201 [635] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_141_24" id="tag_20_141_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to disallow the creation of filenames containing any bytes that +have the encoded value of a <newline> character.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1544 is applied, changing the <b>-o</b> option to require that an option-argument of <b>-</b> is treated as +meaning standard output.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/uucp.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/uuencode.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/uuencode.html b/bdd/uuencode.html @@ -0,0 +1,944 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>uuencode</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/uudecode.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/uustat.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="uuencode" id="uuencode"></a> <a name="tag_20_142" id="tag_20_142"></a><!-- uuencode --> +<h4 class="mansect"><a name="tag_20_142_01" id="tag_20_142_01"></a>NAME</h4> +<blockquote>uuencode — encode a binary file</blockquote> +<h4 class="mansect"><a name="tag_20_142_02" id="tag_20_142_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>uuencode</tt> <b>[</b><tt>-m</tt><b>] [</b><i>file</i><b>]</b> <i>decode_pathname</i></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_142_03" id="tag_20_142_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>uuencode</i> utility shall write an encoded version of the named input file, or standard input if no <i>file</i> is +specified, to standard output. The output shall be encoded using one of the algorithms described in the STDOUT section and shall +include the file access permission bits (in <a href="../utilities/chmod.html"><i>chmod</i></a> octal or symbolic notation) of the +input file and the <i>decode_pathname</i>, for re-creation of the file on another system that conforms to this volume of +POSIX.1-2024.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_142_04" id="tag_20_142_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>uuencode</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following option shall be supported by the implementation:</p> +<dl compact> +<dd></dd> +<dt><b>-m</b></dt> +<dd>Encode the output using the MIME Base64 algorithm described in STDOUT. If <b>-m</b> is not specified, the historical algorithm +described in STDOUT shall be used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_142_05" id="tag_20_142_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>decode_pathname</i></dt> +<dd><br> +The pathname of the file into which the <a href="../utilities/uudecode.html"><i>uudecode</i></a> utility shall place the decoded +file. Specifying a <i>decode_pathname</i> operand of <b>-</b> or <b>/dev/stdout</b> shall indicate that <a href= +"../utilities/uudecode.html"><i>uudecode</i></a> is to use standard output. If there are characters in <i>decode_pathname</i> that +are not in the portable filename character set the results are unspecified.</dd> +<dt><i>file</i></dt> +<dd>A pathname of the file to be encoded.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_142_06" id="tag_20_142_06"></a>STDIN</h4> +<blockquote> +<p>See the INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_142_07" id="tag_20_142_07"></a>INPUT FILES</h4> +<blockquote> +<p>Input files can be files of any type.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_142_08" id="tag_20_142_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>uuencode</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_142_09" id="tag_20_142_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_142_10" id="tag_20_142_10"></a>STDOUT</h4> +<blockquote> +<h5><a name="tag_20_142_10_01" id="tag_20_142_10_01"></a>uuencode Base64 Algorithm</h5> +<p>The standard output shall be a text file (encoded in the character set of the current locale) that begins with the line:</p> +<pre> +<tt>"begin-base64Δ%sΔ%s\n", <</tt><i>mode</i><tt>>, <</tt><i>decode_pathname</i><tt>> +</tt></pre> +<p>and ends with the line:</p> +<pre> +<tt>"====\n" +</tt></pre> +<p>In both cases, the lines shall have no preceding or trailing <blank> characters.</p> +<p>The encoding process represents 24-bit groups of input bits as output strings of four encoded characters. Proceeding from left +to right, a 24-bit input group shall be formed by concatenating three 8-bit input groups. Each 24-bit input group then shall be +treated as four concatenated 6-bit groups, each of which shall be translated into a single digit in the Base64 alphabet. When +encoding a bit stream via the Base64 encoding, the bit stream shall be presumed to be ordered with the most-significant bit first. +That is, the first bit in the stream shall be the high-order bit in the first byte, and the eighth bit shall be the low-order bit +in the first byte, and so on. Each 6-bit group is used as an index into an array of 64 printable characters, as shown in <a href= +"#tagtcjh_24">uuencode Base64 Values</a> .</p> +<p class="caption"><a name="tagtcjh_24" id="tagtcjh_24"></a> Table: uuencode Base64 Values</p> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Value</b></p> +</th> +<th align="center"> +<p class="tent"><b>Encoding</b></p> +</th> +<th align="left"> +<p class="tent"> </p> +</th> +<th align="center"> +<p class="tent"><b>Value</b></p> +</th> +<th align="center"> +<p class="tent"><b>Encoding</b></p> +</th> +<th align="left"> +<p class="tent"> </p> +</th> +<th align="center"> +<p class="tent"><b>Value</b></p> +</th> +<th align="center"> +<p class="tent"><b>Encoding</b></p> +</th> +<th align="left"> +<p class="tent"> </p> +</th> +<th align="center"> +<p class="tent"><b>Value</b></p> +</th> +<th align="center"> +<p class="tent"><b>Encoding</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">0</p> +</td> +<td align="center"> +<p class="tent">A</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">17</p> +</td> +<td align="center"> +<p class="tent">R</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">34</p> +</td> +<td align="center"> +<p class="tent">i</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">51</p> +</td> +<td align="center"> +<p class="tent">z</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">1</p> +</td> +<td align="center"> +<p class="tent">B</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">18</p> +</td> +<td align="center"> +<p class="tent">S</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">35</p> +</td> +<td align="center"> +<p class="tent">j</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">52</p> +</td> +<td align="center"> +<p class="tent">0</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">2</p> +</td> +<td align="center"> +<p class="tent">C</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">19</p> +</td> +<td align="center"> +<p class="tent">T</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">36</p> +</td> +<td align="center"> +<p class="tent">k</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">53</p> +</td> +<td align="center"> +<p class="tent">1</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">3</p> +</td> +<td align="center"> +<p class="tent">D</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">20</p> +</td> +<td align="center"> +<p class="tent">U</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">37</p> +</td> +<td align="center"> +<p class="tent">l</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">54</p> +</td> +<td align="center"> +<p class="tent">2</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">4</p> +</td> +<td align="center"> +<p class="tent">E</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">21</p> +</td> +<td align="center"> +<p class="tent">V</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">38</p> +</td> +<td align="center"> +<p class="tent">m</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">55</p> +</td> +<td align="center"> +<p class="tent">3</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">5</p> +</td> +<td align="center"> +<p class="tent">F</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">22</p> +</td> +<td align="center"> +<p class="tent">W</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">39</p> +</td> +<td align="center"> +<p class="tent">n</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">56</p> +</td> +<td align="center"> +<p class="tent">4</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">6</p> +</td> +<td align="center"> +<p class="tent">G</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">23</p> +</td> +<td align="center"> +<p class="tent">X</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">40</p> +</td> +<td align="center"> +<p class="tent">o</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">57</p> +</td> +<td align="center"> +<p class="tent">5</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">7</p> +</td> +<td align="center"> +<p class="tent">H</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">24</p> +</td> +<td align="center"> +<p class="tent">Y</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">41</p> +</td> +<td align="center"> +<p class="tent">p</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">58</p> +</td> +<td align="center"> +<p class="tent">6</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">8</p> +</td> +<td align="center"> +<p class="tent">I</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">25</p> +</td> +<td align="center"> +<p class="tent">Z</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">42</p> +</td> +<td align="center"> +<p class="tent">q</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">59</p> +</td> +<td align="center"> +<p class="tent">7</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">9</p> +</td> +<td align="center"> +<p class="tent">J</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">26</p> +</td> +<td align="center"> +<p class="tent">a</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">43</p> +</td> +<td align="center"> +<p class="tent">r</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">60</p> +</td> +<td align="center"> +<p class="tent">8</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">10</p> +</td> +<td align="center"> +<p class="tent">K</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">27</p> +</td> +<td align="center"> +<p class="tent">b</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">44</p> +</td> +<td align="center"> +<p class="tent">s</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">61</p> +</td> +<td align="center"> +<p class="tent">9</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">11</p> +</td> +<td align="center"> +<p class="tent">L</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">28</p> +</td> +<td align="center"> +<p class="tent">c</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">45</p> +</td> +<td align="center"> +<p class="tent">t</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">62</p> +</td> +<td align="center"> +<p class="tent">+</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">12</p> +</td> +<td align="center"> +<p class="tent">M</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">29</p> +</td> +<td align="center"> +<p class="tent">d</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">46</p> +</td> +<td align="center"> +<p class="tent">u</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">63</p> +</td> +<td align="center"> +<p class="tent">/</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">13</p> +</td> +<td align="center"> +<p class="tent">N</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">30</p> +</td> +<td align="center"> +<p class="tent">e</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">47</p> +</td> +<td align="center"> +<p class="tent">v</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="center"> +<p class="tent"> </p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">14</p> +</td> +<td align="center"> +<p class="tent">O</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">31</p> +</td> +<td align="center"> +<p class="tent">f</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">48</p> +</td> +<td align="center"> +<p class="tent">w</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">(pad)</p> +</td> +<td align="center"> +<p class="tent">=</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">15</p> +</td> +<td align="center"> +<p class="tent">P</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">32</p> +</td> +<td align="center"> +<p class="tent">g</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">49</p> +</td> +<td align="center"> +<p class="tent">x</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="center"> +<p class="tent"> </p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">16</p> +</td> +<td align="center"> +<p class="tent">Q</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">33</p> +</td> +<td align="center"> +<p class="tent">h</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent">50</p> +</td> +<td align="center"> +<p class="tent">y</p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="left"> +<p class="tent"> </p> +</td> +<td align="center"> +<p class="tent"> </p> +</td> +</tr> +</table> +</center> +<p class="tent">The character referenced by the index shall be placed in the output string.</p> +<p class="tent">The output stream (encoded bytes) shall be represented in lines of no more than 76 characters each. All line breaks +or other characters not found in the table shall be ignored by decoding software (see <a href= +"../utilities/uudecode.html#"><i>uudecode</i></a> ).</p> +<p class="tent">Special processing shall be performed if fewer than 24 bits are available at the end of a message or encapsulated +part of a message. A full encoding quantum shall always be completed at the end of a message. When fewer than 24 input bits are +available in an input group, zero bits shall be added (on the right) to form an integral number of 6-bit groups. Output character +positions that are not required to represent actual input data shall be set to the character <tt>'='</tt>. Since all Base64 input +is an integral number of octets, only the following cases can arise:</p> +<ol> +<li class="tent">The final quantum of encoding input is an integral multiple of 24 bits; here, the final unit of encoded output +shall be an integral multiple of 4 characters with no <tt>'='</tt> padding.</li> +<li class="tent">The final quantum of encoding input is exactly 16 bits; here, the final unit of encoded output shall be three +characters followed by one <tt>'='</tt> padding character.</li> +<li class="tent">The final quantum of encoding input is exactly 8 bits; here, the final unit of encoded output shall be two +characters followed by two <tt>'='</tt> padding characters.</li> +</ol> +<p class="tent">A terminating <tt>"===="</tt> evaluates to nothing and denotes the end of the encoded data.</p> +<h5><a name="tag_20_142_10_02" id="tag_20_142_10_02"></a>uuencode Historical Algorithm</h5> +<p class="tent">The standard output shall be a text file (encoded in the character set of the current locale) that begins with the +line:</p> +<pre> +<tt>"beginΔ%sΔ%s\n" <</tt><i>mode</i><tt>>, <</tt><i>decode_pathname</i><tt>> +</tt></pre> +<p class="tent">and ends with the line:</p> +<pre> +<tt>"end\n" +</tt></pre> +<p class="tent">In both cases, the lines shall have no preceding or trailing <blank> characters.</p> +<p class="tent">The algorithm that shall be used for lines in between <b>begin</b> and <b>end</b> takes three octets as input and +writes four characters of output by splitting the input at six-bit intervals into four octets, containing data in the lower six +bits only. These octets shall be converted to characters in the ISO/IEC 646:1991 standard encoded character set by adding a +value of 0x20 to each octet, so that each octet is in the range [0x20,0x5f], and then optionally replacing any 0x20 octets with +0x60. If necessary, these characters shall then be translated into the corresponding character codes for the codeset in use in the +current locale. For example, the octet 0x41, representing <tt>'A'</tt>, would be translated to <tt>'A'</tt> in the current codeset, +such as 0xc1 if it were EBCDIC; the octet 0x20, representing <space>, would optionally be replaced with 0x60, representing +<tt>'`'</tt>, and then translated to either <space> (0x40 if EBCDIC) or <tt>'`'</tt> (0x79 if EBCDIC), respectively.</p> +<p class="tent">Where the bits of two octets are combined, the least significant bits of the first octet shall be shifted left and +combined with the most significant bits of the second octet shifted right. Thus the three octets <i>A</i>, <i>B</i>, <i>C</i> shall +be converted into the four octets:</p> +<pre> +<tt>0x20 + (( A >> 2 ) & 0x3F) +0x20 + (((A << 4) |'(XX' ((B >> 4) & 0xF)) & 0x3F) +0x20 + (((B << 2) |'(XX' ((C >> 6) & 0x3)) & 0x3F) +0x20 + (( C ) & 0x3F) +</tt></pre> +<p class="tent">before any replacement of 0x20 with 0x60 and translation into the local character set.</p> +<p class="tent">Each encoded line shall contain a length character, equal to the number of characters to be decoded plus 0x20 +translated to the local character set as described above, followed by between 1 and 45, inclusive, encoded characters. The last +encoded line, or the <b>begin</b> line if the input is empty, shall be followed by a line containing only a <space> or +<tt>'`'</tt> character before the terminating <newline>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_142_11" id="tag_20_142_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_142_12" id="tag_20_142_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_142_13" id="tag_20_142_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_142_14" id="tag_20_142_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_142_15" id="tag_20_142_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_142_16" id="tag_20_142_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The file is expanded by 35 percent (each three octets become four, plus control information) causing it to take longer to +transmit.</p> +<p class="tent">Since this utility is intended to create files to be used for data interchange between systems with possibly +different codesets, and to represent binary data as a text file, the ISO/IEC 646:1991 standard was chosen for a midpoint in +the algorithm as a known reference point. The output from <i>uuencode</i> is a text file on the local system. If the output were in +the ISO/IEC 646:1991 standard codeset, it might not be a text file (at least because the <newline> characters might not +match), and the goal of creating a text file would be defeated. If this text file was then carried to another machine with the same +codeset, it would be perfectly compatible with that system's <a href="../utilities/uudecode.html"><i>uudecode</i></a>. If it was +transmitted over a mail system or sent to a machine with a different codeset, it is assumed that, as for every other text file, +some translation mechanism would convert it (by the time it reached a user on the other system) into an appropriate codeset. This +translation only makes sense from the local codeset, not if the file has been put into a ISO/IEC 646:1991 standard +representation first. Similarly, files processed by <i>uuencode</i> can be placed in <a href="../utilities/pax.html"><i>pax</i></a> +archives, intermixed with other text files in the same codeset.</p> +<p class="tent">Since <a href="../utilities/uudecode.html"><i>uudecode</i></a> treats a <i>decode_pathname</i> of <b>-</b> to mean +decode to standard output, in order to specify that a file named <b>-</b> is to be created, <i>decode_pathname</i> should be +specified using an alternative pathname, for example <b>./-</b>. Likewise, in order to specify that a file with the pathname +<b>/dev/stdout</b> is to be written, <i>decode_pathname</i> should be specified as, for example, <b>///dev/stdout</b>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_142_17" id="tag_20_142_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_142_18" id="tag_20_142_18"></a>RATIONALE</h4> +<blockquote> +<p>A new algorithm was added at the request of the international community to parallel work in RFC 2045 (MIME). As with the +historical <i>uuencode</i> format, the Base64 Content-Transfer-Encoding is designed to represent arbitrary sequences of octets in a +form that is not humanly readable. A 65-character subset of the ISO/IEC 646:1991 standard is used, enabling 6 bits to be +represented per printable character. (The extra 65th character, <tt>'='</tt>, is used to signify a special processing +function.)</p> +<p class="tent">This subset has the important property that it is represented identically in all versions of the +ISO/IEC 646:1991 standard, including US ASCII, and all characters in the subset are also represented identically in all +versions of EBCDIC. The historical <i>uuencode</i> algorithm does not share this property, which is the reason that a second +algorithm was added to the ISO POSIX-2 standard.</p> +<p class="tent">The string <tt>"===="</tt> was used for the termination instead of the end used in the original format because the +latter is a string that could be valid encoded input.</p> +<p class="tent">In an early draft, the <b>-m</b> option was named <b>-b</b> (for Base64), but it was renamed to reflect its +relationship to the RFC 2045. A <b>-u</b> was also present to invoke the default algorithm, but since this was not historical +practice, it was omitted as being unnecessary.</p> +<p class="tent">See the RATIONALE section in <a href="../utilities/uudecode.html#"><i>uudecode</i></a> for the derivation of the +<b>/dev/stdout</b> symbol.</p> +<p class="tent">Historically the encoding used only octets in the range [0x20,0x5f], and thus the encoded lines could contain +trailing spaces, which were at risk of being stripped by whatever transport method was used to send the file. To avoid this problem +some implementations use 0x60 instead of 0x20, resulting in <tt>'`'</tt> characters instead of spaces in the output, and +implementations are encouraged to do this.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_142_19" id="tag_20_142_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_142_20" id="tag_20_142_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/chmod.html#tag_20_17"><i>chmod</i></a> , <a href="../utilities/mailx.html#"><i>mailx</i></a> , <a href= +"../utilities/uudecode.html#"><i>uudecode</i></a></p> +<p class="tent">XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_142_21" id="tag_20_142_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 4.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_142_22" id="tag_20_142_22"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +<p class="tent">The Base64 algorithm and the ability to output to <b>/dev/stdout</b> are added as specified in the +IEEE P1003.2b draft standard.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_142_23" id="tag_20_142_23"></a>Issue 7</h4> +<blockquote> +<p>The <i>uuencode</i> utility is moved from the User Portability Utilities option to the Base. User Portability Utilities is now +an option for interactive utilities.</p> +<p class="tent">SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_142_24" id="tag_20_142_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p class="tent">Austin Group Defect 1140 is applied, changing the description of the <i>uuencode</i> historical algorithm.</p> +<p class="tent">Austin Group Defect 1544 is applied, changing the OPERANDS and APPLICATION USAGE sections.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/uudecode.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/uustat.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/uustat.html b/bdd/uustat.html @@ -0,0 +1,214 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>uustat</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/uuencode.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/uux.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="uustat" id="uustat"></a> <a name="tag_20_143" id="tag_20_143"></a><!-- uustat --> +<h4 class="mansect"><a name="tag_20_143_01" id="tag_20_143_01"></a>NAME</h4> +<blockquote>uustat — uucp status enquiry and job control</blockquote> +<h4 class="mansect"><a name="tag_20_143_02" id="tag_20_143_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('UU')">UU</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> uustat</tt> <b>[</b><tt>-q|-k</tt> <i>jobid</i><tt>|-r</tt> <i>jobid</i><b>]</b> <tt><br> +<br> +uustat</tt> <b>[</b><tt>-s</tt> <i>system</i><b>] [</b><tt>-u</tt> <i>user</i><b>]</b> <tt><img src="../images/opt-end.gif" alt= +"[Option End]" border="0"></tt></code></div> +<tt><br></tt></blockquote> +<h4 class="mansect"><a name="tag_20_143_03" id="tag_20_143_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>uustat</i> utility shall display the status of, or cancel, previously specified <a href= +"../utilities/uucp.html"><i>uucp</i></a> requests, or provide general status on <a href="../utilities/uucp.html"><i>uucp</i></a> +connections to other systems.</p> +<p>When no options are given, <i>uustat</i> shall write to standard output the status of all <a href= +"../utilities/uucp.html"><i>uucp</i></a> requests issued by the current user.</p> +<p>Typical implementations of this utility require a communications line configured to use XBD <a href= +"../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> , but other communications means may be used. On +systems where there are no available communications means (either temporarily or permanently), this utility shall write an error +message describing the problem and exit with a non-zero exit status.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_143_04" id="tag_20_143_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>uustat</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-q</b></dt> +<dd>Write the jobs queued for each machine.</dd> +<dt><b>-k </b><i>jobid</i></dt> +<dd>Kill the <a href="../utilities/uucp.html"><i>uucp</i></a> request whose job identification is <i>jobid</i>. The application +shall ensure that the killed <a href="../utilities/uucp.html"><i>uucp</i></a> request belongs to the person invoking <i>uustat</i> +unless that user has appropriate privileges.</dd> +<dt><b>-r </b><i>jobid</i></dt> +<dd>Rejuvenate <i>jobid</i>. The files associated with <i>jobid</i> are touched so that their modification time is set to the +current time. This prevents the cleanup program from deleting the job until the jobs modification time reaches the limit imposed by +the program.</dd> +<dt><b>-s </b><i>system</i></dt> +<dd>Write the status of all <a href="../utilities/uucp.html"><i>uucp</i></a> requests for remote system <i>system</i>.</dd> +<dt><b>-u </b><i>user</i></dt> +<dd>Write the status of all <a href="../utilities/uucp.html"><i>uucp</i></a> requests issued by <i>user</i>.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_143_05" id="tag_20_143_05"></a>OPERANDS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_143_06" id="tag_20_143_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_143_07" id="tag_20_143_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_143_08" id="tag_20_143_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>uustat</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error, and +informative messages written to standard output.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_143_09" id="tag_20_143_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_143_10" id="tag_20_143_10"></a>STDOUT</h4> +<blockquote> +<p>The standard output shall consist of information about each job selected, in an unspecified format. The information shall +include at least the job ID, the user ID or name, and the remote system name.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_143_11" id="tag_20_143_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_143_12" id="tag_20_143_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_143_13" id="tag_20_143_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_143_14" id="tag_20_143_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_143_15" id="tag_20_143_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_143_16" id="tag_20_143_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>This utility is part of the UUCP Utilities option and need not be supported by all implementations.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_143_17" id="tag_20_143_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_143_18" id="tag_20_143_18"></a>RATIONALE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_143_19" id="tag_20_143_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_143_20" id="tag_20_143_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/uucp.html#"><i>uucp</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_143_21" id="tag_20_143_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_143_22" id="tag_20_143_22"></a>Issue 6</h4> +<blockquote> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +<p>The <i>LC_TIME</i> and <i>TZ</i> entries are removed from the ENVIRONMENT VARIABLES section.</p> +<p>The UN margin code and associated shading are removed from the <b>-q</b> option in response to The Open Group Base Resolution +bwg2001-003.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_143_23" id="tag_20_143_23"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-46 is applied, moving this utility to the UUCP Utilities Option Group.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_143_24" id="tag_20_143_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1516 is applied, adding XSI shading to text relating to <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/uuencode.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/uux.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/uux.html b/bdd/uux.html @@ -0,0 +1,285 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>uux</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/uustat.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/val.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="uux" id="uux"></a> <a name="tag_20_144" id="tag_20_144"></a><!-- uux --> +<h4 class="mansect"><a name="tag_20_144_01" id="tag_20_144_01"></a>NAME</h4> +<blockquote>uux — remote command execution</blockquote> +<h4 class="mansect"><a name="tag_20_144_02" id="tag_20_144_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('UU')">UU</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> uux</tt> <b>[</b><tt>-jnp</tt><b>]</b> <i>command-string</i> <tt><img src="../images/opt-end.gif" alt= +"[Option End]" border="0"></tt></code></div> +</blockquote> +<h4 class="mansect"><a name="tag_20_144_03" id="tag_20_144_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>uux</i> utility shall gather zero or more files from various systems, execute a shell pipeline (see <a href= +"../utilities/V3_chap02.html#tag_19_09"><i>2.9 Shell Commands</i></a> ) on a specified system, and then send the standard output of +the command to a file on a specified system. Only the first command of a pipeline can have a <i>system-name</i>! prefix. All other +commands in the pipeline shall be executed on the system of the first command.</p> +<p>The following restrictions are applicable to the shell pipeline processed by <i>uux</i>:</p> +<ul> +<li> +<p>In gathering files from different systems, pathname expansion shall not be performed by <i>uux</i>. Thus, a request such as:</p> +<pre> +<tt>uux "c17 remsys!~/*.c" +</tt></pre> +<p>would attempt to copy the file named literally <b>*.c</b> to the local system.</p> +</li> +<li> +<p>The redirection operators <tt>">>"</tt>, <tt>"<<"</tt>, <tt>">|"</tt>, and <tt>">&"</tt> shall not be +accepted. Any use of these redirection operators shall cause this utility to write an error message describing the problem and exit +with a non-zero exit status.</p> +</li> +<li> +<p>The reserved word <b>!</b> cannot be used at the head of the pipeline to modify the exit status. (See the <i>command-string</i> +operand description below.)</p> +</li> +<li> +<p>Alias substitution shall not be performed.</p> +</li> +</ul> +<p>A filename can be specified as for <a href="../utilities/uucp.html"><i>uucp</i></a>; it can be an absolute pathname, a pathname +preceded by ~<i>name</i> (which is replaced by the corresponding login directory), a pathname specified as ~/<i>dest</i> +(<i>dest</i> is prefixed by the public directory called <i>PUBDIR</i>; the actual location of <i>PUBDIR</i> is +implementation-defined), or a simple filename (which is prefixed by <i>uux</i> with the current directory). See <a href= +"../utilities/uucp.html#"><i>uucp</i></a> for the details.</p> +<p>The execution of commands on remote systems shall take place in an execution directory known to the <a href= +"../utilities/uucp.html"><i>uucp</i></a> system. All files required for the execution shall be put into this directory unless they +already reside on that machine. Therefore, the application shall ensure that non-local filenames (without path or machine +reference) are unique within the <i>uux</i> request.</p> +<p>The <i>uux</i> utility shall attempt to get all files to the execution system. For files that are output files, the application +shall ensure that the filename is escaped using parentheses.</p> +<p>The remote system shall notify the user by mail if the requested command on the remote system was disallowed or the files were +not accessible. This notification can be turned off by the <b>-n</b> option.</p> +<p>Typical implementations of this utility require a communications line configured to use XBD <a href= +"../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> , but other communications means may be used. On +systems where there are no available communications means (either temporarily or permanently), this utility shall write an error +message describing the problem and exit with a non-zero exit status.</p> +<p>The <i>uux</i> utility cannot guarantee support for all character encodings in all circumstances. For example, transmission data +may be restricted to 7 bits by the underlying network, 8-bit data and filenames need not be portable to non-internationalized +systems, and so on. Under these circumstances, it is recommended that only characters defined in the ISO/IEC 646:1991 standard +International Reference Version (equivalent to ASCII) 7-bit range of characters be used and that only characters defined in the +portable filename character set be used for naming files.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_144_04" id="tag_20_144_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>uux</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-j</b></dt> +<dd>Write the job identification string to standard output. This job identification can be used by <a href= +"../utilities/uustat.html"><i>uustat</i></a> to obtain the status or terminate a job.</dd> +<dt><b>-n</b></dt> +<dd>Do not notify the user if the command fails.</dd> +<dt><b>-p</b></dt> +<dd>Make the standard input to <i>uux</i> the standard input to the <i>command-string</i>.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_144_05" id="tag_20_144_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>command-string</i></dt> +<dd><br> +A string made up of one or more arguments that are similar to normal command arguments, except that the command and any filenames +can be prefixed by <i>system-name</i>!. A null <i>system-name</i> shall be interpreted as the local system.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_144_06" id="tag_20_144_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall not be used unless the <tt>'-'</tt> or <b>-p</b> option is specified; in those cases, the standard +input shall be made the standard input of the <i>command-string</i>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_144_07" id="tag_20_144_07"></a>INPUT FILES</h4> +<blockquote> +<p>Input files shall be selected according to the contents of <i>command-string</i>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_144_08" id="tag_20_144_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>uux</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_144_09" id="tag_20_144_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_144_10" id="tag_20_144_10"></a>STDOUT</h4> +<blockquote> +<p>The standard output shall not be used unless the <b>-j</b> option is specified; in that case, the job identification string +shall be written to standard output in the following format:</p> +<pre> +<tt>"%s\n", <</tt><i>jobid</i><tt>> +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_144_11" id="tag_20_144_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_144_12" id="tag_20_144_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>Output files shall be created or written, or both, according to the contents of <i>command-string</i>.</p> +<p>If <b>-n</b> is not used, mail files shall be modified following any command or file-access failures on the remote system.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_144_13" id="tag_20_144_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_144_14" id="tag_20_144_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_144_15" id="tag_20_144_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_144_16" id="tag_20_144_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>This utility is part of the UUCP Utilities option and need not be supported by all implementations.</p> +<p>Note that, for security reasons, many installations limit the list of commands executable on behalf of an incoming request from +<i>uux</i>. Many sites permit little more than the receipt of mail via <i>uux</i>.</p> +<p>Any characters special to the command interpreter should be quoted either by quoting the entire <i>command-string</i> or quoting +the special characters as individual arguments.</p> +<p>As noted in <a href="../utilities/uucp.html"><i>uucp</i></a>, shell pattern matching notation characters appearing in pathnames +are expanded on the appropriate local system. This is done under the control of local settings of <i>LC_COLLATE</i> and <i>LC_CTYPE +.</i> Thus, care should be taken when using bracketed filename patterns, as collation and typing rules may vary from one system to +another. Also be aware that certain types of expression (that is, equivalence classes, character classes, and collating symbols) +need not be supported on non-internationalized systems.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_144_17" id="tag_20_144_17"></a>EXAMPLES</h4> +<blockquote> +<ol> +<li> +<p>The following command gets <b>file1</b> from system <b>a</b> and <b>file2</b> from system <b>b</b>, executes <a href= +"../utilities/diff.html"><i>diff</i></a> on the local system, and puts the results in <b>file.diff</b> in the local <i>PUBDIR</i> +directory. (<i>PUBDIR</i> is the <a href="../utilities/uucp.html"><i>uucp</i></a> public directory on the local system.)</p> +<pre> +<tt>uux "!diff a!/usr/file1 b!/a4/file2 >!~/file.diff" +</tt></pre></li> +<li> +<p>The following command fails because <i>uux</i> places all files copied to a system in the same working directory. Although the +files <b>xyz</b> are from two different systems, their filenames are the same and conflict.</p> +<pre> +<tt>uux "!diff a!/usr1/xyz b!/usr2/xyz >!~/xyz.diff" +</tt></pre></li> +<li> +<p>The following command succeeds (assuming <a href="../utilities/diff.html"><i>diff</i></a> is permitted on system <b>a</b>) +because the file local to system <b>a</b> is not copied to the working directory, and hence does not conflict with the file from +system <b>c</b>.</p> +<pre> +<tt>uux "a!diff a!/usr/xyz c!/usr/xyz >!~/xyz.diff" +</tt></pre></li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_144_18" id="tag_20_144_18"></a>RATIONALE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_144_19" id="tag_20_144_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_144_20" id="tag_20_144_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19"><i>2. Shell Command Language</i></a> , <a href= +"../utilities/uucp.html#"><i>uucp</i></a> , <a href="../utilities/uuencode.html#"><i>uuencode</i></a> , <a href= +"../utilities/uustat.html#"><i>uustat</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_144_21" id="tag_20_144_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_144_22" id="tag_20_144_22"></a>Issue 6</h4> +<blockquote> +<p>The obsolescent SYNOPSIS is removed.</p> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +<p>The UN margin code and associated shading are removed from the <b>-j</b> option in response to The Open Group Base Resolution +bwg2001-003.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_144_23" id="tag_20_144_23"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-46 is applied, moving this utility to the UUCP Utilities Option Group.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_144_24" id="tag_20_144_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1516 is applied, adding XSI shading to text relating to <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/uustat.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/val.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/val.html b/bdd/val.html @@ -0,0 +1,333 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>val</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/uux.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/vi.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="val" id="val"></a> <a name="tag_20_145" id="tag_20_145"></a><!-- val --> +<h4 class="mansect"><a name="tag_20_145_01" id="tag_20_145_01"></a>NAME</h4> +<blockquote>val — validate SCCS files (<b>DEVELOPMENT</b>)</blockquote> +<h4 class="mansect"><a name="tag_20_145_02" id="tag_20_145_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> val -<br> +<br> +val</tt> <b>[</b><tt>-s</tt><b>] [</b><tt>-m</tt> <i>name</i><b>] [</b><tt>-r</tt> <i>SID</i><b>] [</b><tt>-y</tt> +<i>type</i><b>]</b> <i>file</i><tt>... <img src="../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div> +<tt><br></tt></blockquote> +<h4 class="mansect"><a name="tag_20_145_03" id="tag_20_145_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>val</i> utility shall determine whether the specified <i>file</i> is an SCCS file meeting the characteristics specified +by the options.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_145_04" id="tag_20_145_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>val</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> , except that the usage of the <tt>'-'</tt> operand is not strictly as intended by the guidelines (that is, +reading options and operands from standard input).</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-m </b><i>name</i></dt> +<dd>Specify a <i>name</i>, which is compared with the SCCS %<b>M</b>% keyword in <i>file</i>; see <a href= +"../utilities/get.html#"><i>get</i></a> .</dd> +<dt><b>-r </b><i>SID</i></dt> +<dd>Specify a <i>SID</i> (SCCS Identification String), an SCCS delta number. A check shall be made to determine whether the +<i>SID</i> is ambiguous (for example, <b>-r 1</b> is ambiguous because it physically does not exist but implies 1.1, 1.2, and +so on, which may exist) or invalid (for example, <b>-r 1.0</b> or <b>-r 1.1.0</b> are invalid because neither case can +exist as a valid delta number). If the <i>SID</i> is valid and not ambiguous, a check shall be made to determine whether it +actually exists.</dd> +<dt><b>-s</b></dt> +<dd>Silence the diagnostic message normally written to standard output for any error that is detected while processing each named +file on a given command line.</dd> +<dt><b>-y </b><i>type</i></dt> +<dd>Specify a <i>type</i>, which shall be compared with the SCCS %<b>Y</b>% keyword in <i>file</i>; see <a href= +"../utilities/get.html#"><i>get</i></a> .</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_145_05" id="tag_20_145_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of an existing SCCS file. If exactly one <i>file</i> operand appears, and it is <tt>'-'</tt>, the standard input +shall be read: each line shall be independently processed as if it were a command line argument list. (However, the line is not +subjected to any of the shell word expansions, such as parameter expansion or quote removal.)</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_145_06" id="tag_20_145_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be a text file used only when the <i>file</i> operand is specified as <tt>'-'</tt>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_145_07" id="tag_20_145_07"></a>INPUT FILES</h4> +<blockquote> +<p>Any SCCS files processed shall be files of an unspecified format.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_145_08" id="tag_20_145_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>val</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error, and +informative messages written to standard output.</dd> +<dt><i>NLSPATH</i></dt> +<dd>Determine the location of messages objects and message catalogs.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_145_09" id="tag_20_145_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_145_10" id="tag_20_145_10"></a>STDOUT</h4> +<blockquote> +<p>The standard output shall consist of informative messages about either:</p> +<ol> +<li> +<p>Each file processed</p> +</li> +<li> +<p>Each command line read from standard input</p> +</li> +</ol> +<p>If the standard input is not used, for each <i>file</i> operand yielding a discrepancy, the output line shall have the following +format:</p> +<pre> +<tt>"%s: %s\n", <</tt><i>pathname</i><tt>>, <</tt><i>unspecified string</i><tt>> +</tt></pre> +<p>If the standard input is used, for each input line yielding a discrepancy, the output shall have the following format:</p> +<pre> +<tt>"%s\n\n %s: %s\n", <</tt><i>input</i><tt>>, <</tt><i>pathname</i><tt>>, <</tt><i>unspecified string</i><tt>> +</tt></pre> +<p>where <<i>input</i>> is the input line minus its terminating <newline>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_145_11" id="tag_20_145_11"></a>STDERR</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_145_12" id="tag_20_145_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_145_13" id="tag_20_145_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_145_14" id="tag_20_145_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The 8-bit code returned by <i>val</i> shall be a disjunction of the possible errors; that is, it can be interpreted as a bit +string where set bits are interpreted as follows:</p> +<table cellpadding="3"> +<tr valign="top"> +<td align="left"> +<p class="tent">0x80</p> +</td> +<td align="center"> +<p class="tent">=</p> +</td> +<td align="left"> +<p class="tent">Missing file argument.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">0x40</p> +</td> +<td align="center"> +<p class="tent">=</p> +</td> +<td align="left"> +<p class="tent">Unknown or duplicate option.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">0x20</p> +</td> +<td align="center"> +<p class="tent">=</p> +</td> +<td align="left"> +<p class="tent">Corrupted SCCS file.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">0x10</p> +</td> +<td align="center"> +<p class="tent">=</p> +</td> +<td align="left"> +<p class="tent">Cannot open file or file not SCCS.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">0x08</p> +</td> +<td align="center"> +<p class="tent">=</p> +</td> +<td align="left"> +<p class="tent"><i>SID</i> is invalid or ambiguous.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">0x04</p> +</td> +<td align="center"> +<p class="tent">=</p> +</td> +<td align="left"> +<p class="tent"><i>SID</i> does not exist.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">0x02</p> +</td> +<td align="center"> +<p class="tent">=</p> +</td> +<td align="left"> +<p class="tent">%<b>Y</b>%, <b>-y</b> mismatch.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">0x01</p> +</td> +<td align="center"> +<p class="tent">=</p> +</td> +<td align="left"> +<p class="tent">%<b>M</b>%, <b>-m</b> mismatch.</p> +</td> +</tr> +</table> +<p class="tent">Note that <i>val</i> can process two or more files on a given command line and can process multiple command lines +(when reading the standard input). In these cases an aggregate code shall be returned: a logical OR of the codes generated for each +command line and file processed.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_145_15" id="tag_20_145_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_145_16" id="tag_20_145_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Since the <i>val</i> exit status sets the 0x80 bit, shell applications checking <tt>"$?"</tt> cannot tell if it terminated due +to a missing file argument or receipt of a signal.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_145_17" id="tag_20_145_17"></a>EXAMPLES</h4> +<blockquote> +<p>In a directory with three SCCS files—<b>s.x</b> (of <b>t</b> type "text"), <b>s.y</b>, and <b>s.z</b> (a corrupted file)—the +following command could produce the output shown:</p> +<pre> +<tt>val - <<EOF +-y source s.x +-m y s.y +s.z +EOF +-y source s.x +<br class="tent"> + s.x: %Y%, -y mismatch +s.z +<br class="tent"> + s.z: corrupted SCCS file +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_145_18" id="tag_20_145_18"></a>RATIONALE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_145_19" id="tag_20_145_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_145_20" id="tag_20_145_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/admin.html#"><i>admin</i></a> , <a href="../utilities/delta.html#"><i>delta</i></a> , <a href= +"../utilities/get.html#"><i>get</i></a> , <a href="../utilities/prs.html#"><i>prs</i></a></p> +<p class="tent">XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_145_21" id="tag_20_145_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_145_22" id="tag_20_145_22"></a>Issue 6</h4> +<blockquote> +<p>The Open Group Corrigendum U025/4 is applied, correcting a typographical error in the EXIT STATUS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_145_23" id="tag_20_145_23"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p class="tent">POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0147 [416] and XCU/TC1-2008/0148 [416] are applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_145_24" id="tag_20_145_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to report an error if a utility is directed to display a +pathname that contains any bytes that have the encoded value of a <newline> character when <newline> is a terminator or +separator in the output format being used.</p> +<p class="tent">Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/uux.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/vi.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/vi.html b/bdd/vi.html @@ -0,0 +1,3314 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>vi</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/val.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/wait.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="vi" id="vi"></a> <a name="tag_20_146" id="tag_20_146"></a><!-- vi --> +<h4 class="mansect"><a name="tag_20_146_01" id="tag_20_146_01"></a>NAME</h4> +<blockquote>vi — screen-oriented (visual) display editor</blockquote> +<h4 class="mansect"><a name="tag_20_146_02" id="tag_20_146_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('UP')">UP</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> vi</tt> <b>[</b><tt>-rR</tt><b>] [</b><tt>-c</tt> <i>command</i><b>] [</b><tt>-t</tt> +<i>tagstring</i><b>] [</b><tt>-w</tt> <i>size</i><b>] [</b><i>file</i><tt>...</tt><b>]</b> <tt><img src="../images/opt-end.gif" +alt="[Option End]" border="0"></tt></code></div> +</blockquote> +<h4 class="mansect"><a name="tag_20_146_03" id="tag_20_146_03"></a>DESCRIPTION</h4> +<blockquote> +<p>This utility shall be provided on systems that both support the User Portability Utilities option and define the +POSIX2_CHAR_TERM symbol. On other systems it is optional.</p> +<p>The <i>vi</i> (visual) utility is a screen-oriented text editor. Only the open and visual modes of the editor are described in +POSIX.1-2024; see the line editor <a href="../utilities/ex.html"><i>ex</i></a> for additional editing capabilities used in +<i>vi</i>. The user can switch back and forth between <i>vi</i> and <a href="../utilities/ex.html"><i>ex</i></a> and execute +<a href="../utilities/ex.html"><i>ex</i></a> commands from within <i>vi</i>.</p> +<p>This reference page uses the term <i>edit buffer</i> to describe the current working text. No specific implementation is implied +by this term. All editing changes are performed on the edit buffer, and no changes to it shall affect any file until an editor +command writes the file.</p> +<p>When using <i>vi</i>, the terminal screen acts as a window into the editing buffer. Changes made to the editing buffer shall be +reflected in the screen display; the position of the cursor on the screen shall indicate the position within the editing +buffer.</p> +<p>Certain terminals do not have all the capabilities necessary to support the complete <i>vi</i> definition. When these commands +cannot be supported on such terminals, this condition shall not produce an error message such as "not an editor command" or +report a syntax error. The implementation may either accept the commands and produce results on the screen that are the result of +an unsuccessful attempt to meet the requirements of this volume of POSIX.1-2024 or report an error describing the terminal-related +deficiency.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_146_04" id="tag_20_146_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>vi</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> , except that <tt>'+'</tt> may be recognized as an option delimiter as well as <tt>'-'</tt>.</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-c </b><i>command</i></dt> +<dd>See the <a href="../utilities/ex.html"><i>ex</i></a> command description of the <b>-c</b> option.</dd> +<dt><b>-r</b></dt> +<dd>See the <a href="../utilities/ex.html"><i>ex</i></a> command description of the <b>-r</b> option.</dd> +<dt><b>-R</b></dt> +<dd>See the <a href="../utilities/ex.html"><i>ex</i></a> command description of the <b>-R</b> option.</dd> +<dt><b>-t </b><i>tagstring</i></dt> +<dd>See the <a href="../utilities/ex.html"><i>ex</i></a> command description of the <b>-t</b> option.</dd> +<dt><b>-w </b><i>size</i></dt> +<dd>See the <a href="../utilities/ex.html"><i>ex</i></a> command description of the <b>-w</b> option.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_146_05" id="tag_20_146_05"></a>OPERANDS</h4> +<blockquote> +<p>See the OPERANDS section of the <a href="../utilities/ex.html"><i>ex</i></a> command for a description of the operands supported +by the <i>vi</i> command.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_146_06" id="tag_20_146_06"></a>STDIN</h4> +<blockquote> +<p>If standard input is not a terminal device, the results are undefined. The standard input consists of a series of commands and +input text, as described in the EXTENDED DESCRIPTION section.</p> +<p>If a read from the standard input returns an error, or if the editor detects an end-of-file condition from the standard input, +it shall be equivalent to a SIGHUP asynchronous event.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_146_07" id="tag_20_146_07"></a>INPUT FILES</h4> +<blockquote> +<p>See the INPUT FILES section of the <a href="../utilities/ex.html"><i>ex</i></a> command for a description of the input files +supported by the <i>vi</i> command.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_146_08" id="tag_20_146_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>See the ENVIRONMENT VARIABLES section of the <a href="../utilities/ex.html"><i>ex</i></a> command for the environment variables +that affect the execution of the <i>vi</i> command.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_146_09" id="tag_20_146_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>See the ASYNCHRONOUS EVENTS section of the <a href="../utilities/ex.html"><i>ex</i></a> for the asynchronous events that affect +the execution of the <i>vi</i> command.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_146_10" id="tag_20_146_10"></a>STDOUT</h4> +<blockquote> +<p>If standard output is not a terminal device, undefined results occur.</p> +<p>Standard output may be used for writing prompts to the user, for informational messages, and for writing lines from the +file.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_146_11" id="tag_20_146_11"></a>STDERR</h4> +<blockquote> +<p>If standard output is not a terminal device, undefined results occur.</p> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_146_12" id="tag_20_146_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>See the OUTPUT FILES section of the <a href="../utilities/ex.html"><i>ex</i></a> command for a description of the output files +supported by the <i>vi</i> command.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_146_13" id="tag_20_146_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>If the terminal does not have the capabilities necessary to support an unspecified portion of the <i>vi</i> definition, +implementations shall start initially in <a href="../utilities/ex.html"><i>ex</i></a> mode or open mode. Otherwise, after +initialization, <i>vi</i> shall be in command mode; text input mode can be entered by one of several commands used to insert or +change text. In text input mode, <ESC> can be used to return to command mode; other uses of <ESC> are described later +in this section; see <a href="#tag_20_146_13_16">Terminate Command or Input Mode</a> .</p> +<h5><a name="tag_20_146_13_01" id="tag_20_146_13_01"></a>Initialization in ex and vi</h5> +<p>See <a href="../utilities/ex.html#tag_20_40_13_01"><i>Initialization in ex and vi</i></a> for a description of <a href= +"../utilities/ex.html"><i>ex</i></a> and <i>vi</i> initialization for the <i>vi</i> utility.</p> +<h5><a name="tag_20_146_13_02" id="tag_20_146_13_02"></a>Command Descriptions in vi</h5> +<p>The following symbols are used in this reference page to represent arguments to commands.</p> +<dl compact> +<dd></dd> +<dt><i>buffer</i></dt> +<dd>See the description of <i>buffer</i> in the EXTENDED DESCRIPTION section of the <a href="../utilities/ex.html"><i>ex</i></a> +utility; see <a href="../utilities/ex.html#tag_20_40_13_10"><i>Command Descriptions in ex</i></a> . +<p>In open and visual mode, when a command synopsis shows both [<i>buffer</i>] and [<i>count</i>] preceding the command name, they +can be specified in either order.</p> +</dd> +<dt><i>count</i></dt> +<dd>A positive integer used as an optional argument to most commands, either to give a repeat count or as a size. This argument is +optional and shall default to 1 unless otherwise specified. +<p>The Synopsis lines for the <i>vi</i> commands <control>-G, <control>-L, <control>-R, <control>-], +<b>%</b>, <b>&</b>, <b>^</b>, <b>D</b>, <b>m</b>, <b>M</b>, <b>Q</b>, <b>u</b>, <b>U</b>, and <b>ZZ</b> do not have <i>count</i> as +an optional argument. Regardless, it shall not be an error to specify a <i>count</i> to these commands, and any specified +<i>count</i> shall be ignored.</p> +</dd> +<dt><i>motion</i></dt> +<dd>An optional trailing argument used by the <b>!</b>, <b><</b>, <b>></b>, <b>c</b>, <b>d</b>, and <b>y</b> commands, which +is used to indicate the region of text that shall be affected by the command. The motion can be either one of the command +characters repeated or one of several other <i>vi</i> commands (listed in the following table). Each of the applicable commands +specifies the region of text matched by repeating the command; each command that can be used as a motion command specifies the +region of text it affects. +<p>Commands that take <i>motion</i> arguments operate on either lines or characters, depending on the circumstances. When operating +on lines, all lines that fall partially or wholly within the text region specified for the command shall be affected. When +operating on characters, only the exact characters in the specified text region shall be affected. Each motion command specifies +this individually.</p> +<p>When commands that may be motion commands are not used as motion commands, they shall set the current position to the current +line and column as specified.</p> +<p>The following commands shall be valid cursor motion commands:</p> +<pre> +<tt><apostrophe> ( - j H +<carriage-return> ) $ k L +<comma> [[ % l M +<control>-H ]] _ n N +<control>-N { ; t T +<control>-P } ? w W +<grave-accent> ^ b B +<newline> + e E +<space> | f F +<zero> / h G +</tt></pre> +<p>Any <i>count</i> that is specified to a command that has an associated motion command shall be applied to the motion command. If +a <i>count</i> is applied to both the command and its associated motion command, the effect shall be multiplicative.</p> +</dd> +</dl> +<p>The following symbols are used in this section to specify locations in the edit buffer:</p> +<dl compact> +<dd></dd> +<dt><i>current character</i></dt> +<dd><br> +The character that is currently indicated by the cursor.</dd> +<dt><i>end of a line</i></dt> +<dd><br> +The point located between the last non-<newline> (if any) and the terminating <newline> of a line. For an empty line, +this location coincides with the beginning of the line.</dd> +<dt><i>end of the edit buffer</i></dt> +<dd><br> +The location corresponding to the end of the last line in the edit buffer.</dd> +</dl> +<p>The following symbols are used in this section to specify command actions:</p> +<dl compact> +<dd></dd> +<dt><i>bigword</i></dt> +<dd>In the POSIX locale, <i>vi</i> shall recognize four kinds of <i>bigwords</i>: +<ol> +<li> +<p>A maximal sequence of non-<blank> characters preceded and followed by <blank> characters or the beginning or end of +a line or the edit buffer</p> +</li> +<li> +<p>One or more sequential blank lines</p> +</li> +<li> +<p>The first character in the edit buffer</p> +</li> +<li> +<p>The last non-<newline> in the edit buffer</p> +</li> +</ol> +</dd> +<dt><i>word</i></dt> +<dd>In the POSIX locale, <i>vi</i> shall recognize five kinds of words: +<ol> +<li> +<p>A maximal sequence of letters, digits, and underscores, delimited at both ends by:</p> +<ul> +<li> +<p>Characters other than letters, digits, or underscores</p> +</li> +<li> +<p>The beginning or end of a line</p> +</li> +<li> +<p>The beginning or end of the edit buffer</p> +</li> +</ul> +</li> +<li> +<p>A maximal sequence of characters other than letters, digits, underscores, or <blank> characters, delimited at both ends +by:</p> +<ul> +<li> +<p>A letter, digit, underscore</p> +</li> +<li> +<p><blank> characters</p> +</li> +<li> +<p>The beginning or end of a line</p> +</li> +<li> +<p>The beginning or end of the edit buffer</p> +</li> +</ul> +</li> +<li> +<p>One or more sequential blank lines</p> +</li> +<li> +<p>The first character in the edit buffer</p> +</li> +<li> +<p>The last non-<newline> in the edit buffer</p> +</li> +</ol> +</dd> +<dt><i>section boundary</i></dt> +<dd><br> +A <i>section boundary</i> is one of the following: +<ol> +<li> +<p>A line whose first character is a <form-feed></p> +</li> +<li> +<p>A line whose first character is an open curly brace (<tt>'{'</tt>)</p> +</li> +<li> +<p>A line whose first character is a <period> and whose second and third characters match a two-character pair in the +<b>sections</b> edit option (see <a href="../utilities/ex.html"><i>ex</i></a>)</p> +</li> +<li> +<p>A line whose first character is a <period> and whose only other character matches the first character of a two-character +pair in the <b>sections</b> edit option, where the second character of the two-character pair is a <space></p> +</li> +<li> +<p>The first line of the edit buffer</p> +</li> +<li> +<p>The last line of the edit buffer if the last line of the edit buffer is empty or if it is a <b>]]</b> or <b>}</b> command; +otherwise, the last non-<newline> of the last line of the edit buffer</p> +</li> +</ol> +</dd> +<dt><i>paragraph boundary</i></dt> +<dd><br> +A <i>paragraph boundary</i> is one of the following: +<ol> +<li> +<p>A section boundary</p> +</li> +<li> +<p>A line whose first character is a <period> and whose second and third characters match a two-character pair in the +<b>paragraphs</b> edit option (see <a href="../utilities/ex.html"><i>ex</i></a>)</p> +</li> +<li> +<p>A line whose first character is a <period> and whose only other character matches the first character of a two-character +pair in the <i>paragraphs</i> edit option, where the second character of the two-character pair is a <space></p> +</li> +<li> +<p>One or more sequential blank lines</p> +</li> +</ol> +</dd> +<dt><i>remembered search direction</i></dt> +<dd><br> +See the description of <i>remembered search direction</i> in <a href="../utilities/ex.html"><i>ex</i></a>.</dd> +<dt><i>sentence boundary</i></dt> +<dd><br> +A <i>sentence boundary</i> is one of the following: +<ol> +<li> +<p>A paragraph boundary</p> +</li> +<li> +<p>The first non-<blank> that occurs after a paragraph boundary</p> +</li> +<li> +<p>The first non-<blank> that occurs after a <period> (<tt>'.'</tt>), <exclamation-mark> (<tt>'!'</tt>), or +<question-mark> (<tt>'?'</tt>), followed by two <space> characters or the end of a line; any number of closing +parenthesis (<tt>')'</tt>), closing brackets (<tt>']'</tt>), double-quote (<tt>'"'</tt> ), or single-quote (<apostrophe>) +characters can appear between the punctuation mark and the two <space> characters or end-of-line</p> +</li> +</ol> +</dd> +</dl> +<p>In the remainder of the description of the <i>vi</i> utility, the term "buffer line" refers to a line in the edit buffer and +the term "display line" refers to the line or lines on the display screen used to display one buffer line. The term "current +line" refers to a specific "buffer line".</p> +<p>If there are display lines on the screen for which there are no corresponding buffer lines because they correspond to lines that +would be after the end of the file, they shall be displayed as a single <tilde> (<tt>'~'</tt>) character, plus the +terminating <newline>.</p> +<p>The last line of the screen shall be used to report errors or display informational messages. It shall also be used to display +the input for "line-oriented commands" (<b>/</b>, <b>?</b>, <b>:</b>, and <b>!</b>). When a line-oriented command is executed, +the editor shall enter text input mode on the last line on the screen, using the respective command characters as prompt +characters. (In the case of the <b>!</b> command, the associated motion shall be entered by the user before the editor enters text +input mode.) The line entered by the user shall be terminated by a <newline>, a non-<control>-V-escaped +<carriage-return>, or unescaped <ESC>. It is unspecified if more characters than require a display width minus one +column number of screen columns can be entered.</p> +<p>If any command is executed that overwrites a portion of the screen other than the last line of the screen (for example, the +<a href="../utilities/ex.html"><i>ex</i></a> <b>suspend</b> or <b>!</b> commands), other than the <a href= +"../utilities/ex.html"><i>ex</i></a> <b>shell</b> command, the user shall be prompted for a character before the screen is +refreshed and the edit session continued.</p> +<p><tab> characters shall take up the number of columns on the screen set by the <b>tabstop</b> edit option (see <a href= +"../utilities/ex.html"><i>ex</i></a>), unless there are less than that number of columns before the display margin that will cause +the displayed line to be folded; in this case, they shall only take up the number of columns up to that boundary.</p> +<p>The cursor shall be placed on the current line and relative to the current column as specified by each command described in the +following sections.</p> +<p>In open mode, if the current line is not already displayed, then it shall be displayed.</p> +<p>In visual mode, if the current line is not displayed, then the lines that are displayed shall be expanded, scrolled, or redrawn +to cause an unspecified portion of the current line to be displayed. If the screen is redrawn, no more than the number of display +lines specified by the value of the <b>window</b> edit option shall be displayed (unless the current line cannot be completely +displayed in the number of display lines specified by the <b>window</b> edit option) and the current line shall be positioned as +close to the center of the displayed lines as possible (within the constraints imposed by the distance of the line from the +beginning or end of the edit buffer). If the current line is before the first line in the display and the screen is scrolled, an +unspecified portion of the current line shall be placed on the first line of the display. If the current line is after the last +line in the display and the screen is scrolled, an unspecified portion of the current line shall be placed on the last line of the +display.</p> +<p>In visual mode, if a line from the edit buffer (other than the current line) does not entirely fit into the lines at the bottom +of the display that are available for its presentation, the editor may choose not to display any portion of the line. The lines of +the display that do not contain text from the edit buffer for this reason shall each consist of a single <tt>'@'</tt> +character.</p> +<p>In visual mode, the editor may choose for unspecified reasons to not update lines in the display to correspond to the underlying +edit buffer text. The lines of the display that do not correctly correspond to text from the edit buffer for this reason shall +consist of a single <tt>'@'</tt> character (plus the terminating <newline>), and the <control>-R command shall cause +the editor to update the screen to correctly represent the edit buffer.</p> +<p>Open and visual mode commands that set the current column set it to a column position in the display, and not a character +position in the line. In this case, however, the column position in the display shall be calculated for an infinite width display; +for example, the column related to a character that is part of a line that has been folded onto additional screen lines is offset +from the display line column where the buffer line begins, not from the beginning of a particular display line.</p> +<p>The display cursor column in the display is based on the value of the current column, as follows, with each rule applied in +turn:</p> +<ol> +<li> +<p>If the current column is after the last display line column used by the displayed line, the display cursor column shall be set +to the last display line column occupied by the last non-<newline> in the current line; otherwise, the display cursor column +shall be set to the current column.</p> +</li> +<li> +<p>If the character of which some portion is displayed in the display line column specified by the display cursor column requires +more than a single display line column:</p> +<ol type="a"> +<li> +<p>If in text input mode, the display cursor column shall be adjusted to the first display line column in which any portion of that +character is displayed.</p> +</li> +<li> +<p>Otherwise, the display cursor column shall be adjusted to the last display line column in which any portion of that character is +displayed.</p> +</li> +</ol> +</li> +</ol> +<p>The current column shall not be changed by these adjustments to the display cursor column.</p> +<p>If an error occurs during the parsing or execution of a <i>vi</i> command:</p> +<ul> +<li> +<p>The terminal shall be alerted. Execution of the <i>vi</i> command shall stop, and the cursor (for example, the current line and +column) shall not be further modified.</p> +</li> +<li> +<p>Unless otherwise specified by the following command sections, it is unspecified whether an informational message shall be +displayed.</p> +</li> +<li> +<p>Any partially entered <i>vi</i> command shall be discarded.</p> +</li> +<li> +<p>If the <i>vi</i> command resulted from a <b>map</b> expansion, all characters from that <b>map</b> expansion shall be discarded, +except as otherwise specified by the <b>map</b> command (see <a href="../utilities/ex.html"><i>ex</i></a>).</p> +</li> +<li> +<p>If the <i>vi</i> command resulted from the execution of a buffer, no further commands caused by the execution of the buffer +shall be executed.</p> +</li> +</ul> +<h5><a name="tag_20_146_13_03" id="tag_20_146_13_03"></a>Page Backwards</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> <control>-B +</tt></pre></dd> +</dl> +<p>If in open mode, the <control>-B command shall behave identically to the <b>z</b> command. Otherwise, if the current line +is the first line of the edit buffer, it shall be an error.</p> +<p>If the <b>window</b> edit option is less than 3, display a screen where the last line of the display shall be some portion +of:</p> +<pre> +<tt>(</tt><i>current first line</i><tt>) -1 +</tt></pre> +<p>otherwise, display a screen where the first line of the display shall be some portion of:</p> +<pre> +<tt>(</tt><i>current first line</i><tt>) - </tt><i>count</i><tt> x ((window edit option) -2) +</tt></pre> +<p>If this calculation would result in a line that is before the first line of the edit buffer, the first line of the display shall +display some portion of the first line of the edit buffer.</p> +<p><i>Current line</i>: If no lines from the previous display remain on the screen, set to the last line of the display; otherwise, +set to (<i>line</i> - the number of new lines displayed on this screen).</p> +<p><i>Current column</i>: Set to non-<blank>.</p> +<h5><a name="tag_20_146_13_04" id="tag_20_146_13_04"></a>Scroll Forward</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> <control>-D +</tt></pre></dd> +</dl> +<p>If the current line is the last line of the edit buffer, it shall be an error.</p> +<p>If no <i>count</i> is specified, <i>count</i> shall default to the <i>count</i> associated with the previous <control>-D +or <control>-U command. If there was no previous <control>-D or <control>-U command, <i>count</i> shall default +to the value of the <b>scroll</b> edit option.</p> +<p>If in open mode, write lines starting with the line after the current line, until <i>count</i> lines or the last line of the +file have been written.</p> +<p><i>Current line</i>: If the current line + <i>count</i> is past the last line of the edit buffer, set to the last line of the +edit buffer; otherwise, set to the current line + <i>count</i>.</p> +<p><i>Current column</i>: Set to non-<blank>.</p> +<h5><a name="tag_20_146_13_05" id="tag_20_146_13_05"></a>Scroll Forward by Line</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> <control>-E +</tt></pre></dd> +</dl> +<p>Display the line count lines after the last line currently displayed.</p> +<p>If the last line of the edit buffer is displayed, it shall be an error. If there is no line <i>count</i> lines after the last +line currently displayed, the last line of the display shall display some portion of the last line of the edit buffer.</p> +<p><i>Current line</i>: Unchanged if the previous current character is displayed; otherwise, set to the first line displayed.</p> +<p><i>Current column</i>: Unchanged.</p> +<h5><a name="tag_20_146_13_06" id="tag_20_146_13_06"></a>Page Forward</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> <control>-F +</tt></pre></dd> +</dl> +<p>If in open mode, the <control>-F command shall behave identically to the <b>z</b> command. Otherwise, if the current line +is the last line of the edit buffer, it shall be an error.</p> +<p>If the <b>window</b> edit option is less than 3, display a screen where the first line of the display shall be some portion +of:</p> +<pre> +<tt>(</tt><i>current last line</i><tt>) +1 +</tt></pre> +<p>otherwise, display a screen where the first line of the display shall be some portion of:</p> +<pre> +<tt>(</tt><i>current first line</i><tt>) + </tt><i>count</i><tt> x ((window edit option) -2) +</tt></pre> +<p>If this calculation would result in a line that is after the last line of the edit buffer, the last line of the display shall +display some portion of the last line of the edit buffer.</p> +<p><i>Current line</i>: If no lines from the previous display remain on the screen, set to the first line of the display; +otherwise, set to (<i>line</i> + the number of new lines displayed on this screen).</p> +<p><i>Current column</i>: Set to non-<blank>.</p> +<h5><a name="tag_20_146_13_07" id="tag_20_146_13_07"></a>Display Information</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt><control>-G +</tt></pre></dd> +</dl> +<p>This command shall be equivalent to the <a href="../utilities/ex.html"><i>ex</i></a> <b>file</b> command.</p> +<h5><a name="tag_20_146_13_08" id="tag_20_146_13_08"></a>Move Cursor Backwards</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> <control>-H +<br> +</tt><b>[</b><i>count</i><b>]</b><tt> h +<br> +the current </tt><i>erase</i><tt> character (see stty) +</tt></pre></dd> +</dl> +<p>If there are no characters before the current character on the current line, it shall be an error. If there are less than +<i>count</i> previous characters on the current line, <i>count</i> shall be adjusted to the number of previous characters on the +line.</p> +<p>If used as a motion command:</p> +<ol> +<li> +<p>The text region shall be from the character before the starting cursor up to and including the <i>count</i>th character before +the starting cursor.</p> +</li> +<li> +<p>Any text copied to a buffer shall be in character mode.</p> +</li> +</ol> +<p>If not used as a motion command:</p> +<p><i>Current line</i>: Unchanged.</p> +<p><i>Current column</i>: Set to (<i>column</i> - the number of columns occupied by <i>count</i> characters ending with the +previous current column).</p> +<h5><a name="tag_20_146_13_09" id="tag_20_146_13_09"></a>Move Down</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> <newline> +<br> +</tt><b>[</b><i>count</i><b>]</b><tt> <control>-J +<br> +</tt><b>[</b><i>count</i><b>]</b><tt> <control>-M +<br> +</tt><b>[</b><i>count</i><b>]</b><tt> <control>-N +<br> +</tt><b>[</b><i>count</i><b>]</b><tt> j +<br> +</tt><b>[</b><i>count</i><b>]</b><tt> <carriage-return> +<br> +</tt><b>[</b><i>count</i><b>]</b><tt> + +</tt></pre></dd> +</dl> +<p>If there are less than <i>count</i> lines after the current line in the edit buffer, it shall be an error.</p> +<p>If used as a motion command:</p> +<ol> +<li> +<p>The text region shall include the starting line and the next <i>count</i> - 1 lines.</p> +</li> +<li> +<p>Any text copied to a buffer shall be in line mode.</p> +</li> +</ol> +<p>If not used as a motion command:</p> +<p><i>Current line</i>: Set to <i>current line</i>+ <i>count</i>.</p> +<p><i>Current column</i>: Set to non-<blank> for the <carriage-return>, <control>-M, and <b>+</b> commands; +otherwise, unchanged.</p> +<h5><a name="tag_20_146_13_10" id="tag_20_146_13_10"></a>Clear and Redisplay</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt><control>-L +</tt></pre></dd> +</dl> +<p>If in open mode, clear the screen and redisplay the current line. Otherwise, clear and redisplay the screen.</p> +<p><i>Current line</i>: Unchanged.</p> +<p><i>Current column</i>: Unchanged.</p> +<h5><a name="tag_20_146_13_11" id="tag_20_146_13_11"></a>Move Up</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> <control>-P +<br> +</tt><b>[</b><i>count</i><b>]</b><tt> k +<br> +</tt><b>[</b><i>count</i><b>]</b><tt> - +</tt></pre></dd> +</dl> +<p>If there are less than <i>count</i> lines before the current line in the edit buffer, it shall be an error.</p> +<p>If used as a motion command:</p> +<ol> +<li> +<p>The text region shall include the starting line and the previous <i>count</i> lines.</p> +</li> +<li> +<p>Any text copied to a buffer shall be in line mode.</p> +</li> +</ol> +<p>If not used as a motion command:</p> +<p><i>Current line</i>: Set to <i>current line</i> - <i>count</i>.</p> +<p><i>Current column</i>: Set to non-<blank> for the <b>-</b> command; otherwise, unchanged.</p> +<h5><a name="tag_20_146_13_12" id="tag_20_146_13_12"></a>Redraw Screen</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt><control>-R +</tt></pre></dd> +</dl> +<p>If any lines have been deleted from the display screen and flagged as deleted on the terminal using the <b>@</b> convention (see +the beginning of the EXTENDED DESCRIPTION section), they shall be redisplayed to match the contents of the edit buffer.</p> +<p>It is unspecified whether lines flagged with <b>@</b> because they do not fit on the terminal display shall be affected.</p> +<p><i>Current line</i>: Unchanged.</p> +<p><i>Current column</i>: Unchanged.</p> +<h5><a name="tag_20_146_13_13" id="tag_20_146_13_13"></a>Scroll Backward</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> <control>-U +</tt></pre></dd> +</dl> +<p>If the current line is the first line of the edit buffer, it shall be an error.</p> +<p>If no <i>count</i> is specified, <i>count</i> shall default to the <i>count</i> associated with the previous <control>-D +or <control>-U command. If there was no previous <control>-D or <control>-U command, <i>count</i> shall default +to the value of the <b>scroll</b> edit option.</p> +<p><i>Current line</i>: If <i>count</i> is greater than the current line, set to 1; otherwise, set to the current line - +<i>count</i>.</p> +<p><i>Current column</i>: Set to non-<blank>.</p> +<h5><a name="tag_20_146_13_14" id="tag_20_146_13_14"></a>Scroll Backward by Line</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> <control>-Y +</tt></pre></dd> +</dl> +<p>Display the line <i>count</i> lines before the first line currently displayed.</p> +<p>If the current line is the first line of the edit buffer, it shall be an error. If this calculation would result in a line that +is before the first line of the edit buffer, the first line of the display shall display some portion of the first line of the edit +buffer.</p> +<p><i>Current line</i>: Unchanged if the previous current character is displayed; otherwise, set to the first line displayed.</p> +<p><i>Current column</i>: Unchanged.</p> +<h5><a name="tag_20_146_13_15" id="tag_20_146_13_15"></a>Edit the Alternate File</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt><control>-^ +</tt></pre></dd> +</dl> +This command shall be equivalent to the <a href="../utilities/ex.html"><i>ex</i></a> <b>edit</b> command, with the alternate +pathname as its argument. +<h5><a name="tag_20_146_13_16" id="tag_20_146_13_16"></a>Terminate Command or Input Mode</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt><ESC> +</tt></pre></dd> +</dl> +<p>If a partial <i>vi</i> command (as defined by at least one, non-<i>count</i> character) has been entered, discard the +<i>count</i> and the command character(s).</p> +<p>Otherwise, if no command characters have been entered, and the <ESC> was the result of a map expansion, the terminal shall +be alerted and the <ESC> character shall be discarded, but it shall not be an error.</p> +<p>Otherwise, it shall be an error.</p> +<p><i>Current line</i>: Unchanged.</p> +<p><i>Current column</i>: Unchanged.</p> +<h5><a name="tag_20_146_13_17" id="tag_20_146_13_17"></a>Search for tagstring</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt><control>-] +</tt></pre></dd> +</dl> +<p>If the current character is not a word or <blank>, it shall be an error.</p> +<p>This command shall be equivalent to the <a href="../utilities/ex.html"><i>ex</i></a> <b>tag</b> command, with the argument to +that command defined as follows.</p> +<p>If the current character is a <blank>:</p> +<ol> +<li> +<p>Skip all <blank> characters after the cursor up to the end of the line.</p> +</li> +<li> +<p>If the end of the line is reached, it shall be an error.</p> +</li> +</ol> +<p>Then, the argument to the <a href="../utilities/ex.html"><i>ex</i></a> <b>tag</b> command shall be the current character and all +subsequent characters, up to the first non-word character or the end of the line.</p> +<h5><a name="tag_20_146_13_18" id="tag_20_146_13_18"></a>Move Cursor Forward</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> <space> +<br> +</tt><b>[</b><i>count</i><b>]</b><tt> l</tt> (ell)<tt> +</tt></pre></dd> +</dl> +<p>If there are less than <i>count</i> non-<newline> characters after the cursor on the current line, <i>count</i> shall be +adjusted to the number of non-<newline> characters after the cursor on the line.</p> +<p>If used as a motion command:</p> +<ol> +<li> +<p>If the current or <i>count</i>th character after the cursor is the last non-<newline> in the line, the text region shall +be comprised of the current character up to and including the last non-<newline> in the line. Otherwise, the text region +shall be from the current character up to, but not including, the <i>count</i>th character after the cursor.</p> +</li> +<li> +<p>Any text copied to a buffer shall be in character mode.</p> +</li> +</ol> +<p>If not used as a motion command:</p> +<p>If there are no non-<newline> characters after the current character on the current line, it shall be an error.</p> +<p><i>Current line</i>: Unchanged.</p> +<p><i>Current column</i>: Set to the last column that displays any portion of the <i>count</i>th character after the current +character.</p> +<h5><a name="tag_20_146_13_19" id="tag_20_146_13_19"></a>Replace Text with Results from Shell Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> ! </tt><i>motion shell-commands</i><tt> <newline> +</tt></pre></dd> +</dl> +<p>If the motion command is the <b>!</b> command repeated:</p> +<ol> +<li> +<p>If the edit buffer is empty and no <i>count</i> was supplied, the command shall be the equivalent of the <a href= +"../utilities/ex.html"><i>ex</i></a> <b>:read</b> <b>!</b> command, with the text input, and no text shall be copied to any +buffer.</p> +</li> +<li> +<p>Otherwise:</p> +<ol type="a"> +<li> +<p>If there are less than <i>count</i> -1 lines after the current line in the edit buffer, it shall be an error.</p> +</li> +<li> +<p>The text region shall be from the current line up to and including the next <i>count</i> -1 lines.</p> +</li> +</ol> +</li> +</ol> +<p>Otherwise, the text region shall be the lines in which any character of the text region specified by the motion command +appear.</p> +<p>Any text copied to a buffer shall be in line mode.</p> +<p>This command shall be equivalent to the <a href="../utilities/ex.html"><i>ex</i></a> <b>!</b> command for the specified +lines.</p> +<h5><a name="tag_20_146_13_20" id="tag_20_146_13_20"></a>Move Cursor to End-of-Line</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> $ +</tt></pre></dd> +</dl> +<p>It shall be an error if there are less than (<i>count</i> -1) lines after the current line in the edit buffer.</p> +<p>If used as a motion command:</p> +<ol> +<li> +<p>If <i>count</i> is 1:</p> +<ol type="a"> +<li> +<p>It shall be an error if the line is empty.</p> +</li> +<li> +<p>Otherwise, the text region shall consist of all characters from the starting cursor to the last non-<newline> in the line, +inclusive, and any text copied to a buffer shall be in character mode.</p> +</li> +</ol> +</li> +<li> +<p>Otherwise, if the starting cursor position is at or before the first non-<blank> in the line, the text region shall +consist of the current and the next <i>count</i> -1 lines, and any text saved to a buffer shall be in line mode.</p> +</li> +<li> +<p>Otherwise, the text region shall consist of all characters from the starting cursor to the last non-<newline> in the line +that is <i>count</i> -1 lines forward from the current line, and any text copied to a buffer shall be in character mode.</p> +</li> +</ol> +<p>If not used as a motion command:</p> +<p><i>Current line</i>: Set to the <i>current line</i> + <i>count</i>-1.</p> +<p><i>Current column</i>: The current column is set to the last display line column of the last non-<newline> in the line, or +column position 1 if the line is empty.</p> +<p>The current column shall be adjusted to be on the last display line column of the last non-<newline> of the current line +as subsequent commands change the current line, until a command changes the current column.</p> +<h5><a name="tag_20_146_13_21" id="tag_20_146_13_21"></a>Move to Matching Character</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>% +</tt></pre></dd> +</dl> +<p>If the character at the current position is not a parenthesis, bracket, or curly brace, search forward in the line to the first +one of those characters. If no such character is found, it shall be an error.</p> +<p>The matching character shall be the parenthesis, bracket, or curly brace matching the parenthesis, bracket, or curly brace, +respectively, that was at the current position or that was found on the current line.</p> +<p>Matching shall be determined as follows, for an open parenthesis:</p> +<ol> +<li> +<p>Set a counter to 1.</p> +</li> +<li> +<p>Search forwards until a parenthesis is found or the end of the edit buffer is reached.</p> +</li> +<li> +<p>If the end of the edit buffer is reached, it shall be an error.</p> +</li> +<li> +<p>If an open parenthesis is found, increment the counter by 1.</p> +</li> +<li> +<p>If a close parenthesis is found, decrement the counter by 1.</p> +</li> +<li> +<p>If the counter is zero, the current character is the matching character.</p> +</li> +</ol> +<p>Matching for a close parenthesis shall be equivalent, except that the search shall be backwards, from the starting character to +the beginning of the buffer, a close parenthesis shall increment the counter by 1, and an open parenthesis shall decrement the +counter by 1.</p> +<p>Matching for brackets and curly braces shall be equivalent, except that searching shall be done for open and close brackets or +open and close curly braces. It is implementation-defined whether other characters are searched for and matched as well.</p> +<p>If used as a motion command:</p> +<ol> +<li> +<p>If the matching cursor was after the starting cursor in the edit buffer, and the starting cursor position was at or before the +first non-<blank> non-<newline> in the starting line, and the matching cursor position was at or after the last +non-<blank> non-<newline> in the matching line, the text region shall consist of the current line to the matching line, +inclusive, and any text copied to a buffer shall be in line mode.</p> +</li> +<li> +<p>If the matching cursor was before the starting cursor in the edit buffer, and the starting cursor position was at or after the +last non-<blank> non-<newline> in the starting line, and the matching cursor position was at or before the first +non-<blank> non-<newline> in the matching line, the text region shall consist of the current line to the matching line, +inclusive, and any text copied to a buffer shall be in line mode.</p> +</li> +<li> +<p>Otherwise, the text region shall consist of the starting character to the matching character, inclusive, and any text copied to +a buffer shall be in character mode.</p> +</li> +</ol> +<p>If not used as a motion command:</p> +<p><i>Current line</i>: Set to the line where the matching character is located.</p> +<p><i>Current column</i>: Set to the last column where any portion of the matching character is displayed.</p> +<h5><a name="tag_20_146_13_22" id="tag_20_146_13_22"></a>Repeat Substitution</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>& +</tt></pre></dd> +</dl> +<p>Repeat the previous substitution command. This command shall be equivalent to the <a href="../utilities/ex.html"><i>ex</i></a> +<b>&</b> command with the current line as its addresses, and without <i>options</i>, <i>count</i>, or <i>flags</i>.</p> +<h5><a name="tag_20_146_13_23" id="tag_20_146_13_23"></a>Return to Previous Context at Beginning of Line</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>' </tt><i>character</i><tt> +</tt></pre></dd> +</dl> +<p>It shall be an error if there is no line in the edit buffer marked by <i>character</i>.</p> +<p>If used as a motion command:</p> +<ol> +<li> +<p>If the starting cursor is after the marked cursor, then the locations of the starting cursor and the marked cursor in the edit +buffer shall be logically swapped.</p> +</li> +<li> +<p>The text region shall consist of the starting line up to and including the marked line, and any text copied to a buffer shall be +in line mode.</p> +</li> +</ol> +<p>If not used as a motion command:</p> +<p><i>Current line</i>: Set to the line referenced by the mark.</p> +<p><i>Current column</i>: Set to non-<blank>.</p> +<h5><a name="tag_20_146_13_24" id="tag_20_146_13_24"></a>Return to Previous Context</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>` </tt><i>character</i><tt> +</tt></pre></dd> +</dl> +<p>It shall be an error if the marked line is no longer in the edit buffer. If the marked line no longer contains a character in +the saved numbered character position, it shall be as if the marked position is the first non-<blank>.</p> +<p>If used as a motion command:</p> +<ol> +<li> +<p>It shall be an error if the marked cursor references the same character in the edit buffer as the starting cursor.</p> +</li> +<li> +<p>If the starting cursor is after the marked cursor, then the locations of the starting cursor and the marked cursor in the edit +buffer shall be logically swapped.</p> +</li> +<li> +<p>If the starting line is empty or the starting cursor is at or before the first non-<blank> non-<newline> of the +starting line, and the marked cursor line is empty or the marked cursor references the first character of the marked cursor line, +the text region shall consist of all lines containing characters from the starting cursor to the line before the marked cursor +line, inclusive, and any text copied to a buffer shall be in line mode.</p> +</li> +<li> +<p>Otherwise, if the marked cursor line is empty or the marked cursor references a character at or before the first +non-<blank> non-<newline> of the marked cursor line, the region of text shall be from the starting cursor to the last +non-<newline> of the line before the marked cursor line, inclusive, and any text copied to a buffer shall be in character +mode.</p> +</li> +<li> +<p>Otherwise, the region of text shall be from the starting cursor (inclusive), to the marked cursor (exclusive), and any text +copied to a buffer shall be in character mode.</p> +</li> +</ol> +<p>If not used as a motion command:</p> +<p><i>Current line</i>: Set to the line referenced by the mark.</p> +<p><i>Current column</i>: Set to the last column in which any portion of the character referenced by the mark is displayed.</p> +<h5><a name="tag_20_146_13_25" id="tag_20_146_13_25"></a>Return to Previous Section</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> [[ +</tt></pre></dd> +</dl> +<p>Move the cursor backward through the edit buffer to the first character of the previous section boundary, <i>count</i> +times.</p> +<p>If used as a motion command:</p> +<ol> +<li> +<p>If the starting cursor was at the first character of the starting line or the starting line was empty, and the first character +of the boundary was the first character of the boundary line, the text region shall consist of the current line up to and including +the line where the <i>count</i>th next boundary starts, and any text copied to a buffer shall be in line mode.</p> +</li> +<li> +<p>If the boundary was the last line of the edit buffer or the last non-<newline> of the last line of the edit buffer, the +text region shall consist of the last character in the edit buffer up to and including the starting character, and any text saved +to a buffer shall be in character mode.</p> +</li> +<li> +<p>Otherwise, the text region shall consist of the starting character up to but not including the first character in the +<i>count</i>th next boundary, and any text copied to a buffer shall be in character mode.</p> +</li> +</ol> +<p>If not used as a motion command:</p> +<p><i>Current line</i>: Set to the line where the <i>count</i>th next boundary in the edit buffer starts.</p> +<p><i>Current column</i>: Set to the last column in which any portion of the first character of the <i>count</i>th next boundary is +displayed, or column position 1 if the line is empty.</p> +<h5><a name="tag_20_146_13_26" id="tag_20_146_13_26"></a>Move to Next Section</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> ]] +</tt></pre></dd> +</dl> +<p>Move the cursor forward through the edit buffer to the first character of the next section boundary, <i>count</i> times.</p> +<p>If used as a motion command:</p> +<ol> +<li> +<p>If the starting cursor was at the first character of the starting line or the starting line was empty, and the first character +of the boundary was the first character of the boundary line, the text region shall consist of the current line up to and including +the line where the <i>count</i>th previous boundary starts, and any text copied to a buffer shall be in line mode.</p> +</li> +<li> +<p>If the boundary was the first line of the edit buffer, the text region shall consist of the first character in the edit buffer +up to but not including the starting character, and any text copied to a buffer shall be in character mode.</p> +</li> +<li> +<p>Otherwise, the text region shall consist of the first character in the <i>count</i>th previous section boundary up to but not +including the starting character, and any text copied to a buffer shall be in character mode.</p> +</li> +</ol> +<p>If not used as a motion command:</p> +<p><i>Current line</i>: Set to the line where the <i>count</i>th previous boundary in the edit buffer starts.</p> +<p><i>Current column</i>: Set to the last column in which any portion of the first character of the <i>count</i>th previous +boundary is displayed, or column position 1 if the line is empty.</p> +<h5><a name="tag_20_146_13_27" id="tag_20_146_13_27"></a>Move to First Non-<blank> Position on Current Line</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>^ +</tt></pre></dd> +</dl> +If used as a motion command: +<ol> +<li> +<p>If the line has no non-<blank> non-<newline> characters, or if the cursor is at the first non-<blank> +non-<newline> of the line, it shall be an error.</p> +</li> +<li> +<p>If the cursor is before the first non-<blank> non-<newline> of the line, the text region shall be comprised of the +current character, up to, but not including, the first non-<blank> non-<newline> of the line.</p> +</li> +<li> +<p>If the cursor is after the first non-<blank> non-<newline> of the line, the text region shall be from the character +before the starting cursor up to and including the first non-<blank> non-<newline> of the line.</p> +</li> +<li> +<p>Any text copied to a buffer shall be in character mode.</p> +</li> +</ol> +<p>If not used as a motion command:</p> +<p><i>Current line</i>: Unchanged.</p> +<p><i>Current column</i>: Set to non-<blank>.</p> +<h5><a name="tag_20_146_13_28" id="tag_20_146_13_28"></a>Current and Line Above</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> _ +</tt></pre></dd> +</dl> +<p>If there are less than <i>count</i> -1 lines after the current line in the edit buffer, it shall be an error.</p> +<p>If used as a motion command:</p> +<ol> +<li> +<p>If <i>count</i> is less than 2, the text region shall be the current line.</p> +</li> +<li> +<p>Otherwise, the text region shall include the starting line and the next <i>count</i> -1 lines.</p> +</li> +<li> +<p>Any text copied to a buffer shall be in line mode.</p> +</li> +</ol> +<p>If not used as a motion command:</p> +<p><i>Current line</i>: Set to current line + <i>count</i> -1.</p> +<p><i>Current column</i>: Set to non-<blank>.</p> +<h5><a name="tag_20_146_13_29" id="tag_20_146_13_29"></a>Move Back to Beginning of Sentence</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> ( +</tt></pre></dd> +</dl> +<p>Move backward to the beginning of a sentence. This command shall be equivalent to the <b>[[</b> command, with the exception that +sentence boundaries shall be used instead of section boundaries.</p> +<h5><a name="tag_20_146_13_30" id="tag_20_146_13_30"></a>Move Forward to Beginning of Sentence</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> ) +</tt></pre></dd> +</dl> +<p>Move forward to the beginning of a sentence. This command shall be equivalent to the <b>]]</b> command, with the exception that +sentence boundaries shall be used instead of section boundaries.</p> +<h5><a name="tag_20_146_13_31" id="tag_20_146_13_31"></a>Move Back to Preceding Paragraph</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> { +</tt></pre></dd> +</dl> +<p>Move back to the beginning of the preceding paragraph. This command shall be equivalent to the <b>[[</b> command, with the +exception that paragraph boundaries shall be used instead of section boundaries.</p> +<h5><a name="tag_20_146_13_32" id="tag_20_146_13_32"></a>Move Forward to Next Paragraph</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> } +</tt></pre></dd> +</dl> +<p>Move forward to the beginning of the next paragraph. This command shall be equivalent to the <b>]]</b> command, with the +exception that paragraph boundaries shall be used instead of section boundaries.</p> +<h5><a name="tag_20_146_13_33" id="tag_20_146_13_33"></a>Move to Specific Column Position</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> | +</tt></pre></dd> +</dl> +<p>For the purposes of this command, lines that are too long for the current display and that have been folded shall be treated as +having a single, 1-based, number of columns.</p> +<p>If there are less than <i>count</i> columns in which characters from the current line are displayed on the screen, <i>count</i> +shall be adjusted to be the last column in which any portion of the line is displayed on the screen.</p> +<p>If used as a motion command:</p> +<ol> +<li> +<p>If the line is empty, or the cursor character is the same as the character on the <i>count</i>th column of the line, it shall be +an error.</p> +</li> +<li> +<p>If the cursor is before the <i>count</i>th column of the line, the text region shall be comprised of the current character, up +to but not including the character on the <i>count</i>th column of the line.</p> +</li> +<li> +<p>If the cursor is after the <i>count</i>th column of the line, the text region shall be from the character before the starting +cursor up to and including the character on the <i>count</i>th column of the line.</p> +</li> +<li> +<p>Any text copied to a buffer shall be in character mode.</p> +</li> +</ol> +<p>If not used as a motion command:</p> +<p><i>Current line</i>: Unchanged.</p> +<p><i>Current column</i>: Set to the last column in which any portion of the character that is displayed in the <i>count</i> column +of the line is displayed.</p> +<h5><a name="tag_20_146_13_34" id="tag_20_146_13_34"></a>Reverse Find Character</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> , +</tt></pre></dd> +</dl> +<p>If the last <b>F</b>, <b>f</b>, <b>T</b>, or <b>t</b> command was <b>F</b>, <b>f</b>, <b>T</b>, or <b>t</b>, this command shall +be equivalent to an <b>f</b>, <b>F</b>, <b>t</b>, or <b>T</b> command, respectively, with the specified <i>count</i> and the same +search character.</p> +<p>If there was no previous <b>F</b>, <b>f</b>, <b>T</b>, or <b>t</b> command, it shall be an error.</p> +<h5><a name="tag_20_146_13_35" id="tag_20_146_13_35"></a>Repeat</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> . +</tt></pre></dd> +</dl> +<p>Repeat the last <b>!</b>, <b><</b>, <b>></b>, <b>A</b>, <b>C</b>, <b>D</b>, <b>I</b>, <b>J</b>, <b>O</b>, <b>P</b>, +<b>R</b>, <b>S</b>, <b>X</b>, <b>Y</b>, <b>a</b>, <b>c</b>, <b>d</b>, <b>i</b>, <b>o</b>, <b>p</b>, <b>r</b>, <b>s</b>, <b>x</b>, +<b>y</b>, or <b>~</b> command. It shall be an error if none of these commands have been executed. Commands (other than commands +that enter text input mode) executed as a result of map expansions, shall not change the value of the last repeatable command.</p> +<p>Repeated commands with associated motion commands shall repeat the motion command as well; however, any specified <i>count</i> +shall replace the <i>count</i>(s) that were originally specified to the repeated command or its associated motion command.</p> +<p>If the motion component of the repeated command is <b>f</b>, <b>F</b>, <b>t</b>, or <b>T</b>, the repeated command shall not set +the remembered search character for the <b>;</b> and <b>,</b> commands.</p> +<p>If the repeated command is <b>p</b> or <b>P</b>, and the buffer associated with that command was a numeric buffer named with a +number less than 9, the buffer associated with the repeated command shall be set to be the buffer named by the name of the previous +buffer logically incremented by 1.</p> +<p>If the repeated character is a text input command, the input text associated with that command is repeated literally:</p> +<ul> +<li> +<p>Input characters are neither macro or abbreviation-expanded.</p> +</li> +<li> +<p>Input characters are not interpreted in any special way with the exception that <newline>, <carriage-return>, and +<control>-T behave as described in <a href="#tag_20_146_13_88">Input Mode Commands in vi</a> .</p> +</li> +</ul> +<p><i>Current line</i>: Set as described for the repeated command.</p> +<p><i>Current column</i>: Set as described for the repeated command.</p> +<h5><a name="tag_20_146_13_36" id="tag_20_146_13_36"></a>Find Regular Expression</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>/ +</tt></pre></dd> +</dl> +<p>If the input line contains no non-<newline> characters, it shall be equivalent to a line containing only the last regular +expression encountered. The enhanced regular expressions supported by <i>vi</i> are described in <a href= +"../utilities/ex.html#tag_20_40_13_58"><i>Regular Expressions in ex</i></a> .</p> +<p>Otherwise, the line shall be interpreted as one or more regular expressions, optionally followed by an address offset or a +<i>vi</i> <b>z</b> command.</p> +<p>If the regular expression is not the last regular expression on the line, or if a line offset or <b>z</b> command is specified, +the regular expression shall be terminated by an unescaped <tt>'/'</tt> character, which shall not be used as part of the regular +expression. If the regular expression is not the first regular expression on the line, it shall be preceded by zero or more +<blank> characters, a <semicolon>, zero or more <blank> characters, and a leading <tt>'/'</tt> character, which +shall not be interpreted as part of the regular expression. It shall be an error to precede any regular expression with any +characters other than these.</p> +<p>Each search shall begin from the character after the first character of the last match (or, if it is the first search, after the +cursor). If the <b>wrapscan</b> edit option is set, the search shall continue to the character before the starting cursor +character; otherwise, to the end of the edit buffer. It shall be an error if any search fails to find a match, and an informational +message to this effect shall be displayed.</p> +<p>An optional address offset (see <a href="../utilities/ex.html#tag_20_40_13_02"><i>Addressing in ex</i></a> ) can be specified +after the last regular expression by including a trailing <tt>'/'</tt> character after the regular expression and specifying the +address offset. This offset shall be from the line containing the match for the last regular expression specified. It shall be an +error if the line offset would indicate a line address less than 1 or greater than the last line in the edit buffer. An address +offset of zero shall be supported. It shall be an error to follow the address offset with any other characters than <blank> +characters.</p> +<p>If not used as a motion command, an optional <b>z</b> command (see <a href="#tag_20_146_13_86">Redraw Window</a> ) can be +specified after the last regular expression by including a trailing <tt>'/'</tt> character after the regular expression, zero or +more <blank> characters, a <tt>'z'</tt>, zero or more <blank> characters, an optional new <b>window</b> edit option +value, zero or more <blank> characters, and a location character. The effect shall be as if the <b>z</b> command was executed +after the <b>/</b> command. It shall be an error to follow the <b>z</b> command with any other characters than <blank> +characters.</p> +<p>The remembered search direction shall be set to forward.</p> +<p>If used as a motion command:</p> +<ol> +<li> +<p>It shall be an error if the last match references the same character in the edit buffer as the starting cursor.</p> +</li> +<li> +<p>If any address offset is specified, the last match shall be adjusted by the specified offset as described previously.</p> +</li> +<li> +<p>If the starting cursor is after the last match, then the locations of the starting cursor and the last match in the edit buffer +shall be logically swapped.</p> +</li> +<li> +<p>If any address offset is specified, the text region shall consist of all lines containing characters from the starting cursor to +the last match line, inclusive, and any text copied to a buffer shall be in line mode.</p> +</li> +<li> +<p>Otherwise, if the starting line is empty or the starting cursor is at or before the first non-<blank> non-<newline> +of the starting line, and the last match line is empty or the last match starts at the first character of the last match line, the +text region shall consist of all lines containing characters from the starting cursor to the line before the last match line, +inclusive, and any text copied to a buffer shall be in line mode.</p> +</li> +<li> +<p>Otherwise, if the last match line is empty or the last match begins at a character at or before the first non-<blank> +non-<newline> of the last match line, the region of text shall be from the current cursor to the last non-<newline> of +the line before the last match line, inclusive, and any text copied to a buffer shall be in character mode.</p> +</li> +<li> +<p>Otherwise, the region of text shall be from the current cursor (inclusive), to the first character of the last match +(exclusive), and any text copied to a buffer shall be in character mode.</p> +</li> +</ol> +<p>If not used as a motion command:</p> +<p><i>Current line</i>: If a match is found, set to the last matched line plus the address offset, if any; otherwise, +unchanged.</p> +<p><i>Current column</i>: Set to the last column on which any portion of the first character in the last matched string is +displayed, if a match is found; otherwise, unchanged.</p> +<h5><a name="tag_20_146_13_37" id="tag_20_146_13_37"></a>Move to First Character in Line</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>0 </tt>(zero)<tt> +</tt></pre></dd> +</dl> +<p>Move to the first character on the current line. The character <tt>'0'</tt> shall not be interpreted as a command if it is +immediately preceded by a digit.</p> +<p>If used as a motion command:</p> +<ol> +<li> +<p>If the cursor character is the first character in the line, it shall be an error.</p> +</li> +<li> +<p>The text region shall be from the character before the cursor character up to and including the first character in the line.</p> +</li> +<li> +<p>Any text copied to a buffer shall be in character mode.</p> +</li> +</ol> +<p>If not used as a motion command:</p> +<p><i>Current line</i>: Unchanged.</p> +<p><i>Current column</i>: The last column in which any portion of the first character in the line is displayed, or if the line is +empty, unchanged.</p> +<h5><a name="tag_20_146_13_38" id="tag_20_146_13_38"></a>Execute an ex Command</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>: +</tt></pre></dd> +</dl> +<p>Execute one or more <a href="../utilities/ex.html"><i>ex</i></a> commands.</p> +<p>If any portion of the screen other than the last line of the screen was overwritten by any <a href= +"../utilities/ex.html"><i>ex</i></a> command (except <b>shell</b>), <i>vi</i> shall display a message indicating that it is waiting +for an input from the user, and shall then read a character. This action may also be taken for other, unspecified reasons.</p> +<p>If the next character entered is a <tt>':'</tt>, another <a href="../utilities/ex.html"><i>ex</i></a> command shall be accepted +and executed. Any other character shall cause the screen to be refreshed and <i>vi</i> shall return to command mode.</p> +<p><i>Current line</i>: As specified for the <a href="../utilities/ex.html"><i>ex</i></a> command.</p> +<p><i>Current column</i>: As specified for the <a href="../utilities/ex.html"><i>ex</i></a> command.</p> +<h5><a name="tag_20_146_13_39" id="tag_20_146_13_39"></a>Repeat Find</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> ; +</tt></pre></dd> +</dl> +<p>This command shall be equivalent to the last <b>F</b>, <b>f</b>, <b>T</b>, or <b>t</b> command, with the specified <i>count</i>, +and with the same search character used for the last <b>F</b>, <b>f</b>, <b>T</b>, or <b>t</b> command. If there was no previous +<b>F</b>, <b>f</b>, <b>T</b>, or <b>t</b> command, it shall be an error.</p> +<h5><a name="tag_20_146_13_40" id="tag_20_146_13_40"></a>Shift Left</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> < </tt><i>motion</i><tt> +</tt></pre></dd> +</dl> +<p>If the motion command is the <b><</b> command repeated:</p> +<ol> +<li> +<p>If there are less than <i>count</i> -1 lines after the current line in the edit buffer, it shall be an error.</p> +</li> +<li> +<p>The text region shall be from the current line, up to and including the next <i>count</i> -1 lines.</p> +</li> +</ol> +<p>Shift any line in the text region specified by the <i>count</i> and motion command one shiftwidth (see the <a href= +"../utilities/ex.html"><i>ex</i></a> <b>shiftwidth</b> option) toward the start of the line, as described by the <a href= +"../utilities/ex.html"><i>ex</i></a> <b><</b> command. The unshifted lines shall be copied to the unnamed buffer in line +mode.</p> +<p><i>Current line</i>: If the motion was from the current cursor position toward the end of the edit buffer, unchanged. Otherwise, +set to the first line in the edit buffer that is part of the text region specified by the motion command.</p> +<p><i>Current column</i>: Set to non-<blank>.</p> +<h5><a name="tag_20_146_13_41" id="tag_20_146_13_41"></a>Shift Right</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> > </tt><i>motion</i><tt> +</tt></pre></dd> +</dl> +<p>If the motion command is the <b>></b> command repeated:</p> +<ol> +<li> +<p>If there are less than <i>count</i> -1 lines after the current line in the edit buffer, it shall be an error.</p> +</li> +<li> +<p>The text region shall be from the current line, up to and including the next <i>count</i> -1 lines.</p> +</li> +</ol> +<p>Shift any line with characters in the text region specified by the <i>count</i> and motion command one shiftwidth (see the +<a href="../utilities/ex.html"><i>ex</i></a> <b>shiftwidth</b> option) away from the start of the line, as described by the +<a href="../utilities/ex.html"><i>ex</i></a> <b>></b> command. The unshifted lines shall be copied into the unnamed buffer in +line mode.</p> +<p><i>Current line</i>: If the motion was from the current cursor position toward the end of the edit buffer, unchanged. Otherwise, +set to the first line in the edit buffer that is part of the text region specified by the motion command.</p> +<p><i>Current column</i>: Set to non-<blank>.</p> +<h5><a name="tag_20_146_13_42" id="tag_20_146_13_42"></a>Scan Backwards for Regular Expression</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>? +</tt></pre></dd> +</dl> +<p>Scan backwards; the <b>?</b> command shall be equivalent to the <b>/</b> command (see <a href="#tag_20_146_13_36">Find Regular +Expression</a> ) with the following exceptions:</p> +<ol> +<li> +<p>The input prompt shall be a <tt>'?'</tt>.</p> +</li> +<li> +<p>Each search shall begin from the character before the first character of the last match (or, if it is the first search, the +character before the cursor character).</p> +</li> +<li> +<p>The search direction shall be from the cursor toward the beginning of the edit buffer, and the <b>wrapscan</b> edit option shall +affect whether the search wraps to the end of the edit buffer and continues.</p> +</li> +<li> +<p>The remembered search direction shall be set to backward.</p> +</li> +</ol> +<h5><a name="tag_20_146_13_43" id="tag_20_146_13_43"></a>Execute</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>@</tt><i>buffer</i><tt> +</tt></pre></dd> +</dl> +<p>If the <i>buffer</i> is specified as <b>@</b>, the last buffer executed shall be used. If no previous buffer has been executed, +it shall be an error.</p> +<p>Behave as if the contents of the named buffer were entered as standard input. After each line of a line-mode buffer, and all but +the last line of a character mode buffer, behave as if a <newline> were entered as standard input.</p> +<p>If an error occurs during this process, an error message shall be written, and no more characters resulting from the execution +of this command shall be processed.</p> +<p>If a <i>count</i> is specified, behave as if that count were entered as user input before the characters from the <b>@</b> +buffer were entered.</p> +<p><i>Current line</i>: As specified for the individual commands.</p> +<p><i>Current column</i>: As specified for the individual commands.</p> +<h5><a name="tag_20_146_13_44" id="tag_20_146_13_44"></a>Reverse Case</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> ~ +</tt></pre></dd> +</dl> +<p>Reverse the case of the current character and the next <i>count</i> -1 characters, such that lowercase characters that have +uppercase counterparts shall be changed to uppercase characters, and uppercase characters that have lowercase counterparts shall be +changed to lowercase characters, as prescribed by the current locale. No other characters shall be affected by this command.</p> +<p>If there are less than <i>count</i> -1 characters after the cursor in the edit buffer, <i>count</i> shall be adjusted to the +number of characters after the cursor in the edit buffer minus 1.</p> +<p>For the purposes of this command, the next character after the last non-<newline> on the line shall be the next character +in the edit buffer.</p> +<p><i>Current line</i>: Set to the line including the (<i>count</i>-1)th character after the cursor.</p> +<p><i>Current column</i>: Set to the last column in which any portion of the (<i>count</i>-1)th character after the cursor is +displayed.</p> +<h5><a name="tag_20_146_13_45" id="tag_20_146_13_45"></a>Append</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> a +</tt></pre></dd> +</dl> +<p>Enter text input mode after the current cursor position. No characters already in the edit buffer shall be affected by this +command. A <i>count</i> shall cause the input text to be appended <i>count</i> -1 more times to the end of the input.</p> +<p><i>Current line/column</i>: As specified for the text input commands (see <a href="#tag_20_146_13_88">Input Mode Commands in +vi</a> ).</p> +<h5><a name="tag_20_146_13_46" id="tag_20_146_13_46"></a>Append at End-of-Line</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> A +</tt></pre></dd> +</dl> +<p>This command shall be equivalent to the <i>vi</i> command:</p> +<pre> +<tt>$</tt><b> [ </b><i>count </i><b>]</b><tt> a +</tt></pre> +<p>(see <a href="#tag_20_146_13_45">Append</a> ).</p> +<h5><a name="tag_20_146_13_47" id="tag_20_146_13_47"></a>Move Backward to Preceding Word</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> b +</tt></pre></dd> +</dl> +<p>With the exception that words are used as the delimiter instead of bigwords, this command shall be equivalent to the <b>B</b> +command.</p> +<h5><a name="tag_20_146_13_48" id="tag_20_146_13_48"></a>Move Backward to Preceding Bigword</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> B +</tt></pre></dd> +</dl> +<p>If the edit buffer is empty or the cursor is on the first character of the edit buffer, it shall be an error. If less than +<i>count</i> bigwords begin between the cursor and the start of the edit buffer, <i>count</i> shall be adjusted to the number of +bigword beginnings between the cursor and the start of the edit buffer.</p> +<p>If used as a motion command:</p> +<ol> +<li> +<p>The text region shall be from the first character of the <i>count</i>th previous bigword beginning up to but not including the +cursor character.</p> +</li> +<li> +<p>Any text copied to a buffer shall be in character mode.</p> +</li> +</ol> +<p>If not used as a motion command:</p> +<p><i>Current line</i>: Set to the line containing the <i>current column</i>.</p> +<p><i>Current column</i>: Set to the last column upon which any part of the first character of the <i>count</i>th previous bigword +is displayed.</p> +<h5><a name="tag_20_146_13_49" id="tag_20_146_13_49"></a>Change</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>buffer</i><b>][</b><i>count</i><b>]</b><tt> c </tt><i>motion</i><tt> +</tt></pre></dd> +</dl> +<p>If the motion command is the <b>c</b> command repeated:</p> +<ol> +<li> +<p>The buffer text shall be in line mode.</p> +</li> +<li> +<p>If there are less than <i>count</i> -1 lines after the current line in the edit buffer, it shall be an error.</p> +</li> +<li> +<p>The text region shall be from the current line up to and including the next <i>count</i> -1 lines.</p> +</li> +</ol> +<p>Otherwise, the buffer text mode and text region shall be as specified by the motion command.</p> +<p>The replaced text shall be copied into <i>buffer</i>, if specified, and into the unnamed buffer. If the text to be replaced +contains characters from more than a single line, or the buffer text is in line mode, the replaced text shall be copied into the +numeric buffers as well.</p> +<p>If the buffer text is in line mode:</p> +<ol> +<li> +<p>Any lines that contain characters in the region shall be deleted, and the editor shall enter text input mode at the beginning of +a new line which shall replace the first line deleted.</p> +</li> +<li> +<p>If the <b>autoindent</b> edit option is set, <b>autoindent</b> characters equal to the <b>autoindent</b> characters on the first +line deleted shall be inserted as if entered by the user.</p> +</li> +</ol> +<p>Otherwise, if characters from more than one line are in the region of text:</p> +<ol> +<li> +<p>The text shall be deleted.</p> +</li> +<li> +<p>Any text remaining in the last line in the text region shall be appended to the first line in the region, and the last line in +the region shall be deleted.</p> +</li> +<li> +<p>The editor shall enter text input mode after the last character not deleted from the first line in the text region, if any; +otherwise, on the first column of the first line in the region.</p> +</li> +</ol> +<br> +<p>Otherwise:</p> +<ol> +<li> +<p>If the glyph for <tt>'$'</tt> is smaller than the region, the end of the region shall be marked with a <tt>'$'</tt>.</p> +</li> +<li> +<p>The editor shall enter text input mode, overwriting the region of text.</p> +</li> +</ol> +<p><i>Current line/column</i>: As specified for the text input commands (see <a href="#tag_20_146_13_88">Input Mode Commands in +vi</a> ).</p> +<h5><a name="tag_20_146_13_50" id="tag_20_146_13_50"></a>Change to End-of-Line</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>buffer</i><b>][</b><i>count</i><b>]</b><tt> C +</tt></pre></dd> +</dl> +<p>This command shall be equivalent to the <i>vi</i> command:</p> +<pre> +<b>[</b><i>buffer</i><b>][</b><i>count</i><b>]</b><tt> c$ +</tt></pre> +<p>See the <b>c</b> command.</p> +<h5><a name="tag_20_146_13_51" id="tag_20_146_13_51"></a>Delete</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>buffer</i><b>][</b><i>count</i><b>]</b><tt> d </tt><i>motion</i><tt> +</tt></pre></dd> +</dl> +<p>If the motion command is the <b>d</b> command repeated:</p> +<ol> +<li> +<p>The buffer text shall be in line mode.</p> +</li> +<li> +<p>If there are less than <i>count</i> -1 lines after the current line in the edit buffer, it shall be an error.</p> +</li> +<li> +<p>The text region shall be from the current line up to and including the next <i>count</i> -1 lines.</p> +</li> +</ol> +<p>Otherwise, the buffer text mode and text region shall be as specified by the motion command.</p> +<p>If in open mode, and the current line is deleted, and the line remains on the display, an <tt>'@'</tt> character shall be +displayed as the first glyph of that line.</p> +<p>Delete the region of text into <i>buffer</i>, if specified, and into the unnamed buffer. If the text to be deleted contains +characters from more than a single line, or the buffer text is in line mode, the deleted text shall be copied into the numeric +buffers, as well.</p> +<p><i>Current line</i>: Set to the first text region line that appears in the edit buffer, unless that line has been deleted, in +which case it shall be set to the last line in the edit buffer, or line 1 if the edit buffer is empty.</p> +<p><i>Current column</i>:</p> +<ol> +<li> +<p>If the line is empty, set to column position 1.</p> +</li> +<li> +<p>Otherwise, if the buffer text is in line mode or the motion was from the cursor toward the end of the edit buffer:</p> +<ol type="a"> +<li> +<p>If a character from the current line is displayed in the current column, set to the last column that displays any portion of +that character.</p> +</li> +<li> +<p>Otherwise, set to the last column in which any portion of any character in the line is displayed.</p> +</li> +</ol> +</li> +<li> +<p>Otherwise, if a character is displayed in the column that began the text region, set to the last column that displays any +portion of that character.</p> +</li> +<li> +<p>Otherwise, set to the last column in which any portion of any character in the line is displayed.</p> +</li> +</ol> +<h5><a name="tag_20_146_13_52" id="tag_20_146_13_52"></a>Delete to End-of-Line</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>buffer</i><b>]</b><tt> D +</tt></pre></dd> +</dl> +<p>Delete the text from the current position to the end of the current line; equivalent to the <i>vi</i> command:</p> +<pre> +<b>[</b><i>buffer</i><b>]</b><tt> d$ +</tt></pre> +<h5><a name="tag_20_146_13_53" id="tag_20_146_13_53"></a>Move to End-of-Word</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> e +</tt></pre></dd> +</dl> +<p>With the exception that words are used instead of bigwords as the delimiter, this command shall be equivalent to the <b>E</b> +command.</p> +<h5><a name="tag_20_146_13_54" id="tag_20_146_13_54"></a>Move to End-of-Bigword</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> E +</tt></pre></dd> +</dl> +<p>If the edit buffer is empty it shall be an error. If less than <i>count</i> bigwords end between the cursor and the end of the +edit buffer, <i>count</i> shall be adjusted to the number of bigword endings between the cursor and the end of the edit buffer.</p> +<p>If used as a motion command:</p> +<ol> +<li> +<p>The text region shall be from the last character of the <i>count</i>th next bigword up to and including the cursor +character.</p> +</li> +<li> +<p>Any text copied to a buffer shall be in character mode.</p> +</li> +</ol> +<p>If not used as a motion command:</p> +<p><i>Current line</i>: Set to the line containing the current column.</p> +<p><i>Current column</i>: Set to the last column upon which any part of the last character of the <i>count</i>th next bigword is +displayed.</p> +<h5><a name="tag_20_146_13_55" id="tag_20_146_13_55"></a>Find Character in Current Line (Forward)</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> f </tt><i>character</i><tt> +</tt></pre></dd> +</dl> +<p>It shall be an error if <i>count</i> occurrences of the character do not occur after the cursor in the line.</p> +<p>If used as a motion command:</p> +<ol> +<li> +<p>The text range shall be from the cursor character up to and including the <i>count</i>th occurrence of the specified character +after the cursor.</p> +</li> +<li> +<p>Any text copied to a buffer shall be in character mode.</p> +</li> +</ol> +<p>If not used as a motion command:</p> +<p><i>Current line</i>: Unchanged.</p> +<p><i>Current column</i>: Set to the last column in which any portion of the <i>count</i>th occurrence of the specified character +after the cursor appears in the line.</p> +<h5><a name="tag_20_146_13_56" id="tag_20_146_13_56"></a>Find Character in Current Line (Reverse)</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> F </tt><i>character</i><tt> +</tt></pre></dd> +</dl> +<p>It shall be an error if <i>count</i> occurrences of the character do not occur before the cursor in the line.</p> +<p>If used as a motion command:</p> +<ol> +<li> +<p>The text region shall be from the <i>count</i>th occurrence of the specified character before the cursor, up to, but not +including the cursor character.</p> +</li> +<li> +<p>Any text copied to a buffer shall be in character mode.</p> +</li> +</ol> +<p>If not used as a motion command:</p> +<p><i>Current line</i>: Unchanged.</p> +<p><i>Current column</i>: Set to the last column in which any portion of the <i>count</i>th occurrence of the specified character +before the cursor appears in the line.</p> +<h5><a name="tag_20_146_13_57" id="tag_20_146_13_57"></a>Move to Line</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> G +</tt></pre></dd> +</dl> +<p>If <i>count</i> is not specified, it shall default to the last line of the edit buffer. If <i>count</i> is greater than the last +line of the edit buffer, it shall be an error.</p> +<p>If used as a motion command:</p> +<ol> +<li> +<p>The text region shall be from the cursor line up to and including the specified line.</p> +</li> +<li> +<p>Any text copied to a buffer shall be in line mode.</p> +</li> +</ol> +<p>If not used as a motion command:</p> +<p><i>Current line</i>: Set to <i>count</i> if <i>count</i> is specified; otherwise, the last line.</p> +<p><i>Current column</i>: Set to non-<blank>.</p> +<h5><a name="tag_20_146_13_58" id="tag_20_146_13_58"></a>Move to Top of Screen</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> H +</tt></pre></dd> +</dl> +<p>If the beginning of the line <i>count</i> greater than the first line of which any portion appears on the display does not +exist, it shall be an error.</p> +<p>If used as a motion command:</p> +<ol> +<li> +<p>If in open mode, the text region shall be the current line.</p> +</li> +<li> +<p>Otherwise, the text region shall be from the starting line up to and including (the first line of the display + <i>count</i> +-1).</p> +</li> +<li> +<p>Any text copied to a buffer shall be in line mode.</p> +</li> +</ol> +<p>If not used as a motion command:</p> +<p>If in open mode, this command shall set the current column to non-<blank> and do nothing else.</p> +<p>Otherwise, it shall set the current line and current column as follows.</p> +<p><i>Current line</i>: Set to (the first line of the display + <i>count</i> -1).</p> +<p><i>Current column</i>: Set to non-<blank>.</p> +<h5><a name="tag_20_146_13_59" id="tag_20_146_13_59"></a>Insert Before Cursor</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> i +</tt></pre></dd> +</dl> +<p>Enter text input mode before the current cursor position. No characters already in the edit buffer shall be affected by this +command. A <i>count</i> shall cause the input text to be appended <i>count</i> -1 more times to the end of the input.</p> +<p><i>Current line/column</i>: As specified for the text input commands (see <a href="#tag_20_146_13_88">Input Mode Commands in +vi</a> ).</p> +<h5><a name="tag_20_146_13_60" id="tag_20_146_13_60"></a>Insert at Beginning of Line</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> I +</tt></pre></dd> +</dl> +<p>This command shall be equivalent to the <i>vi</i> command ^[<i>count</i>]<b>i</b>.</p> +<h5><a name="tag_20_146_13_61" id="tag_20_146_13_61"></a>Join</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> J +</tt></pre></dd> +</dl> +<p>If the current line is the last line in the edit buffer, it shall be an error.</p> +<p>This command shall be equivalent to the <a href="../utilities/ex.html"><i>ex</i></a> <b>join</b> command with no addresses, and +an <a href="../utilities/ex.html"><i>ex</i></a> command <i>count</i> value of 1 if <i>count</i> was not specified or if a +<i>count</i> of 1 was specified, and an <a href="../utilities/ex.html"><i>ex</i></a> command <i>count</i> value of <i>count</i> -1 +for any other value of <i>count</i>, except that the current line and column shall be set as follows.</p> +<p><i>Current line</i>: Unchanged.</p> +<p><i>Current column</i>: The last column in which any portion of the character following the last character in the initial line is +displayed, or the last non-<newline> in the line if no characters were appended.</p> +<h5><a name="tag_20_146_13_62" id="tag_20_146_13_62"></a>Move to Bottom of Screen</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> L +</tt></pre></dd> +</dl> +<p>If the beginning of the line <i>count</i> less than the last line of which any portion appears on the display does not exist, it +shall be an error.</p> +<p>If used as a motion command:</p> +<ol> +<li> +<p>If in open mode, the text region shall be the current line.</p> +</li> +<li> +<p>Otherwise, the text region shall include all lines from the starting cursor line to (the last line of the display -(<i>count</i> +-1)).</p> +</li> +<li> +<p>Any text copied to a buffer shall be in line mode.</p> +</li> +</ol> +<p>If not used as a motion command:</p> +<ol> +<li> +<p>If in open mode, this command shall set the current column to non-<blank> and do nothing else.</p> +</li> +<li> +<p>Otherwise, it shall set the current line and current column as follows.</p> +</li> +</ol> +<p><i>Current line</i>: Set to (the last line of the display -(<i>count</i> -1)).</p> +<p><i>Current column</i>: Set to non-<blank>.</p> +<h5><a name="tag_20_146_13_63" id="tag_20_146_13_63"></a>Mark Position</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>m </tt><i>letter</i><tt> +</tt></pre></dd> +</dl> +<p>This command shall be equivalent to the <a href="../utilities/ex.html"><i>ex</i></a> <b>mark</b> command with the specified +character as an argument.</p> +<h5><a name="tag_20_146_13_64" id="tag_20_146_13_64"></a>Move to Middle of Screen</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>M +</tt></pre></dd> +</dl> +<p>The middle line of the display shall be calculated as follows:</p> +<pre> +<tt>(the top line of the display) + (((number of lines displayed) +1) /2) -1 +</tt></pre> +<p>If used as a motion command:</p> +<ol> +<li> +<p>If in open mode, the text region shall be the current line.</p> +</li> +<li> +<p>Otherwise, the text region shall include all lines from the starting cursor line up to and including the middle line of the +display.</p> +</li> +<li> +<p>Any text copied to a buffer shall be in line mode.</p> +</li> +</ol> +<p>If not used as a motion command:</p> +<p>If in open mode, this command shall set the current column to non-<blank> and do nothing else.</p> +<p>Otherwise, it shall set the current line and current column as follows.</p> +<p><i>Current line</i>: Set to the middle line of the display.</p> +<p><i>Current column</i>: Set to non-<blank>.</p> +<h5><a name="tag_20_146_13_65" id="tag_20_146_13_65"></a>Repeat Regular Expression Find (Forward)</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>n +</tt></pre></dd> +</dl> +<p>If the remembered search direction was forward, the <b>n</b> command shall be equivalent to the <i>vi</i> <b>/</b> command with +no characters entered by the user. Otherwise, it shall be equivalent to the <i>vi</i> <b>?</b> command with no characters entered +by the user.</p> +<p>If the <b>n</b> command is used as a motion command for the <b>!</b> command, the editor shall not enter text input mode on the +last line on the screen, and shall behave as if the user entered a single <tt>'!'</tt> character as the text input.</p> +<h5><a name="tag_20_146_13_66" id="tag_20_146_13_66"></a>Repeat Regular Expression Find (Reverse)</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>N +</tt></pre></dd> +</dl> +<p>Scan for the next match of the last pattern given to <b>/</b> or <b>?</b>, but in the reverse direction; this is the reverse of +<b>n</b>.</p> +<p>If the remembered search direction was forward, the <b>N</b> command shall be equivalent to the <i>vi</i> <b>?</b> command with +no characters entered by the user. Otherwise, it shall be equivalent to the <i>vi</i> <b>/</b> command with no characters entered +by the user. If the <b>N</b> command is used as a motion command for the <b>!</b> command, the editor shall not enter text input +mode on the last line on the screen, and shall behave as if the user entered a single <b>!</b> character as the text input.</p> +<h5><a name="tag_20_146_13_67" id="tag_20_146_13_67"></a>Insert Empty Line Below</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>o +</tt></pre></dd> +</dl> +<p>Enter text input mode in a new line appended after the current line. A <i>count</i> shall cause the input text to be appended +<i>count</i> -1 more times to the end of the already added text, each time starting on a new, appended line.</p> +<p><i>Current line/column</i>: As specified for the text input commands (see <a href="#tag_20_146_13_88">Input Mode Commands in +vi</a> ).</p> +<h5><a name="tag_20_146_13_68" id="tag_20_146_13_68"></a>Insert Empty Line Above</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>O +</tt></pre></dd> +</dl> +<p>Enter text input mode in a new line inserted before the current line. A <i>count</i> shall cause the input text to be appended +<i>count</i> -1 more times to the end of the already added text, each time starting on a new, appended line.</p> +<p><i>Current line/column</i>: As specified for the text input commands (see <a href="#tag_20_146_13_88">Input Mode Commands in +vi</a> ).</p> +<h5><a name="tag_20_146_13_69" id="tag_20_146_13_69"></a>Put from Buffer Following</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>buffer</i><b>]</b><tt> p +</tt></pre></dd> +</dl> +<p>If no <i>buffer</i> is specified, the unnamed buffer shall be used.</p> +<p>If the buffer text is in line mode, the text shall be appended below the current line, and each line of the buffer shall become +a new line in the edit buffer. A <i>count</i> shall cause the buffer text to be appended <i>count</i> -1 more times to the end of +the already added text, each time starting on a new, appended line.</p> +<p>If the buffer text is in character mode, the text shall be appended into the current line after the cursor, and each line of the +buffer other than the first and last shall become a new line in the edit buffer. A <i>count</i> shall cause the buffer text to be +appended <i>count</i> -1 more times to the end of the already added text, each time starting after the last added character.</p> +<p><i>Current line</i>: If the buffer text is in line mode, set the line to line +1; otherwise, unchanged.</p> +<p><i>Current column</i>: If the buffer text is in line mode:</p> +<ol> +<li> +<p>If there is a non-<blank> in the first line of the buffer, set to the last column on which any portion of the first +non-<blank> in the line is displayed.</p> +</li> +<li> +<p>If there is no non-<blank> in the first line of the buffer, set to the last column on which any portion of the last +non-<newline> in the first line of the buffer is displayed.</p> +</li> +</ol> +<p>If the buffer text is in character mode:</p> +<ol> +<li> +<p>If the text in the buffer is from more than a single line, then set to the last column on which any portion of the first +character from the buffer is displayed.</p> +</li> +<li> +<p>Otherwise, if the buffer is the unnamed buffer, set to the last column on which any portion of the last character from the +buffer is displayed.</p> +</li> +<li> +<p>Otherwise, set to the first column on which any portion of the first character from the buffer is displayed.</p> +</li> +</ol> +<h5><a name="tag_20_146_13_70" id="tag_20_146_13_70"></a>Put from Buffer Before</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>buffer</i><b>]</b><tt> P +</tt></pre></dd> +</dl> +<p>If no <i>buffer</i> is specified, the unnamed buffer shall be used.</p> +<p>If the buffer text is in line mode, the text shall be inserted above the current line, and each line of the buffer shall become +a new line in the edit buffer. A <i>count</i> shall cause the buffer text to be appended <i>count</i> -1 more times to the end of +the already added text, each time starting on a new, appended line.</p> +<p>If the buffer text is in character mode, the text shall be inserted into the current line before the cursor, and each line of +the buffer other than the first and last shall become a new line in the edit buffer. A <i>count</i> shall cause the buffer text to +be appended <i>count</i> -1 more times to the end of the already added text, each time starting after the last added character.</p> +<p><i>Current line</i>: Unchanged.</p> +<p><i>Current column</i>: If the buffer text is in line mode:</p> +<ol> +<li> +<p>If there is a non-<blank> in the first line of the buffer, set to the last column on which any portion of that character +is displayed.</p> +</li> +<li> +<p>If there is no non-<blank> in the first line of the buffer, set to the last column on which any portion of the last +non-<newline> in the first line of the buffer is displayed.</p> +</li> +</ol> +<p>If the buffer text is in character mode:</p> +<ol> +<li> +<p>If the text in the buffer is from more than a single line, then set to the last column on which any portion of the first +character from the buffer is displayed.</p> +</li> +<li> +<p>Otherwise, if the buffer is the unnamed buffer, set to the last column on which any portion of the last character from the +buffer is displayed.</p> +</li> +<li> +<p>Otherwise, set to the first column on which any portion of the first character from the buffer is displayed.</p> +</li> +</ol> +<h5><a name="tag_20_146_13_71" id="tag_20_146_13_71"></a>Enter ex Mode</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>Q +</tt></pre></dd> +</dl> +<p>Leave visual or open mode and enter <a href="../utilities/ex.html"><i>ex</i></a> command mode.</p> +<p><i>Current line</i>: Unchanged.</p> +<p><i>Current column</i>: Unchanged.</p> +<h5><a name="tag_20_146_13_72" id="tag_20_146_13_72"></a>Replace Character</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> r </tt><i>character</i><tt> +</tt></pre></dd> +</dl> +<p>Replace the <i>count</i> characters at and after the cursor with the specified character. If there are less than <i>count</i> +non-<newline> characters at and after the cursor on the line, it shall be an error.</p> +<p>If character is <control>-V, any next character other than the <newline> shall be stripped of any special meaning +and used as a literal character.</p> +<p>If character is <ESC>, no replacement shall be made and the current line and current column shall be unchanged.</p> +<p>If character is <carriage-return> or <newline>, <i>count</i> new lines shall be appended to the current line. All +but the last of these lines shall be empty. <i>count</i> characters at and after the cursor shall be discarded, and any remaining +characters after the cursor in the current line shall be moved to the last of the new lines. If the <b>autoindent</b> edit option +is set, they shall be preceded by the same number of <b>autoindent</b> characters found on the line from which the command was +executed.</p> +<p><i>Current line</i>: Unchanged unless the replacement character is a <carriage-return> or <newline>, in which case +it shall be set to line + <i>count</i>.</p> +<p><i>Current column</i>: Set to the last column position on which a portion of the last replaced character is displayed, or if the +replacement character caused new lines to be created, set to non-<blank>.</p> +<h5><a name="tag_20_146_13_73" id="tag_20_146_13_73"></a>Replace Characters</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>R +</tt></pre></dd> +</dl> +<p>Enter text input mode at the current cursor position possibly replacing text on the current line. A <i>count</i> shall cause the +input text to be appended <i>count</i> -1 more times to the end of the input.</p> +<p><i>Current line/column</i>: As specified for the text input commands (see <a href="#tag_20_146_13_88">Input Mode Commands in +vi</a> ).</p> +<h5><a name="tag_20_146_13_74" id="tag_20_146_13_74"></a>Substitute Character</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>buffer</i><b>][</b><i>count</i><b>]</b><tt> s +</tt></pre></dd> +</dl> +<p>This command shall be equivalent to the <i>vi</i> command:</p> +<pre> +<b>[</b><i>buffer</i><b>][</b><i>count</i><b>]</b><tt> c<space> +</tt></pre> +<h5><a name="tag_20_146_13_75" id="tag_20_146_13_75"></a>Substitute Lines</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>buffer</i><b>][</b><i>count</i><b>]</b><tt> S +</tt></pre></dd> +</dl> +<p>This command shall be equivalent to the <i>vi</i> command:</p> +<pre> +<b>[</b><i>buffer</i><b>][</b><i>count</i><b>]</b><tt> c_ +</tt></pre> +<h5><a name="tag_20_146_13_76" id="tag_20_146_13_76"></a>Move Cursor to Before Character (Forward)</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> t </tt><i>character</i><tt> +</tt></pre></dd> +</dl> +<p>It shall be an error if <i>count</i> occurrences of the character do not occur after the cursor in the line.</p> +<p>If used as a motion command:</p> +<ol> +<li> +<p>The text region shall be from the cursor up to but not including the <i>count</i>th occurrence of the specified character after +the cursor.</p> +</li> +<li> +<p>Any text copied to a buffer shall be in character mode.</p> +</li> +</ol> +<p>If not used as a motion command:</p> +<p><i>Current line</i>: Unchanged.</p> +<p><i>Current column</i>: Set to the last column in which any portion of the character before the <i>count</i>th occurrence of the +specified character after the cursor appears in the line.</p> +<h5><a name="tag_20_146_13_77" id="tag_20_146_13_77"></a>Move Cursor to After Character (Reverse)</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> T </tt><i>character</i><tt> +</tt></pre></dd> +</dl> +<p>It shall be an error if <i>count</i> occurrences of the character do not occur before the cursor in the line.</p> +<p>If used as a motion command:</p> +<ol> +<li> +<p>If the character before the cursor is the specified character, it shall be an error.</p> +</li> +<li> +<p>The text region shall be from the character before the cursor up to but not including the <i>count</i>th occurrence of the +specified character before the cursor.</p> +</li> +<li> +<p>Any text copied to a buffer shall be in character mode.</p> +</li> +</ol> +<p>If not used as a motion command:</p> +<p><i>Current line</i>: Unchanged.</p> +<p><i>Current column</i>: Set to the last column in which any portion of the character after the <i>count</i>th occurrence of the +specified character before the cursor appears in the line.</p> +<h5><a name="tag_20_146_13_78" id="tag_20_146_13_78"></a>Undo</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>u +</tt></pre></dd> +</dl> +<p>This command shall be equivalent to the <a href="../utilities/ex.html"><i>ex</i></a> <b>undo</b> command except that the current +line and current column shall be set as follows:</p> +<p><i>Current line</i>: Set to the first line added or changed if any; otherwise, move to the line preceding any deleted text if +one exists; otherwise, move to line 1.</p> +<p><i>Current column</i>: If undoing an <a href="../utilities/ex.html"><i>ex</i></a> command, set to the first +non-<blank>.</p> +<p>Otherwise, if undoing a text input command:</p> +<ol> +<li> +<p>If the command was a <b>C</b>, <b>c</b>, <b>O</b>, <b>o</b>, <b>R</b>, <b>S</b>, or <b>s</b> command, the current column shall +be set to the value it held when the text input command was entered.</p> +</li> +<li> +<p>Otherwise, set to the last column in which any portion of the first character after the deleted text is displayed, or, if no +non-<newline> characters follow the text deleted from this line, set to the last column in which any portion of the last +non-<newline> in the line is displayed, or 1 if the line is empty.</p> +</li> +</ol> +<p>Otherwise, if a single line was modified (that is, not added or deleted) by the <b>u</b> command:</p> +<ol> +<li> +<p>If text was added or changed, set to the last column in which any portion of the first character added or changed is +displayed.</p> +</li> +<li> +<p>If text was deleted, set to the last column in which any portion of the first character after the deleted text is displayed, or, +if no non-<newline> characters follow the deleted text, set to the last column in which any portion of the last +non-<newline> in the line is displayed, or 1 if the line is empty.</p> +</li> +</ol> +<p>Otherwise, set to non-<blank>.</p> +<h5><a name="tag_20_146_13_79" id="tag_20_146_13_79"></a>Undo Current Line</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>U +</tt></pre></dd> +</dl> +<p>Restore the current line to its state immediately before the most recent time that it became the current line.</p> +<p><i>Current line</i>: Unchanged.</p> +<p><i>Current column</i>: Set to the first column in the line in which any portion of the first character in the line is +displayed.</p> +<h5><a name="tag_20_146_13_80" id="tag_20_146_13_80"></a>Move to Beginning of Word</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> w +</tt></pre></dd> +</dl> +<p>With the exception that words are used as the delimiter instead of bigwords, this command shall be equivalent to the <b>W</b> +command.</p> +<h5><a name="tag_20_146_13_81" id="tag_20_146_13_81"></a>Move to Beginning of Bigword</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> W +</tt></pre></dd> +</dl> +<p>If the edit buffer is empty, it shall be an error. If there are less than <i>count</i> bigwords between the cursor and the end +of the edit buffer, <i>count</i> shall be adjusted to move the cursor to the last bigword in the edit buffer.</p> +<p>If used as a motion command:</p> +<ol> +<li> +<p>If the associated command is <b>c</b>, <i>count</i> is 1, and the cursor is on a <blank>, the region of text shall be the +current character and no further action shall be taken.</p> +</li> +<li> +<p>If there are less than <i>count</i> bigwords between the cursor and the end of the edit buffer, then the command shall succeed, +and the region of text shall include the last character of the edit buffer.</p> +</li> +<li> +<p>If there are <blank> characters or an end-of-line that precede the <i>count</i>th bigword, and the associated command is +<b>c</b>, the region of text shall be up to and including the last character before the preceding <blank> characters or +end-of-line.</p> +</li> +<li> +<p>If there are <blank> characters or an end-of-line that precede the bigword, and the associated command is <b>d</b> or +<b>y</b>, the region of text shall be up to and including the last <blank> before the start of the bigword or +end-of-line.</p> +</li> +<li> +<p>Any text copied to a buffer shall be in character mode.</p> +</li> +</ol> +<p>If not used as a motion command:</p> +<ol> +<li> +<p>If the cursor is on the last character of the edit buffer, it shall be an error.</p> +</li> +</ol> +<p><i>Current line</i>: Set to the line containing the current column.</p> +<p><i>Current column</i>: Set to the last column in which any part of the first character of the <i>count</i>th next bigword is +displayed.</p> +<h5><a name="tag_20_146_13_82" id="tag_20_146_13_82"></a>Delete Character at Cursor</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>buffer</i><b>][</b><i>count</i><b>]</b><tt> x +</tt></pre></dd> +</dl> +<p>Delete the <i>count</i> characters at and after the current character into <i>buffer</i>, if specified, and into the unnamed +buffer.</p> +<p>If the line is empty, it shall be an error. If there are less than <i>count</i> non-<newline> characters at and after the +cursor on the current line, <i>count</i> shall be adjusted to the number of non-<newline> characters at and after the +cursor.</p> +<p><i>Current line</i>: Unchanged.</p> +<p><i>Current column</i>: If the line is empty, set to column position 1. Otherwise, if there were <i>count</i> or less +non-<newline> characters at and after the cursor on the current line, set to the last column that displays any part of the +last non-<newline> of the line. Otherwise, unchanged.</p> +<h5><a name="tag_20_146_13_83" id="tag_20_146_13_83"></a>Delete Character Before Cursor</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>buffer</i><b>][</b><i>count</i><b>]</b><tt> X +</tt></pre></dd> +</dl> +<p>Delete the <i>count</i> characters before the current character into <i>buffer</i>, if specified, and into the unnamed +buffer.</p> +<p>If there are no characters before the current character on the current line, it shall be an error. If there are less than +<i>count</i> previous characters on the current line, <i>count</i> shall be adjusted to the number of previous characters on the +line.</p> +<p><i>Current line</i>: Unchanged.</p> +<p><i>Current column</i>: Set to (current column - the width of the deleted characters).</p> +<h5><a name="tag_20_146_13_84" id="tag_20_146_13_84"></a>Yank</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>buffer</i><b>][</b><i>count</i><b>]</b><tt> y </tt><i>motion</i><tt> +</tt></pre></dd> +</dl> +<p>Copy (yank) the region of text into <i>buffer</i>, if specified, and into the unnamed buffer.</p> +<p>If the motion command is the <b>y</b> command repeated:</p> +<ol> +<li> +<p>The buffer shall be in line mode.</p> +</li> +<li> +<p>If there are less than <i>count</i> -1 lines after the current line in the edit buffer, it shall be an error.</p> +</li> +<li> +<p>The text region shall be from the current line up to and including the next <i>count</i> -1 lines.</p> +</li> +</ol> +<p>Otherwise, the buffer text mode and text region shall be as specified by the motion command.</p> +<p><i>Current line</i>: If the motion was from the current cursor position toward the end of the edit buffer, unchanged. Otherwise, +set to the first line in the edit buffer that is part of the text region specified by the motion command.</p> +<p><i>Current column</i>:</p> +<ol> +<li> +<p>If the motion was from the current cursor position toward the end of the edit buffer, unchanged.</p> +</li> +<li> +<p>Otherwise, if the current line is empty, set to column position 1.</p> +</li> +<li> +<p>Otherwise, set to the last column that displays any part of the first character in the file that is part of the text region +specified by the motion command.</p> +</li> +</ol> +<h5><a name="tag_20_146_13_85" id="tag_20_146_13_85"></a>Yank Current Line</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>buffer</i><b>][</b><i>count</i><b>]</b><tt> Y +</tt></pre></dd> +</dl> +<p>This command shall be equivalent to the <i>vi</i> command:</p> +<pre> +<b>[</b><i>buffer</i><b>][</b><i>count</i><b>]</b><tt> y_ +</tt></pre> +<h5><a name="tag_20_146_13_86" id="tag_20_146_13_86"></a>Redraw Window</h5> +<p>If in open mode, the <b>z</b> command shall have the Synopsis:</p> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>count</i><b>]</b><tt> z +</tt></pre></dd> +</dl> +<p>If <i>count</i> is not specified, it shall default to the <b>window</b> edit option -1. The <b>z</b> command shall be equivalent +to the <a href="../utilities/ex.html"><i>ex</i></a> <b>z</b> command, with a type character of <b>=</b> and a <i>count</i> of +<i>count</i> -2, except that the current line and current column shall be set as follows, and the <b>window</b> edit option shall +not be affected. If the calculation for the <i>count</i> argument would result in a negative number, the <i>count</i> argument to +the <a href="../utilities/ex.html"><i>ex</i></a> <b>z</b> command shall be zero. A blank line shall be written after the last line +is written.</p> +<p><i>Current line</i>: Unchanged.</p> +<p><i>Current column</i>: Unchanged.</p> +<p>If not in open mode, the <b>z</b> command shall have the following Synopsis:</p> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<b>[</b><i>line</i><b>]</b><tt> z </tt><b>[</b><i>count</i><b>] </b><i>character</i><tt> +</tt></pre></dd> +</dl> +<p>If <i>line</i> is not specified, it shall default to the current line. If <i>line</i> is specified, but is greater than the +number of lines in the edit buffer, it shall default to the number of lines in the edit buffer.</p> +<p>If <i>count</i> is specified, the value of the <b>window</b> edit option shall be set to <i>count</i> (as described in the +<a href="../utilities/ex.html"><i>ex</i></a> <b>window</b> command), and the screen shall be redrawn.</p> +<p><i>line</i> shall be placed as specified by the following characters:</p> +<dl compact> +<dd></dd> +<dt><newline>, <carriage-return></dt> +<dd><br> +Place the beginning of the line on the first line of the display.</dd> +<dt><tt>.</tt></dt> +<dd>Place the beginning of the line in the center of the display. The middle line of the display shall be calculated as described +for the <b>M</b> command.</dd> +<dt><tt>-</tt></dt> +<dd>Place an unspecified portion of the line on the last line of the display.</dd> +<dt><tt>+</tt></dt> +<dd>If <i>line</i> was specified, equivalent to the <newline> case. If <i>line</i> was not specified, display a screen where +the first line of the display shall be (current last line) +1. If there are no lines after the last line in the display, it shall +be an error.</dd> +<dt><tt>^</tt></dt> +<dd>If <i>line</i> was specified, display a screen where the last line of the display shall contain an unspecified portion of the +first line of a display that had an unspecified portion of the specified line on the last line of the display. If this calculation +results in a line before the beginning of the edit buffer, display the first screen of the edit buffer. +<p>Otherwise, display a screen where the last line of the display shall contain an unspecified portion of (current first line -1). +If this calculation results in a line before the beginning of the edit buffer, it shall be an error.</p> +</dd> +</dl> +<br> +<p><i>Current line</i>: If <i>line</i> and the <tt>'^'</tt> character were specified:</p> +<ol> +<li> +<p>If the first screen was displayed as a result of the command attempting to display lines before the beginning of the edit +buffer: if the first screen was already displayed, unchanged; otherwise, set to (current first line -1).</p> +</li> +<li> +<p>Otherwise, set to the last line of the display.</p> +</li> +</ol> +<p>If <i>line</i> and the <tt>'+'</tt> character were specified, set to the first line of the display.</p> +<p>Otherwise, if <i>line</i> was specified, set to <i>line</i>.</p> +<p>Otherwise, unchanged.</p> +<p><i>Current column</i>: Set to non-<blank>.</p> +<h5><a name="tag_20_146_13_87" id="tag_20_146_13_87"></a>Exit</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>ZZ +</tt></pre></dd> +</dl> +<p>This command shall be equivalent to the <a href="../utilities/ex.html"><i>ex</i></a> <b>xit</b> command with no addresses, +trailing <b>!</b>, or filename (see the <a href="../utilities/ex.html"><i>ex</i></a> <b>xit</b> command).</p> +<h5><a name="tag_20_146_13_88" id="tag_20_146_13_88"></a>Input Mode Commands in vi</h5> +<p>In text input mode, the current line shall consist of zero or more of the following categories, plus the terminating +<newline>:</p> +<ol> +<li> +<p>Characters preceding the text input entry point</p> +<p>Characters in this category shall not be modified during text input mode.</p> +</li> +<li> +<p><b>autoindent</b> characters</p> +<p><b>autoindent</b> characters shall be automatically inserted into each line that is created in text input mode, either as a +result of entering a <newline> or <carriage-return> while in text input mode, or as an effect of the command itself; +for example, <b>O</b> or <b>o</b> (see the <a href="../utilities/ex.html"><i>ex</i></a> <b>autoindent</b> command), as if entered +by the user.</p> +<p>It shall be possible to erase <b>autoindent</b> characters with the <control>-D command; it is unspecified whether they +can be erased by <control>-H, <control>-U, and <control>-W characters. Erasing any <b>autoindent</b> character +turns the glyph into erase-columns and deletes the character from the edit buffer, but does not change its representation on the +screen.</p> +</li> +<li> +<p>Text input characters</p> +<p>Text input characters are the characters entered by the user. Erasing any text input character turns the glyph into +erase-columns and deletes the character from the edit buffer, but does not change its representation on the screen.</p> +<p>Each text input character entered by the user (that does not have a special meaning) shall be treated as follows:</p> +<ol type="a"> +<li> +<p>The text input character shall be appended to the last character in the edit buffer from the first, second, or third +categories.</p> +</li> +<li> +<p>If there are no erase-columns on the screen, the text input command was the <b>R</b> command, and characters in the fifth +category from the original line follow the cursor, the next such character shall be deleted from the edit buffer. If the +<b>slowopen</b> edit option is not set, the corresponding glyph on the screen shall become erase-columns.</p> +</li> +<li> +<p>If there are erase-columns on the screen, as many columns as they occupy, or as are necessary, shall be overwritten to display +the text input character. (If only part of a multi-column glyph is overwritten, the remainder shall be left on the screen, and +continue to be treated as erase-columns; it is unspecified whether the remainder of the glyph is modified in any way.)</p> +</li> +<li> +<p>If additional display line columns are needed to display the text input character:</p> +<ol type="i"> +<li> +<p>If the <b>slowopen</b> edit option is set, the text input characters shall be displayed on subsequent display line columns, +overwriting any characters displayed in those columns.</p> +</li> +<li> +<p>Otherwise, any characters currently displayed on or after the column on the display line where the text input character is to be +displayed shall be pushed ahead the number of display line columns necessary to display the rest of the text input character.</p> +</li> +</ol> +</li> +</ol> +</li> +<li> +<p>Erase-columns</p> +<p>Erase-columns are not logically part of the edit buffer, appearing only on the screen, and may be overwritten on the screen by +subsequent text input characters. When text input mode ends, all erase-columns shall no longer appear on the screen.</p> +<p>Erase-columns are initially the region of text specified by the <b>c</b> command (see <a href="#tag_20_146_13_49">Change</a> ); +however, erasing <b>autoindent</b> or text input characters causes the glyphs of the erased characters to be treated as +erase-columns.</p> +</li> +<li> +<p>Characters following the text region for the <b>c</b> command, or the text input entry point for all other commands</p> +<p>Characters in this category shall not be modified during text input mode, except as specified in category 3.b. for the <b>R</b> +text input command, or as <blank> characters deleted when a <newline> or <carriage-return> is entered.</p> +</li> +</ol> +<p>It is unspecified whether it is an error to attempt to erase past the beginning of a line that was created by the entry of a +<newline> or <carriage-return> during text input mode. If it is not an error, the editor shall behave as if the erasing +character was entered immediately after the last text input character entered on the previous line, and all of the +non-<newline> characters on the current line shall be treated as erase-columns.</p> +<p>When text input mode is entered, or after a text input mode character is entered (except as specified for the special characters +below), the cursor shall be positioned as follows:</p> +<ol> +<li> +<p>On the first column that displays any part of the first erase-column, if one exists</p> +</li> +<li> +<p>Otherwise, if the <b>slowopen</b> edit option is set, on the first display line column after the last character in the first, +second, or third categories, if one exists</p> +</li> +<li> +<p>Otherwise, the first column that displays any part of the first character in the fifth category, if one exists</p> +</li> +<li> +<p>Otherwise, the display line column after the last character in the first, second, or third categories, if one exists</p> +</li> +<li> +<p>Otherwise, on column position 1</p> +</li> +</ol> +<p>The characters that are updated on the screen during text input mode are unspecified, other than that the last text input +character shall always be updated, and, if the <b>slowopen</b> edit option is not set, the current cursor character shall always be +updated.</p> +<p>The following specifications are for command characters entered during text input mode.</p> +<h5><a name="tag_20_146_13_89" id="tag_20_146_13_89"></a>NUL</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt>NUL +</tt></pre></dd> +</dl> +<p>If the first character of the text input is a NUL, the most recently input text shall be input as if entered by the user, and +then text input mode shall be exited. The text shall be input literally; that is, characters are neither macro or abbreviation +expanded, nor are any characters interpreted in any special manner. It is unspecified whether implementations shall support more +than 256 bytes of remembered input text.</p> +<h5><a name="tag_20_146_13_90" id="tag_20_146_13_90"></a><control>-D</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt><control>-D +</tt></pre></dd> +</dl> +<p>The <control>-D character shall have no special meaning when in text input mode for a line-oriented command (see <a href= +"#tag_20_146_13_02">Command Descriptions in vi</a> ).</p> +<p>This command need not be supported on block-mode terminals.</p> +<p>If the cursor does not follow an <b>autoindent</b> character, or an <b>autoindent</b> character and a <tt>'0'</tt> or +<tt>'^'</tt> character:</p> +<ol> +<li> +<p>If the cursor is in column position 1, the <control>-D character shall be discarded and no further action taken.</p> +</li> +<li> +<p>Otherwise, the <control>-D character shall have no special meaning.</p> +</li> +</ol> +<p>If the last input character was a <tt>'0'</tt>, the cursor shall be moved to column position 1.</p> +<p>Otherwise, if the last input character was a <tt>'^'</tt>, the cursor shall be moved to column position 1. In addition, the +<b>autoindent</b> level for the next input line shall be derived from the same line from which the <b>autoindent</b> level for the +current input line was derived.</p> +<p>Otherwise, the cursor shall be moved back to the column after the previous shiftwidth (see the <a href= +"../utilities/ex.html"><i>ex</i></a> <b>shiftwidth</b> command) boundary.</p> +<p>All of the glyphs on columns between the starting cursor position and (inclusively) the ending cursor position shall become +erase-columns as described in <a href="#tag_20_146_13_88">Input Mode Commands in vi</a> .</p> +<p><i>Current line</i>: Unchanged.</p> +<p><i>Current column</i>: Set to 1 if the <control>-D was preceded by a <tt>'^'</tt> or <tt>'0'</tt>; otherwise, set to +(column -1) -((column -2) % <b>shiftwidth</b>).</p> +<h5><a name="tag_20_146_13_91" id="tag_20_146_13_91"></a><control>-H</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt><control>-H +</tt></pre></dd> +</dl> +<p>If in text input mode for a line-oriented command, and there are no characters to erase, text input mode shall be terminated, no +further action shall be done for this command, and the current line and column shall be unchanged.</p> +<p>If there are characters other than <b>autoindent</b> characters that have been input on the current line before the cursor, the +cursor shall move back one character.</p> +<p>Otherwise, if there are <b>autoindent</b> characters on the current line before the cursor, it is implementation-defined whether +the <control>-H command is an error or if the cursor moves back one <b>autoindent</b> character.</p> +<p>Otherwise, if the cursor is in column position 1 and there are previous lines that have been input, it is implementation-defined +whether the <control>-H command is an error or if it is equivalent to entering <control>-H after the last input +character on the previous input line.</p> +<p>Otherwise, it shall be an error.</p> +<p>All of the glyphs on columns between the starting cursor position and (inclusively) the ending cursor position shall become +erase-columns as described in <a href="#tag_20_146_13_88">Input Mode Commands in vi</a> .</p> +<p>The current erase character (see <a href="../utilities/stty.html"><i>stty</i></a>) shall cause an equivalent action to the +<control>-H command, unless the previously inserted character was a <backslash>, in which case it shall be as if the +literal current erase character had been inserted instead of the <backslash>.</p> +<p><i>Current line</i>: Unchanged, unless previously input lines are erased, in which case it shall be set to line -1.</p> +<p><i>Current column</i>: Set to the first column that displays any portion of the character backed up over.</p> +<h5><a name="tag_20_146_13_92" id="tag_20_146_13_92"></a><newline></h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt><newline> +<br> +<carriage-return> +<br> +<control>-J +<br> +<control>-M +</tt></pre></dd> +</dl> +<p>If input was part of a line-oriented command, text input mode shall be terminated and the command shall continue execution with +the input provided.</p> +<p>Otherwise, terminate the current line. If there are no characters other than <b>autoindent</b> characters on the line, all +characters on the line shall be discarded. Otherwise, it is unspecified whether the <b>autoindent</b> characters in the line are +modified by entering these characters.</p> +<p>Continue text input mode on a new line appended after the current line. If the <b>slowopen</b> edit option is set, the lines on +the screen below the current line shall not be pushed down, but the first of them shall be cleared and shall appear to be +overwritten. Otherwise, the lines of the screen below the current line shall be pushed down.</p> +<p>If the <b>autoindent</b> edit option is set, an appropriate number of <b>autoindent</b> characters shall be added as a prefix to +the line as described by the <a href="../utilities/ex.html"><i>ex</i></a> <b>autoindent</b> edit option.</p> +<p>All columns after the cursor that are erase-columns (as described in <a href="#tag_20_146_13_88">Input Mode Commands in vi</a> ) +shall be discarded.</p> +<p>If the <b>autoindent</b> edit option is set, all <blank> characters immediately following the cursor shall be +discarded.</p> +<p>All remaining characters after the cursor shall be transferred to the new line, positioned after any <b>autoindent</b> +characters.</p> +<p><i>Current line</i>: Set to current line +1.</p> +<p><i>Current column</i>: Set to the first column that displays any portion of the first character after the <b>autoindent</b> +characters on the new line, if any, or the first column position after the last <b>autoindent</b> character, if any, or column +position 1.</p> +<h5><a name="tag_20_146_13_93" id="tag_20_146_13_93"></a><control>-T</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt><control>-T +</tt></pre></dd> +</dl> +<p>The <control>-T character shall have no special meaning when in text input mode for a line-oriented command (see <a href= +"#tag_20_146_13_02">Command Descriptions in vi</a> ).</p> +<p>This command need not be supported on block-mode terminals.</p> +<p>Behave as if the user entered the minimum number of <blank> characters necessary to move the cursor forward to the column +position after the next <b>shiftwidth</b> (see the <a href="../utilities/ex.html"><i>ex</i></a> <b>shiftwidth</b> command) +boundary.</p> +<p><i>Current line</i>: Unchanged.</p> +<p><i>Current column</i>: Set to <i>column</i> + <b>shiftwidth</b> - ((column -1) % <b>shiftwidth</b>).</p> +<h5><a name="tag_20_146_13_94" id="tag_20_146_13_94"></a><control>-U</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt><control>-U +</tt></pre></dd> +</dl> +<p>If there are characters other than <b>autoindent</b> characters that have been input on the current line before the cursor, the +cursor shall move to the first character input after the <b>autoindent</b> characters.</p> +<p>Otherwise, if there are <b>autoindent</b> characters on the current line before the cursor, it is implementation-defined whether +the <control>-U command is an error or if the cursor moves to the first column position on the line.</p> +<p>Otherwise, if the cursor is in column position 1 and there are previous lines that have been input, it is implementation-defined +whether the <control>-U command is an error or if it is equivalent to entering <control>-U after the last input +character on the previous input line.</p> +<p>Otherwise, it shall be an error.</p> +<p>All of the glyphs on columns between the starting cursor position and (inclusively) the ending cursor position shall become +erase-columns as described in <a href="#tag_20_146_13_88">Input Mode Commands in vi</a> .</p> +<p>The current <i>kill</i> character (see <a href="../utilities/stty.html"><i>stty</i></a>) shall cause an equivalent action to the +<control>-U command, unless the previously inserted character was a <backslash>, in which case it shall be as if the +literal current <i>kill</i> character had been inserted instead of the <backslash>.</p> +<p><i>Current line</i>: Unchanged, unless previously input lines are erased, in which case it shall be set to line -1.</p> +<p><i>Current column</i>: Set to the first column that displays any portion of the last character backed up over.</p> +<h5><a name="tag_20_146_13_95" id="tag_20_146_13_95"></a><control>-V</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt><control>-V +<br> +<control>-Q +</tt></pre></dd> +</dl> +<p>Allow the entry of any subsequent character, other than <control>-J or the <newline>, as a literal character, +removing any special meaning that it may have to the editor in text input mode. If a <control>-V or <control>-Q is +entered before a <control>-J or <newline>, the <control>-V or <control>-Q character shall be discarded, and +the <control>-J or <newline> shall behave as described in the <newline> command character during input mode.</p> +<p>For purposes of the display only, the editor shall behave as if a <tt>'^'</tt> character was entered, and the cursor shall be +positioned as if overwriting the <tt>'^'</tt> character. When a subsequent character is entered, the editor shall behave as if that +character was entered instead of the original <control>-V or <control>-Q character.</p> +<p><i>Current line</i>: Unchanged.</p> +<p><i>Current column</i>: Unchanged.</p> +<h5><a name="tag_20_146_13_96" id="tag_20_146_13_96"></a><control>-W</h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt><control>-W +</tt></pre></dd> +</dl> +<p>If there are characters other than <b>autoindent</b> characters that have been input on the current line before the cursor, the +cursor shall move back over the last word preceding the cursor (including any <blank> characters between the end of the last +word and the current cursor); the cursor shall not move to before the first character after the end of any <b>autoindent</b> +characters.</p> +<p>Otherwise, if there are <b>autoindent</b> characters on the current line before the cursor, it is implementation-defined whether +the <control>-W command is an error or if the cursor moves to the first column position on the line.</p> +<p>Otherwise, if the cursor is in column position 1 and there are previous lines that have been input, it is implementation-defined +whether the <control>-W command is an error or if it is equivalent to entering <control>-W after the last input +character on the previous input line.</p> +<p>Otherwise, it shall be an error.</p> +<p>All of the glyphs on columns between the starting cursor position and (inclusively) the ending cursor position shall become +erase-columns as described in <a href="#tag_20_146_13_88">Input Mode Commands in vi</a> .</p> +<p><i>Current line</i>: Unchanged, unless previously input lines are erased, in which case it shall be set to line -1.</p> +<p><i>Current column</i>: Set to the first column that displays any portion of the last character backed up over.</p> +<h5><a name="tag_20_146_13_97" id="tag_20_146_13_97"></a><ESC></h5> +<dl compact> +<dd></dd> +<dt><i>Synopsis</i>:</dt> +<dd> +<pre> +<tt><ESC> +</tt></pre></dd> +</dl> +<p>If input was part of a line-oriented command:</p> +<ol> +<li> +<p>If <i>interrupt</i> was entered, text input mode shall be terminated and the editor shall return to command mode. The terminal +shall be alerted.</p> +</li> +<li> +<p>If <ESC> was entered, text input mode shall be terminated and the command shall continue execution with the input +provided.</p> +</li> +</ol> +<p>Otherwise, terminate text input mode and return to command mode.</p> +<p>Any <b>autoindent</b> characters entered on newly created lines that have no other non-<newline> characters shall be +deleted.</p> +<p>Any leading <b>autoindent</b> and <blank> characters on newly created lines shall be rewritten to be the minimum number of +<blank> characters possible.</p> +<p>The screen shall be redisplayed as necessary to match the contents of the edit buffer.</p> +<p><i>Current line</i>: Unchanged.<br></p> +<p><i>Current column</i>:</p> +<ol> +<li> +<p>If there are text input characters on the current line, the column shall be set to the last column where any portion of the last +text input character is displayed.</p> +</li> +<li> +<p>Otherwise, if a character is displayed in the current column, unchanged.</p> +</li> +<li> +<p>Otherwise, set to column position 1.</p> +</li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_146_14" id="tag_20_146_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_146_15" id="tag_20_146_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>When an unrecoverable error is encountered it shall be equivalent to a SIGHUP asynchronous event.</p> +<p>Otherwise, when an error is encountered, the editor shall behave as specified in <a href="#tag_20_146_13_02">Command +Descriptions in vi</a> .</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_146_16" id="tag_20_146_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_146_17" id="tag_20_146_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_146_18" id="tag_20_146_18"></a>RATIONALE</h4> +<blockquote> +<p>See the RATIONALE for <a href="../utilities/ex.html#"><i>ex</i></a> for more information on <i>vi</i>. Major portions of the +<i>vi</i> utility specification point to <a href="../utilities/ex.html"><i>ex</i></a> to avoid inadvertent divergence. While +<a href="../utilities/ex.html"><i>ex</i></a> and <i>vi</i> have historically been implemented as a single utility, this is not +required by POSIX.1-2024.</p> +<p>It is recognized that portions of <i>vi</i> would be difficult, if not impossible, to implement satisfactorily on a block-mode +terminal, or a terminal without any form of cursor addressing, thus it is not a mandatory requirement that such features should +work on all terminals. It is the intention, however, that a <i>vi</i> implementation should provide the full set of capabilities on +all terminals capable of supporting them.</p> +<p>Historically, <i>vi</i> exited immediately if the standard input was not a terminal. POSIX.1-2024 permits, but does not require, +this behavior. An end-of-file condition is not equivalent to an end-of-file character. A common end-of-file character, +<control>-D, is historically a <i>vi</i> command.</p> +<p>The text in the STDOUT section reflects the usage of the verb <i>display</i> in this section; some implementations of <i>vi</i> +use standard output to write to the terminal, but POSIX.1-2024 does not require that to be the case.</p> +<p>Historically, implementations reverted to open mode if the terminal was incapable of supporting full visual mode. POSIX.1-2024 +requires this behavior. Historically, the open mode of <i>vi</i> behaved roughly equivalently to the visual mode, with the +exception that only a single line from the edit buffer (one "buffer line") was kept current at any time. This line was normally +displayed on the next-to-last line of a terminal with cursor addressing (and the last line performed its normal visual functions +for line-oriented commands and messages). In addition, some few commands behaved differently in open mode than in visual mode. +POSIX.1-2024 requires conformance to historical practice.</p> +<p>Historically, <a href="../utilities/ex.html"><i>ex</i></a> and <i>vi</i> implementations have expected text to proceed in the +usual European/Latin order of left to right, top to bottom. There is no requirement in POSIX.1-2024 that this be the case. The +specification was deliberately written using words like "before", "after", "first", and "last" in order to permit +implementations to support the natural text order of the language.</p> +<p>Historically, lines past the end of the edit buffer were marked with single <tilde> (<tt>'~'</tt>) characters; that is, if +the one-based display was 20 lines in length, and the last line of the file was on line one, then lines 2-20 would contain only a +single <tt>'~'</tt> character.</p> +<p>Historically, the <i>vi</i> editor attempted to display only complete lines at the bottom of the screen (it did display partial +lines at the top of the screen). If a line was too long to fit in its entirety at the bottom of the screen, the screen lines where +the line would have been displayed were displayed as single <tt>'@'</tt> characters, instead of displaying part of the line. +POSIX.1-2024 permits, but does not require, this behavior. Implementations are encouraged to attempt always to display a complete +line at the bottom of the screen when doing scrolling or screen positioning by buffer lines.</p> +<p>Historically, lines marked with <tt>'@'</tt> were also used to minimize output to dumb terminals over slow lines; that is, +changes local to the cursor were updated, but changes to lines on the screen that were not close to the cursor were simply marked +with an <tt>'@'</tt> sign instead of being updated to match the current text. POSIX.1-2024 permits, but does not require this +feature because it is used ever less frequently as terminals become smarter and connections are faster.</p> +<h5><a name="tag_20_146_18_01" id="tag_20_146_18_01"></a>Initialization in ex and vi</h5> +<p>Historically, <i>vi</i> always had a line in the edit buffer, even if the edit buffer was "empty". For example:</p> +<ol> +<li> +<p>The <a href="../utilities/ex.html"><i>ex</i></a> command <b>=</b> executed from visual mode wrote "1" when the buffer was +empty.</p> +</li> +<li> +<p>Writes from visual mode of an empty edit buffer wrote files of a single character (a <newline>), while writes from +<a href="../utilities/ex.html"><i>ex</i></a> mode of an empty edit buffer wrote empty files.</p> +</li> +<li> +<p>Put and read commands into an empty edit buffer left an empty line at the top of the edit buffer.</p> +</li> +</ol> +<p>For consistency, POSIX.1-2024 does not permit any of these behaviors.</p> +<p>Historically, <i>vi</i> did not always return the terminal to its original modes; for example, ICRNL was modified if it was not +originally set. POSIX.1-2024 does not permit this behavior.</p> +<h5><a name="tag_20_146_18_02" id="tag_20_146_18_02"></a>Command Descriptions in vi</h5> +<p>Motion commands are among the most complicated aspects of <i>vi</i> to describe. With some exceptions, the text region and +buffer type effect of a motion command on a <i>vi</i> command are described on a case-by-case basis. The descriptions of text +regions in POSIX.1-2024 are not intended to imply direction; that is, an inclusive region from line <i>n</i> to line <i>n</i>+5 is +identical to a region from line <i>n</i>+5 to line <i>n</i>. This is of more than academic interest—movements to marks can be in +either direction, and, if the <b>wrapscan</b> option is set, so can movements to search points. Historically, lines are always +stored into buffers in text order; that is, from the start of the edit buffer to the end. POSIX.1-2024 requires conformance to +historical practice.</p> +<p>Historically, command counts were applied to any associated motion, and were multiplicative to any supplied motion count. For +example, <b>2cw</b> is the same as <b>c2w</b>, and <b>2c3w</b> is the same as <b>c6w</b>. POSIX.1-2024 requires this behavior. +Historically, <i>vi</i> commands that used bigwords, words, paragraphs, and sentences as objects treated groups of empty lines, or +lines that contained only <blank> characters, inconsistently. Some commands treated them as a single entity, while others +treated each line separately. For example, the <b>w</b>, <b>W</b>, and <b>B</b> commands treated groups of empty lines as +individual words; that is, the command would move the cursor to each new empty line. The <b>e</b> and <b>E</b> commands treated +groups of empty lines as a single word; that is, the first use would move past the group of lines. The <b>b</b> command would just +beep at the user, or if done from the start of the line as a motion command, fail in unexpected ways. If the lines contained only +(or ended with) <blank> characters, the <b>w</b> and <b>W</b> commands would just beep at the user, the <b>E</b> and <b>e</b> +commands would treat the group as a single word, and the <b>B</b> and <b>b</b> commands would treat the lines as individual words. +For consistency and simplicity of specification, POSIX.1-2024 requires that all <i>vi</i> commands treat groups of empty or blank +lines as a single entity, and that movement through lines ending with <blank> characters be consistent with other +movements.</p> +<p>Historically, <i>vi</i> documentation indicated that any number of double-quotes were skipped after punctuation marks at +sentence boundaries; however, implementations only skipped single-quotes. POSIX.1-2024 requires both to be skipped.</p> +<p>Historically, the first and last characters in the edit buffer were word boundaries. This historical practice is required by +POSIX.1-2024.</p> +<p>Historically, <i>vi</i> attempted to update the minimum number of columns on the screen possible, which could lead to misleading +information being displayed. POSIX.1-2024 makes no requirements other than that the current character being entered is displayed +correctly, leaving all other decisions in this area up to the implementation.</p> +<p>Historically, lines were arbitrarily folded between columns of any characters that required multiple column positions on the +screen, with the exception of tabs, which terminated at the right-hand margin. POSIX.1-2024 permits the former and requires the +latter. Implementations that do not arbitrarily break lines between columns of characters that occupy multiple column positions +should not permit the cursor to rest on a column that does not contain any part of a character.</p> +<p>The historical <i>vi</i> had a problem in that all movements were by buffer lines, not by display or screen lines. This is often +the right thing to do; for example, single line movements, such as <b>j</b> or <b>k</b>, should work on buffer lines. Commands like +<b>dj</b>, or <b>j.</b>, where <b>.</b> is a change command, only make sense for buffer lines. It is not, however, the right thing +to do for screen motion or scrolling commands like <control>-D, <control>-F, and <b>H</b>. If the window is fairly +small, using buffer lines in these cases can result in completely random motion; for example, <b>1</b><control><b>-D</b> can +result in a completely changed screen, without any overlap. This is clearly not what the user wanted. The problem is even worse in +the case of the <b>H</b>, <b>L</b>, and <b>M</b> commands—as they position the cursor at the first non-<blank> of the line, +they may all refer to the same location in large lines, and will result in no movement at all.</p> +<p>In addition, if the line is larger than the screen, using buffer lines can make it impossible to display parts of the line—there +are not any commands that do not display the beginning of the line in historical <i>vi</i>, and if both the beginning and end of +the line cannot be on the screen at the same time, the user suffers. Finally, the page and half-page scrolling commands +historically moved to the first non-<blank> in the new line. If the line is approximately the same size as the screen, this +is inadequate because the cursor before and after a <control>-D command will refer to the same location on the screen.</p> +<p>Implementations of <a href="../utilities/ex.html"><i>ex</i></a> and <i>vi</i> exist that do not have these problems because the +relevant commands (<control>-B, <control>-D, <control>-F, <control>-U, <control>-Y, +<control>-E, <b>H</b>, <b>L</b>, and <b>M)</b> operate on display (screen) lines, not (edit) buffer lines.</p> +<p>POSIX.1-2024 does not permit this behavior by default because the standard developers believed that users would find it too +confusing. However, historical practice has been relaxed. For example, <a href="../utilities/ex.html"><i>ex</i></a> and <i>vi</i> +historically attempted, albeit sometimes unsuccessfully, to never put part of a line on the last lines of a screen; for example, if +a line would not fit in its entirety, no part of the line was displayed, and the screen lines corresponding to the line contained +single <tt>'@'</tt> characters. This behavior is permitted, but not required by POSIX.1-2024, so that it is possible for +implementations to support long lines in small screens more reasonably without changing the commands to be oriented to the display +(instead of oriented to the buffer). POSIX.1-2024 also permits implementations to refuse to edit any edit buffer containing a line +that will not fit on the screen in its entirety.</p> +<p>The display area (for example, the value of the <b>window</b> edit option) has historically been "grown", or expanded, to +display new text when local movements are done in displays where the number of lines displayed is less than the maximum possible. +Expansion has historically been the first choice, when the target line is less than the maximum possible expansion value away. +Scrolling has historically been the next choice, done when the target line is less than half a display away, and otherwise, the +screen was redrawn. There were exceptions, however, in that <a href="../utilities/ex.html"><i>ex</i></a> commands generally always +caused the screen to be redrawn. POSIX.1-2024 does not specify a standard behavior because there may be external issues, such as +connection speed, the number of characters necessary to redraw as opposed to scroll, or terminal capabilities that implementations +will have to accommodate.</p> +<p>The current line in POSIX.1-2024 maps one-to-one to a buffer line in the file. The current column does not. There are two +different column values that are described by POSIX.1-2024. The first is the current column value as set by many of the <i>vi</i> +commands. This value is remembered for the lifetime of the editor. The second column value is the actual position on the screen +where the cursor rests. The two are not always the same. For example, when the cursor is backed by a multi-column character, the +actual cursor position on the screen has historically been the last column of the character in command mode, and the first column +of the character in input mode.</p> +<p>Commands that set the current line, but that do not set the current cursor value (for example, <b>j</b> and <b>k</b>) attempt to +get as close as possible to the remembered column position, so that the cursor tends to restrict itself to a vertical column as the +user moves around in the edit buffer. POSIX.1-2024 requires conformance to historical practice, requiring that the display location +of the cursor on the display line be adjusted from the current column value as necessary to support this historical behavior.</p> +<p>Historically, only a single line (and for some terminals, a single line minus 1 column) of characters could be entered by the +user for the line-oriented commands; that is, <b>:</b>, <b>!</b>, <b>/</b>, or <b>?</b>. POSIX.1-2024 permits, but does not +require, this limitation.</p> +<p>Historically, "soft" errors in <i>vi</i> caused the terminal to be alerted, but no error message was displayed. As a general +rule, no error message was displayed for errors in command execution in <i>vi</i>, when the error resulted from the user attempting +an invalid or impossible action, or when a searched-for object was not found. Examples of soft errors included <b>h</b> at the left +margin, <control>-B or <b>[[</b> at the beginning of the file, <b>2G</b> at the end of the file, and so on. In addition, +errors such as <b>%</b>, <b>]]</b>, <b>}</b>, <b>)</b>, <b>N</b>, <b>n</b>, <b>f</b>, <b>F</b>, <b>t</b>, and <b>T</b> failing to +find the searched-for object were soft as well. Less consistently, <b>/</b> and <b>?</b> displayed an error message if the pattern +was not found, <b>/</b>, <b>?</b>, <b>N</b>, and <b>n</b> displayed an error message if no previous regular expression had been +specified, and <b>;</b> did not display an error message if no previous <b>f</b>, <b>F</b>, <b>t</b>, or <b>T</b> command had +occurred. Also, behavior in this area might reasonably be based on a runtime evaluation of the speed of a network connection. +Finally, some implementations have provided error messages for soft errors in order to assist naive users, based on the value of a +verbose edit option. POSIX.1-2024 does not list specific errors for which an error message shall be displayed. Implementations +should conform to historical practice in the absence of any strong reason to diverge.</p> +<h5><a name="tag_20_146_18_03" id="tag_20_146_18_03"></a>Page Backwards</h5> +<p>The <control>-B and <control>-F commands historically considered it an error to attempt to page past the beginning +or end of the file, whereas the <control>-D and <control>-U commands simply moved to the beginning or end of the file. +For consistency, POSIX.1-2024 requires the latter behavior for all four commands. All four commands still consider it an error if +the current line is at the beginning (<control>-B, <control>-U) or end (<control>-F, <control>-D) of the +file. Historically, the <control>-B and <control>-F commands skip two lines in order to include overlapping lines when +a single command is entered. This makes less sense in the presence of a <i>count</i>, as there will be, by definition, no +overlapping lines. The actual calculation used by historical implementations of the <i>vi</i> editor for <control>-B was:</p> +<pre> +<tt>((current first line) - count x (window edit option)) +2 +</tt></pre> +<p>and for <control>-F was:</p> +<pre> +<tt>((current first line) + count x (window edit option)) -2 +</tt></pre> +<p>This calculation does not work well when intermixing commands with and without counts; for example, <b>3</b><control>-F is +not equivalent to entering the <control>-F command three times, and is not reversible by entering the <control>-B +command three times. For consistency with other <i>vi</i> commands that take counts, POSIX.1-2024 requires a different +calculation.</p> +<h5><a name="tag_20_146_18_04" id="tag_20_146_18_04"></a>Scroll Forward</h5> +<p>The 4BSD and System V implementations of <i>vi</i> differed on the initial value used by the <b>scroll</b> command. 4BSD +used:</p> +<pre> +<tt>((window edit option) +1) /2 +</tt></pre> +<p>while System V used the value of the <b>scroll</b> edit option. The System V version is specified by POSIX.1-2024 because the +standard developers believed that it was more intuitive and permitted the user a method of setting the scroll value initially +without also setting the number of lines that are displayed.</p> +<h5><a name="tag_20_146_18_05" id="tag_20_146_18_05"></a>Scroll Forward by Line</h5> +<p>Historically, the <control>-E and <control>-Y commands considered it an error if the last and first lines, +respectively, were already on the screen. POSIX.1-2024 requires conformance to historical practice. Historically, the +<control>-E and <control>-Y commands had no effect in open mode. For simplicity and consistency of specification, +POSIX.1-2024 requires that they behave as usual, albeit with a single line screen.</p> +<h5><a name="tag_20_146_18_06" id="tag_20_146_18_06"></a>Clear and Redisplay</h5> +<p>The historical <control>-L command refreshed the screen exactly as it was supposed to be currently displayed, replacing +any <tt>'@'</tt> characters for lines that had been deleted but not updated on the screen with refreshed <tt>'@'</tt> characters. +The intent of the <control>-L command is to refresh when the screen has been accidentally overwritten; for example, by a +<b>write</b> command from another user, or modem noise.</p> +<h5><a name="tag_20_146_18_07" id="tag_20_146_18_07"></a>Redraw Screen</h5> +<p>The historical <control>-R command redisplayed only when necessary to update lines that had been deleted but not updated +on the screen and that were flagged with <tt>'@'</tt> characters. There is no requirement that the screen be in any way refreshed +if no lines of this form are currently displayed. POSIX.1-2024 permits implementations to extend this command to refresh lines on +the screen flagged with <tt>'@'</tt> characters because they are too long to be displayed in the current framework; however, the +current line and column need not be modified.</p> +<h5><a name="tag_20_146_18_08" id="tag_20_146_18_08"></a>Search for tagstring</h5> +<p>Historically, the first non-<blank> at or after the cursor was the first character, and all subsequent characters that +were word characters, up to the end of the line, were included. For example, with the cursor on the leading <space> or on the +<tt>'#'</tt> character in the text <tt>"#bar@"</tt>, the tag was <tt>"#bar"</tt>. On the character <tt>'b'</tt> it was +<tt>"bar"</tt>, and on the <tt>'a'</tt> it was <tt>"ar"</tt>. POSIX.1-2024 requires this behavior.</p> +<h5><a name="tag_20_146_18_09" id="tag_20_146_18_09"></a>Replace Text with Results from Shell Command</h5> +<p>Historically, the <b><</b>, <b>></b>, and <b>!</b> commands considered most cursor motions other than line-oriented +motions an error; for example, the command <b>>/foo<CR></b> succeeded, while the command <b>>l</b> failed, even though +the text region described by the two commands might be identical. For consistency, all three commands only consider entire lines +and not partial lines, and the region is defined as any line that contains a character that was specified by the motion.</p> +<h5><a name="tag_20_146_18_10" id="tag_20_146_18_10"></a>Move to Matching Character</h5> +<p>Other matching characters have been left implementation-defined in order to allow extensions such as matching <tt>'<'</tt> +and <tt>'>'</tt> for searching HTML, or <b>#ifdef</b>, <b>#else</b>, and <b>#endif</b> for searching C source.</p> +<h5><a name="tag_20_146_18_11" id="tag_20_146_18_11"></a>Repeat Substitution</h5> +<p>POSIX.1-2024 requires that any <b>c</b> and <b>g</b> flags specified to the previous substitute command be ignored; however, the +<b>r</b> flag may still apply, if supported by the implementation.</p> +<h5><a name="tag_20_146_18_12" id="tag_20_146_18_12"></a>Return to Previous (Context or Section)</h5> +<p>The <b>[[</b>, <b>]]</b>, <b>(</b>, <b>)</b>, <b>{</b>, and <b>}</b> commands are all affected by "section boundaries", but in +some historical implementations not all of the commands recognize the same section boundaries. This is a bug, not a feature, and a +unique section-boundary algorithm was not described for each command. One special case that is preserved is that the sentence +command moves to the end of the last line of the edit buffer while the other commands go to the beginning, in order to preserve the +traditional character cut semantics of the sentence command. Historically, <i>vi</i> section boundaries at the beginning and end of +the edit buffer were the first non-<blank> on the first and last lines of the edit buffer if one exists; otherwise, the last +character of the first and last lines of the edit buffer if one exists. To increase consistency with other section locations, this +has been simplified by POSIX.1-2024 to the first character of the first and last lines of the edit buffer, or the first and the +last lines of the edit buffer if they are empty.</p> +<p>Sentence boundaries were problematic in the historical <i>vi</i>. They were not only the boundaries as defined for the section +and paragraph commands, but they were the first non-<blank> that occurred after those boundaries, as well. Historically, the +<i>vi</i> section commands were documented as taking an optional window size as a <i>count</i> preceding the command. This was not +implemented in historical versions, so POSIX.1-2024 requires that the <i>count</i> repeat the command, for consistency with other +<i>vi</i> commands.</p> +<h5><a name="tag_20_146_18_13" id="tag_20_146_18_13"></a>Repeat</h5> +<p>Historically, mapped commands other than text input commands could not be repeated using the <b>period</b> command. POSIX.1-2024 +requires conformance to historical practice.</p> +<p>The restrictions on the interpretation of special characters (for example, <control>-H) in the repetition of text input +mode commands is intended to match historical practice. For example, given the input sequence:</p> +<pre> +<tt>iab<control>-H<control>-H<control>-Hdef<escape> +</tt></pre> +<p>the user should be informed of an error when the sequence is first entered, but not during a command repetition. The character +<control>-T is specifically exempted from this restriction. Historical implementations of <i>vi</i> ignored <control>-T +characters that were input in the original command during command repetition. POSIX.1-2024 prohibits this behavior.</p> +<h5><a name="tag_20_146_18_14" id="tag_20_146_18_14"></a>Find Regular Expression</h5> +<p>Historically, commands did not affect the line searched to or from if the motion command was a search (<b>/</b>, <b>?</b>, +<b>N</b>, <b>n</b>) and the final position was the start/end of the line. There were some special cases and <i>vi</i> was not +consistent. POSIX.1-2024 does not permit this behavior, for consistency. Historical implementations permitted but were unable to +handle searches as motion commands that wrapped (that is, due to the edit option <b>wrapscan</b>) to the original location. +POSIX.1-2024 requires that this behavior be treated as an error.</p> +<p>Historically, the syntax <tt>"/RE/0"</tt> was used to force the command to cut text in line mode. POSIX.1-2024 requires +conformance to historical practice.</p> +<p>Historically, in open mode, a <b>z</b> specified to a search command redisplayed the current line instead of displaying the +current screen with the current line highlighted. For consistency and simplicity of specification, POSIX.1-2024 does not permit +this behavior.</p> +<p>Historically, trailing <b>z</b> commands were permitted and ignored if entered as part of a search used as a motion command. For +consistency and simplicity of specification, POSIX.1-2024 does not permit this behavior.</p> +<h5><a name="tag_20_146_18_15" id="tag_20_146_18_15"></a>Execute an ex Command</h5> +<p>Historically, <i>vi</i> implementations restricted the commands that could be entered on the colon command line (for example, +<b>append</b> and <b>change</b>), and some other commands were known to cause them to fail catastrophically. For consistency, +POSIX.1-2024 does not permit these restrictions. When executing an <a href="../utilities/ex.html"><i>ex</i></a> command by entering +<b>:</b>, it is not possible to enter a <newline> as part of the command because it is considered the end of the command. A +different approach is to enter <a href="../utilities/ex.html"><i>ex</i></a> command mode by using the <i>vi</i> <b>Q</b> command +(and later resuming visual mode with the <a href="../utilities/ex.html"><i>ex</i></a> <b>vi</b> command). In <a href= +"../utilities/ex.html"><i>ex</i></a> command mode, the single-line limitation does not exist. So, for example, the following is +valid:</p> +<pre> +<tt>Q +s/break here/break\ +here/ +vi +</tt></pre> +<p>POSIX.1-2024 requires that, if the <a href="../utilities/ex.html"><i>ex</i></a> command overwrites any part of the screen that +would be erased by a refresh, <i>vi</i> pauses for a character from the user. Historically, this character could be any character; +for example, a character input by the user before the message appeared, or even a mapped character. This is probably a bug, but +implementations that have tried to be more rigorous by requiring that the user enter a specific character, or that the user enter a +character after the message was displayed, have been forced by user indignation back into historical behavior. POSIX.1-2024 +requires conformance to historical practice.</p> +<h5><a name="tag_20_146_18_16" id="tag_20_146_18_16"></a>Shift Left (Right)</h5> +<p>Refer to the Rationale for the <b>!</b> and <b>/</b> commands. Historically, the <b><</b> and <b>></b> commands sometimes +moved the cursor to the first non-<blank> (for example if the command was repeated or with <b>_</b> as the motion command), +and sometimes left it unchanged. POSIX.1-2024 does not permit this inconsistency, requiring instead that the cursor always move to +the first non-<blank>. Historically, the <b><</b> and <b>></b> commands did not support buffer arguments, although some +implementations allow the specification of an optional buffer. This behavior is neither required nor disallowed by +POSIX.1-2024.</p> +<h5><a name="tag_20_146_18_17" id="tag_20_146_18_17"></a>Execute</h5> +<p>Historically, buffers could execute other buffers, and loops, infinite and otherwise, were possible. POSIX.1-2024 requires +conformance to historical practice. The *<i>buffer</i> syntax of <a href="../utilities/ex.html"><i>ex</i></a> is not required in +<i>vi</i>, because it is not historical practice and has been used in some <i>vi</i> implementations to support additional +scripting languages.</p> +<h5><a name="tag_20_146_18_18" id="tag_20_146_18_18"></a>Reverse Case</h5> +<p>Historically, the <b>~</b> command ignored any associated <i>count</i>, and acted only on the characters in the current line. +For consistency with other <i>vi</i> commands, POSIX.1-2024 requires that an associated <i>count</i> act on the next <i>count</i> +characters, and that the command move to subsequent lines if warranted by <i>count</i>, to make it possible to modify large pieces +of text in a reasonably efficient manner. There exist <i>vi</i> implementations that optionally require an associated motion +command for the <b>~</b> command. Implementations supporting this functionality are encouraged to base it on the <b>tildedop</b> +edit option and handle the text regions and cursor positioning identically to the <b>yank</b> command.</p> +<h5><a name="tag_20_146_18_19" id="tag_20_146_18_19"></a>Append</h5> +<p>Historically, <i>count</i>s specified to the <b>A</b>, <b>a</b>, <b>I</b>, and <b>i</b> commands repeated the input of the first +line <i>count</i> times, and did not repeat the subsequent lines of the input text. POSIX.1-2024 requires that the entire text +input be repeated <i>count</i> times.</p> +<h5><a name="tag_20_146_18_20" id="tag_20_146_18_20"></a>Move Backward to Preceding Word</h5> +<p>Historically, <i>vi</i> became confused if word commands were used as motion commands in empty files. POSIX.1-2024 requires that +this be an error. Historical implementations of <i>vi</i> had a large number of bugs in the word movement commands, and they varied +greatly in behavior in the presence of empty lines, "words" made up of a single character, and lines containing only +<blank> characters. For consistency and simplicity of specification, POSIX.1-2024 does not permit this behavior.</p> +<h5><a name="tag_20_146_18_21" id="tag_20_146_18_21"></a>Change to End-of-Line</h5> +<p>Some historical implementations of the <b>C</b> command did not behave as described by POSIX.1-2024 when the <b>$</b> key was +remapped because they were implemented by pushing the <b>$</b> key onto the input queue and reprocessing it. POSIX.1-2024 does not +permit this behavior. Historically, the <b>C</b>, <b>S</b>, and <b>s</b> commands did not copy replaced text into the numeric +buffers. For consistency and simplicity of specification, POSIX.1-2024 requires that they behave like their respective <b>c</b> +commands in all respects.</p> +<h5><a name="tag_20_146_18_22" id="tag_20_146_18_22"></a>Delete</h5> +<p>Historically, lines in open mode that were deleted were scrolled up, and an <b>@</b> glyph written over the beginning of the +line. In the case of terminals that are incapable of the necessary cursor motions, the editor erased the deleted line from the +screen. POSIX.1-2024 requires conformance to historical practice; that is, if the terminal cannot display the <tt>'@'</tt> +character, the line cannot remain on the screen.</p> +<h5><a name="tag_20_146_18_23" id="tag_20_146_18_23"></a>Delete to End-of-Line</h5> +<p>Some historical implementations of the <b>D</b> command did not behave as described by POSIX.1-2024 when the <b>$</b> key was +remapped because they were implemented by pushing the <b>$</b> key onto the input queue and reprocessing it. POSIX.1-2024 does not +permit this behavior.</p> +<h5><a name="tag_20_146_18_24" id="tag_20_146_18_24"></a>Join</h5> +<p>An historical oddity of <i>vi</i> is that the commands <b>J</b>, <b>1J</b>, and <b>2J</b> are all equivalent. POSIX.1-2024 +requires conformance to historical practice. The <i>vi</i> <b>J</b> command is specified in terms of the <a href= +"../utilities/ex.html"><i>ex</i></a> <b>join</b> command with an <a href="../utilities/ex.html"><i>ex</i></a> command <i>count</i> +value. The address correction for a <i>count</i> that is past the end of the edit buffer is necessary for historical compatibility +for both <a href="../utilities/ex.html"><i>ex</i></a> and <i>vi</i>.</p> +<h5><a name="tag_20_146_18_25" id="tag_20_146_18_25"></a>Mark Position</h5> +<p>Historical practice is that only lowercase letters, plus backquote and single-quote, could be used to mark a cursor position. +POSIX.1-2024 requires conformance to historical practice, but encourages implementations to support other characters as marks as +well.</p> +<h5><a name="tag_20_146_18_26" id="tag_20_146_18_26"></a>Repeat Regular Expression Find (Forward and Reverse)</h5> +<p>Historically, the <b>N</b> and <b>n</b> commands could not be used as motion components for the <b>c</b> command. With the +exception of the <b>cN</b> command, which worked if the search crossed a line boundary, the text region would be discarded, and the +user would not be in text input mode. For consistency and simplicity of specification, POSIX.1-2024 does not permit this +behavior.</p> +<h5><a name="tag_20_146_18_27" id="tag_20_146_18_27"></a>Insert Empty Line (Below and Above)</h5> +<p>Historically, counts to the <b>O</b> and <b>o</b> commands were used as the number of physical lines to open, if the terminal +was dumb and the <b>slowopen</b> option was not set. This was intended to minimize traffic over slow connections and repainting for +dumb terminals. POSIX.1-2024 does not permit this behavior, requiring that a <i>count</i> to the open command behave as for other +text input commands. This change to historical practice was made for consistency, and because a superset of the functionality is +provided by the <b>slowopen</b> edit option.</p> +<h5><a name="tag_20_146_18_28" id="tag_20_146_18_28"></a>Put from Buffer (Following and Before)</h5> +<p>Historically, <i>count</i>s to the <b>p</b> and <b>P</b> commands were ignored if the buffer was a line mode buffer, but were +(mostly) implemented as described in POSIX.1-2024 if the buffer was a character mode buffer. Because implementations exist that do +not have this limitation, and because pasting lines multiple times is generally useful, POSIX.1-2024 requires that <i>count</i> be +supported for all <b>p</b> and <b>P</b> commands.</p> +<p>Historical implementations of <i>vi</i> were widely known to have major problems in the <b>p</b> and <b>P</b> commands, +particularly when unusual regions of text were copied into the edit buffer. The standard developers viewed these as bugs, and they +are not permitted for consistency and simplicity of specification.</p> +<p>Historically, a <b>P</b> or <b>p</b> command (or an <a href="../utilities/ex.html"><i>ex</i></a> <b>put</b> command executed +from open or visual mode) executed in an empty file, left an empty line as the first line of the file. For consistency and +simplicity of specification, POSIX.1-2024 does not permit this behavior.</p> +<h5><a name="tag_20_146_18_29" id="tag_20_146_18_29"></a>Replace Character</h5> +<p>Historically, the <b>r</b> command did not correctly handle the <i>erase</i> and <i>word erase</i> characters as arguments, nor +did it handle an associated <i>count</i> greater than 1 with a <carriage-return> argument, for which it replaced <i>count</i> +characters with a single <newline>. POSIX.1-2024 does not permit these inconsistencies.</p> +<p>Historically, the <b>r</b> command permitted the <control>-V escaping of entered characters, such as <ESC> and the +<carriage-return>; however, it required two leading <control>-V characters instead of one. POSIX.1-2024 requires that +this be changed for consistency with the other text input commands of <i>vi</i>.</p> +<p>Historically, it is an error to enter the <b>r</b> command if there are less than <i>count</i> characters at or after the cursor +in the line. While a reasonable and unambiguous extension would be to permit the <b>r</b> command on empty lines, it would require +that too large a <i>count</i> be adjusted to match the number of characters at or after the cursor for consistency, which is +sufficiently different from historical practice to be avoided. POSIX.1-2024 requires conformance to historical practice.</p> +<h5><a name="tag_20_146_18_30" id="tag_20_146_18_30"></a>Replace Characters</h5> +<p>Historically, if there were <b>autoindent</b> characters in the line on which the <b>R</b> command was run, and +<b>autoindent</b> was set, the first <newline> would be properly indented and no characters would be replaced by the +<newline>. Each additional <newline> would replace <i>n</i> characters, where <i>n</i> was the number of characters +that were needed to indent the rest of the line to the proper indentation level. This behavior is a bug and is not permitted by +POSIX.1-2024.</p> +<h5><a name="tag_20_146_18_31" id="tag_20_146_18_31"></a>Undo</h5> +<p>Historical practice for cursor positioning after undoing commands was mixed. In most cases, when undoing commands that affected +a single line, the cursor was moved to the start of added or changed text, or immediately after deleted text. However, if the user +had moved from the line being changed, the column was either set to the first non-<blank>, returned to the origin of the +command, or remained unchanged. When undoing commands that affected multiple lines or entire lines, the cursor was moved to the +first character in the first line restored. As an example of how inconsistent this was, a search, followed by an <b>o</b> text +input command, followed by an <b>undo</b> would return the cursor to the location where the <b>o</b> command was entered, but a +<b>cw</b> command followed by an <b>o</b> command followed by an <b>undo</b> would return the cursor to the first non-<blank> +of the line. POSIX.1-2024 requires the most useful of these behaviors, and discards the least useful, in the interest of +consistency and simplicity of specification.</p> +<h5><a name="tag_20_146_18_32" id="tag_20_146_18_32"></a>Yank</h5> +<p>Historically, the <b>yank</b> command did not move to the end of the motion if the motion was in the forward direction. It moved +to the end of the motion if the motion was in the backward direction, except for the <b>_</b> command, or for the <b>G</b> and +<b>'</b> commands when the end of the motion was on the current line. This was further complicated by the fact that for a number of +motion commands, the <b>yank</b> command moved the cursor but did not update the screen; for example, a subsequent command would +move the cursor from the end of the motion, even though the cursor on the screen had not reflected the cursor movement for the +<b>yank</b> command. POSIX.1-2024 requires that all <b>yank</b> commands associated with backward motions move the cursor to the +end of the motion for consistency, and specifically, to make <b>'</b> commands as motions consistent with search patterns as +motions.</p> +<h5><a name="tag_20_146_18_33" id="tag_20_146_18_33"></a>Yank Current Line</h5> +<p>Some historical implementations of the <b>Y</b> command did not behave as described by POSIX.1-2024 when the <tt>'_'</tt> key +was remapped because they were implemented by pushing the <tt>'_'</tt> key onto the input queue and reprocessing it. POSIX.1-2024 +does not permit this behavior.</p> +<h5><a name="tag_20_146_18_34" id="tag_20_146_18_34"></a>Redraw Window</h5> +<p>Historically, the <b>z</b> command always redrew the screen. This is permitted but not required by POSIX.1-2024, because of the +frequent use of the <b>z</b> command in macros such as <b>map n nz.</b> for screen positioning, instead of its use to change the +screen size. The standard developers believed that expanding or scrolling the screen offered a better interface for users. The +ability to redraw the screen is preserved if the optional new window size is specified, and in the <control>-L and +<control>-R commands.</p> +<p>The semantics of <b>z^</b> are confusing at best. Historical practice is that the screen before the screen that ended with the +specified line is displayed. POSIX.1-2024 requires conformance to historical practice.</p> +<p>Historically, the <b>z</b> command would not display a partial line at the top or bottom of the screen. If the partial line +would normally have been displayed at the bottom of the screen, the command worked, but the partial line was replaced with +<tt>'@'</tt> characters. If the partial line would normally have been displayed at the top of the screen, the command would fail. +For consistency and simplicity of specification, POSIX.1-2024 does not permit this behavior.</p> +<p>Historically, the <b>z</b> command with a line specification of 1 ignored the command. For consistency and simplicity of +specification, POSIX.1-2024 does not permit this behavior.</p> +<p>Historically, the <b>z</b> command did not set the cursor column to the first non-<blank> for the character if the first +screen was to be displayed, and was already displayed. For consistency and simplicity of specification, POSIX.1-2024 does not +permit this behavior.</p> +<h5><a name="tag_20_146_18_35" id="tag_20_146_18_35"></a>Input Mode Commands in vi</h5> +<p>Historical implementations of <i>vi</i> did not permit the user to erase more than a single line of input, or to use normal +erase characters such as <i>line erase</i>, <i>worderase</i>, and <i>erase</i> to erase <b>autoindent</b> characters. As there +exist implementations of <i>vi</i> that do not have these limitations, both behaviors are permitted, but only historical practice +is required. In the case of these extensions, <i>vi</i> is required to pause at the <b>autoindent</b> and previous line +boundaries.</p> +<p>Historical implementations of <i>vi</i> updated only the portion of the screen where the current cursor character was displayed. +For example, consider the <i>vi</i> input keystrokes:</p> +<pre> +<tt>iabcd<escape>0C<tab> +</tt></pre> +<p>Historically, the <tab> would overwrite the characters <tt>"abcd"</tt> when it was displayed. Other implementations +replace only the <tt>'a'</tt> character with the <tab>, and then push the rest of the characters ahead of the cursor. Both +implementations have problems. The historical implementation is probably visually nicer for the above example; however, for the +keystrokes:</p> +<pre> +<tt>iabcd<ESC>0R<tab><ESC> +</tt></pre> +<p>the historical implementation results in the string <tt>"bcd"</tt> disappearing and then magically reappearing when the +<ESC> character is entered. POSIX.1-2024 requires the former behavior when overwriting erase-columns—that is, overwriting +characters that are no longer logically part of the edit buffer—and the latter behavior otherwise.</p> +<p>Historical implementations of <i>vi</i> discarded the <control>-D and <control>-T characters when they were entered +at places where their command functionality was not appropriate. POSIX.1-2024 requires that the <control>-T functionality +always be available, and that <control>-D be treated as any other key when not operating on <b>autoindent</b> characters.</p> +<h5><a name="tag_20_146_18_36" id="tag_20_146_18_36"></a>NUL</h5> +<p>Some historical implementations of <i>vi</i> limited the number of characters entered using the NUL input character to 256 +bytes. POSIX.1-2024 permits this limitation; however, implementations are encouraged to remove this limit.</p> +<h5><a name="tag_20_146_18_37" id="tag_20_146_18_37"></a><control>-D</h5> +<p>See also Rationale for the input mode command <newline>. The hidden assumptions in the <control>-D command (and in +the <i>vi</i> <b>autoindent</b> specification in general) is that <space> characters take up a single column on the screen +and that <tab> characters are comprised of an integral number of <space> characters.</p> +<h5><a name="tag_20_146_18_38" id="tag_20_146_18_38"></a><newline></h5> +<p>Implementations are permitted to rewrite <b>autoindent</b> characters in the line when <newline>, <carriage-return>, +<control>-D, and <control>-T are entered, or when the <b>shift</b> commands are used, because historical +implementations have both done so and found it necessary to do so. For example, a <control>-D when the cursor is preceded by +a single <tab>, with <b>tabstop</b> set to 8, and <b>shiftwidth</b> set to 3, will result in the <tab> being replaced +by several <space> characters.</p> +<h5><a name="tag_20_146_18_39" id="tag_20_146_18_39"></a><control>-T</h5> +<p>See also the Rationale for the input mode command <newline>. Historically, <control>-T only worked if no +non-<blank> characters had yet been input in the current input line. In addition, the characters inserted by +<control>-T were treated as <b>autoindent</b> characters, and could not be erased using normal user erase characters. Because +implementations exist that do not have these limitations, and as moving to a column boundary is generally useful, POSIX.1-2024 +requires that both limitations be removed.</p> +<h5><a name="tag_20_146_18_40" id="tag_20_146_18_40"></a><control>-V</h5> +<p>Historically, <i>vi</i> used <b>^V</b>, regardless of the value of the literal-next character of the terminal. POSIX.1-2024 +requires conformance to historical practice.</p> +<p>The uses described for <control>-V can also be accomplished with <control>-Q, which is useful on terminals that use +<control>-V for the down-arrow function. However, most historical implementations use <control>-Q for the +<i>termios</i> START character, so the editor will generally not receive the <control>-Q unless <b>stty ixon</b> mode is set +to off. (In addition, some historical implementations of <i>vi</i> explicitly set <b>ixon</b> mode to on, so it was difficult for +the user to set it to off.) Any of the command characters described in POSIX.1-2024 can be made ineffective by their selection as +<i>termios</i> control characters, using the <a href="../utilities/stty.html"><i>stty</i></a> utility or other methods described in +the System Interfaces volume of POSIX.1-2024.</p> +<h5><a name="tag_20_146_18_41" id="tag_20_146_18_41"></a><ESC></h5> +<p>Historically, SIGINT alerted the terminal when used to end input mode. This behavior is permitted, but not required, by +POSIX.1-2024.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_146_19" id="tag_20_146_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a +<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require +implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_146_20" id="tag_20_146_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/ed.html#"><i>ed</i></a> , <a href="../utilities/ex.html#"><i>ex</i></a> , <a href= +"../utilities/stty.html#"><i>stty</i></a></p> +<p>XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_146_21" id="tag_20_146_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_146_22" id="tag_20_146_22"></a>Issue 5</h4> +<blockquote> +<p>The FUTURE DIRECTIONS section is added.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_146_23" id="tag_20_146_23"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +<p>The APPLICATION USAGE section is added.</p> +<p>The obsolescent SYNOPSIS is removed.</p> +<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p> +<ul> +<li> +<p>The <b>reindent</b> command description is added.</p> +</li> +</ul> +<p>The <i>vi</i> utility has been extensively rewritten for alignment with the IEEE P1003.2b draft standard.</p> +<p>IEEE PASC Interpretations 1003.2 #57, #62, #63, #64, #78, and #188 are applied.</p> +<p>IEEE PASC Interpretation 1003.2 #207 is applied, clarifying the description of the <b>R</b> command in a manner similar to the +descriptions of other text input mode commands such as <b>i</b>, <b>o</b>, and <b>O</b>.</p> +<p>The <b>-l</b> option is removed.</p> +<p>IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/41 is applied, adding [<i>count</i>] to the Synopsis for +<b>[[</b>.</p> +<p>IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/42 is applied, adding [<i>count</i>] to the Synopsis for +<b>]]</b>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_146_24" id="tag_20_146_24"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #027 is applied, clarifying that <tt>'+'</tt> may be recognized as an option delimiter +in the OPTIONS section.</p> +<p>Austin Group Interpretation 1003.1-2001 #087 is applied, updating the Put from Buffer Before (<b>P</b>) command description to +address multi-line requirements.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0202 [812] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_146_25" id="tag_20_146_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to disallow the creation of filenames containing any bytes that +have the encoded value of a <newline> character.</p> +<p>Austin Group Defect 1310 is applied, changing the CONSEQUENCES OF ERRORS section.</p> +<p>Austin Group Defect 1676 is applied, changing the typeface of some bold text in the RATIONALE section.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/val.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/wait.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/wait.html b/bdd/wait.html @@ -0,0 +1,304 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>wait</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/vi.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/wc.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="wait" id="wait"></a> <a name="tag_20_147" id="tag_20_147"></a><!-- wait --> +<h4 class="mansect"><a name="tag_20_147_01" id="tag_20_147_01"></a>NAME</h4> +<blockquote>wait — await process completion</blockquote> +<h4 class="mansect"><a name="tag_20_147_02" id="tag_20_147_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>wait</tt> <b>[</b><i>pid</i><tt>...</tt><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_147_03" id="tag_20_147_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>wait</i> utility shall wait for one or more child processes whose process IDs are known in the current shell execution +environment (see <a href="../utilities/V3_chap02.html#tag_19_13"><i>2.13 Shell Execution Environment</i></a> ) to terminate.</p> +<p>If the <i>wait</i> utility is invoked with no operands, it shall wait until all process IDs known to the invoking shell have +terminated and exit with a zero exit status.</p> +<p>If one or more <i>pid</i> operands are specified that represent known process IDs, the <i>wait</i> utility shall wait until all +of them have terminated. If one or more <i>pid</i> operands are specified that represent unknown process IDs, <i>wait</i> shall +treat them as if they were known process IDs that exited with exit status 127. The exit status returned by the <i>wait</i> utility +shall be the exit status of the process requested by the last <i>pid</i> operand.</p> +<p>Once a process ID that is known in the current shell execution environment (see <a href= +"../utilities/V3_chap02.html#tag_19_13"><i>2.13 Shell Execution Environment</i></a> ) has been successfully waited for, it shall be +removed from the list of process IDs that are known in the current shell execution environment. If the process ID is associated +with a background job, the corresponding job shall also be removed from the list of background jobs.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_147_04" id="tag_20_147_04"></a>OPTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_147_05" id="tag_20_147_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>pid</i></dt> +<dd>One of the following: +<ol> +<li> +<p>The unsigned decimal integer process ID of a child process whose termination the utility is to wait for.</p> +</li> +<li> +<p>A job ID (see XBD <a href="../basedefs/V1_chap03.html#tag_03_182"><i>3.182 Job ID</i></a> ) that identifies a process group in +the case of a job-control background job, or a process ID in the case of a non-job-control background job (if supported), to be +waited for. The job ID notation is applicable only for invocations of <i>wait</i> in the current shell execution environment; see +<a href="../utilities/V3_chap02.html#tag_19_13"><i>2.13 Shell Execution Environment</i></a> . The exit status of <i>wait</i> shall +be determined by the exit status of the last pipeline to be executed. <basefont size="2"></p> +<dl> +<dt><b>Note:</b></dt> +<dd>The job ID type of <i>pid</i> is only available on systems supporting the User Portability Utilities option or supporting +non-job-control background jobs.</dd> +</dl> +<basefont size="3"></li> +</ol> +</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_147_06" id="tag_20_147_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_147_07" id="tag_20_147_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_147_08" id="tag_20_147_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>wait</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_147_09" id="tag_20_147_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_147_10" id="tag_20_147_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_147_11" id="tag_20_147_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_147_12" id="tag_20_147_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_147_13" id="tag_20_147_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_147_14" id="tag_20_147_14"></a>EXIT STATUS</h4> +<blockquote> +<p>If one or more operands were specified, all of them have terminated or were not known in the invoking shell execution +environment, and the status of the last operand specified is known, then the exit status of <i>wait</i> shall be the status of the +last operand specified. If the process terminated abnormally due to the receipt of a signal, the exit status shall be greater than +128 and shall be distinct from the exit status generated by other signals, but the exact value is unspecified. (See the <a href= +"../utilities/kill.html"><i>kill</i></a> <b>-l</b> option.) Otherwise, the <i>wait</i> utility shall exit with one of the following +values:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>The <i>wait</i> utility was invoked with no operands and all process IDs known by the invoking shell have terminated.</dd> +<dt>1-126</dt> +<dd>The <i>wait</i> utility detected an error.</dd> +<dt> 127</dt> +<dd>The process ID specified by the last <i>pid</i> operand specified is not known in the invoking shell execution +environment.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_147_15" id="tag_20_147_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_147_16" id="tag_20_147_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>This utility is required to be intrinsic. See <a href="../utilities/V3_chap01.html#tag_18_07"><i>1.7 Intrinsic Utilities</i></a> +for details.</p> +<p>On most implementations, <i>wait</i> is a shell built-in. If it is called in a subshell or separate utility execution +environment, such as one of the following:</p> +<pre> +<tt>(wait) +nohup wait ... +find . -exec wait ... \; +</tt></pre> +<p>it returns immediately because there are no known process IDs to wait for in those environments.</p> +<p>The use of job ID notation is not dependent on job control being enabled. When job control has been disabled using <a href= +"../utilities/set.html"><i>set</i></a> <b>+m</b>, <i>wait</i> can still be used to wait for the process group associated with a +job-control background job, or the process ID associated with a non-control background job (if supported), using</p> +<pre> +<tt>wait %<</tt><i>background job number</i><tt>> +</tt></pre> +<p>See also the RATIONALE for <a href="../utilities/jobs.html"><i>jobs</i></a> and <a href= +"../utilities/kill.html"><i>kill</i></a>.</p> +<p>The shell is allowed to discard the status of any process if it determines that the application cannot get the process ID for +that process from the shell. It is also required to remember only {CHILD_MAX} number of processes in this way. Since the only way +to get the process ID from the shell is by using the <tt>'!'</tt> shell parameter, the shell is allowed to discard the status of an +asynchronous AND-OR list if <tt>"$!"</tt> was not referenced before another asynchronous AND-OR list was started. (This means that +the shell only has to keep the status of the last asynchronous AND-OR list started if the application did not reference +<tt>"$!"</tt>. If the implementation of the shell is smart enough to determine that a reference to <tt>"$!"</tt> was not saved +anywhere that the application can retrieve it later, it can use this information to trim the list of saved information. Note also +that a successful call to <i>wait</i> with no operands discards the exit status of all asynchronous AND-OR lists.)</p> +<p>If the exit status of <i>wait</i> is greater than 128, there is no way for the application to know if the waited-for process +exited with that value or was killed by a signal. Since most utilities exit with small values, there is seldom any ambiguity. Even +in the ambiguous cases, most applications just need to know that the asynchronous job failed; it does not matter whether it +detected an error and failed or was killed and did not complete its job normally.</p> +<p>Some historical shells returned from wait when a process stops instead of only when it terminates. This standard does not allow +wait to return when a process stops for two reasons:</p> +<ol> +<li> +<p>The vast majority, if not all, shell scripts that use <i>wait</i> (without using an extension) expect it not to return until the +process terminates.</p> +</li> +<li> +<p>It is not possible to write a portable shell script that can correctly handle <i>wait</i> returning when a process stops, +because an exit status indicating a process was stopped by a signal cannot be distinguished from one indicating that the process +called <a href="../functions/exit.html"><i>exit</i>()</a> with the same value.</p> +</li> +</ol> +<p>The standard developers considered allowing interactive shells to return from <i>wait</i> when a process stops, since the +interactive user would see a message which would allow them to tell whether the process stopped or terminated. However, they +decided that it would be inadvisable to introduce an inconsistency between interactive and non-interactive shells, particularly as +the most likely use of <i>wait</i> in an interactive shell is to try out commands before putting them in a shell script. +Implementations can provide an extension that could be used to request that <i>wait</i> returns when a process stops. It is +recommended that any such extension uses a different method of returning information about the wait status of the process so that +the information can be unambiguous. One suitable method would be an option that takes a variable name as an option-argument. The +named variable would be set to a numeric value and the exit status of wait would indicate whether this value is an exit value or a +signal number, and whether the signal terminated the process or stopped it. Such an extension would also provide a way for shell +scripts to obtain the full exit value (as would be returned by <a href="../functions/waitid.html"><i>waitid</i>()</a>).</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_147_17" id="tag_20_147_17"></a>EXAMPLES</h4> +<blockquote> +<p>Although the exact value used when a process is terminated by a signal is unspecified, if it is known that a signal terminated a +process, a script can still reliably determine which signal by using <a href="../utilities/kill.html"><i>kill</i></a> as shown by +the following script:</p> +<pre> +<tt>sleep 1000& +pid=$! +kill -kill $pid +wait $pid +echo $pid was terminated by a SIG$(kill -l $?) signal. +</tt></pre> +<p>If the following sequence of commands is run in less than 31 seconds:</p> +<pre> +<tt>sleep 257 | sleep 31 & +jobs -l %% +</tt></pre> +<p>either of the following commands returns the exit status of the second <a href="../utilities/sleep.html"><i>sleep</i></a> in the +pipeline:</p> +<pre> +<tt>wait </tt><i><pid of sleep 31></i><tt> +wait %% +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_147_18" id="tag_20_147_18"></a>RATIONALE</h4> +<blockquote> +<p>The description of <i>wait</i> does not refer to the <a href="../functions/waitpid.html"><i>waitpid</i>()</a> function from the +System Interfaces volume of POSIX.1-2024 because that would needlessly overspecify this interface. However, the wording means that +<i>wait</i> is required to wait for an explicit process when it is given an argument so that the status information of other +processes is not consumed. Historical implementations use the <a href="../functions/wait.html"><i>wait</i>()</a> function defined +in the System Interfaces volume of POSIX.1-2024 until <a href="../functions/wait.html"><i>wait</i>()</a> returns the requested +process ID or finds that the requested process does not exist. Because this means that a shell script could not reliably get the +status of all background children if a second background job was ever started before the first job finished, it is recommended that +the <i>wait</i> utility use a method such as the functionality provided by the <a href= +"../functions/waitpid.html"><i>waitpid</i>()</a> function.</p> +<p>The ability to wait for multiple <i>pid</i> operands was adopted from the KornShell.</p> +<p>This new functionality was added because it is needed to determine the exit status of any asynchronous AND-OR list accurately. +The only compatibility problem that this change creates is for a script like</p> +<pre> +<tt>while sleep 60 do + job& echo Job started $(date) as $! done +</tt></pre> +<p>which causes the shell to monitor all of the jobs started until the script terminates or runs out of memory. This would not be a +problem if the loop did not reference <tt>"$!"</tt> or if the script would occasionally <i>wait</i> for jobs it started.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_147_19" id="tag_20_147_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>A future version of this standard may add an option which takes a variable name as an option-argument, allowing <i>wait</i> to +return information about the wait status of a process in an unambiguous way.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_147_20" id="tag_20_147_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19"><i>2. Shell Command Language</i></a> , <a href= +"../utilities/kill.html#tag_20_64"><i>kill</i></a> , <a href="../utilities/sh.html#"><i>sh</i></a></p> +<p>XBD <a href="../basedefs/V1_chap03.html#tag_03_182"><i>3.182 Job ID</i></a> , <a href="../basedefs/V1_chap08.html#tag_08"><i>8. +Environment Variables</i></a></p> +<p>XSH <a href="../functions/wait.html#tag_17_658"><i>wait</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_147_21" id="tag_20_147_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_147_22" id="tag_20_147_22"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 854 is applied, adding a note to the APPLICATION USAGE section that this utility is required to be +intrinsic.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1254 is applied, updating various requirements for the <a href="../utilities/jobs.html"><i>jobs</i></a> +utility to account for the addition of <a href="../utilities/V3_chap02.html#tag_19_11"><i>2.11 Job Control</i></a> .</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/vi.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/wc.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/wc.html b/bdd/wc.html @@ -0,0 +1,239 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>wc</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/wait.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/what.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="wc" id="wc"></a> <a name="tag_20_148" id="tag_20_148"></a><!-- wc --> +<h4 class="mansect"><a name="tag_20_148_01" id="tag_20_148_01"></a>NAME</h4> +<blockquote>wc — word, line, and byte or character count</blockquote> +<h4 class="mansect"><a name="tag_20_148_02" id="tag_20_148_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>wc</tt> <b>[</b><tt>-c|-m</tt><b>] [</b><tt>-lw</tt><b>] [</b><i>file</i><tt>...</tt><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_148_03" id="tag_20_148_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>wc</i> utility shall read one or more input files and, by default, write the number of <newline> characters, words, +and bytes contained in each input file to the standard output.</p> +<p>The utility also shall write a total count for all named files, if more than one input file is specified.</p> +<p>The <i>wc</i> utility shall consider a <i>word</i> to be a non-zero-length string of characters delimited by white space.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_148_04" id="tag_20_148_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>wc</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-c</b></dt> +<dd>Write to the standard output the number of bytes in each input file.</dd> +<dt><b>-l</b></dt> +<dd>Write to the standard output the number of <newline> characters in each input file.</dd> +<dt><b>-m</b></dt> +<dd>Write to the standard output the number of characters in each input file.</dd> +<dt><b>-w</b></dt> +<dd>Write to the standard output the number of words in each input file.</dd> +</dl> +<p>When any option is specified, <i>wc</i> shall report only the information requested by the specified options.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_148_05" id="tag_20_148_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of an input file. If no <i>file</i> operands are specified, the standard input shall be used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_148_06" id="tag_20_148_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall be used if no <i>file</i> operands are specified, and shall be used if a <i>file</i> operand is +<tt>'-'</tt> and the implementation treats the <tt>'-'</tt> as meaning standard input. Otherwise, the standard input shall not be +used. See the INPUT FILES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_148_07" id="tag_20_148_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files may be of any type.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_148_08" id="tag_20_148_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>wc</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files) and which characters are defined as white-space characters.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error and +informative messages written to standard output.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_148_09" id="tag_20_148_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_148_10" id="tag_20_148_10"></a>STDOUT</h4> +<blockquote> +<p>By default, the standard output shall contain an entry for each input file of the form:</p> +<pre> +<tt>"%d %d %d %s\n", <</tt><i>newlines</i><tt>>, <</tt><i>words</i><tt>>, <</tt><i>bytes</i><tt>>, <</tt><i>file</i><tt>> +</tt></pre> +<p>If the <b>-m</b> option is specified, the number of characters shall replace the <<i>bytes</i>> field in this format.</p> +<p>If any options are specified and the <b>-l</b> option is not specified, the number of <newline> characters shall not be +written.</p> +<p>If any options are specified and the <b>-w</b> option is not specified, the number of words shall not be written.</p> +<p>If any options are specified and neither <b>-c</b> nor <b>-m</b> is specified, the number of bytes or characters shall not be +written.</p> +<p>If no input <i>file</i> operands are specified, no name shall be written and no <blank> characters preceding the pathname +shall be written.</p> +<p>If more than one input <i>file</i> operand is specified, an additional line shall be written, of the same format as the other +lines, except that the word <b>total</b> (in the POSIX locale) shall be written instead of a pathname and the total of each column +shall be written as appropriate. Such an additional line, if any, is written at the end of the output.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_148_11" id="tag_20_148_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_148_12" id="tag_20_148_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_148_13" id="tag_20_148_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_148_14" id="tag_20_148_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_148_15" id="tag_20_148_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_148_16" id="tag_20_148_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The <b>-m</b> option is not a switch, but an option at the same level as <b>-c</b>. Thus, to produce the full default output +with character counts instead of bytes, the command required is:</p> +<pre> +<tt>wc -mlw +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_148_17" id="tag_20_148_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_148_18" id="tag_20_148_18"></a>RATIONALE</h4> +<blockquote> +<p>The output file format pseudo-<a href="../functions/printf.html"><i>printf</i>()</a> string differs from the System V version of +<i>wc</i>:</p> +<pre> +<tt>"%7d%7d%7d %s\n" +</tt></pre> +<p>which produces possibly ambiguous and unparsable results for very large files, as it assumes no number shall exceed six +digits.</p> +<p>Some historical implementations use only <space>, <tab>, and <newline> as word separators. The equivalent of +the ISO C standard <a href="../functions/isspace.html"><i>isspace</i>()</a> function is more appropriate.</p> +<p>The <b>-c</b> option stands for "character" count, even though it counts bytes. This stems from the sometimes erroneous +historical view that bytes and characters are the same size. Due to international requirements, the <b>-m</b> option (reminiscent +of "multi-byte") was added to obtain actual character counts.</p> +<p>Early proposals only specified the results when input files were text files. The current specification more closely matches +historical practice. (Bytes, words, and <newline> characters are counted separately and the results are written when an +end-of-file is detected.)</p> +<p>Historical implementations of the <i>wc</i> utility only accepted one argument to specify the options <b>-c</b>, <b>-l</b>, and +<b>-w</b>. Some of them also had multiple occurrences of an option cause the corresponding count to be written multiple times and +had the order of specification of the options affect the order of the fields on output, but did not document either of these. +Because common usage either specifies no options or only one option, and because none of this was documented, the changes required +by this volume of POSIX.1-2024 should not break many historical applications (and do not break any historical conforming +applications).</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_148_19" id="tag_20_148_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_148_20" id="tag_20_148_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/cksum.html#"><i>cksum</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_148_21" id="tag_20_148_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_148_22" id="tag_20_148_22"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #092 is applied.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_148_23" id="tag_20_148_23"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to report an error if a utility is directed to display a +pathname that contains any bytes that have the encoded value of a <newline> character when <newline> is a terminator or +separator in the output format being used.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/wait.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/what.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/what.html b/bdd/what.html @@ -0,0 +1,229 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>what</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/wc.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/who.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="what" id="what"></a> <a name="tag_20_149" id="tag_20_149"></a><!-- what --> +<h4 class="mansect"><a name="tag_20_149_01" id="tag_20_149_01"></a>NAME</h4> +<blockquote>what — identify SCCS files (<b>DEVELOPMENT</b>)</blockquote> +<h4 class="mansect"><a name="tag_20_149_02" id="tag_20_149_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> what</tt> <b>[</b><tt>-s</tt><b>]</b> <i>file</i><tt>... <img src="../images/opt-end.gif" alt= +"[Option End]" border="0"></tt></code></div> +</blockquote> +<h4 class="mansect"><a name="tag_20_149_03" id="tag_20_149_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>what</i> utility shall search the given files for all occurrences of the pattern that <a href= +"../utilities/get.html"><i>get</i></a> (see <a href="../utilities/get.html#"><i>get</i></a> ) substitutes for the %<b>Z</b>% +keyword (<tt>"@(#)"</tt>). The <i>what</i> utility shall write to standard output the identification string that follows up to, but +not including, the first occurrence of one of the following: <double-quote> (<tt>'"'</tt> ), <greater-than-sign> +(<tt>'>'</tt>), <newline>, <backslash> (<tt>'\\'</tt>), <NUL> (<tt>'\0'</tt>), or an end-of-file condition on +the input file. If not at end-of-file, the <i>what</i> utility shall then look for the next occurrence of <tt>"@(#)"</tt> after one +of those characters.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_149_04" id="tag_20_149_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>what</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following option shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-s</b></dt> +<dd>Write at most one identification string for each file. After locating and writing to standard output the identification string +following the first pattern (if any) in a file, no further data shall be read from that file and the search shall recommence from +the beginning of the next file, if any.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_149_05" id="tag_20_149_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of a file to search.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_149_06" id="tag_20_149_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_149_07" id="tag_20_149_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files shall be of any file type.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_149_08" id="tag_20_149_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>what</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd>Determine the location of messages objects and message catalogs.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_149_09" id="tag_20_149_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_149_10" id="tag_20_149_10"></a>STDOUT</h4> +<blockquote> +<p>For each <i>file</i> operand, the standard output shall consist of:</p> +<pre> +<tt>"%s:\n", <</tt><i>pathname</i><tt>> +</tt></pre> +<p>followed by zero or more of:</p> +<pre> +<tt>"\t%s\n", <</tt><i>identification string</i><tt>> +</tt></pre> +<p>one for each identification string located.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_149_11" id="tag_20_149_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_149_12" id="tag_20_149_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_149_13" id="tag_20_149_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_149_14" id="tag_20_149_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt>0</dt> +<dd>One or more matches were found and the output specified in STDOUT was successfully written to standard output.</dd> +<dt>1</dt> +<dd>No matches were found or an error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_149_15" id="tag_20_149_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_149_16" id="tag_20_149_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The <i>what</i> utility is intended to be used in conjunction with the SCCS command <a href= +"../utilities/get.html"><i>get</i></a>, which automatically inserts identifying information, but it can also be used where the +information is inserted by any other means.</p> +<p>When the string <tt>"@(#)"</tt> is included in a library routine in a shared library, it might not be found in an <b>a.out</b> +file using that library routine.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_149_17" id="tag_20_149_17"></a>EXAMPLES</h4> +<blockquote> +<p>If the C-language program in file <b>f.c</b> contains:</p> +<pre> +<tt>char ident[] = "@(#)identification information"; +</tt></pre> +<p>and <b>f.c</b> is compiled to yield <b>f.o</b> and <b>a.out</b>, then the command:</p> +<pre> +<tt>what f.c f.o a.out +</tt></pre> +<p>writes:</p> +<pre> +<tt>f.c: + identification information + ... +f.o: + identification information + ... +a.out: + identification information + ... +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_149_18" id="tag_20_149_18"></a>RATIONALE</h4> +<blockquote> +<p>This standard requires that when the <b>-s</b> option is used, <i>what</i> does not continue reading from the current file after +writing the first identification string. This might seem an unimportant detail, but applications would experience different +behavior if a <i>file</i> operand named a FIFO special file and <i>what</i> waited for an end-of-file condition rather than closing +the file straight away.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_149_19" id="tag_20_149_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline> +character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to +treat this as an error. A future version of this standard may require implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_149_20" id="tag_20_149_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/get.html#"><i>get</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_149_21" id="tag_20_149_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_149_22" id="tag_20_149_22"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to report an error if a utility is directed to display a +pathname that contains any bytes that have the encoded value of a <newline> character when <newline> is a terminator or +separator in the output format being used.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1512 is applied, changing the EXIT STATUS section.</p> +<p>Austin Group Defect 1538 is applied, clarifying the <b>-s</b> option.</p> +<p>Austin Group Defect 1563 is applied, clarifying the output format when the <i>what</i> utility finds multiple identification +strings in one file.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/wc.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/who.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/who.html b/bdd/who.html @@ -0,0 +1,317 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>who</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/what.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/write.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="who" id="who"></a> <a name="tag_20_150" id="tag_20_150"></a><!-- who --> +<h4 class="mansect"><a name="tag_20_150_01" id="tag_20_150_01"></a>NAME</h4> +<blockquote>who — display who is on the system</blockquote> +<h4 class="mansect"><a name="tag_20_150_02" id="tag_20_150_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> who</tt> <b>[</b><tt>-mTu</tt><b>] <img src= +"../images/opt-start.gif" border="0">[</b><tt>-abdHlprt</tt><b>] [</b><i>file</i><b>]</b><tt><img src="../images/opt-end.gif" +border="0"><br> +<br></tt></code></p> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> who</tt> <b>[</b><tt>-mu</tt><b>]</b> <tt>-s</tt> <b>[</b><tt>-bHlprt</tt><b>] +[</b><i>file</i><b>]</b> <tt><br> +<br> +who -q</tt> <b>[</b><i>file</i><b>]</b> <tt><br> +<br> +who am i<br> +<br> +who am I <img src="../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div> +<tt><br></tt></blockquote> +<h4 class="mansect"><a name="tag_20_150_03" id="tag_20_150_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>who</i> utility shall list various pieces of information about accessible users. The domain of accessibility is +implementation-defined.</p> +<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Based on the options given, <i>who</i> can also list the user's name, terminal line, login time, elapsed time since activity +occurred on the line, and the process ID of the command interpreter for each current system user. <img src="../images/opt-end.gif" +alt="[Option End]" border="0"></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_150_04" id="tag_20_150_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>who</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported. The metavariables, such as <<i>line</i>>, refer to fields described in the +STDOUT section.</p> +<dl compact> +<dd></dd> +<dt><b>-a</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Process the implementation-defined database or named file with the <b>-b</b>, <b>-d</b>, <b>-l</b>, <b>-p</b>, <b>-r</b>, +<b>-t</b>, <b>-T</b> and <b>-u</b> options turned on. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-b</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Write the time and date of the last system reboot. The system reboot time is the time at which the implementation is able to +commence running processes. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-d</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Write a list of all processes that have expired and not been respawned by the <i>init</i> system process. The <<i>exit</i>> +field shall appear for dead processes and contain the termination and exit values of the dead process. This can be useful in +determining why a process terminated. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-H</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Write column headings above the regular output. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-l</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +(The letter ell.) List only those lines on which the system is waiting for someone to login. The <<i>name</i>> field shall be +<b>LOGIN</b> in such cases. Other fields shall be the same as for user entries except that the <<i>state</i>> field does not +exist. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-m</b></dt> +<dd>Output only information about the current terminal.</dd> +<dt><b>-p</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +List any other process that is currently active and has been previously spawned by <i>init</i>. <img src="../images/opt-end.gif" +alt="[Option End]" border="0"></dd> +<dt><b>-q</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +(Quick.) List only the names and the number of users currently logged on. When this option is used, all other options shall be +ignored. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-r</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Write the current <i>run-level</i> of the <i>init</i> process. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-s</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +List only the <<i>name</i>>, <<i>line</i>>, and <<i>time</i>> fields. This is the default case. <img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-t</b></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Indicate the last change to the system clock. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-T</b></dt> +<dd>Show the state of each terminal, as described in the STDOUT section.</dd> +<dt><b>-u</b></dt> +<dd>Write "idle time" for each displayed user in addition to any other information. The idle time is the time since any activity +occurred on the user's terminal. The method of determining this is unspecified. <sup>[<a href= +"javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> This option +shall list only those users who are currently logged in. The <<i>name</i>> is the user's login name. The <<i>line</i>> +is the name of the line as found in the directory <b>/dev</b>. The <<i>time</i>> is the time that the user logged in. The +<<i>activity</i>> is the number of hours and minutes since activity last occurred on that particular line. A dot indicates +that the terminal has seen activity in the last minute and is therefore "current". If more than twenty-four hours have elapsed or +the line has not been used since boot time, the entry shall be marked <<i>old</i>>. This field is useful when trying to +determine whether a person is working at the terminal or not. The <<i>pid</i>> is the process ID of the user's login process. +<img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_150_05" id="tag_20_150_05"></a>OPERANDS</h4> +<blockquote> +<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>am i</b>, <b>am I</b></dt> +<dd>In the POSIX locale, limit the output to describing the invoking user, equivalent to the <b>-m</b> option. The <b>am</b> and +<b>i</b> or <b>I</b> need to be separate arguments.</dd> +<dt><i>file</i></dt> +<dd>Specify a pathname of a file to substitute for the implementation-defined database of logged-on users that <i>who</i> uses by +default. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_150_06" id="tag_20_150_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_150_07" id="tag_20_150_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_150_08" id="tag_20_150_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>who</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>LC_TIME</i></dt> +<dd>Determine the locale used for the format and contents of the date and time strings.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>TZ</i></dt> +<dd>Determine the timezone used when writing date and time information. If <i>TZ</i> is unset or null, an unspecified default +timezone shall be used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_150_09" id="tag_20_150_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_150_10" id="tag_20_150_10"></a>STDOUT</h4> +<blockquote> +<p>The <i>who</i> utility shall write its default format to the standard output in an implementation-defined format, subject only +to the requirement of containing the information described above.</p> +<p><sup>[<a href="javascript:open_code('XSI%20OF')">XSI OF</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" +border="0"> XSI-conformant systems shall write the default information to the standard output in the following general format:</p> +<pre> +<tt><</tt><i>name</i><tt>></tt><b>[</b><tt><</tt><i>state</i><tt>></tt><b>]</b><tt><</tt><i>line</i><tt>><</tt><i>time</i><tt>></tt><b>[</b><tt><</tt><i>activity</i><tt>></tt><b>][</b><tt><</tt><i>pid</i><tt>></tt><b>][</b><tt><</tt><i>comment</i><tt>></tt><b>][</b><tt><</tt><i>exit</i><tt>></tt><b>]</b><tt> +</tt></pre> +<p>For the <b>-b</b> option, <<i>line</i>> shall be <tt>"system boot"</tt>. The <<i>name</i>> is unspecified. <img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></p> +<p>The following format shall be used for the <b>-T</b> option:</p> +<pre> +<tt>"%s %c %s %s\n" <</tt><i>name</i><tt>>, <</tt><i>terminal state</i><tt>>, <</tt><i>terminal name</i><tt>>, + <</tt><i>time of login</i><tt>> +</tt></pre> +<p>where <<i>terminal state</i>> is one of the following characters:</p> +<dl compact> +<dd></dd> +<dt><tt>+</tt></dt> +<dd>The terminal allows write access to other users.</dd> +<dt><tt>-</tt></dt> +<dd>The terminal denies write access to other users.</dd> +<dt><tt>?</tt></dt> +<dd>The terminal write-access state cannot be determined.</dd> +<dt><tt><space></tt></dt> +<dd>This entry is not associated with a terminal.</dd> +</dl> +<p>In the POSIX locale, the <<i>time of login</i>> shall be equivalent in format to the output of:</p> +<pre> +<tt>date +"%b %e %H:%M" +</tt></pre> +<p>If the <b>-u</b> option is used with <b>-T</b>, the idle time shall be added to the end of the previous format in an unspecified +format.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_150_11" id="tag_20_150_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_150_12" id="tag_20_150_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_150_13" id="tag_20_150_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_150_14" id="tag_20_150_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_150_15" id="tag_20_150_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_150_16" id="tag_20_150_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The name <i>init</i> used for the system process is the most commonly used on historical systems, but it may vary.</p> +<p>The "domain of accessibility" referred to is a broad concept that permits interpretation either on a very secure basis or even +to allow a network-wide implementation like the historical <i>rwho</i>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_150_17" id="tag_20_150_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_150_18" id="tag_20_150_18"></a>RATIONALE</h4> +<blockquote> +<p>Due to differences between historical implementations, the base options provided were a compromise to allow users to work with +those functions. The standard developers also considered removing all the options, but felt that these options offered users +valuable functionality. Additional options to match historical systems are available on XSI-conformant systems.</p> +<p>It is recognized that the <i>who</i> command may be of limited usefulness, especially in a multi-level secure environment. The +standard developers considered, however, that having some standard method of determining the "accessibility" of other users would +aid user portability.</p> +<p>No format was specified for the default <i>who</i> output for systems not supporting the XSI option. In such a user-oriented +command, designed only for human use, this was not considered to be a deficiency.</p> +<p>The format of the terminal name is unspecified, but the descriptions of <a href="../utilities/ps.html"><i>ps</i></a>, <a href= +"../utilities/talk.html"><i>talk</i></a>, and <a href="../utilities/write.html"><i>write</i></a> require that they use the same +format.</p> +<p>It is acceptable for an implementation to produce no output for an invocation of <i>who</i> <b>mil</b>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_150_19" id="tag_20_150_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_150_20" id="tag_20_150_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/mesg.html#"><i>mesg</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_150_21" id="tag_20_150_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_150_22" id="tag_20_150_22"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +<p>The <i>TZ</i> entry is added to the ENVIRONMENT VARIABLES section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_150_23" id="tag_20_150_23"></a>Issue 7</h4> +<blockquote> +<p>SD5-XCU-ERN-58 is applied, clarifying the <b>-b</b> option.</p> +<p>The <i>who</i> utility is moved from the User Portability Utilities option to the Base. User Portability Utilities is now an +option for interactive utilities.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_150_24" id="tag_20_150_24"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/what.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/write.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/write.html b/bdd/write.html @@ -0,0 +1,248 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>write</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/who.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/xargs.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="write" id="write"></a> <a name="tag_20_151" id="tag_20_151"></a><!-- write --> +<h4 class="mansect"><a name="tag_20_151_01" id="tag_20_151_01"></a>NAME</h4> +<blockquote>write — write to another user</blockquote> +<h4 class="mansect"><a name="tag_20_151_02" id="tag_20_151_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt>write</tt> <i>user_name</i> <b>[</b><i>terminal</i><b>]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_151_03" id="tag_20_151_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>write</i> utility shall read lines from the standard input and write them to the terminal of the specified user. When +first invoked, it shall write the message:</p> +<pre> +<b>Message from </b><i>sender-login-id</i><tt> (</tt><i>sending-terminal</i><tt>) </tt><b>[</b><i>date</i><b>]</b><tt>... +</tt></pre> +<p>to <i>user_name</i>. When it has successfully completed the connection, the sender's terminal shall be alerted twice to indicate +that what the sender is typing is being written to the recipient's terminal.</p> +<p>If the recipient wants to reply, this can be accomplished by typing:</p> +<pre> +<tt>write </tt><i>sender-login-id </i><b>[</b><i>sending-terminal</i><b>]</b><tt> +</tt></pre> +<p>upon receipt of the initial message. Whenever a line of input as delimited by an NL, EOF, or EOL special character (see XBD +<a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> ) is accumulated while in canonical input +mode, the accumulated data shall be written on the other user's terminal. Characters shall be processed as follows:</p> +<ul> +<li> +<p>Typing <alert> shall write the <alert> character to the recipient's terminal.</p> +</li> +<li> +<p>Typing the erase and kill characters shall affect the sender's terminal in the manner described by the <b>termios</b> interface +in XBD <a href="../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a> .</p> +</li> +<li> +<p>Typing the interrupt or end-of-file characters shall cause <i>write</i> to write an appropriate message (<tt>"EOT\n"</tt> in the +POSIX locale) to the recipient's terminal and exit.</p> +</li> +<li> +<p>Typing characters from <i>LC_CTYPE</i> classifications <b>print</b> or <b>space</b> shall cause those characters to be sent to +the recipient's terminal.</p> +</li> +<li> +<p>When and only when the <a href="../utilities/stty.html"><i>stty</i></a> <b>iexten</b> local mode is enabled, the existence and +processing of additional special control characters and multi-byte or single-byte functions is implementation-defined.</p> +</li> +<li> +<p>Typing other non-printable characters shall cause implementation-defined sequences of printable characters to be written to the +recipient's terminal.</p> +</li> +</ul> +<p>To write to a user who is logged in more than once, the <i>terminal</i> argument can be used to indicate which terminal to write +to; otherwise, the recipient's terminal is selected in an implementation-defined manner and an informational message is written to +the sender's standard output, indicating which terminal was chosen.</p> +<p>Permission to be a recipient of a <i>write</i> message can be denied or granted by use of the <a href= +"../utilities/mesg.html"><i>mesg</i></a> utility. However, a user's privilege may further constrain the domain of accessibility of +other users' terminals. The <i>write</i> utility shall fail when the user lacks appropriate privileges to perform the requested +action.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_151_04" id="tag_20_151_04"></a>OPTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_151_05" id="tag_20_151_05"></a>OPERANDS</h4> +<blockquote> +<p><br> +The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>user_name</i></dt> +<dd>Login name of the person to whom the message shall be written. The application shall ensure that this operand is of the form +returned by the <a href="../utilities/who.html"><i>who</i></a> utility.</dd> +<dt><i>terminal</i></dt> +<dd>Terminal identification in the same format provided by the <a href="../utilities/who.html"><i>who</i></a> utility.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_151_06" id="tag_20_151_06"></a>STDIN</h4> +<blockquote> +<p>Lines to be copied to the recipient's terminal are read from standard input.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_151_07" id="tag_20_151_07"></a>INPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_151_08" id="tag_20_151_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>write</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). If the recipient's locale does not use an <i>LC_CTYPE</i> +equivalent to the sender's, the results are undefined.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error and +informative messages written to standard output.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_151_09" id="tag_20_151_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>If an interrupt signal is received, <i>write</i> shall write an appropriate message on the recipient's terminal and exit with a +status of zero. It shall take the standard action for all other signals.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_151_10" id="tag_20_151_10"></a>STDOUT</h4> +<blockquote> +<p>An informational message shall be written to standard output if a recipient is logged in more than once.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_151_11" id="tag_20_151_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used only for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_151_12" id="tag_20_151_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>The recipient's terminal is used for output.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_151_13" id="tag_20_151_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_151_14" id="tag_20_151_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>The addressed user is not logged on or the addressed user denies permission.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_151_15" id="tag_20_151_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_151_16" id="tag_20_151_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The <a href="../utilities/talk.html"><i>talk</i></a> utility is considered by some users to be a more usable utility on +full-screen terminals.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_151_17" id="tag_20_151_17"></a>EXAMPLES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_151_18" id="tag_20_151_18"></a>RATIONALE</h4> +<blockquote> +<p>The <i>write</i> utility was included in this volume of POSIX.1-2024 since it can be implemented on all terminal types. The +standard developers considered the <a href="../utilities/talk.html"><i>talk</i></a> utility, which cannot be implemented on certain +terminals, to be a "better" communications interface. Both of these programs are in widespread use on historical implementations. +Therefore, the standard developers decided that both utilities should be specified.</p> +<p>The format of the terminal name is unspecified, but the descriptions of <a href="../utilities/ps.html"><i>ps</i></a>, <a href= +"../utilities/talk.html"><i>talk</i></a>, <a href="../utilities/who.html"><i>who</i></a>, and <i>write</i> require that they all +use or accept the same format.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_151_19" id="tag_20_151_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_151_20" id="tag_20_151_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/mesg.html#"><i>mesg</i></a> , <a href="../utilities/talk.html#"><i>talk</i></a> , <a href= +"../utilities/who.html#"><i>who</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap11.html#tag_11"><i>11. General Terminal Interface</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_151_21" id="tag_20_151_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_151_22" id="tag_20_151_22"></a>Issue 5</h4> +<blockquote> +<p>The FUTURE DIRECTIONS section is added.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_151_23" id="tag_20_151_23"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the User Portability Utilities option.</p> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_151_24" id="tag_20_151_24"></a>Issue 7</h4> +<blockquote> +<p>The <i>write</i> utility is moved from the User Portability Utilities option to the Base. User Portability Utilities is now an +option for interactive utilities.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_151_25" id="tag_20_151_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/who.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/xargs.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/xargs.html b/bdd/xargs.html @@ -0,0 +1,479 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>xargs</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/write.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/xgettext.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="xargs" id="xargs"></a> <a name="tag_20_152" id="tag_20_152"></a><!-- xargs --> +<h4 class="mansect"><a name="tag_20_152_01" id="tag_20_152_01"></a>NAME</h4> +<blockquote>xargs — construct argument lists and invoke utility</blockquote> +<h4 class="mansect"><a name="tag_20_152_02" id="tag_20_152_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<p><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> xargs</tt> <b>[</b><tt>-prtx</tt><b>] [</b><tt>-E</tt> +<i>eofstr</i><tt>|-0</tt><b>] [<img src="../images/opt-start.gif" border="0"></b><tt>-I</tt> <i>replstr</i><tt>|-L</tt> +<i>number</i><tt><img src="../images/opt-end.gif" border="0">|-n</tt> <i>number</i><b>]</b> <tt><br> + </tt> <b>[</b><tt>-s</tt> <i>size</i><b>] [</b><i>utility</i> +<b>[</b><i>argument</i><tt>...</tt><b>]]</b></code></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_152_03" id="tag_20_152_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>xargs</i> utility shall construct a command line consisting of the <i>utility</i> and <i>argument</i> operands specified +followed by as many arguments read in sequence from standard input as fit in length and number constraints specified by the +options. The <i>xargs</i> utility shall then invoke the constructed command line and wait for its completion. This sequence shall +be repeated until one of the following occurs:</p> +<ul> +<li> +<p>An end-of-file condition is detected on standard input.</p> +</li> +<li> +<p>An argument consisting of just the logical end-of-file string (see the <b>-E</b> <i>eofstr</i> option) is found on standard +input after double-quote processing, <apostrophe> processing, and <backslash>-escape processing (see next paragraph). +All arguments up to but not including the argument consisting of just the logical end-of-file string shall be used as arguments in +constructed command lines.</p> +</li> +<li> +<p>An invocation of a constructed command line returns an exit status of 255.</p> +</li> +</ul> +<p>If the <b>-0</b> option is not specified, the application shall ensure that arguments in the standard input are delimited by +unquoted <blank> characters, unescaped <blank> characters, or <newline> characters, and quoting characters shall +be interpreted as follows:</p> +<ul> +<li> +<p>A string of zero or more non-double-quote (<tt>'"'</tt> ) non-<newline> characters can be quoted by enclosing them in +double-quotes.</p> +</li> +<li> +<p>A string of zero or more non-<apostrophe> (<tt>'\''</tt>) non-<newline> characters can be quoted by enclosing them +in <apostrophe> characters.</p> +</li> +<li> +<p>Any unquoted character can be escaped by preceding it with a <backslash>.</p> +</li> +</ul> +<p>Multiple adjacent delimiter characters shall be treated as a single delimiter. If the standard input is not empty and does not +end with a <newline>, the behavior is undefined (because the requirement in STDIN that the input is a text file is not met in +that case).</p> +<p>If the <b>-0</b> option is specified, the application shall ensure that arguments in the standard input are delimited by null +bytes. If multiple adjacent null bytes occur in the input, each null byte shall be treated as a delimiter. If the standard input is +not empty and does not end with a null byte, <i>xargs</i> should ignore the trailing non-null bytes (as this can signal incomplete +data) but may use them as the last argument passed to utility.</p> +<p>The utility named by <i>utility</i> shall be executed zero or more times until the end-of-file is reached or the logical end-of +file string is found. If no arguments are supplied on standard input, the utility named by <i>utility</i> shall be executed zero +times if the <b>-r</b> option is specified and shall be executed exactly once if the <b>-r</b> option is not specified. The results +are unspecified if the utility named by <i>utility</i> attempts to read from its standard input.</p> +<p>The generated command line length shall be the sum of the size in bytes of the utility name and each argument treated as +strings, including a null byte terminator for each of these strings. The <i>xargs</i> utility shall limit the command line length +such that when the command line is invoked, the combined argument and environment lists (see the <i>exec</i> family of functions in +the System Interfaces volume of POSIX.1-2024) shall not exceed {ARG_MAX}-2048 bytes. Within this constraint, if neither the +<b>-n</b> nor the <b>-s</b> option is specified, the default command line length shall be at least {LINE_MAX}.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_152_04" id="tag_20_152_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>xargs</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-E </b><i>eofstr</i></dt> +<dd>Use <i>eofstr</i> as the logical end-of-file string. If neither <b>-E</b> nor <b>-0</b> is specified, it is unspecified whether +the logical end-of-file string is the <underscore> character (<tt>'_'</tt>) or the end-of-file string capability is disabled. +When <i>eofstr</i> is the null string, the logical end-of-file string capability shall be disabled and <underscore> +characters shall be taken literally.</dd> +<dt><b>-I </b><i>replstr</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Insert mode: invoke <i>utility</i> for each argument from standard input. If <b>-0</b> is not specified, arguments in the standard +input shall be delimited only by unescaped <newline> characters, not by <blank> characters, and any unquoted unescaped +<blank> characters at the beginning of each line shall be ignored. The resulting argument shall be inserted in +<i>arguments</i> in place of each occurrence of <i>replstr</i>. At least five arguments in <i>arguments</i> can each contain one or +more instances of <i>replstr</i>. Each of these constructed arguments cannot grow larger than an implementation-defined limit +greater than or equal to 255 bytes. Option <b>-x</b> shall be forced on. <img src="../images/opt-end.gif" alt="[Option End]" +border="0"></dd> +<dt><b>-L </b><i>number</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Invoke <i>utility</i> for each set of <i>number</i> arguments from standard input. The last invocation of <i>utility</i> shall be +with fewer arguments if fewer than <i>number</i> remain. If the <b>-0</b> option is not specified, each line in the standard input +shall be treated as containing one argument except that empty lines shall be ignored and a line ending with a trailing unescaped +<blank> shall signal continuation to the next non-empty line, inclusive; such continuation shall result in removal of all +trailing unescaped <blank> characters and all <newline> characters that immediately follow them from the argument. +<img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><b>-n </b><i>number</i></dt> +<dd>Invoke <i>utility</i> using as many standard input arguments as possible, up to <i>number</i> (a positive decimal integer) +arguments maximum. Fewer arguments shall be used if: +<ul> +<li> +<p>The command line length accumulated exceeds the size specified by the <b>-s</b> option (or {LINE_MAX} if there is no <b>-s</b> +option).</p> +</li> +<li> +<p>The last iteration has fewer than <i>number</i>, but not zero, operands remaining.</p> +</li> +</ul> +</dd> +<dt><b>-p</b></dt> +<dd>Prompt mode: the user is asked whether to execute <i>utility</i> at each invocation. Trace mode (<b>-t</b>) is turned on to +write the command instance to be executed, followed by a prompt to standard error. An affirmative response read from +<b>/dev/tty</b> shall execute the command; otherwise, that particular invocation of <i>utility</i> shall be skipped.</dd> +<dt><b>-r</b></dt> +<dd>Do not execute the utility named by <i>utility</i> if no arguments are supplied on standard input.</dd> +<dt><b>-s </b><i>size</i></dt> +<dd>Invoke <i>utility</i> using as many standard input arguments as possible yielding a command line length less than <i>size</i> +(a positive decimal integer) bytes. Fewer arguments shall be used if: +<ul> +<li> +<p>The total number of arguments exceeds that specified by the <b>-n</b> option.</p> +</li> +<li> +<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +The total number of arguments exceeds that specified by the <b>-L</b> option. <img src="../images/opt-end.gif" alt="[Option End]" +border="0"></p> +</li> +<li> +<p>End-of-file is encountered on standard input before <i>size</i> bytes are accumulated.</p> +</li> +</ul> +<p>Values of <i>size</i> up to at least {LINE_MAX} bytes shall be supported, provided that the constraints specified in the +DESCRIPTION are met. It shall not be considered an error if a value larger than that supported by the implementation or exceeding +the constraints specified in the DESCRIPTION is given; <i>xargs</i> shall use the largest value it supports within the +constraints.</p> +</dd> +<dt><b>-t</b></dt> +<dd>Enable trace mode. Each generated command line shall be written to standard error just prior to invocation.</dd> +<dt><b>-x</b></dt> +<dd>Terminate if a constructed command line will not fit in the implied or specified size (see the <b>-s</b> option above).</dd> +<dt><b>-0</b></dt> +<dd>Use a null byte as the input argument delimiter and do not treat any other input bytes as special.</dd> +</dl> +<p>If the mutually exclusive <b>-0</b> and <b>-E</b> <i>eofstr</i> options are both specified, the behavior is unspecified, except +that if <i>eofstr</i> is the null string the behavior shall be the same as if <b>-0</b> was specified without <b>-E</b> +<i>eofstr</i>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_152_05" id="tag_20_152_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operands shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>utility</i></dt> +<dd>The name of the utility to be invoked, found by search path using the <i>PATH</i> environment variable, described in XBD +<a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> . If <i>utility</i> is omitted, the default shall +be the <a href="../utilities/echo.html"><i>echo</i></a> utility. If the <i>utility</i> operand names any of the special built-in +utilities in <a href="../utilities/V3_chap02.html#tag_19_15"><i>2.15 Special Built-In Utilities</i></a> , the results are +undefined.</dd> +<dt><i>argument</i></dt> +<dd>An initial option or operand for the invocation of <i>utility</i>.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_152_06" id="tag_20_152_06"></a>STDIN</h4> +<blockquote> +<p>If the <b>-0</b> option is not specified, the standard input shall be a text file and the results are unspecified if an +end-of-file condition is detected immediately following an escaped <newline>.</p> +<p>If the <b>-0</b> option is specified, the standard input need not be a text file, and <i>xargs</i> shall process the input as +bytes, not characters.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_152_07" id="tag_20_152_07"></a>INPUT FILES</h4> +<blockquote> +<p>The file <b>/dev/tty</b> shall be used to read responses required by the <b>-p</b> option.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_152_08" id="tag_20_152_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>xargs</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_COLLATE</i></dt> +<dd><br> +Determine the locale for the behavior of ranges, equivalence classes, and multi-character collating elements used in the extended +regular expression defined for the <b>yesexpr</b> locale keyword in the <i>LC_MESSAGES</i> category.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files) and the behavior of character classes used in the extended regular +expression defined for the <b>yesexpr</b> locale keyword in the <i>LC_MESSAGES</i> category.</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale used to process affirmative responses, and the locale used to affect the format and contents of diagnostic +messages and prompts written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +<dt><i>PATH</i></dt> +<dd>Determine the location of <i>utility</i>, as described in XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment +Variables</i></a> .</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_152_09" id="tag_20_152_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_152_10" id="tag_20_152_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_152_11" id="tag_20_152_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used for diagnostic messages and the <b>-t</b> and <b>-p</b> options. If the <b>-t</b> option is +specified, the <i>utility</i> and its constructed argument list shall be written to standard error, as it will be invoked, prior to +invocation. If <b>-p</b> is specified, a prompt of the following format shall be written (in the POSIX locale):</p> +<pre> +<tt>"?..." +</tt></pre> +<p>at the end of the line of the output from <b>-t</b>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_152_12" id="tag_20_152_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_152_13" id="tag_20_152_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_152_14" id="tag_20_152_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>1-125</dt> +<dd>A command line meeting the specified requirements could not be assembled, one or more of the invocations of <i>utility</i> +returned a non-zero exit status, or some other error occurred.</dd> +<dt> 126</dt> +<dd>The utility specified by <i>utility</i> was found but could not be invoked.</dd> +<dt> 127</dt> +<dd>The utility specified by <i>utility</i> could not be found.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_152_15" id="tag_20_152_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>If a command line meeting the specified requirements cannot be assembled, the utility cannot be invoked, an invocation of the +utility is terminated by a signal, or an invocation of the utility exits with exit status 255, the <i>xargs</i> utility shall write +a diagnostic message and exit without processing any remaining input.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_152_16" id="tag_20_152_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>The 255 exit status allows a utility being used by <i>xargs</i> to tell <i>xargs</i> to terminate if it knows no further +invocations using the current data stream will succeed. Thus, <i>utility</i> should explicitly <a href= +"../utilities/V3_chap02.html#exit"><i>exit</i></a> with an appropriate value to avoid accidentally returning with 255.</p> +<p>Note that since input is parsed as lines (if <b>-0</b> is not specified), with <blank> characters separating arguments and +<backslash>, <apostrophe>, and double-quote characters used for quoting, if <i>xargs</i> is used to bundle the output +of commands like <a href="../utilities/find.html"><i>find</i></a> <i>dir</i> <b>-print</b> or <a href= +"../utilities/ls.html"><i>ls</i></a> into commands to be executed, unexpected results are likely if any filenames contain +<blank>, <newline>, or quoting characters. This can be solved by using the <b>-print0</b> primary of <a href= +"../utilities/find.html"><i>find</i></a> together with the <i>xargs</i> <b>-0</b> option, or by using <a href= +"../utilities/find.html"><i>find</i></a> to call a script that converts each file found into a quoted string that is then piped to +<i>xargs</i>, but in most cases it is preferable just to have <a href="../utilities/find.html"><i>find</i></a> do the argument +aggregation itself by using <b>-exec</b> with a <tt>'+'</tt> terminator instead of <tt>';'</tt>. Note that the quoting rules used +by <i>xargs</i> are not the same as in the shell. They were not made consistent here because existing applications depend on the +current rules. An easy (but inefficient) method that can be used to transform input consisting of one argument per line into a +quoted form that <i>xargs</i> interprets correctly is to precede each non-<newline> character with a <backslash>. More +efficient alternatives are shown in Example 2 and Example 5 below.</p> +<p>On implementations with a large value for {ARG_MAX}, <i>xargs</i> may produce command lines longer than {LINE_MAX}. For +invocation of utilities, this is not a problem. If <i>xargs</i> is being used to create a text file, users should explicitly set +the maximum command line length with the <b>-s</b> option.</p> +<p>The <a href="../utilities/command.html"><i>command</i></a>, <a href="../utilities/env.html"><i>env</i></a>, <a href= +"../utilities/nice.html"><i>nice</i></a>, <a href="../utilities/nohup.html"><i>nohup</i></a>, <a href= +"../utilities/time.html"><i>time</i></a>, <a href="../utilities/timeout.html"><i>timeout</i></a>, and <i>xargs</i> utilities have +been specified to use exit code 127 if a utility to be invoked cannot be found, so that applications can distinguish "failure to +find a utility" from "invoked utility exited with an error indication". The value 127 was chosen because it is not commonly used +for other meanings; most utilities use small values for "normal error conditions" and the values above 128 can be confused with +termination due to receipt of a signal. The value 126 was chosen in a similar manner to indicate that the utility could be found, +but not invoked. Some scripts produce meaningful error messages differentiating the 126 and 127 cases. The distinction between exit +codes 126 and 127 is based on KornShell practice that uses 127 when all attempts to <i>exec</i> the utility fail with [ENOENT], and +uses 126 when any attempt to <i>exec</i> the utility fails for any other reason.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_152_17" id="tag_20_152_17"></a>EXAMPLES</h4> +<blockquote> +<ol> +<li> +<p>The following command combines the output of the parenthesized commands (minus the <apostrophe> characters) onto one line, +which is then appended to the file log. It assumes that the expansion of <tt>"$0 $*"</tt> does not include any <apostrophe> +or <newline> characters.</p> +<pre> +<tt>(logname; date; printf "'%s'\n" "$0 $*") | xargs -E "" >>log +</tt></pre></li> +<li> +<p>The following command invokes <a href="../utilities/diff.html"><i>diff</i></a> with successive pairs of arguments originally +typed as command line arguments.</p> +<pre> +<tt>printf "%s\0" "$@" | xargs -0 -n 2 -x diff -- +</tt></pre></li> +<li> +<p>In the following command, the user is asked which regular files below the current directory are to be archived.</p> +<pre> +<tt>find . -type f -print0 | xargs -0 -p -L 1 ar -r arch +</tt></pre></li> +<li> +<p>The following command invokes <i>command1</i> one or more times with multiple arguments, stopping if an invocation of +<i>command1</i> has a non-zero exit status.</p> +<pre> +<tt>xargs -E "" sh -c 'command1 "$@" || exit 255' sh < xargs_input +</tt></pre></li> +</ol> +</blockquote> +<h4 class="mansect"><a name="tag_20_152_18" id="tag_20_152_18"></a>RATIONALE</h4> +<blockquote> +<p>The <i>xargs</i> utility was usually found only in System V-based systems; BSD systems included an <i>apply</i> utility that +provided functionality similar to <i>xargs</i> <b>-n</b> <i>number</i>. The SVID lists <i>xargs</i> as a software development +extension. This volume of POSIX.1-2024 does not share the view that it is used only for development, and therefore it is not +optional.</p> +<p>The classic application of the <i>xargs</i> utility is in conjunction with the <a href="../utilities/find.html"><i>find</i></a> +utility to reduce the number of processes launched by a simplistic use of the <a href="../utilities/find.html"><i>find</i></a> +<b>-exec</b> combination. The <i>xargs</i> utility is also used to enforce an upper limit on memory required to launch a process. +With this basis in mind, this volume of POSIX.1-2024 selected only the minimal features required.</p> +<p>Although the 255 exit status is mostly an accident of historical implementations, it allows a utility being used by <i>xargs</i> +to tell <i>xargs</i> to terminate if it knows no further invocations using the current data stream shall succeed. Any non-zero exit +status from a utility falls into the 1-125 range when <i>xargs</i> exits. There is no statement of how the various non-zero utility +exit status codes are accumulated by <i>xargs</i>. The value could be the addition of all codes, their highest value, the last one +received, or a single value such as 1. Since no algorithm is arguably better than the others, and since many of the standard +utilities say little more (portably) than "pass/fail", no new algorithm was invented.</p> +<p>Several other <i>xargs</i> options were removed because simple alternatives already exist within this volume of POSIX.1-2024. +For example, the <b>-i</b> <i>replstr</i> option can be just as efficiently performed using a shell <b>for</b> loop. Since +<i>xargs</i> calls an <i>exec</i> function with each input line, the <b>-i</b> option does not usually exploit the grouping +capabilities of <i>xargs</i>.</p> +<p>The requirement that <i>xargs</i> never produces command lines such that invocation of <i>utility</i> is within 2048 bytes of +hitting the POSIX <i>exec</i> {ARG_MAX} limitations is intended to guarantee that the invoked utility has room to modify its +environment variables and command line arguments and still be able to invoke another utility. Note that the minimum {ARG_MAX} +allowed by the System Interfaces volume of POSIX.1-2024 is 4096 bytes and the minimum value allowed by this volume of POSIX.1-2024 +is 2048 bytes; therefore, the 2048 bytes difference seems reasonable. Note, however, that <i>xargs</i> may never be able to invoke +a utility if the environment passed in to <i>xargs</i> comes close to using {ARG_MAX} bytes.</p> +<p>The version of <i>xargs</i> required by this volume of POSIX.1-2024 is required to wait for the completion of the invoked +command before invoking another command. This was done because historical scripts using <i>xargs</i> assumed sequential execution. +Implementations wanting to provide parallel operation of the invoked utilities are encouraged to add an option enabling parallel +invocation, but should still wait for termination of all of the children before <i>xargs</i> terminates normally.</p> +<p>The <b>-e</b> option was omitted from the ISO POSIX-2:1993 standard in the belief that the <i>eofstr</i> option-argument +was recognized only when it was on a line by itself and before quote and escape processing were performed, and that the logical +end-of-file processing was only enabled if a <b>-e</b> option was specified. In that case, a simple <a href= +"../utilities/sed.html"><i>sed</i></a> script could be used to duplicate the <b>-e</b> functionality. Further investigation +revealed that:</p> +<ul> +<li> +<p>The logical end-of-file string was checked for after quote and escape processing, making a <a href= +"../utilities/sed.html"><i>sed</i></a> script that provided equivalent functionality much more difficult to write.</p> +</li> +<li> +<p>The default was to perform logical end-of-file processing with an <underscore> as the logical end-of-file string.</p> +</li> +</ul> +<p>To correct this misunderstanding, the <b>-E</b> <i>eofstr</i> option was adopted from the X/Open Portability Guide. Users should +note that the description of the <b>-E</b> option matches historical documentation of the <b>-e</b> option (which was not adopted +because it did not support the Utility Syntax Guidelines), by saying that if <i>eofstr</i> is the null string, logical end-of-file +processing is disabled. Historical implementations of <i>xargs</i> actually did not disable logical end-of-file processing; they +treated a null argument found in the input as a logical end-of-file string. (A null <i>string</i> argument could be generated using +single or double-quotes (<tt>'"'</tt> or <tt>""</tt>). Since this behavior was not documented historically, it is considered to be +a bug.</p> +<p>The <b>-I</b>, <b>-L</b>, and <b>-n</b> options are mutually-exclusive. Some implementations use the last one specified if more +than one is given on a command line; other implementations treat combinations of the options in different ways.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_152_19" id="tag_20_152_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>A future version of this standard may require that, when the <b>-0</b> option is specified, if the standard input is not empty +and does not end with a null byte, <i>xargs</i> ignores the trailing non-null bytes.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_152_20" id="tag_20_152_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/V3_chap02.html#tag_19"><i>2. Shell Command Language</i></a> , <a href= +"../utilities/diff.html#"><i>diff</i></a> , <a href="../utilities/echo.html#"><i>echo</i></a> , <a href= +"../utilities/find.html#"><i>find</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/exec.html#tag_17_129"><i>exec</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_152_21" id="tag_20_152_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_152_22" id="tag_20_152_22"></a>Issue 5</h4> +<blockquote> +<p>A second FUTURE DIRECTION is added.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_152_23" id="tag_20_152_23"></a>Issue 6</h4> +<blockquote> +<p>The obsolescent <b>-e</b>, <b>-i</b>, and <b>-l</b> options are removed.</p> +<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p> +<ul> +<li> +<p>The <b>-p</b> option is added.</p> +</li> +<li> +<p>In the INPUT FILES section, the file <b>/dev/tty</b> is used to read responses required by the <b>-p</b> option.</p> +</li> +<li> +<p>The STDERR section is updated to describe the <b>-p</b> option.</p> +</li> +</ul> +<p>The description of the <b>-E</b> option is aligned with the ISO POSIX-2:1993 standard.</p> +<p>The normative text is reworded to avoid use of the term "must" for application requirements.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_152_24" id="tag_20_152_24"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #123 is applied, changing the description of the <i>xargs</i> <b>-I</b> option.</p> +<p>Austin Group Interpretation 1003.1-2001 #126 is applied, changing the description of the <i>LC_MESSAGES</i> environment +variable.</p> +<p>SD5-XCU-ERN-68 is applied.</p> +<p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p>SD5-XCU-ERN-128 is applied, clarifying the DESCRIPTION of the logical end-of-file string.</p> +<p>SD5-XCU-ERN-132 is applied, updating the EXAMPLES section.</p> +<p>POSIX.1-2008, Technical Corrigendum 1, XCU/TC1-2008/0149 [342] is applied.</p> +<p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0203 [499] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_152_25" id="tag_20_152_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 243 is applied, adding the <b>-r</b> and <b>-0</b> options.</p> +<p>Austin Group Defect 248 is applied, changing the EXAMPLES section.</p> +<p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p>Austin Group Defect 1586 is applied, adding the <a href="../utilities/timeout.html"><i>timeout</i></a> utility.</p> +<p>Austin Group Defect 1594 is applied, changing the APPLICATION USAGE section.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/write.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/xgettext.html" accesskey="N">Next +>>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/xgettext.html b/bdd/xgettext.html @@ -0,0 +1,315 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>xgettext</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/xargs.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/yacc.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="xgettext" id="xgettext"></a> <a name="tag_20_153" id="tag_20_153"></a><!-- xgettext --> +<h4 class="mansect"><a name="tag_20_153_01" id="tag_20_153_01"></a>NAME</h4> +<blockquote>xgettext — extract <i>gettext</i> call strings from C-language source files (DEVELOPMENT)</blockquote> +<h4 class="mansect"><a name="tag_20_153_02" id="tag_20_153_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('CD')">CD</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> xgettext</tt> <b>[</b><tt>-j</tt><b>] [</b><tt>-n</tt><b>] [</b><tt>-d</tt> <i>default-domain</i><b>] +[</b><tt>-K</tt> <i>keyword-spec</i><b>]</b><tt>...<br> + </tt> <b>[</b><tt>-p</tt> <i>pathname</i><b>]</b> <i>file</i><tt>...<br> +<br> +xgettext -a</tt> <b>[</b><tt>-n</tt><b>] [</b><tt>-d</tt> <i>default-domain</i><b>] [</b><tt>-p</tt> <i>pathname</i><b>]<br></b> +<tt> </tt> <b>[</b><tt>-x</tt> <i>exclude-file</i><b>]</b> <i>file</i><tt>... <img src= +"../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div> +<tt><br></tt></blockquote> +<h4 class="mansect"><a name="tag_20_153_03" id="tag_20_153_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>xgettext</i> utility shall automate the creation of portable messages object source files (dot-po files). A dot-po file +shall contain copies of string literals that are found in C-language source code in files specified by <i>file</i> operands. The +dot-po file can be used as input to the <a href="../utilities/msgfmt.html"><i>msgfmt</i></a> utility, to produce a messages object +file that can be used by applications.</p> +<p>The <i>xgettext</i> utility shall write <i>msgid</i> argument strings that are passed as string literals in <a href= +"../functions/gettext.html"><i>gettext</i>()</a>, <a href="../functions/gettext_l.html"><i>gettext_l</i>()</a>, <a href= +"../functions/ngettext.html"><i>ngettext</i>()</a>, and <a href="../functions/ngettext_l.html"><i>ngettext_l</i>()</a> calls in +C-language source code to the default output file; this file shall be named <b>messages.po</b> unless it is changed by the +<b>-d</b> option. The <i>xgettext</i> utility shall also write <i>msgid</i> argument strings that are passed as string literals in +<a href="../functions/dcgettext.html"><i>dcgettext</i>()</a>, <a href="../functions/dcgettext_l.html"><i>dcgettext_l</i>()</a>, +<a href="../functions/dcngettext.html"><i>dcngettext</i>()</a>, <a href="../functions/dcngettext_l.html"><i>dcngettext_l</i>()</a>, +<a href="../functions/dgettext.html"><i>dgettext</i>()</a>, <a href="../functions/dgettext_l.html"><i>dgettext_l</i>()</a>, +<a href="../functions/dngettext.html"><i>dngettext</i>()</a>, and <a href="../functions/dngettext_l.html"><i>dngettext_l</i>()</a> +calls either to the default output file or to the output file <i>domainname</i><b>.po</b> where <i>domainname</i> is the first +parameter to the call; it is implementation-defined which of those output files is used. A <b>msgid</b> directive shall precede +each <i>msgid</i> argument string. For the functions that have a <i>msgid_plural</i> argument, a <b>msgid_plural</b> directive +followed by that argument string shall also be written directly after the corresponding <b>msgid</b> directive. A <b>msgstr</b> +directive or <b>msgstr[</b><i>index</i><b>]</b> directives with an empty string shall be written after the corresponding +<b>msgid</b> or <b>msgid_plural</b> directive, respectively. The function names that <i>xgettext</i> searches for can be changed +using the <b>-K</b> option.</p> +<p>The first directive in each created dot-po file shall be a <b>domain</b> directive giving the associated domain name, except +that this directive is optional in the default output file.</p> +<p>If the <b>-p</b> <i>pathname</i> option is specified, <i>xgettext</i> shall create the dot-po files in the <i>pathname</i> +directory. Otherwise, the dot-po files shall be created in the current working directory.</p> +<p>The <b>msgid</b> values shall be in the same order that the strings are extracted from each <i>file</i> and subsections with +duplicate <b>msgid</b> values shall be written to the dot-po files as comment lines.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_153_04" id="tag_20_153_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>xgettext</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> .</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-a</b></dt> +<dd>Extract all strings, not just those found in calls to <i>gettext</i> family functions. Only one dot-po file shall be +created.</dd> +<dt><b>-d </b><i>default-domain</i></dt> +<dd><br> +Name the default output file <i>default-domain</i><b>.po</b> instead of <b>messages.po</b>.</dd> +<dt><b>-j</b></dt> +<dd>Join messages from C-language source files with existing dot-po files. For each dot-po file that <i>xgettext</i> writes +messages to, if the file does not exist, it shall be created. New messages shall be appended but any subsections with duplicate +<b>msgid</b> values except the first (including <b>msgid</b> values found in an existing dot-po file) shall either be commented out +or omitted in the resulting dot-po file; if omitted, a warning message may be written to standard error. Domain directives in the +existing dot-po files shall be ignored; the assumption is that all previous <b>msgid</b> values belong to the same domain. The +behavior is unspecified if an existing dot-po file was not created by <i>xgettext</i> or has been modified by another +application.</dd> +<dt><b>-K </b><i>keyword-spec</i></dt> +<dd><br> +Specify an additional keyword to be looked for: +<ul> +<li> +<p>If <i>keyword-spec</i> is an empty string, this shall disable the use of default keywords for the <i>gettext</i> family of +functions.</p> +</li> +<li> +<p>If <i>keyword-spec</i> is a C identifier, <i>xgettext</i> shall look for strings in the first argument of each call to the +function or macro <i>keyword-spec</i>.</p> +</li> +<li> +<p>If <i>keyword-spec</i> is of the form <i>id</i>:<i>argnum</i> then <i>xgettext</i> shall treat the <i>argnum</i>-th argument of +a call to the function or macro <i>id</i> as the <i>msgid</i> argument, where <i>argnum</i> 1 is the first argument.</p> +</li> +<li> +<p>If <i>keyword-spec</i> is of the form <i>id</i>:<i>argnum1</i>,<i>argnum2</i> then <i>xgettext</i> shall treat strings in the +<i>argnum1</i>-th argument and in the <i>argnum2</i>-th argument of a call to the function or macro <i>id</i> as the <i>msgid</i> +and <i>msgid_plural</i> arguments, respectively.</p> +</li> +</ul> +<p>For all mentioned forms, the application shall ensure that if <i>argnum2</i> is given, it is not equal to <i>argnum1</i>. All +numeric values shall be converted as specified in item 6 in XBD <a href="../basedefs/V1_chap12.html#tag_12_01"><i>12.1 Utility +Argument Syntax</i></a> .</p> +</dd> +<dt><b>-n</b></dt> +<dd>Add comment lines to the output file indicating pathnames and line numbers in the source files where each extracted string is +encountered. These lines shall appear before each <b>msgid</b> directive. Such comments should have the format: +<pre> +<tt>#: </tt><i>pathname1</i><tt>:</tt><i>linenumber1 </i><b>[</b><i>pathname2</i><tt>:</tt><i>linenumber2</i><tt>...</tt><b>]</b><tt> +</tt></pre></dd> +<dt><b>-p </b><i>pathname</i></dt> +<dd><br> +Create output files in the directory specified by <i>pathname</i> instead of in the current working directory.</dd> +<dt><b>-x </b><i>exclude-file</i></dt> +<dd><br> +Specify a file containing strings that shall not be extracted from the input files. The format of <i>exclude-file</i> is identical +to that of a dot-po file. However, only statements containing <b>msgid</b> directives in <i>exclude-file</i> shall be used. All +other statements shall be ignored.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_153_05" id="tag_20_153_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand shall be supported:</p> +<dl compact> +<dd></dd> +<dt><i>file</i></dt> +<dd>A pathname of an input file containing C-language source code. If <tt>'-'</tt> is specified for an instance of <i>file</i>, the +standard input shall be used.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_153_06" id="tag_20_153_06"></a>STDIN</h4> +<blockquote> +<p>The standard input shall not be used unless a <i>file</i> operand is specified as <tt>'-'</tt>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_153_07" id="tag_20_153_07"></a>INPUT FILES</h4> +<blockquote> +<p>The input files specified as <i>file</i> operands shall be C-language source files. The input file specified as the +option-argument for the <b>-x</b> option shall be a dot-po file in the format specified as input for the <a href= +"../utilities/msgfmt.html"><i>msgfmt</i></a> utility.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_153_08" id="tag_20_153_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>xgettext</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LANGUAGE</i></dt> +<dd>Determine the location of messages objects <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src= +"../images/opt-start.gif" alt="[Option Start]" border="0"> if <i>NLSPATH</i> is not set or the evaluation of <i>NLSPATH</i> +did not lead to a suitable messages object being found. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale name used to locate messages objects, and the locale that should be used to affect the format and contents of +diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_153_09" id="tag_20_153_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_153_10" id="tag_20_153_10"></a>STDOUT</h4> +<blockquote> +<p>The standard output shall not be used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_153_11" id="tag_20_153_11"></a>STDERR</h4> +<blockquote> +<p>The standard error shall be used for diagnostic messages and may be used for warning messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_153_12" id="tag_20_153_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>The output files shall be dot-po files in the format specified as input for the <a href= +"../utilities/msgfmt.html"><i>msgfmt</i></a> utility. It is unspecified whether each output file includes a header (<b>msgid</b> +<tt>""</tt>) before the content derived from the input C-language source files.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_153_13" id="tag_20_153_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>None.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_153_14" id="tag_20_153_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_153_15" id="tag_20_153_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_153_16" id="tag_20_153_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Implementations differ as to whether they write all output to the default output file or split the output into separate +per-domain files. Portable applications can either ensure that each C-language source file contains calls to <i>gettext</i> family +functions for only a single domain, or force all output to be to the default output file by using the <b>-K</b> option to override +the default keywords.</p> +<p>Some implementations of <i>xgettext</i> are not able to extract cast strings (unless <b>-a</b> is used), for example casts of +literal strings to <b>(const char *)</b>. Use of a cast is unnecessary anyway, since the prototypes in <a href= +"../basedefs/libintl.h.html"><i><libintl.h></i></a> already specify this type.</p> +<p>The <i>xgettext</i> utility is not required to handle C preprocessor directives. Therefore if, for example, calls to +<i>gettext</i> family functions are wrapped by macros, they might not be found unless the <b>-K</b> option is used to tell +<i>xgettext</i> to look for the macro calls.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_153_17" id="tag_20_153_17"></a>EXAMPLES</h4> +<blockquote> +<p><b>Example 1</b></p> +<p>The following example shows how <b>-K</b> can be used to force all output to be to the default output file:</p> +<pre> +<tt>xgettext -K "" -K gettext:1 -K dgettext:2 -K dcgettext:2 \ + -K ngettext:1,2 -K dngettext:2,3 -K dcngettext:2,3 source.c +</tt></pre> +<p>By overriding the default keywords using the <b>-K</b> option as above, the <i>xgettext</i> utility is directed to ignore the +<i>domainname</i> arguments to the <a href="../functions/dgettext.html"><i>dgettext</i>()</a>, <a href= +"../functions/dcgettext.html"><i>dcgettext</i>()</a>, <a href="../functions/dngettext.html"><i>dngettext</i>()</a>, and <a href= +"../functions/dcngettext.html"><i>dcngettext</i>()</a> functions. Thus, the utility treats the functions as their respective +equivalent without the <i>d</i> prefix, ignoring the <i>domainname</i> argument and writing generated output to the default output +file, <b>messages.po</b>. Additional <b>-K</b> options would be needed for the variants of the functions with an <i>_l</i> suffix +if they are used.</p> +<p><b>Example 2</b></p> +<p>If the source uses a macro definition such as:</p> +<pre> +<tt>#define i18n gettext +</tt></pre> +<p>the use of:</p> +<pre> +<tt>xgettext -K i18n:1 source.c +</tt></pre> +<p>will pick up <b>msgid</b> values from a line such as:</p> +<pre> +<tt>fprintf(stdout, i18n("The value is %s"), value1); +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_153_18" id="tag_20_153_18"></a>RATIONALE</h4> +<blockquote> +<p>The <b>-K</b> option is based on the <b>-k</b> option of GNU <i>xgettext</i>; the only difference is that GNU's <b>-k</b> takes +an optional option-argument whereas <b>-K</b> in this standard has a mandatory option-argument in order to comply with the syntax +guidelines.</p> +<p>The standard developers considered including functionality equivalent to the <b>-c</b>, <b>-m</b>, and <b>-M</b> options in +existing implementations. However, those letters could not be used as the syntax differed between implementations. The usual +solution of adding an uppercase equivalent of lowercase options with the standard syntax instead was not possible, for obvious +reasons for <b>-m</b> and <b>-M</b>, and as <b>-C</b> was already in use for another purpose in one implementation.</p> +<p>The <b>-s</b> option is not included as it has been deprecated in at least one implementation because it has been found to +deprive translators of valuable context.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_153_19" id="tag_20_153_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a +<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require +implementations to treat this as an error.</p> +<p>A future version of this standard may change the description of the <b>-n</b> option to mandate the given comment format (by +using "shall" instead of "should").</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_153_20" id="tag_20_153_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/gettext.html#tag_20_54"><i>gettext</i></a> , <a href="../utilities/msgfmt.html#"><i>msgfmt</i></a></p> +<p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +<p>XSH <a href="../functions/gettext.html#tag_17_238"><i>gettext</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_153_21" id="tag_20_153_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 8.</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/xargs.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/yacc.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/yacc.html b/bdd/yacc.html @@ -0,0 +1,962 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!DOCTYPE HTML> +<html lang="en"> +<head> +<meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>yacc</title> +</head> +<body bgcolor="white"> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/xgettext.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/zcat.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +<script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> +<center><font size="2">The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top" id="top"></a> <a name="yacc" id="yacc"></a> <a name="tag_20_154" id="tag_20_154"></a><!-- yacc --> +<h4 class="mansect"><a name="tag_20_154_01" id="tag_20_154_01"></a>NAME</h4> +<blockquote>yacc — yet another compiler compiler (<b>DEVELOPMENT</b>)</blockquote> +<h4 class="mansect"><a name="tag_20_154_02" id="tag_20_154_02"></a>SYNOPSIS</h4> +<blockquote class="synopsis"> +<div class="box"><code><tt><sup>[<a href="javascript:open_code('CD')">CD</a>]</sup> <img src="../images/opt-start.gif" alt= +"[Option Start]" border="0"> yacc</tt> <b>[</b><tt>-dltv</tt><b>] [</b><tt>-b</tt> <i>file_prefix</i><b>] [</b><tt>-p</tt> +<i>sym_prefix</i><b>]</b> <i>grammar</i> <tt><img src="../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div> +</blockquote> +<h4 class="mansect"><a name="tag_20_154_03" id="tag_20_154_03"></a>DESCRIPTION</h4> +<blockquote> +<p>The <i>yacc</i> utility shall read a description of a context-free grammar in <i>grammar</i> and write C source code, conforming +to the ISO C standard, to a code file, and optionally header information into a header file, in the current directory. The +generated source code shall not depend on any undefined, unspecified, or implementation-defined behavior, except in cases where it +is copied directly from the supplied grammar, or in cases that are documented by the implementation. The C code shall define a +function and related routines and macros for an automaton that executes a parsing algorithm meeting the requirements in <a href= +"#tag_20_154_13_13">Algorithms</a> .</p> +<p>The form and meaning of the grammar are described in the EXTENDED DESCRIPTION section.</p> +<p>The C source code and header file shall be produced in a form suitable as input for the C compiler (see <a href= +"../utilities/c17.html#"><i>c17</i></a> ).</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_154_04" id="tag_20_154_04"></a>OPTIONS</h4> +<blockquote> +<p>The <i>yacc</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax +Guidelines</i></a> , except for Guideline 9.</p> +<p>The following options shall be supported:</p> +<dl compact> +<dd></dd> +<dt><b>-b </b><i>file_prefix</i></dt> +<dd>Use <i>file_prefix</i> instead of <b>y</b> as the prefix for all output filenames. The code file <b>y.tab.c</b>, the header +file <b>y.tab.h</b> (created when <b>-d</b> is specified), and the description file <b>y.output</b> (created when <b>-v</b> is +specified), shall be changed to <i>file_prefix</i><b>.tab.c</b>, <i>file_prefix</i><b>.tab.h</b>, and +<i>file_prefix</i><b>.output</b>, respectively.</dd> +<dt><b>-d</b></dt> +<dd>Write the header file; by default only the code file is written. See the OUTPUT FILES section.</dd> +<dt><b>-l</b></dt> +<dd>Produce a code file that does not contain any <b>#line</b> constructs. If this option is not present, it is unspecified whether +the code file or header file contains <b>#line</b> directives. This should only be used after the grammar and the associated +actions are fully debugged.</dd> +<dt><b>-p </b><i>sym_prefix</i></dt> +<dd><br> +Use <i>sym_prefix</i> instead of <b>yy</b> as the prefix for all external names produced by <i>yacc</i>. The names affected shall +include the functions <i>yyparse</i>(), <i>yylex</i>(), and <i>yyerror</i>(), and the variables <i>yylval</i>, <i>yychar</i>, and +<i>yydebug</i>. (In the remainder of this section, the six symbols cited are referenced using their default names only as a +notational convenience.) Local names may also be affected by the <b>-p</b> option; however, the <b>-p</b> option shall not affect +<b>#define</b> symbols generated by <i>yacc</i>.</dd> +<dt><b>-t</b></dt> +<dd>Modify conditional compilation directives to permit compilation of debugging code in the code file. Runtime debugging +statements shall always be contained in the code file, but by default conditional compilation directives prevent their +compilation.</dd> +<dt><b>-v</b></dt> +<dd>Write a file containing a description of the parser and a report of conflicts generated by ambiguities in the grammar.</dd> +</dl> +<br></blockquote> +<h4 class="mansect"><a name="tag_20_154_05" id="tag_20_154_05"></a>OPERANDS</h4> +<blockquote> +<p>The following operand is required:</p> +<dl compact> +<dd></dd> +<dt><i>grammar</i></dt> +<dd>A pathname of a file containing instructions, hereafter called <i>grammar</i>, for which a parser is to be created. The format +for the grammar is described in the EXTENDED DESCRIPTION section.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_154_06" id="tag_20_154_06"></a>STDIN</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_154_07" id="tag_20_154_07"></a>INPUT FILES</h4> +<blockquote> +<p>The file <i>grammar</i> shall be a text file formatted as specified in the EXTENDED DESCRIPTION section.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_154_08" id="tag_20_154_08"></a>ENVIRONMENT VARIABLES</h4> +<blockquote> +<p>The following environment variables shall affect the execution of <i>yacc</i>:</p> +<dl compact> +<dd></dd> +<dt><i>LANG</i></dt> +<dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href= +"../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization +variables used to determine the values of locale categories.)</dd> +<dt><i>LC_ALL</i></dt> +<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd> +<dt><i>LC_CTYPE</i></dt> +<dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files).</dd> +<dt><i>LC_MESSAGES</i></dt> +<dd><br> +Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd> +<dt><i>NLSPATH</i></dt> +<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> +Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border= +"0"></dd> +</dl> +<p>The <i>LANG</i> and <i>LC_*</i> variables affect the execution of the <i>yacc</i> utility as stated. The <i>main</i>() function +defined in <a href="#tag_20_154_13_11">Yacc Library</a> shall call:</p> +<pre> +<tt>setlocale(LC_ALL, "") +</tt></pre> +<p>and thus the program generated by <i>yacc</i> shall also be affected by the contents of these variables at runtime.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_154_09" id="tag_20_154_09"></a>ASYNCHRONOUS EVENTS</h4> +<blockquote> +<p>Default.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_154_10" id="tag_20_154_10"></a>STDOUT</h4> +<blockquote> +<p>Not used.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_154_11" id="tag_20_154_11"></a>STDERR</h4> +<blockquote> +<p>If shift/reduce or reduce/reduce conflicts are detected in <i>grammar</i>, <i>yacc</i> shall write a report of those conflicts +to the standard error in an unspecified format.</p> +<p>Standard error shall also be used for diagnostic messages.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_154_12" id="tag_20_154_12"></a>OUTPUT FILES</h4> +<blockquote> +<p>The code file, the header file, and the description file shall be text files. All are described in the following sections.</p> +<h5><a name="tag_20_154_12_01" id="tag_20_154_12_01"></a>Code File</h5> +<p>This file shall contain the C source code for the <i>yyparse</i>() function. It shall contain code for the various semantic +actions with macro substitution performed on them as described in the EXTENDED DESCRIPTION section. Preceding this code it shall +contain an <tt>extern int yychar</tt> declaration or <tt>int yychar</tt> definition, and <b>#define</b> statements for the +following macros:</p> +<dl compact> +<dd></dd> +<dt>YYEMPTY</dt> +<dd>Token number indicating there is no lookahead token. This macro shall expand to an integer constant with a value less than +zero, protected by parentheses.</dd> +<dt>YYEOF</dt> +<dd>Token number indicating the end of input. This macro shall expand to the value 0.</dd> +</dl> +<p>It also shall contain a copy of the <b>#define</b> statements in the header file, prior to any code copied from semantic actions +in <i>grammar</i>, and the following function prototypes for the <i>yyerror</i>(), <i>yylex</i>(), and <i>yyparse</i>() functions, +after any code copied from within <b>%{</b> and <b>%}</b> in the declarations section in <i>grammar</i> and before any code copied +from semantic actions in <i>grammar</i>:</p> +<pre> +<tt>void yyerror(const char *); +int yylex(void); +int yyparse(void); +</tt></pre> +<p>The declarations of <i>yyerror</i>() and <i>yylex</i>() shall be protected by <b>#ifndef</b> or <b>#if</b> preprocessor +statements such that each is only visible if a preprocessor macro with the name yyerror or yylex, respectively, is not already +defined, where the yy in the macro names is replaced by <i>sym_prefix</i> if the <b>-p</b> <i>sym_prefix</i> option is used.</p> +<p>If a <b>%union</b> declaration is used, the declaration for YYSTYPE and an <tt>extern YYSTYPE yylval</tt> declaration or +<tt>YYSTYPE yylval</tt> definition shall also be included in this file.</p> +<p>The code file shall not contain a declaration of the <i>main</i>() function, unless one is present within <b>%{</b> and +<b>%}</b> in the declarations section in <i>grammar</i>.</p> +<h5><a name="tag_20_154_12_02" id="tag_20_154_12_02"></a>Header File</h5> +<p>The header file shall contain <b>#define</b> statements that associate the token numbers with the token names. This allows +source files other than the code file to access the token codes. If a <b>%union</b> declaration is used, the declaration for +YYSTYPE and an <tt>extern YYSTYPE yylval</tt> declaration shall also be included in this file. The header file may also declare the +<i>yyparse</i>() function, using a function prototype. It shall not declare the <i>yyerror</i>() and <i>yylex</i>() functions.</p> +<h5><a name="tag_20_154_12_03" id="tag_20_154_12_03"></a>Description File</h5> +<p>The description file shall be a text file containing a description of the state machine corresponding to the parser, using an +unspecified format. Limits for internal tables (see <a href="#tag_20_154_13_14">Limits</a> ) shall also be reported, in an +implementation-defined manner. (Some implementations may use dynamic allocation techniques and have no specific limit values to +report.)</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_154_13" id="tag_20_154_13"></a>EXTENDED DESCRIPTION</h4> +<blockquote> +<p>The <i>yacc</i> command accepts a language that is used to define a grammar for a target language to be parsed by the tables and +code generated by <i>yacc</i>. The language accepted by <i>yacc</i> as a grammar for the target language is described below using +the <i>yacc</i> input language itself.</p> +<p>The input <i>grammar</i> includes rules describing the input structure of the target language and code to be invoked when these +rules are recognized to provide the associated semantic action. The code to be executed shall appear as bodies of text that are +intended to be C-language code. These bodies of text shall not contain C-language trigraphs. The C-language inclusions are presumed +to form a correct function when processed by <i>yacc</i> into its output files. The code included in this way shall be executed +during the recognition of the target language.</p> +<p>Given a grammar, the <i>yacc</i> utility generates the files described in the OUTPUT FILES section. The code file can be +compiled and linked using <a href="../utilities/c17.html"><i>c17</i></a>. If the declaration and programs sections of the grammar +file did not include definitions of <i>main</i>(), <i>yylex</i>(), and <i>yyerror</i>(), the compiled output requires linking with +externally supplied versions of those functions. Default versions of <i>main</i>() and <i>yyerror</i>() are supplied in the +<i>yacc</i> library and can be linked in by using the <b>-l y</b> operand to <a href="../utilities/c17.html"><i>c17</i></a>. +The <i>yacc</i> library interfaces need not support interfaces with other than the default <b>yy</b> symbol prefix. The application +provides the lexical analyzer function, <i>yylex</i>(); the <a href="../utilities/lex.html"><i>lex</i></a> utility is specifically +designed to generate such a routine.</p> +<h5><a name="tag_20_154_13_01" id="tag_20_154_13_01"></a>Input Language</h5> +<p>The application shall ensure that every specification file consists of three sections in order: <i>declarations</i>, <i>grammar +rules</i>, and <i>programs</i>, separated by double <percent-sign> characters (<tt>"%%"</tt>). The declarations and programs +sections can be empty. If the latter is empty, the preceding <tt>"%%"</tt> mark separating it from the rules section can be +omitted.</p> +<p>The input is free form text following the structure of the grammar defined below.</p> +<h5><a name="tag_20_154_13_02" id="tag_20_154_13_02"></a>Lexical Structure of the Grammar</h5> +<p>The <blank>, <newline>, and <form-feed> character shall be ignored, except that the application shall ensure +that they do not appear in names or multi-character reserved symbols. Comments shall be enclosed in <tt>"/* ... */"</tt>, +and can appear wherever a name is valid.</p> +<p>Names are of arbitrary length, made up of letters, periods (<tt>'.'</tt>), underscores (<tt>'_'</tt>), and non-initial digits. +Uppercase and lowercase letters are distinct. Conforming applications shall not use names beginning in <b>yy</b> or <b>YY</b> since +the <i>yacc</i> parser uses such names. Many of the names appear in the final output of <i>yacc</i>, and thus they should be chosen +to conform with any additional rules created by the C compiler to be used. In particular they appear in <b>#define</b> +statements.</p> +<p>A literal shall consist of a single character enclosed in single-quote characters. All of the escape sequences supported for +character constants by the ISO C standard shall be supported by <i>yacc</i>.</p> +<p>The relationship with the lexical analyzer is discussed in detail below.</p> +<p>The application shall ensure that the NUL character is not used in grammar rules or literals.</p> +<h5><a name="tag_20_154_13_03" id="tag_20_154_13_03"></a>Declarations Section</h5> +<p>The declarations section is used to define the symbols used to define the target language and their relationship with each +other. In particular, much of the additional information required to resolve ambiguities in the context-free grammar for the target +language is provided here.</p> +<p>Usually <i>yacc</i> assigns the relationship between the symbolic names it generates and their underlying numeric value. The +declarations section makes it possible to control the assignment of these values.</p> +<p>It is also possible to keep semantic information associated with the tokens currently on the parse stack in a user-defined +C-language <b>union</b>, if the members of the union are associated with the various names in the grammar. The declarations section +provides for this as well.</p> +<p>The first group of declarators below all take a list of names as arguments. That list can optionally be preceded by the name of +a C union member (called a <i>tag</i> below) appearing within <tt>'<'</tt> and <tt>'>'</tt>. (As an exception to the +typographical conventions of the rest of this volume of POSIX.1-2024, in this case <<i>tag</i>> does not represent a +metavariable, but the literal angle bracket characters surrounding a symbol.) The use of <i>tag</i> specifies that the tokens named +on this line shall be of the same C type as the union member referenced by <i>tag</i>. This is discussed in more detail below.</p> +<p>For lists used to define tokens, the first appearance of a given token can be followed by a positive integer (as a string of +decimal digits). If this is done, the underlying value assigned to it for lexical purposes shall be taken to be that number.</p> +<p>The following declares <i>name</i> to be a token:</p> +<pre> +<tt>%token </tt><b>[</b><tt><</tt><i>tag</i><tt>></tt><b>] </b><i>name </i><b>[</b><i>number</i><b>] [</b><i>name </i><b>[</b><i>number</i><b>]]</b><tt>... +</tt></pre> +<p>If <i>tag</i> is present, the C type for all tokens on this line shall be declared to be the type referenced by <i>tag</i>. If a +positive integer, <i>number</i>, follows a <i>name</i>, that value shall be assigned to the token.</p> +<p>The following declares <i>name</i> to be a token, and assigns precedence to it:</p> +<pre> +<tt>%left </tt><b>[</b><tt><</tt><i>tag</i><tt>></tt><b>] </b><i>name </i><b>[</b><i>number</i><b>] [</b><i>name </i><b>[</b><i>number</i><b>]]</b><tt>... +%right </tt><b>[</b><tt><</tt><i>tag</i><tt>></tt><b>] </b><i>name </i><b>[</b><i>number</i><b>] [</b><i>name </i><b>[</b><i>number</i><b>]]</b><tt>... +</tt></pre> +<p>One or more lines, each beginning with one of these symbols, can appear in this section. All tokens on the same line have the +same precedence level and associativity; the lines are in order of increasing precedence or binding strength. <b>%left</b> denotes +that the operators on that line are left associative, and <b>%right</b> similarly denotes right associative operators. If +<i>tag</i> is present, it shall declare a C type for <i>name</i>s as described for <b>%token</b>.</p> +<p>The following declares <i>name</i> to be a token, and indicates that this cannot be used associatively:</p> +<pre> +<tt>%nonassoc </tt><b>[</b><tt><</tt><i>tag</i><tt>></tt><b>] </b><i>name </i><b>[</b><i>number</i><b>] [</b><i>name </i><b>[</b><i>number</i><b>]]</b><tt>... +</tt></pre> +<p>If the parser encounters associative use of this token it reports an error. If <i>tag</i> is present, it shall declare a C type +for <i>name</i>s as described for <b>%token</b>.</p> +<p>The following declares that union member <i>name</i>s are non-terminals, and thus it is required to have a <i>tag</i> field at +its beginning:</p> +<pre> +<tt>%type <</tt><i>tag</i><tt>> </tt><i>name</i><tt>... +</tt></pre> +<p>Because it deals with non-terminals only, assigning a token number or using a literal is also prohibited. If this construct is +present, <i>yacc</i> shall perform type checking; if this construct is not present, the parse stack shall hold only the <b>int</b> +type.</p> +<p>Every name used in <i>grammar</i> not defined by a <b>%token</b>, <b>%left</b>, <b>%right</b>, or <b>%nonassoc</b> declaration +is assumed to represent a non-terminal symbol. The <i>yacc</i> utility shall report an error for any non-terminal symbol that does +not appear on the left side of at least one grammar rule.</p> +<p>Once the type, precedence, or token number of a name is specified, it shall not be changed. If the first declaration of a token +does not assign a token number, <i>yacc</i> shall assign a token number. Once this assignment is made, the token number shall not +be changed by explicit assignment.</p> +<p>The following declarators do not follow the previous pattern.</p> +<p>The following declares the non-terminal <i>name</i> to be the <i>start symbol</i>, which represents the largest, most general +structure described by the grammar rules:</p> +<pre> +<tt>%start </tt><i>name</i><tt> +</tt></pre> +<p>By default, it is the left-hand side of the first grammar rule; this default can be overridden with this declaration.</p> +<p>The following declares the <i>yacc</i> value stack to be a union of the various types of values desired.</p> +<pre> +<tt>%union { </tt><i>body of union</i><tt> (</tt><i>in C</i><tt>) } +</tt></pre> +<p>The body of the union shall not contain unbalanced curly brace preprocessing tokens.</p> +<p>By default, the values returned by actions (see below) and the lexical analyzer shall be of type <b>int</b>. The <i>yacc</i> +utility keeps track of types, and it shall insert corresponding union member names in order to perform strict type checking of the +resulting parser.</p> +<p>Alternatively, given that at least one <<i>tag</i>> construct is used, the union can be declared in a header file (which +shall be included in the declarations section by using a <b>#include</b> construct within <b>%{</b> and <b>%}</b>), and a +<b>typedef</b> used to define the symbol YYSTYPE to represent this union. The effect of <b>%union</b> is to provide the declaration +of YYSTYPE directly from the <i>yacc</i> input.</p> +<p>C-language declarations and definitions can appear in the declarations section, enclosed by the following marks:</p> +<pre> +<tt>%{ ... %} +</tt></pre> +<p>These statements shall be copied into the code file, and have global scope within it so that they can be used in the rules and +program sections. The statements shall not contain <tt>"%}"</tt> outside a comment, string literal, or multi-character +constant.</p> +<p>The application shall ensure that the declarations section is terminated by the token <b>%%</b>.</p> +<h5><a name="tag_20_154_13_04" id="tag_20_154_13_04"></a>Grammar Rules in yacc</h5> +<p>The rules section defines the context-free grammar to be accepted by the function <i>yacc</i> generates, and associates with +those rules C-language actions and additional precedence information. The grammar is described below, and a formal definition +follows.</p> +<p>The rules section is comprised of one or more grammar rules. A grammar rule has the form:</p> +<pre> +<tt>A : BODY ; +</tt></pre> +<p>The symbol <b>A</b> represents a non-terminal name, and <b>BODY</b> represents a sequence of zero or more <i>name</i>s, +<i>literal</i>s, and <i>semantic action</i>s that can then be followed by optional <i>precedence rule</i>s. Only the names and +literals participate in the formation of the grammar; the semantic actions and precedence rules are used in other ways. The +<colon> and the <semicolon> are <i>yacc</i> punctuation. If there are several successive grammar rules with the same +left-hand side, the <vertical-line> (<tt>'|'</tt>) can be used to avoid rewriting the left-hand side; in this case the +<semicolon> appears only after the last rule. The BODY part can be empty (or empty of names and literals) to indicate that +the non-terminal symbol matches the empty string.</p> +<p>The <i>yacc</i> utility assigns a unique number to each rule. Rules using the vertical bar notation are distinct rules. The +number assigned to the rule appears in the description file.</p> +<p>The elements comprising a BODY are:</p> +<dl compact> +<dd></dd> +<dt><i>name</i>, <i>literal</i></dt> +<dd>These form the rules of the grammar: <i>name</i> is either a <i>token</i> or a <i>non-terminal</i>; <i>literal</i> stands for +itself (less the lexically required quotation marks).</dd> +<dt><i>semantic action</i></dt> +<dd><br> +With each grammar rule, the user can associate actions to be performed each time the rule is recognized in the input process. (Note +that the word "action" can also refer to the actions of the parser—shift, reduce, and so on.) +<p>These actions can return values and can obtain the values returned by previous actions. These values are kept in objects of type +YYSTYPE (see <b>%union</b>). The result value of the action shall be kept on the parse stack with the left-hand side of the rule, +to be accessed by other reductions as part of their right-hand side. By using the <<i>tag</i>> information provided in the +declarations section, the code generated by <i>yacc</i> can be strictly type checked and contain arbitrary information. In +addition, the lexical analyzer can provide the same kinds of values for tokens, if desired.</p> +<p>An action is an arbitrary C statement and as such can do input or output, call subprograms, and alter external variables. An +action is one or more C statements enclosed in curly braces <tt>'{'</tt> and <tt>'}'</tt>. The statements shall not contain +unbalanced curly brace preprocessing tokens.</p> +<p>Certain pseudo-variables can be used in the action. These are macros for access to data structures known internally to +<i>yacc</i>.</p> +<dl compact> +<dd></dd> +<dt>$$</dt> +<dd>The value of the action can be set by assigning it to $$. If type checking is enabled and the type of the value to be assigned +cannot be determined, a diagnostic message may be generated.</dd> +<dt>$<i>number</i></dt> +<dd>This refers to the value returned by the component specified by the token <i>number</i> in the right side of a rule, reading +from left to right; <i>number</i> can be zero or negative. If <i>number</i> is zero or negative, it refers to the data associated +with the name on the parser's stack preceding the leftmost symbol of the current rule. (That is, <tt>"$0"</tt> refers to the name +immediately preceding the leftmost name in the current rule to be found on the parser's stack and <tt>"$-1"</tt> refers to the +symbol to <i>its</i> left.) If <i>number</i> refers to an element past the current point in the rule, or beyond the bottom of the +stack, the result is undefined. If type checking is enabled and the type of the value to be assigned cannot be determined, a +diagnostic message may be generated.</dd> +<dt>$<<i>tag</i>><i>number</i></dt> +<dd><br> +These correspond exactly to the corresponding symbols without the <i>tag</i> inclusion, but allow for strict type checking (and +preclude unwanted type conversions). The effect is that the macro is expanded to use <i>tag</i> to select an element from the +YYSTYPE union (using <i>dataname.tag</i>). This is particularly useful if <i>number</i> is not positive.</dd> +<dt>$<<i>tag</i>>$</dt> +<dd>This imposes on the reference the type of the union member referenced by <i>tag</i>. This construction is applicable when a +reference to a left context value occurs in the grammar, and provides <i>yacc</i> with a means for selecting a type.</dd> +</dl> +<p>Actions can occur anywhere in a rule (not just at the end); an action can access values returned by actions to its left, and in +turn the value it returns can be accessed by actions to its right. An action appearing in the middle of a rule shall be equivalent +to replacing the action with a new non-terminal symbol and adding an empty rule with that non-terminal symbol on the left-hand +side. The semantic action associated with the new rule shall be equivalent to the original action. The use of actions within rules +might introduce conflicts that would not otherwise exist.</p> +<p>By default, the value of a rule shall be the value of the first element in it. If the first element does not have a type +(particularly in the case of a literal) and type checking is turned on by <b>%type</b>, an error message shall result.</p> +</dd> +<dt><i>precedence</i></dt> +<dd>The keyword <b>%prec</b> can be used to change the precedence level associated with a particular grammar rule. Examples of this +are in cases where a unary and binary operator have the same symbolic representation, but need to be given different precedences, +or where the handling of an ambiguous if-else construction is necessary. The reserved symbol <b>%prec</b> can appear immediately +after the body of the grammar rule and can be followed by a token name or a literal. It shall cause the precedence of the grammar +rule to become that of the following token name or literal. The action for the rule as a whole can follow <b>%prec</b>.</dd> +</dl> +<p>If a program section follows, the application shall ensure that the grammar rules are terminated by <b>%%</b>.</p> +<h5><a name="tag_20_154_13_05" id="tag_20_154_13_05"></a>Programs Section</h5> +<p>The <i>programs</i> section can include the definition of the lexical analyzer <i>yylex</i>(), and any other functions; for +example, those used in the actions specified in the grammar rules. It is unspecified whether the programs section precedes or +follows the semantic actions in the output file; therefore, if the application contains any macro definitions and declarations +intended to apply to the code in the semantic actions, it shall place them within <tt>"%{ ... %}"</tt> in the +declarations section.</p> +<h5><a name="tag_20_154_13_06" id="tag_20_154_13_06"></a>Input Grammar</h5> +<p>The following input to <i>yacc</i> yields a parser for the input to <i>yacc</i>. This formal syntax takes precedence over the +preceding text syntax description.</p> +<p>The lexical structure is defined less precisely; <a href="#tag_20_154_13_02">Lexical Structure of the Grammar</a> defines most +terms. The correspondence between the previous terms and the tokens below is as follows.</p> +<dl compact> +<dd></dd> +<dt><b>IDENTIFIER</b></dt> +<dd>This corresponds to the concept of <i>name</i>, given previously. It also includes literals as defined previously.</dd> +<dt><b>C_IDENTIFIER</b></dt> +<dd>This is a name, and additionally it is known to be followed by a <colon>. A literal cannot yield this token.</dd> +<dt><b>NUMBER</b></dt> +<dd>A string of digits (a non-negative decimal integer).</dd> +<dt><b>TYPE</b>, <b>LEFT</b>, <b>MARK</b>, <b>LCURL</b>, <b>RCURL</b></dt> +<dd><br> +These correspond directly to <b>%type</b>, <b>%left</b>, <b>%%</b>, <b>%{</b>, and <b>%}</b>.</dd> +<dt><b>{ ... }</b></dt> +<dd>This indicates C-language source code, with the possible inclusion of <tt>'$'</tt> macros as discussed previously.</dd> +</dl> +<pre> +<tt>/* Grammar for the input to yacc. */ +/* Basic entries. */ +/* The following are recognized by the lexical analyzer. */ +<br> +%token IDENTIFIER /* Includes identifiers and literals */ +%token C_IDENTIFIER /* identifier (but not literal) + followed by a :. */ +%token NUMBER /* [0-9][0-9]* */ +<br> +/* Reserved words : %type=>TYPE %left=>LEFT, and so on */ +<br> +%token LEFT RIGHT NONASSOC TOKEN PREC TYPE START UNION +<br> +%token MARK /* The %% mark. */ +%token LCURL /* The %{ mark. */ +%token RCURL /* The %} mark. */ +<br> +/* 8-bit character literals stand for themselves; */ +/* tokens have to be defined for multi-byte characters. */ +<br> +%start spec +<br> +%% +<br> +spec : defs MARK rules tail + ; +tail : MARK + { + /* In this action, set up the rest of the file. */ + } + | /* Empty; the second MARK is optional. */ + ; +defs : /* Empty. */ + | defs def + ; +def : START IDENTIFIER + | UNION + { + /* Copy union definition to output. */ + } + | LCURL + { + /* Copy C code to output file. */ + } + RCURL + | rword tag nlist + ; +rword : TOKEN + | LEFT + | RIGHT + | NONASSOC + | TYPE + ; +tag : /* Empty: union tag ID optional. */ + | '<' IDENTIFIER '>' + ; +nlist : nmno + | nlist nmno + ; +nmno : IDENTIFIER /* Note: literal invalid with % type. */ + | IDENTIFIER NUMBER /* Note: invalid with % type. */ + ; +<br> +/* Rule section */ +<br> +rules : C_IDENTIFIER rbody prec + | rules rule + ; +rule : C_IDENTIFIER rbody prec + | '|' rbody prec + ; +rbody : /* empty */ + | rbody IDENTIFIER + | rbody act + ; +act : '{' + { + /* Copy action, translate $$, and so on. */ + } + '}' + ; +prec : /* Empty */ + | PREC IDENTIFIER + | PREC IDENTIFIER act + | prec ';' + ; +</tt></pre> +<h5><a name="tag_20_154_13_07" id="tag_20_154_13_07"></a>Conflicts</h5> +<p>The parser produced for an input grammar may contain states in which conflicts occur. The conflicts occur because the grammar is +not LALR(1). An ambiguous grammar always contains at least one LALR(1) conflict. The <i>yacc</i> utility shall resolve all +conflicts, using either default rules or user-specified precedence rules.</p> +<p>Conflicts are either shift/reduce conflicts or reduce/reduce conflicts. A shift/reduce conflict is where, for a given state and +lookahead symbol, both a shift action and a reduce action are possible. A reduce/reduce conflict is where, for a given state and +lookahead symbol, reductions by two different rules are possible.</p> +<p>The rules below describe how to specify what actions to take when a conflict occurs. Not all shift/reduce conflicts can be +successfully resolved this way because the conflict may be due to something other than ambiguity, so incautious use of these +facilities can cause the language accepted by the parser to be much different from that which was intended. The description file +shall contain sufficient information to understand the cause of the conflict. Where ambiguity is the reason either the default or +explicit rules should be adequate to produce a working parser.</p> +<p>The declared precedences and associativities (see <a href="#tag_20_154_13_03">Declarations Section</a> ) are used to resolve +parsing conflicts as follows:</p> +<ol> +<li> +<p>A precedence and associativity is associated with each grammar rule; it is the precedence and associativity of the last token or +literal in the body of the rule. If the <b>%prec</b> keyword is used, it overrides this default. Some grammar rules might not have +both precedence and associativity.</p> +</li> +<li> +<p>If there is a shift/reduce conflict, and both the grammar rule and the input symbol have precedence and associativity associated +with them, then the conflict is resolved in favor of the action (shift or reduce) associated with the higher precedence. If the +precedences are the same, then the associativity is used; left associative implies reduce, right associative implies shift, and +non-associative implies an error in the string being parsed.</p> +</li> +<li> +<p>When there is a shift/reduce conflict that cannot be resolved by rule 2, the shift is done. Conflicts resolved this way are +counted in the diagnostic output described in <a href="#tag_20_154_13_08">Error Handling</a> .</p> +</li> +<li> +<p>When there is a reduce/reduce conflict, a reduction is done by the grammar rule that occurs earlier in the input sequence. +Conflicts resolved this way are counted in the diagnostic output described in <a href="#tag_20_154_13_08">Error Handling</a> .</p> +</li> +</ol> +<p>Conflicts resolved by precedence or associativity shall not be counted in the shift/reduce and reduce/reduce conflicts reported +by <i>yacc</i> on either standard error or in the description file.</p> +<h5><a name="tag_20_154_13_08" id="tag_20_154_13_08"></a>Error Handling</h5> +<p>The token <b>error</b> shall be reserved for error handling. The name <b>error</b> can be used in grammar rules. It indicates +places where the parser can recover from a syntax error. The default value of <b>error</b> shall be 256. Its value can be changed +using a <b>%token</b> declaration. The lexical analyzer should not return the value of <b>error</b>.</p> +<p>The parser shall detect a syntax error when it is in a state where the action associated with the lookahead symbol is +<b>error</b>. A semantic action can cause the parser to initiate error handling by executing the macro YYERROR. When YYERROR is +executed, the semantic action passes control back to the parser. YYERROR cannot be used outside of semantic actions.</p> +<p>When the parser detects a syntax error, it normally calls <i>yyerror</i>() with the character string +<tt>"syntax error"</tt> as its argument. The call shall not be made if the parser is still recovering from a previous error +when the error is detected. The parser is considered to be recovering from a previous error until the parser has shifted over at +least three normal input symbols since the last error was detected or a semantic action has executed the macro <i>yyerrok</i>. The +parser shall not call <i>yyerror</i>() when YYERROR is executed.</p> +<p>The macro function YYRECOVERING shall return 1 if a syntax error has been detected and the parser has not yet fully recovered +from it. Otherwise, zero shall be returned.</p> +<p>When a syntax error is detected by the parser, the parser shall check if a previous syntax error has been detected. If a +previous error was detected, and if no normal input symbols have been shifted since the preceding error was detected, the parser +checks if the lookahead symbol is an endmarker (see <a href="#tag_20_154_13_09">Interface to the Lexical Analyzer</a> ). If it is, +the parser shall return with a non-zero value. Otherwise, the lookahead symbol shall be discarded and normal parsing shall +resume.</p> +<p>When YYERROR is executed or when the parser detects a syntax error and no previous error has been detected, or at least one +normal input symbol has been shifted since the previous error was detected, the parser shall pop back one state at a time until the +parse stack is empty or the current state allows a shift over <b>error</b>. If the parser empties the parse stack, it shall return +with a non-zero value. Otherwise, it shall shift over <b>error</b> and then resume normal parsing. If the parser reads a lookahead +symbol before the error was detected, that symbol shall still be the lookahead symbol when parsing is resumed.</p> +<p>The macro <i>yyerrok</i> in a semantic action shall cause the parser to act as if it has fully recovered from any previous +errors. The macro <i>yyclearin</i> shall cause the parser to discard the current lookahead token. If the current lookahead token +has not yet been read, <i>yyclearin</i> shall have no effect.</p> +<p>The macro YYACCEPT shall cause the parser to return with the value zero. The macro YYABORT shall cause the parser to return with +a non-zero value.</p> +<h5><a name="tag_20_154_13_09" id="tag_20_154_13_09"></a>Interface to the Lexical Analyzer</h5> +<p>The application shall ensure that the <i>yylex</i>() function is an integer-valued function that returns a <i>token number</i> +greater than zero representing the kind of token read, or a value less than or equal to zero when the end of input is reached. When +the parser generated by <i>yacc</i> calls <i>yylex</i>(), it shall assign the returned value, if greater than zero, to the external +variable <i>yychar</i>. If there is a value associated with the returned token (see the discussion of <i>tag</i> above), it shall +be assigned to the external variable <i>yylval</i>. If the return value from <i>yylex</i>() is less than or equal to zero, the +parser shall assign the value YYEOF to <i>yychar</i>.</p> +<p>If the parser and <i>yylex</i>() do not agree on these token numbers, reliable communication between them cannot occur. For +(single-byte character) literals, the token is simply the numeric value of the character in the current character set. The numbers +for other tokens can either be chosen by <i>yacc</i>, or chosen by the user. In either case, the <b>#define</b> construct of C is +used to allow <i>yylex</i>() to return these numbers symbolically. The <b>#define</b> statements are put into the code file, and +the header file if that file is requested. The set of characters permitted by <i>yacc</i> in an identifier is larger than that +permitted by C. Token names found to contain such characters shall not be included in the <b>#define</b> declarations.</p> +<p>If the token numbers are chosen by <i>yacc</i>, the tokens other than literals shall be assigned numbers greater than 256, +although no order is implied. A token can be explicitly assigned a number by following its first appearance in the declarations +section with a number. Names and literals not defined this way retain their default definition. All token numbers assigned by +<i>yacc</i> shall be unique and distinct from the token numbers used for literals and user-assigned tokens. If duplicate token +numbers cause conflicts in parser generation, <i>yacc</i> shall report an error; otherwise, it is unspecified whether the token +assignment is accepted or an error is reported.</p> +<p>When a parser action is executed, <i>yychar</i> shall hold either the token number of the lookahead token, or YYEMPTY indicating +that there is no lookahead token, or YYEOF indicating the end of input. If <i>yychar</i> holds the token number of the lookahead +token, <i>yylval</i> shall hold the value associated with that token, if any.</p> +<p>The application shall ensure that when the end of input is reached, the <i>yylex</i>() function returns a value that is zero or +negative. The parser shall treat this as the token number YYEOF for a special token called the <i>endmarker</i>. If the tokens up +to, but excluding, the endmarker form a structure that matches the start symbol, the parser shall accept the input. If the +endmarker is seen in any other context, it shall be considered an error.</p> +<h5><a name="tag_20_154_13_10" id="tag_20_154_13_10"></a>Completing the Program</h5> +<p>In addition to <i>yyparse</i>() and <i>yylex</i>(), the functions <i>yyerror</i>() and <i>main</i>() are required to make a +complete program. The application can supply <i>main</i>() and <i>yyerror</i>(), or those routines can be obtained from the +<i>yacc</i> library.</p> +<h5><a name="tag_20_154_13_11" id="tag_20_154_13_11"></a>Yacc Library</h5> +<p>The following functions shall appear only in the <i>yacc</i> library accessible through the <b>-l y</b> operand to <a href= +"../utilities/c17.html"><i>c17</i></a>; they can therefore be redefined by a conforming application:</p> +<dl compact> +<dd></dd> +<dt><b>int </b><i>main</i>(<b>void</b>)</dt> +<dd><br> +This function shall call <i>yyparse</i>() and exit with an unspecified value. Other actions within this function are +unspecified.</dd> +<dt><b>void </b><i>yyerror</i>(<b>const char</b> *<i>s</i>)</dt> +<dd><br> +This function shall write the NUL-terminated argument to standard error, followed by a <newline>.</dd> +</dl> +<p>The order of the <b>-l y</b> and <b>-l l</b> operands given to <a href="../utilities/c17.html"><i>c17</i></a> is +significant; the application shall either provide its own <i>main</i>() function or ensure that <b>-l y</b> precedes +<b>-l l</b>.</p> +<h5><a name="tag_20_154_13_12" id="tag_20_154_13_12"></a>Debugging the Parser</h5> +<p>The parser generated by <i>yacc</i> shall have diagnostic facilities in it that can be optionally enabled at either compile time +or at runtime (if enabled at compile time). The compilation of the runtime debugging code is under the control of YYDEBUG, a +preprocessor symbol. If YYDEBUG has a non-zero value, the debugging code shall be included. If its value is zero, the code shall +not be included.</p> +<p>In parsers where the debugging code has been included, the external <b>int</b> <i>yydebug</i> can be used to turn debugging on +(with a non-zero value) and off (zero value) at runtime. The initial value of <i>yydebug</i> shall be zero.</p> +<p>When <b>-t</b> is specified, the code file shall be built such that, if YYDEBUG is not already defined at compilation time +(using the <a href="../utilities/c17.html"><i>c17</i></a> <b>-D</b> YYDEBUG option, for example), YYDEBUG shall be set explicitly +to 1. When <b>-t</b> is not specified, the code file shall be built such that, if YYDEBUG is not already defined, it shall be set +explicitly to zero.</p> +<p>The format of the debugging output is unspecified but includes at least enough information to determine the shift and reduce +actions, and the input symbols. It also provides information about error recovery.</p> +<h5><a name="tag_20_154_13_13" id="tag_20_154_13_13"></a>Algorithms</h5> +<p>The parser constructed by <i>yacc</i> implements an LALR(1) parsing algorithm as documented in the literature. It is unspecified +whether the parser is table-driven or direct-coded.</p> +<p>A parser generated by <i>yacc</i> shall never request an input symbol from <i>yylex</i>() while in a state where the only +actions other than the error action are reductions by a single rule.</p> +<p>The literature of parsing theory defines these concepts.</p> +<h5><a name="tag_20_154_13_14" id="tag_20_154_13_14"></a>Limits</h5> +<p>The <i>yacc</i> utility may have several internal tables. The minimum maximums for these tables are shown in the following +table. The exact meaning of these values is implementation-defined. The implementation shall define the relationship between these +values and between them and any error messages that the implementation may generate should it run out of space for any internal +structure. An implementation may combine groups of these resources into a single pool as long as the total available to the user +does not fall below the sum of the sizes specified by this section.<br></p> +<p class="caption">Table: Internal Limits in <i>yacc</i></p> +<center> +<table border="1" cellpadding="3" align="center"> +<tr valign="top"> +<th align="center"> +<p class="tent"><b>Limit</b></p> +</th> +<th align="center"> +<p class="tent"><b>Minimum Maximum</b></p> +</th> +<th align="center"> +<p class="tent"><b>Description</b></p> +</th> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">{NTERMS}</p> +</td> +<td align="left"> +<p class="tent">126</p> +</td> +<td align="left"> +<p class="tent">Number of tokens.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">{NNONTERM}</p> +</td> +<td align="left"> +<p class="tent">200</p> +</td> +<td align="left"> +<p class="tent">Number of non-terminals.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">{NPROD}</p> +</td> +<td align="left"> +<p class="tent">300</p> +</td> +<td align="left"> +<p class="tent">Number of rules.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">{NSTATES}</p> +</td> +<td align="left"> +<p class="tent">600</p> +</td> +<td align="left"> +<p class="tent">Number of states.</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">{MEMSIZE}</p> +</td> +<td align="left"> +<p class="tent">5200</p> +</td> +<td align="left"> +<p class="tent">Length of rules. The total length, in names (tokens and non-terminals), of all the rules of the grammar. The +left-hand side is counted for each rule, even if it is not explicitly repeated, as specified in <a href="#tag_20_154_13_04">Grammar +Rules in yacc</a> .</p> +</td> +</tr> +<tr valign="top"> +<td align="left"> +<p class="tent">{ACTSIZE}</p> +</td> +<td align="left"> +<p class="tent">4000</p> +</td> +<td align="left"> +<p class="tent">Number of actions. "Actions" here (and in the description file) refer to parser actions (shift, reduce, and so +on) not to semantic actions defined in <a href="#tag_20_154_13_04">Grammar Rules in yacc</a> .</p> +</td> +</tr> +</table> +</center> +</blockquote> +<h4 class="mansect"><a name="tag_20_154_14" id="tag_20_154_14"></a>EXIT STATUS</h4> +<blockquote> +<p>The following exit values shall be returned:</p> +<dl compact> +<dd></dd> +<dt> 0</dt> +<dd>Successful completion.</dd> +<dt>>0</dt> +<dd>An error occurred.</dd> +</dl> +</blockquote> +<h4 class="mansect"><a name="tag_20_154_15" id="tag_20_154_15"></a>CONSEQUENCES OF ERRORS</h4> +<blockquote> +<p>If any errors are encountered, the run is aborted and <i>yacc</i> exits with a non-zero status. Partial code files and header +files may be produced. The summary information in the description file shall always be produced if the <b>-v</b> flag is +present.</p> +</blockquote> +<hr> +<div class="box"><em>The following sections are informative.</em></div> +<h4 class="mansect"><a name="tag_20_154_16" id="tag_20_154_16"></a>APPLICATION USAGE</h4> +<blockquote> +<p>Historical implementations experience name conflicts on the names <b>yacc.tmp</b>, <b>yacc.acts</b>, <b>yacc.debug</b>, +<b>y.tab.c</b>, <b>y.tab.h</b>, and <b>y.output</b> if more than one copy of <i>yacc</i> is running in a single directory at one +time. The <b>-b</b> option was added to overcome this problem. The related problem of allowing multiple <i>yacc</i> parsers to be +placed in the same file was addressed by adding a <b>-p</b> option to override the previously hard-coded <b>yy</b> variable +prefix.</p> +<p class="tent">The description of the <b>-p</b> option specifies the minimal set of function and variable names that cause +conflict when multiple parsers are linked together. YYSTYPE does not need to be changed. Instead, the programmer can use <b>-b</b> +to give the header files for different parsers different names, and then the file with the <i>yylex</i>() for a given parser can +include the header for that parser. Names such as <i>yyclearerr</i> do not need to be changed because they are used only in the +actions; they do not have linkage. It is possible that an implementation has other names, either internal ones for implementing +things such as <i>yyclearerr</i>, or providing non-standard features that it wants to change with <b>-p</b>.</p> +<p class="tent">Unary operators that are the same token as a binary operator in general need their precedence adjusted. This is +handled by the <b>%prec</b> advisory symbol associated with the particular grammar rule defining that unary operator. (See <a href= +"#tag_20_154_13_04">Grammar Rules in yacc</a> .) Applications are not required to use this operator for unary operators, but the +grammars that do not require it are rare.</p> +<p class="tent">If <i>yyerror</i>() and <i>yylex</i>() are not defined within <b>%{</b> and <b>%}</b> in the declarations section +as functions or macros, nor in the programs section as functions, recommended practice is to declare them as functions in a +separate header file and include that file in the declarations section, followed by <tt>#define yyerror yyerror</tt> and +<tt>#define yylex yylex</tt>. This lets the separate header file be the definitive API for all code defining or using these +functions.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_154_17" id="tag_20_154_17"></a>EXAMPLES</h4> +<blockquote> +<p>Access to the <i>yacc</i> library is obtained with library search operands to <a href="../utilities/c17.html"><i>c17</i></a>. To +use the <i>yacc</i> library <i>main</i>():</p> +<pre> +<tt>c17 y.tab.c -l y +</tt></pre> +<p class="tent">Both the <a href="../utilities/lex.html"><i>lex</i></a> library and the <i>yacc</i> library contain <i>main</i>(). +To access the <i>yacc</i> <i>main</i>():</p> +<pre> +<tt>c17 y.tab.c lex.yy.c -l y -l l +</tt></pre> +<p class="tent">This ensures that the <i>yacc</i> library is searched first, so that its <i>main</i>() is used.</p> +<p class="tent">The historical <i>yacc</i> libraries have contained two simple functions that are normally coded by the application +programmer. These functions are similar to the following code:</p> +<pre> +<tt>#include <locale.h> +int main(void) +{ + extern int yyparse(); +<br class="tent"> + setlocale(LC_ALL, ""); +<br class="tent"> + /* If the following parser is one created by lex, the + application must be careful to ensure that LC_CTYPE + and LC_COLLATE are set to the POSIX locale. */ + (void) yyparse(); + return (0); +} +<br class="tent"> +#include <stdio.h> +<br class="tent"> +void yyerror(const char *msg) +{ + (void) fprintf(stderr, "%s\n", msg); + return (0); +} +</tt></pre></blockquote> +<h4 class="mansect"><a name="tag_20_154_18" id="tag_20_154_18"></a>RATIONALE</h4> +<blockquote> +<p>The references in <b>Referenced Documents</b> may be helpful in constructing the parser generator. The referenced DeRemer and +Pennello article (along with the works it references) describes a technique to generate parsers that conform to this volume of +POSIX.1-2024. Work in this area continues to be done, so implementors should consult current literature before doing any new +implementations. The original Knuth article is the theoretical basis for this kind of parser, but the tables it generates are +impractically large for reasonable grammars and should not be used. The "equivalent to" wording is intentional to assure that the +best tables that are LALR(1) can be generated.</p> +<p class="tent">There has been confusion between the class of grammars, the algorithms needed to generate parsers, and the +algorithms needed to parse the languages. They are all reasonably orthogonal. In particular, a parser generator that accepts the +full range of LR(1) grammars need not generate a table any more complex than one that accepts SLR(1) (a relatively weak class of LR +grammars) for a grammar that happens to be SLR(1). Such an implementation need not recognize the case, either; table compression +can yield the SLR(1) table (or one even smaller than that) without recognizing that the grammar is SLR(1). The speed of an LR(1) +parser for any class is dependent more upon the table representation and compression (or the code generation if a direct parser is +generated) than upon the class of grammar that the table generator handles.</p> +<p class="tent">The speed of the parser generator is somewhat dependent upon the class of grammar it handles. However, the original +Knuth article algorithms for constructing LR parsers were judged by its author to be impractically slow at that time. Although full +LR is more complex than LALR(1), as computer speeds and algorithms improve, the difference (in terms of acceptable wall-clock +execution time) is becoming less significant.</p> +<p class="tent">Potential authors are cautioned that the referenced DeRemer and Pennello article previously cited identifies a bug +(an over-simplification of the computation of LALR(1) lookahead sets) in some of the LALR(1) algorithm statements that preceded it +to publication. They should take the time to seek out that paper, as well as current relevant work, particularly Aho's.</p> +<p class="tent">The <b>-b</b> option was added to provide a portable method for permitting <i>yacc</i> to work on multiple separate +parsers in the same directory. If a directory contains more than one <i>yacc</i> grammar, and both grammars are constructed at the +same time (by, for example, a parallel <a href="../utilities/make.html"><i>make</i></a> program), conflict results. While the +solution is not historical practice, it corrects a known deficiency in historical implementations. Corresponding changes were made +to all sections that referenced the filenames <b>y.tab.c</b> (now "the code file"), <b>y.tab.h</b> (now "the header file"), and +<b>y.output</b> (now "the description file").</p> +<p class="tent">The grammar for <i>yacc</i> input is based on System V documentation. The textual description shows there that the +<tt>';'</tt> is required at the end of the rule. The grammar and the implementation do not require this. (The use of +<b>C_IDENTIFIER</b> causes a reduce to occur in the right place.)</p> +<p class="tent">Also, in that implementation, the constructs such as <b>%token</b> can be terminated by a <semicolon>, but +this is not permitted by the grammar. The keywords such as <b>%token</b> can also appear in uppercase, which is again not +discussed. In most places where <tt>'%'</tt> is used, <backslash> can be substituted, and there are alternate spellings for +some of the symbols (for example, <b>%LEFT</b> can be <tt>"%<"</tt> or even <tt>"\<"</tt>).</p> +<p class="tent">Historically, <<i>tag</i>> can contain any characters except <tt>'>'</tt>, including white space, in the +implementation. However, since the <i>tag</i> must reference an ISO C standard union member, in practice conforming +implementations need to support only the set of characters for ISO C standard identifiers in this context.</p> +<p class="tent">Some historical implementations are known to accept actions that are terminated by a period. Historical +implementations often allow <tt>'$'</tt> in names. A conforming implementation does not need to support either of these +behaviors.</p> +<p class="tent">Deciding when to use <b>%prec</b> illustrates the difficulty in specifying the behavior of <i>yacc</i>. There may +be situations in which the <i>grammar</i> is not, strictly speaking, in error, and yet <i>yacc</i> cannot interpret it +unambiguously. The resolution of ambiguities in the grammar can in many instances be resolved by providing additional information, +such as using <b>%type</b> or <b>%union</b> declarations. It is often easier and it usually yields a smaller parser to take this +alternative when it is appropriate.</p> +<p class="tent">The size and execution time of a program produced without the runtime debugging code is usually smaller and +slightly faster in historical implementations.</p> +<p class="tent">Statistics messages from several historical implementations include the following types of information:</p> +<pre> +<i>n</i><tt>/512 terminals, </tt><i>n</i><tt>/300 non-terminals +</tt><i>n</i><tt>/600 grammar rules, </tt><i>n</i><tt>/1500 states +</tt><i>n</i><tt> shift/reduce, </tt><i>n</i><tt> reduce/reduce conflicts reported +</tt><i>n</i><tt>/350 working sets used +Memory: states, etc. </tt><i>n</i><tt>/15000, parser </tt><i>n</i><tt>/15000 +</tt><i>n</i><tt>/600 distinct lookahead sets +</tt><i>n</i><tt> extra closures +</tt><i>n</i><tt> shift entries, </tt><i>n</i><tt> exceptions +</tt><i>n</i><tt> goto entries +</tt><i>n</i><tt> entries saved by goto default +Optimizer space used: input </tt><i>n</i><tt>/15000, output </tt><i>n</i><tt>/15000 +</tt><i>n</i><tt> table entries, </tt><i>n</i><tt> zero +Maximum spread: </tt><i>n</i><tt>, Maximum offset: </tt><i>n</i><tt> +</tt></pre> +<p class="tent">The report of internal tables in the description file is left implementation-defined because all aspects of these +limits are also implementation-defined. Some implementations may use dynamic allocation techniques and have no specific limit +values to report.</p> +<p class="tent">The format of the <b>y.output</b> file is not given because specification of the format was not seen to enhance +applications portability. The listing is primarily intended to help human users understand and debug the parser; use of +<b>y.output</b> by a conforming application script would be unusual. Furthermore, implementations have not produced consistent +output and no popular format was apparent. The format selected by the implementation should be human-readable, in addition to the +requirement that it be a text file.</p> +<p class="tent">Standard error reports are not specifically described because they are seldom of use to conforming applications and +there was no reason to restrict implementations.</p> +<p class="tent">Some implementations recognize <tt>"={"</tt> as equivalent to <tt>'{'</tt> because it appears in historical +documentation. This construction was recognized and documented as obsolete as long ago as 1978, in the referenced <i>Yacc: Yet +Another Compiler-Compiler</i>. This volume of POSIX.1-2024 chose to leave it as obsolete and omit it.</p> +<p class="tent">Multi-byte characters should be recognized by the lexical analyzer and returned as tokens. They should not be +returned as multi-byte character literals. The token <b>error</b> that is used for error recovery is normally assigned the value +256 in the historical implementation. Thus, the token value 256, which is used in many multi-byte character sets, is not available +for use as the value of a user-defined token.</p> +<p class="tent">Earlier versions of this standard did not require the code file created by <i>yacc</i> to contain declarations of +<i>yyerror</i>(), <i>yylex</i>(), and <i>yyparse</i>(). This meant that portable applications that did not define them had to +declare them in the <i>grammar</i> file, to ensure they would not be diagnosed by the compiler as being called without being +declared, but this was not stated in those versions of the standard either. The standard developers decided it was preferable for +<i>yacc</i> to include the declarations in the code file and this is now a requirement. However, the declarations of +<i>yyerror</i>() and <i>yylex</i>() are only visible if a macro of the same name is not defined, which provides application writers +with a way to suppress the declaration if desired (for example, in order to provide their own declaration that would conflict with +the one written by <i>yacc</i>). These functions are not declared in the header file because a macro definition in the declaration +section would not be be able to suppress them there.</p> +<p class="tent">Earlier versions of this standard were also silent about a declaration of <i>main</i>(). However, the equivalent +solution was not adopted because a declaration of <i>main</i>() would only be needed if it is called recursively by an application. +Although in theory an application could call the <i>yacc</i> library version of <i>main</i>() from code in a <i>grammar</i> file, +it is questionable why any application (other than a test suite) would do so, in particular because that version of <i>main</i>() +does not accept any arguments and it calls <a href="../functions/exit.html"><i>exit</i>()</a>—it does not return—and therefore is +of little use recursively. An application that includes its own definition of <i>main</i>() could call it recursively, but can +reasonably be expected to ensure it does not call <i>main</i>() without previously defining or declaring it. An additional +complication is that <i>main</i>() has multiple different allowed prototypes. The standard developers decided the simplest solution +was to disallow <i>yacc</i> from providing a declaration of <i>main</i>() in the code file.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_154_19" id="tag_20_154_19"></a>FUTURE DIRECTIONS</h4> +<blockquote> +<p>If this utility is directed to create a new directory entry that contains any bytes that have the encoded value of a +<newline> character, implementations are encouraged to treat this as an error. A future version of this standard may require +implementations to treat this as an error.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_154_20" id="tag_20_154_20"></a>SEE ALSO</h4> +<blockquote> +<p><a href="../utilities/c17.html#"><i>c17</i></a> , <a href="../utilities/lex.html#"><i>lex</i></a></p> +<p class="tent">XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href= +"../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p> +</blockquote> +<h4 class="mansect"><a name="tag_20_154_21" id="tag_20_154_21"></a>CHANGE HISTORY</h4> +<blockquote> +<p>First released in Issue 2.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_154_22" id="tag_20_154_22"></a>Issue 5</h4> +<blockquote> +<p>The FUTURE DIRECTIONS section is added.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_154_23" id="tag_20_154_23"></a>Issue 6</h4> +<blockquote> +<p>This utility is marked as part of the C-Language Development Utilities option.</p> +<p class="tent">Minor changes have been added to align with the IEEE P1003.2b draft standard.</p> +<p class="tent">The normative text is reworded to avoid use of the term "must" for application requirements.</p> +<p class="tent">IEEE PASC Interpretation 1003.2 #177 is applied, changing the comment on <b>RCURL</b> from the <b>}%</b> token to +the <b>%}</b>.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_154_24" id="tag_20_154_24"></a>Issue 7</h4> +<blockquote> +<p>Austin Group Interpretation 1003.1-2001 #190 is applied, clarifying the requirements for generated code to conform to the +ISO C standard.</p> +<p class="tent">Austin Group Interpretation 1003.1-2001 #191 is applied, clarifying the handling of C-language trigraphs and curly +brace preprocessing tokens.</p> +<p class="tent">SD5-XCU-ERN-6 is applied, clarifying that Guideline 9 of the Utility Syntax Guidelines does not apply.</p> +<p class="tent">SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p> +<p class="tent">POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0204 [977] is applied.</p> +</blockquote> +<h4 class="mansect"><a name="tag_20_154_25" id="tag_20_154_25"></a>Issue 8</h4> +<blockquote> +<p>Austin Group Defect 251 is applied, encouraging implementations to disallow the creation of filenames containing any bytes that +have the encoded value of a <newline> character.</p> +<p class="tent">Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p> +<p class="tent">Austin Group Defect 1269 is applied, changing the required contents of the code file (including <b>#define</b> +statements for YYEMPTY and YYEOF) and adding new requirements for the interface to the lexical analyzer.</p> +<p class="tent">Austin Group Defect 1388 is applied, changing the requirements relating to declarations of <i>yyerror</i>(), +<i>yylex</i>(), <i>yyparse</i>(), and <i>main</i>().</p> +</blockquote> +<div class="box"><em>End of informative text.</em></div> +<hr> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href= +"../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a> +]</font></center> +<hr size="2" noshade> +<div class="NAVHEADER"> +<table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0"> +<tr class="nav"> +<td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/xgettext.html" accesskey="P"><<< +Previous</a></td> +<td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td> +<td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/zcat.html" accesskey="N">Next >>></a></td> +</tr> +</table> +<hr align="left" width="100%"></div> +</body> +</html> diff --git a/bdd/zcat.html b/bdd/zcat.html @@ -0,0 +1,627 @@ +<!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved --> +<!doctype HTML> +<html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><link type="text/css" rel="stylesheet" href="style.css"> +<!-- Generated by The Open Group rhtm tool v1.2.4 --> +<!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved --> +<title>compress</title> +</head><body bgcolor="white"><DIV CLASS="NAVHEADER"> +<TABLE SUMMARY="Header navigation table" class="nav" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0"> +<TR class="nav"><TD class="nav" WIDTH="15%" ALIGN="left" VALIGN="bottom"><A href="../utilities/command.html" ACCESSKEY="P" ><<< Previous</A></TD><TD class="nav" WIDTH="70%" ALIGN="center" VALIGN="bottom" ><a href="contents.html">Home</a></TD><TD class="nav" WIDTH="15%" ALIGN="right" VALIGN="bottom"> <A href="../utilities/cp.html" ACCESSKEY="N" >Next >>></A></TD></TR></TABLE><HR ALIGN="LEFT" WIDTH="100%"></DIV> +<script LANGUAGE="JavaScript" src="../jscript/codes.js"></script><basefont size=3> +<center><font size="2"> +The Open Group Base Specifications Issue 8<br> +IEEE Std 1003.1-2024<br> +Copyright © 2001-2024 The IEEE and The Open Group</font></center> +<hr size="2" noshade> +<a name="top"></a> + +<a name="compress"></a> +<a name = "tag_20_23"></a><!-- compress --> + + + +<h4 class="mansect"><a name = "tag_20_23_01"></a>NAME</h4><blockquote> +compress, uncompress, zcat — compress and decompress data + + + + + + +</blockquote><h4 class="mansect"><a name = "tag_20_23_02"></a>SYNOPSIS</h4><blockquote class="synopsis"> +<p> +<p> +<tt><div class="box"><code><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> +<img src="../images/opt-start.gif" alt="[Option Start]" border=0> +compress </tt><b>[</b><tt>-fv</tt><b>] [</b><tt>-b </tt><i>value</i><b>] [</b><tt>-g | -m </tt><i>algo</i><b>] [</b><i>file</i><tt>...</tt><b>]</b><tt> +<br> +<br> +compress -c </tt><b>[</b><tt>-fv</tt><b>] [</b><tt>-b </tt><i>value</i><b>] [</b><tt>-g | -m </tt><i>algo</i><b>] [</b><i>file</i><b>]</b><tt> +<br> +<br> +compress -d </tt><b>[</b><tt>-cfv</tt><b>] [</b><i>file</i><tt>...</tt><b>]</b><tt> +<br> +<br> +uncompress </tt><b>[</b><tt>-cfv</tt><b>] [</b><i>file</i><tt>...</tt><b>]</b><tt> +<br> +<br> +zcat </tt><b>[</b><i>file</i><tt>...</tt><b>]</b><tt> +<img src="../images/opt-end.gif" alt="[Option End]" border=0> +</code></div> +<br> +</tt> +</blockquote><h4 class="mansect"><a name = "tag_20_23_03"></a>DESCRIPTION</h4><blockquote> +<p> +The +<i>compress</i> +utility, when the +<b>-d</b> +option is not specified, shall apply the compression algorithm identified +by the +<b>-g</b> +option or the +<b>-m</b> +<i>algo</i> +option to the named files to attempt to reduce their size without loss +of information. The compress utility with the +<b>-d</b> +option shall apply the appropriate decompression algorithm to the +named files to restore the data to their original state. +<p> +The +<i>uncompress</i> +utility shall be equivalent to +<i>compress</i> +<b>-d</b>. +The +<i>zcat</i> +utility shall be equivalent to +<i>compress</i> +<b>-c -d</b>. +If multiple +<i>file</i> +operands are specified, the decompressed data from each input file +shall be concatenated to standard output. +<p> +When compressing data, unless the +<b>-c</b> +option is specified, after an input file other than standard input has +been compressed, the compressed data from the input file shall be +stored in a file with the same pathname as the input file but with an +added suffix. The added suffix shall be the suffix associated with the +algorithm (see the algorithms in +<a href="#tagtcjh_17"> +Compression algorithms, algo option-argument values, and suffixes +</a> +). +If appending the suffix would make the size of the last component of +the output file's pathname exceed +{NAME_MAX} +bytes, the command shall fail. If appending the suffix would make the +size of the pathname exceed +{PATH_MAX} +bytes, the command may fail. +<p> +When decompressing data, unless the +<b>-c</b> +option is specified, after an input file other than standard input has +been decompressed, the decompressed data from the input file shall be +stored in a file with the same pathname as the input file but with the +suffix associated with the algorithm removed. +<sup>[<a href="javascript:open_code('OB')">OB</a>]</sup> +<img src="../images/opt-start.gif" alt="[Option Start]" border=0> + If +<i>file</i> +has no suffix associated with a known compression algorithm or +<i>file</i> +does not exist and does not have a +<b>.Z</b> +suffix, +<i>file</i> +shall be used as the name of the output file, and the default suffix +<b>.Z</b> +shall be appended to +<i>file</i> +to form the input pathname. +<img src="../images/opt-end.gif" alt="[Option End]" border=0> +The behavior is unspecified if the input pathname ends with a suffix +other than the suffix associated with the algorithm used to compress +the data. When the +<b>-c</b> +option is specified, +<i>file</i> +can have any suffix, or no suffix, and the utility shall use +<i>file</i> +as the input file and examine the file's contents to determine which +algorithm to use to decompress the data (it is not an error if +<i>file</i> +does not have a suffix that matches the suffix associated with the +compression algorithm). +<p> +When compressing or decompressing a file other than standard input and the +<b>-c</b> +option is not specified, if the invoking process has sufficient privilege, +the ownership, modes, access time, and modification time of the output +file shall match the ownership, modes, access time, and modification +time of the input file. After the output file has been successfully +created, the input file shall be removed if the invoking process has +sufficient privileges. If the invoking process does not have sufficient +privileges to remove the input file (for example, if the directory has +the S_ISVTX bit set) the behavior depends on whether the +<b>-f</b> +option is specified: if +<b>-f</b> +is not specified, the output file shall be removed, a diagnostic +message shall be written and the utility shall continue processing +other files but the final exit status shall be non-zero; if +<b>-f</b> +is specified, the output file shall not be removed and it is +unspecified whether the inability to remove the input file is treated +as an error. If it is not treated as an error, a warning message may +be written to standard error +<p> +If no +<i>file</i> +operands are specified, standard input shall be compressed or +decompressed to standard output. +<p> +<sup>[<a href="javascript:open_code('OB')">OB</a>]</sup> +<img src="../images/opt-start.gif" alt="[Option Start]" border=0> +If an input file that is to be removed after processing has multiple +hard links, the +<i>compress</i> +and +<i>uncompress</i> +utilities may write a diagnostic message to standard error and do +nothing with the file; this behavior may depend on whether the +<b>-f</b> +option is specified. If a diagnostic message is written, the final +exit status shall be non-zero. +<img src="../images/opt-end.gif" alt="[Option End]" border=0> +</blockquote><h4 class="mansect"><a name = "tag_20_23_04"></a>OPTIONS</h4><blockquote> +<p> +The +<i>compress</i>, +<i>uncompress</i>, +and +<i>zcat</i> +utilities shall conform to XBD +<a href="../basedefs/V1_chap12.html#tag_12_02"> +<i>12.2 Utility Syntax Guidelines</i> +</a> +, +except that Guideline 1 does not apply to +<i>uncompress</i> +since the utility name has ten letters. +<p> +The following options shall be supported: +<dl compact><dd> +<p><dt><b>-b </b><i>value</i><dd>If the compression algorithm is LZW, +<i>value</i> +specifies the maximum number of bits to use in a code. For a +conforming application, the +<i>value</i> +argument shall be: +<pre> +<tt>9 <= </tt><i>value</i><tt> <= 16 +</tt></pre> +<p> +The implementation may allow values of greater than 16. The default +shall be 14, 15, or 16. +<p> +If the compression algorithm is DEFLATE, +<i>value</i> +specifies the compression level. For a conforming application, the +<i>value</i> +argument shall be: +<pre> +<tt>1 <= </tt><i>value</i><tt> <= 9 +</tt></pre> +<p> +The default shall be 6. +<p> +For other algorithms, value specifies implementation-defined tuning. +<p><dt><b>-c</b><dd>Write to standard output; the input files shall not be changed, and no +output files shall be created. +<p><dt><b>-d</b><dd>Decompress files. When invoked with the +<b>-d</b> +option, the +<i>compress</i> +utility shall restore previously compressed files to their original state. +<p><dt><b>-f</b><dd>Force compression or decompression of file, even if it does not (for +compression) actually reduce the size of the file, or if the +corresponding output file already exists. If the +<b>-f</b> +option is not given and the standard input is a terminal, the user +shall be prompted as to whether an existing output file should be +overwritten. If the response is affirmative, the existing file shall +be overwritten. If the standard input is not a terminal and +<b>-f</b> +is not given, +<i>compress</i> +or +<i>uncompress</i> +shall write a diagnostic message to standard error, the existing file +shall not be overwritten, and the utility shall exit with a status +greater than zero. If the +<b>-f</b> +option is specified and an input file other than standard input has +multiple hard links, it is implementation-defined whether the input +file is unlinked after the corresponding output file is successfully +written, or if processing of that file is skipped and a diagnostic +message is written to standard error. +<p><dt><b>-g</b><dd>Equivalent to +<b>-m</b> +<i>gzip</i>. +<p><dt><b>-m </b><i>algo</i><dd>Use the algorithm defined by +<i>algo</i> +to compress the files. The following algorithms shall be supported: +<br> +<p class="caption"><xref table="Compression algorithms, algo option-argument values, and suffixes"><a name="tagtcjh_17"></a> +Table: Compression algorithms, algo option-argument values, and suffixes</p> + + +<p> +<center> +<p> +<table border=1 cellpadding=3 align=center> +<tr valign=top><th align=center><p class="tent"><b>Algorithm</b></p></th> +<th align=center><p class="tent">algo</p></th> +<th align=center><p class="tent"><b>Filename Suffix</b></p></th> +</p></tr> +<tr valign=top><td align=left><p class="tent">Adaptive LZW +<td align=left><p class="tent"><b>lzw</b> +<td align=left><p class="tent"><b>.Z</b> +</p></tr> +<tr valign=top><td align=left><p class="tent">RFC1951 DEFLATE +<td align=left><p class="tent"><b>deflate</b> +<td align=left><p class="tent"><b>.gz</b> +</p></tr> +<tr valign=top><td align=left><p class="tent">Synonym for DEFLATE +<td align=left><p class="tent"><b>gzip</b> +<td align=left><p class="tent"><b>.gz</b> +</tr> +</table> +</center> +<p class="tent"> +Other implementation-defined algorithms may be supported. +<p class="tent"> +If neither of the +<b>-m</b> +<i>algo</i> +and +<b>-g</b> +options is specified, +<b>lzw</b> +shall be used as a default +<i>algo</i> +value. Specifying more than one of the mutually exclusive +<b>-g</b> +and +<b>-m</b> +<i>algo</i> +options, or multiple +<b>-m</b> +<i>algo</i> +options, shall not be considered an error. The last option specified +shall determine the behavior of the utility. +<p class="tent"> +On systems not supporting the selected algorithm, the input files +shall not be changed and an exit status greater than two shall be +returned. +<basefont size=2> +<dl><dt><b>Note:</b> +<dd>The Lempel-Ziv compression algorithm is described in the now-expired +US Patent 4464650, which was issued to William Eastman, Abraham Lempel, +Jacob Ziv, and Martin Cohn on August 7th, 1984 and assigned to Sperry +Corporation. +<p class="tent"> +The Lempel-Ziv-Welch compression algorithm is described in the +now-expired US Patent 4558302, which was issued to Terry A. Welch on +December 10th, 1985 and assigned to Sperry Corporation. +</dl> +<basefont size=3> +<p><dt><b>-v</b><dd>For +<i>compress</i>, +write the percentage reduction of each file to standard error. For +<i>uncompress</i>, +write messages to standard error concerning the expansion of each file. +</dl> +</blockquote><h4 class="mansect"><a name = "tag_20_23_05"></a>OPERANDS</h4><blockquote> +<p> +The following operand shall be supported: +<dl compact><dd> +<p><dt><i>file</i><dd>A pathname of a file to be compressed or decompressed. If a +<i>file</i> +is +<tt>'-'</tt>, +the utility shall read from standard input at that point in the +sequence and write to standard output. If more than one +<i>file</i> +operand is +<tt>'-'</tt>, +the behavior is unspecified. +</dl> +</blockquote><h4 class="mansect"><a name = "tag_20_23_06"></a>STDIN</h4><blockquote> +<p> +The standard input shall be used only if no +<i>file</i> +operands are specified, or if a +<i>file</i> +operand is +<tt>'-'</tt>. +</blockquote><h4 class="mansect"><a name = "tag_20_23_07"></a>INPUT FILES</h4><blockquote> +<p> +If +<i>file</i> +operands are specified, the corresponding input files contain the data +to be compressed or decompressed. +</blockquote><h4 class="mansect"><a name = "tag_20_23_08"></a>ENVIRONMENT VARIABLES</h4><blockquote> +<p> +The following environment variables shall affect the execution of +<i>compress</i>: +<dl compact><dd> +<p><dt><i>LANG</i><dd>Provide a default value for the internationalization variables that are +unset or null. (See XBD +<a href="../basedefs/V1_chap08.html#tag_08_02"> +<i>8.2 Internationalization Variables</i> +</a> +for the precedence of internationalization variables used to determine +the values of locale categories.) +<p><dt><i>LC_ALL</i><dd>If set to a non-empty string value, override the values of all the +other internationalization variables. +<p><dt><i>LC_COLLATE</i><dd><br> +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements used in the extended regular +expression defined for the +<b>yesexpr</b> +locale keyword in the +<i>LC_MESSAGES</i> +category. +<p><dt><i>LC_CTYPE</i><dd>Determine the locale for the interpretation of sequences of bytes of text +data as characters (for example, single-byte as opposed to multi-byte +characters in arguments), the behavior of character classes used in the +extended regular expression defined for the +<b>yesexpr</b> +locale keyword in the +<i>LC_MESSAGES</i> +category. +<p><dt><i>LC_MESSAGES</i><dd><br> +Determine the locale used to process affirmative responses, and the +locale used to affect the format and contents of diagnostic messages, +prompts, and the output from the +<b>-v</b> +option written to standard error. +<p><dt><i>NLSPATH</i><dd>Determine the location of messages objects and message catalogs. +</dl> +</blockquote><h4 class="mansect"><a name = "tag_20_23_09"></a>ASYNCHRONOUS EVENTS</h4><blockquote> +<p> +Default. +</blockquote><h4 class="mansect"><a name = "tag_20_23_10"></a>STDOUT</h4><blockquote> +<p> +For the +<i>compress</i> +and +<i>uncompress</i> +utilities, the standard output shall be used if no +<i>file</i> +operands are specified, if a +<i>file</i> +operand is +<tt>'-'</tt>, +or if the +<b>-c</b> +option is specified. Otherwise, the standard output shall not be used. +<p class="tent"> +The +<i>zcat</i> +utility shall write the decompressed data to the standard output. +</blockquote><h4 class="mansect"><a name = "tag_20_23_11"></a>STDERR</h4><blockquote> +<p> +The standard error shall be used only for diagnostic and prompt +messages, the optional warning message described in DESCRIPTION, and +the output from +<b>-v</b>. +</blockquote><h4 class="mansect"><a name = "tag_20_23_12"></a>OUTPUT FILES</h4><blockquote> +<p> +When decompressing input files other than standard input, the +corresponding output files shall contain the decompressed input data. +When compressing input files other than standard input, the +corresponding output files shall contain the compressed input data. +If the selected +<i>algo</i> +is +<b>deflate</b> +or +<b>gzip</b>, +the compressed output shall be in the GZIP format described in RFC 1952. +For other algorithms, the compressed output file format is +implementation-defined and interchange of such files between +implementations (including access via unspecified file sharing +mechanisms) is not required by POSIX.1-2024. +</blockquote><h4 class="mansect"><a name = "tag_20_23_13"></a>EXTENDED DESCRIPTION</h4><blockquote> +<p> +None. +</blockquote><h4 class="mansect"><a name = "tag_20_23_14"></a>EXIT STATUS</h4><blockquote> +<p> +The following exit values shall be returned for +<i>compress</i>: +<dl compact><dd> +<p><dt> 0<dd>Successful completion. +<p><dt> 1<dd>An error occurred. +<p><dt> 2<dd>One or more files were not compressed because they would have increased +in size (and the +<b>-f</b> +option was not specified). +<p><dt>>2<dd>An error occurred. +</dl> +<p class="tent"> +The following exit values shall be returned for +<i>uncompress</i> +and +<i>zcat</i>: +<dl compact><dd> +<p><dt> 0<dd>Successful completion. +<p><dt>>0<dd>An error occurred. +</dl> +</blockquote><h4 class="mansect"><a name = "tag_20_23_15"></a>CONSEQUENCES OF ERRORS</h4><blockquote> +<p> +If an error occurs while compressing or decompressing an input file +other than standard input, the input file shall remain unmodified. +</blockquote> +<hr><div class="box"><em>The following sections are informative.</em></div> +<blockquote> +</blockquote><h4 class="mansect"><a name = "tag_20_23_16"></a>APPLICATION USAGE</h4><blockquote> +<p> +The amount of compression obtained depends on the size of the input, +the number of bits +per code, and the distribution of common substrings. Typically, text +such as source code or English is reduced by 50-60%. Compression is +generally much better than that achieved by Huffman coding +or adaptive Huffman coding (<i>compact</i>), +and takes less time to compute. +<p class="tent"> +Although +<i>compress</i> +strictly follows the default actions upon receipt of a signal or when +an error occurs, some unexpected results may occur. In some +implementations it is likely that a partially compressed file is left +in place, alongside its uncompressed input file. Since the general +operation of +<i>compress</i> +is to delete the uncompressed file only after the +<b>.Z</b> +file has been successfully filled, an application should always +carefully check the exit status of +<i>compress</i> +before arbitrarily deleting files that have like-named neighbors with +<b>.Z</b> +suffixes. +<p class="tent"> +In addition to trying +<i>file</i> +and +<i>file</i><b>.Z</b> +when looking for a file to decompress, some implementations of +<i>uncompress</i> +and +<i>zcat</i> +also try suffixes for other known compression algorithms if neither +<i>file</i> +nor +<i>file</i><b>.Z</b> +is found. This version of the standard allows, but does not require +this behavior. Portable applications should always specify the full +pathname (including the suffix) of files to be decompressed. +</blockquote><h4 class="mansect"><a name = "tag_20_23_17"></a>EXAMPLES</h4><blockquote> +<p> +None. +</blockquote><h4 class="mansect"><a name = "tag_20_23_18"></a>RATIONALE</h4><blockquote> +<p> +Earlier versions of this standard limited the number of bits used by +conforming applications for the +<b>lzw</b> +algorithm to 14 due to address space limitations on 16-bit +architectures. Using 15 or 16 is a much more common default when using +current hardware. +<p class="tent"> +Earlier versions of this standard only supported LZW compression. The +standard developers noted that existing implementations added other +compression utilities, such as +<i>gzip</i>, +and found it desirable to support this widespread usage. Some +implementations had extended the +<i>compress</i> +utility to support such other schemes. The standard developers +generalized this practice by the addition of the +<b>-m</b> +option, even though this was not previous practice. +<p class="tent"> +The +<i>uncompress</i> +<b>-d</b> +option is added to match undocumented existing practice of tested +implementations. +</blockquote><h4 class="mansect"><a name = "tag_20_23_19"></a>FUTURE DIRECTIONS</h4><blockquote> +<p> +If this utility is directed to create a new directory entry that +contains any bytes that have the encoded value of a +<newline> +character, implementations are encouraged to treat this as an error. +A future version of this standard may require implementations to treat +this as an error. +<p class="tent"> +When decompressing a file, the requirement to add +<b>.Z</b> +to a +<i>file</i> +operand if the given pathname does not include a suffix associated +with a known compression algorithm or if +<i>file</i> +does not exist and does not already have a +<b>.Z</b> +extension is an obsolescent feature and may be removed in a future version. +</blockquote><h4 class="mansect"><a name = "tag_20_23_20"></a>SEE ALSO</h4><blockquote> +<p> +XBD +<a href="../basedefs/V1_chap08.html#tag_08"> +<i>8. Environment Variables</i> +</a> +, +<a href="../basedefs/V1_chap12.html#tag_12_02"> +<i>12.2 Utility Syntax Guidelines</i> +</a> +</blockquote><h4 class="mansect"><a name = "tag_20_23_21"></a>CHANGE HISTORY</h4><blockquote> +<p> +First released in Issue 4. +</blockquote><h4 class="mansect"><a name = "tag_20_23_22"></a>Issue 6</h4><blockquote> +<p> +The normative text is reworded to avoid use of the term "must" +for application requirements. +<p class="tent"> +An error case is added for systems not supporting adaptive Lempel-Ziv +coding. +</blockquote><h4 class="mansect"><a name = "tag_20_23_23"></a>Issue 7</h4><blockquote> +<p> +SD5-XCU-ERN-97 is applied, updating the SYNOPSIS. +<p class="tent"> +Austin Group Interpretation 1003.1-2001 #125 is applied, revising +the ENVIRONMENT VARIABLES section. +</blockquote><h4 class="mansect"><a name = "tag_20_23_24"></a>Issue 8</h4><blockquote> +<p> +Austin Group Defect 251 is applied, encouraging implementations to +disallow the creation of filenames containing any bytes that have the +encoded value of a +<newline> +character. +<p class="tent"> +Austin Group Defect 1041 is applied, combining the +<i>compress</i>, +<i>uncompress</i> +and +<i>zcat</i> +pages into one and extensively modifying most sections. +<p class="tent"> +Austin Group Defect 1122 is applied, changing the description of +<i>NLSPATH . +</i></blockquote> +<div class="box"><em>End of informative text.</em></div><hr> +<blockquote> +</blockquote> +<p> </p> +<a href="#top"><span class="topOfPage">return to top of page</span></a><br> +<hr size="2" noshade> +<center><font size="2">UNIX® is a registered Trademark of The Open Group.<br> +POSIX™ is a Trademark of The IEEE.<br> +Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br> +[ <a href="../mindex.html">Main Index</a> | +<a href="../basedefs/contents.html">XBD</a> | +<a href="../functions/contents.html">XSH</a> | +<a href="../utilities/contents.html">XCU</a> | +<a href="../xrat/contents.html">XRAT</a> ] +</font></center> +<hr size="2" noshade> + +<DIV CLASS="NAVHEADER"> +<TABLE SUMMARY="Header navigation table" class="nav" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0"> +<TR class="nav"><TD class="nav" WIDTH="15%" ALIGN="left" VALIGN="bottom"><A href="../utilities/command.html" ACCESSKEY="P" ><<< Previous</A></TD><TD class="nav" WIDTH="70%" ALIGN="center" VALIGN="bottom" ><a href="contents.html">Home</a></TD><TD class="nav" WIDTH="15%" ALIGN="right" VALIGN="bottom"> <A href="../utilities/cp.html" ACCESSKEY="N" >Next >>></A></TD></TR></TABLE><HR ALIGN="LEFT" WIDTH="100%"></DIV></body></html> diff --git a/isposix b/isposix @@ -0,0 +1,61 @@ +#! /bin/sh +set -e + +red="\033[91m";green="\033[92m";blue="\033[94m";norm="\033[0m" +_die() { echo "$red$@$norm" >&2 ; } +_success() { echo "$green$@$norm" >&2; } +_inform() { echo "$blue$@$norm" >&2; } +_cmdnotposix() { + if command -V fzy 2>&1 > /dev/null;then + fzcmd=$(find bdd -name '*.html' | + xargs -I{} basename {} | sed 's/\.html$//' | + fzy -e "$cmd" | head -n3) + fi + [ -z "$fzcmd" ] && { _die "$cmd is not posix";exit 1;} + if [ -t 0 ];then + _inform "$cmd appears not to be posix, did you mean :$norm" + cmd=$(echo "$fzcmd" | fzy) + else + _inform "$cmd appears not to be posix, did you mean :\n$fzcmd" + exit 1 + fi +} + +usage() { + <<-. cat + Check if command or its options are posix + + isposix command [options] + + exemple : + + isposix ls + isposix ls -a + . +} + +checkoption() { + < bdd/$cmd.html grep -q "<dt><b>$option.*</dt>" \ + && { _success "$option is a posix option";return 0;} \ + || { _die "$option is not a posix option"; return 1;} +} + +isposix=0 +cmd="$1" + +[ "$cmd" = "-h" ] && { usage; exit 0; } + +[ ! -f bdd/$cmd.html ] && _cmdnotposix +_success "$cmd is a posix command" + +shift;options="$@" +for option in "$@";do + checkoption || isposix=1 +done + +[ $isposix = "0" ] \ + && _success "$cmd $@ is posix" \ + || { _die "$cmd $@ is not posix"; exit 1; } + +exit $isposix +